The Date File (Configuration File)

The default date/configuration file is expected to be named .calendar (pcal.dat under MS-DOS), or calendar for compatibility with older versions. Pcal will look in several places for such a file. First, if the environment variable PCAL_DIR is defined, pcal searches the directory indicated by that variable. Next, pcal searches the user's home directory (as specified by the HOME environment variable). If neither PCAL_DIR nor HOME is defined, pcal searches the current directory instead. Finally, if enabled (via the `SEARCH_PCAL_DIR' flag) when pcal was built, the directory where the pcal executable resides will be checked. If no date file is found, an empty calendar is printed; no error is generated.

Alternatively, the name of the date file (and, optionally, the path where it can be found) can be specified using the -f command-line option. See the OPTIONS section for more details.

Every pcal distribution comes with an 'examples' directory. The `pcal-cfg.txt' file that is located there contains a myriad of examples of settings that can be used in your own configuration file. Please check it out for lots of useful ideas. Furthermore, that directory contains several language/country-specific examples (including holiday and other event definitions) in various `calendar_xx.txt' files, where `xx' represents the 2-letter language code (e.g. 'calendar_de.txt' is the German example file).

If a date file is found, it will be searched for lines with leading dates matching the requested month and year.

Any text following the dates found will be printed on the calendar under the appropriate day of the month. Encapsulated PostScript (EPS) images are handled similarly as described in a later subsection.

troff-style escape sequences \fB, \fI, \fP, and \fR may be used to set the font style to Bold, Italic, the previous font style, or Roman respectively. For those more familiar with HTML, <B>, <I>, </B>, and </I> may be used instead to enable/disable Bold or Italic font styles. The font style is reset to Roman after each line break.

Using the `include' pre-processor directive (described in the section entitled `Pre-Processor Functionality', below), other configuration files can be processed from within an existing configuration file. That is, you can `nest' configuration files as needed.

