  This file documents Gcal, a program for printing calendars.  Gcal
displays a calendar for a month or a year, eternal holiday lists and
fixed date lists, in many ways.  The program correctly omits the dates
that were skipped when the current Gregorian calendar replaced the
earlier Julian calendar.

  Copyright (C) 1994, 1995, 1996, 1997 Thomas Esken

  This is the second edition of the Gcal documentation.

  Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

  Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

  Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Free Software Foundation.

  Any suggestions, improvements, extensions, bug reports, donations,
proposals for contract work, and so forth are welcome!  Please send
them directly to my eMail address.  If you like my work, I'd appreciate
a postcard from you!

------------------------oOO      \\\_''/      OOo---------------------------
Thomas Esken               O     (/o-o\)     O  eMail: esken@uni-muenster.de
Im Hagenfeld 84                 ((  ^  ))       Phone: +49 251 232585
D-48147 Muenster; Germany    \____) ~ (____/    MotD : 2old2live, 2young2die

Actual date modifier
--------------------

  It is allowed to use that date -- instead of the actual system date
-- which is defined by the `%DATE' option.  This means, fixed dates can
be checked for *any* year and are respected in the same way, as if they
would be fixed dates of the actual year.

The date must be denoted in one of these formats:

   * `YYYY[MM[DD|WWWN]]'

   * `YYYY*d|wN[WWW]'

   * `YYYY@e|t|DVAR[[+|-]N[WWW]]'

   * `MONTH NAME[DD]'

   * `WEEKDAY NAME[N]'

   * DD

Some examples to this:

     *Please note:*
     The following examples assumes the actual system date is
     *Wednesday, the 17th February 1993* (19930217)!

The `YYYY[MM[DD|WWWN]]' format:
        * `gcal %1994' (== YYYY)
          The actual date is set to the date 17th February 1994
          => 19940217.

        * `gcal %1994Mar'

        * `gcal %19943'

        * `gcal %199403' (== YYYYMM)
          The actual date is set to the date 17th March 1994
          => 19940317.

        * `gcal %1994Mar3'

        * `gcal %1994033'

        * `gcal %19940303' (== YYYYMMDD)
          The actual date is set to the date 3rd March 1994 => 19940303.

        * `gcal %1994MarWed3'

        * `gcal %199403wed3' (== YYYYMMWWWN)
          The actual date is set to the date 3rd Wednesday in March 1994
          (N == `1...5|9') => 19940316.

        * `gcal %0'

        * `gcal %00'

        * `gcal %000'

        * `gcal %0000' (== YYYY)
          The actual date remains unchanged => 19930217.

        * `gcal %0000Mar'

        * `gcal %00003'

        * `gcal %000003' (== YYYYMM)
          The actual date is set to the date 17th March 1993
          => 19930317.

        * `gcal %0000Mar3'

        * `gcal %0000033'

        * `gcal %00000303' (== YYYYMMDD)
          The actual date is set to the date 3rd March 1993 => 19930303.

        * `gcal %0000MarWed3'

        * `gcal %000003wed3' (== YYYYMMWWWN)
          The actual date is set to the date 3rd Wednesday in March 1993
          (N == `1...5|9') => 19930317.

The `YYYY*d|wN[WWW]' format:
        * `gcal %1994*d10' (== `YYYY*dN')
          The actual date is set to the date 10th absolute day in 1994
          (N == `1...365|366|999') => 19940110.

        * `gcal %1994*d10sun' (== `YYYY*dNWWW')
          The actual date is set to the date 10th Sunday in 1994
          (N == `1...51|52|53|99') => 19940306.

        * `gcal %0*d10' (== `YYYY*dN')
          The actual date is set to the date 10th absolute day in 1993
          => 19930110.

        * `gcal %0*d10sun' (== `YYYY*dNWWW')
          The actual date is set to the date 10th Sunday in 1993
          => 19930307.

        * `gcal %1994*w10' (== `YYYY*wN')
          The actual date is set to the date Monday of the 10th
          ISO-week in 1994
          (N == `0|1...52|53|99') => 19940307.

        * `gcal %1994*w10sun' (== `YYYY*wNWWW')
          The actual date is set to the date Sunday of the 10th
          ISO-week in 1994 => 19940313.

        * `gcal %0*w10' (== `YYYY*wN')
          The actual date is set to the date Monday of the 10th
          ISO-week in 1993 => 19930308.

        * `gcal %0*w10sun' (== `YYYY*wNWWW')
          The actual date is set to the date Sunday of the 10th
          ISO-week in 1993 => 19930314.

The `YYYY@e|t|DVAR[[+|-]N[WWW]]' format:
        * `gcal %1994@e' (== `YYYY@e')
          The actual date is set to the date Easter Sunday 1994
          => 19940403.

        * `gcal %1994@e10'

        * `gcal %1994@e+10' (== `YYYY@e[+]N')
          The actual date is set to the date 10 days after Easter
          Sunday 1994 => 19940413.

        * `gcal %1994@e-10' (== `YYYY@e-N')
          The actual date is set to the date 10 days before Easter
          Sunday 1994 => 19940324.

        * `gcal %0@e'

        * `gcal %00@e'

        * `gcal %000@e'

        * `gcal %0000@e' (== `YYYY@e')
          The actual date is set to the date Easter Sunday 1993
          => 19930411.

        * `gcal %0@e10'

        * `gcal %0@e+10' (== `YYYY@e[|]N')
          The actual date is set to the date 10 days after Easter
          Sunday 1993 => 19930421.

        * `gcal %0@e-10' (== `YYYY@e-N')
          The actual date is set to the date 10 days before Easter
          Sunday 1993 => 19930401.

        * `gcal %1994@e3Wed'

        * `gcal %1994@e+3Wed' (== `YYYY@e[+]NWWW')
          The actual date is set to the date 3rd Wednesday after Easter
          Sunday 1994 => 19940420.

        * `gcal %1994@e-3wed' (== `YYYY@e-NWWW')
          The actual date is set to the date 3rd Wednesday before
          Easter Sunday 1994 => 19940316.

        * `gcal %0@e3wed'

        * `gcal %0@e+3wed' (== `YYYY@e[+]NWWW')
          The actual date is set to the date 3rd Wednesday after Easter
          Sunday 1993 => 19930428.

        * `gcal %0@e-3we' (== `YYYY@e-NWWW')
          The actual date is set to the date 3rd Wednesday before
          Easter Sunday 1993 => 19930324.

        * `gcal %1994@t' (== `YYYY@t')
          The actual date is set to today's date in 1994 => 199400217.

        * `gcal %1994@t10'

        * `gcal %1994@t+10' (== `YYYY@t[+]N')
          The actual date is set to the date 10 days after today's date
          in 1994 => 19940227.

        * `gcal %1994@t-10' (== `YYYY@e-N')
          The actual date is set to the date 10 days before today's
          date in 1994 => 19940207.

        * `gcal %0@t'

        * `gcal %00@t'

        * `gcal %000@t'

        * `gcal %0000@t' (== `YYYY@t')
          The actual date is set to today's date => 19930217.

        * `gcal %0@t10'

        * `gcal %0@t+10' (== `YYYY@t[|]N')
          The actual date is set to the date 10 days after today's date
          => 19930227.

        * `gcal %0@t-10' (== `YYYY@t-N')
          The actual date is set to the date 10 days before today's date
          => 19930207.

        * `gcal %1994@t3Wed'

        * `gcal %1994@t+3Wed' (== `YYYY@t[+]NWWW')
          The actual date is set to the date 3rd Wednesday after
          today's date in 1994 => 19940309.

        * `gcal %1994@t-3wed' (== `YYYY@t-NWWW')
          The actual date is set to the date 3rd Wednesday before
          today's date in 1994 => 19940302.

        * `gcal %0@t3wed'

        * `gcal %0@t+3wed' (== `YYYY@t[+]NWWW')
          The actual date is set to the date 3rd Wednesday after
          today's date => 19930310.

        * `gcal %0@t-3we' (== `YYYY@t-NWWW')
          The actual date is set to the date 3rd Wednesday before
          today's date => 19930127.

        * `gcal -v a=0303 %1994@a' (== `YYYY@DVAR')
          The actual date is set to the date 3rd March 1994 => 19940303.

        * `gcal -v a=0303 %1994@a10'

        * `gcal -v a=0303 %1994@a+10' (== `YYYY@DVAR[+]N')
          The actual date is set to the date 10 days after 3rd March
          1994 => 19940313.

        * `gcal -v a=0303 %1994@a-10' (== `YYYY@DVAR-N')
          The actual date is set to the date 10 days before 3rd March
          1994 => 19940221.

        * `gcal -v a=0303 %0@a' (== `YYYY@DVAR')
          The actual date is set to the date 3rd March 1993 => 19930303.

        * `gcal -v a=0303 %0@a10'

        * `gcal -v a=0303 %0@a+10' (== `YYYY@DVAR[+]N')
          The actual date is set to the date 10 days after 3rd March
          1993 => 19930313.

        * `gcal -v a=0303 %0@a-10' (== `YYYY@DVAR-N')
          The actual date is set to the date 10 days before 3rd March
          1993 => 19930221.

        * `gcal -v a=0303 %1994@a3wed'

        * `gcal -v a=0303 %1994@a+3wed' (== `YYYY@DVAR[+]NWWW')
          The actual date is set to the date 3rd Wednesday after 3rd
          March 1994 => 19940323.

        * `gcal -v a=0303 %1994@a-3wed' (== `YYYY@DVAR-NWWW')
          The actual date is set to the date 3rd Wednesday before 3rd
          March 1994 => 19940216.

        * `gcal -v a=0303 %0@a3wed'

        * `gcal -v a=0303 %0@a+3wed' (== `YYYY@DVAR[+]NWWW')
          The actual date is set to the date 3rd Wednesday after 3rd
          March 1993 => 19930324.

        * `gcal -v a=0303 %0@a-3wed' (== `YYYY@DVAR-NWWW')
          The actual date is set to the date 3rd Wednesday before 3rd
          March 1993 => 19930210.

