
  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

Gcal
****

  Gcal is 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.

  This is Edition 2.05 of the Gcal documentation, 16 July 1996, for
Gcal 2.10.

  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

Gcal Introduction
*****************

  Apart from the usual and well known calendar functions like the
output of a month or a year calendar sheet, or the output of an eternal
holiday list, Gcal offers the facility to display fixed dates on the
day of their occurrence and to remind or inform the user about them.
So it's imaginable after booting the computer or starting the work
session, that the user is informed on screen or by means of electronic
mail, about all holidays or appointments, which are observed or
scheduled for that day.

  The period, for which Gcal respects occuring fixed dates, may be
freely selected by the user.  So it is possible that Gcal displays all
fixed dates, which occur on tomorrow's date, the whole week, the whole
month or in the whole year.  Fixed dates which occur on a selected date
of the year and those that occur relative to another given date, are
displayed either related to this single date only or in listed manner
starting at this date and ending (inclusive or exclusive) at the actual
date.

  There are two ways to display a preview of fixed dates (future years)
or retrospective view of fixed dates (past years).  On the one hand,
Gcal can be started using an option, which sets the system date of the
computer to the given date during the time of the program execution
with the result, the program assumes the system date is set to this
given date and the user can define any needed period, which should be
respected, by an option.  On the other hand, Gcal can be started with a
command, which forces the program to use a different year instead of
the actual year, so Gcal will display all occuring fixed dates for this
particular year.  But this limits the user in that it disables defining
any needed period by an option, because the period is always set to the
whole year by default.

  Gcal isn't only able to display fixed dates, which are stored for a
concrete date, e.g. `Fixed date on 1st December 1995', rather than
fixed dates occuring periodically again and again.  So it's possible to
define repeated events like `This fixed date occurs all days in May
1995' or `Every 15th November in any years'.  These fixed date
definitions are stored in resource files and whenever Gcal is started,
an option to evaluate the necessary resource files can be given.

  Once the user has set his/her preferred command line arguments for
querying the fixed dates data base, it is possible to store them in a
response file or shell script file.  A response file contains all
arguments delivered to Gcal, but unlike a shell script file, such a
response file isn't executable; it is only a pool of command line
options that can be preloaded if needed.  A shell script file can be
started and calls Gcal directly with all arguments, which are stored in
it and all arguments, which are given further in the command line.

  A description of all usable command line arguments and their
descriptions is listed in the next chapter, which helps one use Gcal in
the most efficient and productive way possible.

Invoking Gcal
*************

  Gcal is a command line oriented program.  It is usually called from a
"shell" (this is an operating system program, which interprets and runs
given command lines) and processes given arguments, which are options
and commands.  Options must be given before commands, i.e. you must
call Gcal in this way:

             gcal [ [OPTION...] [%DATE] [@FILE...] ]  [COMMAND]


  If Gcal is started without any options or commands, a calendar of the
current month is displayed.  If the calendar of a definite year is
wanted, the year must be fully specified, e.g. `gcal 94' displays a
year calendar of the year 94, not of the year 1994.

  If two arguments are given in the command part, the *first* argument
denotes the month and the *second* argument denotes the year.  In case
any illegal commands are given running Gcal, the program will use
internal defaults.

  In the English program version, Gcal assumes the Gregorian
Reformation have occurred in 1752 on the 3rd of September, see *Note
Todays calendar::, and *Note Internationalization:: for more details.

Command line arguments
======================

  This section describes all command line arguments processed by Gcal.
Four different types of command line arguments exists.  One important
type of argument are the "options" which control how Gcal behaves.
Other types of arguments are the `%DATE' and the `@FILE' options.  The
`%DATE' option sets the period Gcal shall work on to any starting date;
the `@FILE' option preloads options and commands from a response file.
The most important arguments are the "commands" which control the
periods Gcal respects.

  An option is defined by a leading "switch" character; either the `-'
(dash) or the `/' (slash) character for traditional short-style options,
or `--' for mnemonic long-style options; a command may not have a
leading switch character!  Options (inclusive `%DATE' and `@FILE')
*must* be given before commands!

  Depending on operating system and used shell, some of the arguments
and texts given in command line must be quoted by `"' or `'' characters
respectively protected by a `\' character to avoid expansion by the
shell.

  Here is an incomplete list of characters, which must potentially be
protected:

     `(', `)', `<', `>', `[', `]', `{', `}', `\', `|', `$', `@', `!',
     `&', `~', `"', `'', ``', `;'

Options
-------

  The options processed by Gcal can be grouped into four major option
classes.  The options of the "common option class" are the standard
options all GNU software should implement at least partially.  The
"global option class" contains options which modify the program output.
The options of the "calendar option class" control the calendar
layout, and the options of the "date warning option class" control the
date warning layout and intensity.

  Gcal supports both short-style options and GNU long-style options.
Traditional short-style options are indicated by a single switch
character and trailed by the option character itself and perhaps a
modifier or an argument.  The most single character options (unless
they take an argument) can be composed into a single command line word:
`-Ax' is equivalent to `-A -x'.  GNU long-style options are indicated
with `--' and trailed by the mnemonic option name itself and perhaps an
argument.  Long-style options and their arguments may be abbreviated if
done unambiguously.  When a long-style option takes an argument,
connect the option name and the argument with `='.

  Brackets ([ and ]) indicate that an option takes an optional
argument.  The `|' character is used to separate several selectable
arguments from each other.

Gcal processes the GNU long-style options in a special, non-standard
way.  There are five different types of long-style options:

  1. `--foo'
     Enables option `--foo'.

  2. `--foo=BAR'
     Enables option `--foo' with required argument BAR.

  3. `--foo[=BAR[|...|BAR]]'
     Option `--foo' may have one BAR argument.  If no argument list is
     given, any argument can be given to this option.  If an argument
     list is given, exactly one BAR argument may be selected from given
     list.  If there is no argument choosen in this case, the first BAR
     argument of the argument list is pre-selected by default.

  4. `--foo=BAR|...|BAR'
     Option `--foo' requires exactly one BAR argument, which must be
     selected from given argument list.

  5. `--foo=BAR|...|BAR|BAZ'
     Option `--foo' requires exactly one BAR argument, which must be
     selected from given BAR argument list, or the alternative BAZ
     argument.

Traditional short-style options differ as follows:

  1. `-x'
     Enables option `-x'.

  2. `-x BAR'
     Enables option `-x' with required argument BAR.  The BAR argument
     may be separated by a leading *whitespace* character from the
     short-style option character `x'.  This means following notations
     are valid for giving an argument, namely `-x BAR' or `-xBAR'.

  3. `-x[BAR|...|BAR]'
     Option `-x' may have one or more BAR "modifier".  In this sense,
     modifiers are one or more characters which define a special mode
     of operation enabled by the `-x' option.  A modifier may not be
     separated by a leading *whitespace* character from the short-style
     option character.

Common options
..............

`-?'
`-h'
`--help'
     Print a short usage message listing most of all available options,
     then exit successfully.

`-??'
`-hh'
`--usage[=ARGUMENT]'
`--long-help[=ARGUMENT]'
     Print an extended usage message listing all available options,
     then exit successfully.  If ARGUMENT is given and is a valid
     long-style option name, an extended help text related to the given
     long-style option name is displayed only, e.g.:

          --long-help=long-help

     displays the extended help text for the long option `--long-help'.

     If ARGUMENTS consists only of a single `?' character or is no
     valid long-style option name, a list of all valid long-style
     option names is displayed.

`-L'
`--license'
`--copyleft'
`--copyright'
     Print the software license message, then exit successfully.

`-V'
`--version'
     Print the version number and compilation options, then exit
     successfully.

`--exit-status-help-127'
     Set exit state of program to 127 instead to 0, if one of the other
     options of the *common option class* is used.

Global options
..............

`-R NAME'
`--response-file=NAME'
     Write contents of environment variable `GCAL' (*note GCAL:
     Environment variables.) and then arguments of command line (in the
     given order) to file NAME, i.e. create response file `name'.
     *Note Response file::, for more details.

`-S NAME'
`--shell-script=NAME'
     Write contents of environment variable `GCAL' (*note GCAL:
     Environment variables.) and then arguments of command line (in the
     given order) to shell script file NAME, i.e. create file `name'.
     An automatically created shell script file is executable and calls
     Gcal directly with the arguments, which are stored in it.  You may
     start the shell script with other command line arguments, which
     are directed to Gcal too.

`--debug[=internal|handled|unhandled|all|abort]'
     Display some debug informations.

    `--debug=internal'
          Display warnings if program internal maximums are reached.

    `--debug=handled'
          Like `--debug=internal' and display file names which are
          handled, too.

    `--debug=unhandled'
          Like `--debug=internal' and display file names which are
          unhandled, too.

    `--debug=all'
          Like `--debug=handled' and `--debug=unhandled' together.

    `--debug=abort'
          Like `--debug=all' and abort program with error if file name
          can't be handled, see *Note 118: Error codes.

`-p'
`--pager'
     Enables either an *external* pager or a simple *internal* pager.
     If an environment variable `PAGER' is set, its value will be used
     for detecting the external pager program.  *Note PAGER:
     Environment variables, for more information.

     If no `PAGER' environment variable is set or if its value is
     invalid, Gcal tries to use the `less' pager; if this program can't
     be found during scanning the `PATH' environment variable, Gcal
     tries to use the `more' pager, if this program can't be found, the
     `pg' pager in the same way (1).  *Note PATH: Environment variables.

     If all these actions fail, Gcal will use its simple, built-in
     pager.  If the internal pager is used, Gcal detects the number of
     lines shown before it prompts and waits for user input using these
     methods:

       1. Gcal respects the values set in the environment variables
          `LINES' and `COLUMNS'.  *Note LINES: Environment variables,
          and see *Note COLUMNS: Environment variables, for more
          details.

       2. If above action fails, Gcal respects the values set in the
          environment variables `LI' and `CO'.  *Note LI: Environment
          variables, and see *Note CO: Environment variables, for more
          details.

       3. If above actions fails, Gcal uses a system dependent
          *low-level* function (on MS-DOS, OS/2 and some other
          operating systems) and respects the reported values.

       4. If above action fails, Gcal respects the values set in the
          `termcap' (2) file, which refers to the terminal used (*note
          TERM: Environment variables.).  This step is only done on
          systems which support the use of Termcap by default.

       5. If all above actions fail, Gcal uses default values (either
          23 or 24 lines, 80 columns).

`-H yes'
`--force-highlighting'
`--highlighting=yes'
     If output of the program is redirected or piped, the highlighting
     sequences are *not* converted automatically into the according
     marking characters, they remain unchanged.  This option has no
     effect if the output of the program is send by means of electronic
     mail, see *Note `--mail=ADDRESS': Global options.

`-H no'
`--disable-highlighting'
`--highlighting=no'
     Disable highlighting sequence / marking character pairs of current
     day, holiday respectively text explicitly.

