[4mPCAL[24m(1)                          USER COMMANDS                         [4mPCAL[24m(1)

[1mNAME[0m
       pcal - generate PostScript (or HTML) calendars

[1mSYNOPSIS[0m
       [1mpcal [22m[[1m-e[22m|[1m-f [4m[22mcal[24m] [[1m-o [4m[22mfile[24m] [[1m-l [22m| [1m-p[22m] [[1m-P [22m[letter | legal | a4 |
            tabloid]] [[1m-j [22m| [1m-J[22m] [[1m-m [22m| [1m-M[22m] [[1m-g [4m[22mweekday[24m[[4m-weekday[24m]|all|holiday]
            [[1m-O [4m[22mweekday[24m[[4m-weekday[24m]|all|holiday] [[1m-G [4m[22mweekday[24m[[4m-weekday[24m]|all|holi-
            day] [[1m-b [4m[22mweekday[24m[[4m-weekday[24m]|all|holiday] [[1m-s [22m[[4mday_numer-[0m
            [4mics_color[24m][/[4mempty_day_box_fill_color[24m]] [[1m-F [4m[22mday[24m] [[1m-A[22m|[1m-E[22m]
            [[1m-X [4m[22mxtrans[24m] [[1m-Y [4m[22mytrans[24m] [[1m-x [4m[22mxscale[24m] [[1m-y [4m[22myscale[24m] [[1m-t [22m[[4mti-[0m
            [4mtle_font[24m][/[4msize[24m]] [[1m-d [22m[[4mday_font[24m][/[4msize[24m]] [[1m-n [22m[[4mtext_font[24m][/[4msize[24m]]
            [[1m-L [4m[22mfooter_str[24m] [[1m-C [4m[22mfooter_str[24m] [[1m-R [4m[22mfooter_str[24m] [[1m-N [4m[22mnotes_str[24m]
            [[1m-D [4m[22msymbol[24m] [[1m-U [4m[22msymbol[24m] [[1m-B[22m] [[1m-# [4m[22mn[24m] [[1m-S [22m| [1m-k [22m| [1m-K[22m] [[1m-w[22m] [[1m-I[22m]
            [[1m-c [22m| [1m-H[22m] [[1m-q[22m] [[1m-z [4m[22mtime_zone[24m] [[1m-h [22m| [1m-u [22m| [1m-v[22m] [[1m-a [4m[22moutput_language[24m]
            [[1m-r [22m[[4mmapping[24m] [[1m-T [22m[B|I|R]] [[1m-W [22m[left|center|right]] [month] [year]
            [nmonths]



[1mDESCRIPTION[0m
       [4mPcal[24m generates PostScript to produce landscape or portrait calendars
       for any month and year.  The arguments [1mmonth[22m, [1myear[22m, and [1mnmonths[22m, if
       provided, should be numeric.  The [1mmonth [22mvalue should be in the range 1
       - 12, and the [1myear [22mvalue 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 [1myear[0m
       value, and calendars for the entire year will be generated.  Otherwise,
       [1mnmonths [22mmonths, starting with [1mmonth [22mand [1myear[22m, will be generated.

       For whole-year calendars (i.e. when the [1m-w [22moption 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 [1mmonth [22margument alone is given, it is expected to be the desired
       [1myear [22mto print, and prints all of the months in the given year.  If both
       [1mmonth [22mand [1myear [22mare given, then 12 consecutive months are printed start-
       ing at the given month and year.  If the [1mmonth[22m, [1myear[22m, and [1mnmonths [22margu-
       ments are all present, printing begins with the given month and year
       and [1mnmonths [22mmonths are printed, rounded up to the nearest multiple of
       12.



   [1mThe Date File (Configuration File)[0m
       By default, [4mpcal[24m 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 [4m.calendar[0m
       ([4mpcal.dat[24m under MS-DOS), or [4mcalendar[24m for compatibility with older ver-
       sions.  [4mPcal[24m will look in several places for such a file.  First, if
       the environment variable [1mPCAL_DIR [22mis defined, [4mpcal[24m searches the direc-
       tory indicated by that variable.  Next, [4mpcal[24m searches the user's home
       directory (as specified by the [1mHOME [22menvironment variable).  If neither
       [1mPCAL_DIR [22mnor [1mHOME [22mis defined, [4mpcal[24m searches the current directory in-
       stead.  Finally, if enabled (via the `SEARCH_PCAL_DIR' flag) when [4mpcal[0m
       was built, the directory where the [4mpcal[24m executable resides will be
       checked.  (This final search of the executable directory has been dis-
       abled in the version shipped with Debian.)  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 [1m-f [22mcommand-line op-
       tion.  See the [1mOPTIONS [22msection for more details.

       Every [4mpcal[24m 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 un-
       der the appropriate day of the month.  Encapsulated PostScript (EPS)
       images are handled similarly as described in a later subsection.

       [1mtroff[22m-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 re-
       spectively.  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 ex-
       pressed 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''

                             [1mNote: [4m[22mpcal[24m 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  ``im-
                             age:'', then it is interpreted as a specification
                             of  an Encapsulated PostScript (EPS) image rather
                             than as simple text; more information on specify-
                             ing EPS images is available in a later section of
                             this document

       If the [1m-A [22moption (American date formats, the default) is given:

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

       If the [1m-E [22moption (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 [1m-s [22moption (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'' in-
       cludes only those days flagged as holidays.   The  keywords  ``nonweek-
       day'',  ``nonworkday'', and ``nonholiday'' are also recognized as nega-
       tions of the above.  See the [1mCAVEATS [22mbelow 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  us-
       ing  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 ``al-
       ternate, 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
       [4mpcal[24m  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 [1mnewline [22m)  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 [1m-H [22mflag); 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 [4mcalendar(1)[24m (see the [1m-c [22mflag) input.

       Lines  in the configuration file consisting of [1myear #### [22m(where [1m#### [22mis
       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 [1myear  all  [22m(or,  alterna-
       tively, [1myear *[22m) direct [4mpcal[24m 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  ex-
       plicit [1myear #### [22mentry) will set the remembered year to that year.

       Lines in the configuration file consisting of [1mopt <options> [22mcan be used
       to  override  the  defaults for any command-line options except [1m-c[22m, [1m-e[22m,
       [1m-f[22m, [1m-h[22m, [1m-H[22m, [1m-u[22m, [1m-v[22m, [1m-D[22m, and [1m-U[22m.  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  [1mnote{/<number>}  <month>[0m
       can be used to place notes regarding the entire month in one of the un-
       used  blocks  of  the  calendar.  The [1m<month> [22mindicator 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.  [1m<number> [22mis an optional positive or nega-
       tive number specifying the empty box where the associated text is to be
       placed.  If positive, [4mpcal[24m counts forward from the first empty box;  if
       negative,  [4mpcal[24m  counts  backward  from  the  last  empty  box.   Thus,
       [1m``note/1'' [22mplaces the associated text in the first empty  box;  [1mnote/-3[0m
       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.  [1m-S[22m, [1m-k[22m, and [1m-K[22m, 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 [1minput-language XX [22m(where
       [1mXX [22mis 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  op-
       tion  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 [1m-a [22moption.

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



   [1mDeleting Events[0m
       By  prepending  the  [4m`delete'[24m 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.



   [1mFormat Specifiers[0m
       [4mPcal[24m allows format specifiers in both the event text and footer strings
       (see the [1m-L[22m, [1m-C[22m, [1m-R[22m, and [1m-N [22moptions 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
       [1m%[louwMD] [22mand [1m%[o0+-] [22mformat specifiers are specific to [4mpcal[24m.

       The  [1m%u [22mspecifier 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 [1m-F [22moption below) as the start of week 2; [1m%U [22mconsiders the first
       logical Sunday as the first day of week 1.  [1m%w [22mand [1m%W  [22mbehave  like  [1m%u[0m
       and  [1m%U  [22mrespectively,  but use the first logical Monday instead.  Note
       that [1m%w [22mhas a different meaning from strftime().

       The [1m%o [22mformat specifier prints a number as an ordinal, with the  appro-
       priate  suffix (``st'', ``nd'', ``rd'', or ``th'' in English) appended.
       For example, [1m%od [22mprints the day  of  the  month  as  ``1st'',  ``2nd'',
       ``3rd'', etc.

       Unlike  strftime(), [4mpcal[24m defaults to printing numbers (except [1m%y[22m) with-
       out leading zeroes.  If leading zeroes are desired, the `0' prefix  may
       be used.  For example, [1m%0j [22mprints the first day of year as ``001''.

       The  [1m%+  [22mand [1m%- [22mformat specifiers direct [4mpcal[24m to substitute the follow-
       ing/previous month/year in the following [1m[bBmyY] [22mspecifier.  For  exam-
       ple, [1m%+B [22mprints the name of the next month.

       The [1m%{[+-]N}[DWMY] [22mformat specifiers do not print anything, but instead
       adjust  the  working  date  by  +- [1mN[22mdays ([1mD[22m), weeks ([1mW[22m), months ([1mM[22m), or
       years ([1mY[22m).  Subsequent format specifiers use the adjusted date  instead
       of  the current date.  For example, [1m%+1M %B %Y [22madjusts the date forward
       by one month and then prints the resulting month  and  year  (``January
       1992''  in December, 1991); [1m%-2W %b %d [22madjusts 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,  [1m%+1Y%-1D[0m
       adjusts  the date forward by one year and then backward by one day.  If
       [1m%D [22mor [1m%M [22mis specified alone (or if [1mN [22mis zero), [4mpcal[24m restores the origi-
       nal date.  Note that [1m%M [22mhas a different meaning to the strftime() func-
       tion.

       Here's a common, useful example of an event entry  for  the  [4mpcal[24m  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

   [1mEncapsulated PostScript (EPS) Images[0m
       For  monthly  PostScript calendars only, [4mpcal[24m supports the embedding of
       one or more EPS images (photos, icons, etc) into any given day  of  the
       month.  (EPS image specifications in the [4mpcal[24m 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 in-
       stead 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.
                                   [1mNote:  [22mThe  EPS image filename must be pre-
                                   ceded by the constant text `image:' in  or-
                                   der  to distinguish an EPS image specifica-
                                   tion from an ordinary event text specifica-
                                   tion.

            <x-scale>              is a scaling factor in the  horizontal  di-
                                   mension  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 posi-
                                   tive values should be  used.   However,  in
                                   the  rare  case that you find that your EPS
                                   image needs to be flipped about the  verti-
                                   cal  axis (i.e. left to right), you can use
                                   a negative value to  achieve  this  without
                                   having  to tweak the actual PostScript con-
                                   tent within the EPS image file.  Use  of  a
                                   negative value will undoubtedly necessitate
                                   a corresponding change to the <x-delta> pa-
                                   rameter  to  account  for the image's relo-
                                   cated 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 im-
                                   age'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 [4mpcal[24m 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.)

       [1mNote: [22mUnfortunately, most EPS images cannot be used directly by [4mpcal[24m.


              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
              [4mpcal[24m 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 [4mpcal[24m output using a PostScript viewer as you tweak the Post-
              Script commands in the EPS image file and/or the event entry  in
              the [4mpcal[24m date file.

                     [1mNote:  [22mDepending 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':

              [4mhttp://www.gimp.org[0m


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

              [4mhttp://wvware.sourceforge.net/libwmf.html[0m


       For icons/images in SVG format, the ImageMagick  `convert'  utility  is
       sometimes useful for generating [4mpcal[24m-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:

              [4mhttp://www.imagemagick.org[0m


       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:

              [4mhttp://librsvg.sourceforge.net/[0m

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


       The [4mOpen[24m [4mClip[24m [4mArt[24m [4mLibrary[24m is a  good  source  of  freely-usable  images
       (many of which are in SVG format) for decorating your events:

              [4mhttp://www.openclipart.org[0m

       [1mNote:  [22mThe  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  [4mpcal[24m  from  the  same  com-
       puter/setup  as that which was used to run [4mpcal[24m 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 out-
       put  file.  For example, assuming your initial calendar output was gen-
       erated 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, al-
       lowing you to transport the `out.ps' file to another computer for view-
       ing/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.



   [1mPre-Processor Functionality[0m
       [4mPcal[24m supports rudimentary [4mcpp[24m-like functionality in the date file,  al-
       lowing the following constructs:

              +o [1mdefine | undef[0m

              +o [1mif{{n}def} ... {elif ...}* {else ...} endif[0m

              +o [1minclude[0m

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

       Symbol  names  defined  using these keywords (or via the [1m-D [22moption) are
       case-insensitive.  It is not an error to [1mundef [22man undefined symbol, nor
       to [1mdefine [22ma 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  [1mifdef [22malone is always [1mfalse[22m; an [1mifndef [22malone is always [1mtrue[22m.  [1mif [22mis
       accepted as a synonym for [1mifdef[22m.

       The name of the file in the [1minclude [22mdirective 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"  ap-
       pears  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 applic-
       able years.  [4mPcal[24m is smart enough to translate [1m~/ [22mto  the  user's  home
       directory.

       [4mPcal[24m  normally  terminates  immediately if the file specified in an [1min-[0m
       [1mclude [22mdirective does not exist.  An alternate form  of  the  directive,
       [1minclude?[22m,  directs [4mpcal[24m to continue silently if the file does not exist
       or cannot be opened.

       In addition to pre-processing keywords, [4mpcal[24m also accepts  boolean  ex-
       pressions in [1mif{{n}def} [22mand [1melif [22mdirectives.  These expressions consist
       of  symbol names joined by the boolean operators [1m![22m, [1m&[22m, [1m^[22m, and [1m|[22m, in or-
       der of precedence, high to low.  Parentheses may be used to  alter  the
       precedence.  The synonyms [1m&& [22mand [1m|| [22mare accepted for [1m& [22mand [1m|[22m.  A symbol
       name evaluates to [1mtrue [22mif currently defined, [1mfalse [22mif not; thus:

            ifdef A | B | C

       ...is [1mtrue [22mif any of the symbols A, B, and C is defined, and:

            ifdef A & B & C

       ...is  [1mtrue  [22mif they all are.  Note that [1mifndef <expr> [22mis equivalent to
       [1mifdef !( <expr> ).[0m



   [1mThe Moon File[0m
       If a file of the name [4m.moon##[24m ([4mmoon##.dat[24m under MS-DOS),  where  [1m##  [22mis
       the  last two digits of the calendar year, exists in the same directory
       as the date file (or in the directory where [4mpcal[24m  resides),  [4mpcal[24m  uses
       the  information  contained  within to calculate the phase of the moon.
       If a) no such file exists, b) the [1m-e [22mflag (do not use a date  file)  is
       specified,  or  c)  the  [1m-z [22mflag (specify time zone) is specified, then
       [4mpcal[24m uses an algorithm to calculate the phase of the moon.

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

       If the [1m-A [22moption (American date formats, the default) is given:

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

       If the [1m-E [22moption (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, [4mpcal[24m 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 [1mopt -A [22mor [1mopt -E [22mline 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.

   [1mGenerating PostScript Calendars Via A Web Browser Interface[0m
       PostScript-format [4mpcal[24m calendars can be generated and viewed from a web
       browser interface.

              [1mNote: [22mThis is not to be confused with the  ability  to  generate
              non-PostScript,  HTML-format  (using the [1m-H [22mcommand-line option)
              calendars, which is a different capability entirely.

       [4mPcal[24m 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 us-
       ing  it. Change the definition for [4m`pcal='[24m (Bourne shell script) or [4m`my[0m
       [4m$PCAL[24m [4m='[24m (Perl script) to point to the location of the [4mpcal[24m  executable
       file.   Change  the definition for [4m`file='[24m (Bourne shell script) or [4m`my[0m
       [4m$FILE[24m [4m='[24m (Perl script) to point to the location of the [4mpcal[24m `date file'
       (e.g. `.calendar'), which contains the options for running  [4mpcal[24m.   Fi-
       nally,  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.

              [1mNote: [22mDepending 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) Im-
              ages'.

[1mOPTIONS[0m
       [1m-e     [22mPrints an empty calendar.  Do not print entries from a [4m.calendar[0m
              file even if one exists.

       [1m-f [4m[22mcal[24m Directs [4mpcal[24m to use the file name [4mcal[24m as the input file in place
              of the default [4m.calendar[24m file.  Note that the search  rules  are
              different  when  [1m-f  [22mis  used.   If [4mcal[24m is an absolute file name
              (i.e. starting with a `/'), then [4mpcal[24m attempts to open only that
              file.  Otherwise, [4mpcal[24m looks for [4mcal[24m in the  current  directory,
              then  in  the  directory  indicated  by the environment variable
              [1mPCAL_DIR  [22m(if  defined),  and  finally,  if  enabled  (via   the
              `SEARCH_PCAL_DIR'  flag)  when  [4mpcal[24m was built, in the directory
              where the [4mpcal[24m executable resides.  If the given [4mcal[24m file is not
              found, an error results.

       [1m-o [4m[22mfile[0m
              Directs [4mpcal[24m to write the output to [4mfile[24m instead of to stdout.

       [1m-l     [22mCauses the output to be in landscape mode (default).

              [4mPcal[24m  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 im-
              age placement and scaling, based on the page orientation.


       [1m-p     [22mCauses the output to be in portrait mode.

              [4mPcal[24m 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.


       [1m-P     [22mSelects 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

              [4mPcal[24m 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.

       [1m-j     [22mCauses  the Julian date (day of year) to be printed in each cal-
              endar box.

       [1m-J     [22mCauses the Julian date and the number of days remaining  in  the
              year to be printed in each calendar box.

       [1m-m     [22mCauses  moon  icons to be printed on dates corresponding to new,
              half, and full moons (the default is that no moons are printed).

       [1m-M     [22mCauses moon icons to be printed on all  dates  (the  default  is
              that no moons are printed).

       [1m-g [4m[22mday1[24m[[4m-day2[24m] [1m| all | holiday[0m
              Causes all dates falling on weekday [4mday1[24m (through [4mday2[24m if speci-
              fied)  to be printed in the `day numerics color' (i.e. the color
              specified by the [1m-s [22moption [default = gray]); [1m-g all [22mcauses  all
              weekdays  (other than holidays) to be printed in the `day numer-
              ics color'; [1m-g holiday [22mcauses all holidays to be printed in `day
              numerics color'.  [4mday1[24m and [4mday2[24m may wrap  around  weekends;  for
              example, [1m-g fri-sun [22mcauses Fridays, Saturdays, and Sundays to be
              printed in the `day numerics color'.

       [1m-O [4m[22mday1[24m[[4m-day2[24m] [1m| all | holiday[0m
              Similar to [1m-g[22m, but the selected days will be printed as outlined
              characters, using the `day numerics color'.

       [1m-G [4m[22mday1[24m[[4m-day2[24m] [1m| all | holiday[0m
              Similar to [1m-g[22m, but the selected days will be printed in the `day
              numerics color', outlined in black.

       [1m-b [4m[22mday1[24m[[4m-day2[24m] [1m| all | holiday[0m
              Similar  to  -- you guessed it -- [1m-g[22m, 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., [1m-g all -b[0m
              [1msat-sun [22m).

           [1mNote:[0m
              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 [4mpcal[24m, [1m-O [22mand [1m-G [22malone change all non-black days to the speci-
              fied color.

       [1m-s [4m[22m[day_numerics_color][/empty_day_box_fill_color][0m
              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.   [1mNote: [22mThis 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 [4mred[24m:[4mgreen[24m:[4mblue[24m (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).

       [1m-F [4m[22mday[24m Selects weekday [4mday[24m as the first day of the week.  The given day
              will appear in the left-most column of the calendar.  [4mday[24m 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).

       [1m-A     [22mDirects  [4mpcal[24m  to use American date conventions ( [1mmm/dd{/yy} [22mand
              [1mmonth dd [22m) 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).

       [1m-E     [22mDirects [4mpcal[24m to use European date conventions (  [1mdd/mm{/yy}  [22mand
              [1mdd month [22m) 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).

       [1m-X [4m[22mxtrans[0m
              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.

       [1m-Y [4m[22mytrans[0m
              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.

       [1m-x [4m[22mxscale[0m
              Specifies the x-axis scaling factor for the calendar size.

       [1m-y [4m[22myscale[0m
              Specifies the y-axis scaling factor for the calendar size.

       [1m-t [22m[[4mtitle_font[24m][[1m/[4m[22msize[24m]
              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, [1mpcal -t Times-Roman/54 [22msets the font to Times-Roman
              and the month/year point size to 54.  The font size may also  be
              changed  independently: [1mpcal -t /54 [22mchanges the point size to 54
              without affecting the font name.

              Note: For yearly calendars, any specification of  font  [4msize[24m  is
              ignored.

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

       [1m-d [22m[[4mdate_font[24m][[1m/[4m[22msize[24m]
              Similar  to the [1m-t [22moption, 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  [4msize[24m  is
              ignored.

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

       [1m-n [22m[[4mtext_font[24m][[1m/[4m[22msize[24m]
              Similar  to  the  [1m-t [22mand [1m-d [22moptions, 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).

       [1m-L [4m[22mstring[0m
              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.

       [1m-C [4m[22mstring[0m
              Similar  to [1m-L[22m, but causes the accompanying string to be printed
              as a centered footer.  If the [1m-H [22mflag (generate calendar as HTML
              table) was specified, this string will be used as the title  and
              heading.

       [1m-R [4m[22mstring[0m
              Similar  to [1m-L[22m, but causes the accompanying string to be printed
              as a right-justified footer.

       [1m-N [4m[22mstring[0m
              Causes the accompanying string to be printed as the heading  for
              the  "Notes"  box.  Note, however, that [4mpcal[24m makes no attempt to
              ensure that it fits.

       [1m-D [4m[22msymbol[24m [4m[value][0m
              Defines the named symbol and an optional value to be  associated
              with that symbol, prior to reading the date file.

       [1m-U [4m[22msymbol[0m
              Un-defines the named symbol prior to reading the date file.

       [1m-B     [22mCauses  [4mpcal[24m 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 [1m-s [22moption  [default
              = gray]).

       [1m-# [4m[22mn[24m   Causes  [4mpcal[24m  to  print  [4mn[24m  copies (maximum: 100) of each output
              page.

       [1m-S     [22mCauses [4mpcal[24m to suppress printing the small calendars.   See  the
              [1mCAVEATS [22msection for further details.

       [1m-k     [22mCauses  [4mpcal[24m to print the small calendars in the upper left cor-
              ner (the default is to print them at the lower right).

       [1m-K     [22mCauses [4mpcal[24m 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).

       [1m-w     [22mCauses [4mpcal[24m 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 [1mCAVEATS [22msection for details on the  use  of
              this option with other options.

              Pcal predefines the symbol [1mwhole_year [22mwhen the [1m-w [22mflag is in ef-
              fect, allowing directives like `[1mifdef whole_year[22m' in the config-
              uration file.

       [1m-I     [22mResets all parameters to the program defaults.

       [1m-c     [22mCauses [4mpcal[24m to generate a date file suitable for use as input to
              the  Un*x  [4mcalendar(1)[24m utility.  The normal PostScript output is
              suppressed.

       [1m-H     [22mCauses [4mpcal[24m 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 [1m-C [22mflag), al-
              ternate fonts/sizes, transformation and scaling factors, or  em-
              bedded EPS images.

       [1m-q     [22mThis  option  is only valid when used in conjunction with the [1m-H[0m
              (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.

       [1m-z [4m[22mtime_zone[0m
              Forces  [4mpcal[24m to ignore the moon file and to use its internal al-
              gorithm for moon phase  calculations,  adjusting  the  phase  by
              [4mtime_zone[24m  hours  (where [4mtime_zone[24m 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).

       [1m-h     [22mCauses  [4mpcal[24m  to write version information, parameter usage mes-
              sage, and full explanation of options and file formats (to  [4mstd-[0m
              [4mout[24m) and terminate.

       [1m-u     [22mCauses  [4mpcal[24m  to  write  version information and parameter usage
              message (to [4mstdout[24m) and terminate.

       [1m-v     [22mCauses [4mpcal[24m to write version information only  (to  [4mstdout[24m)  and
              terminate.

              Pcal  predefines the symbol [1mvX_Y_Z[22m, where [1mX_Y_Z [22mdenotes the cur-
              rent version of Pcal (e.g. version 4.9.0 predefines  the  symbol
              [1mv4_9_0[22m).

       [1m-a [4m[22moutput_language[0m
              Select  the output language (for the names of months and days on
              the calendar).

              Currently, the following languages are supported: [1mca  [22m(Catalan),
              [1mcs  [22m(Czech), [1mda [22m(Danish), [1mde [22m(German), [1mel [22m(Greek), [1men [22m(English),
              [1meo [22m(Esperanto), [1mes [22m(Spanish), [1met [22m(Estonian),  [1mfi  [22m(Finnish),  [1mfr[0m
              (French),  [1mha  [22m(Hawaiian),  [1mhu  [22m(Hungarian),  [1mit  [22m(Italian),  [1mlt[0m
              (Lithuanian), [1mlv [22m(Latvian), [1mnl [22m(Dutch), [1mpl  [22m(Polish),  [1mpt  [22m(Por-
              tuguese),   [1mro   [22m(Romanian),   [1mru  [22m(Russian),  [1msk  [22m(Slovak),  [1msv[0m
              (Swedish), and [1muk [22m(Ukrainian).  The default is [1men[22m.

              Note that this option does [1mnot  [22mspecify  the  `input  language',
              which  is  the language used to process events in the configura-
              tion file ('English', by default, unless changed with the [4minput-[0m
              [4mlanguage[24m [4mXX[24m directive).  See the section [4mThe[24m [4mDate[24m [4mFile[24m for  more
              details on specifying the `input language'.

              [1mNote:  [22mIn  order  to  display diacritical marks, languages other
              than English require that the characters be remapped.  Normally,
              no action is required since [4mpcal[24m 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 [1m-r [22moption (e.g. "-r Latin1").

              Furthermore,  an  appropriate  font should be selected as needed
              using the [1m-t [22moption (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.

              [4mPcal[24m predefines the symbol [1mlang_XX[22m, where [1mXX [22mis the  two-charac-
              ter abbreviation for the selected output language.

       [1m-r [22m[[4mmapping[24m]
              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 [4mpcal[24m 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 [4mmapping[24m 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).


       [1m-T [22m[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.


       [1m-W [22m[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.  [1m-Y -###[22m) should be specified
       with no space between the option and the (negative) value to avoid [4mpcal[0m
       interpreting the value as an illegal flag and aborting.   For  example,
       use ` [4m-Y-50[24m' instead of ` [4m-Y[24m [4m-50[24m' on your option specification.

       Any  option  (except  [1m-G [22mand [1m-O[22m, 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 [1m-D [22mop-
       tion alone clears all the defined symbols, the [1m-U [22moption alone  has  no
       effect.   The  [1m- [22m(or [1m-- [22mas per System V) argument may be used to disam-
       biguate command lines such as:

              [1mpcal -t 9 90[0m

       This could be written instead as one of the following:

              [1mpcal -t - 9 90[0m
              [1mpcal -t -- 9 90[0m

       If the environment variable [1mPCAL_OPTS  [22mis  defined,  its  contents  are
       parsed as a command line.  Flags set via [1mPCAL_OPTS [22moverride the program
       defaults,  but  are overridden by options set via [1mopt [22mlines in the con-
       figuration file or explicitly on the command line.



   [1mAdditional Options For Debugging Only[0m
       The [1m-Z [22mflag is used to print debugging information which is of interest
       primarily to [4mpcal[24m 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.



[1mCAVEATS[0m
       +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 [4mpcal[24m 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 [4mpcal[0m
         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 [1m-w [22mand [1m-p [22moptions are used together,  [4mpcal[24m  revises  the  y-
         scale factor in order to use the entire portrait page; therefore, the
         user  should avoid using use the [1m-y [22moption when using both the [1m-w [22mand
         [1m-p [22moptions.  Use of the [1m-w [22moption in any  case  effectively  disables
         the [1m-m[22m, [1m-M[22m, [1m-j[22m, and [1m-J [22moptions.

       +o The  output  of the [1m-c [22moption may be used as input to subsequent runs
         of [4mpcal[24m.  Note, however, that [1mopt [22mlines (except for an automatic  [1mopt[0m
         [1m-[A|E][22m),  comments,  ``note''  text,  and  [1mifdef[22m'd-out source will be
         lost.

       +o The [1m-S [22moption interacts with [1mnote{/<number>}[22m; if used, it  should  be
         specified  either on the command line or prior to the first [1mnote [22mline
         in the date file.

[1mSEE ALSO[0m
       Website for [4mpcal[24m and [4mlcal[24m (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
       [4mpcal[24m  and the '-c' option is part of the BSD Main Utilities ('bsdmainu-
       tils') package and is available at the Debian site:

              [4mhttp://packages.debian.org/stable/source/bsdmainutils[0m

       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  [4mPostScript[24m [4mLanguage[24m [4mReference[24m [4mManual[24m, which can be found here
       (as of Dec 2007):

              [4mhttp://partners.adobe.com/public/developer/ps/index_specs.html[0m

[1mAUTHORS[0m
       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  in-
       corporated  into [4mpcal[24m by Richard Dyson.  International 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. Li-
       sivka (Ukrainian), Neeme Praks (Estonian,  Russian,  Latvian,  Lithuan-
       ian),  Peter  Cernoch  (Czech),  Ferenc  Kruzslicz  (Hungarian), Carles
       Sadurni 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                          [4mPCAL[24m(1)
