PCAL(1)                          USER COMMANDS                         PCAL(1)



NNAAMMEE
       pcal - generate PostScript (or HTML) calendars

SSYYNNOOPPSSIISS
       ppccaall [--ee|--ff _c_a_l] [--oo _f_i_l_e] [--ll | --pp] [--PP [letter | legal | a4 |
            tabloid]] [--jj | --JJ] [--mm | --MM] [--gg _w_e_e_k_d_a_y[_-_w_e_e_k_d_a_y]|all|holiday]
            [--OO _w_e_e_k_d_a_y[_-_w_e_e_k_d_a_y]|all|holiday] [--GG _w_e_e_k_d_a_y[_-_w_e_e_k_d_a_y]|all|holi-
            day] [--bb _w_e_e_k_d_a_y[_-_w_e_e_k_d_a_y]|all|holiday] [--ss [_d_a_y___n_u_m_e_r_-
            _i_c_s___c_o_l_o_r][/_e_m_p_t_y___d_a_y___b_o_x___f_i_l_l___c_o_l_o_r]] [--FF _d_a_y] [--AA|--EE]
            [--XX _x_t_r_a_n_s] [--YY _y_t_r_a_n_s] [--xx _x_s_c_a_l_e] [--yy _y_s_c_a_l_e]
            [--tt [_t_i_t_l_e___f_o_n_t][/_s_i_z_e]] [--dd [_d_a_y___f_o_n_t][/_s_i_z_e]]
            [--nn [_t_e_x_t___f_o_n_t][/_s_i_z_e]] [--LL _f_o_o_t_e_r___s_t_r] [--CC _f_o_o_t_e_r___s_t_r]
            [--RR _f_o_o_t_e_r___s_t_r] [--NN _n_o_t_e_s___s_t_r] [--DD _s_y_m_b_o_l] [--UU _s_y_m_b_o_l] [--BB] [--## _n]
            [--SS | --kk | --KK] [--ww] [--II] [--cc | --HH] [--qq] [--zz _t_i_m_e___z_o_n_e]
            [--hh | --uu | --vv] [--aa _o_u_t_p_u_t___l_a_n_g_u_a_g_e] [--rr [_m_a_p_p_i_n_g] [--TT [B|I|R]]
            [--WW [left|center|right]] [month] [year] [nmonths]



DDEESSCCRRIIPPTTIIOONN
       _P_c_a_l generates PostScript to produce landscape or portrait calendars
       for any month and year.  The arguments mmoonntthh, yyeeaarr, and nnmmoonntthhss, if
       provided, should be numeric.  The mmoonntthh value should be in the range 1
       - 12, and the yyeeaarr 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 cal-
       endar for the current month and year will be generated.

       If one numeric argument is provided, it is interpreted as the yyeeaarr
       value, and calendars for the entire year will be generated.  Otherwise,
       nnmmoonntthhss months, starting with mmoonntthh and yyeeaarr, will be generated.

       For whole-year calendars (i.e. when the --ww option is given), the com-
       mand line arguments are interpreted somewhat differently.  By default,
       all months in the current year are printed, starting with January.  If
       the mmoonntthh argument alone is given, it is expected to be the desired
       yyeeaarr to print, and prints all of the months in the given year.  If both
       mmoonntthh and yyeeaarr are given, then 12 consecutive months are printed start-
       ing at the given month and year.  If the mmoonntthh, yyeeaarr, and nnmmoonntthhss argu-
       ments are all present, printing begins with the given month and year
       and nnmmoonntthhss months are printed, rounded up to the nearest multiple of
       12.



   TThhee DDaattee FFiillee ((CCoonnffiigguurraattiioonn FFiillee))
       By default, _p_c_a_l 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''.

       The default date/configuration file is expected to be named _._c_a_l_e_n_d_a_r
       (_p_c_a_l_._d_a_t under MS-DOS), or _c_a_l_e_n_d_a_r for compatibility with older ver-
       sions.  _P_c_a_l will look in several places for such a file.  First, if
       the environment variable PPCCAALL__DDIIRR is defined, _p_c_a_l searches the direc-
       tory indicated by that variable.  Next, _p_c_a_l searches the user's home
       directory (as specified by the HHOOMMEE environment variable).  If neither
       PPCCAALL__DDIIRR nor HHOOMMEE is defined, _p_c_a_l searches the current directory
       instead.  Finally, if enabled (via the `SEARCH_PCAL_DIR' flag) when
       _p_c_a_l was built, the directory where the _p_c_a_l 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 --ff command-line
       option.  See the OOPPTTIIOONNSS section for more details.

       Every _p_c_a_l 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' rep-
       resents the 2-letter language code (e.g. 'calendar_de.txt' is the Ger-
       man 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.

       ttrrooffff-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:

              +o <ordinal> <day_spec> in <month_spec>{*} {<text>}

              +o {<ordinal>} <day_spec> <prep> <date_spec>{*} {<text>}

              +o <date_spec>{*} {<text>}

              +o <pre_defined_event>{*} {<text>}

       Where:

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

                             NNoottee:: _p_c_a_l 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 let-
                             ters of one of the names of the days of the week.
                             Because of this, the specification in such a lan-
                             guage 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'', ``near-
                             est_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 specifi-
                             cation 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 --AA option (American date formats, the default) is given:

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

       If the --EE 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 --ss option (default = gray) and will cause the associ-
       ated 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 key-
       words ``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 predom-
       inant 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 ``nonweek-
       day'', ``nonworkday'', and ``nonholiday'' are also recognized as nega-
       tions of the above.  See the CCAAVVEEAATTSS 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_quar-
       ter'', 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
       _p_c_a_l 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 near-
       est_before [Thu.] 9/26/96'' refers to Saturday, 9/28.)

       Text in the date file may use C-like escape sequences (i.e. a `\' fol-
       lowed by a character, 1 - 3 octal digits, or `x' followed by 1 - 2
       hexadecimal digits).  Escaped whitespace (including nneewwlliinnee ) 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 --HH 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 _c_a_l_e_n_d_a_r_(_1_) (see the --cc flag) input.

       Lines in the configuration file consisting of yyeeaarr ######## (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 yyeeaarr aallll (or, alterna-
       tively, yyeeaarr **) direct _p_c_a_l to wildcard following entries against every
       applicable year.  This assumes that the following entries do not con-
       tain a year; any date entries containing year information (or an
       explicit yyeeaarr ######## entry) will set the remembered year to that year.

       Lines in the configuration file consisting of oopptt <<ooppttiioonnss>> can be used
       to override the defaults for any command-line options except --cc, --ee,
       --ff, --hh, --HH, --uu, --vv, --DD, and --UU.  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 nnoottee{{//<<nnuummbbeerr>>}} <<mmoonntthh>>
       can be used to place notes regarding the entire month in one of the
       unused blocks of the calendar.  The <<mmoonntthh>> 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.  <<nnuummbbeerr>> is an optional positive or nega-
       tive number specifying the empty box where the associated text is to be
       placed.  If positive, _p_c_a_l counts forward from the first empty box; if
       negative, _p_c_a_l counts backward from the last empty box.  Thus,
       ````nnoottee//11'''' places the associated text in the first empty box; nnoottee//--33
       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.  --SS, --kk, and --KK, 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 iinnppuutt--llaanngguuaaggee XXXX (where
       XXXX 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 compatibil-
       ity, 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 --aa option.

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



   DDeelleettiinngg EEvveennttss
       By prepending the _`_d_e_l_e_t_e_' keyword to an event specification, one or
       more events may be deleted from a set of previously-specified 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.



   FFoorrmmaatt SSppeecciiffiieerrss
       _P_c_a_l allows format specifiers in both the event text and footer strings
       (see the --LL, --CC, --RR, and --NN options below). Each format specifier will
       be replaced by a corresponding string as outlined in the following ta-
       ble:

            %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
       %%[[lloouuwwMMDD]] and %%[[oo00++--]] format specifiers are specific to _p_c_a_l.

       The %%uu 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 --FF option below) as the start of week 2; %%UU considers the first
       logical Sunday as the first day of week 1.  %%ww and %%WW behave like %%uu
       and %%UU respectively, but use the first logical Monday instead.  Note
       that %%ww has a different meaning from strftime().

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

       Unlike strftime(), _p_c_a_l defaults to printing numbers (except %%yy) with-
       out leading zeroes.  If leading zeroes are desired, the `0' prefix may
       be used.  For example, %%00jj prints the first day of year as ``001''.

       The %%++ and %%-- format specifiers direct _p_c_a_l to substitute the follow-
       ing/previous month/year in the following [[bbBBmmyyYY]] specifier.  For exam-
       ple, %%++BB prints the name of the next month.

       The %%{{[[++--]]NN}}[[DDWWMMYY]] format specifiers do not print anything, but instead
       adjust the working date by +- NNdays (DD), weeks (WW), months (MM), or
       years (YY).  Subsequent format specifiers use the adjusted date instead
       of the current date.  For example, %%++11MM %%BB %%YY adjusts the date forward
       by one month and then prints the resulting month and year (``January
       1992'' in December, 1991); %%--22WW %%bb %%dd 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, %%++11YY%%--11DD
       adjusts the date forward by one year and then backward by one day.  If
       %%DD or %%MM is specified alone (or if NN is zero), _p_c_a_l restores the origi-
       nal date.  Note that %%MM has a different meaning to the strftime() func-
       tion.

       Here's a common, useful example of an event entry for the _p_c_a_l 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:

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

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

              Eric's 14th Birthday

   EEnnccaappssuullaatteedd PPoossttSSccrriipptt ((EEPPSS)) IImmaaggeess
       For monthly PostScript calendars only, _p_c_a_l supports the embedding of
       one or more EPS images (photos, icons, etc) into any given day of the
       month.  (EPS image specifications in the _p_c_a_l 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.  How-
       ever, 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.
                                   NNoottee:: The EPS image filename must be pre-
                                   ceded by the constant text `image:' in
                                   order to distinguish an EPS image specifi-
                                   cation from an ordinary event text specifi-
                                   cation.

            <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.  How-
                                   ever, 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 Post-
                                   Script 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 dimen-
                                   sion 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 Post-
                                   Script 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 typo-
       graphic points so as not to overlay the first icon.

       The _p_c_a_l releases come with a single EPS sample file ('eps/recy-
       cle.eps') of the ubiquitous 'recycle' icon (3 green arrows in a trian-
       gular shape).  Such an image might be used with configuration file set-
       tings 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.)

       NNoottee:: Unfortunately, most EPS images cannot be used directly by _p_c_a_l.


              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
              _p_c_a_l 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.

              It may take some experimentation to get it just right.  Preview
              the _p_c_a_l output using a PostScript viewer as you tweak the Post-
              Script commands in the EPS image file and/or the event entry in
              the _p_c_a_l date file.

                     NNoottee:: 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 popu-
                     lar PostScript-viewing applications and whether they cor-
                     rectly display the embedded EPS images:

                            +o gv (version 3.5.8) -- EPS images appear fine

                            +o ggv (versions 2.4.0.1 and 2.6.1) -- EPS images
                              appear fine

                            +o 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!

                            +o newer kghostview (version 0.2.0 [KDE 3.4.2 and
                              3.5.4]) -- EPS images appear fine

       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':

              _h_t_t_p_:_/_/_w_w_w_._g_i_m_p_._o_r_g


       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 _p_c_a_l-capable EPS images.  It
       can be found at this site:

              _h_t_t_p_:_/_/_w_v_w_a_r_e_._s_o_u_r_c_e_f_o_r_g_e_._n_e_t_/_l_i_b_w_m_f_._h_t_m_l


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

              _h_t_t_p_:_/_/_w_w_w_._i_m_a_g_e_m_a_g_i_c_k_._o_r_g


       For cases where ImageMagick's `convert' utility fails to properly con-
       vert SVG-format images to EPS format, you can try the method of con-
       verting 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:

              _h_t_t_p_:_/_/_l_i_b_r_s_v_g_._s_o_u_r_c_e_f_o_r_g_e_._n_e_t_/

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


       The _O_p_e_n _C_l_i_p _A_r_t _L_i_b_r_a_r_y is a good source of freely-usable images
       (many of which are in SVG format) for decorating your events:

              _h_t_t_p_:_/_/_w_w_w_._o_p_e_n_c_l_i_p_a_r_t_._o_r_g

       NNoottee:: 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 _p_c_a_l from the same computer/set-
       up as that which was used to run _p_c_a_l 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:

              gs -r300x300 -dBATCH -dNOPAUSE -sDEVICE=pswrite -sOutput-
              File=out.ps pcal.ps

       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 sup-
       port the display of embedded (by filename only) EPS images.



   PPrree--PPrroocceessssoorr FFuunnccttiioonnaalliittyy
       _P_c_a_l supports rudimentary _c_p_p-like functionality in the date file,
       allowing the following constructs:

              +o ddeeffiinnee || uunnddeeff

              +o iiff{{{{nn}}ddeeff}} ...... {{eelliiff ......}}** {{eellssee ......}} eennddiiff

              +o iinncclluuddee

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

       Symbol names defined using these keywords (or via the --DD option) are
       case-insensitive.  It is not an error to uunnddeeff an undefined symbol, nor
       to ddeeffiinnee 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 sym-
       bol to reference that starting date in one or more events.  For exam-
       ple, 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 `se-
       mester_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 calen-
       dar on that day instead of `Class Start'!  The use of `undef semes-
       ter_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 iiffddeeff alone is always ffaallssee; an iiffnnddeeff alone is always ttrruuee.  iiff is
       accepted as a synonym for iiffddeeff.

       The name of the file in the iinncclluuddee directive may optionally be sur-
       rounded 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 appli-
       cable years.  _P_c_a_l is smart enough to translate ~~// to the user's home
       directory.

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

       In addition to pre-processing keywords, _p_c_a_l also accepts boolean
       expressions in iiff{{{{nn}}ddeeff}} and eelliiff directives.  These expressions con-
       sist 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 ttrruuee if currently defined, ffaallssee if not; thus:

            ifdef A | B | C

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

            ifdef A & B & C

       ...is ttrruuee if they all are.  Note that iiffnnddeeff <<eexxpprr>> is equivalent to
       iiffddeeff !!(( <<eexxpprr>> ))..



   TThhee MMoooonn FFiillee
       If a file of the name _._m_o_o_n_#_# (_m_o_o_n_#_#_._d_a_t under MS-DOS), where #### is
       the last two digits of the calendar year, exists in the same directory
       as the date file (or in the directory where _p_c_a_l resides), _p_c_a_l uses
       the information contained within to calculate the phase of the moon.
       If a) no such file exists, b) the --ee flag (do not use a date file) is
       specified, or c) the --zz flag (specify time zone) is specified, then
       _p_c_a_l uses an algorithm to calculate the phase of the moon.

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

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

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

       If the --EE 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, _p_c_a_l 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 oopptt --AA or oopptt --EE line to spec-
       ify 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.

   GGeenneerraattiinngg PPoossttSSccrriipptt CCaalleennddaarrss VViiaa AA WWeebb BBrroowwsseerr IInntteerrffaaccee
       PostScript-format _p_c_a_l calendars can be generated and viewed from a web
       browser interface.

              NNoottee:: This is not to be confused with the ability to generate
              non-PostScript, HTML-format (using the --HH command-line option)
              calendars, which is a different capability entirely.

       _P_c_a_l 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 _`_p_c_a_l_=_' (Bourne shell script) or
       _`_m_y _$_P_C_A_L _=_' (Perl script) to point to the location of the _p_c_a_l exe-
       cutable file.  Change the definition for _`_f_i_l_e_=_' (Bourne shell script)
       or _`_m_y _$_F_I_L_E _=_' (Perl script) to point to the location of the _p_c_a_l
       `date file' (e.g. `.calendar'), which contains the options for running
       _p_c_a_l.  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:

              <FORM ACTION="http://yourpath/cgi-bin/pcal.cgi" METHOD=GET>

       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.

              NNoottee:: Depending upon what application your web browser spawns to
              preview PostScript content, the monthly calendars generated via
              this web browser interface may not show any embedded EPS images.
              For a rundown of some popular PostScript-viewing applications
              and whether they correctly display the embedded EPS images, see
              the section (above) entitled `Encapsulated PostScript (EPS)
              Images'.

OOPPTTIIOONNSS
       --ee     Prints an empty calendar.  Do not print entries from a _._c_a_l_e_n_d_a_r
              file even if one exists.

       --ff _c_a_l Directs _p_c_a_l to use the file name _c_a_l as the input file in place
              of the default _._c_a_l_e_n_d_a_r file.  Note that the search rules are
              different when --ff is used.  If _c_a_l is an absolute file name
              (i.e. starting with a `/'), then _p_c_a_l attempts to open only that
              file.  Otherwise, _p_c_a_l looks for _c_a_l in the current directory,
              then in the directory indicated by the environment variable
              PPCCAALL__DDIIRR (if defined), and finally, if enabled (via the
              `SEARCH_PCAL_DIR' flag) when _p_c_a_l was built, in the directory
              where the _p_c_a_l executable resides.  If the given _c_a_l file is not
              found, an error results.

       --oo _f_i_l_e
              Directs _p_c_a_l to write the output to _f_i_l_e instead of to stdout.

       --ll     Causes the output to be in landscape mode (default).

              _P_c_a_l predefines the symbol `ORIENTATION_LANDSCAPE' whenever
              `landscape' page orientation is enabled.  This can be useful for
              providing alternate values in the configuration file for EPS
              image placement and scaling, based on the page orientation.


       --pp     Causes the output to be in portrait mode.

              _P_c_a_l predefines the symbol `ORIENTATION_PORTRAIT' whenever `por-
              trait' page orientation is enabled.  This can be useful for pro-
              viding alternate values in the configuration file for EPS image
              placement and scaling, based on the page orientation.


       --PP     Selects the paper size.  The following sizes are supported:

                     +o letter -- 8.5 x 11.0 inches

                     +o legal -- 8.5 x 14.0 inches

                     +o a4 -- 210 x 297 mm

                     +o tabloid -- 11.0 x 17.0 inches

              _P_c_a_l predefines one of the following symbols based on the cur-
              rent paper size:

                     +o PAPERSIZE_LETTER

                     +o PAPERSIZE_LEGAL

                     +o PAPERSIZE_A4

                     +o PAPERSIZE_TABLOID

              These symbol definitions can be useful for providing alternate
              values in the configuration file for EPS image placement and
              scaling, based on paper size.

       --jj     Causes the Julian date (day of year) to be printed in each cal-
              endar box.

       --JJ     Causes the Julian date and the number of days remaining in the
              year to be printed in each calendar box.

       --mm     Causes moon icons to be printed on dates corresponding to new,
              half, and full moons (the default is that no moons are printed).

       --MM     Causes moon icons to be printed on all dates (the default is
              that no moons are printed).

       --gg _d_a_y_1[_-_d_a_y_2] || aallll || hhoolliiddaayy
              Causes all dates falling on weekday _d_a_y_1 (through _d_a_y_2 if speci-
              fied) to be printed in the `day numerics color' (i.e. the color
              specified by the --ss option [default = gray]); --gg aallll causes all
              weekdays (other than holidays) to be printed in the `day numer-
              ics color'; --gg hhoolliiddaayy causes all holidays to be printed in `day
              numerics color'.  _d_a_y_1 and _d_a_y_2 may wrap around weekends; for
              example, --gg ffrrii--ssuunn causes Fridays, Saturdays, and Sundays to be
              printed in the `day numerics color'.

       --OO _d_a_y_1[_-_d_a_y_2] || aallll || hhoolliiddaayy
              Similar to --gg, but the selected days will be printed as outlined
              characters, using the `day numerics color'.

       --GG _d_a_y_1[_-_d_a_y_2] || aallll || hhoolliiddaayy
              Similar to --gg, but the selected days will be printed in the `day
              numerics color', outlined in black.

       --bb _d_a_y_1[_-_d_a_y_2] || aallll || hhoolliiddaayy
              Similar to -- you guessed it -- --gg, but the selected days will
              be printed in black.  Since black is the default for weekdays,
              -b is primarily used to overriding other flags (e.g., --gg aallll --bb
              ssaatt--ssuunn ).

           NNoottee::
              The default for the above options is to print Saturdays, Sun-
              days, and holidays in the `day numerics color' and all other
              days in black.  For backward compatibility with earlier versions
              of _p_c_a_l, --OO and --GG alone change all non-black days to the speci-
              fied color.

       --ss _[_d_a_y___n_u_m_e_r_i_c_s___c_o_l_o_r_]_[_/_e_m_p_t_y___d_a_y___b_o_x___f_i_l_l___c_o_l_o_r_]
              Overrides the default value(s) for the color of the numerics for
              each day and/or the color of the fill used on boxes for 'empty'
              days.  NNoottee:: This option only applies to PostScript-format cal-
              endars, not to HTML-format calendars.  These values may be set
              independently of each other.  For use with non-color printers,
              these values should be in the range 0.0 (black) through 1.0
              (white).  The default values are 0.8 for day numerics and 0.9
              for empty day boxes.  For use with color printers, these values
              may optionally be specified as a set of _r_e_d:_g_r_e_e_n:_b_l_u_e (RGB)
              values, each of which must in the range 0.0 through 1.0.  At
              least one `:' must be present for these values to be recognized
              as RGB colors; omitted values are set to 0.0.

              This option may also be set semi-permanently by altering the
              makefile (`Makefile' for most environments, 'Makefile.DOS' for
              MS-DOS).

       --FF _d_a_y Selects weekday _d_a_y as the first day of the week.  The given day
              will appear in the left-most column of the calendar.  _d_a_y may be
              specified either as a weekday name or, optionally, as a number
              in the range 0 (Sunday) through 6 (Saturday).

              This option may also be set semi-permanently by altering the
              makefile (`Makefile' for most environments, 'Makefile.DOS' for
              MS-DOS).

       --AA     Directs _p_c_a_l to use American date conventions ( mmmm//dddd{{//yyyy}} and
              mmoonntthh dddd ) when parsing the date file.  This is the default.

              This option may also be set semi-permanently by altering the
              makefile (`Makefile' for most environments, 'Makefile.DOS' for
              MS-DOS).

       --EE     Directs _p_c_a_l to use European date conventions ( dddd//mmmm{{//yyyy}} and
              dddd mmoonntthh ) when parsing the date file.

              This option may also be set semi-permanently by altering the
              makefile (`Makefile' for most environments, 'Makefile.DOS' for
              MS-DOS).

       --XX _x_t_r_a_n_s
              Specifies the x-axis translation value for positioning the out-
              put on the page.  Positive values shift the output to the right.
              Negative values shift the output to the left.

       --YY _y_t_r_a_n_s
              Specifies the y-axis translation value for positioning the out-
              put on the page.  Positive values shift the output up.  Negative
              values shift the output down.

       --xx _x_s_c_a_l_e
              Specifies the x-axis scaling factor for the calendar size.

       --yy _y_s_c_a_l_e
              Specifies the y-axis scaling factor for the calendar size.

       --tt [_t_i_t_l_e___f_o_n_t][//_s_i_z_e]
              Specifies the name of a font to use for all the calendar heading
              text:

                     +o the month name and year at the top of the calendar (for
                       monthly-format calendars) or at the top of each month
                       (for yearly-format calendars and for the small previ-
                       ous/next-month calendars [if enabled] on monthly-format
                       calendars)

                     +o the day-of-week names

                     +o the footer strings (if any)

                     +o the ``Notes'' box heading (if any; for monthly calen-
                       dars only)

              For monthly calendars only, the user may optionally specify the
              font size, which applies only to the main month/year heading.
              For example, ppccaall --tt TTiimmeess--RRoommaann//5544 sets the font to Times-Roman
              and the month/year point size to 54.  The font size may also be
              changed independently: ppccaall --tt //5544 changes the point size to 54
              without affecting the font name.

              Note: For yearly calendars, any specification of font _s_i_z_e is
              ignored.

              This option may also be set semi-permanently by altering the
              makefile (`Makefile' for most environments, 'Makefile.DOS' for
              MS-DOS).

       --dd [_d_a_t_e___f_o_n_t][//_s_i_z_e]
              Similar to the --tt option, but selects the font and/or size used
              for the day numerics (the numbers inside the box for each day).

              Note: For yearly calendars, any specification of font _s_i_z_e is
              ignored.

              This option may also be set semi-permanently by altering the
              makefile (`Makefile' for most environments, 'Makefile.DOS' for
              MS-DOS).

       --nn [_t_e_x_t___f_o_n_t][//_s_i_z_e]
              Similar to the --tt and --dd options, but selects the font and/or
              size used for any `event' text associated with each day and for
              any text in the monthly ``Notes'' box.

              Note: This option applies to monthly calendars only. For yearly
              calendars, this option does not apply.

              This option may also be set semi-permanently by altering the
              makefile (`Makefile' for most environments, 'Makefile.DOS' for
              MS-DOS).

       --LL _s_t_r_i_n_g
              Causes the accompanying string to be printed as a left-justified
              footer.  Format specifiers denoting the month and/or year may
              appear in the string; the appropriate values will be substituted
              upon printing.

       --CC _s_t_r_i_n_g
              Similar to --LL, but causes the accompanying string to be printed
              as a centered footer.  If the --HH flag (generate calendar as HTML
              table) was specified, this string will be used as the title and
              heading.

       --RR _s_t_r_i_n_g
              Similar to --LL, but causes the accompanying string to be printed
              as a right-justified footer.

       --NN _s_t_r_i_n_g
              Causes the accompanying string to be printed as the heading for
              the "Notes" box.  Note, however, that _p_c_a_l makes no attempt to
              ensure that it fits.

       --DD _s_y_m_b_o_l _[_v_a_l_u_e_]
              Defines the named symbol and an optional value to be associated
              with that symbol, prior to reading the date file.

       --UU _s_y_m_b_o_l
              Un-defines the named symbol prior to reading the date file.

       --BB     Causes _p_c_a_l to leave unused calendar day boxes blank as opposed
              to the default behavior of filling them using the `empty day-box
              fill color' (i.e. the color specified by the --ss option [default
              = gray]).

       --## _n   Causes _p_c_a_l to print _n copies (maximum: 100) of each output
              page.

       --SS     Causes _p_c_a_l to suppress printing the small calendars.  See the
              CCAAVVEEAATTSS section for further details.

       --kk     Causes _p_c_a_l to print the small calendars in the upper left cor-
              ner (the default is to print them at the lower right).

       --KK     Causes _p_c_a_l to print the small calendar for the previous month
              in the upper left corner and the next month in the lower right
              (the default is to print both at the lower right).

       --ww     Causes _p_c_a_l to print a calendar for 12 consecutive months: 3
              rows / 4 columns in landscape mode, 4 rows / 3 columns in por-
              trait mode.  See the CCAAVVEEAATTSS section for details on the use of
              this option with other options.

              Pcal predefines the symbol wwhhoollee__yyeeaarr when the --ww flag is in
              effect, allowing directives like `iiffddeeff wwhhoollee__yyeeaarr' in the con-
              figuration file.

       --II     Resets all parameters to the program defaults.

       --cc     Causes _p_c_a_l to generate a date file suitable for use as input to
              the Un*x _c_a_l_e_n_d_a_r_(_1_) utility.  The normal PostScript output is
              suppressed.

       --HH     Causes _p_c_a_l to generate a calendar in HTML table format.  The
              normal PostScript output is suppressed.

              The HTML table format does not support moon graphics, Julian
              date information, `day numerics' color, `empty day' `box fill'
              color, left or right footer strings (but see the --CC flag),
              alternate fonts/sizes, transformation and scaling factors, or
              embedded EPS images.

       --qq     This option is only valid when used in conjunction with the --HH
              (generate HTML-format calendar) option.  It generates a yearly-
              planner style of HTML calendar whereby a single column for each
              month is used, resulting in table that gives a quicker overview
              of several months.  Since there is less space for text, only the
              first character of the weekday and the first 5 characters of
              text from each event for that day are printed. The day numerics
              for holidays are colored red but the text of the holiday event
              is not printed.  The day numerics are grey for Saturdays and
              bold black for Sundays.

       --zz _t_i_m_e___z_o_n_e
              Forces _p_c_a_l to ignore the moon file and to use its internal
              algorithm for moon phase calculations, adjusting the phase by
              _t_i_m_e___z_o_n_e hours (where _t_i_m_e___z_o_n_e is expressed in hours west of
              UTC).

              For example, New York residents (USA Eastern time zone) would
              use '-z 5' while on Eastern Standard Time (winter) and '-z 4'
              while on Eastern Daylight Time (summer).  People in India would
              use '-z-5.5'.  Notice that fractional values are allowed.

              This option may also be set semi-permanently by altering the
              makefile (`Makefile' for most environments, 'Makefile.DOS' for
              MS-DOS).

       --hh     Causes _p_c_a_l to write version information, parameter usage mes-
              sage, and full explanation of options and file formats (to _s_t_d_-
              _o_u_t) and terminate.

       --uu     Causes _p_c_a_l to write version information and parameter usage
              message (to _s_t_d_o_u_t) and terminate.

       --vv     Causes _p_c_a_l to write version information only (to _s_t_d_o_u_t) and
              terminate.

              Pcal predefines the symbol vvXX__YY__ZZ, where XX__YY__ZZ denotes the cur-
              rent version of Pcal (e.g. version 4.9.0 predefines the symbol
              vv44__99__00).

       --aa _o_u_t_p_u_t___l_a_n_g_u_a_g_e
              Select the output language (for the names of months and days on
              the calendar).

              Currently, the following languages are supported: ccaa (Catalan),
              ccss (Czech), ddaa (Danish), ddee (German), eell (Greek), eenn (English),
              eeoo (Esperanto), eess (Spanish), eett (Estonian), ffii (Finnish), ffrr
              (French), hhaa (Hawaiian), hhuu (Hungarian), iitt (Italian), lltt
              (Lithuanian), llvv (Latvian), nnll (Dutch), ppll (Polish), pptt (Por-
              tuguese), rroo (Romanian), rruu (Russian), sskk (Slovak), ssvv
              (Swedish), and uukk (Ukrainian).  The default is eenn.

              Note that this option does nnoott specify the `input language',
              which is the language used to process events in the configura-
              tion file ('English', by default, unless changed with the _i_n_p_u_t_-
              _l_a_n_g_u_a_g_e _X_X directive).  See the section _T_h_e _D_a_t_e _F_i_l_e for more
              details on specifying the `input language'.

              NNoottee:: In order to display diacritical marks, languages other
              than English require that the characters be remapped.  Normally,
              no action is required since _p_c_a_l automatically selects a remap-
              ping which is appropriate to the selected language.  However, if
              you want to override the default remapping for a given language,
              you would use the --rr option (e.g. "-r Latin1").

              Furthermore, an appropriate font should be selected as needed
              using the --tt option (e.g. "-t some-latin1-font-name").  Any lan-
              guage using the "Latin1" remapping (e.g. French, German, Ital-
              ian, Spanish, etc) requires an ISO 8859-1 ('Latin1') font.  The
              Greek language requires an ISO 8859-7 (similar to ELOT-928) font
              (available from Angelo Haritsis <ah@doc.ic.ac.uk>; also see
              http://www.hellenic.net/fonts/).  Similarly, Russian requires a
              KOI8-R font while Ukrainian requires a KOI8-U font.

              _P_c_a_l predefines the symbol llaanngg__XXXX, where XXXX is the two-charac-
              ter abbreviation for the selected output language.

       --rr [_m_a_p_p_i_n_g]
              Specifies an 8-bit character set remapping (encoding) for print-
              ing the diacritical marks common to European languages.

              Note: This option is not usually needed since _p_c_a_l will automat-
              ically select an appropriate default character encoding (map-
              ping) for the language for which the calendar is being gener-
              ated.

              The value specified for _m_a_p_p_i_n_g is case-insensitive and may be
              abbreviated to the point where it is still unique.  The value
              used may be any of the following:

                     +o "none" (use built-in character set)

                     +o "Latin1" (ISO 8859-1)

                     +o "Latin2" (ISO 8859-2)

                     +o "Latin3" (ISO 8859-3)

                     +o "Latin4" (ISO 8859-4)

                     +o "Cyrillic" (ISO 8859-5)

                     +o "Greek" (ISO 8859-7)

                     +o "Latin5" (ISO 8859-9)

                     +o "Latin6" (ISO 8859-10)

                     +o "Thai" (ISO 8859-11)

                     +o "Latin7" (ISO 8859-13)

                     +o "Latin8" (ISO 8859-14)

                     +o "Latin9" (ISO 8859-15)

                     +o "KOI8-R" (Russian)

                     +o "KOI8-U" (Ukrainian)

                     +o "Roman8"

              This option may also be set semi-permanently by altering the
              makefile (`Makefile' for most environments, 'Makefile.DOS' for
              MS-DOS).


       --TT [B|I|R]
              Select the default typeface (Bold, Italic, or Roman) for print-
              ing date/note text.  This flag may be specified multiple times
              within the date file (via "opt") to reset the font style on the
              fly -- for example, to print all holidays in Bold.


       --WW [left|center|right]
              Specify the horizontal alignment of the month/year heading
              (left, center, right) (for monthly-format calendars only).


       Any option taking a negative value (e.g.  --YY --######) should be specified
       with no space between the option and the (negative) value to avoid _p_c_a_l
       interpreting the value as an illegal flag and aborting.  For example,
       use ` _-_Y_-_5_0' instead of ` _-_Y _-_5_0' on your option specification.

       Any option (except --GG and --OO, for backward-compatibility) which nor-
       mally takes an argument may be specified without the argument in order
       to reset the value to the program default.  Note that while the --DD
       option alone clears all the defined symbols, the --UU option alone has no
       effect.  The -- (or ---- as per System V) argument may be used to disam-
       biguate command lines such as:

              ppccaall --tt 99 9900

       This could be written instead as one of the following:

              ppccaall --tt -- 99 9900
              ppccaall --tt ---- 99 9900

       If the environment variable PPCCAALL__OOPPTTSS is defined, its contents are
       parsed as a command line.  Flags set via PPCCAALL__OOPPTTSS override the program
       defaults, but are overridden by options set via oopptt lines in the con-
       figuration file or explicitly on the command line.



   AAddddiittiioonnaall OOppttiioonnss FFoorr DDeebbuuggggiinngg OOnnllyy
       The --ZZ flag is used to print debugging information which is of interest
       primarily to _p_c_a_l hackers.  This flag is a "hidden" flag; it does not
       appear as part of the usage message.  At present, the following options
       are supported:

              +o -ZD  print dates and text as read from date file

              +o -ZF  print date file search paths

              +o -ZM  print moon phases and identify quarters

              +o -ZO  print option flags and where set

              +o -ZP  print "preprocessor" debug info

              +o -ZT  print dates and text as written to output file

              +o -Z   turn off all debugging info

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



CCAAVVEEAATTSS
       +o The ``workday'' and ``holiday'' keywords are aware of only those hol-
         idays which have already been flagged at the point where they appear.
         For example, consider January 1990:

                          January 1990
                       S  M Tu  W Th  F  S
                          1  2  3  4  5  6
                       7  8  9 10 11 12 13
                      14 15 16 17 18 19 20
                      21 22 23 24 25 26 27
                      28 29 30 31

         If the configuration file looked like this:

            workday on_or_before all 15   payday
            3rd Mon in Jan*               MLK day

         ... then _p_c_a_l would mark the 15th as ``payday'' since at that point
         in the configuration file it has no way of knowing that January 15th
         will later be flagged as a holiday.  If the two lines were reversed,
         such that the holiday preceded the ``workday'' wildcard, then _p_c_a_l
         would work as intended, marking instead the 12th as ``payday''.

         Also, beware of year boundaries which affect the handling of all of
         the day wildcard keywords.  In general, it is best to place monthly
         wildcards such as the example above at the end of each year to
         achieve the desired effect.

       +o Only the positive ordinals may be used in conjunction with preposi-
         tions (e.g. "fourth Sunday before 12/25").  (It could be argued that
         "last Sunday before 12/25" should be accepted as a synonym for "first
         Sunday before 12/25", but then what does "last Sunday after 12/25"
         mean?)

       +o When the --ww and --pp options are used together, _p_c_a_l revises the y-
         scale factor in order to use the entire portrait page; therefore, the
         user should avoid using use the --yy option when using both the --ww and
         --pp options.  Use of the --ww option in any case effectively disables
         the --mm, --MM, --jj, and --JJ options.

       +o The output of the --cc option may be used as input to subsequent runs
         of _p_c_a_l.  Note, however, that oopptt lines (except for an automatic oopptt
         --[[AA||EE]]), comments, ``note'' text, and iiffddeeff'd-out source will be
         lost.

       +o The --SS option interacts with nnoottee{{//<<nnuummbbeerr>>}}; if used, it should be
         specified either on the command line or prior to the first nnoottee line
         in the date file.

SSEEEE AALLSSOO
       Website for _p_c_a_l and _l_c_a_l (a lunar calendar generation application):

              http://pcal.sourceforge.net

       cal(1), calendar(1).

       The old, simple Unix/BSD 'calendar' program, which can be used with
       _p_c_a_l and the '-c' option is part of the BSD Main Utilities ('bsdmainu-
       tils') package and is available at the Debian site:

              _h_t_t_p_:_/_/_p_a_c_k_a_g_e_s_._d_e_b_i_a_n_._o_r_g_/_s_t_a_b_l_e_/_s_o_u_r_c_e_/_b_s_d_m_a_i_n_u_t_i_l_s

       This old program does not seem to be included with most GNU/Linux dis-
       tributions these days.

       For more information on PostScript, consult the free, online Adobe book
       entitled _P_o_s_t_S_c_r_i_p_t _L_a_n_g_u_a_g_e _R_e_f_e_r_e_n_c_e _M_a_n_u_a_l, which can be found here
       (as of Dec 2007):

              _h_t_t_p_:_/_/_p_a_r_t_n_e_r_s_._a_d_o_b_e_._c_o_m_/_p_u_b_l_i_c_/_d_e_v_e_l_o_p_e_r_/_p_s_/_i_n_d_e_x___s_p_e_c_s_._h_t_m_l

AAUUTTHHOORRSS
       The original PostScript code to generate the calendars was written by
       Patrick Wood (Copyright (C) 1987 by Patrick Wood of Pipeline Asso-
       ciates, Inc.), and authorized for modification and redistribution.  The
       calendar file inclusion code was originally written in "bs(1)" by Bill
       Vogel of AT&T.  Patrick's original PostScript was modified and enhanced
       several times by King Ables, Tim Tessin, Joe Wood, Jeff Mogul, Mark
       Hanson, and others whose names have regrettably been lost.  This C ver-
       sion was originally created by Ken Keirnan of Pacific Bell; additional
       enhancements by Joseph P. Larson, Ed Hand, Andrew Rogers, Mark
       Kantrowitz, Joe Brownlee, Andy Fyfe, Steve Grandi, Geoff Kuenning, Ste-
       fan Fronzek (1-column HTML output), Bill Bogstad (event deletion capa-
       bility), and Bill Marr (embedded EPS images, command-line paper size
       specification, new paper sizes [legal & tabloid], additional character
       mappings for new languages, and various cleanups).  The moon routines
       were originally written by Jef Poskanzer and Craig Leres, and were
       incorporated into _p_c_a_l by Richard Dyson.  International language sup-
       port was initially added by Angelo Haritsis.  Additional languages were
       added by Andrew Rogers (Esperanto), Lars Wirzenius (Finnish), Pedro
       Zorzenon Neto (Portuguese), Joel Fredrikson (Swedish), Volodymyr M.
       Lisivka (Ukrainian), Neeme Praks (Estonian, Russian, Latvian, Lithua-
       nian), Peter Cernoch (Czech), Ferenc Kruzslicz (Hungarian), Carles
       Sadurn Anguita (Catalan), Dominik 'Chiron' Derlatka (Polish), Ewald
       Beekman (Dutch), Claudiu Costin (Romanian), Kenneth Geisshirt (Danish),
       Zdenko Podobny (Slovak), and Eric Nichols (Hawaiian).



Version 4.11.0                    18 Dec 2007                          PCAL(1)
