PCAL gets dates down on paper

In our house, the refrigerator door is where we post the family calendar, showing our family and friends’ birthdays, school terms, and important events, along with public holidays. We create the calendar using a nifty command-line program called PCAL, which produces a standard one-month-per-page calendar with each day in a separate box. It resembles those mall-stall calendars, but the important dates in our family’s life are highlighted.

You can download PCAL as source, or as a package for most Linux distributions. The project also provides a pre-built .exe file for MS-DOS.

To control the calendar content, you enter parameters in a text file named .calendar, though you can override the file specification with the run-time option -f. This file makes PCAL extremely customizable and versatile. With its parameters, which are documented in the software’s man pages and on the PCAL Web site, you can specify any event, on any date, and also allow that event to be repeated, so that it will appear on future calendars in the months or years that you need it scheduled. Here’s a sample .calendar file:

last Monday in May*		Memorial Day Holiday

all Fridays in Oct		Status Meeting, 11 AM
first workday in all		%-B progress report due
all Fri in all              	fBTime card due,fP 3 PM
all Monday in all           	Fiscal week %0W
-2nd workday in all         	Schedule for %+B due %+2D
2nd full_moon in all        	Blue Moon
Fri on_or_before all 15     	Pay Day
even Fridays in year        	Pay Day
183rd day of year           	Mid-year (%l days left)

Tue after first Mon in Nov  	Election Day (USA)

4th Thu in Nov*             	Thanksgiving
Fri after 4th Thu in Nov*   	Day after Thanksgiving

Easter                     	Easter Sunday
Good_Friday*               	Good Friday
Monday after Easter*       	Easter Monday

Christmas                  	Christmas
Day after Christmas        	Boxing Day
workday ooa Christmas*     	Christmas Holiday
workday after Christmas*   	Boxing Day Holiday

Last Sunday in Sep		Day Light Saving Starts - Clock Forward
First Sunday in Apr		Day Light Saving Ends - Clock Back

F13                   		Avoid black cats!   # Friday the 13th

Several of the lines have an * in them, which indicates that the day is a holiday, and that the text following should appear on the same line as the date. The character string %B means print the month name; a + or a - after the % means print the next or previous month’s name. You can make text bold using fB, then revert to the previous font with fP. The string %OW prints the week number with leading zeroes. -2nd indicates that you want the event to occur on the second to last workday of the month.

%+2D is an example of PCAL’s simple math functions; it means adjust the date backwards two days and print that date. %l prints the number of days left in the year. ooa is shorthand for “on or after,” and oob can be used for “on or before.” And just for fun, F13 will highlight any Friday the Thirteenth.

The format of the parameters allows for public holidays to be Monday-ized, and other dates that require flexible scheduling, such as Jewish New Year or Ramadan, can be easily entered. Easter and Christmas can be specified with special parameters of their own, so you don’t need to know their dates.

You can link to a graphics file in EPS format to personalize an event with an image. These images appear inside the box for the day that the specified event takes place. The manual warns that not all EPS images will work, and that some manipulation may be required. Other parameters control fonts, allowing color changes, highlighting, and different sizes of text. If you want a large picture to display above your calendar’s date page, you will have to print this separately; there is no function to do this in PCAL.

One of PCAL’s most interesting features is the ability to use simple math in an event description. This is most useful if you want to be reminded which birthday a person is having. For instance, if you specify:

May 10 Eric's %-1993Y%oY Birthday

PCAL reads this as, subtract 1993 (Eric’s birth year) from the current year and print the answer as an ordinal number: “Eric’s 14th Birthday.” No excuse now for forgetting how old your nephew is.

PCAL can produce not only single-month calendars, but also a whole-year calendar. Another option lets you add to the monthly calendars notes that are not date-dependent, which appear in a separate notes box. All dates can be in either American or European format, and you can produce calendars in more than 20 different languages.

I usually run PCAL with the command pcal -E -H -o testcal.html 2007 to test its output. The -H option allows you to generate an HTML calendar rather than the default PostScript. The resulting file can be viewed in any Web browser. I find this option helpful for checking that my parameters are correct and produce the expected output. Once I’m satisfied that everything is correct, I produce the calendar with the command

pcal -E -P a4 -B -F 1 -n Arial/10 -o cal.ps 2007

• -E specifies European dates
• -P specifies A4 paper size
• -B leaves unused date boxes blank; this saves ink
• -F indicates the starting weekday; 1 is Monday
• -n selects the font size to be used in the notes boxes — in this case 10-point Arial
• -o specifies an output file in PostScript format. I do this so that it is easy to print another copy if I want to.
• 2007 is the year for which I want to print the calendar — useful if you produce the calendar in December. PCAL’s default option is to produce the calendar for the current year.

PCAL provides a CGI script that allows you to generate PostScript calendars using a Web interface. Two copies of this script are available, one a bash script and the other in Perl. Two HTML files are also provided, one to produce monthly calendars and the other a whole-year calendar. With a bit of tweaking, I was able to use these as the basis for a calendar that the whole family could access online.

In addition to PCAL, you might want to try a couple of other useful linked programs. LCAL is a multiplatform command-line tool that will generate full-year moon phase calendars in PostScript format. Makediary is a separate project from PCAL that uses the same parameter file to produce a one-year diary ready for printing.

Printed calendars are useful for many families and organizations. PCAL helps keep everyone in our family on the same schedule.