.\"
.\" pcal.man - documentation for Pcal
.\"
.\" This 'man' page may be generated in alternate formats with any
.\" of the following commands:
.\"
.\" groff -man -Tps pcal.man >pcal-help.ps
.\" groff -man -Thtml pcal.man >pcal-help.html
.\" groff -man -Tascii pcal.man >pcal-help.txt
.\"
.\" Revision History:
.\"
.\" 4.11.0
.\"
.\" 2007-12-15 -- changes by Bill Marr (marr99@users.sourceforge.net):
.\"
.\" Update version number and date.
.\"
.\" Describe newly-added languages: Slovak and Hawaiian
.\"
.\" Describe use of newly-added "on" preposition.
.\"
.\" Describe use of newly-added '-W' option.
.\"
.\" Remove 'F13' as a pre-defined event, now that the new 'on'
.\" preposition allows that event to be specified generically.
.\"
.\" Add long-missing descriptions of predefined symbols for 'paper size'
.\" and 'page orientation'.
.\"
.\" Mention the 'examples' directory and all the useful files contained
.\" within.
.\"
.\" Mention the 'recycle.eps' EPS image file that comes with the 'pcal'
.\" distribution and give an example of how to use it.
.\"
.\" Mention the use of ImageMagick's 'convert' utility and the 'rsvg'
.\" utility to convert SVG images into EPS format.
.\"
.\" Fix a minor capitalization typo and a minor spelling error.
.\"
.\" Make various other minor tweaks and updates.
.\"
.\" 4.10.0
.\"
.\" 2006-07-12 -- changes by Bill Marr (marr99@users.sourceforge.net):
.\"
.\" Update version number and date.
.\"
.\" Describe newly-added languages: Polish, Dutch, Romanian, and Danish
.\"
.\" Update 'AUTHORS' credits list.
.\"
.\" Expand the comments on the use of the time-zone option ('-z'). Also,
.\" make it clear that fractional values are allowed for the timezone
.\" value specification.
.\"
.\" Make note of the options/values which can be specified
.\" semi-permanently via the makefile.
.\"
.\" Clarify interpretation of 1-digit or 2-digit specification of the year.
.\"
.\" Add a link to the website where 'pcal' (and 'lcal') can be found.
.\"
.\" Add a link to the website where the 'bsdmainutils' package (with the
.\" old Unix/BSD 'calendar' program) can be found.
.\"
.\" Remove now-obsolete comment about having to comment out the
.\" 'showpage' command in EPS image files. This only applied to
.\" 'pcal' version 4.8.0.
.\"
.\" Clarify 'character remapping' and 'font use' comments in the '-a'
.\" option description section. Mention a useful website that discusses
.\" Greek fonts.
.\"
.\" Update date in reference to Adobe website.
.\"
.\" 4.9.1
.\"
.\" 2005-08-24 -- changes by Bill Marr (marr99@users.sourceforge.net):
.\"
.\" Update version number and date.
.\"
.\" 4.9.0
.\"
.\" 2005-08-10 -- changes by Bill Marr (marr99@users.sourceforge.net):
.\"
.\" Remove references to the now-obsolete custom 'Esperanto' character
.\" encoding, now that 'Latin3' (ISO 8859-3) is supported.
.\"
.\" Clarify the use of the options for specification of fonts and font
.\" sizes, especially for yearly-format calendars versus monthly-format
.\" calendars.
.\"
.\" 2005-08-01 -- changes by Bill Marr (marr99@users.sourceforge.net):
.\"
.\" Document the newly-added 'delete' event keyword/capability.
.\"
.\" Document the fact that the search for the configuration file in the
.\" executable directory is now disabled by default in the 'Makefile'.
.\"
.\" Describe another newly-added language (ca [Catalan]) in the list of
.\" those supported by the '-a' option.
.\"
.\" Mention and include a link to the Open Clip Art Library as a good
.\" source of images for event decoration.
.\"
.\" Document the fact that the 'showpage' command need no longer be
.\" disabled in EPS files used by 'pcal'.
.\"
.\" Fix link to Adobe documentation.
.\"
.\" Remove the 'experimental' comment for the Lithuanian, Latvian, and
.\" Russian languages now that the necessary character encodings are
.\" provided.
.\"
.\" 2005-01-23 -- changes by Bill Marr (marr99@users.sourceforge.net):
.\"
.\" Describe the newly-added languages (cs [Czech] and hu [Hungarian])
.\" in the list of those supported by the '-a' option.
.\"
.\" Document the support for the 12 new character encodings.
.\"
.\" Describe the use of the new `pcal.pl' Perl script for HTML/CGI
.\" generation of calendars.
.\"
.\" Describe the new values available for the '-r' (character set
.\" remapping) option, including the old 'KOI8-U' value that was
.\" accidentally left out of this file for v4.8.0.
.\"
.\" 4.8.0
.\"
.\" 2004-12-04 -- changes by Bill Marr (marr99@users.sourceforge.net):
.\"
.\" Provide this commented-out section in the header of this 'pcal.man'
.\" file to document the revision history.
.\"
.\" Provide instructions at the beginning of this file on how to
.\" generate the various human-readable forms of this 'man' page.
.\"
.\" Add a detailed new section ('Encapsulated PostScript (EPS) Images')
.\" to document the newly-added ability for embedded EPS images (photos,
.\" icons, etc) on monthly PostScript calendars.
.\"
.\" Add a new section ('Generating PostScript Calendars Via A Web
.\" Browser Interface') to document the long-available ability to
.\" generate PostScript calendars via a web browser interface using a
.\" CGI (Common Gateway Interface) script and a couple of HTML user
.\" interface files.
.\"
.\" In a special section apart from the normal 'pcal' options, document
.\" the '-Z' (debug-only) flag, which has been available since version
.\" 4.3, but for which the documentation was intentionally left out of
.\" the 'man' page.
.\"
.\" Add the newly-added languages (sv [Swedish], pt [Portuguese], uk
.\" [Ukrainian], et [Estonian], ru [Russian], lv [Latvian], and lt
.\" [Lithuanian]), to the list of those supported by the '-a' option.
.\"
.\" Change the '-a' switch option for the Greek language from 'gr' to
.\" 'el' to match the ISO 639 (2-letter and 3-letter language codes)
.\" standard.
.\"
.\" Slightly re-order both the list of command-line options and the
.\" associated full-length descriptions so that they're in the same
.\" order.
.\"
.\" Use the 'groff'/'man' '.SS' macro (unnumbered secondary section
.\" heading) to provide nicer-looking section breaks.
.\"
.\" Create new 'secondary sections' for existing descriptions of 'Format
.\" Specifiers', 'Pre-Processor Functionality', and 'The Moon File'.
.\" Previously, these first 2 sections were part of one monolithic
.\" section and the third was delineated with a simple bold font rather
.\" than being defined in a distinct secondary section.
.\"
.\" Enhance the description of 'Pre-Processor Functionality' to include
.\" the newly added ability to define a symbol value alongside a symbol
.\" name with the 'define' directive.
.\"
.\" Provide additional examples of entries for the 'date file' (i.e. the
.\" 'pcal' configuration file).
.\"
.\" Change a couple of the existing examples of entries for the 'date
.\" file' to reflect more-current 'year' values, to make it obvious how
.\" to specify post-1999 years.
.\"
.\" Fix 2 small bugs (from the Debian Bug Tracking List for 'pcal') in
.\" the use of escape sequences (e.g. '-\H' changed to '\-H') which was
.\" causing the associated hyphenated 'pcal' option descriptions to
.\" appear incorrectly.
.\"
.\" Add an HTML link to the free, online Adobe "PostScript Language
.\" Reference Manual" book for those wanting to delve into the
.\" PostScript world a bit deeper.
.\"
.\" Update the 'AUTHORS' section with a list of all known recent
.\" contributors.
.\"
.\" Add commented-out lines which consist of several hypostrophes,
.\" merely as a visual aid to the section breaks within this document
.\" for future editors. Also, to avoid text colorization problems (in
.\" Emacs' 'font-lock-mode', usually because of a line starting with a
.\" double-quote character), break certain lines at a different spot,
.\" which does not affect the 'man' page output at all.
.\"
.\" Change parameter names associated with '-s' command-line option from
.\" 'date_shade' and 'fill_shade' to 'day_numerics_color' and
.\" 'empty_day_box_fill_color' to more accurately reflect their
.\" function, especially since the specification of a non-gray-scale
.\" (i.e. RGB color) has been possible with this parameter for some time
.\" now.
.\"
.\" Change various references to the color 'gray' to reflect the fact
.\" that the colors used are those specified by the '-s' option, with
.\" the default for both colors being 'gray'.
.\"
.\" Document the '-q' flag (print one column per month, for HTML
.\" calendars only) which has been available since 'pcal' version 4.7.1.
.\"
.\" Document the issue of collision of month names and day-of-week names
.\" in certain languages (e.g. French and Finnish).
.\"
.\" To avoid confusion, provide a note about use of no space between an
.\" option and its negative value to prevent 'pcal' from misinterpreting
.\" the negative option value as an illegal option itself, based on a
.\" problem reported by a user on the 'pcal' SourceForge site.
.\"
.\" Provide various other small cleanups and generally bring the
.\" document up-to-date for all the changes which have gone into 'pcal'
.\" over the various revisions, including some changes to reflect
.\" oversights from previous revisions.
.\"
.\" Perform general formatting cleanups designed to make the output of
.\" this manual page easier to read.
.\"
.\"
.TH PCAL 1 "18 Dec 2007" "Version 4.11.0" "USER COMMANDS"
.SH NAME
pcal \- generate PostScript (or HTML) calendars
.SH SYNOPSIS
.na
.in +5n
.ti -5n
.B pcal
[\fB\-e\fP|\fB\-f\fP\ \fIcal\fP\|]
[\fB\-o\fP\ \fIfile\fP\|]
[\fB\-l\fP\ |\ \fB\-p\fP]
[\fB\-P\fP\ [letter | legal | a4 | tabloid]]
[\fB\-j\fP\ |\ \fB\-J\fP]
[\fB\-m\fP\ |\ \fB\-M\fP]
[\fB\-g\fP\ \fIweekday\fR[\fI\-weekday\fR]|all|holiday]
[\fB\-O\fP\ \fIweekday\fR[\fI\-weekday\fR]|all|holiday]
[\fB\-G\fP\ \fIweekday\fR[\fI\-weekday\fR]|all|holiday]
[\fB\-b\fP\ \fIweekday\fR[\fI\-weekday\fR]|all|holiday]
[\fB\-s\fP\ [\fIday_numerics_color\fP][/\fIempty_day_box_fill_color\fP\|]]
[\fB\-F\fP\ \fIday\fP\|]
[\fB\-A\fP|\fB\-E\fP]
[\fB\-X\fP\ \fIxtrans\fP\|]
[\fB\-Y\fP\ \fIytrans\fP\|]
[\fB\-x\fP\ \fIxscale\fP\|]
[\fB\-y\fP\ \fIyscale\fP\|]
[\fB\-t\fP\ [\fItitle_font\fP][/\fIsize\fP\|]]
[\fB\-d\fP\ [\fIday_font\fP][/\fIsize\fP\|]]
[\fB\-n\fP\ [\fItext_font\fP][/\fIsize\fP\|]]
[\fB\-L\fP\ \fIfooter_str\fP\|]
[\fB\-C\fP\ \fIfooter_str\fP\|]
[\fB\-R\fP\ \fIfooter_str\fP\|]
[\fB\-N\fP\ \fInotes_str\fP\|]
[\fB\-D\fP\ \fIsymbol\fP\|]
[\fB\-U\fP\ \fIsymbol\fP\|]
[\fB\-B\fP]
[\fB\-#\fP\ \fIn\fP\|]
[\fB\-S\fP\ |\ \fB\-k\fP\ |\ \fB\-K\fP]
[\fB\-w\fP]
[\fB\-I\fP]
[\fB\-c\fP\ |\ \fB\-H\fP]
[\fB\-q\fP]
[\fB\-z\fP\ \fItime_zone\fP\|]
[\fB\-h\fP\ |\ \fB\-u\fP\ |\ \fB\-v\fP]
[\fB\-a\fP\ \fIoutput_language\fP\|]
[\fB\-r\fP\ [\fImapping\fP]
[\fB\-T\fP\ [B|I|R]]
[\fB\-W\fP\ [left|center|right]]
[month]
[year]
[nmonths]
.\" ------------------------------------------------------------------
.SH DESCRIPTION
.I Pcal
generates PostScript to produce landscape or portrait calendars for any
month and year. The arguments
.BR month ,
.BR year ,
and
.BR nmonths ,
if provided, should be numeric. The
.BR month
value should be in the range 1 \- 12, and the
.BR year
value should be specified as 1 or 2 digits (in which case it will be
interpreted as that year in the current century) or as the full 4-digit year.
If no numeric arguments are provided, the calendar for the current month and
year will be generated.
.PP
If one numeric argument is provided, it is interpreted as the
.BR year
value, and calendars for the entire year will be generated. Otherwise,
.BR nmonths
months, starting with
.BR month
and
.BR year ,
will be generated.
.PP
For whole-year calendars (i.e. when the
.B \-w
option is given), the command line arguments are interpreted somewhat
differently. By default, all months in the current year are printed, starting
with January. If the
.B month
argument alone is given, it is expected to be the desired
.B year
to print, and prints all of the months in the given year. If both
.BR month " and " year
are given, then 12 consecutive months are printed starting at the given
month and year. If the
.BR month ", " year ", and " nmonths
arguments are all present, printing begins with the given month and year and
.B nmonths
months are printed, rounded up to the nearest multiple of 12.
.\" ------------------------------------------------------------------
.SS The Date File (Configuration File)
By default,
.I pcal
simply prints an empty calendar. Its real power is in its ability to place
``events'' (and, for monthly-format PostScript calendars, Encapsulated
PostScript images [e.g. photos and icons]) in appropriate days on the
(PostScript or HTML) calendar, thus allowing the user to create personalized
calendars. This is achieved through the use of the ``date file'', also known
as the ``configuration file''.
.PP
The default date/configuration file is expected to be named
.IR \.calendar " (" pcal.dat
under MS-DOS),
or
.I calendar
for compatibility with older versions.
.I Pcal
will look in several places for such a file. First, if the environment variable
.BR PCAL_DIR
is defined,
.I pcal
searches the directory indicated by that variable.
Next,
.I pcal
searches the user's home directory (as specified by the
.BR HOME
environment variable).
If neither
.BR PCAL_DIR
nor
.BR HOME
is defined,
.I pcal
searches the current directory instead. Finally, if enabled (via
the `SEARCH_PCAL_DIR' flag) when
.I pcal
was built, the directory where the
.I pcal
executable resides will be checked. (This final search of the
executable directory has been disabled in the version shipped with
Debian.) If no date file is found, an empty
calendar is printed; no error is generated.
.PP
Alternatively, the name of the date file (and, optionally, the path where it
can be found) can be specified using the
.B \-f
command-line option. See the \fBOPTIONS\fP section for more details.
.PP
Every
.I 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).
.PP
If a date file is found, it will be searched for lines with
leading dates matching the requested month and year.
.PP
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.
.PP
\fBtroff\fP-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,
, , , and may be used instead to enable/disable Bold or
Italic font styles. The font style is reset to Roman after each line break.
.PP
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.
.PP
Dates (essentially `events') in the configuration files may be expressed in
any of several formats:
.RS
.LP
.IP \(bu 2
in {*} {}
.IP \(bu 2
{} {*} {}
.IP \(bu 2
{*} {}
.IP \(bu 2
{*} {}
.RE
.LP
Where:
.PP
.\".nf
.TP 22
:= first 3+ characters of name of month, or ``all''
.IP
.B Note:
.I 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'.
.TP
:= , or ``year''
.TP
:= first 3+ characters of name of weekday, ``day'', ``weekday'', ``workday'',
``holiday'', ``nonweekday'', ``nonworkday'', ``nonholiday'', ``new_moon'',
``first_quarter'', ``full_moon'', or ``last_quarter''
.TP
:= any ordinal number (``1st'', ``2nd'', etc.), ``first'' ... ``fifth'',
``last'', ``odd'', ``even'', or ``all''
.TP
:= ``on'', ``before'', ``preceding'', ``after'', ``following'', ``on_or_before''
(``oob''), ``on_or_after'' (``ooa''), ``nearest'', ``nearest_before``, or
``nearest_after``
.TP
:= ``Christmas'', ``Thanksgiving'', ``Easter'', ``Good_Friday'', ``GEaster''
(Orthodox Easter), ``Gstgeorge'' (Orthodox holiday), and ``Gmarcus'' (Orthodox
holiday).
.TP
:= one or more non-numeric, non-space, non-`*' characters
.TP
:= a numeric month (1-12)
.TP
:= day of month (1-31)
.TP
:= a numeric year
.TP
:= 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
.PP
If the
.B \-A
option (American date formats, the default) is given:
.PP
.TP 22
:= | {}
.PP
If the
.B \-E
option (European date formats) is given:
.PP
.TP 22
:= | | {}
.PP
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.
.PP
Examples:
.PP
.ft CW
.nf
last Monday in May* Memorial Day Holiday
.sp
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)
.sp
Tue after first Mon in Nov Election Day (USA)
.sp
4th Thu in Nov* Thanksgiving
Fri after 4th Thu in Nov* Day after Thanksgiving
workday nearest 12/25* Holiday
.sp
12/25/04* Christmas # American
25.12.04* Christmas # European
25. 12.* Christmas # European
.sp
Dec 25* Christmas # American
25 Dec* Christmas # European
25. Dec* Christmas # European
.sp
Fri on all 13 Avoid black cats! # 'Friday the 13th'
.fi
.ft
.PP
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
.B \-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.
.PP
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
.B 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''.
.PP
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''.
.PP
``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 \(em not to
those Fridays falling on odd dates.
.PP
``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.
.PP
``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 \fIpcal\fP 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.)
.PP
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
.B newline
) and the standard ANSI character escapes (`\\a', `\\b', `\\f', `\\n', `\\r',
`\\t', `\\v') are all replaced by a single blank.
.PP
The HTML special characters `<' `>' `"' `&' ` ' 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
.B \-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
.I "calendar(1)"
(see the
.B \-c
flag) input.
.PP
Lines in the configuration file consisting of
.B year ####
(where
.B ####
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.
.PP
Lines in the configuration file consisting of
.B year all
(or, alternatively, \fByear *\fP) direct \fIpcal\fP 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 \fByear ####\fP entry) will set the remembered year
to that year.
.PP
Lines in the configuration file consisting of
.B opt
can be used to override the defaults for
any command-line options except
.BR \-c ,
.BR \-e ,
.BR \-f ,
.BR \-h ,
.BR \-H ,
.BR \-u ,
.BR \-v ,
.BR \-D ", and"
.BR \-U .
Any options specified in this manner
are, in turn, overridden by those specified explicitly on the command line.
.PP
Lines in the configuration file consisting of
.B note{/}
can be used to place notes regarding the
entire month in one of the unused blocks of the calendar. The
.B
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.
.B
is an optional positive or negative number specifying the
empty box where the associated text is to be placed. If positive,
.I pcal
counts forward from the first empty box; if negative,
.I pcal
counts backward from the last empty box. Thus,
.BR ``note/1''
places the associated text in the first empty box;
.BR "note/-3"
in the third-to-last. The default is -1 if no is given
(last empty box, immediately preceding the small
calendars on the bottom row; cf.
.BR \-S ,
.BR \-k ,
and
.BR \-K ,
below). You can place several notes in the same box. You can also use more
than 1 box for the various monthly notes.
.PP
Lines in the configuration file consisting of
.B input-language XX
(where
.B 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
.B \-a
option.
.PP
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 `\\'.
.\" ------------------------------------------------------------------
.SS Deleting Events
By prepending the
.I `delete'
keyword to an event specification, one or more events may be deleted from a
set of previously-specified events.
.PP
For example, the following lines might appear in the date file:
.PP
.RS
.LP
.nf
all Friday in all Poker game
delete first Friday in all Poker game
.fi
.RE
.LP
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.
.\" ------------------------------------------------------------------
.SS Format Specifiers
.I Pcal
allows format specifiers in both the event text and footer strings (see the
.BR \-L ,
.BR \-C ,
.BR \-R ,
and
.B \-N
options below). Each format specifier will be replaced by a corresponding
string as outlined in the following table:
.PP
.nf
%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
.fi
.PP
Most of these are derived from the ANSI C
.ft CW
strftime()
.ft
function, but the
.B %[louwMD]
and
.B %[o0+\-]
format specifiers are specific to
.IR pcal .
.PP
The
.B %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
.B \-F
option below) as the start of week 2;
.B %U
considers the first logical Sunday as the first day of week 1.
.B %w
and
.B %W
behave like
.B %u
and
.B %U
respectively, but use the first logical Monday instead. Note that
.B %w
has a different meaning from
.ft CW
strftime().
.ft
.PP
The
.B %o
format specifier prints a number as an ordinal, with the appropriate suffix
(``st'', ``nd'', ``rd'', or ``th'' in English) appended. For example,
.B %od
prints the day of the month as ``1st'', ``2nd'', ``3rd'', etc.
.PP
Unlike
.ft CW
strftime(),
.ft
.I pcal
defaults to printing numbers (except
.BR %y )
without leading zeroes. If leading zeroes are desired, the `0'
prefix may be used. For example,
.B %0j
prints the first day of year as ``001''.
.PP
The
.B %+
and
.B %\-
format specifiers direct
.I pcal
to substitute the following/previous month/year in the following
.B [bBmyY]
specifier. For example,
.B %+B
prints the name of the next month.
.PP
The
.B %{[+\-]N}[DWMY]
format specifiers do not print anything, but instead adjust the working
date by \(+-
.BR N days
.RB ( D ),
weeks
.RB ( W ),
months
.RB ( M ),
or years
.RB ( Y ).
Subsequent format specifiers use the adjusted date instead of the
current date. For example,
.B %+1M %B %Y
adjusts the date forward by one month and then prints the resulting
month and year (``January 1992'' in December, 1991);
.B %\-2W %b %d
adjusts the date backward by two weeks and prints the resulting
month and day (``Jul 26'' on August 9).
.PP
Such date adjustments are normally cumulative; for example,
.B %+1Y%\-1D
adjusts the date forward by one year and then backward by one day. If
.B %D
or
.B %M
is specified alone (or if
.B N
is zero),
.I pcal
restores the original date. Note that
.B %M
has a different meaning to the
.ft CW
strftime()
.ft
function.
.PP
Here's a common, useful example of an event entry for the
.I 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:
.RS
.LP
May 10 Eric's %-1991Y%oY Birthday
.RE
.LP
That entry would result in the following text being displayed on May 10, 2005:
.PP
.RS
.LP
Eric's 14th Birthday
.RE
.LP
.\" ------------------------------------------------------------------
.SS Encapsulated PostScript (EPS) Images
For monthly PostScript calendars only,
.I pcal
supports the embedding of one or more EPS images (photos, icons, etc) into any
given day of the month. (EPS image specifications in the
.I pcal
date file are ignored for yearly PostScript calendars and for all HTML
calendars.)
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:
.PP
.ft CW
.nf
image:
.fi
.ft
.PP
Where:
.PP
.TP 28
is the filename (which can include a path) of the Encapsulated PostScript
image.
.BR "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.
.TP
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 parameter to account for
the image's relocated position that occurs when it gets
flipped "left-to-right".
.TP
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 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 parameter to account for the image's
relocated position that occurs when it gets flipped "upside down".
.TP
:= 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.
.TP
:= 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.
.PP
Here's an example of a line from the date file that associates an EPS image
with an event:
.PP
.ft CW
.nf
4th Thu in Nov* Thanksgiving
4th Thu in Nov* image:/eps-path/turkey.eps 1.0 1.0 0 0
.fi
.ft
.PP
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:
.PP
.ft CW
.nf
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
.fi
.ft
.PP
Note that the icon for Lincoln is shifted to the right by 48 typographic
points so as not to overlay the first icon.
.PP
The
.I 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:
.PP
.ft CW
.nf
second Sat in all RECYCLE!
second Sat in all image:/eps-path/recycle.eps 0.039 0.039 34 -9
.fi
.ft
.PP
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.)
.PP
.BR "Note:"
Unfortunately, most EPS images cannot be used directly by
.IR pcal .
.RS
.LP
Depending on the EPS image used and how it was created, you may have to remove
or comment out some or all of the PostScript `translate' commands, in order to
avoid the use of illogical X-delta and Y-delta values when specifying the EPS
image in your
.I pcal
date file. Most programs that generate EPS output (either directly or via
conversion from some other graphic format) seem to have these `translate'
commands relatively early in the EPS file.
.PP
It may take some experimentation to get it just right. Preview the
.I pcal
output using a PostScript viewer as you tweak the PostScript commands in the
EPS image file and/or the event entry in the
.I pcal
date file.
.RS
.LP
.BR "Note:"
Depending upon what application you use to preview PostScript
content, the monthly calendars may not show any embedded EPS images.
Here's a rundown of some popular PostScript-viewing applications and
whether they correctly display the embedded EPS images:
.RS
.LP
.IP \(bu 2
gv (version 3.5.8) -- EPS images appear fine
.IP \(bu 2
ggv (versions 2.4.0.1 and 2.6.1) -- EPS images appear fine
.IP \(bu 2
older kghostview (versions 0.13.2 [KDE 3.1.4] and 0.2.0 [KDE 3.2.3 and 3.3.2]) -- EPS images DO NOT APPEAR!
.IP \(bu 2
newer kghostview (version 0.2.0 [KDE 3.4.2 and 3.5.4]) -- EPS images appear fine
.RE
.LP
.RE
.LP
.RE
.LP
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':
.RS
.LP
.IR http://www.gimp.org
.RE
.LP
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
.IR pcal -capable
EPS images. It can be found at this site:
.RS
.LP
.IR http://wvware.sourceforge.net/libwmf.html
.RE
.LP
For icons/images in SVG format, the ImageMagick `convert' utility is sometimes
useful for generating
.IR 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:
.RS
.LP
.IR http://www.imagemagick.org
.RE
.LP
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:
.RS
.LP
.IR http://librsvg.sourceforge.net/
.RE
.LP
From the PNG format, the image can often then be successfully converted to EPS
format, using the above-mentioned ImageMagick `convert' utility.
.LP
The
.I Open Clip Art Library
is a good source of freely-usable images (many of which are in SVG format) for
decorating your events:
.RS
.LP
.IR http://www.openclipart.org
.RE
.LP
.BR "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
.I pcal
from the same computer/setup as that which was used to run
.I 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:
.RS
.LP
gs -r300x300 -dBATCH -dNOPAUSE -sDEVICE=pswrite -sOutputFile=out.ps pcal.ps
.RE
.LP
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.
.\" ------------------------------------------------------------------
.SS Pre-Processor Functionality
.I Pcal
supports rudimentary
.IR cpp -like
functionality in the
date file, allowing the following constructs:
.RS
.LP
.IP \(bu 2
.BR "define | undef"
.IP \(bu 2
.B if{{n}def} ... {elif ...}* {else ...} endif
.IP \(bu 2
.BR include
.RE
.LP
Note that these are not preceded by `#' as they are in C.
.PP
Symbol names defined using these keywords (or via the
.B -D
option) are case-insensitive.
It is not an error to
.BR undef
an undefined symbol, nor to
.BR define
a previously-defined one.
.PP
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:
.PP
.ft CW
.nf
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
.fi
.ft
.PP
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.
.PP
An
.BR ifdef
alone is always
.BR false "; an"
.BR ifndef
alone is always
.BR true .
.BR if
is accepted as a synonym for
.BR ifdef .
.PP
The name of the file in the
.BR 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.
.I Pcal
is smart enough to translate
.B ~/
to the user's home directory.
.PP
.I Pcal
normally terminates immediately if the file specified in an
.BR include
directive does not exist. An alternate form of the directive,
.BR include? ,
directs
.I pcal
to continue silently if the file does not exist or cannot be opened.
.PP
In addition to pre-processing keywords,
.I pcal
also accepts boolean expressions in
.B if{{n}def}
and
.B elif
directives. These expressions consist of symbol names joined by the boolean
operators
.BR ! ", " & ", " ^ ", and "
.BR | ,
in order of precedence, high to low. Parentheses may be used to alter the
precedence. The synonyms
.BR && " and " ||
are accepted for
.BR & " and " | .
A symbol name evaluates to
.B true
if currently defined,
.B false
if not; thus:
.PP
.ft CW
.nf
ifdef A | B | C
.fi
.ft
.PP
\&...is
.B true
if any of the symbols A, B, and C is defined, and:
.PP
.ft CW
.nf
ifdef A & B & C
.fi
.ft
.PP
\&...is
.B true
if they all are. Note that
.B ifndef
is equivalent to
.B ifdef !( ).
.\" ------------------------------------------------------------------
.SS The Moon File
If a file of the name
.IR .moon## " (" moon##.dat
under MS-DOS),
where
.B ##
is the last two digits of the calendar year, exists in the same directory
as the date file (or in the directory where
.I pcal
resides),
.I pcal
uses the information contained within to calculate the phase of the
moon. If a) no such file exists, b) the
.B \-e
flag (do not use a date file) is specified, or c) the
.B \-z
flag (specify time zone) is specified, then
.I pcal
uses an algorithm to calculate the phase of the moon.
.PP
Entries in the moon file must conform to the following syntax:
.PP
If the
.B \-A
option (American date formats, the default) is given:
.PP
.ft CW
.nf
{}
.fi
.ft
.PP
If the
.B \-E
option (European date formats) is given:
.PP
.ft CW
.nf
{}
.fi
.ft
.PP
Where:
.PP
.nf
:= ``nm'', ``fq'' or ``1q'', ``fm'', ``3q'' or ``lq'' (new moon,
first quarter, full moon, last quarter)
:= number 0-23 (24-hour clock)
:= number 0-59
.fi
.PP
This file must contain entries for all quarter moons in the year,
in chronological order; if any errors are encountered,
.I pcal
will revert to using its default algorithm.
.PP
As in the date file, comments start with `#' and run through the
end of the given line.
.PP
The moon file may optionally contain an \fBopt \-A\fR or \fBopt \-E\fR 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.
.PP
.\" ------------------------------------------------------------------
.SS Generating PostScript Calendars Via A Web Browser Interface
PostScript-format
.I pcal
calendars can be generated and viewed from a web browser interface.
.RS
.LP
.BR "Note:"
This is not to be confused with the ability to generate
non-PostScript, HTML-format (using the
.BR \-H
command-line option) calendars,
which is a different capability entirely.
.RE
.LP
.I 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'.
.PP
The CGI file (either `pcal.cgi' or `pcal.pl') must be edited before using
it. Change the definition for
.I `pcal='
(Bourne shell script) or
.I `my $PCAL ='
(Perl script) to point to the location of the
.I pcal
executable file.
Change the definition
for
.I `file='
(Bourne shell script) or
.I `my $FILE ='
(Perl script) to point to the location of the
.I pcal
`date file' (e.g. `.calendar'), which contains the options
for running
.IR 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/').
.PP
The `pcal.html' and `pcalw.html' files must also be edited. Each
one has a line like this:
.RS
.LP