The `MONTH NAME[DD]' format:
        * `gcal %April' (== MONTH NAME)
          The actual date is set to the date 17th April 1993
          => 19930417.

        * `gcal %april3'

        * `gcal %april03' (== MONTH NAME DD)
          The actual date is set to the date 3rd April 1993 => 19930403.

The `WEEKDAY NAME[N]' format:
        * `gcal %Friday' (== WEEKDAY NAME)
          The actual date is set to the date Friday of current week in
          February 1993 => 19930219.

        * `gcal %Friday2'

        * `gcal %Friday02' (== WEEKDAY NAME N)
          The actual date is set to the date 2nd Friday in February 1993
          (N == `1...5|9') => 19930212.

The DD format:
        * `gcal %3'

        * `gcal %03' (== DD)
          The actual date is set to the date 3rd February 1993
          => 19930203.

Commands
--------

  The commands control the periods Gcal respects.  They can be
partitioned into four major classes, namely "single" commands, special
"3-Month mode" commands, "lists" of commands and "ranges" of commands.
Single commands and special 3-Month mode commands only produce *one*
calendar sheet, ranges of commands or list of commands produce *more
than one* calendar sheet per run.  If a list of commands is given, Gcal
works sequentially on each single command given in the list, one by one.
A range of commands is expanded first by Gcal and after expansion is
done, Gcal works sequentially on each single command produced during
the internal expansion step.

  For understanding the notation used in the text below, MM is either a
number, a month name or one of the special 3-Month mode commands `.',
`..', `.+' and `.-'.  No lists or ranges of months or years can be
created in case a special 3-Month mode command is given.

  The range of MM is valid from 1 to 12 or valid from January to
December.  Both notations may be mixed.  Month names may be abbreviated
up to their first three characters.  YYYY is a number.  The range of
YYYY is valid from 1 to 9999.  A range (MM-MM YYYY+YYYY ...) must
consist of two elements.  A list (MM,...,MM YYYY;...;YYYY ...) must
contain two elements minimum and may have any number of elements.

Here is a list of all ranges of commands, lists of commands and other
command separator characters:

   * The `-' character is the *range of months* separator.

   * The `,' character is the *list of months* separator.

   * The `+' character is the *range of years* separator.

   * The `;' character is the *list of years* separator.

   * The `/' character is the *month of year* separator.

   * The `:' character is the *fiscal year* separator.

Single commands
...............

`NOTHING'
     Current month of current year, called "single month mode" in the
     further context.

`MONTH NAME'
     Selected month of current year, e.g.:

          gcal may
          gcal OCTOBER
          gcal ja

`YYYY'
     Selected year, called "single year mode" in the further context,
     e.g.:

          gcal 1992

     But there is an exception of this general rule.  If the specified
     year number is less or equal twelve, Gcal assumes that a selected
     month of the current year is wanted.  If you want to have a
     selected year less or equal twelve, call Gcal like this

          gcal 1:6

     or like this

          gcal 6+6

     to get the year six A.C.

`MM YYYY'
`MM/YYYY'
     Single month of selected year, e.g.:

          gcal 9 1992
          gcal 9/1992
          gcal Nov 1777
          gcal Nov/1777

`:'
     Single fiscal year, starting at the *actual month* of the *actual
     year* and ending at month *actual month*-1 of the *actual year*+1,
     called "implicit fiscal year" in the further context, e.g.:

          gcal :

`MM:'
     Single fiscal year, starting at month MM of the *actual year* and
     ending at month MM-1 of the *actual year*+1, called "explicit
     fiscal year" in the further context, e.g.:

          gcal 6:
          gcal feb:
          gcal NOVEMBER:

`:YYYY'
     Single fiscal year, starting at the *actual month* of year YYYY
     and ending at month *actual month*-1 of year YYYY+1, also called
     "explicit fiscal year" in the further context, e.g.:

          gcal :1999

`MM:YYYY'
     Single fiscal year, starting at month MM of year YYYY and ending
     at month MM-1 of year YYYY+1, called "explicit fiscal year" too in
     the further context, e.g.:

          gcal 7:1999
          gcal oct:1992
          gcal February:1777

3-Month mode commands
.....................

`.'
     Previous, actual and next month of the current year, e.g.:

          gcal .

`. YYYY'
     Previous, actual and next month of selected year, e.g.:

          gcal . 1992

`..'
     Actual quarter of the current year, e.g.:

          gcal ..

`.. YYYY'
     Actual quarter of selected year, e.g.:

          gcal .. 1992

`.+'
     Actual and next two months of the current year, e.g.:

          gcal .+

`.+ YYYY'
     Actual and next two months of selected year, e.g.:

          gcal .+ 1992

`.-'
     Actual and previous two months of the current year, e.g.:

          gcal .-

`.- YYYY'
     Actual and previous two months of selected year, e.g.:

          gcal .- 1992

Lists of commands
.................

`MM,...,MM'
     List of specified months of the current year, e.g.:

          gcal 1,5,12
          gcal 3,1,5,3
          gcal june,9,jan

`MM/YYYY,...,MM/YYYY'
     List of months in specified year, e.g.:

          gcal 1/1992,5,12/2001
          gcal june/1991,9/1801,jan

`MM,...,MM YYYY'
     List of specified months of selected year, e.g.:

          gcal 3,7 1999
          gcal 1,dec,july 1777

`YYYY;...;YYYY'
     List of specified years, e.g.:

          gcal 1992;1777;1899

`MM:YYYY;...;MM:YYYY'
     List of specified fiscal years, e.g.:

          gcal 7:1999;8:1992;April:3

*Other valid lists:*

`MM,MM/YYYY,...'
     Mixed list of months consisting of: `MM MM/YYYY'

          gcal 6,8,3/1999,feb/3,january

`MM:;MM:YYYY;...'
     Mixed list of fiscal years of the given / actual year consisting
     of: `MM: :YYYY MM:YYYY YYYY'

          gcal 3:;1994;february:1999;:1777;JAN:

`MM:;MM:;...'
     List of fiscal years of the actual year consisting of: `MM:'

          gcal 3:;august:;DEC:

Ranges of commands
..................

`MM-MM'
     Range of current months, e.g.:

          gcal 3-7
          gcal 11-8
          gcal MAY-dec
          gcal 12-aug

`MM/YYYY-MM/YYYY'
     Range of months of year, e.g.:

          gcal 3/1991-july/1992
          gcal dec/1994-3
          gcal sep-dec/2000

`MM-MM YYYY'
     Range of specified months of selected year, e.g.:

          gcal 3-7 1999
          gcal nov-3 1777
          gcal aug-dec 1992

`MM YYYY-YYYY'
`MM/YYYY-YYYY'
     Range of specified month of selected years, e.g.:

          gcal AUGUST 1494-1497
          gcal 3/1993-1999
          gcal nov/3-1777

`YYYY+YYYY'
     Range of specified years, e.g.:

          gcal 1992+1994

`MM:YYYY+MM:YYYY'
     Range of specified fiscal years, e.g.:

          gcal 7:1999+8:1992
          gcal aug:1992+july:1999

The `GCAL' environment variable
===============================

  The environment variable `GCAL' can hold a set of default options for
Gcal (see GCAL).  These options are
interpreted first at program start-up, and some can be overwritten by
explicit command line arguments or values found in a `@FILE' response
file.  See Command line arguments, and Response file, for
further information.

For example:

   * for *sh*:
          GCAL="-i @color -b 3"; export GCAL

   * for *csh*:
          setenv GCAL "-i @color -b 3"

   * for *MS-DOS*:
          set GCAL=-i @color -b 3

  On Vax/VMS, the name of the environment variable is `GCAL_OPT', to
avoid a conflict with the symbol `GCAL' set for invocation of the
program.

For example:

   * for *VMS*:
          define GCAL_OPT "-i @color -b 3"

Eternal Holidays
****************

The *eternal holiday list* is created only for dates after A.D.29.
It can be displayed in different ways:

  In case you start Gcal without an explicit (fiscal) date and the
*eternal holiday list* argument (see `--holiday-list[=long|short]'),
e.g.:

     gcal --holiday-list
     gcal -n
     gcal -n :

Gcal displays all holidays of the eternal holiday list that refer to
the actual / fiscal year, without a leading calendar sheet.

  In case you start Gcal with the *eternal holiday list* argument and a
month (plus an additional year), e.g.:

     gcal --holiday-list july
     gcal -n july
     gcal -n 7 1993
     gcal -n 7/1993

Gcal displays a month calendar sheet of the specified month (of year),
and trailing those holidays of the eternal holiday list that refer to
the given month (of the given year).

  In case you start Gcal with the *eternal holiday list* argument and a
simple year (or an explicit fiscal year), e.g.:

     gcal --holiday-list 1993
     gcal -n 1993
     gcal -n july:
     gcal -n :1993
     gcal -n 7:1993

Gcal displays a year calendar sheet of the specified year or fiscal
year, and trailing all holidays of the eternal holiday list that refer
to the given year or fiscal year.

  In case you start Gcal with the *eternal holiday list* argument and a
special 3-Month mode command (see `. YYYY'),
e.g.:

     gcal --holiday-list .
     gcal -n .
     gcal -n ..
     gcal -n .+
     gcal -n .-

Gcal displays the according three months using a fixed-style year
calendar sheet, and trailing all holidays of the eternal holiday list
that refer to the these months.

  In case you start Gcal with the *eternal holiday list* argument and a
*list* or *range* of commands, it produces the according series of
eternal holiday lists.  See `MM,...,MM', and
`MM-MM', for more details.

Some annotations:

  The following table lists all those characters which are used for
marking an entry in the eternal holiday list, i.e. directly leads its
date:

*Character*   *Description*
`+'           Legal holiday which is valid in the whole country.  Is
              automatically provided with highlighting sequences
              respectively marking characters.
`#'           Legal holiday which is valid in major parts of the whole
              country.  Is automatically provided with highlighting
              sequences respectively marking characters.
`*'           Legal holiday which is valid in minor parts of the whole
              country.  Is not provided with highlighting sequences
              respectively marking characters.
`-'           Other holiday which serves for memorial or remarking
              purposes only.  Is not provided with highlighting
              sequences respectively marking characters.

  By using the `--cc-holidays=CC[+...]' option, it is possible to
provide the eternal holiday list with additional country specific
holidays.  Thereafter, those country specific holidays are part of the
list likewise the standard holidays, too.  See
`--cc-holidays=CC[+...]'.  For example:

     --cc-holidays=de+fr

effects the inclusion of German and French holidays into the eternal
holiday list.  The inclusion of country specific holidays is not
coupled to Gcal's internationalization (see Aspects in Internationalization).
This means, no country
specific holidays are automatically respected at program start-up for a
definite territory or country.  So it's up to the user to decide which
country specific holidays are included into the eternal holiday list.
See The `GCAL' environment variable,
for informations, how Gcal can be induced to include the country
specific holidays automatically into the eternal holiday list at
program start-up.

  The free selection of the different country specific holidays can be
used very ingenious in case informations of a definite territory or
country are required.  Assuming a business man from Germany proposes to
travel to the U.S.A. in November and needs the information which legal
holidays are celebrated there on work days so he is able to plan his
dates.  This can be determined as follows:

     gcal -f /dev/null -q US -D r -cE nov

Fixed Dates
***********

  This chapter describes how to use the *fixed date* feature of Gcal.
For that purpose, you may create a Gcal resource file for showing fixed
dates and appointments (see Resource file.).

  Each time you execute Gcal in simple single month mode, i.e. no
explicit month, year or fiscal year is given in the command line, but
the *fixed date* argument, e.g.:

     gcal --list-of-fixed-dates
     gcal -c

it checks the resource file for dates and processes those that refer to
the actual system date (==today)!  Then Gcal displays all fixed dates
found in the resource file which refer to the actual day
(week/month/year) of the actual year, without a leading calendar sheet.

Some more examples:

     gcal -ce
     gcal -cw-
     gcal -c-m
     gcal -c-y-
     gcal -jcb -c-et
     gcal -cey-
     gcal -jc -cey

The fixed dates can be displayed in different ways:

  In case you start Gcal with the *fixed date* argument and/or a month
and/or an explicit year or fiscal year; respectively with the special
3-Month mode command, e.g.:

     gcal -c july
     gcal -ce 7 1994
     gcal -c-y 7/1994
     gcal -c 7:1993
     gcal -c 1993
     gcal -c .
     gcal -c .+

Gcal displays a (three) month / year calendar sheet of the specified
respectively actual month / year, and trailing those fixed dates found
in the resource file that refer to the given period; the intensity level
is the same as the `-cy' option if the period refers to a year or
fiscal year or to a three month period, respectively, is the same as the
`-cm' option if the period refers to a month.

  In case you start Gcal without an explicit date and the *fixed date*
argument *in connection with* the *eternal holiday list* argument, e.g.:

     gcal -c -n
     gcal -Cm -n
     gcal -Cl1224 -n
     gcal -cl3+ -n

then Gcal displays all fixed dates found in the resource file that
refer to the requested period, and after that all holidays of the
eternal holiday list that refer to the whole actual year, without a
leading calendar sheet.  See Eternal Holidays, for more details how
to use an *eternal holiday list*.

Annotation to previous examples:

  In case an additional *standard/special calendar format* argument or
an additional *starting day of week* argument (1) is found in the
command line, e.g.:

     gcal -c -n -i
     gcal -c -i-
     gcal -n -i- :
     gcal -n -s Sunday

Gcal displays a leading month, year or fiscal year calendar sheet
before all other lists.  See `--type=special|standard',
and `--starting-day[=ARGUMENT]', for
more information.

  Each time you execute Gcal in simple single year mode, i.e. no
explicit month, year or fiscal year is given in the command line, but
the *fixed date* argument (with optional modifiers) and the *number of
blocks* argument (see `--blocks=NUMBER'), e.g.:

     gcal -c --blocks=3
     gcal -C-em -b 3
     gcal -c-t -b 6 -jc

it checks the resource file for dates and processes those that refer to
the actual system date (==today)!  Gcal displays a leading year calendar
sheet, and all fixed dates found in the resource file that refer to the
actual day (week/month/year) of the actual year.

  You can list fixed dates of past, present or future month/years, too.
This can be done on the one hand, if you use the `%DATE' option in the
way you require (see Actual date modifier.), and on the other hand,
if a command respectively a *list* or *range* of commands is used.

For example:

`gcal -c -n- 1993'
     Lists all fixed dates of entire 1993 in ascending order, and the
     eternal holiday list of entire 1993 in descending order; the
     intensity level is the same as the `-cy' option.

`gcal -c- july:1993'
     Lists all fixed dates of fiscal year -- starting in July 1993 and
     ending in June 1994 -- in descending order; the intensity level is
     the same as the `-cy' option.

`gcal -ce july 1993'
     Lists all fixed dates of July 1993 inclusive all eternal holidays
     merged into this list in ascending order; the intensity level is
     the same as the `-cm' option.

`gcal -c-e -n 1993+1996'
     Lists all fixed dates of entire 1993, 1994, 1995 and 1996 (series
     of years) inclusive all eternal holidays merged into this list in
     descending order, and the eternal holiday list related to all
     above years in ascending order; the intensity level is the same as
     the `-cy' option.

`gcal -cm %19920317'
     Lists all fixed dates of March 1992 in ascending order.

`gcal %1994@e -n -c'
     Lists all fixed dates of Easter Sunday 1994 in ascending order,
     and the eternal holiday list of entire 1994 in ascending order.

  ---------- Footnotes ----------

  (1)  Except the `--starting-day=today' respectively the
`--starting-day=0' option.

Resource file
=============

  This section describes how to use a "resource file" that contains
fixed dates and appointments.  The name of the standard resource file is
`$HOME/.gcalrc' (1).

Gcal uses a special file searching mechanism:

  1. The Gcal program expects the standard resource file in that
     directory which is referenced in the environment variable `HOME'.
     If no `HOME' environment variable is defined and set, Gcal omits
     this step.  See HOME.

  2. If the above action fails, Gcal scans the directories which are
     referenced in the environment variable `GCALPATH' (see GCALPATH)
     for the standard resource file.  The
     `GCALPATH' environment variable contains a (`:') colon-separated
     (2) list of directories.  If no such environment variable is
     defined and set, Gcal also omits this step.

  3. If the above action fails, Gcal inspects the *user data* directory
     (3) to find the standard resource file.  This directory is a
     directory relative to the `HOME' directory.  If an environment
     variable `GCAL_USR_DATADIR' is set, Gcal appends the contents of
     this environment variable to the contents of the `HOME'
     environment variable, and tries to use that directory first
     instead of using the burned-in default name of that directory
     (see GCAL_USR_DATADIR).  If no `HOME'
     environment variable is defined and set, naturally Gcal also omits
     this step.

  4. If all above actions fail, Gcal inspects the *system data*
     directory (4) to find the standard resource file.  This directory
     is a directory absolute the *root*/*$(prefix)* directory.  If an
     environment variable `GCAL_SYS_DATADIR' is set, Gcal tries to use
     that directory first instead of using the burned-in default name
     of that directory (see GCAL_SYS_DATADIR).

  If the standard resource file is not found during the steps 1...4 of
the file searching mechanism, no fixed date messages will be created!

  In case the `--debug=abort' option is given and no standard resource
file is found during the steps 1...4 of the file searching mechanism,
the Gcal program will be aborted with an error code.  See 118,
and `--debug=abort', for more information.

  If a `-f|F NAME[+...]' respectively `--resource-file=NAME' command
line argument is given, a file NAME will be used for the resource file
instead of the standard resource file.  See `--resource-file=NAME'.

Annotation:

  An "extended file name" contains one ore more `/' (slash) characters
(5) and denotes a file, which fixed access path either starts from the
root directory, like `/foo/bar/file', or from the actual directory,
like `./bar/file' or `../bar/file'.  If NAME is an extended file name:

   * In case file NAME is found, Gcal will use it.

   * In case file NAME is not found, Gcal will not use it.

  A "simple file name" denotes a file, which access path doesn't either
starts from the root directory or from the actual directory, like
`file' or `bar/file'.  If NAME is a simple file name:

   * Gcal tries to find this file NAME using the previously explained
     file searching mechanism.

  ---------- Footnotes ----------

  (1)  On MS-DOS, OS/2 and some other operating systems, the name of
the *standard* resource file is `$HOME/gcalrc' (without a leading `.').

  (2)  On MS-DOS, OS/2 and some other operating systems, another
character will be used, e.g. `;' on MS-DOS and OS/2.

  (3)  Normally `$HOME/share/gcal'.

  (4)  Normally `/usr/local/share/gcal' or `$(prefix)/share/gcal'.

  (5)  Operating systems like MS-DOS or OS/2 use the `\' (Backslash)
character for separating a directory from a file name.

Structure of resource file
--------------------------

  First of all, a Gcal resource file is a plain ASCII text file.  This
text file may be created by any text editor or by redirecting the
*standard output channel* to a file, e.g.:

     $ echo '19930217 Text'>> resource-file <RET>

  A special -- but simple -- line structure is required so Gcal is able
to interpret its contents.  Each fixed date entry in a resource file
must be split into two parts, namely a *date part* and an optional
*text part* which *must* be separated by *one* "whitespace" (1)
character minimum.  It is unnecessary to give a whitespace separator
character if no *text part* is specified.

  A line must always end with a `\n' (newline) character, except it's
the last line of a resource file.  The maximum length of a line is
limited to `INT_MAX' (2) characters.  A newline character is
automatically appended to the line if the *standard output channel* is
directed to a file.  A newline character is appended to the typed line
in a text editor window if it is completed by pressing the <RET> key.
In case the used text editor doesn't generate the newline character in
this way, it should be set to this mode of operation, otherwise this
text editor is useless for creating Gcal resource files.

The line structure of fixed date entries is:

     DATE PART [ *whitespace* TEXT PART ] *newline*

or more concrete, e.g.:

     YYYY[MM[DD|WWWN]] [ *whitespace* TEXT ] *newline*

or much more concrete, e.g.:

     19940217 Hi, I'm the text!

Besides fixed date entries, a resource file may contain further entries
like:

Include directives...

     #include <FILE NAME>
     #include "FILE NAME"

Date variable assignments respectively operations...

     DVAR=NOTHING
     DVAR=MMDD
     DVAR=MMWWWN
     DVAR=*dN[WWW]
     DVAR=*wN[WWW]
     DVAR=DVAR[[+|-]N[WWW]]
     DVAR++
     DVAR--
     DVAR+=N[WWW]
     DVAR-=N[WWW]

Text variable assignments...

     TVAR=[TEXT]

Text variable references...

     TVAR

  Text variable references in the beginning of a Gcal resource file line
may only be used, if it is ensured that they are expanded to a valid
Gcal resource file line.

  ---------- Footnotes ----------

  (1)  For example *Tab*, *Space*, *Form-feed* and similar characters.

  (2)  Normally, this is for example equivalent to a value of 32,767 ==
(2^15)-1 on a 16-Bit machine architecture; to a value of 2,147,483,648
== (2^31)-1 on a 32-Bit machine architecture etc.

Date part of a line
-------------------

  The structure of a "date part" -- which gives Gcal the information at
which date a fixed date happens -- of a line in the resource file is

*either*: `YYYY[MM[DD|WWWN]]'

    `YYYY'
          (4 digits), is the year including the century (range
          0000...9999).  Leading zeroes are required in case given year
          is less than 1000 and other components of the date part are
          trailing the year.

    `MM'
          (2 digits or 3 characters), is the month (range 00...12 or
          99, respectively Jan, Feb...).  A given 99 for the month
          means the last month of the year (== December).  Leading
          zeroes are required in case given month is less than 10 and
          other components of the date part are trailing the month.

    `DD'
          (2 digits), is the day (range 00...31 or 99).  A given 99 for
          the day means the last day of the month.  Leading zeroes are
          required in case given day is less than 10 and other
          components of the date part are trailing the day.

    `WWW'
          (2...3 characters), is a short weekday name (range Mon...Sun).

    `N'
          (1 digit), is the N'th weekday WWW of month (range 1...5 or
          9).

             * N == 1...5
               N'th weekday WWW of month.

             * N == 9
               Last weekday WWW of month.

*or*: `YYYY*d|wN[WWW]'

    `YYYY'
          (4 digits), is the year including the century (range
          0000...9999).  Leading zeroes are required in case given year
          is less than 1000 and other components of the date part are
          trailing the year.

    `*d'
          (2 characters), is the reference to an ordinary date.

    `*w'
          (2 characters), is the reference to a date of an
          ISO-8601:1988 week.

    `N'
          (1...3 digits), is the value in days or in weeks, the fixed
          date occurs.  A given 99 in connection with a short weekday
          name means the last weekday WWW of the year.  A given 999 in
          connection with `*d' means the last day of a year, i.e. the
          31st December.  If the computed date doesn't occur in the
          year, i.e. exceeds the year bounds, the fixed date message is
          suppressed.

    `WWW'
          (2...3 characters), is a short weekday name (range Mon...Sun).

*or*: `YYYY@e|t|DVAR[[+|-]N]'

    `YYYY'
          (4 digits), is the year including the century (range
          0000...9999).  Leading zeroes are required in case given year
          is less than 1000 and other components of the date part are
          trailing the year.

    `@e'
          (2 characters), is the reference to the Easter Sunday's date.

    `@t'
          (2 characters), is the reference to today's date.

    `@DVAR'
          (2 characters), is the reference to a date variable.

    `[+|-]N'
          (1...4 alphanumeric characters), is the optional displacement
          value in days, the fixed date occurs relative to the Easter
          Sunday's date or date variables date.  A given -999 means the
          first day of a year, i.e. the 1st January.  A given +999 or
          999 means the last day of a year, i.e. the 31st December.  If
          the computed date doesn't occur in the year, i.e. exceeds the
          year bounds, the fixed date message is suppressed.

*or*: `YYYY@e|t|DVAR[+|-]NWWW'

    `YYYY'
          (4 digits), is the year including the century (range
          0000...9999).  Leading zeroes are required in case given year
          is less than 1000 and other components of the date part are
          trailing the year.

    `@e'
          (2 characters), is the reference to the Easter Sunday's date.

    `@t'
          (2 characters), is the reference to today's date.

    `@DVAR'
          (2 characters), is the reference to a date variable.

    `[+|-]NWWW'
          (3...7 alphanumeric characters), is the optional displacement
          value in weekdays, the fixed date occurs relative to the
          Easter Sunday's date or date variables date.  A given -99
          means the first weekday WWW of the year.  A given +99 or 99
          means the last weekday WWW of the year.  If the computed date
          doesn't occur in the year, i.e. exceeds the year bounds, the
          fixed date message is suppressed.

*Please note:*

   * If YYYY is specified as 0000:
     The month and day are assumed to be annual events and the *text
     part* will be displayed for any year.

   * If MM is not given or specified as 00:
     The day is assumed to be a monthly event for the specified year
     and the *text part* will be displayed for any month.

   * If DD is not given or specified as 00:
     Each day is assumed to be a daily event for the specified year and
     month and the *text part* will be displayed for any day.

   * If WWW is specified as a short (2...3 characters) weekday name,
     e.g. `Mon, Tue...':
     The given weekday name is assumed to be a weekly event for the
     specified year and month and the *text part* will be displayed for
     any week.

Further date part attributes
----------------------------

  The date part -- which leads a fixed date entry of a Gcal resource
file line -- may be provided with further attributes, that are either
specifications of lists of days or ranges of days, which provide the
information at which date a fixed date happens.  More further attributes
are the repetition factor as well as the appearance factor.

  All date parts of a Gcal resource file line, which are structured as
follows, may be provided generally with further attributes:

   * `YYYYMM...'

   * `YYYY*d|w...'

   * `YYYY@e|t|DVAR...'

*Attention:*
If the date part is supplied with further attributes and the year of
the fixed date is not given in a concrete manner, i.e. the year YYYY is
set to zero, such kinds of fixed dates are *only* computed correctly in
simple year bounds -- which means during a current year -- and not in
fixed dates shown after the current year has changed, e.g. in *fiscal
years*.

Lists of days
.............

  A list of days is specified by a `,' separator character; it must
contain two elements minimum and may have any number of elements.  A
single element of the list may not be set to a zero value and be not
concrete therefore.  (This wouldn't make any sense in this context.)

  A list of days is used to define recurrent fixed dates and to use
only one line in the resource file for them, instead of using several
lines in a resource file needed for defining these recurrent fixed
dates separately.  Assuming a fixed date shall always occur on the 1st
and the 15th day in every month of the year 1996, e.g. `Tax returns',
one solution would be on the one hand a fixed date entry in the
resource file for the 1st of the month and another entry for the 15th
of the month, which would be a total of two entries in the resource
file for such a fixed date.

  On the other hand, this expense can be reduced to a total of only one
entry in the resource file by using a list of days, which is likewise
valid for the 1st and the 15th day in every month, that is

     19960001,15 Tax returns

The use of lists of days in the date part is permitted as follows:

   * `YYYYMMDD|WWW|WWWN,[MM]DD|[MM]WWW|[MM]WWWN ...'

   * `YYYY*d|wN|NWWW,N|NWWW ...'

   * `YYYY@e|t|DVAR,|[+|-]N[WWW],[+|-]N[WWW] ...'

Some examples to this:

`000001fr3,12,99,mon,apr14,993,julfri3,08fr'
     In every year in January: on the 3rd Friday, on the 12th, on the
     last day of the month and on every Monday.  And in every year: on
     the 14th April, on the 3rd December, on the 3rd Friday in July and
     on every Friday in August.

`199600mon,fr,12'
     In the year 1996 in every month: on every Monday, on every Friday
     and on the 12th.

`0*d1,1fr,999,17mo'
     In every year: on the first day of the year, on the 1st Friday of
     the year, on the last day of the year and on the 17th Monday of
     the year.

`1996*w1fr,1,17mo,99fr'
     In the year 1996: on Friday of the 1st ISO-week, on Monday of the
     first ISO-week, on Monday of the 17th ISO-week and on Friday of
     the last ISO-week.

`0@a,+1,-3,5,+4fr,2fr,-10sa'
     In every year: on the date of the date variable A, one day after
     the date of A, three days before the date of A, five days after the
     date of A, four Fridays after the date of A, two Fridays after the
     date of A and ten Saturdays before the date of A.

`1996@e+1,-3,5,+4fr,2fr,-10sa'
     In the year 1996: one day after the Easter Sunday's date, three
     days before the Easter Sunday's date, five days after the Easter
     Sunday's date, four Fridays after the Easter Sunday's date, two
     Fridays after the Easter Sunday's date and ten Saturdays before
     the Easter Sunday's date.

`1996@t+1,-3,5,+4fr,2fr,-10sa'
     In the year 1996: one day after today's date, three days before
     today's date, five days after today's date, four Fridays after the
     today's date, two Fridays after today's date and ten Saturdays
     before today's date.

Ranges of days
..............

  A range of days is specified by a `#' separator character and must
consist of two elements, namely the starting day and the final day.
The starting day and likewise the final day of the range may not be set
to a zero value and be not concrete therefore.  (This wouldn't make any
sense in this context.)

  A range of days just as a list of days is used to define recurrent
fixed dates and to use only one line in the resource file for them,
instead of using several lines in a resource file needed for defining
these recurrent fixed dates separately.  Assuming a fixed date shall
always occur during the 1st and the 15th day (inclusive) in every month
of the year 1996, e.g.  `Inside work', one solution would be on the one
hand a fixed date entry in the resource file for the 1st of the month,
another one for the 2nd of the month until the 15th of the month, which
would be a total of 15 entries in the resource file for such a fixed
date (1).

  On the other hand, this expense can be reduced to a total of only one
entry in the resource file by using a range of days, which is likewise
valid for the 1st until the 15th day in every month, that is

     19960001#15 Inside work

The use of ranges of days in the date part is permitted as follows:

   * `YYYYMMWWW#WWW'

   * `YYYYMMDD|WWWN#[MM]DD|[MM]WWWN'

   * `YYYY*d|wN[WWW]#N[WWW]'

   * `YYYY@e|t|DVAR[[+|-]N[WWW]]#[+|-]N[WWW]'

  Preceding table shows that the starting and ending day can only be
specified by using date formats of the same type left and right the `#'
separator character.  Thus, it is not explicitly possible to define a
range of days using different types of date formats, means, fixed date
entries like:

     1996@e+3fr#1012 In the year 1996: every day that appears within the\
                     period of the date 3 Fridays after Easter Sunday's\
                     date until the 12th October.

cannot be defined in this way.  But this problem can be solved by using
an inclusive date period `%i[DATE][#[DATE]]' special text for defining
the ending day of the range (2), and the fixed dates are simply
produced until the last day of the year, e.g.:

     1996@e+3fr#+999 In the year 1996: every day that appears within the\
                     period of the date 3 Fridays after Easter Sunday's\
                     date until the 12th October.%i0#19961012

  See Inclusive date period `%i[DATE][#[DATE]]' special text,
for more details.

Some examples to this:

`199600mon#fr'
     In the year 1996 in every month: every day that appears within the
     day sequence `mon, tue, wed, thu, fri'.

`000000fr#mon'
     In every year in every month: every day that appears within the day
     sequence `fri, sat, sun, mon'.

`000001fr3#12'
     In every year in January: every day that appears within the period
     of the 3rd Friday of the month until the 12th of the month.

`00000112#fr3'
     In every year in January: every day that appears within the period
     of the 12th of the month until the 3rd Friday of the month.

`00000112#augfri3'
     In every year: every day that appears within the period of the
     12th January until the 3rd Friday of August.

`0000sep13#99fr9'
     In every year: every day that appears within the period of the
     13th September until the last Friday of December.

`0*d1#1fr'
     In every year: every day that appears within the period of the 1st
     day of the year until the 1rd Friday of the year.

`0*d99fr#333'
     In every year: every day that appears within the period of the
     last Friday of the year until the 333rd day of the year.

`1996*w1fr#17mo'
     In the year 1996: every day that appears within the period of the
     Friday of the 1st ISO-week until the Monday of the 17th ISO-week.

`0@a#+4fr'
     In every year: every day that appears within the period of the
     date of the date variable A until the 4th Friday after the date of
     the date variable A.

`1996@e-3#+9fr'
     In the year 1996: every day that appears within the period of the
     date three days before the Easter Sunday's date until the 9th
     Friday after the date of the Easter Sunday's date.

`1996@t-3#+99fr'
     In the year 1996: every day that appears within the period of the
     date three days before today's date until the last Friday of the
     year.

  ---------- Footnotes ----------

  (1)  Apart from the possibility, that a list of days can be used in
such a case.

  (2)  Implicit solution.