  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 warning 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 Thomas Esken

  This is the first 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    (/o-o\)    OOo-------------------------
Thomas Esken                o  (.  "  .)  o   Internet :
Im Hagenfeld 84              \___) ~ (___/      (esken@uni-muenster.de)
D-48147 M"unster; GERMANY                     Phone    : +49 251 232585

Fixed date warnings
*******************

  This chapter describes how to use the *fixed date warning* feature of
Gcal.  For that purpose, you may create a Gcal resource file for
showing fixed dates/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 warning* 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 (==todays) date.  Then Gcal displays all fixed date warnings
found in the resource file, that refer to the actual day
(week/month/year) of the actual year without a leading calendar.

Some more examples:

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

The fixed date warnings can be displayed in different ways:

  In case you start Gcal with the *fixed date warning* 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 of the specified
respectively actual month / year and trailing those fixed date warnings
found in the resource file, that refer to the given period; the warning
level is same as `-cy' option if the warning period refers to a year or
fiscal year or to a three month period respectively is same as `-cm'
option if the warning period refers to a month.

  In case you start Gcal without an explicit date and the *fixed date
warning* 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 date warnings found in the resource file,
that refer to the requested period and trailing all holidays of the
eternal holiday list that refer to the whole actual year without a
leading calendar.  For more details how to use an *eternal holiday
list*, see Eternal holidays.

*Annotation to previous examples:*

  In case an additional *standard/special calendar format* argument
(see `--type=special|standard') or an additional
*starting day of week* argument (see `--starting-day[=ARG]')
(except the `--starting-day=today' respectively the
`--starting-day=0' option) 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 before all
other lists.

  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 warning* argument (with optional modifiers) and the
*number of blocks* argument (see `--blocks=ARG'),
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 (==todays) date!  Gcal displays a leading year calendar and
all fixed date warnings, found in the resource file, that refer to the
actual day (week/month/year) of the actual year.

  You can list fixed date warnings of past, present or future
month/years, too.  This can be done on the one hand, if you use the
`%DATE' option in the fashion 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 1993'
     List all date entries related to entire 1993 and all eternal date
     entries related to entire 1993 in ascending order; the warning
     level is same as `-cy' option.

`gcal -c- july:1993'
     List all date entries related to fiscal year - starting in July
     1993 and ending in June 1994 - and all eternal date entries
     related to fiscal year - starting in July 1993 and ending in June
     1994 - in descending order; the warning level is same as `-cy'
     option.

`gcal -ce july 1993'
     List all date entries related to July 1993 and all eternal date
     entries related to July 1993 and all eternal holiday entries
     related to July 1993 in ascending order; the warning level is same
     as `-cm' option.

`gcal -c-e 1993'
     List all date entries related to entire 1993 and all eternal date
     entries related to entire 1993 and all eternal holiday entries
     related to entire 1993 in descending order; the warning level is
     same as `-cy' option.

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

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

Gcal uses a special file searching mechanism:

  1. The Gcal program expects the standard resource file in the actual
     directory and looks in this directory first.

  2. If the above action fails, Gcal inspects 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.

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

  4. If the above action fails, Gcal inspects the *user library*
     directory (normally `$HOME/lib/gcal-lib') to find the standard
     resource file.  This directory is a directory relative to the
     `HOME' directory.  If an environment variable `GCAL_USR_LIBDIR' 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_LIBDIR).
     If no `HOME' environment variable is defined and set, Gcal omits
     this step.

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

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

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

  An "extended file name" contains one ore more `/' (3) (slash)
characters 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" does denote 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 `./gcalrc'.

  (2)  The environment variable `PATH' is used on MS-DOS for this, and
the environment variable `DPATH' is used on OS/2 for this.

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

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

  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 warning entry in a resource
file must be splitted into two parts, namely a *date part* and an
optional *text part*, which *must* be separated by *one* "whitespace"
character (Tab, Space, Form-Feed ...) minimum (except of *local date
variable* assignments/operations).  It's not necessary 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.  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 is:

     date part [ *whitespace* text part ] *newline*

or more concrete, e.g.:

     YYYY[MM[DD|WWW[N]]][*whitespace*TEXT]*newline*

or much more concrete, e.g.:

     19940217 Hi, I'm the text!

The maximum length of a line is limited to INT_MAX (1) characters.

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

  (1)  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|WWW[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.

    `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.  If the computed date doesn't occur in year,
          i.e. exceeds the year bounds, the fixed date warning message
          is suppressed.

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

*Or*: `YYYY@e|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.

    `@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.  If the computed date
          doesn't occur in year, i.e. exceeds the year bounds, the
          fixed date warning message is suppressed.

*Or*: `YYYY@e|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.

    `@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.  If the computed
          date doesn't occur in year, i.e. exceeds the year bounds, the
          fixed date warning message is suppressed.

*Or*: Any of these date variable assignments respectively operations...

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

*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 of a Gcal resource file may be provided with further
attributes, which 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, which are structured as
follows, may be provided generally with further attributes:

   * `YYYYMM...'

   * `YYYY*d|w...'

   * `YYYY@e|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, 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
unconcrete therefore, which wouldn't make any sense in this coherence.

  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 1'st
and the 15'th 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 1'st of the month and another entry for the 15'th
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 1'st and the 15'th day in every month, namely

     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|DVAR,|[+|-]N[WWW],[+|-]N[WWW] ...'

  Some examples to this:

`000001fr3,12,99,mon,apr14,993,julfri3,08fr'
     In every year in January: on the 3'rd Friday, on the 12'th, on the
     last day of the month and on every Monday.  And in every year: on
     the 14'th April, on the 3'rd December, on the 3'rd 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 12'th.

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

`1996*w1fr,1,17mo,99fr'
     In the year 1996: on Friday of the 1'st ISO-week, on Monday of the
     first ISO-week, on Monday of the 17'th 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.

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 unconcrete therefore, which wouldn't make any
sense in this coherence.

  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 1'st and the 15'th 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 1'st of
the month, another one for the 2'nd of the month until the 15'th of the
month, which would be a total of 15 entries in the resource file for
such a fixed date (apart from the possibility, that a list of days can
be used in such a case).

  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 1'st until the 15'th day in every month, namely

     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|DVAR[[+|-]N[WWW]]#[+|-]N[WWW]'

  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 3'rd Friday of the month until the 12'th of the month.

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

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

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

`0*d1#1fr'
     In every year: every day that appears within the period of the
     1'st day of the year until the 1'rd 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 333'rd day of the year.

`1996*w1fr#17mo'
     In the year 1996: every day that appears within the period of the
     Friday of the 1'st ISO-week until the Monday of the 17'th 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 4'th 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 9'th
     Friday after the date of the Easter Sunday's date.

Repetition factor of days
.........................

  A repetition factor of days (`:N') is specified by a `:' character
and must trail the day field, which must have a concrete value in a
date part of a Gcal resource file and has not been set to a zero value,
respectively either lead or trail an appearance factor of days.  Except
ranges of days or fixed dates, which occur only on a definite weekday
like `199600mon Every Monday 1996', such a repetition factor may be
specified in all possible codings of date parts of a Gcal resource file.

  This factor may have values in range `1'...`999'.  Values greater
than the real difference between the date of the first occurrence of
the fixed date und the last day of the year are always reduced to this
real difference.  In this sense, any value greater `365' (or `366' in
leap years) means a repetition factor until the last day of the year.

  A repetition factor 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 15'th day in every month of the year 1996 and covers a
period of four days (inclusive the 15'th itself), e.g. `Co-workers
training', one solution would be on the one hand a fixed date entry in
the resource file for the 15'th of the month and the succeeding three
days, which would be a total of four entries in the resource file for
such a fixed date (apart from the possibility, that a list or a range
of days can be used in such a case).

  On the other hand, this expense can be reduced to a total of only one
entry in the resource file by using a repetition factor of days, which
is likewise valid for the 15'th and the three days, which succeed the
15'th in every month, namely

     19960015:4 Co-workers training

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

   * `YYYYMMDD:N|WWWN:N'

   * `YYYY*d|wN:N|NWWW:N'

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

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

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

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

  Some examples to this:

`000001fr3:11'
     In every year in January: every day that appears within the period
     of the 3'rd Friday of the month and the succeeding ten days.

`00000112:3'
     In every year in January: every day that appears within the period
     of the 12'th of the month and the succeeding two days.

`00000112:3,fr3:5'
     In every year in January: every day that appears within the period
     of the 12'th of the month and the succeeding two days, and that
     appears within the period of the 3'rd Friday of the month and the
     succeeding four days.

`0*d1:1'
     In every year: every day that appears within the period of the
     1'st day of the year and no succeeding day.

`0*d1:2'
     In every year: every day that appears within the period of the
     1'st day of the year and the succeeding day.

`0*d99fr:333'
     In every year: every day that appears within the period of the
     last Friday of the year and the succeeding 332 days.  Well, in
     cases a fixed date exceeds the year bounds, it will only be
     produced until the last day of the year.

`1996*w1fr:17'
     In the year 1996: every day that appears within the period of the
     Friday of the 1'st ISO-week and the succeeding 16 days.

`0@a:4'
     In every year: every day that appears within the period of the
     date of the date variable A and the succeeding three days.

`1996@e-3:9'
     In the year 1996: every day that appears within the period of the
     date three days before the Easter Sunday's date and the succeeding
     eight days.

Appearance factor of days
.........................

  An appearance factor of days (`.N') is specified by a `.' character
and must trail the day field, which must have a concrete value in a
date part of a Gcal resource file and has not been set to a zero value,
respectively either lead or trail a repetition factor of days.  Except
fixed dates, which occur only on a definite weekday and are not
specified by using a range of days, like `199600mon Every Monday 1996',
such an appearance factor may be specified in all possible codings of
date parts of a Gcal resource file.  This factor may be specified with
each single element of lists of days, but in a range of days, this
factor may trail *only* the final day of the range.  Well, the use of
such an appearance factor is only helpful if it is either given in a
range of days, or if it is given together with a repetition factor.

  This factor may have values in range `1'...`999'.  Fixed dates will
be ignored if the factor takes values, which are greater than the real
difference between the date of the occurrence of the fixed date und the
last day of the year, respectively the end of the period, for which the
fixed dates shall either be produced or respected.

  An appearance factor of days is used to define a concrete
displacement of recurrent fixed dates.  Assuming a fixed date shall
always occur on the 15'th day in every month of the year 1996 and
covers a period of seven days (inclusive the 15'th itself), but shall
only be respected every third day (i.e. two days have to be skipped at
a time) within this period, e.g. `Training-college', one solution would
be on the one hand a fixed date entry in the resource file for the
15'th of the month, for the 18'th and for the 21'st of the month, which
would be a total of three entries in the resource file for such a fixed
date (apart from the possibility, that a list of days can be used in
such a case).

  On the other hand, this expense can be reduced to a total of only one
entry in the resource file by using an appearance factor of days, which
is likewise valid for the 15'th, the 18'th and the 21'st in every
month, namely on the one hand by the use of a repetition factor

     19960015:7.3 Training-college

  or on the other hand by the use of a range of days

     19960015#21.3 Training-college

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

   * `YYYYMMDD:N.N|DD.N:N'

   * `YYYYMMWWWN:N.N|WWWN.N:N'

   * `YYYY*d|wN:N.N|N.N:N'

   * `YYYY*d|wNWWW:N.N|NWWW.N:N'

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

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

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

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

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

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

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

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

   * `YYYYMMWWW#WWW.N'

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

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

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

  Some examples to this:

`000001fr3:11.3'
     In every year in January: every day that appears within the period
     of the 3'rd Friday of the month and the succeeding ten days, but
     only every 3'rd day within this period (skip two days at a time).

`00000112:3.2'
     In every year in January: every day that appears within the period
     of the 12'th of the month and the succeeding two days, but only
     every 2'nd day within this period (skip one day at a time).

`00000112:3.2,fr3:5.3'
     In every year in January: every day that appears within the period
     of the 12'th of the month and the succeeding two days, but only
     every 2'nd day within this period (skip one day at a time), and
     that appears within the period of the 3'rd Friday of the month and
     the succeeding four days, but only every 3'rd day within this
     period (skip two days at a time).

`0*d1:10.1'
     In every year: every day that appears within the period of the
     1'st day of the year and the succeeding nine days, and this for
     any day within this period (skip zero days at a time).

`0*d1:2.5'
     In every year: every day that appears within the period of the
     1'st day of the year and the succeeding day, but only every 5'th
     day within this period (skip four days at a time).  Well, the
     succeeding days (only one in this example) of the starting day
     (1'st day of year) are not respected, because the next day
     resulted by the appearance factor exceeds the final day (resulted
     by the repetition factor) of the period.

`0*d99fr:333.61'
     In every year: every day that appears within the period of the
     last Friday of the year and the succeeding 332 days, but only
     every 61'st day within this period (skip 60 days at a time). Well,
     in cases a fixed date exceeds the year bounds, it will only be
     produced until the last day of the year.  No succeeding day (332
     in this example) of the starting day (last Friday of the year) is
     respected by reason of the displacement value of 60 days, because
     the next day resulted by the appearance factor exceeds the final
     day (resulted by the repetition factor) of the period (the last
     day of the year).

`1996*w1fr:17.8'
     In the year 1996: every day that appears within the period of the
     Friday of the 1'st ISO-week and the succeeding 16 days, but only
     every 8'th day within this period (skip seven days at a time).

`0@a:4.3'
     In every year: every day that appears within the period of the
     date of the date variable A and the succeeding three days, but
     only every 3'rd day within this period (skip two days at a time).

`1996@e-3:9.4'
     In the year 1996: every day that appears within the period of the
     date three days before the Easter Sunday's date and the succeeding
     eight days, but only every 4'th day within this period (skip three
     days at a time)..

`1996@e3#-20so.15'
     In the year 1996: every day that appears within the period of the
     date three days after the Easter Sunday's date until the 20'th
     Sunday before the Easter Sunday's date, but only every 15'th day
     within this period (skip 14 days at a time).

Text part of a line
-------------------

  The "text part" of a line in a resource file can be any text you like.
If the text part contains characters, which are used for highlighting
the text or format it for a printer, or characters with decimal values
above 127 in the code table of the used character set (these are
potentially non-printable), which are not produced by Gcal itself, such
characters respectively sequences are displayed by Gcal in an
*uninterpreted* manner!  For that very reason it can happen that the
output of such characters can potentially create problems with the used
screen device driver software and/or the external pager program,
likewise mailing of such texts by means of electronic mail.

  So-called `NUL' characters (that's the character with the value zero
in the code table of the used character set) may occur too in the text
part, but their effect is only the suppression of all succeeding
characters of the line.  In my opinion it makes no perceptible sense to
output these `NUL' characters uninterpreted so they are used for
remarking purposes only; besides the `NUL' characters would cause the
same problems already mentioned above.

  A line of the resource file is continued on the next line if a `\-\n'
backslash-newline character sequence is found, e.g.:

the line:
     000000Mo Every Monday

and the lines:
     000000Mo \
     Every \
     Monday

produce the same output and are essentially equivalent.

  Furthermore you can break up the text of a *long* resource file line
at any place your like.  The term *long* means in this context, that the
text displayed by Gcal would override the right text margin of the
screen respectively break up at that margin.  Each time a `~' (tilde)
character is found in the text part, this character is replaced by a
real `\n' (newline) character.  Such texts will be displayed by Gcal in
a formatted manner at a left margin.

  You may quote the `~' (tilde) character - in case this character
itself is needed - by placing a `\' (backslash) character before it,
e.g. `\~'.

  If you need the characters `\~' itself, you have to quote the `\'
(backslash) character by itself, e.g. `\\~'.

The resource file `example.rc'

     ;
     ; Hi, I'm `example.rc' and alive now
     ;
     0 I know I'm a short text
     0 I hope I'm long enough~here, a line break up\
     ~and again~and now for the last time...
     0 Am I another short text? Dunno...

is displayed as follows:

     $ gcal --resource-file=example.rc --disable-highlighting

     => Fixed date list:
     =>
     => Wed, Sep  14'th 1994: Am I another short text? Dunno...
     => Wed, Sep  14'th 1994: I hope I'm long enough
     =>                       here, a line break up
     =>                       and again
     =>                       and now for the last time...
     => Wed, Sep  14'th 1994: I know I'm a short text

Comment line
------------

  A line beginning with a `;' (semicolon) character in the resource file
is treated as a remark and will not be used by Gcal!  Any *whitespace*
characters may lead the remark character.  For information for how a
`NUL' character can be used for remarking in a text part, see
Text part of a line.

Include statements
------------------

  You may add "#include" statements in a resource file (a mechanism
similar the method, which is used by the C Preprocessor) for searching
and loading further resource files, e.g.:

  1. #include "foo/bar"

  2. #include <bar>

  The first *#include* statement tells Gcal to load the file `bar' from
the directory `foo' using steps 1...5 of the previously explained
mechanism, which is used for searching files (see File searching mechanism).

  The second *#include* statement tells Gcal to load the file `bar'
from the user respectively system library directory using steps 4...5
of the previously explained mechanism, which is used for searching
files.  It is not allowed to include files, which have a fixed access
path starting from the root directory by such a *#include* statement
like `#include </file>' or `#include </foo/bar/file>'; just as the
specification of a single or an extended file name containing a
disk/drive specifier (even if operating systems like MS-DOS or OS/2
would permit such a disk/drive specification on principle), because the
resulting path name (lead by the user respectively system library
directory name) wouldn't be a valid file name anymore.

  Included files may include other files again.  But the nesting level
of included files is limited on the one hand by the amount of useable
working storage of the computer, and on the other hand by the value,
which is given by the operating system respectively the compiler for
the number of files which can be opened simultaneously.  Recursive
includes (1) or cyclic includes (2) are not permitted, because such
backward references would produce an infinite loop in the program
internally!

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

  (1)  The included file tries to include itself again

  (2)  The included file is included again by another file, which
occurs at a deeper place of such a chain

Special macro texts
-------------------

  The text part of a resource file line may contain 14 different,
special macro texts, which may occur in any (senseful) number and
order.  These texts start with a `%' (percent) character, which may be
quoted by a leading `\' (backslash) character if the `%' (percent)
character itself is wanted to be used in the text part, e.g. `\%'.

     *Please note:*
     The optional date after the `%b...', `%y...', `%s...' and `%e...'
     macro texts may be denoted either using the date format
     `YYYY[MM[DD|WWWN]]', `YYYY*d|wN[WWW]' or `YYYY@e|DVAR[[+|-]N[WWW]]'
     date format.

%s macro text
.............

  `%s[YYYY[MM[DD|WWWN]]]' references the "starting date" of the fixed
date, i.e. the first date the fixed date may occur.  If the date, which
is encoded in the `%s...' macro text, is later the current respectively
queried date, so the complete warning text will be suppressed.  If the
warning text must be shown, the text of this macro is always suppressed
in output.  This macro text *must* have a trailing *whitespace*
character.

   * If YYYY... is not given (==*no* date encoded), the 01 January of
     current year is assumed for the date.

   * If YYYY is set to 0000, the current year is assumed for the year.

   * If MM is not given, then 01 (==January) is assumed for the month.

   * If MM is set to 00, the current month is assumed for the month.

   * If DD|WWW is not given, then 01 is assumed for the day.

   * If DD is set to 00, the current day is assumed for the day.

   * If the N field is given (range 1...5 or 9), a WWW field must be
     given then.

%e macro text
.............

  `%e[YYYY[MM[DD|WWWN]]]' references the "ending date" of the fixed
date, i.e. the last date the fixed date may occur.  If the date, which
is encoded in the `%e...' macro text, is earlier the current
respectively queried date, so the complete warning text will be
suppressed.  If the warning text must be shown, the text of this macro
is always suppressed in output.  This macro text *must* have a trailing
*whitespace* character.

   * If YYYY... is not given (==*no* date encoded), the 31 December of
     current year is assumed for the date.

   * If YYYY is set to 0000, the current year is assumed for the year.

   * If MM is not given, then 12 (==December) is assumed for the month.

   * If MM is set to 00, the current month is assumed for the month.

   * If DD|WWW is not given, then the last day of month MM is assumed
     for the day.

   * If DD is set to 00, the current day is assumed for the day.

   * If the N field is given (range 1...5 or 9), a WWW field must be
     given then.

%b macro text
.............

  `%b[YYYY[MM[DD|WWWN]]]' references a "year of birth" and is converted
to an *age value*, e.g.:

     The text `My %b1962 birthday%s1952 %e2062' will be expanded to
     ==> `My 32'nd birthday', in case the current year is 1994.

  Those age values are evaluated/respected only, if the computation of
an age value is greater zero.  The fixed date warning in preceding
example is displayed only in case the current year is greater than 1952
and less than 2062.  If the warning text must be shown, the text of
this macro is always suppressed in output.  This macro text *must* have
a trailing *whitespace* character.

   * If YYYY... ist not given (==*no* date encoded), the current date
     is assumed for the date.

   * If YYYY is set to 0000, the current year is assumed for the year.

   * If MM is not given or set to 00, the current month is assumed for
     the month.

   * If DD is not given or set to 00, the current day is assumed for
     the day.

   * If the N field is given (range 1...5 or 9), a WWW field must be
     given then.

%y macro text
.............

  `%y[YYYY[MM[DD|WWWN]]]' references any year and is converted to a
"year difference value", e.g.:

     The text `Sylvester 1912 is %y1912 years ago' will be expanded to
     ==> `Sylvester 1912 is -82 years ago', in case the current year is
     1994.

  If the warning text must be shown, the text of this macro is always
suppressed in output.  This macro text *must* have a trailing
*whitespace* character.

   * If YYYY... is not given (==*no* date encoded), the current date is
     assumed for the date.

   * If YYYY is set to 0000, the current year is assumed for the year.

   * If MM is not given or set to 00, the current month is assumed for
     the month.

   * If DD is not given or set to 00, the current day is assumed for
     the day.

   * If the N field is given (range 1...5 or 9), a WWW field must be
     given then.

%m macro text
.............

  `%m' references the current respectively queried "month number"
relative to the actual (==todays) date.

%w macro text
.............

  `%w' references the current respectively queried "week number"
relative to the actual (==todays) date.

%d macro text
.............

  `%d' references the current respectively queried "day number"
relative to the actual (==todays) date, e.g.:

     A resource file line like `0 %d days gone' will be expanded to
     ==> `-10 days gone', in case you call Gcal with the `-c10-' option
     and no command.

%j macro text
.............

  `%j[[-]N]' references the current respectively queried "Julian Day
number" relative to the actual (==todays) date.  This day number is
tied with the date 1'st January 4713 BCE, which is the starting day
zero of a consecutive day counting used in astronomical computations
and is known as the Julian Date (J.D.).  The real zero of this date is
at 12 o'clock universal time; the day doesn't change at midnight, but
at noon universal time.  Actually, Gcal does not evalute the time zone,
which is returned by the systems date function.  For that reason, this
day number is represented without a time fraction on the supposition
that the day has already changed at noon.  If you don't like the
feature that the day has already changed at noon, you can decrease the
resulting Julian Day number of that macro text always by one, e.g.
`%j-1'.

  For example:

     The line `0 Julian Day %j since 01-Jan-4713 BCE' will be expanded
     to
     ==> `Julian Day 2437929 since 01-Jan-4713 BCE', in case you call
     Gcal with the `-c %19620921' option and no command.

  If the `%j' text is directly trailed by a number, this number is
always subtracted from the real Julian Day number (a negative sign can
be given to increase the readability of this expression), so you are
able to work with any reference values, e.g.:

     The line `0 Julian Day %j-2415021 since 01-Jan-1900' will be
     expanded to
     ==> `Julian Day 4 since 01-Jan-1900', in case you call Gcal with
     the `-c %19000105' option and no command.

%n macro text
.............

  `%n[[+|-]N]' references the current respectively queried "day number"
relative to the current date `+/-' N days and is converted to an
effective "date text", e.g.:

     A resource file line like `1962Sep21 10000 days old: %n+10000'
     will be expanded to
     ==> `10000 days old: Feb-06-1990', in case you call Gcal with the
     simple `-c' option and the command `sep 1962' (see `MM YYYY').

%t macro text
.............

  `%t[12|24]' references the "actual system time", e.g.:

     The text `Time: %t --> Dentist at 10:00' will be expanded to
     ==> `Time: 07:32 --> Dentist at 10:00', in case the actual system
     time value is 07:32 (hh:mm).

  A system time value is always displayed in the *24-hour* format by
default.  For displaying in the *12-hour* format, add `12' behind `%t',
e.g. `%t12'.

%1 macro text
.............

  `%1' is replaced by the starting highlighting sequence respectively
the starting marking character, which is used for highlighting the
actual day, (see `--highlighting=ARG').  This attains
that all succeeding text of the line after this macro text is displayed
in the same way as the highlighted respectively marked actual day.  `%1'
is used together with the `%2' macro text, which turns off this enabled
highlighting sequence respectively produces the ending marking
character.  If a `%1' text is not succeeded by a `%2' text on the line,
Gcal automatically inserts such a `%2' text at the end of the line.

  For example:

     Only %1THIS%2 word is highlighted in this line.
     %1This text is highlighted up to%2 here.
     All from %1here up to the end of the line is highlighted.