`-H TEXT'
`--highlighting=TEXT'
     Set highlighting sequence / marking character pairs explicitly.
     In this sense, "highlighting" sequences are control character
     sequences which cause a colour or intensity switch of output text.
     Typical control character sequences are the ANSI escape
     sequences, which have a leading escape character and trailing more
     characters, which define the type of the ANSI escape sequence.  In
     this sense, "marking" characters are single, printable characters,
     which lead and succeed the output text.

     The TEXT argument must be a (`:') colon-separated text, which is
     structured in this way: SEQ1_START:SEQ1_END:SEQ2_START:SEQ2_END.
     The *first* sequence is used for highlighting/marking the actual
     day, the *second* for holiday.  The sequences must be given in
     form of a sequence pair; SEQ?_START enables the
     highlighting/marking, SEQ?_END disables it.  Only two sequence
     pairs will be processed, others are ignored.  Either highlighting
     sequence pairs or marking character pairs may be defined, i.e.
     using them both in a mixed couple is not allowed!

     Some examples:

          `-H \x20:\x20:\x1:#' respectively
          `--highlighting=\x20:\x20:\x1:#'
          marks the actual day like `\x20ACTUAL DATE\x20' (this means
          with leading and trailing blanks) and the holiday date like
          `\x1HOLIDAY DATE#' using given marking characters.

          `-H \x1b[34;42m:\x1b[0;40m' or
          `-H \033[34;42m:\033[0;40m' or
          `-H \E[34;42m:\E[0;40m'
          defines a starting ANSI escape highlighting sequence
          `\x1b[34;42m' used for actual day and ending ANSI escape
          highlighting sequence `\x1b[0;40m' with no given highlighting
          sequence for holiday, so default highlighting sequences for
          holidays are used (non-notated entries are always skipped).
          Please note the last abstract of this text part, which
          informs you more detailed to this coherence. *Note GCALANSI:
          Environment variables.

     Control code definitions may contain any printable characters.
     Non-printable characters may be encoded in octal or hexadecimal
     notation.  The abbreviation `\E' directly encodes the escape
     character (octal `\033' respectively hexadecimal `\x1B').

     A character can be encoded octal by typing `\NNN'
     (backslash-octal digit(s)), where N must be a valid octal digit
     (0...7).  Normally, three octal digits must be given.  If the octal
     character code consists of one or two octal digits, leading zeroes
     must be added; except the case where the encoded octal character
     is given last in single sequence.

     A character can be encoded hexadecimal by typing `\xNN'
     (backslash-x hexadecimal digit(s)), where N must be a valid
     hexadecimal digit (0...9A...Fa...f).  Normally, two hexadecimal
     digits must be given.  If the hexadecimal character code consists
     of one hexadecimal digit, a leading zero must be added; except the
     case where the encoded hexadecimal character is given last in
     single sequence.

     If the sequence separator character, the `:' (colon) character
     itself is used for marking character, it must be encoded either
     octal by `\072' or hexadecimal by `\x3A'.

     If the C Preprocessor symbol USE_PAGER was defined and output of
     program is redirected or piped, the highlighting sequences are
     converted automatically into the according marking characters; if
     USE_PAGER was not defined, they remain untouched.

     Incomplete or no given highlighting sequences will be replaced by
     internal default ANSI escape highlighting sequences if a `GCALANSI'
     environment variable is defined; otherwise completely replaced by
     their according marking characters.  *Note GCALANSI: Environment
     variables.

`-m ADDRESS'
`--mail=ADDRESS'
     Send Gcal's output via `mail' (3) program to Email-address
     ADDRESS, e.g.:

          --mail=root
          -m esken@uni-muenster.de

     All highlighting sequences produced by Gcal itself are always
     disabled respectively converted automatically into the according
     marking characters if an Email must be send; no matter if the
     `--force-highlighting' option was given or not.  This behavior of
     Gcal is an imperative necessaty, because it is possible that the
     `mail' program cannot perform the mailing correctly.  Please pay
     attention in this context to the further explanations concerning
     the limitations of the *text part* of a resource file line (*note
     Text part of a line::.).

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

  (1)  See the standard manual pages for `less', `more' and `pg'.

  (2)  See the standard manual pages for Termcap.

  (3)  See the standard manual pages for `mail'.

Calendar options
................

`-n|N[-]'
`--holiday-list[=long|short]'
`--descending-holiday-list[=long|short]'
     Display the eternal holiday list.  *Note Eternal holidays::, for
     additional information.

    `-n'
    `--holiday-list=long'
          Display all holidays in eternal holiday list (this means all
          legal days and all further memorial days) sorted in ascending
          order.

    `-n-'
    `--descending-holiday-list=long'
          Display all holidays in eternal holiday list (this means all
          legal days and all further memorial days) sorted in
          descending order.

    `-N'
    `--holiday-list=short'
          Display legal days only in eternal holiday list sorted in
          ascending order.

    `-N-'
    `--descending-holiday-list=short'
          Display legal days only in eternal holiday list sorted in
          descending order.

`-X'
`--exclude-holiday-list-title'
     Suppresses the title text line of the eternal holiday list.

`--christan-holidays'
     Provides the eternal holiday list with additional Christian
     holidays.  Furthermore, all additionally highlighted days of the
     eternal holiday list are highlighted in the calendar sheets, too.

`--de-holidays'
     Provides the eternal holiday list with additional German holidays.
     Furthermore, all additionally highlighted days of the eternal
     holiday list are highlighted in the calendar sheets, too.

`--us-holidays'
     Provides the eternal holiday list with additional U.S. American
     holidays.  Furthermore, all additionally highlighted days of the
     eternal holiday list are highlighted in the calendar sheets, too.

`-i[-]'
`--type=special|standard'
     To get the "standard" calendar format (similar BSD-`cal'), start
     Gcal omitting the `-i[-]' option because it is set by default.
     *Note Internationalization::, for more details.  Or start Gcal with
     the `-i-' respectively the `--type=standard' option to force the
     output of a calendar sheet:

          $ gcal -i-
          -|
          -|    September 1994
          -| Su Mo Tu We Th Fr Sa
          -|              1  2  3
          -|  4  5  6  7  8  9 10
          -| 11 12 13 14 15 16 17
          -| 18 19 20 21 22 23 24
          -| 25 26 27 28 29 30

     To get the "special" calendar format and to force the output of a
     calendar sheet, start Gcal with the `-i' respectively the
     `--type=special' option:

          $ gcal -i
          -|
          -| September 1994
          -|
          -| Sunday          4 11 18 25
          -| Monday          5 12 19 26
          -| Tuesday         6 13 20 27
          -| Wednesday       7 14 21 28
          -| Thursday     1  8 15 22 29
          -| Friday       2  9 16 23 30
          -| Saturday     3 10 17 24

`-u'
`--suppress-calendar'
     Suppress output of calendar sheet explicitly.

`-b NUMBER'
`--blocks=NUMBER'
     Set NUMBER of calendar sheet blocks (valid arguments:
     `1|2|3|4|6|12').  The default NUMBER for the *standard* calendar
     format is `-b4 ' respectively `--blocks=4', and for the *special*
     calendar format `-b 3' respectively `--blocks=3'.  If this option
     is found, the program sees that a year calendar output is desired!

    `-b 1'
    `--blocks=1'
          Displays one block with twelve months at a time.

    `-b 2'
    `--blocks=2'
          Displays two blocks with six months at a time.

    `-b 3'
    `--blocks=3'
          Displays three blocks with four months at a time.

    `-b 4'
    `--blocks=4'
          Displays four blocks with three months at a time.

    `-b 6'
    `--blocks=6'
          Displays six blocks with two months at a time.

    `-b 12'
    `--blocks=12'
          Displays twelve blocks with one month at a time.

`-j[b]'
`--calendar-dates=special|both'
     Use alternative date format in calendar sheet instead of the
     default standard format, which displays the days of month in
     consecutive manner.

    `-j'
    `--calendar-dates=special'
          Display the calendar sheet using the special date format.
          This means the days of year are displayed in consecutive
          manner instead of the days of month.

    `-jb'
    `--calendar-dates=both'
          Display the calendar sheet using the standard and special
          date format.

`-jn[b]'
`--holiday-dates=special|both'
     Use alternative date format in eternal holiday list instead of the
     default standard format, which displays the days of month in
     consecutive manner.  *Note `--holiday-list[=long|short]': Calendar
     options.

    `-jn'
    `--holiday-dates=special'
          Display the eternal holiday list using the special date
          format.  This means the days of year are displayed in
          consecutive manner instead of the days of month.

    `-jnb'
    `--holiday-dates=both'
          Display the eternal holiday list using the standard and
          special date format.

`-jc[b]'
`--fixed-dates=special|both'
     Use alternative date format in fixed date warning list instead of
     the default standard format, which displays the days of month in
     consecutive manner.  *Note `--list-of-fixed-dates[=short|long]':
     Date warning options.

    `-jc'
    `--fixed-dates=special'
          Display the fixed date warning list using the special date
          format.  This means the days of year are displayed in
          consecutive manner instead of the days of month.

    `-jcb'
    `--fixed-dates=both'
          Display the fixed date warning list using the standard and
          special date format.

`-s ARGUMENT'
`--starting-day=ARGUMENT'
     Set the starting day of week (valid ARGUMENT:
     `0, 1...7 | today | WEEKDAY NAME').

     Example:

          --starting-day=Sunday or
          --starting-day=7 or
          -s SUNDAY or
          -s sund or
          -s Su or
          -s 7

     thus all specifies the Sunday (1==Mon, 2==Tue ... 7==Sun).

     If the `-s today' option (or `--starting-day=today') or the `-s 0'
     option (or `--starting-day=0') is given, the starting day of week
     is set to the actual weekday.

     *Note Internationalization::, for more details.

`--gregorian-reform=1582|1752|ARGUMENT'
     Set the period which was skipped during the Gregorian Reformation.
     *Note Internationalization::, for more details.  Actually, two
     fixed default periods (on the one hand of the year 1582 and on the
     other hand of the year 1752) are supported.  If Gcal is called
     with the `--gregorian-reform=1582' option, it assumes the
     Gregorian Reformation have occured from 5th till 14th October
     1582.  If Gcal is called with the `--gregorian-reform=1752'
     option, it assumes the Gregorian Reformation have occured from 3rd
     till 13th September 1752.

     In case another period shall be respected, it can be arranged by
     the option argument ARGUMENT like `YYYY,MM,FIRST DAY,LAST DAY'.
     If the Gregorian Reformation have occured for example on the 7th
     till the 17th April 1802, this can be declared as follows:

          --gregorian-reform=1802,4,7,17

`--date-format=de|us|gb|TEXT'
     Set the date format which controls the ordering and representation
     of a displayed date.  *Note Internationalization::, for more
     details.  The date format text is respected by Gcal in the eternal
     holiday list, in the fixed date warning list and the calendar
     sheets.  Moreover, Gcal internally tries to obtain the best
     representation of a displayed date in case the days of the year
     instead of the days of the months must be displayed.

     Actually, three fixed default date formats (for German users, U.S.
     American users and for users in Great Britain) are supported.  If
     Gcal is called with the `--date-format=de' option, the
     `%w,  %1%D%2 %b %y' format text is used.  If Gcal is called with
     the `--date-format=us' option, the `%W, %b  %1%U%2 %y' format text
     is used.  If Gcal is called with the `--date-format=gb' option, the
     `%W,  %1%U%2 %b %y' format text is used.

     In case another format text shall be respected, this format text
     can either be set in the `GCAL_DATE_FORMAT' environment variable
     (but `GCAL_DATE_FORMAT' is only used in case no
     `--date-format=de|us|gb|TEXT' option is given), or it can be
     arranged by the option argument TEXT, e.g.:

          --date-format="%Y %D %m ; %1(%A)%2"

     The format text may contain on the one hand all characters, which
     can be managed by Gcal and on the other hand character replacement
     instructions and format statements, which are transformed into
     their according values at run-time.  A minimum date format text
     must contain components from the day group, the month group, the
     year group and the highlighting group.  A component of the weekday
     name group is optional.  The following format statements and
     character replacement instructions are actually supported:

     Day group (exactly one member must be defined):

    `%d'
          Day number with leading zeroes

    `%D'
          Day number with leading spaces

    `%u'
          Day number with leading zeroes and trailing Ordinal Number
          suffix

    `%U'
          Day number with leading spaces and trailing Ordinal Number
          suffix

     Month group (exactly one member must be defined):

    `%B'
          Complete month name

    `%b'
          Abbreviated month name (3 letters)

    `%m'
          Month number with leading zeroes

    `%M'
          Month number with leading spaces

     Year group (exactly one member must be defined):

    `%y'
          Complete year number with leading zeroes

    `%Y'
          Complete year number with leading spaces

    `%z'
          Last two digits of year number with leading zeroes

    `%Y'
          Last two digits of year number with leading spaces

     Weekday name group (one member may be defined):

    `%A'
          Complete weekday name

    `%W'
          Abbreviated weekday name (3 letters)

    `%w'
          Abbreviated weekday name (2 letters)

     Highlighting group (all members must be defined and `%1' must be
     specified before `%2'):

    `%1'
          Start of highlighting sequence / marking character

    `%2'
          End of highlighting sequence / marking character

     Character replacement instructions:

    `_'
          Space/blank character ` '

    `\_'
          Underscore character `_'

    `\%'
          Percent character `%'

Date warning options
....................

`-v ARGUMENT'
`--date-variable=ARGUMENT'
     Define "global" date variable, which is visible in all referenced
     resource files (*note Date variables::.).  The option argument
     ARGUMENT must either be a valid single date variable definition or
     a (`:') colon-separated list of definitions.

     A date variable name DVAR consists of a single letter
     (case-insensitive and except the letter `e', which is internally
     reserved for the Easter Sunday's date and which is
     unassignable/inoperatable therefore) and is trailed in a
     definition by the assignment operator character `=' and the
     numerical values of month MM (or a short, three characters month
     name, e.g.  `Jan', `Feb'...) and day DD this variable has to store
     (or another global date variable name, but *no* date given in the
     `MMWWWN', `DVAR[+|-]N[WWW]' or the `*d|wN[WWW]' format).

     Some examples:

          `--date-variable=a=1127:c=a' respectively
          `-v a=1127:c=a'
          stores the 27th November to the global date variable A and to
          the global date variable C.

`--export-date-variables'
     Affects the export of local date variables from one resource file
     to another resource file.  *Note Date variables::, for more
     details.

`-r ARGUMENT'
`--text-variable=ARGUMENT'
     Define "global" text variable, which is visible in all referenced
     resource files (*note Text variables::.).  The option argument
     ARGUMENT must either be a valid single text variable definition or
     a (`:') colon-separated list of definitions.

     A text variable name TVAR consists of the `$' prefix and a single
     letter (case-insensitive), and is trailed in a definition by the
     assignment operator character `=' and the text this variable has
     to store.  A global text variable is defined with an *empty*
     contents in case no text is specified on the right of the
     assignment operator character.

     Some examples:

          `--text-variable=$a=foo:$c=$a' respectively
          `-r $a=foo:$c=$a'
          stores the `foo' text to the global text variable $A and to
          the global text variable $C.

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

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

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

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

     Each time a `_' (underscore) character is found in ARGUMENT, this
     character is replaced by a real ` ' (space) character.

     You may quote the `_' (underscore) 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. `\\_'.

`--export-text-variables'
     Affects the export of local text variables from one resource file
     to another resource file.  *Note Text variables::, for more
     details.

`-c|C[-]'
`--today'
`--list-of-fixed-dates[=short|long]'
`--descending-fixed-dates[=short|long]'
     Activate fixed date warning function and display fixed date
     warning messages.

    `-c'
    `--today'
    `--list-of-fixed-dates=short'
          Activate fixed date warning function (use standard resource
          file implicitly) and list all dates related to current day
          sorted in ascending order.  If no fixed dates related to the
          current day are found, no fixed date warning messages are
          displayed and the program is terminated with error code, see
          *Note 1: Error codes.

    `-c-'
    `--descending-fixed-dates=short'
          Activate fixed date warning function (use standard resource
          file implicitly) and list all dates related to current day
          sorted in descending order.  If no fixed dates related to the
          current day are found, no fixed date warning messages are
          displayed and the program is terminated with error code, see
          *Note 1: Error codes.

    `-C'
    `--list-of-fixed-dates=long'
          Activate fixed date warning function (use standard resource
          file implicitly) and list all dates related to current day
          sorted in ascending order.  If no fixed dates related to the
          current day are found, a fixed date warning text which
          consists only of the date is displayed.

    `-C-'
    `--descending-fixed-dates=long'
          Activate fixed date warning function (use standard resource
          file implicitly) and list all dates related to current day
          sorted in descending order.  If no fixed dates related to the
          current day are found, a fixed date warning text which
          consists only of the date is displayed.

`-f|F NAME[+...]'
`--resource-file=NAME'
     Activate fixed date warning function and use file NAME instead of
     the standard resource file.  Then list all dates sorted in
     ascending order, which occur in the fixed date warning period.  If
     no other fixed date warning period is specified, the current day
     is used for the fixed date warning period.  If the option letter
     `f' of the short-style option is used and no dates related to the
     fixed date warning period are found in NAME, no fixed date warning
     messages are displayed and the program is terminated with error
     code, see *Note 1: Error codes.  If the option letter `F' of the
     short-style option is used and no dates related to the fixed date
     warning period are found in NAME, a fixed date warning text which
     consists only of the date is displayed.

     You can use more than one resource file NAME by separating them
     with a `+' separator character, e.g.:

          `--resource-file=./foo+xyz+/data/foo.bar+$HOME/.gcalrc' resp.,
          `-f ./foo+xyz+/data/foo.bar+$HOME/.gcalrc'

     respects all files, which are given in above argument using a
     special file search mechanism.  *Note File searching mechanism:
     Resource file, for more details.  Use `/dev/null' to avoid the use
     of the standard resource file, useful for creating empty fixed
     dates warning lists.

     You may quote the `+' separator 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. `\\+'.

     Each time a `_' (underscore) character is found in NAME, this
     character is replaced by a real ` ' (space) character.

     You may quote the `_' (underscore) 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. `\\_'.

*Please note:*
If the short-style option `-c' and/or its modifiers `t|[w|m|y[+|-]', or
the short-style option `-f' is/are given in *upper case*, e.g.:

     -C
     -F foo.bar
     -CeT
     -c-aW+
     -CeaxY-
     -c-M

Gcal displays fixed date messages for *every* day of the requested
period.

  The modifiers of a combined/complex/packed short-style fixed date
warning option must be constructed according to following steps,
because Gcal treats them as positional parameters:

    First step: *Representation-of-text-modifier*
          `a', `A', `e|E', `k', `o', `x', `z'

    Second step: *Respected-warning-period-modifier*
          `d', `l', `t|T', `w|W|m|M|y|Y[+|-]', `N+|-', `Nd', `Nw',
          `*dN[WWW]', `*wN[WWW]', `@e|DVAR[[+|-]N]', `@e|DVAR[+|-]NWWW',
          `MMDD', `MMWWWN'

  If you want to operate with the following modifiers, an *explicit*
`-c|C[-]' short-style option must be leading, e.g.:

     -c-t
     -cw-
     -CaAdeklorxz12+

and only *one* period defining fixed date warning period modifier may
be given (this means exclusive the `--include-today' option
respectively `d' modifier, the `--list-mode' option respectively `l'
modifier and the `--leap-day=february|march').

  Or the modifiers must be given as single character options or
composed into a single command line word, and additionally either the
short-style option `-c|C[-]' (or the according long-style option) or
`-f|F NAME[+...]' (or the according long-style option) must be given
like:

     -c -t
     -w- -c
     -a -Ad -e -klorxz -C12+
     -F foo.bar -Ad -l*d10

  If modifiers are given as single character options or composed into a
single command line word and one of the `t|T|[w|W|m|M|y|Y[+|-]]'
modifiers is used (or their according alias names like `--today',
`--tomorrow'...), it's not necessary to give a `-c|C[-]' short-style
option (or its according long-style option) respectively
`-f|F NAME[+...]' (or its according long-style option) to activate the
fixed date warning function of Gcal, because it is triggered implicitly
by means of these modifiers.

*Fixed date warning text modifiers:*

`a'
`--include-resource-file-name'
     Extend fixed date warning text by the name of the resource file,
     which the warning text comes from, e.g.:

          Mon, Jan   1st 1995: (`Eternal holiday list') New Year's day
          Mon, Jan   1st 1995: (.gcalrc) No fixed dates
          ...

`A'
`--alternative-format'
     Instead of using the "standard" list format, e.g.:

          Mon, Jan   1st 1995: New Year's day
          Mon, Jan   1st 1995: No fixed dates
          ...

     Gcal uses the "alternative" list format, e.g.:

          Mon, Jan   1st 1995:
          New Year's day
          No fixed dates
          ...

`e'
`--include-holidays=long'
     Enable inclusion of all built-in eternal holiday dates, this
     includes legal days and memorial days.

`E'
`--include-holidays=short'
     Enable inclusion of those built-in eternal holiday dates, which
     are legal days only.

`g[TEXT]'
`--grouping-text[=TEXT]'
     Group fixed date warnings by day using separator TEXT.  If TEXT is
     not given, the built-in text TEXT (`RC_GROUP_SEP' "" == empty line
     only) is used for grouping, e.g.:

          $ gcal -Cw -cg
          -|
          -| Sun, Nov   6th 1994: Text 1
          -| Sun, Nov   6th 1994: Text 2
          -|
          -| Mon, Nov   7th 1994: Text 3
          -|
          -| Tue, Nov   8th 1994: Text 4
          ...
          
          
          $ gcal -Cw -g'-A_user\_defined-~-grouping text-'
          -|
          -| Sun, Nov   6th 1994: Text 1
          -| Sun, Nov   6th 1994: Text 2
          -| -A user_defined-
          -| -grouping text-
          -| Mon, Nov   7th 1994: Text 3
          -| -A user_defined-
          -| -grouping text-
          -| Tue, Nov   8th 1994: Text 4
          ...

     Each time a `~' (tilde) character is found in TEXT, this character
     is replaced by a real `\n' (newline) character.

     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. `\\~'.

     Each time a `_' (underscore) character is found in TEXT, this
     character is replaced by a real ` ' (space) character.

     You may quote the `_' (underscore) 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. `\\_'.

`k'
`--include-weeknumber'
     The leading date of a warning message is extended by the
     ISO-8601:1988 week number of that date.

     *Please note:*
     The methods of ISO-8601:1988 are used for detecting week numbers;
     this means a week begins with a Monday, and the first week of a
     year is the one which includes the first Thursday; equivalently,
     the one which includes 4th January.

`o'
`--omit-multiple-date-part'
     Omit displaying the leading date of a warning message in case more
     than one warning message refers to that date (only if the
     `--alternative-format' option respectively the `A' modifier is not
     given), e.g.:

          $ gcal -co
          -|
          -| Sun, Nov   6th 1994: Text 1
          -|                      Text 2
          ...

`x'
`--exclude-fixed-dates-list-title'
     Suppresses the title text line of the fixed date warning list.

`z'
`--include-consecutive-number'
     Display consecutive numbers of fixed date warning messages.

*Fixed date warning period modifiers:*

`--leap-day=february|march'
     The "leap day" (i.e. the 29th February) is observed in non-leap
     years.

    `--leap-day=february'
          A warning message which appears in every year and which is
          related to the leap day, is displayed on the 28th February in
          non-leap years.

    `--leap-day=march'
          A warning message which appears in every year and which is
          related to the leap day, is displayed on the 1st March in
          non-leap years.

`d'
`--include-today'
     If lists of periods are generated, include the actual date into
     the list.  *Note `--list-mode': Date warning options, for how to
     create a list of periods.

`l'
`--list-mode'
     Generate a list of periods instead of a single period.

     *Please note:*
     The following examples assume the current date is the 17th February
     of any year.

`--period-of-fixed-dates=ARGUMENT'
`Nd'
`*dN'
     Single date of absolute day N == `1...365|366|999' of actual year;
     the warning level is same as simple `-c' option.  If the value 999
     for N is given, the last day of the year (31st December) is
     assumed.

        * E.g. `gcal -c10d' respectively
          `gcal --period-of-fixed-dates=10d' or `gcal -c*d10'
          respectively `gcal --period-of-fixed-dates=*d10' displays all
          fixed dates, which occur on the 10th day of the year.

`lNd'
`l*dN'
     List dates starting yesterday or tomorrow (depending on given day
     number N) and ending at N'th absolute day of actual year; the
     warning level is same as `-cy' option.

        * E.g. `gcal -cl10d' respectively `gcal -cl*d10' displays a
          list of all fixed dates, which start on the 10th day of year
          and end on 16th February.

`N+|-'
     Single date of day *actual day `+/-' N days* of actual year; the
     warning level is same as simple `-c' option.

        * E.g. `gcal -c10+' displays all fixed dates, which occur 10
          days after the 17th February (today).

        * E.g. `gcal -c10-' displays all fixed dates, which occur 10
          days before the 17th February (today).

`lN+|-'
     List dates starting yesterday `-' or tomorrow `+' and ending at
     *actual day `+/-' N days* of actual year; the warning level is
     same as `-cy' option.

        * E.g. `gcal -cl10+' displays a list of all fixed dates, which
          start on the 18th February and end 10 days after.

        * E.g. `gcal -cl10-' displays a list of all fixed dates, which
          start 10 days before the 16th February and end on the 16th
          February.

`Nw'
     Single dates of week number N == `0|1...52|53|99' of actual year;
     the warning level is same as `-cw' option.

        * E.g. `gcal -c0w' displays all fixed dates, which occur in the
          53rd ISO-week of previous year, in case the previous year has
          a 53rd ISO-week.  If the previous year has 52 ISO-weeks only,
          all fixed dates occuring on the 1st week of the actual year
          are displayed.

        * E.g. `gcal -c6w' displays all fixed dates, which occur in the
          6th ISO-week of year.

        * E.g. `gcal -c52w' displays all fixed dates, which occur in
          the 52nd ISO-week of year.

        * E.g. `gcal -c53w' displays all fixed dates, which occur in
          the 53rd ISO-week of the actual year, in case the actual year
          has a 53rd ISO-week.  If the actual year has 52 ISO-weeks
          only, no fixed date warning messages are displayed and the
          program is terminated with error code, see *Note 126: Error
          codes.

        * E.g. `gcal -c99w' displays all fixed dates, which occur in
          the last ISO-week of the actual year, i.e. either the 52nd or
          the 53rd ISO-week.

`lNw'
     List dates starting yesterday or tomorrow (depending on given
     ISO-week number N) and ending at first respectively last day of
     given ISO-week number N == `0|1...52|53|99' of actual year; the
     warning level is same as `-cy' option.

        * E.g. `gcal -cl12w' displays a list of all fixed dates, which
          start on the 18th February and end on the last day of the
          12th ISO-week.

        * E.g. `gcal -cl3w' displays a list of all fixed dates, which
          start on the first day of the 3rd ISO-week and end on the
          16th February.

`MMDD'
     Single date of day DD in month MM of actual year; the warning
     level is same as simple `-c' option.

        * E.g. `gcal -c0225' displays all fixed dates, which occur on
          the 25th February.

`lMMDD'
     List dates starting yesterday or tomorrow (depending on the value
     given in MMDD) and ending at day DD of month MM of actual year;
     the warning level is same as `-cy' option.

        * E.g. `gcal -cl0225' displays a list of all fixed dates, which
          start on the 18th February and end on the 25th February.

        * E.g. `gcal -cl0109' displays a list of all fixed dates, which
          start on the 9th January and end on the 16th February.

`MMWWWN'
     Single date of N'th == `1...5|9' weekday DD|WWW in month MM of
     actual year; the warning level is same as simple `-c' option.

        * E.g. `gcal -c01mon3' displays all fixed dates, which occur on
          the 3rd Monday in January.

        * E.g. `gcal -c02fri9' displays all fixed dates, which occur on
          the last Friday in February.

`lMMWWWN'
     List dates starting yesterday or tomorrow (depending on the value
     given in MMWWWN) and ending at N'th == `1...5|9' weekday DD of
     month MM of actual year; the warning level is same as `-cy' option.

        * E.g. `gcal -cl01mon3' displays a list of all fixed dates,
          which start on the 3rd Monday in January and end on the 16th
          February.

        * E.g. `gcal -cl02fri9' displays a list of all fixed dates,
          which start on the 18th February and end on the last Friday
          in February.

`*dNWWW'
     Single date of N'th == `1...51|52|53|99' weekday WWW of actual
     year; the warning level is same as simple `-c' option.

        * E.g. `gcal -c*d16sun' displays all fixed dates, which occur
          on the 16th Sunday of actual year.

        * E.g. `gcal -c*d52sun' displays all fixed dates, which occur
          on the 52nd Sunday of actual year.  If the actual year has no
          52nd Sunday, no fixed date warning messages are displayed and
          the program is terminated with error code, see *Note 126:
          Error codes.

        * E.g. `gcal -c*d53sun' displays all fixed dates, which occur
          on the 53rd Sunday of actual year.  If the actual year has no
          53rd Sunday, no fixed date warning messages are displayed and
          the program is terminated with error code, see *Note 126:
          Error codes.

        * E.g. `gcal -c*d99sun' displays all fixed dates, which occur
          on the last Sunday (that's either the 51st, 52nd or 53rd
          Sunday) of actual year.

`l*dNWWW'
     List dates starting yesterday or tomorrow (depending on the value
     given in N) and ending at N'th == `1...51|52|53|99' weekday WWW of
     actual year; the warning level is same as `-cy' option.

        * E.g. `gcal -cl*d16sun' displays a list of all fixed dates,
          which start on the 18th February and end on the 16th Sunday
          of actual year.

        * E.g. `gcal -cl*d52sun' displays a list of all fixed dates,
          which start on the 18th February and end on the 52nd Sunday
          of actual year.  If the actual year has no 52nd Sunday, no
          fixed date warning messages are displayed and the program is
          terminated with error code, see *Note 126: Error codes.

        * E.g. `gcal -cl*d53sun' displays a list of all fixed dates,
          which start on the 18th February and end on the 53nd Sunday
          of actual year.  If the actual year has no 53nd Sunday, no
          fixed date warning messages are displayed and the program is
          terminated with error code, see *Note 126: Error codes.

        * E.g. `gcal -cl*d99sun' displays a list of all fixed dates,
          which start on the 18th February and end on the last Sunday
          (that's either the 51st, 52nd or 53rd Sunday) of actual year.

`*wN[WWW]'
     Single date of weekday WWW of N'th == `0|1...52|53|99' ISO-week of
     actual year; the warning level is same as simple `-c' option. If
     no weekday WWW is given, then Monday is assumed for the weekday.

        * E.g. `gcal -c*w0sun' displays all fixed dates, which occur on
          Sunday, which is located in the 52nd respectively 53rd
          ISO-week of previous year.  In case such a Sunday doesn't
          exist, no fixed date warning messages are displayed an the
          program is terminated with error code, see *Note 126: Error
          codes.

        * E.g. `gcal -c*w16sun' displays all fixed dates, which occur on
          Sunday of the 16th ISO-week of actual year.

        * E.g. `gcal -c*w52sun' displays all fixed dates, which occur on
          Sunday of the 52nd ISO-week of actual year.  If the actual
          year has no Sunday of the 52nd ISO-week, no fixed date
          warning messages are displayed and the program is terminated
          with error code, see *Note 126: Error codes.

        * E.g. `gcal -c*w53sun' displays all fixed dates, which occur on
          Sunday of the 53rd ISO-week of actual year.  If the actual
          year has no Sunday of the 53rd ISO-week, no fixed date
          warning messages are displayed and the program is terminated
          with error code, see *Note 126: Error codes.

        * E.g. `gcal -c*w99sun' displays all fixed dates, which occur on
          Sunday of the last ISO-week (that's either the 52nd or 53rd
          ISO-week) of actual year.

`l*wN[WWW]'
     List dates starting yesterday or tomorrow (depending on the value
     given in N) and ending at weekday WWW of N'th == `0|1...52|53|99'
     ISO-week of actual year; the warning level is same as `-cy' option.
     If no weekday WWW is given, then Monday is assumed for the weekday.

        * E.g. `gcal -cl*w0sun' displays a list of all fixed dates,
          which start on Sunday, which is located in the 52nd
          respectively 53rd ISO-week of previous year and end on 16th
          February.  In case such a Sunday doesn't exist, no fixed date
          warning messages are displayed an the program is terminated
          with error code, see *Note 126: Error codes.

        * E.g. `gcal -cl*w16sun' displays a list of all fixed dates,
          which start on the 18th February and end on Sunday of the
          16th ISO-week of actual year.

        * E.g. `gcal -cl*w52sun' displays a list of all fixed dates,
          which start on the 18th February and end on Sunday of the
          52nd ISO-week of actual year.  If the actual year has no
          Sunday of the 52nd ISO-week, no fixed date warning messages
          are displayed and the program is terminated with error code,
          see *Note 126: Error codes.

        * E.g. `gcal -cl*w53sun' displays a list of all fixed dates,
          which start on the 18th February and end on Sunday of the
          53rd ISO-week of actual year.  If the actual year has no
          Sunday of the 53rd ISO-week, no fixed date warning messages
          are displayed and the program is terminated with error code,
          see *Note 126: Error codes.

        * E.g. `gcal -cl*w99sun' displays a list of all fixed dates,
          which start on the 18th February and end on Sunday of the
          last ISO-week (that's either the 52nd or 53rd ISO-week) of
          actual year.

`@e[[+|-]N]'
     Single date of day N relative to the Easter Sunday's date of
     actual year; the warning level is same as simple `-c' option.

        * E.g. `gcal -c@e' displays all fixed dates, which occur on the
          Easter Sunday's date.

        * E.g. `gcal -c@e10' respectively `gcal -c@e+10' displays all
          fixed dates, which occur 10 days after the Easter Sunday's
          date.

        * E.g. `gcal -c@e-10' displays all fixed dates, which occur 10
          days before the Easter Sunday's date.

`l@e[[+|-]N]'
     List dates starting yesterday or tomorrow (depending on the value
     given in N) and ending at N'th day relative to the Easter Sunday's
     date of actual year; the warning level is same as `-cy' option.

        * E.g. `gcal -cl@e' displays a list of all fixed dates, which
          start on the 18th February and end on the Easter Sunday's
          date.

        * E.g. `gcal -cl@e10' respectively `gcal -cl@e+10' displays a
          list of all fixed dates, which start on the 18th February and
          end 10 days after the Easter Sunday's date.

        * E.g. `gcal -cl@e-10' displays a list of all fixed dates,
          which start on the 18th February and end 10 days before the
          Easter Sunday's date.

`@e[+|-]NWWW'
     Single date of N'th weekday WWW relative to the Easter Sunday's
     date of actual year; the warning level is same as simple `-c'
     option.

        * E.g. `gcal -c@e3fri' respectively `gcal -c@e+3fri' displays
          all fixed dates, which occur on the 3rd Friday after the
          Easter Sunday's date.

        * E.g. `gcal -c@e-3fri' displays all fixed dates, which occur
          on the 3rd Friday before the Easter Sunday's date.

`l@e[+|-]NWWW'
     List dates starting yesterday or tomorrow (depending on the value
     given in N) and ending at N'th weekday WWW relative to the Easter
     Sunday's date of actual year; the warning level is same as `-cy'
     option.

        * E.g. `gcal -cl@e3fri' respectively `gcal -cl@e+3fri' displays
          a list of all fixed dates, which start on the 18th February
          and end on the 3rd Friday after the Easter Sunday's date.

        * E.g. `gcal -cl@e-3fri' displays a list of all fixed dates,
          which start on the 18th February and end on the 3rd Friday
          before the Easter Sunday's date.

`@DVAR[[+|-]N]'
     Single date of day N relative to date variables date of actual
     year; the warning level is same as simple `-c' option.

        * E.g. `gcal -v a=0422 -c@a' displays all fixed dates, which
          occur on the 22nd April.

        * E.g. `gcal -v a=0422 -c@a10' respectively `gcal -v a=0422
          -c@a+10' displays all fixed dates, which occur 10 days after
          the 22nd April.

        * E.g. `gcal -v a=0422 -c@a-10' displays all fixed dates, which
          occur 10 days before the 22nd April.

`l@DVAR[[+|-]N]'
     List dates starting yesterday or tomorrow (depending on the value
     given in N) and ending at N'th day relative to date variables date
     of actual year; the warning level is same as `-cy' option.

        * E.g. `gcal -v a=0422 -cl@a' displays a list of all fixed
          dates, which start on the 18th February and end on the 22nd
          April.

        * E.g. `gcal -v a=0422 -cl@a10' respectively `gcal -v a=0422
          -cl@a+10' displays a list of all fixed dates, which start on
          the 18th February and end 10 days after the 22nd April.

        * E.g. `gcal -v a=0422 -cl@a-10' displays a list of all fixed
          dates, which start on the 18th February and end 10 days
          before the 22nd April.

`@DVAR[+|-]NWWW'
     Singe date of N'th weekday WWW relative to date variables date of
     actual year; the warning level is same as simple `-c' option.

        * E.g. `gcal -v a=0122 -c@a2sat' respectively `gcal -v a=0122
          -c@a+2sat' displays all fixed dates, which occur on the 2nd
          Saturday after the 22nd January.

        * E.g. `gcal -v a=0122 -c@a-2sat' displays all fixed dates,
          which occur on the 2nd Saturday before the 22nd January.

`l@DVAR[+|-]NWWW'
     List dates starting yesterday or tomorrow (depending on the value
     given in N) and ending at N'th weekday WWW relative to date
     variables date of actual year; the warning level is same as `-cy'
     option.

        * E.g. `gcal -v a=0122 -cl@a2sat' respectively `gcal -v a=0122
          -cl@a+2sat' displays a list of all fixed dates, which start
          on the 2nd Saturday after the 22nd January and end on the
          16th February.

        * E.g. `gcal -v a=0122 -cl@a-2sat' displays a list of all fixed
          dates, which start on the 2nd Saturday before the 22nd
          January and end on the 16th February.

`t|T'
`--tomorrow' long-style option
     List dates related to tomorrow.

        * E.g. `gcal -ct' displays all fixed dates, which occur on the
          18th February (tomorrow).

        * E.g. `gcal -cdt' displays all fixed dates, which occur on the
          17th February (today) and on the 18th February (tomorrow).

`w|W[+|-]'
`--week' long-style option
`--end-of-week' long-style option
`--start-of-week' long-style option
     Display week warnings (*note `--starting-day[=ARGUMENT]': Calendar
     options.).

        * `w' or `--week' long-style option
          List dates between *starting day* of current week and last
          day of current week

             - E.g. `gcal -cw' displays all fixed dates, which occur in
               the whole week the 17th February is part of.

        * `w+' or `--end-of-week' long-style option
          List dates between day after current day of current week and
          last day of current week.

             - E.g. `gcal -cw+' displays all fixed dates, which start
               on the 18th February (tomorrow) and end on the last day
               of the week.

             - E.g. `gcal -cdw+' displays all fixed dates, which start
               on the 17th February (today) and end on the last day of
               the week.

        * `w-' or `--start-of-week' long-style option
          List dates between *starting day* of current week and day
          before current day of current week

             - E.g. `gcal -cw-' displays all fixed dates, which start
               on the first day of the week and end on the 16th
               February (yesterday).

             - E.g. `gcal -cdw-' displays all fixed dates, which start
               on the first day of the week and end on the 17th
               February (today).

`m|M[+|-]'
`--month' long-style option
`--end-of-month' long-style option
`--start-of-month' long-style option
     Display month warnings.

        * `m' or `--month' long-style option
          List dates between first day of current month and last day of
          current month.

             - E.g. `gcal -cm' displays all fixed dates, which occur in
               the whole month of February.

        * `m+' or `--end-of-month' long-style option
          List dates between day after current day of current month and
          last day of current month.

             - E.g. `gcal -cm+' displays all fixed dates, which start
               on the 18th February (tomorrow) and end on the last day
               of the month February.

             - E.g. `gcal -cdm+' displays all fixed dates, which start
               on the 17th February (today) and end on the last day of
               the month February.

        * `m-' or `--start-of-month' long-style option
          List dates between first day of current month and day before
          current day of current month.

             - E.g. `gcal -cm-' displays all fixed dates, which start
               on the first day of the month February and end on the
               16th February (yesterday).

             - E.g. `gcal -cdm-' displays all fixed dates, which start
               on the first day of the month February and end on the
               17th February (today).

`y|Y[+|-]'
`--year' long-style option
`--end-of-year' long-style option
`--start-of-year' long-stlye option
     Display year warnings.

        * `y' or `--year' long-style option
          List dates between first day of current year and last day of
          current year.

             - E.g. `gcal -cy' displays all fixed dates, which occur in
               the whole year.

        * `y+' or `--end-of-year' long-style option
          List dates between day after current day of current year and
          last day of current year.

             - E.g. `gcal -cy+' displays all fixed dates, which start
               on the 18th February (tomorrow) and end on the last day
               of the year.

             - E.g. `gcal -cdy+' displays all fixed dates, which start
               on the 17th February (today) and end on the last day of
               the year.

        * `y-' or `--start-of-year' long-style option
          List dates between first day of current year and day before
          current day of current year.

             - E.g. `gcal -cy-' displays all fixed dates, which start
               on the first day of the year and end on the 16th
               February (yesterday).

             - E.g. `gcal -cdy-' displays all fixed dates, which start
               on the first day of the year and end on the 17th
               February (today).

Response file
-------------

  If a `@FILE' option is given in command line, a "response file" FILE
will be used, i.e. options and commands are preloaded from that file.
A response file FILE may contain options and commands, which are
preloaded by Gcal, but *no* reference to further response files.  If
such references to further response files are found, they are ignored.
*Note `--response-file=NAME': Global options, for hints how to generate
a response file automatically.

  The searching scheme for a response file is the same as that for
resource files, except *no* standard response file is respected.  *Note
File searching mechanism: Resource file, for more details.  Multiple
response files may be given in the command line when Gcal is started
and are processed exactly in that order as given, i.e. strictly
sequential.

  Each option and command must be on a single line, i.e. separated by a
real `\n' (newline) character.  A line beginning with a `;' (semicolon)
character in the response file is treated as a remark and will not be
used by Gcal (*note Comment line::.).

  Options must be defined before commands.  If a response file contains
any commands, then all further arguments after the `@FILE' option of
the command line are ignored.

For example:

  1. Contents of response file `file':

          Line     Text
          1        -j
          2        -Cw
          EOF
          
          $ gcal -i -b 3 @file -s 3 1994
          
          ==> gcal -i -b 3 -j -Cw -s 3 1994

  2. Contents of response file `file':

          Line     Text
          1        -j
          2        -Cw
          3        may 1992
          EOF
          
          $ gcal -i -b 3 @file -s 3 1994
          
          ==> gcal -i -b 3 -j -Cw may

  3. Contents of response file `file':

          Line     Text
          1        -j
          2        -Cw
          3        may
          4        1992
          EOF
          
          $ gcal -i -b 3 @file -s 3 1994
          
          ==> gcal -i -b 3 -j -Cw may 1992

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 that fixed date
warning messages can be created for *any* year and are like the warning
messages of the actual year.

The date must be denoted in one of these formats:

   * `YYYY[MM[DD|WWW[N]]]'

   * `YYYY*d|wN[WWW]'

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

   * `MONTH NAME[DD]'

   * `WEEKDAY NAME[N]'

   * DD

Some examples to this:

     *Please note:*
     Following examples assume the current date is Wednesday, the 17th
     February 1993 (19930217)!

The `YYYY[MM[DD|WWW[N]]]' 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 %1994Marth'

        * `gcal %199403th' (== YYYYMMWWW)
          The actual date is set to the date 4th March 1994 => 19940304.

        * `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 %0000MarThu'

        * `gcal %000003thu' (== YYYYMMWWW)
          The actual date is set to the date 4th March 1993 => 19930304.

        * `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|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 -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.

  To understand 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:

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

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

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

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

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

       6. 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 *actual month* of *actual year*
     and ending at month *actual month*-1 of *actual year*+1, called
     "implicit fiscal year" in the further context, e.g.:

          gcal :

`MM:'
     Single fiscal year, starting at month MM of *actual year* and
     ending at month MM-1 of *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 *actual month* of year YYYY and
     ending at month *actual month*-1 of year YYYY+1, called "explicit
     fiscal year" too 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 current year, e.g.:

          gcal .

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

          gcal . 1992

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

          gcal ..

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

          gcal .. 1992

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

          gcal .+

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

          gcal .+ 1992

`.-'
     Actual and previous two months of 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 in 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 given / actual year consisting of:
     `MM: :YYYY MM:YYYY YYYY'

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

`MM:;MM:;...'
     List of fiscal years of 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 (*note GCAL: Environment variables.).  These options are
interpreted first at program start-up and some can be overwritten by
explicit command line arguments or values which are found in a response
file option `@FILE'.  *Note Command line arguments::, and *Note
Response file::.

For example:

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

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

   * for *MS-DOS*:
          set GCAL=-i @colour -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 @colour -b 3"

Eternal holidays
****************

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

  In case you start Gcal without an explicit (fiscal) date and the
*eternal holiday list* argument (*note `--holiday-list[=long|short]':
Calendar options.), 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.

  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 of the specified month (of year) and
trailing those holidays of the eternal holiday list, that refer to the
given month (of 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 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 (*note `. YYYY': 3-Month mode commands.),
e.g.:

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

Gcal displays the according three months using a fixed year calendar
style 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.  *Note `MM,...,MM': Lists of commands, and *Note
`MM-MM': Ranges of commands, for more details.

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 (*note 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 *Note Eternal holidays::.

*Annotation to previous examples:*

  In case an additional *standard/special calendar format* argument or
an additional *starting day of week* argument (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.  *Note `--type=special|standard': Calendar options, and
*Note `--starting-day[=ARGUMENT]': Calendar options, 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 warning* argument (with optional modifiers) and the
*number of blocks* argument (*note `--blocks=NUMBER': Calendar
options.), 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 (*note 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
     warning level is same as `-cy' option.

`gcal -c- july:1993'
     Lists all fixed dates 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'
     Lists all fixed dates related to July 1993 inclusive all eternal
     holidays merged into this list in ascending order; the warning
     level is same as `-cm' option.

`gcal -c-e -n 1993+1996'
     Lists all fixed dates related to 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 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 that
     directory, which is referenced in the environment variable `HOME'.
     If no `HOME' environment variable is defined and set, Gcal omits
     this step.  *Note HOME: Environment variables.

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

  3. If the above action fails, Gcal inspects the *user data* directory
     (normally `$HOME/share/gcal') 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
     (*note GCAL_USR_DATADIR: Environment variables.).  If no `HOME'
     environment variable is defined and set, Gcal omits this step.

  4. If all above actions fail, Gcal inspects the *system data*
     directory (normally `/usr/local/share/gcal' or
     `$(prefix)/share/gcal') 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 (*note GCAL_SYS_DATADIR:
     Environment variables.).

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

  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.  *Note `--resource-file=NAME':
Date warning options.

  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)  On MS-DOS, OS/2 and some other operating systems, another
character will be used, e.g. `;' on MS-DOS and OS/2.

  (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
--------------------------

  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 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.  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.  The maximum length of a line is
limited to INT_MAX (1) 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 warning entries 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!

Besides fixed date warning 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)  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.  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 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.  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 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.  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 year, i.e. exceeds the year bounds, the
          fixed date warning 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 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 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|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.

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

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 15th day in every month of the year 1996 and covers a
period of four days (inclusive the 15th itself), e.g. `Co-workers
training', one solution would be on the one hand a fixed date entry in
the resource file for the 15th 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 15th and the three days, which succeed the
15th 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 3rd 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 12th 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 12th of the month and the succeeding two days, and that
     appears within the period of the 3rd Friday of the month and the
     succeeding four days.

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

`0*d1:2'
     In every year: every day that appears within the period of the 1st
     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 1st 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 15th day in every month of the year 1996 and covers
a period of seven days (inclusive the 15th 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 15th of
the month, for the 18th and for the 21st 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 15th, the 18th and the 21st 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 3rd Friday of the month and the succeeding ten days, but
     only every 3rd 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 12th of the month and the succeeding two days, but only
     every 2nd 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 12th of the month and the succeeding two days, but only
     every 2nd day within this period (skip one day at a time), and that
     appears within the period of the 3rd Friday of the month and the
     succeeding four days, but only every 3rd 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 1st
     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 1st
     day of the year and the succeeding day, but only every 5th day
     within this period (skip four days at a time).  Well, the
     succeeding days (only one in this example) of the starting day
     (1st 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 61st 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 1st ISO-week and the succeeding 16 days, but only
     every 8th 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 3rd 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 4th day within this period (skip three
     days at a time).

`1996@e3#-20sun.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 20th
     Sunday before the Easter Sunday's date, but only every 15th 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  14th 1994: Am I another short text? Dunno...
     -| Wed, Sep  14th 1994: I hope I'm long enough
     -|                      here, a line break up
     -|                      and again
     -|                      and now for the last time...
     -| Wed, Sep  14th 1994: I know I'm a short text

  Because *whitespace* characters are used to separate the date part
from the text part (these are internally skipped and remain undisplayed
therefore), it's not possible to supply the text part with leading
*whitespace* characters without further ado.  If one or more
*whitespace* characters shall lead the text part, this can be arranged
by quoting the *first* of these *whitespace* characters (and that by
placing a `\' (backslash) character before it), e.g. `\ ' if it is a
space character.  By means of such a character sequence, Gcal notices
that the text trailing the `\' character is no longer used for
separating purposes, but is member of the text part.  Gcal skips this
specific marking backslash character (avoids its output) and processes
the rest of the line as usual.

The following example should be enough to elucidate the above facts.
The resource file `whitespc.rc'

     0 BANG BANG
     0 bogus
     0         bogomips
     0    \hello world
     0    \ main(){for(;;)fork();}
     0 \     sh $0 & $0 &
     0    \  a  \  b  \\  c  \\\  d
     0    What happens now?\
     ~0  \  This!
     0    What happens now?\\
     ~0  \  That!

is displayed as follows:

     $ gcal --resource-file=whitespc.rc --disable-highlighting
     -|
     -| Fixed date list:
     -|
     -| Wed, Sep  14th 1994:      sh $0 & $0 &
     -| Wed, Sep  14th 1994:   a  \  b  \\  c  \\\  d
     -| Wed, Sep  14th 1994:  main(){for(;;)fork();}
     -| Wed, Sep  14th 1994: BANG BANG
     -| Wed, Sep  14th 1994: What happens now?~0  \  That!
     -| Wed, Sep  14th 1994: What happens now?
     -|                      0  \  This!
     -| Wed, Sep  14th 1994: \hello world
     -| Wed, Sep  14th 1994: bogomips
     -| Wed, Sep  14th 1994: bogus

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 *Note
Text part of a line::.

Include directives
------------------

  You may add `#include' directives in a resource file (a mechanism
similar the method, which is used by the C Preprocessor) for searching
and loading further resource files.  An `#include' directive tells Gcal
to suspend reading the current resource file and read one other
resource file before continuing.  The directive is a line in the
resource file that looks like this template:

     #include *whitespace* ARGUMENT [*whitespace*] *newline*

The ARGUMENT can either be

     "FILE NAME"

or

     <FILE NAME>

(thus a file name, which is embraced by `""' or `<>').

  A *whitespace* character minimum is required between `#include' and
the ARGUMENT.  The ARGUMENT may be trailed by extra *whitespace*
characters and the line must always end with a `\n' (newline)
character, except it's the last line of a resource file.

Let's inspect a bit more concrete example:

  1. #include "foo/bar"

  2. #include <bar>

  The first `#include' directive tells Gcal to load the file `bar' in
the directory `foo' from the actual directory.  If this fails, Gcal
tries to load this file using steps 1...4 of the previously explained
mechanism, which is used for searching files (*note File searching
mechanism: Resource file.).

  The second `#include' directive tells Gcal to load the file `bar'
from the user respectively system data directory using steps 3...4 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 an `#include' directive 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 data
directory name) wouldn't be a valid file name any longer.

  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!  Gcal recognizes such situations and terminates immediately
with a fatal error.

  If an included resource file cannot be found and no `--debug=abort'
option is given, processing of the resource file containing the
`#include' continues.

  ---------- 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 16 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. `\%'.  The
`%' character is trailed by a distinguishing mark, which defines the
kind of the macro text to be used and if it is a letter, Gcal accepts
it case-insentive.

     *Please note:*
     The optional date after the `%s...', `%e...', `%o...', `%k...',
     `%b...' and `%y...' 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, which is suppressed in output.

   * 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, which is suppressed in output.

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

%o macro text
.............

  `%o[YYYY[MM[DD|WWWN]]]' references the "weekday name" and is
converted to a *weekday name text*, e.g.:

     The text `Today is %o , the %n' will be expanded to
     ==> `Today is Monday, the 10-Jun-1996', in case the current date
     is the 10th June 1996.

  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, which is suppressed in output.

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

%k macro text
.............

  `%k[YYYY[MM[DD|WWWN]]]' references the "week number" and is converted
to an ISO-*week number text*, e.g.:

     The text `Today is %o  of week %k' will be expanded to
     ==> `Today is Monday of week 24', in case the current date is the
     10th June 1996.

  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, which is suppressed in output.

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

%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 32nd 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, which is suppressed in output.  If
the use of an ordinal suffix is encoded in the date format, which is
used to display dates, such computed age values also have a trailing
ordinal suffix automatically.  *Note `--date-format=de|us|gb|TEXT':
Calendar options, for more details.

   * 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, which is suppressed in output.

   * 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 1st 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: 06-Feb-1990', in case you call Gcal with the
     simple `-c' option and the command `sep 1962' (*note `MM YYYY':
     Single commands.).

%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, (*note `--highlighting=TEXT': Global options.).  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.

%2 macro text
.............

  `%2' is replaced by the ending highlighting sequence respectively the
ending marking character, which is used for highlighting the actual
day.  This attains that a possibly active highlighting according to the
actual day is turned off respectively an ending marking character is
produced.  `%2' is used together with the `%1' macro text.  The `%2'
text has no effect if no preceeding `%1' text was found on the line.

%3 macro text
.............

  `%3' is replaced by the starting highlighting sequence respectively
the starting marking character, which is used for highlighting a
holiday, (*note `--highlighting=TEXT': Global options.).  This attains
that all succeeding text of the line after this macro text is displayed
in the same way as the highlighted respectively marked holiday.  `%3'
is used together with the `%4' macro text, which turns off this enabled
highlighting sequence respectively produces the ending marking
character.  If a `%3' text is not succeeded by a `%4' text on the line,
Gcal automatically inserts such a `%4' text at the end of the line.

  For example:

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

%4 macro text
.............

  `%4' is replaced by the ending highlighting sequence respectively the
ending marking character, which is used for highlighting the actual
day.  This attains that a possibly active highlighting according to the
actual day is turned off respectively an ending marking character is
produced.  `%4' is used together with the `%3' macro text.  The `%4'
text has no effect if no preceeding `%3' text was found on the line.

Date variables
--------------

  Gcal respects *global* and/or *local* date variables (*note
`--date-variable=ARGUMENT': Date warning options.), which may be used
either in the date part of a Gcal resource file line or which may be
part of a special macro text in the text part of a Gcal resource file
line.  This means up to *25* user defined date variables can be set and
referenced during program execution.  A date variable name DVAR
consists of a single letter (case-insensitive and except the letter
`e', which is internally reserved for the Easter Sunday's date and
unassignable/inoperatable therefore) and is trailed in a definition by
the assignment operator character `=' and the numerical values of month
MM (or a short, three characters month name, e.g. `Jan', `Feb'...) and
day DD this variable has to store (or another date variable name), e.g.:

     a=1127
     c=a

stores the 27th November to the local date variable A and to the local
date variable C.  You should always remember that date variables can
only be referenced in a line if they are already defined, because Gcal
processes a resource file line by line.

  Only local date variables can store dynamic dates given in the
`MMWWWN', `DVAR[+|-]N[WWW]' or `*d|wN[WWW]' format, e.g.:

     a=03su2
     b=JunMon9
     c=b-3
     d=c+4Sa
     x=*d10
     y=*d10fri
     z=*w3Su

which means, date variable A stores the date of second Sunday in March
and B stores date of last Monday in June.  The date variable C stores
the date, which is three days before the date of the last Monday in
June and this date is set in the date variable D to that date, which is
four Saturdays after the date of C.  The date variable X stores the
date of the 10th absolute day of the year (== 10th January).  Y stores
the date of the 10th Friday of the year, and the assignment to Z is the
date of the Sunday, which occurs in the 3rd week of the year.

*Caution:*
These kinds of assignments to date variables 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*.

  Date variables which are defined in a resource file are always local
and only respected in this specific file and that file, which is
included by it.  This means for the included file that *all* local
variables of the caller are visible.  The included file itself may
define its own local variables in its own name-space, which are not
exported to caller on return.  All other definitions of date variables
(in command line, environment variable `GCAL' or response file) are
always global.  If a resource file line contains a reference of a date
variable, which is not locally defined in that file, Gcal will try to
use the global values held by this variable.  If this fails because no
global definition of this date variable is given, Gcal will not process
this line.  If the simple `--debug' respectively `--debug=internal'
option is given, warning messages for each undefined date variable will
be shown (*note `--debug=internal': Global options.).  If the
`--debug=abort' option is given, Gcal will abort program execution when
the first undefined global date variable reference occurs.  For more
information, see *Note `--debug=abort': Global options.

  A local date variable can be deleted, which means, that this date
variable is no longer valid in its local scope and be undefined
therefore.  So it is possible to use its potentially defined global
value in succeeding lines if this date variable is referenced there.
The following example of the resource file `dvar.rc' elucidates these
facts:

     z=0202
     0@z The local assigned date to `z'
     z=
     0@z The global assigned date to `z'
     z=0404
     0@z The local assigned date to `z'

So Gcal creates the following output:

     $ gcal %1777 -H no -x -v z=1212 -f ./dvar.rc -y
     -|
     -| Sun, Feb   2nd 1777: The local assigned date to `z'
     -| Fri, Apr   4th 1777: The local assigned date to `z'
     -| Fri, Dec  12th 1777: The global assigned date to `z'
     $ gcal %1777 -H no -x -f ./dvar.rc -y
     -|
     -| Sun, Feb   2nd 1777: The local assigned date to `z'
     -| Fri, Apr   4th 1777: The local assigned date to `z'

  Only advanced users should apply the `--export-date-variables'
option, which affects that the actual incarnation of a local date
variable - which was previously defined in a resource file and not in an
included file - is being exported to further resource files instead of
using its global value in case that date variable isn't locally defined
in that further resource file.  *Note Include directives::, for more
details.

  But be aware, the use of this option could create unwanted results,
because the order of processing the resource files is an important
entity in managing the `--export-date-variables' option, so it's not
recommended using it.  You, the user, must know exactly what you're
doing when applying this option; *you are expressively warned now!*

Some basic operations can be performed on date variables.

These are:

`DVAR++'
     Simple incrementation by one day.

`DVAR--'
     Simple decrementation by one day.

`DVAR+=N'
     Addition of a constant numeric day factor N.

`DVAR-=N'
     Subtraction of a constant numeric day factor N.

`DVAR+=NWWW'
     Addition of N weekdays WWW.

`DVAR-=NWWW'
     Subtraction of N weekdays WWW.

  The scope of the operations which are done on a local date variable,
is that resource or include file, where the local date variable is
defined.

  If operations on a global date variable are performed in a resource
file or that file which is included by it, these operations are only
valid in that specific file (they are done locally), not in further
resource files processed.  This means the initial values of global date
variables are always restored if the resource file changes.

  Please note finally, that each date variable assignment/operation
must be given separately on a single line in the resource file.

Text variables
--------------

  Gcal respects *global* and/or *local* text variables (*note
`--text-variable=ARGUMENT': Date warning options.), which may be used
anywhere in a line of a Gcal resource file.  This means up to *26* user
defined text variables can be set and referenced during program
execution.  A text variable name TVAR consists of the `$' prefix and a
single letter (case-insensitive), and is trailed in a definition by the
assignment operator character `=' and the text this variable has to
store.  Only local text variables are set to an undefined value in case
no text is specified on the right of the assignment operator character.
You should always remember that text variables can only be referenced
in a line if they are already defined, because Gcal processes a
resource file line by line.  Gcal always expands text variable
references recursively until all sub-references to other text variables
are resolved.

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

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

  Here are some examples showing how Gcal processes text variables.
Let's assume a resource file by the name of `demo.rc' exists with the
following contents:

     $a=foo
     0 \$a:1=$a
     $c=$a
     0 \$c=$c
     $b=$c bar $a
     0 \$b=$b
     $a=bar $b baz $a booz
     0 \$a:2=$a
     $a=
     $b=0 $b $c frozz $a frozz
     $b --> That's \$b
     0 \$x='$x' and \$d is undefined: $d...
     $a= 0 ~ 1~2~\$3~%n~$c~now it's enough!
     0 \$a=---$a---
     $a=0 \   \ \\ And this...
     $a works too!

So Gcal creates the following output:

     $ gcal %19960101 -H no -x -r '$A=FROBOZZ:$x=' -f ./demo.rc
     -|
     -| Mon, Jan   1st 1996: $a:1=foo
     -| Mon, Jan   1st 1996: $a:2=bar foo bar foo baz foo booz
     -| Mon, Jan   1st 1996: $a=--- 0
     -|                       1
     -|                      2
     -|                      $3
     -|                      01-Jan-1996
     -|                      foo
     -|                      now it's enough!---
     -| Mon, Jan   1st 1996: $b=foo bar foo
     -| Mon, Jan   1st 1996: $c=foo
     -| Mon, Jan   1st 1996:    \ \\  And this... works too!
     -| Mon, Jan   1st 1996: $x='' and $d is undefined: $d...
     -| Mon, Jan   1st 1996: foo bar foo foo frozz FROBOZZ frozz --> That's $b

Or a resource file by the name of `demo2.rc' exists with the following
contents:

     $a=$b foo
     $b=0@e
     $a bar
     $b \$b
     0 \$a:$a
     0 \$b:$b

So Gcal creates the following output:

     $ gcal %19960101 -H no -x -f ./demo2.rc
     -|
     -| Mon, Jan   1st 1996: $a:0@e foo
     -| Mon, Jan   1st 1996: $b:0@e
     $ gcal %19960101 -H no -x -f ./demo2.rc -y
     -|
     -| Sun, Apr   7th 1996: $b
     -| Sun, Apr   7th 1996: foo bar

  As seen before, it's allowed to store complete (or partitial) date
parts (*note Date part of a line::.), likewise special macro texts
(*note Special macro texts::.) into text variables or references to
other text variables, which are processed by Gcal after their expansion.

  Text variables which are defined in a resource file are always local
and only respected in this specific file and that file, which is
included by it.  This means for the included file that *all* local
variables of the caller are visible.  The included file itself may
define its own local variables in its own name-space, which are not
exported to caller on return.  All other definitions of text variables
(in command line, environment variable `GCAL' or response file) are
always global.  If a resource file line contains a reference of a text
variable, which is not locally defined in that file, Gcal will try to
use the global values held by this variable.  If this fails because no
global definition of this text variable is given, Gcal keeps the name
of this text variable untouched in this line.

  Only advanced users should apply the `--export-text-variables'
option, which affects that the actual incarnation of a local text
variable - which was previously defined in a resource file and not in an
included file - is being exported to further resource files instead of
using its global value in case that text variable isn't locally defined
in that further resource file.  *Note Include directives::, for more
details.

  But be aware, the use of this option could create unwanted results,
because the order of processing the resource files is an important
entity in managing the `--export-text-variables' option, so it's not
recommended using it.  You, the user, must know exactly what you're
doing when applying this option; *you are expressively warned now!*

  The scope of the definitions which are done on a local text variable,
is that resource or include file, where the local text variable is
defined.

  If a global text variable is redefined in a resource file or that
file which is included by it, these definitions are only valid in that
specific file (they are done locally), not in further resource files
processed.  This means the initial values of global text variables are
always restored if the resource file changes.

  Please note finally, that each text variable assignment must be given
separately on a single line in the resource file.

Resource file examples
======================

  Here are some examples of problem oriented resource files, which
might be useful to get a deeper impression about the attributes of
Gcal's fixed date warning feature.

Let's begin with a common example:

     ; This is general example of a resource file.
     ;
     19940715 Time: %t --> Dentist at 10:00
     00000921 My %b1962 birthday%s1952 %e2062
     0000093 Gregorian~reformation\~is %y1752 year ago
     0000Sep03 Gregorian~reformation\~is %y1752 year ago
     0 Every day in every month in every year
     0000 Every day in every month in every year
     00000000 Every day in every month in every year
     199400fri        Every Friday in 1994
     000007mo3 Every third Monday~in July every year less 1980%e1979
     0000@e-10 Easter Sunday-10 days every year
     0@e-10 Easter Sunday-10 days every year
     00000000@e+10 Easter Sunday+10 days every year
     a=1127
     0@a+20 20 days after date of date variable `a'
     a=*W10FR
     0@a-1 The Thursday of the 10th ISO-week every year
     0@a   The Friday of the 10th ISO-week every year
     0@a1  The Saturday of the 10th ISO-week every year
     1995*d10    The 10th absolute day in 1995
     1995*d99tue The last Tuesday in 1995
     0*w99su The Sunday of the last ISO-week every year
     ;
     ; The next entry is respected by ALL
     ;   fixed date warning period modifiers.
     ;
     1994*d1sun#99SUN.7 Each Sunday in 1994
     ;
     ; Day of Prayer & Repentance is Wednesday before the Sunday,
     ;   which is before the 1st Advent's Sunday.
     ;
     a=1225
     a=a-5sun
     0@a-4 Day of Prayer & Repentance

And here is a resource file by the name of `demo3.rc' used to detect
all Fridays the 13th of a year:

     $a=Friday the 13th%s0000
     $b= %e0000
     $c=fri2
     $d=fri3
     00000113 $a01$c$b01$c
     00000113 $a01$d$b0$1d
     00000213 $a02$c$b02$c
     00000213 $a02$d$b02$d
     00000313 $a03$c$b03$c
     00000313 $a03$d$b03$d
     00000413 $a04$c$b04$c
     00000413 $a04$d$b04$d
     00000513 $a05$c$b05$c
     00000513 $a05$d$b05$d
     00000613 $a06$c$b06$c
     00000613 $a06$d$b06$d
     00000713 $a07$c$b07$c
     00000713 $a07$d$b07$d
     00000813 $a08$c$b08$c
     00000813 $a08$d$b08$d
     00000913 $a09$c$b09$c
     00000913 $a09$d$b09$d
     00001013 $a10$c$b10$c
     00001013 $a10$d$b10$d
     00001113 $a11$c$b11$c
     00001113 $a11$d$b11$d
     00001213 $a12$c$b12$c
     00001213 $a12$d$b12$d

The result for the years 1996...2002 is as follows:

     $ gcal -H no -u -x -f ./demo3.rc 1996+2002
     -|
     -| Fri, Sep  13th 1996: Friday the 13th
     -| Fri, Dec  13th 1996: Friday the 13th
     -|
     -| Fri, Jun  13th 1997: Friday the 13th
     -|
     -| Fri, Feb  13th 1998: Friday the 13th
     -| Fri, Mar  13th 1998: Friday the 13th
     -| Fri, Nov  13th 1998: Friday the 13th
     -|
     -| Fri, Aug  13th 1999: Friday the 13th
     -|
     -| Fri, Oct  13th 2000: Friday the 13th
     -|
     -| Fri, Apr  13th 2001: Friday the 13th
     -| Fri, Jul  13th 2001: Friday the 13th
     -|
     -| Fri, Sep  13th 2002: Friday the 13th
     -| Fri, Dec  13th 2002: Friday the 13th

Or a bit shorter version of the resource file `demo3.rc' by the name of
`demo4.rc' likewise used to detect all Fridays the 13th of a year:

     $a=%n+12 is a Friday%s0000
     $b=1 %e0000
     $c=sun1
     00000101 $a01$c$b01$c
     00000201 $a02$c$b02$c
     00000301 $a03$c$b03$c
     00000401 $a04$c$b04$c
     00000501 $a05$c$b05$c
     00000601 $a06$c$b06$c
     00000701 $a07$c$b07$c
     00000801 $a08$c$b08$c
     00000901 $a09$c$b09$c
     00001001 $a10$c$b10$c
     00001101 $a11$c$b11$c
     00001201 $a12$c$b12$c

The result for the years 1996...2002 is as follows:

     $ gcal -H no -u -x -f ./demo4.rc 1996+2002
     -|
     -| Sun, Sep   1st 1996: 13-Sep-1996 is a Friday
     -| Sun, Dec   1st 1996: 13-Dec-1996 is a Friday
     -|
     -| Sun, Jun   1st 1997: 13-Jun-1997 is a Friday
     -|
     -| Sun, Feb   1st 1998: 13-Feb-1998 is a Friday
     -| Sun, Mar   1st 1998: 13-Mar-1998 is a Friday
     -| Sun, Nov   1st 1998: 13-Nov-1998 is a Friday
     -|
     -| Sun, Aug   1st 1999: 13-Aug-1999 is a Friday
     -|
     -| Sun, Oct   1st 2000: 13-Oct-2000 is a Friday
     -|
     -| Sun, Apr   1st 2001: 13-Apr-2001 is a Friday
     -| Sun, Jul   1st 2001: 13-Jul-2001 is a Friday
     -|
     -| Sun, Sep   1st 2002: 13-Sep-2002 is a Friday
     -| Sun, Dec   1st 2002: 13-Dec-2002 is a Friday

And here is a resource file by the name of `demo5.rc' used to detect
all working-days of any month:

     $a=Working-day
     $c=%e0000$b99
     a=$bmon1
     0@a#+4 $a
     a=$btue1
     0@a#+3 $a
     a=$bwed1
     0@a#+2 $a
     a=$bthu1
     0@a#+1 $a
     a=$bfri1
     0@a $a
     a=$bmon2
     0@a#+4 $a
     a=$bmon3
     0@a#+4 $a
     a=$bmon4
     0@a#+4 $a$c
     a=$bmon9
     0@a#+4 $a$c

Respectively a bit shorter version of the resource file `demo5.rc':

     $a=Working-day
     $c=%e0000$b99
     0000$bmon1:5 $a
     0000$btue1:4 $a
     0000$bwed1:3 $a
     0000$bthu1:2 $a
     0000$bfri1:1 $a
     0000$bmon2:5 $a
     0000$bmon3:5 $a
     0000$bmon4:5 $a$c
     0000$bmon9:5 $a$c

And a resource file by the name of `include.rc' exists, which is only
used to include one given resource file:

     #include "$f"

Then the result for the month February 1996 is as follows:

     $ gcal -H no -u -x -r '$b=02:$f=demo5.rc' -f ./include.rc feb 1996
     -|
     -| Thu, Feb   1st 1996: Working-day
     -| Fri, Feb   2nd 1996: Working-day
     -| Mon, Feb   5th 1996: Working-day
     -| Tue, Feb   6th 1996: Working-day
     -| Wed, Feb   7th 1996: Working-day
     -| Thu, Feb   8th 1996: Working-day
     -| Fri, Feb   9th 1996: Working-day
     -| Mon, Feb  12th 1996: Working-day
     -| Tue, Feb  13th 1996: Working-day
     -| Wed, Feb  14th 1996: Working-day
     -| Thu, Feb  15th 1996: Working-day
     -| Fri, Feb  16th 1996: Working-day
     -| Mon, Feb  19th 1996: Working-day
     -| Tue, Feb  20th 1996: Working-day
     -| Wed, Feb  21st 1996: Working-day
     -| Thu, Feb  22nd 1996: Working-day
     -| Fri, Feb  23rd 1996: Working-day
     -| Mon, Feb  26th 1996: Working-day
     -| Tue, Feb  27th 1996: Working-day
     -| Wed, Feb  28th 1996: Working-day
     -| Thu, Feb  29th 1996: Working-day

And finally a resource file by the name of `swtime.rc', which results
fixed date warnings for the change of daylight-saving time valid since
1980 for the Federal Republic of Germany (two days before adaptation
till two days after adaptation).

     ;
     ; `swtime.rc'; daylight-saving time BRD
     ;
     $a=daylight-saving time starts Sunday
     ;
     a=03sun9
     0@a-2#+2 Summer $a~+1 hrs. (02:00 --> 03:00 h.)%s1980
     ;
     a=09sun9
     0@a-2#+2 Winter $a~-1 hrs. (03:00 --> 02:00 h.)%s1980 %e1995
     ;
     a=10sun9
     0@a-2#+2 Winter $a~-1 hrs. (03:00 --> 02:00 h.)%s1996

Genesis of the Gregorian calendar
*********************************

  The calendar that we use today was first formulated in several
inaccurate variations by the Romans.  The aim of all these calendars
was to harmonize the cycles of the moon and the sun.  During Julius
Caesar's reign, January was falling in autumn so he ordered Sosigenes
to make changes to the calendar.  He added 90 days to the year 46 B.C.
to make up for the seasonal drift and adjusted the lengths of the
months similarly as we know them to be today.  He introduced the leap
year by adding one day to February every four years.  For the present,
the leap year regulation was made in the way, that all four years after
the 23rd day in February a leap day was layed in, so the 24th February
occurred twice.  The use of the leap year was an improvement but not
entirely accurate.

  But in the later years, the leap rule was used in the wrong way so
that the emperor Augustus corrected the errors in the year 8 B.C.  A
curious sequel happened on this occasion.  Because Augustus reacted
with great jealousy to all things previously made and propagated by
Julius Caesar, he didn't like Caesar's name in the calendar, namely the
today's month of *July*.  Offhandedly he named another month to himself
and so the month name *August* arose.  Furthermore, Augustus did not
tolerate the fact, that his month of birth (the August) was shorter
than Caesar's month in the sense of the periodical sequence of months
with 30 and 31 days.  Consequently, the month of August got 31 days,
too.  By reason of this, the number of days in February were reduced to
28 and 29 days, respectively.

  This calendar is well known under the term "Julian calendar" and is
based on a plain solar year.  The nominal length of a solar year
(respectively a so-called tropical year) is 365 days, 5 hours, 48
minutes, and 46 seconds.  One 366-day year every four years equates to
an average Julian year of 365 days and 6 hours, consequently to 365.25
days.  This means every four years, an error of 44 minutes, 56 seconds
was accumulated by this kind of calendar calculation.  Because of this
counting method, the length of the years becomes a bit too long, by
more than 11 minutes.

  By the 16th century, the vernal equinox occurred around March 11,
rather than March 21, by reason of an accumulated error of ten days.
The feast of Easter shifted away more and more from the habitual vernal
date, which must have always been celebrated on an earlier date.  So
Pope Gregory XIII introduced the new style calendar in 1582.  Thursday,
the 4th October 1582 was followed by Friday, the 15th October, by
suppressing the ten days between both dates.  Moreover, he ordained
that years ending in hundreds should not be leap years unless they are
divisible by 400.  Incidentally, the "Gregorian reform" compensates by
72 hours (3 days) every 400 years.  The actual excess accumulated is 74
hours, 53 minutes and 20 seconds.  The error of 2 hours, 53 minutes and
20 seconds every 400 years accumulates to one day in 3323 years.
Thereby the Gregorian year has an average length of 365.2425 days.

  But this "Gregorian calendar" was accepted very slowly by others.
Catholic countries adopted the Gregorian calendar almost immediately.
Most Protestant countries on the Continent adopted the new calendar
around 1700.  England and the American colonies changed in 1752, by act
of Parliament.  Orthodox Christian countries adopted the Gregorian
calendar later.  Russia was the last European country to do so, after
the communist revolution of 1917.  As a result, the U.S.S.R. celebrates
the October Revolution (happened on October 25th, 1917) in the old
style calendar on November 7th.

  Up to now, China was the last country to change over its chronology,
conforming with the Gregorian calendar in 1949.  The era of a world
wide uniform calendar is already part of history today.  The Iran
returned to the traditional Mohammedian moon calendar in 1979 after
removal of the Schah reign.  There are some efforts to improve our
actually valid Gregorian calendar.  Its disadvantages are the fact,
that an appointed day is not always on the same week day.  Besides, the
month lengths are not equal and the holidays, which have relations to
the feast of Easter are moved within the calendar from one year to
another.  A very sophisticated suggestion was proposed by the United
Nations, but the international establishment of this suggestions has
failed, since it was resisted by some countries as well as the churchs.

Gcal Utilities
**************

  Two small utility programs are part of the Gcal 2.10 package.  The
`tcal' program runs the Gcal program with the date set one day ahead.
And the `txt2gcal' program creates a verbatim Gcal resource file from a
text file.

Invoking `tcal'
===============

  The `tcal' program runs `gcal' with the date of tomorrows day
(equivalent the `--shift=1' option).  Its arguments are as follows:

     tcal [--help | --version] | [--shift=[+|-]NUMBER] [ARGUMENT...]

  All given ARGUMENTS are passed unmodified to the Gcal program.  If
the Gcal program shall be called with another date than tomorrows date,
this desired date can be selected by using the `--shift=[+|-]NUMBER'
option, in which `[+|-]NUMBER' is the distance of days, the desired
date is distant from the actual date.  The `--shift' option must be
given before all other ARGUMENTS, which are passed to the Gcal program.

  In case a `GCALPROG' environment variable (*note GCALPROG:
Environment variables.) is defined and set with the file name of the
executable Gcal program, `tcal' will use this file name for calling
Gcal.  Otherwise, the file name `gcal', which is burned-in during the
compilation step of `tcal', is used for calling the Gcal program.  An
exit status of 0 means all processing is successfully done, and any
other value means an error has occured.

  The program accepts the following options:

`--help'
     Print a usage message listing all available options, then exit
     successfully.

`--version'
     Print the version number, then exit successfully.

`--shift=[+|-]NUMBER'
     Define the displacement in `[+|-]NUMBER' days the desired date is
     distant from the actual date.

Invoking `txt2gcal'
===================

  The `txt2gcal' program creates a verbatim Gcal resource file from a
text file. Its arguments are as follows:

     txt2gcal [--help | --version] | [TEXT-FILE|-] [DATE-PART]

  If no TEXT-FILE or `-' argument is given, the program reads and
processes all input received from the standard input channel. If no
DATE-PART argument is given, `txt2gcal' creates a `0' for the date
part.  All results are always shown on the standard output channel.  An
exit status of 0 means all processing is successfully done, and any
other value means an error has occured.

  The program accepts the following options:

`--help'
     Print a usage message listing all available options, then exit
     successfully.

`--version'
     Print the version number, then exit successfully.

  Here comes an example how to use `txt2gcal'.  Let's suppose there is a
text file by the name of `demo' with the following contents:

             Hi friends,
     
     I'm the demo text containing funny characters and character
     sequences like ~~ \~ % %% $a $1 %%%\
     %\ %s %%foo %bar \%baz \\~ \~\ and so on...
     I'm be anxious how I'll be transformed by `txt2gcal'.

and `txt2gcal' processes this file, redirecting the output to `demo.rc':

     $ txt2gcal demo 0*d1#999 > demo.rc
     => 0*d1#999 \        Hi friends,~\
     => ~\
     => I'm the demo text containing funny characters and character~\
     => sequences like \~\~ \\~ % %% \$a $1 %%%\ ~\
     => %\ \%s %%foo \%bar \\%baz \\\~ \\~\ and so on...~\
     => I'm be anxious how I'll be transformed by `txt2gcal'.

then `txt2gcal' has now created a new Gcal resource file `demo.rc' from
the text file `demo'.  Let's finally see how Gcal will interpret this
new resource file:

     $ gcal -H no -Ax -f ./demo.rc
     -|
     -| Thu, May   2nd 1996:
     -|         Hi friends,
     -|
     -| I'm the demo text containing funny characters and character
     -| sequences like ~~ \~ % %% $a $1 %%%\
     -| %\ %s %%foo %bar \%baz \\~ \~\ and so on...
     -| I'm be anxious how I'll be transformed by `txt2gcal'.

Aspects in Internationalization
*******************************

  Starting with version 2.00, Gcal is able to display message texts
using any native languages instead of using the English language only,
because parts of the GNU `gettext' package are integrated into the
Software.  *Note Introduction: (gettext)Top, for more details.

  By default, Gcal displays all message texts using the English native
language in case no other native language is wanted.  A so-called
*message catalog* is read by Gcal at run-time if message texts from
another native language are required.  Gcal 2.10 supports the following
native languages:

     English (en)
     German (de)

  It is only necessary to set one of the environment variables (which
are listed here with decreasing priority)

  1. `LANGUAGE' (*note LANGUAGE: Environment variables.)

  2. `LC_ALL' (*note LC_ALL: Environment variables.)

  3. `LC_MESSAGES' (*note LC_MESSAGES: Environment variables.)

  4. `LANG' (*note LANG: Environment variables.)

with a language code to select another native language instead of the
English native language.

  Normally, users only have to set the `LANG' environment variable to
tell Gcal the native language to use at run-time.  Presuming users want
to run Gcal using the German native language for displaying message
texts, they merely have to execute `setenv LANG de' (in `csh') or
`export LANG; LANG=de' (in `sh') at the shell prompt.  Of course they
could even do this from their `.login' or `.profile' file.  *Note The
User's View: (gettext)Users, for more details.

  As shown above, a simple setting of `de' in the environment variable
`LANG' is sufficient to enable German message texts.  `de' is the
two-letter language code for the German language, which is defined in
the ISO-639:1988 and is called "simple language code information" in
the further context.  Other language codes can be taken from this
ISO-document (e.g. `fr' for French, `es' for Spanish etc.).

  Because Gcal as calendar program must also comply the specifics of a
used native language concerning the ordering of day, month and year
(and further things) of a displayed date, the period of Gregorian
Reformation and the representation of calendar sheets, these criterias
are likewise bound to the language code (strictly speaking, an extended
language code information).

A `en' language code effects the following internal defaults of above
criterias:

   * U.S. American date format

   * Gregorian Reformation have occured 1752

   * Week starts on Sunday

   * Representation of calendar sheet

             September 1994
          Mo Tu We Th Fr Sa Su
                    1  2  3  4
           5  6  7  8  9 10 11
          12 13 14 15 16 17 18
          19 20 21 22 23 24 25
          26 27 28 29 30

And a `de' language code (or other language codes, for which a *message
catalog* will be created and distributed in future) effects the
following internal defaults:

   * German date format

   * Gregorian Reformation have occured 1582

   * Week starts on Monday

   * Representation of calendar sheet

          September 1994
          
          Sunday          4 11 18 25
          Monday          5 12 19 26
          Tuesday         6 13 20 27
          Wednesday       7 14 21 28
          Thursday     1  8 15 22 29
          Friday       2  9 16 23 30
          Saturday     3 10 17 24

  Remember, all these internal defaults are modifiable by the according
options (`--date-format', `--gregorian-reform', `--starting-day' and
`--type').

  If no language code is detected, Gcal takes the internal defaults of
the `en' language code (or to be more precise, of the extended language
code information `en_us').

  If a language code is specified for which no *message catalog* is
installed, Gcal takes the internal defaults of the `de' language code,
but displays the message texts using the English native language.
Actually, this behavior seems to me the most proper solution in such a
case.  The English native language is speaken all over the world unlike
the German or other native languages, so it is wise to use it here.
But the other criterias bound to the English native language are so
special for users of other native languages that it is wise to use the
criterias taken for internal defaults of the `de' language code,
because most european countries (taken as standard) use them.

  Now British users will certainly ask whether they could use their
date format as an internal default (all other internal defaults of the
simple `en' language code information meet their criterias).  The
answer to this is a simple `yes', nevertheless these users have to set
the environment variable `LANG' with an "extended language code
information" instead of a simple language code information.  The usual
template of an extended language code information is as follows:

   * For XPG syntax (X/Open Portability Guide):
          LANGUAGE[_TERRITORY][.CODESET][@MODIFIER]

   * For CEN syntax (Comite Europen de Normalisation):
          LANGUAGE[_TERRITORY][+AUDIENCE][+SPECIAL][,SPONSOR][_REVISION]

  Both syntax's contain the LANGUAGE and TERRITORY components, which
are used by Gcal to select the native language and the other criterias.
The LANGUAGE component is equivalent to the simple language code
information and the TERRITORY component is a two-letter territory code
as defined by the ISO-3166 like `gb' for Great Britain or `us' for the
U.S.A.  See the pertinent literature for more details.  So British
users only have to set the `LANG' environment variable with a `en_gb'
contents, after that they can use the British date format as an internal
default.

Meta Symbols
************

  Within this document the following *metasyntactic* conventions will
be used when discussing command line options, arguments, commands and
templates:

`N'
     Argument is not optional and N must be a valid number.

`e|DVAR'
     Argument is not optional and must be a single alphabetic character.

`[TEXT]'
     Argument is optional and TEXT is a valid string of text.

`[AB]'
     Arguments are optional, any number may be used in any order, e.g.:

          NOTHING, A, B, AB, BA ...

`{AB}'
     Arguments are not optional, minimum one up to any number may be
     used in any order, e.g.:

          A, B, AB, BA ...

`[A|B]'
     Arguments are optional, select either A or B, but not both.

`A|B'
     Arguments are not optional, select either A or B, but not both.

`[A[B]]'
     Arguments are optional, select either A or AB, but not B.

`[A|B[C]]'
     Arguments are optional, select A or B or AC or BC, but not C.

`[A|BC]'
     Arguments are optional, select either AC or BC, but not A or B or
     C.

`[A]|[B]'
     Argument *lists* are optional, select either list A or list B, but
     not both.

`[...]'
     Additional arguments/files may be specified and are optional.

Coding scheme
*************

  The following coding scheme tables explain the relations between the
*date part* (YYYY...) of a resource file line and the modifiers, the
short-style option `-c|C[]', which is used for the fixed date warnings
respectively the long-style option `--period-of-fixed-dates=ARGUMENT'
may have, i.e. they point out all possible correspondences.  This is
necessary because Gcal does not respect all entries found in a resource
file if a *fixed date warning* argument is given, it respects only
those entries which have a definite relation to the *fixed date
warning* argument to avoid the output of redundant information!

In *date part* `YYYY...':

YYYY
     represents any year number (0001...9999).

MM
     represents any month number (01...12 or 99) respectively any
     textual short month name with lenght of 3 characters (Jan, Feb...).

DD
     represents any day number (1...28, 29, 30, 31 or 99).

WWW
     represents any textual short weekday name with lenght of 2...3
     characters (Mon...Sun).

?
     represents any case-insensitive single letter.

N
     represents any positive integer number (one or more digits).

Coding scheme table 1
=====================

  This table opposes all possible encode variations of a date given in
the *date part* of resource file with all fitting modifiers of the
short-style option `-c|C[]'.

     *Please note:*
     The `-c', `-ct', `-cNd', `-c*d|wN[WWW]', `-c@e|DVAR[[+|-]N[WWW]]',
     `-cMMDD' and `-cMMWWWN' options respect *all* encode variations of
     the *date part*!

`*Date part of resource file*'
     *Short-style option -c|C[]*

`00000000'
     `-cN+|-'

`000000DD'
     `-cNw|+|-', `-cw[+|-]', `-cm[+|-]'

`0000MM00'
     `-cN+|-'

`0000MMDD'
     `-cNw|+|-', `-cw[+|-]', `-cm[+|-]', `-cy[+|-]', `-clNd|w|+|-',
     `-cl*d|wN[WWW]',
     `-cl@e|DVAR[[+|-]N[WWW]]', `-clMMDD', `-clMMWWWN'

`YYYY0000'
     `-cN+|-'

`YYYY00DD'
     `-cNw|+|-', `-cw[+|-]', `-cm[+|-]'

`YYYYMM00'
     `-cN+|-'

`YYYYMMDD'
     `-cNw|+|-', `-cw[+|-]', `-cm[+|-]', `-cy[+|-]', `-clNd|w|+|-',
     `-cl*d|wN[WWW]',
     `-cl@e|DVAR[[+|-]N[WWW]]', `-clMMDD', `-clMMWWWN'

`000000WWW'
     `-cNw|+|-', `-cw[+|-]'

`0000MMWWW'
     `-cNw|+|-', `-cw[+|-]'

`YYYY00WWW'
     `-cNw|+|-', `-cw[+|-]'

`YYYYMMWWW'
     `-cNw|+|-', `-cw[+|-]'

`000000WWWN'
     `-cNw|+|-', `-cw[+|-]', `-cm[+|-]'

`0000MMWWWN'
     `-cNw|+|-', `-cw[+|-]', `-cm[+|-]', `-cy[+|-]', `-clNd|w|+|-',
     `-cl*d|wN[WWW]',
     `-cl@e|DVAR[[+|-]N[WWW]]', `-clMMDD', `-clMMWWWN'

`YYYY00WWWN'
     `-cNw|+|-', `-cw[+|-]', `-cm[+|-]'

`YYYYMMWWWN'
     `-cNw|+|-', `-cw[+|-]', `-cm[+|-]', `-cy[+|-]', `-clNd|w|+|-',
     `-cl*d|wN[WWW]',
     `-cl@e|DVAR[[+|-]N[WWW]]', `-clMMDD', `-clMMWWWN'

`0000*dN[WWW]'
     `-cNw|+|-', `-cw[+|-]', `-cm[+|-]', `-cy[+|-]', `-clNd|w|+|-',
     `-cl*d|wN[WWW]',
     `-cl@e|DVAR[[+|-]N[WWW]]', `-clMMDD', `-clMMWWWN'

`YYYY*dN[WWW]'
     `-cNw|+|-', `-cw[+|-]', `-cm[+|-]', `-cy[+|-]', `-clNd|w|+|-',
     `-cl*d|wN[WWW]',
     `-cl@e|DVAR[[+|-]N[WWW]]', `-clMMDD', `-clMMWWWN'

`0000*wN[WWW]'
     `-cNw|+|-', `-cw[+|-]', `-cm[+|-]', `-cy[+|-]', `-clNd|w|+|-',
     `-cl*d|wN[WWW]',
     `-cl@e|DVAR[[+|-]N[WWW]]', `-clMMDD', `-clMMWWWN'

`YYYY*wN[WWW]'
     `-cNw|+|-', `-cw[+|-]', `-cm[+|-]', `-cy[+|-]', `-clNd|w|+|-',
     `-cl*d|wN[WWW]',
     `-cl@e|DVAR[[+|-]N[WWW]]', `-clMMDD', `-clMMWWWN'

`0000@?[+|-]N[WWW]'
     `-cNw|+|-', `-cw[+|-]', `-cm[+|-]', `-cy[+|-]', `-clNd|w|+|-',
     `-cl*d|wN[WWW]',
     `-cl@e|DVAR[[+|-]N[WWW]]', `-clMMDD', `-clMMWWWN'

`YYYY@?[+|-]N[WWW]'
     `-cNw|+|-', `-cw[+|-]', `-cm[+|-]', `-cy[+|-]', `-clNd|w|+|-',
     `-cl*d|wN[WWW]',
     `-cl@e|DVAR[[+|-]N[WWW]]', `-clMMDD', `-clMMWWWN'

Coding scheme table 2
=====================

  This table opposes all possible encode variations of the short-style
option `-c|C[]' with all fitting modifiers of a date given in the *date
part* of resource file.

`*Short-style option -c|C[]*'
     `*Date part of resource file*'

`-c'
`-ct'
`-cNd|+|-'
`-cMMDD'
`-cMMWWWN'
`-c*d|wN[WWW]'
`-c@e|DVAR[[+|-]N[WWW]]'
     `00000000', `0000MM00', `YYYY0000', `YYYYMM00', `000000DD',
     `0000MMDD', `YYYY00DD', `YYYYMMDD', `000000WWW', `0000MMWWW',
     `YYYY00WWW', `YYYYMMWWW', `000000WWWN', `0000MMWWWN', `YYYY00WWWN',
     `YYYYMMWWWN', `0000*dN', `0000*dNWWW', `YYYY*dN', `YYYY*dNWWW',
     `0000*wN', `0000*wNWWW', `YYYY*wN', `YYYY*wNWWW', `0000@?[+|-]N',
     `0000@?[+|-]NWWW', `YYYY@?[+|-]N', `YYYY@?[+|-]NWWW'

`-cw[+|-]'
`-cNw'
     `000000DD', `0000MMDD', `YYYY00DD', `YYYYMMDD', `000000WWW',
     `0000MMWWW', `YYYY00WWW', `YYYYMMWWW', `000000WWWN', `0000MMWWWN',
     `YYYY00WWWN', `YYYYMMWWWN', `0000*dN', `0000*dNWWW', `YYYY*dN',
     `YYYY*dNWWW', `0000*wN', `0000*wNWWW', `YYYY*wN', `YYYY*wNWWW',
     `0000@?[+|-]N', `0000@?[+|-]NWWW', `YYYY@?[+|-]N',
     `YYYY@?[+|-]NWWW'

`-cm[+|-]'
     `000000DD', `0000MMDD', `YYYY00DD', `YYYYMMDD', `000000WWWN',
     `0000MMWWWN', `YYYY00WWWN', `YYYYMMWWWN', `0000*dN', `0000*dNWWW',
     `YYYY*dN', `YYYY*dNWWW', `0000*wN', `0000*wNWWW', `YYYY*wN',
     `YYYY*wNWWW', `0000@?[+|-]N', `0000@?[+|-]NWWW', `YYYY@?[+|-]N',
     `YYYY@?[+|-]NWWW'

`-cy[+|-]'
`-clNd|w|+|-'
`-clMMDD'
`-clMMWWWN'
`-cl*d|wN[WWW]'
`-cl@e|DVAR[[+|-]N[WWW]]'
     `0000MMDD', `YYYYMMDD', `0000MMWWWN', `YYYYMMWWWN', `0000*dN',
     `0000*dNWWW', `YYYY*dN', `YYYY*dNWWW', `0000*wN', `0000*wNWWW',
     `YYYY*wN', `YYYY*wNWWW', `0000@?[+|-]N', `0000@?[+|-]NWWW',
     `YYYY@?[+|-]N', `YYYY@?[+|-]NWWW'

Environment variables
*********************

  Here is a list of all environment variables which are used by Gcal:

`COLUMNS'
`CO'
     Sets the number of columns on the screen.  Takes precedence over
     the number of columns specified by the `TERM' environment variable
     or the system itself.

`GCAL'
     Flags which are passed to Gcal automatically.

`GCALANSI'
     If defined or set, ANSI escape highlighting sequences are used
     respectively substituted by default if no other highlighting
     sequences are defined by command line option or found in the
     Termcap library.

`GCAL_DATE_FORMAT'
     Contains the date format text, which defines the ordering of a
     displayed date.  Takes precedence over the default date format
     text.

`GCALPATH'
     (`:') colon-separated list of directories which are searched to
     find the `.gcalrc' file.  Takes precedence over `GCAL_USR_DATADIR'
     and `GCAL_SYS_DATADIR'.

`GCALPROG'
     Contains the file name of the executable Gcal program, which is
     used by the `tcal' program to call Gcal.  Takes precedence over
     the file name `gcal', which is burned-in during the compilation
     step of `tcal'.

`GCAL_USR_DATADIR'
     Name of a directory relative to `HOME' directory, where user stores
     personal respectively *private access* resource files (dates
     files).  Takes precedence over `GCAL_SYS_DATADIR'.

`GCAL_SYS_DATADIR'
     Name of a directory absolute *root*/*$(prefix)* directory, where
     the system-administrator stores common *public access* resource
     files (dates files).

`HOME'
     Name of the users home directory (used to find the `.gcalrc' file).
     Takes precedence over `GCALPATH', `GCAL_USR_DATADIR' and
     `GCAL_SYS_DATADIR'.

`LANGUAGE'
     The national language and other cultural-specific conventions used
     by Gcal at run-time.  Takes precedence over `LC_ALL', `LC_MESSAGES'
     and `LANG'.

`LC_ALL'
     The national language and other cultural-specific conventions used
     by Gcal at run-time.  Takes precedence over `LC_MESSAGES' and
     `LANG'.

`LC_MESSAGES'
     The national language and other cultural-specific conventions used
     by Gcal at run-time.  Takes precedence over `LANG'.

`LANG'
     The national language and other cultural-specific conventions used
     by Gcal at run-time.

`LINES'
`LI'
     Sets the number of lines on the screen.  Takes precedence over the
     number of lines specified by the `TERM' environment variable or
     the system itself.

`PAGER'
     Name of the *external* pager program, which is used if the paging
     option `-p' respectively `--pager' is wanted.

`PATH'
     (`:') colon-separated list of directories which are searched to
     find the *external pager* program.  *Note `--pager': Global
     options, for more details.

`TERM'
     The type of terminal on which Gcal is being run.

`TZ'
     The time zone information, which is added to the date text of send
     Emails, created response files and created shell script files.

Error codes
***********

  Gcal produces the following *exit* codes:

`127'
     Request for help screen, software license or program version
     (adjustable).

`126'
     Invalid command line argument / option.

`125'
     Year out of range for computing the Easter Sunday's date.

`124'
     Virtual memory exhausted.

`123'
     Invalid date part in resource file or in include file.

`122'
     Invalid month field entry in resource file or in include file.

`121'
     Invalid day field entry in resource file or in include file.

`120'
     Malformed *#include* statement in resource file or in include file.

`119'
     Illegal recursive/cyclic *#include* statement in resource file or
     in include file.

`118'
     Resource file or include file not found.

`117'
     Invalid N'th weekday field (only 1...5 or 9 valid).

`116'
     Missing *whitespace* separator character between *date part* and
     *text part*.

`115'
     Response file respectively shell script can't be written.

`114'
     Invalid date variable operation.

`113'
     Referenced date variable undefined.

`112'
     Invalid date value assigned to date variable.

`111'
     Sending output to Email address fails.

`110'
     Internal error, C function pipe(), fork(), execlp() or unlink()
     fails.

`109'
     Error reading resource, include respectively response file.

`108'
     Illegal character found in response file.

`107'
     Internal error, invalid value for the size of an internal table
     occured.

`106'
     Invalid date format text specified.

`105'
     Invalid text variable definition.

`1'
     Activated `-c|C[]' or `-f|F NAME[+...]' option causes no output of
     resource file entries.

`0'
     Normal program termination.

Command Line Argument Index
***************************

  This is an alphabetical list of the command line arguments that Gcal
processes.

(removed)


Environment Variable Index
**************************

  This is an alphabetical list of the environment variables that Gcal
checks.

(removed)


Concept Index
*************

(removed)