Dates (essentially `events') in the configuration files may be expressed in any of several formats:

Where:

<month_name>

:= first 3+ characters of name of month, or ``all''

Note: pcal looks for names of the days of the week prior to names of months when parsing event date specifications. Furthermore, some languages (e.g. French and Finnish) have a month name whose first 3 letters are the same as the first 3 letters of one of the names of the days of the week. Because of this, the specification in such a language of any month name which collides thusly must use 4 or more letters to distinguish it from the name of the day of the week with which it `collides'.

<month_spec>

:= <month_name>, or ``year''

<day_spec>

:= first 3+ characters of name of weekday, ``day'', ``weekday'', ``workday'', ``holiday'', ``nonweekday'', ``nonworkday'', ``nonholiday'', ``new_moon'', ``first_quarter'', ``full_moon'', or ``last_quarter''

<ordinal>

:= any ordinal number (``1st'', ``2nd'', etc.), ``first'' ... ``fifth'', ``last'', ``odd'', ``even'', or ``all''

<prep>

:= ``on'', ``before'', ``preceding'', ``after'', ``following'', ``on_or_before'' (``oob''), ``on_or_after'' (``ooa''), ``nearest'', ``nearest_before``, or ``nearest_after``

<pre_defined_event>

:= ``Christmas'', ``Thanksgiving'', ``Easter'', ``Good_Friday'', ``GEaster'' (Orthodox Easter), ``Gstgeorge'' (Orthodox holiday), and ``Gmarcus'' (Orthodox holiday).

<sep>

:= one or more non-numeric, non-space, non-`*' characters

<month>

:= a numeric month (1-12)

<day>

:= day of month (1-31)

<year>

:= a numeric year

<text>

:= the text to be displayed for this event; if the text begins with the constant string ``image:'', then it is interpreted as a specification of an Encapsulated PostScript (EPS) image rather than as simple text; more information on specifying EPS images is available in a later section of this document

If the -A option (American date formats, the default) is given:

<date_spec>

:= <month_name> <day> | <month><sep><day>{<sep><year>}

If the -E option (European date formats) is given:

<date_spec>

:= <day> <month_name> | <day> <month> | <day><sep><month>{<sep><year>}

The ``Notes'' box (see below) uses the first of the current month as the default date. All footer strings use the first of the current month in single-month mode and the first of the starting month in whole-year mode.

Examples:

	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
	workday nearest 12/25*      Holiday

	12/25/04*                   Christmas     # American
	25.12.04*                   Christmas     # European
	25. 12.*                    Christmas     # European

	Dec 25*                     Christmas     # American
	25 Dec*                     Christmas     # European
	25. Dec*                    Christmas     # European

	Fri on all 13               Avoid black cats!   # 'Friday the 13th'

Any non-numeric character may separate numeric dates. Holidays may be flagged by following the date immediately with `*' as in the examples above; this will cause the date numerics to be printed in the color specified by the -s option (default = gray) and will cause the associated text (on monthly-format calendars) to be placed adjacent to the numeric date in the day box rather than below the numeric date (as is done for all non-holiday events). ``Each'' and ``every'' are accepted as synonyms for ``all'', and any word may be used in place of ``in''. The abbreviations ``oob'' and ``ooa'' may be used in place of the keywords ``on_or_before'' and ``on_or_after'', respectively. ``Nearest'' attempts to match the specified date; if that fails, it tries the day after, then the day before, then two days after, two days before, and so forth until a match occurs.

Wildcard day names are also provided. The keyword ``weekday'' applies to any days which are normally printed in "logical black" - the predominant day color - on the calendar. The keyword ``workday'' is the same, but does not include any holidays. The keyword ``holiday'' includes only those days flagged as holidays. The keywords ``nonweekday'', ``nonworkday'', and ``nonholiday'' are also recognized as negations of the above. See the CAVEATS below for important notes on using these keywords. Moon phases may also appear as wildcards; ``nm'' is accepted as a synonym for ``new_moon'', ``1q'' and ``fq'' for ``first_quarter'', ``fm'' for ``full_moon'', ``3q'' for ``third_quarter'', and ``lq'' for ``last_quarter''.

Ordinal day numbers may be used to specify dates, either relative to the month or to the year. Either words or numeric abbreviations may be used for ``first'' through ``fifth''; higher numbers must be given using the numeric equivalent (e.g. 100th). Negative ordinal numbers may even be used. For example, ``-2nd'' means ``next to last''.

``Odd'' and ``even'' do not refer to the actual date; instead, ``odd'' means ``alternate, starting with the first'', and ``even'' means ``alternate, starting with the second''. Thus, ``odd Fridays in March'' refers to the first, third, and (if present) fifth Fridays in March — not to those Fridays falling on odd dates.

``All'' refers to each individual month; ``year'' refers to the year as an entity. Thus ``odd Fridays in all'' refers to the first, third, and fifth Friday of each month, while ``odd Fridays in year'' refers to the first Friday of January and every other Friday thereafter.

``Nearest'', ``nearest_before'', and ``nearest_after'' refer to the nearest weekday or wildcard day with respect to the specified date. ``Nearest_before'' and ``nearest_after'' allow the user to specify how pcal is to disambiguate between two dates that are equally near: e.g., ``nonweekday nearest_before [Wed.] 9/25/96'' refers to Sunday, 9/22 while ``nonweekday nearest_after 9/25/96'' refers to Saturday, 9/28. (Note that ``nearest_before'' and ``nearest_after'' are equivalent to ``nearest'' when no such ambiguity exists: e.g., ``nonweekday nearest_before [Thu.] 9/26/96'' refers to Saturday, 9/28.)

Text in the date file may use C-like escape sequences (i.e. a `\' followed by a character, 1 - 3 octal digits, or `x' followed by 1 - 2 hexadecimal digits). Escaped whitespace (including newline ) and the standard ANSI character escapes (`\a', `\b', `\f', `\n', `\r', `\t', `\v') are all replaced by a single blank.

The HTML special characters `&lt;' `&gt;' `&quot;' `&amp;' `&nbsp;' and `&#NNN;' (NNN = any three decimal digits) are also supported. These will be propagated intact (be sure to escape the `#' in `&#NNN;') if the output is specified as HTML (see the -H flag); otherwise they will be converted to their ASCII equivalents. This allows a common date file to be used regardless of whether the desired output format is HTML, PostScript, or Un*x calendar(1) (see the -c flag) input.

Lines in the configuration file consisting of year #### (where #### is a numeric year) can be used to set the year for following entries. This assumes that the following entries do not contain a year; any date entries containing year information will set the remembered year to that year.

Lines in the configuration file consisting of year all (or, alternatively, year *) direct pcal to wildcard following entries against every applicable year. This assumes that the following entries do not contain a year; any date entries containing year information (or an explicit year #### entry) will set the remembered year to that year.

Lines in the configuration file consisting of opt <options> can be used to override the defaults for any command-line options except -c, -e, -f, -h, -H, -u, -v, -D, and -U. Any options specified in this manner are, in turn, overridden by those specified explicitly on the command line.

Lines in the configuration file consisting of note{/<number>} <month> can be used to place notes regarding the entire month in one of the unused blocks of the calendar. The <month> indicator may be either a number 1 through 12 or an alphabetic month name as described above; ``note all'' will place the associated text in the notes block for each month in the current year. <number> is an optional positive or negative number specifying the empty box where the associated text is to be placed. If positive, pcal counts forward from the first empty box; if negative, pcal counts backward from the last empty box. Thus, ``note/1'' places the associated text in the first empty box; note/-3 in the third-to-last. The default is -1 if no <number> is given (last empty box, immediately preceding the small calendars on the bottom row; cf. -S, -k, and -K, below). You can place several notes in the same box. You can also use more than 1 box for the various monthly notes.

Lines in the configuration file consisting of input-language XX (where XX is the 2-letter specification for any of the supported languages) can be used to set the language used for interpretation of the month names and day-of-week names for the remaining event entries. This option may be specified more than once, as needed, if the language used to describe events changes within the file. For backwards compatibility, the default value for `input language' if this directive is never used is 'en' (English). Note that this directive is distinct from the specification of 'output language' as accomplished with the -a option.

Comments are supported in the configuration file. Any characters following a `#' character are ignored, through the end of that line, unless the `#' character is escaped by `\'.

Deleting Events

For example, the following lines might appear in the date file:

all Friday in all  Poker game
delete first Friday in all  Poker game

This results in an event labeled `Poker game' on every Friday except the first Friday of the month. If you delete an entry which is marked as a holiday, the `holiday' flag for that day will be recalculated. Any `delete' entries which don't match any pre-existing entries are silently ignored.

Format Specifiers

	%a	abbreviated weekday
	%A	full weekday
	%b	abbreviated month name
	%B	full month name
	%d	day of month (1-31)
	%j	day of year (1-366)
	%l	days left in year (0-365)
	%m	month (1-12)
	%U	week number (0-53)
	%W	week number (0-53)
	%u	week number (1-54)
	%w	week number (1-54)
	%y	year w/o century (00-99)
	%Y	year w/century
	%%	`%' character
	%o	print number as ordinal
	%0	print number with leading zeroes
	%+	use following month or year
	%-	use previous month or year
	%{+N}[DWMY]	adjust date by +N days/weeks/months/years
	%{-N}[DWMY]	adjust date by -N days/weeks/months/years

Most of these are derived from the ANSI C strftime() function, but the %[louwMD] and %[o0+-] format specifiers are specific to pcal.

The %u specifier considers the week containing 1/1 (Jan 1st) as week 1 and the following logical Sunday (the first day of the week as printed; cf. the -F option below) as the start of week 2; %U considers the first logical Sunday as the first day of week 1. %w and %W behave like %u and %U respectively, but use the first logical Monday instead. Note that %w has a different meaning from strftime().

The %o format specifier prints a number as an ordinal, with the appropriate suffix (``st'', ``nd'', ``rd'', or ``th'' in English) appended. For example, %od prints the day of the month as ``1st'', ``2nd'', ``3rd'', etc.

Unlike strftime(), pcal defaults to printing numbers (except %y) without leading zeroes. If leading zeroes are desired, the `0' prefix may be used. For example, %0j prints the first day of year as ``001''.

The %+ and %- format specifiers direct pcal to substitute the following/previous month/year in the following [bBmyY] specifier. For example, %+B prints the name of the next month.

The %{[+-]N}[DWMY] format specifiers do not print anything, but instead adjust the working date by ± Ndays (D), weeks (W), months (M), or years (Y). Subsequent format specifiers use the adjusted date instead of the current date. For example, %+1M %B %Y adjusts the date forward by one month and then prints the resulting month and year (``January 1992'' in December, 1991); %-2W %b %d adjusts the date backward by two weeks and prints the resulting month and day (``Jul 26'' on August 9).

Such date adjustments are normally cumulative; for example, %+1Y%-1D adjusts the date forward by one year and then backward by one day. If %D or %M is specified alone (or if N is zero), pcal restores the original date. Note that %M has a different meaning to the strftime() function.

Here's a common, useful example of an event entry for the pcal date file which combines the ability to adjust working dates and the ability to display ordinals. This particular example is used to display text on the birthday of a person born in 1991:

That entry would result in the following text being displayed on May 10, 2005:

Encapsulated PostScript (EPS) Images

In order to associate an image with a given event, you must add one or more entries to the date file. The event date is specified exactly as described previously for simple event text specification lines. However, instead of specifying the text associated with the event, you instead specify the EPS image filename and some additional parameters in the following format:

	image:<EPS-image-filename> <x-scale> <y-scale> <x-delta> <y-delta>

Where:

<EPS-image-filename>

is the filename (which can include a path) of the Encapsulated PostScript image. Note: The EPS image filename must be preceded by the constant text `image:' in order to distinguish an EPS image specification from an ordinary event text specification.

<x-scale>

is a scaling factor in the horizontal dimension for the EPS image. A value of 1.0 is nominal (i.e. no change to image scale). Values between 0.0 and 1.0 shrink the image in the horizontal dimension while values over 1.0 expand the image in the horizontal dimension. Generally speaking, only positive values should be used. However, in the rare case that you find that your EPS image needs to be flipped about the vertical axis (i.e. left to right), you can use a negative value to achieve this without having to tweak the actual PostScript content within the EPS image file. Use of a negative value will undoubtedly necessitate a corresponding change to the <x-delta> parameter to account for the image's relocated position that occurs when it gets flipped "left-to-right".

<y-scale>

is a scaling factor in the vertical dimension for the EPS image. Values between 0.0 and 1.0 shrink the image in the vertical dimension while values over 1.0 expand the image in the vertical dimension. Note that a negative value for this parameter can be useful in the less-than-rare case that you find that your EPS image needs to be flipped about the horizontal axis (i.e. top to bottom). In such cases, you can use a negative <y-scale> value to achieve this without having to tweak the actual PostScript content within the EPS image file. Use of a negative value will undoubtedly necessitate a corresponding change to the <y-delta> parameter to account for the image's relocated position that occurs when it gets flipped "upside down".

<x-delta>

:= a horizontal adjustment in typographic `points' (i.e. 72nds of an inch) for the positioning of the EPS image. With offsets of 0 for X and Y, the image will be printed at the extreme left edge of the box for that day, just under the numerics for that day. Positive values move the image to the right and negative values move the image to the left.

<y-delta>

:= a vertical adjustment in typographic `points' (i.e. 72nds of an inch) for the positioning of the EPS image. With offsets of 0 for X and Y, the image will be printed at the extreme left edge of the box for that day, just under the numerics for that day. Positive values move the image up and negative values move the image down.

Here's an example of a line from the date file that associates an EPS image with an event:

	4th Thu in Nov*   Thanksgiving
	4th Thu in Nov*   image:/eps-path/turkey.eps 1.0 1.0 0 0

You can place as many images as you want on a single day of the month by specifying repeated lines in the date file. For example, these lines put icons of George Washington and Abraham Lincoln on the day of the U.S. ``Presidents' Day'' holiday, along with the event text:

	3rd Monday in Feb*   Presidents' Day
	3rd Monday in Feb*   image:/eps-path/washington.eps 0.08 0.08 8 0
	3rd Monday in Feb*   image:/eps-path/lincoln.eps 0.22 0.22 48 0

Note that the icon for Lincoln is shifted to the right by 48 typographic points so as not to overlay the first icon.

The pcal releases come with a single EPS sample file ('eps/recycle.eps') of the ubiquitous 'recycle' icon (3 green arrows in a triangular shape). Such an image might be used with configuration file settings like this:

	second Sat in all RECYCLE!
	second Sat in all image:/eps-path/recycle.eps 0.039 0.039 34 -9

In cases where you're displaying non-holiday event text (e.g. someone's birthday) and an EPS image, you'll often need to use a negative `Y-delta' value on the EPS image specification line, in order to shift the image down so that it doesn't cover the event text, which appears just below the day's numerics for non-holiday events. (Text for holiday events appears higher up, to the right of the day's numerics, so there's usually no collision with the EPS image.)

Note: Unfortunately, most EPS images cannot be used directly by pcal.

For converting non-EPS images (e.g. photos) to EPS format, one can use the graphical GNU Image Manipulation Program, a.k.a. `The GIMP':

For icons/images in WMF format (which are popular in various 3rd-party, legacy-OS, commercial calendar programs), the `libwmf'/`wmf2eps' library/utility is useful for generating pcal-capable EPS images. It can be found at this site:

For icons/images in SVG format, the ImageMagick `convert' utility is sometimes useful for generating pcal-capable EPS images. This suite of utilities (which includes other useful ImageMagick utilities like `display' and `identify') may already be available on your Linux distribution. If not, it can be found at this site:

For cases where ImageMagick's `convert' utility fails to properly convert SVG-format images to EPS format, you can try the method of converting the SVG image into an intermediate format (e.g. PNG) using the `rsvg' utility. This utility may already be available on your Linux distribution. If not, it can be found at this site:

From the PNG format, the image can often then be successfully converted to EPS format, using the above-mentioned ImageMagick `convert' utility.

The Open Clip Art Library is a good source of freely-usable images (many of which are in SVG format) for decorating your events:

Note: The EPS image content is not generated in the PostScript output -- only a reference to the EPS image filename is generated. From a practical standpoint, this means that normally you'll need to print/preview the PostScript output of pcal from the same computer/setup as that which was used to run pcal in the first place. If you want to generate a calendar with embedded EPS images that will later be printed/viewed on another machine which does not have access to those EPS images, you'll need to run the output through a pre-processor which will put the EPS image content into the PostScript output file. For example, assuming your initial calendar output was generated to a file named `pcal.ps', on most GNU/Linux systems you could run this command, which uses the popular `Ghostscript' interpreter:

This would generate a PostScript file named `out.ps', at 300x300 dpi resolution, which has the actual EPS image content embedded within, allowing you to transport the `out.ps' file to another computer for viewing/printing. Of course, the new file is substantially larger, but it's portable. Furthermore, the EPS images will be viewable even in PostScript-viewing applications (see above) which don't properly support the display of embedded (by filename only) EPS images.

Pre-Processor Functionality

Note that these are not preceded by `#' as they are in C.

Symbol names defined using these keywords (or via the -D option) are case-insensitive. It is not an error to undef an undefined symbol, nor to define a previously-defined one.

A symbol can be defined with just a name (e.g. ``define MY_SYM'') or it can take on a value (e.g. ``define MY_SYM SOME_VALUE''). Use of symbol values is convenient for defining a starting date then using that symbol to reference that starting date in one or more events. For example, these definitions in the date file might be useful:

	define semester_start 8/23   # Beginning of semester
	semester_start                 Class Start
	7th  day after semester_start  1st Quiz
	14th day after semester_start  2nd Quiz
	undef semester_start

Be aware that the substitution of symbol values for symbol names is not robust, so it's wise to use a symbol name that's unlikely to occur in any of your other event text. In other words, if you defined the `semester_start' symbol in the example above as merely `start', then you'd get the undesired effect of having the text `Class 8/23' in your calendar on that day instead of `Class Start'! The use of `undef semester_start' in the above example is optional and is really only useful to prevent any unwanted symbol substitutions later on, which probably won't happen unless you poorly choose your symbol name to begin with.

An ifdef alone is always false; an ifndef alone is always true. if is accepted as a synonym for ifdef.

The name of the file in the include directive may optionally be surrounded by either "" or <>, both of which are ignored. If the name is not an absolute path, it is taken to be relative to the directory where the file containing the directive is located. If the string "%y" appears in the file name, it is replaced by the last two digits of the current year or, if "year all" is in effect, is expanded to all applicable years. Pcal is smart enough to translate ~/ to the user's home directory.

Pcal normally terminates immediately if the file specified in an include directive does not exist. An alternate form of the directive, include?, directs pcal to continue silently if the file does not exist or cannot be opened.

In addition to pre-processing keywords, pcal also accepts boolean expressions in if{{n}def} and elif directives. These expressions consist of symbol names joined by the boolean operators !, &, ^, and |, in order of precedence, high to low. Parentheses may be used to alter the precedence. The synonyms && and || are accepted for & and |. A symbol name evaluates to true if currently defined, false if not; thus:

	ifdef A | B | C

...is true if any of the symbols A, B, and C is defined, and:

	ifdef A & B & C

...is true if they all are. Note that ifndef <expr> is equivalent to ifdef !( <expr> ).

The Moon File

Entries in the moon file must conform to the following syntax:

If the -A option (American date formats, the default) is given:

	<quarter> <month><sep><day> {<hour><sep><min>}

If the -E option (European date formats) is given:

	<quarter> <day><sep><month> {<hour><sep><min>}

Where:

	<quarter>	:= ``nm'', ``fq'' or ``1q'', ``fm'', ``3q'' or ``lq'' (new moon,
				first quarter, full moon, last quarter)
	<hour>		:= number 0-23 (24-hour clock)
	<min>		:= number 0-59

This file must contain entries for all quarter moons in the year, in chronological order; if any errors are encountered, pcal will revert to using its default algorithm.

As in the date file, comments start with `#' and run through the end of the given line.

The moon file may optionally contain an opt -A or opt -E line to specify the format of its own date entries independently of the format used in the date file. No other flags are legal in the moon file.

Generating PostScript Calendars Via A Web Browser Interface

Pcal comes with 4 files that provide this ability: `pcal.cgi' (a Bourne shell script), `pcal.pl' (a Perl equivalent of `pcal.cgi'), `pcal.html', and `pcalw.html'.

The CGI file (either `pcal.cgi' or `pcal.pl') must be edited before using it. Change the definition for `pcal=' (Bourne shell script) or `my $PCAL =' (Perl script) to point to the location of the pcal executable file. Change the definition for `file=' (Bourne shell script) or `my $FILE =' (Perl script) to point to the location of the pcal `date file' (e.g. `.calendar'), which contains the options for running pcal. Finally, copy the `pcal.cgi' (or `pcal.pl') file to the location where your web server expects to find such files (e.g. `/var/www/cgi-bin/').

The `pcal.html' and `pcalw.html' files must also be edited. Each one has a line like this:

That line must be edited to point to the host and location of your CGI script file (`pcal.cgi' or `pcal.pl').

Once that's done, point your web browser to the `pcal.html' or `pcalw.html' file to generate monthly/yearly PostScript calendars for viewing within your web browser.

Additional Options For Debugging Only

The subflags may be combined: e.g. "-ZDF" is equivalent to "-ZD -ZF". All of the aforementioned debugging information is written to stderr.