PCAL(1)                   USER COMMANDS                   PCAL(1)



NNAAMMEE
       pcal - generate PostScript (or HTML) calendars

SSYYNNOOPPSSIISS
       ppccaall [--ee|--ff _c_a_l] [--oo _f_i_l_e] [--ll | --pp] [--PP [letter | legal |
            a4 | tabloid]] [--jj | --JJ] [--mm | --MM] [--gg _w_e_e_k_d_a_y[_-_w_e_e_k_-
            _d_a_y]|all|holiday] [--OO _w_e_e_k_d_a_y[_-_w_e_e_k_d_a_y]|all|holiday]
            [--GG _w_e_e_k_d_a_y[_-_w_e_e_k_d_a_y]|all|holiday] [--bb _w_e_e_k_d_a_y[_-_w_e_e_k_-
            _d_a_y]|all|holiday] [--ss [_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]] [--FF _d_a_y]
            [--AA|--EE] [--XX _x_t_r_a_n_s] [--YY _y_t_r_a_n_s] [--xx _x_s_c_a_l_e]
            [--yy _y_s_c_a_l_e] [--tt [_t_i_t_l_e___f_o_n_t][/_s_i_z_e]]
            [--dd [_d_a_y___f_o_n_t][/_s_i_z_e]] [--nn [_t_e_x_t___f_o_n_t][/_s_i_z_e]]
            [--LL _f_o_o_t_e_r___s_t_r] [--CC _f_o_o_t_e_r___s_t_r] [--RR _f_o_o_t_e_r___s_t_r]
            [--NN _n_o_t_e_s___s_t_r] [--DD _s_y_m_b_o_l] [--UU _s_y_m_b_o_l] [--BB] [--## _n]
            [--SS | --kk | --KK] [--ww] [--II] [--cc | --HH] [--qq]
            [--zz _t_i_m_e___z_o_n_e] [--hh | --uu | --vv] [--aa _o_u_t_p_u_t___l_a_n_g_u_a_g_e]
            [--rr [_m_a_p_p_i_n_g] [--TT [B|I|R]] [month] [year] [nmonths]



DDEESSCCRRIIPPTTIIOONN
       _P_c_a_l generates PostScript to produce landscape or portrait
       calendars for any month and year.  The arguments mmoonntthh,
       yyeeaarr, and nnmmoonntthhss, if provided, should be numeric.  The
       mmoonntthh value should be in the range 1 - 12, and the yyeeaarr
       value should be specified as 1 or 2 digits or as the full
       4-digit year.  If no numeric arguments are provided, the
       calendar for the current month and year will be generated.

       If one numeric argument is provided, it is interpreted as
       the yyeeaarr value, and calendars for the entire year will be
       generated.  Otherwise, nnmmoonntthhss months, starting with mmoonntthh
       and yyeeaarr, will be generated.

       For whole-year calendars (i.e. when the --ww option is
       given), the command line arguments are interpreted some-
       what differently.  By default, all months in the current
       year are printed, starting with January.  If the mmoonntthh
       argument alone is given, it is expected to be the desired
       yyeeaarr to print, and prints all of the months in the given
       year.  If both mmoonntthh and yyeeaarr are given, then 12 consecu-
       tive months are printed starting at the given month and
       year.  If the mmoonntthh, yyeeaarr, and nnmmoonntthhss arguments are all
       present, printing begins with the given month and year and
       nnmmoonntthhss months are printed, rounded up to the nearest mul-
       tiple of 12.



   TThhee DDaattee FFiillee
       By default, _p_c_a_l simply prints an empty calendar.  Its
       real power is in its ability to place ``events'' (and, for
       monthly PostScript calendars, Encapsulated PostScript
       images [e.g. photos and icons]) in appropriate days on the
       calendar, thus allowing the user to create personalized
       calendars.  This is achieved through the use of the ``date
       file''.

       The date file is 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 versions.  _P_c_a_l
       will look in several places for such a file.  First, if
       the environment variable PPCCAALL__DDIIRR is defined, _p_c_a_l
       searches the directory indicated by that variable.  Next,
       _p_c_a_l searches the user's home directory (as specified by
       the HHOOMMEE environment variable).  If neither PPCCAALL__DDIIRR nor
       HHOOMMEE is defined, _p_c_a_l searches the current directory
       instead.  Finally, unless inhibited (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
       --ff command-line option.  See the OOPPTTIIOONNSS section for more
       details.

       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.  Encapsu-
       lated PostScript (EPS) images are handled similarly as
       described in a later subsection.

       ttrrooffff-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 famil-
       iar with HTML, <B>, <I>, and </B> or </I> may be used
       instead to set the font style to Bold, Italic, or the pre-
       vious font style respectively.  The font style is reset to
       Roman after each line break.

       Dates in the _._c_a_l_e_n_d_a_r file 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''

                             NNoottee:: _p_c_a_l looks for names of the
                             days of the week prior to names of
                             months when parsing event date spec-
                             ifications.  Furthermore, some lan-
                             guages (e.g. French and Finnish)
                             have a month name whose first 3 let-
                             ters 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 `col-
                             lides'.

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

            <day_spec>       := first 3+ characters of name of
                             weekday, ``day'', ``weekday'',
                             ``workday'', ``holiday'', ``nonweek-
                             day'', ``nonworkday'', ``nonholi-
                             day'', ``new_moon'', ``first_quar-
                             ter'', ``full_moon'', or
                             ``last_quarter''

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

            <prep>           := ``before'', ``preceding'',
                             ``after'', ``following'',
                             ``on_or_before'' (``oob''),
                             ``on_or_after'' (``ooa''), ``near-
                             est'', ``nearest_before``, or
                             ``nearest_after``

            <pre_defined_event>
                             := ``Christmas'', ``Thanksgiving'',
                             ``Easter'', ``Good_Friday'',
                             ``GEaster'' (Orthodox Easter),
                             ``Gstgeorge'' (Orthodox holiday),
                             ``Gmarcus'' (Orthodox holiday), and
                             ``F13'' (Friday the 13th, for the
                             superstitious among us).

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

            <month>          := a numeric month (1-12)

            <day>            := day of month (1-31)

            <year>           := a numeric year

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

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


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

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


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


       The ``Notes'' box (see below) uses the first of the cur-
       rent 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

            F13                   Avoid black cats!   # 'Friday the 13th'

       Any non-numeric character may separate numeric dates.
       Holidays may be flagged by following the date immediately
       with `*' as in the examples above; this will cause the
       date numerics to be printed in the color specified by the
       --s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'', respec-
       tively.  ``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 ``week-
       day'' applies to any days which are normally printed in
       "logical black" - the predominant day color - on the cal-
       endar.  The keyword ``workday'' is the same, but does not
       include any holidays.  The keyword ``holiday'' includes
       only those days flagged as holidays.  The keywords ``non-
       weekday'', ``nonworkday'', and ``nonholiday'' are also
       recognized as negations of the above.  See the CCAAVVEEAATTSS
       below for important notes on using these keywords.  Moon
       phases may also appear as wildcards; ``nm'' is accepted as
       a synonym for ``new_moon'', ``1q'' and ``fq'' for
       ``first_quarter'', ``fm'' for ``full_moon'', ``3q'' for
       ``third_quarter'', and ``lq'' for ``last_quarter''.

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

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

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

       ``Nearest'', ``nearest_before'', and ``nearest_after''
       refer to the nearest weekday or wildcard day with respect
       to the specified date.  ``Nearest_before'' and ``near-
       est_after'' allow the user to specify how _p_c_a_l is to dis-
       ambiguate 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 `\' followed by a character, 1 - 3 octal digits,
       or `x' followed by 1 - 2 hexadecimal digits).  Escaped
       whitespace (including nneewwlliinnee ) and the standard ANSI
       character escapes (`\a', `\b', `\f', `\n', `\r', `\t',
       `\v') are all replaced by a single blank.

       The HTML special characters `&lt;' `&gt;' `&quot;' `&amp;'
       `&nbsp;' and `&#NNN;' (NNN = any three decimal digits) are
       also supported.  These will be propagated intact (be sure
       to escape the `#' in `&#NNN;') if the output is specified
       as HTML (see the --HH flag); otherwise they will be con-
       verted 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 --cc flag) input.

       Lines in the _._c_a_l_e_n_d_a_r file consisting of yyeeaarr ######## (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 _._c_a_l_e_n_d_a_r file consisting of yyeeaarr aallll (or,
       alternatively, yyeeaarr **) direct _p_c_a_l 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 yyeeaarr
       ######## entry) will set the remembered year to that year.

       Lines in the _._c_a_l_e_n_d_a_r file consisting of oopptt <<ooppttiioonnss>>
       can be used to override the defaults for any command-line
       options except --cc, --ee, --ff, --hh, --HH, --uu, --vv, --DD, and --UU.
       Any options specified in this manner are, in turn, over-
       ridden by those specified explicitly on the command line.

       Lines in the _._c_a_l_e_n_d_a_r file consisting of nnoottee{{//<<nnuummbbeerr>>}}
       <<mmoonntthh>> can be used to place notes regarding the entire
       month in one of the unused blocks of the calendar.  The
       <<mmoonntthh>> 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.  <<nnuummbbeerr>> is an optional posi-
       tive or negative 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, ````nnoottee//11'''' places
       the associated text in the first empty box; nnoottee//--33 in the
       third-to-last.  The default is -1 if no <number> is given
       (last empty box, immediately preceding the small calendars
       on the bottom row; cf.  --SS, --kk, and --KK, below).  You can
       place several notes in the same box.  You can also use
       more than 1 box for the various monthly notes.

       Lines in the _._c_a_l_e_n_d_a_r file consisting of iinnppuutt--llaanngguuaaggee
       XXXX (where XXXX 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 'out-
       put language' as accomplished with the --aa option.

       Comments are supported in the _._c_a_l_e_n_d_a_r file.  Any charac-
       ters following a `#' character are ignored, through the
       end of that line, unless the `#' character is escaped by
       `\'.



   FFoorrmmaatt SSppeecciiffiieerrss
       _P_c_a_l allows format specifiers in both the event text and
       footer strings (see the --LL, --CC, --RR, and --NN options below).
       Each format specifier will be replaced by a corresponding
       string as outlined in the following table:

            %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() func-
       tion, but the %%[[lloouuwwMMDD]] and %%[[oo00++--]] format specifiers are
       specific to _p_c_a_l.

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

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

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

       The %%++ and %%-- format specifiers direct _p_c_a_l to substitute
       the following/previous month/year in the following [[bbBBmmyyYY]]
       specifier.  For example, %%++BB prints the name of the next
       month.

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

       Such date adjustments are normally cumulative; for exam-
       ple, %%++11YY%%--11DD adjusts the date forward by one year and
       then backward by one day.  If %%DD or %%MM is specified alone
       (or if NN is zero), _p_c_a_l restores the original date.  Note
       that %%MM 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 work-
       ing dates and the ability to display ordinals.  This par-
       ticular 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 dis-
       played on May 10, 2005:


              Eric's 14th Birthday




   EEnnccaappssuullaatteedd PPoossttSSccrriipptt ((EEPPSS)) IImmaaggeess
       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 specifica-
       tions 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 sim-
       ple event text specification lines.  However, instead of
       specifying the text associated with the event, you instead
       specify the EPS image filename and some additional parame-
       ters 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 Encap-
                                   sulated PostScript image.
                                   NNoottee:: The EPS image filename
                                   must be preceded by the con-
                                   stant text `image:' in order
                                   to distinguish an EPS image
                                   specification from an ordinary
                                   event text specification.

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

            <y-scale>              is a scaling factor in the
                                   vertical dimension for the EPS
                                   image.  Values between 0.0 and
                                   1.0 shrink the image in the
                                   vertical dimension while val-
                                   ues over 1.0 expand the image
                                   in the vertical dimension.
                                   Note that a negative value for
                                   this parameter can be useful
                                   in the less-than-rare case
                                   that you find that your EPS
                                   image needs to be flipped
                                   about the horizontal axis
                                   (i.e. top to bottom).  In such
                                   cases, you can use a negative
                                   <y-scale> value to achieve
                                   this without having to tweak
                                   the actual PostScript content
                                   within the EPS image file.
                                   Use of a negative value will
                                   undoubtedly necessitate a cor-
                                   responding 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 val-
                                   ues 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 asso-
       ciates 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 Wash-
       ington and Abraham Lincoln on the day of the U.S. ``Presi-
       dents' Day'' holiday, along with the event text:

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

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

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

       NNoottee:: Unfortunately, most EPS images cannot be used
       directly by _p_c_a_l.  In order to make an EPS image usable,
       you will have to (as an absolute minimum) remove or com-
       ment out the PostScript `showpage' command near the end of
       the EPS image file.  If you fail to do this, the calendar
       will be printed immediately (or displayed immediately, if
       previewing on-screen) after encountering the EPS image,
       prior to completion of the processing of the rest of the
       EPS images for that month!

       Furthermore, depending on the EPS image used and how it
       was created, you may also 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 PostScript commands in the EPS image file and/or
       the event entry in the _p_c_a_l date file.

              NNoottee:: 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 applica-
              tions and whether they correctly display the embed-
              ded 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 kghostview (versions 0.13.2 [KDE 3.1.4]
                       and 0.2.0 [KDE 3.2.3]) -- EPS images DO
                       NOT APPEAR!


       For converting non-EPS images (e.g. photos) to EPS format,
       one can use the graphical image manipulation program
       called `The Gimp':

              _h_t_t_p_:_/_/_w_w_w_._g_i_m_p_._o_r_g

       For icons in WMF format (which are popular in various 3rd-
       party, legacy-OS, commercial calendar programs), the `lib-
       wmf'/`wmf2eps' library/utility is useful for generating
       _p_c_a_l-capable EPS icons.  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

       NNoottee:: 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/setup 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 gener-
       ated 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
              -sOutputFile=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 support the display of embedded (by file-
       name only) EPS images.



   PPrree--PPrroocceessssoorr FFuunnccttiioonnaalliittyy
       _P_c_a_l supports rudimentary _c_p_p-like functionality in the
       date file, allowing the following constructs:


              +o ddeeffiinnee || uunnddeeff

              +o iiff{{{{nn}}ddeeff}} ...... {{eelliiff ......}}** {{eellssee ......}} eennddiiff

              +o iinncclluuddee

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

       Symbol names defined using these keywords (or via the --DD
       option) are case-insensitive.  It is not an error to uunnddeeff
       an undefined symbol, nor to ddeeffiinnee a previously-defined
       one.

       A symbol can be defined with just a name (e.g. ``define
       MY_SYM'') or it can take on a value (e.g. ``define MY_SYM
       SOME_VALUE'').  Use of symbol values is convenient for
       defining a starting date then using that symbol to refer-
       ence 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 `semester_start' symbol
       in the example above as merely `start', then you'd get the
       undesired effect of having the text `Class 8/23' in your
       calendar on that day instead of `Class Start'!  The use of
       `undef semester_start' in the above example is optional
       and is really only useful to prevent any unwanted symbol
       substitutions later on, which probably won't happen unless
       you poorly choose your symbol name to begin with.

       An iiffddeeff alone is always ffaallssee; an iiffnnddeeff alone is always
       ttrruuee.  iiff is accepted as a synonym for iiffddeeff.

       The name of the file in the iinncclluuddee directive may option-
       ally 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.  _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 iinncclluuddee directive does not exist.  An alternate form
       of the directive, iinncclluuddee??, 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 iiff{{{{nn}}ddeeff}} and eelliiff directives.
       These expressions consist of symbol names joined by the
       boolean operators !!, &&, ^^, and ||, in order of precedence,
       high to low.  Parentheses may be used to alter the prece-
       dence.  The synonyms &&&& and |||| are accepted for && and ||.
       A symbol name evaluates to ttrruuee if currently defined,
       ffaallssee if not; thus:

            ifdef A | B | C

       ...is ttrruuee if any of the symbols A, B, and C is defined,
       and:

            ifdef A & B & C

       ...is ttrruuee if they all are.  Note that iiffnnddeeff <<eexxpprr>> is
       equivalent to iiffddeeff !!(( <<eexxpprr>> ))..



   TThhee MMoooonn FFiillee
       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 --ee flag (do not use a date
       file) is specified, or c) the --zz 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 --AA option (American date formats, the default) is
       given:

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

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

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

       Where:

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

       This file must contain entries for all quarter moons in
       the year, in chronological order; if any errors are
       encountered, _p_c_a_l will revert to using its default algo-
       rithm.

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

       The moon file may optionally contain an oopptt --AA or oopptt --EE
       line to specify the format of its own date entries inde-
       pendently of the format used in the date file.  No other
       flags are legal in the moon file.




   GGeenneerraattiinngg PPoossttSSccrriipptt CCaalleennddaarrss VViiaa AA WWeebb BBrroowwsseerr IInntteerrffaaccee
       PostScript-format _p_c_a_l calendars can be generated and
       viewed from a web browser interface.

              NNoottee:: This is not to be confused with the ability
              to generate non-PostScript, HTML-format (using the
              --HH command-line option) calendars, which is a dif-
              ferent capability entirely.

       _P_c_a_l comes with 3 files that provide this ability:
       `pcal.cgi', `pcal.html', and `pcalw.html'.

       The CGI file must be edited before using it. Change the
       definition for _`_p_c_a_l_=_' to point to the location of the
       _p_c_a_l executable file.  Change the definition for _`_f_i_l_e_=_'
       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' 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 file.

       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.

              NNoottee:: 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) enti-
              tled `Encapsulated PostScript (EPS) Images'.




OOPPTTIIOONNSS
       --ee     Prints an empty calendar.  Do not print entries
              from a _._c_a_l_e_n_d_a_r file even if one exists.

       --ff _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 --ff 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 indi-
              cated by the environment variable PPCCAALL__DDIIRR (if
              defined), and finally, unless inhibited (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.

       --oo _f_i_l_e
              Directs _p_c_a_l to write the output to _f_i_l_e instead of
              to stdout.

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

       --pp     Causes the output to be in portrait mode.

       --PP     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


       --jj     Causes the Julian date (day of year) to be printed
              in each calendar box.

       --JJ     Causes the Julian date and the number of days
              remaining in the year to be printed in each calen-
              dar box.

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

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

       --gg _d_a_y_1[_-_d_a_y_2] || aallll || hhoolliiddaayy
              Causes all dates falling on weekday _d_a_y_1 (through
              _d_a_y_2 if specified) to be printed in the `day numer-
              ics color' (i.e. the color specified by the --ss
              option [default = gray]); --gg aallll causes all week-
              days (other than holidays) to be printed in the
              `day numerics color'; --gg hhoolliiddaayy causes all holi-
              days to be printed in `day numerics color'.  _d_a_y_1
              and _d_a_y_2 may wrap around weekends; for example, --gg
              ffrrii--ssuunn causes Fridays, Saturdays, and Sundays to
              be printed in the `day numerics color'.

       --OO _d_a_y_1[_-_d_a_y_2] || aallll || hhoolliiddaayy
              Similar to --gg, but the selected days will be
              printed as outlined characters, using the `day
              numerics color'.

       --GG _d_a_y_1[_-_d_a_y_2] || aallll || hhoolliiddaayy
              Similar to --gg, but the selected days will be
              printed in the `day numerics color', outlined in
              black.

       --bb _d_a_y_1[_-_d_a_y_2] || aallll || hhoolliiddaayy
              Similar to -- you guessed it -- --gg, 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., --gg aallll --bb
              ssaatt--ssuunn ).

           NNoottee::
              The default for the above options is to print Sat-
              urdays, Sundays, and holidays in the `day numerics
              color' and all other days in black.  For backward
              compatibility with earlier versions of _p_c_a_l, --OO and
              --GG alone change all non-black days to the specified
              color.

       --ss _[_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.  NNoottee:: This option
              only applies to PostScript-format calendars, 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 val-
              ues 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.

       --FF _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).

       --AA     Directs _p_c_a_l to use American date conventions (
              mmmm//dddd{{//yyyy}} and mmoonntthh dddd ) when parsing the date
              file.  This is the default.

       --EE     Directs _p_c_a_l to use European date conventions (
              dddd//mmmm{{//yyyy}} and dddd mmoonntthh ) when parsing the date
              file.

       --XX _x_t_r_a_n_s
              Specifies the x-axis translation value for posi-
              tioning the output on the page.  Positive values
              shift the output to the right.  Negative values
              shift the output to the left.

       --YY _y_t_r_a_n_s
              Specifies the y-axis translation value for posi-
              tioning the output on the page.  Positive values
              shift the output up.  Negative values shift the
              output down.

       --xx _x_s_c_a_l_e
              Specifies the x-axis scaling factor for the calen-
              dar size.

       --yy _y_s_c_a_l_e
              Specifies the y-axis scaling factor for the calen-
              dar size.

       --tt [_t_i_t_l_e___f_o_n_t][//_s_i_z_e]
              Specifies the name of a font to use to print all
              the calendar heading text: the month name and year
              at the top of the calendar, the weekday names, the
              notes box heading, and the footer strings.  The
              user may optionally specify the font size for the
              month/year heading (single-month calendar only);
              for example, ppccaall --tt TTiimmeess--RRoommaann//5544 sets the font
              to Times-Roman and the month/year point size to 54.
              The font size may also be changed independently:
              ppccaall --tt //5544 changes the point size to 54 without
              affecting the font name.

       --dd [_d_a_t_e___f_o_n_t][//_s_i_z_e]
              Similar to the --tt option, but selects the font
              and/or size used to print the dates.

       --nn [_t_e_x_t___f_o_n_t][//_s_i_z_e]
              Similar to the --tt and --dd options, but selects the
              font and/or size used to print the text associated
              with each day and in the monthly "Notes" blocks.

       --LL _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 print-
              ing.

       --CC _s_t_r_i_n_g
              Similar to --LL, but causes the accompanying string
              to be printed as a centered footer.  If the --HH flag
              (generate calendar as HTML table) was specified,
              this string will be used as the title and heading.

       --RR _s_t_r_i_n_g
              Similar to --LL, but causes the accompanying string
              to be printed as a right-justified footer.

       --NN _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.

       --DD _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.

       --UU _s_y_m_b_o_l
              Un-defines the named symbol prior to reading the
              date file.

       --BB     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 --ss option [default = gray]).

       --## _n   Causes _p_c_a_l to print _n copies (maximum: 100) of
              each output page.

       --SS     Causes _p_c_a_l to suppress printing the small calen-
              dars.  See the CCAAVVEEAATTSS section for further details.

       --kk     Causes _p_c_a_l to print the small calendars in the
              upper left corner (the default is to print them at
              the lower right).

       --KK     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).

       --ww     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 portrait mode.  See the CCAAVVEEAATTSS
              section for details on the use of this option with
              other options.

              Pcal predefines the symbol wwhhoollee__yyeeaarr when the --ww
              flag is in effect, allowing directives like `iiffddeeff
              wwhhoollee__yyeeaarr' in the configuration file.

       --II     Resets all parameters to the program defaults.

       --cc     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.

       --HH     Causes _p_c_a_l to generate a calendar in HTML table
              format.  The normal PostScript output is sup-
              pressed.

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

       --qq     This option is only valid when used in conjunction
              with the --HH (generate HTML-format calendar) option.
              It generates a yearly-planner style of HTML calen-
              dar 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 Sat-
              urdays and bold black for Sundays.

       --zz _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).

       --hh     Causes _p_c_a_l to write version information, parameter
              usage message, and full explanation of options and
              file formats (to _s_t_d_o_u_t) and terminate.

       --uu     Causes _p_c_a_l to write version information and param-
              eter usage message (to _s_t_d_o_u_t) and terminate.

       --vv     Causes _p_c_a_l to write version information only (to
              _s_t_d_o_u_t) and terminate.

              Pcal predefines the symbol vvXX__YY__ZZ, where XX__YY__ZZ
              denotes the current version of Pcal (e.g. version
              4.8.0 predefines the symbol vv44__88__00).

       --aa _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:
              ddee (German), eell (Greek), eenn (English), eeoo
              (Esperanto), eess (Spanish), eett (Estonian), ffii
              (Finnish), ffrr (French), iitt (Italian), lltt (Lithua-
              nian [experimental -- see `ReadMe.txt' file]), llvv
              (Latvian [experimental -- see `ReadMe.txt' file]),
              pptt (Portuguese), rruu (Russian [experimental -- see
              `ReadMe.txt' file]), ssvv (Swedish), and uukk
              (Ukrainian).  The default is eenn.

              Note that this option does nnoott specify the `input
              language', which is the language used to process
              events in the _._c_a_l_e_n_d_a_r (pcal configuration) 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'.

              NNoottee:: In order to display diacritical marks, lan-
              guages other than English require that the fonts be
              remapped (typically via the "Latin1" remapping).
              If no remapping is specified, _p_c_a_l selects a remap-
              ping appropriate to the selected language; note
              that the Greek language also requires an ELOT-928
              font (available from ah@doc.ic.ac.uk).  Also see
              the --rr and --tt options.

              If Esperanto is selected, _p_c_a_l converts [cghj-
              suCGHJSU][xX^] and [uU][xX~] to the corresponding
              accented character; e.g. "jxauxdo", "j^au~do", or
              any equivalent form will print as "j-circumflex a
              u-breve d o".

              _P_c_a_l predefines the symbol llaanngg__XXXX, where XXXX is the
              two-character abbreviation for the selected output
              language.

       --rr [_m_a_p_p_i_n_g]
              Specifies an 8-bit character set remapping for
              printing the diacritical marks common to European
              languages; _m_a_p_p_i_n_g may be "Roman8" (ROMAN-8
              extended character set), "Latin1" (ISO LATIN-1
              extended character set), or "none" (builtin 8-bit
              mappings only).  It may be abbreviated to a single
              character if desired.

       --TT [B|I|R]
              Select the default typeface (Bold, Italic, or
              Roman) for printing 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.

       Any option taking a negative value (e.g.  --YY --######) 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 --GG and --OO, for backward-compatibility)
       which normally takes an argument may be specified without
       the argument in order to reset the value to the program
       default.  Note that while the --DD option alone clears all
       the defined symbols, the --UU option alone has no effect.
       The -- (or ---- as per System V) argument may be used to dis-
       ambiguate command lines such as:

              ppccaall --tt 99 9900

       This could be written instead as one of the following:

              ppccaall --tt -- 99 9900
              ppccaall --tt ---- 99 9900

       If the environment variable PPCCAALL__OOPPTTSS is defined, its con-
       tents are parsed as a command line.  Flags set via
       PPCCAALL__OOPPTTSS override the program defaults, but are overrid-
       den by options set via oopptt lines in the _._c_a_l_e_n_d_a_r file or
       explicitly on the command line.



   AAddddiittiioonnaall OOppttiioonnss FFoorr DDeebbuuggggiinngg OOnnllyy
       The --ZZ 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 informa-
       tion is written to stderr.



CCAAVVEEAATTSS
       +o The ``workday'' and ``holiday'' keywords are aware of
         only those holidays which have already been flagged at
         the point where they appear.  For example, consider Jan-
         uary 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 _._c_a_l_e_n_d_a_r 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 _._c_a_l_e_n_d_a_r file it has no way of know-
         ing that January 15th will later be flagged as a holi-
         day.  If the two lines were reversed, such that the hol-
         iday preceded the ``workday'' wildcard, then _p_c_a_l would
         work as intended, marking instead the 12th as ``pay-
         day''.

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


       +o Only the positive ordinals may be used in conjunction
         with prepositions (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 --ww and --pp 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 --yy option when using both the --ww and --pp options.
         Use of the --ww option in any case effectively disables
         the --mm, --MM, --jj, and --JJ options.


       +o The output of the --cc option may be used as input to sub-
         sequent runs of _p_c_a_l.  Note, however, that oopptt lines
         (except for an automatic oopptt --[[AA||EE]]), comments, ``note''
         text, and iiffddeeff'd-out source will be lost.


       +o The --SS option interacts with nnoottee{{//<<nnuummbbeerr>>}}; if used,
         it should be specified either on the command line or
         prior to the first nnoottee line in the date file.




SSEEEE AALLSSOO
       cal(1), calendar(1).

       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 2004):

              _h_t_t_p_:_/_/_p_a_r_t_n_e_r_s_._a_d_o_b_e_._c_o_m_/_a_s_n_/_t_e_c_h_/_p_s_/_s_p_e_c_i_f_i_c_a_-
              _t_i_o_n_s_._j_s_p



AAUUTTHHOORRSS
       The original PostScript code to generate the calendars was
       written by Patrick Wood (Copyright (C) 1987 by Patrick
       Wood of Pipeline Associates, Inc.), and authorized for
       modification and redistribution.  The calendar file inclu-
       sion 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 version was originally cre-
       ated by Ken Keirnan of Pacific Bell; additional enhance-
       ments by Joseph P. Larson, Ed Hand, Andrew Rogers, Mark
       Kantrowitz, Joe Brownlee, Andy Fyfe, Steve Grandi, Geoff
       Kuenning, Stefan Fronzek (1-column HTML output), Don
       Laursen (`Friday the 13th' events), and Bill Marr (embed-
       ded EPS images, command-line paper size specification, and
       new paper sizes [legal & tabloid]).  The moon routines
       were originally written by Jef Poskanzer and Craig Leres,
       and were incorporated into _p_c_a_l by Richard Dyson.  Inter-
       national language support 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), and Neeme Praks (Esto-
       nian).



Version 4.8.0              14 Dec 2004                    PCAL(1)
