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

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

  This is the second edition of the Gcal documentation.

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

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

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

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

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

Gcal
****

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

  This is Edition 2.40 of the Gcal documentation, 06 May 1997, for Gcal
2.40.

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

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

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 occurring 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 at the actual date (1).

  There are two ways to display a preview of fixed dates (2) or
retrospective view of fixed dates (3).  On the one hand, Gcal can be
started using an option that 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 that 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 occurring 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 occurring 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
arguments which can be preloaded if needed.  A shell script file can be
started and calls Gcal directly with all arguments stored in it, and
all arguments which are given further in the command line.

  A list of all usable command line arguments and their descriptions
can be found in the next chapter, which helps one use Gcal in the most
efficient and productive way possible.

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

  (1)  Inclusive or exclusive.

  (2)  Future years.

  (3)  Past years.

Invoking `gcal'
***************

  Gcal is a command line oriented program.  It is usually called from
the "shell" (1) and processes given arguments that 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 incorrect 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.  *Note
Genesis of the Gregorian Calendar: Todays Calendar, and *Note Aspects
in Internationalization: Internationalization, for more details.

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

  (1)  This is an operating system program which interprets and runs
given command lines.

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 arguments 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 (1) *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 or depreciated by a `\' character to avoid
expansion by the shell.

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

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

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

  (1)  Inclusive `%DATE' and `@FILE'.

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 "fixed date option class" control the
fixed date 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 (1) 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 in the following tables, that an option
takes an optional argument.  The `|' character is used to separate
several 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 chosen 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, the 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.

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

  (1)  Unless they take an argument.

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 an ARGUMENT is given and it 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 the ARGUMENT only consists 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 the 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 the contents of the environment variable `GCAL' (*note GCAL:
     Environment Variables.), and then the 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 the contents of the environment variable `GCAL' (*note GCAL:
     Environment Variables.), and then the arguments of command line
     (in the given order) to file NAME, i.e. create shell script file
     `name'.  An automatically created shell script file is executable
     and calls Gcal directly with the arguments 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 informational texts if program internal maximums are
          reached respectively other conditions have occurred.

    `--debug=handled'
          Like `--debug=internal' and display the file names which can
          be processed respectively handled, too.

    `--debug=unhandled'
          Like `--debug=internal' and display file names which cannot be
          processed respectively handled, too.

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

    `--debug=abort'
          Like `--debug=all' and abort program with an error code if
          the file name cannot be handled, respectively other
          unmanageable conditions have occurred.  *Note Error Codes::.

`-p'
`--pager'
     Enables either an *external* pager or a simple, *internal* pager.
     If an environment variable `PAGER' is set, its contents 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 contents 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 *Note COLUMNS: Environment Variables, for more
          information.

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

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

          On MS-DOS, OS/2 and some other operating systems, Gcal uses a
          system dependent *low-level* function and respects the
          reported values.

       4. If all above actions have failed, Gcal uses default values
          (3).

`-H yes'
`--force-highlighting'
`--highlighting=yes'
     If the output of the program is redirected (4) or piped (5), the
     highlighting sequences are *not* automatically converted 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.  *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 color 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 that define the type of the ANSI escape sequence.  In
     this sense, "marking" characters are single, printable characters
     which lead and trail 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 an actual
     day, the *second* for a 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 permitted!

     For example:

          `-H \x20:\x20:\x1:#' respectively
          `--highlighting=\x20:\x20:\x1:#'
          marks the actual day like `\x20ACTUAL DATE\x20' (6) 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-given entries are always skipped).
          Please note the last abstract of this text part which informs
          you more detailed of this context.  *Note GCALANSI:
          Environment Variables, too.

     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, thus the `:' (colon)
     character itself, is used as a marking character, it must be
     encoded either octal by `\072' or hexadecimal by `\x3A'.

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

     Incomplete or non-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.

`--mail=ADDRESS'
     Send Gcal's output via `mail' (7) program to the given ADDRESS,
     e.g.:

          --mail=esken@uni-muenster.de

     All highlighting sequences produced by Gcal itself are always
     disabled respectively automatically converted 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 necessity, because it is possible that the
     `mail' program cannot perform the mailing correctly.  Please pay
     attention in this context to the further explainations concerning
     the limitations of the *text part* of a resource file line (*note
     Text part of a line::.).

     If an environment variable `MAILPROG' is defined and set, its
     contents will be used as the program name of the mailer instead of
     the standard `mail' program.  *Note MAILPROG: Environment
     Variables, for more information.

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

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

  (2)  See the standard manual pages for Termcap.

  (3)  Either 23 or 24 lines, and 80 columns.

  (4)  This means, send to another device.

  (5)  This means, used as an input data stream for another program.

  (6)  This means with a leading and a trailing blank.

  (7)  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 of eternal holiday list -- this means,
          all legal holidays and all further memorial days -- sorted in
          ascending order.

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

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

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

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

`--without-standard-holidays'
     Suppress all standard holidays in the eternal holiday list.
     Furthermore, all days of the eternal holiday list which are
     highlighted by default are no longer highlighted in the calendar
     sheets, too.

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

`-q CC[+...]'
`--cc-holidays=CC[+...]'
     Provide the eternal holiday list additionally with country
     specific holidays.  Furthermore, all additionally highlighted days
     of the eternal holiday list are highlighted in the calendar
     sheets, too.

     The CC argument is a two-letter territory or country 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.

     You can use more than one country code CC by connecting them with
     a `+' character, e.g.:

          `--cc-holidays=ca+DE+fr+it' resp.,
          `-q ca+DE+fr+it'

     includes all the country specific holidays given in the preceding
     argument into the eternal holiday list, i.e. Canadian, German,
     French and Italian holidays.

     Actually, Gcal respects the following country codes:

    `at'
          Austria

    `au'
          Australia

    `be'
          Belgium

    `ca'
          Canada

    `ch'
          Switzerland

    `cz'
          Czech Republic

    `de'
          Germany

    `dk'
          Denmark

    `es'
          Spain

    `fi'
          Finland

    `fr'
          France

    `gb'
          Great Britain

    `gr'
          Greece

    `hu'
          Hungary

    `it'
          Italy

    `mx'
          Mexico

    `nl'
          Netherlands

    `no'
          Norway

    `pl'
          Poland

    `pt'
          Portugal

    `se'
          Sweden

    `si'
          Slovenia

    `th'
          Thailand

    `us'
          U.S.A.

`-i[-]'
`--type=special|standard'
     To get the "standard" calendar format (1), start Gcal omitting the
     `-i[-]' option because it is set by default.  *Note Aspects in
     Internationalization: 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

`-O'
`--orthodox-calendar'
     Use the leap year rule as used by the Eastern orthodox churches.

     Without specifying the `--orthodox-calendar' option, Gcal is
     unable to display Gregorian years later than 2799 in the correct
     way for the Eastern churches, because they use a different scheme
     for calculating the leap years.  The method for computing leap
     years within the common Gregorian calendar, which Gcal uses by
     default, is as follows:

          A leap year is any year, which number can be divided by 4
          without a remainder, and years ending in hundrets are no leap
          years unless they are divisible by 400.

     But the Eastern orthodox churches compute leap years within the
     Gregorian calendar by using another rule:

          A leap year is any year, which number can be divided by 4
          without a remainder, and years ending in hundrets are leap
          years, if a remainder of 2 or 6 occurs when such a year is
          divided by 9.

     The first difference therefore occurs in the year 2800, which is a
     leap year in the common Gregorian calendar, but an ordinary year
     only in the calendar as used by the Eastern orthodox churches.

`-K'
`--with-week-number'
     Provide the calendar sheet with ISO-8601:1988 week numbers.

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

     If the starting day of week is not set to Monday (*note
     `--starting-day=ARGUMENT': Calendar options.), the week numbers
     are not represented correctly in most cases.  If you use this
     option, you should take care of setting Monday as the starting day
     of the week!  *Note Aspects in Internationalization:
     Internationalization, for more details.

`-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 list instead of the
     default standard format which displays the days of month in
     consecutive manner.  *Note `--list-of-fixed-dates[=short|long]':
     Fixed date options.

    `-jc'
    `--fixed-dates=special'
          Display the fixed date 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 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').

     For example:

          --starting-day=Sunday or
          --starting-day=7 or
          -s SUNDAY or
          -s sund or
          -sSu 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 which is delivered by the system date.

     *Note Aspects in Internationalization: Internationalization, for
     more details.

`--gregorian-reform=1582|1700|1752|1753|ARGUMENT'
     Set the period which was skipped during the Gregorian Reformation.
     *Note Aspects in Internationalization: Internationalization, for
     more details.  Actually, four fixed default periods are supported,
     and that of the year 1582, of the year 1700, of the year 1752 and
     of the year 1753.

     If Gcal is called with the `--gregorian-reform=1582' option, it
     assumes the Gregorian Reformation have occurred from 5th till 14th
     October 1582.

     If Gcal is called with the `--gregorian-reform=1700' option, it
     assumes the Gregorian Reformation have occurred from 19th till
     28th February 1700.

     If Gcal is called with the `--gregorian-reform=1752' option, it
     assumes the Gregorian Reformation have occurred from 3rd till 13th
     September 1752.

     If Gcal is called with the `--gregorian-reform=1753' option, it
     assumes the Gregorian Reformation have occurred from 18th till
     28th February 1753.

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

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

     Please note that it is possible to corrupt the calendars likewise
     the fixed date feature logically (which works correctly now for
     the year in which the Gregorian Reformation have occured) if
     ARGUMENT is not used with care.

`--date-format=de|us|gb|TEXT'
     Set the date format which controls the ordering and representation
     of a displayed date.  *Note Aspects in Internationalization:
     Internationalization, for more details.  The date format text is
     respected by Gcal in the eternal holiday list, in the fixed date
     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 are supported, and that
     for German users, U.S. American users and for users in Great
     Britain.

     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
     (2), 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
     currently 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 zero

    `%M'
          Month number with leading space

     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 zero

    `%Z'
          Last two digits of year number with leading space

     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 `%'

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

  (1)  Similar the BSD-`cal' program.

  (2)  But `GCAL_DATE_FORMAT' is only used in case no
`--date-format=de|us|gb|TEXT' option is given.

Fixed date options
..................

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

     A date variable name DVAR consists of a single, case-insensitive
     letter (1), 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 (2).

     For example:

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

`--export-date-variables'
     Effects 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
     must either be a valid single text variable definition or a (`:')
     colon-connected series of definitions.

     A text variable name TVAR consists of the `$' prefix and a single,
     case-insensitive letter, 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 side of the
     assignment operator character.

     For example:

          `--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 depreciate the special meaning of the `:' separator
     character -- in case this character itself is needed -- by placing
     a `\' (backslash) character before it, e.g. `\:'.  If you need the
     `\:' characters themselves, you have to protect the `\'
     (backslash) character by itself, e.g. `\\:'.

     You may depreciate the special meaning of 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 themselves in the text, you have to
     protect 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 depreciate the special meaning of the `_' (underscore)
     character -- in case this character itself is needed -- by placing
     a `\' (backslash) character before it, e.g. `\_'.  If you need the
     `\_' themselves, you have to protect the `\' (backslash) character
     by itself, e.g. `\\_'.

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

`-D ARGUMENT'
`--filter-day=ARGUMENT'
     Displays only those fixed dates, whose date is not excluded by the
     given ARGUMENT.  *Note Date part of a line::, and likewise *Note
     Exclusions without any argument `%?' special texts: Exclusions
     without any argument.  The ARGUMENT consists of one or more
     characters as used in the exclusion without any argument `%?'
     special text; but without the leading `%' character in each case.

     For example, it is possible to induce Gcal to display only those
     fixed dates from the resource file `demo.rc' for the whole year,
     which are legals holidays, and moreover, Saturdays or Sundays:

          gcal -f demo.rc --year --filter-day=Rv

`-P ARGUMENT'
`--filter-period=ARGUMENT'
     Displays only those fixed dates, whose date is not excluded by the
     given ARGUMENT.  *Note Date part of a line::, and likewise *Note
     Exclusions with date argument `%?[DATE]' special texts: Exclusions
     with date argument.  The ARGUMENT consists of one or more
     expressions as used in the exclusion with date argument `%?[DATE]'
     special text; but without the leading `%' character in each case.
     You can use more than one of these `%?[DATE]' expressions by
     connecting them with a `,' character.

     For example, it is possible to induce Gcal to display only those
     fixed dates from the resource file `demo.rc' for the whole year,
     which appear within the period of the 17th and the 20th of any
     month, and which appear on the 31st of any month.

          gcal -f demo.rc -y -P i00000017#00000020,i00000031#00000031

`-I PATTERN'
`--filter-text=PATTERN'
     Displays only those fixed dates, whose completely expanded text (3)
     contains the given PATTERN.  *Note Text part of a line::, and
     *Note `%?'... special texts for text replacement: Replacements.
     The PATTERN is a *regular expression*, as recognized by the Unix
     `ed' line-editor.  *Note Regular Expressions::, for more
     information.

     For example, it is possible to induce Gcal to display all fixed
     dates from the resource file `doctor.rc' for the current month,
     which are defined for dentists or oculists:

          gcal -f doctor.rc --month -I "[dD]entist|[oO]culist"

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

     You may depreciate the special meaning of the `_' (underscore)
     character -- in case this character itself is needed -- by placing
     a `\' (backslash) character before it, e.g. `\_'.  If you need the
     `\_' characters themselves, you have to protect the `\'
     (backslash) character by itself, e.g. `\\_'.

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

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

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

    `-C'
    `--list-of-fixed-dates=long'
          Activate fixed date function (use standard resource file
          implicitly) and list all dates related to the actual system
          date (==today), sorted in ascending order.  If no fixed dates
          related to the current day are found, an "empty" fixed date
          message only consisting of the date is displayed.

    `-C-'
    `--descending-fixed-dates=long'
          Activate fixed date function (use standard resource file
          implicitly) and list all dates related to the actual system
          date (==today), sorted in descending order.  If no fixed
          dates related to the current day are found, an "empty" fixed
          date message only consisting of the date is displayed.

`-f|F NAME[+...]'
`--resource-file=NAME[+...]'
     Activate fixed date 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 period.  If no other fixed
     date period is specified, the actual system date (==today) is used
     for the fixed date period.  If the option letter `f' of the
     short-style option is used and no dates related to the fixed date
     period are found in NAME, no fixed date messages are displayed and
     the program is terminated with an error code.  *Note 1: Error
     Codes.  If the option letter `F' of the short-style option is used
     and no dates related to the fixed date period are found in NAME,
     an "empty" fixed date message only consisting of the date is
     displayed.

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

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

     respects all files given in the preceding 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 date
     lists.

     You may depreciate the special meaning of the `+' separator
     character -- in case this character itself is needed -- by placing
     a `\' (backslash) character before it, e.g. `\+'.  If you need the
     `\+' characters themselves, you have to protect 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 depreciate the special meaning of the `_' (underscore)
     character -- in case this character itself is needed -- by placing
     a `\' (backslash) character before it, e.g. `\_'.  If you need the
     `\_' characters themselves, you have to protect the `\'
     (backslash) character by itself, e.g. `\\_'.

`-# LINE'
`--here=LINE'
     Activate fixed date function and use the LINE argument together
     with the standard resource file respectively additional resource
     files.  The LINE argument has to be a valid logical line as it may
     occur in a Gcal resource file (*note Structure of resource
     file::.), and is always evaluated at last *after* the processing
     of all resource files, which allows the dealing with references to
     exported local date or text variables.  This option may be given
     multiple and it will be processed exactly in the given order.  All
     dates are listed, sorted in ascending order, which occur in the
     fixed date period.  If no other fixed date period is specified,
     the actual system date (==today) is used for the fixed date
     period.  If no dates related to the fixed date period are found in
     the LINE, no fixed date messages are displayed and the program is
     terminated with an error code.  *Note 1: Error Codes.

     For example, the call:

          gcal -# "0*d1su#99su.7 ^%:" --here="#include <foo>" -y

     effects the implicit processing of the standard resource file just
     before the further resource file line `0*d1su#99su.7 ^%:' and
     following `#include <foo>' are processed, and that as if these
     lines were a physical part of the standard resource file.

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

     You may depreciate the special meaning of the `_' (underscore)
     character -- in case this character itself is needed -- by placing
     a `\' (backslash) character before it, e.g. `\_'.  If you need the
     `\_' characters themselves, you have to protect 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
option must be constructed according to following steps, because Gcal
treats them as positional parameters:

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

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

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

     -c-t
     -cw-
     -CZBdekloUzaxA12+

and only *one* period defining fixed date period modifier may be given
(4).

  Or on the other hand, 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[-]', `-f|F NAME[+...]' or `-# LINE'
(5) must be given like:

     -c -t
     -w- -c
     -a -ABd -e -kloUxz -C12+
     -F foo.bar -dZA -l*d10
     --here="; Comment" -dZAa

  If the 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 (6), it is unnecessary to give a `-c|C[-]'
respectively `-f|F NAME[+...]' short-style option (7) to activate the
fixed date function of Gcal, because it is triggered implicitly by
means of these modifiers / alias names.

  *Note Coding Scheme::, whose 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 enabling the fixed
date feature -- 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* argument
is given, it respects only those entries which have a definite relation
to the *fixed date* argument to avoid the output of redundant
information!

*Fixed date text modifiers and options:*

`--biorhythm-axis=NUMBER'
     The width of the biorhythm text graphics -- which can be created
     by means of the biorhythm text graphics `%;[DATE]' special text --
     is changed to NUMBER characters for each axis of the bar.  The
     NUMBER argument must be an integer value between 1...100, the
     default number of characters is 20.  If the NUMBER divides 100
     with a remainder, it is internally reduced to the nearest number
     that divides 100 without any remainder.  This means, only the
     numbers 1, 2, 4, 5, 10, 20, 25, 50 and 100 are factually
     respected, so a NUMBER argument of 19 is internally reduced to 10.

     For example:

          $ cat bio.rc
          -| 0*d1#999 %;19620921
          $ gcal -f bio.rc %19961212 -s0 -xw --biorhythm-axis=19
          -|
          -| Thu, Dec <12th>1996: 0- I       P1 E        +0
          -| Fri, Dec  13th 1996: 0-  I   P   1          +0
          -| Sat, Dec  14th 1996: 0-    @   E 0          +0
          -| Sun, Dec  15th 1996: 0-  P  IE   0          +0
          -| Mon, Dec  16th 1996: 0- P  E  I  0          +0
          -| Tue, Dec  17th 1996: 1-P  E     I0          +0
          -| Wed, Dec  18th 1996: 0- @        1          +0

     *Note Biorhythm `%?[DATE]' special texts: Biorhythm, for more
     details.

`--moonimage-lines=NUMBER'
     The height of the moonphase text graphics -- which can be created
     by means of the moonphase text graphics `%:[DATE]' special text --
     is changed to NUMBER lines.  The NUMBER argument must be an integer
     value between 6...30, the default number of lines is 12.

     For example:

          $ gcal -f/dev/null -#0*d1#999_%:__%- %19950308 -x --moon=8
          -|
          -| Wed, Mar < 8th>1995:          (    @@@@@
          -|                          (           @@@@@@@@
          -|                       (               @@@@@@@@@@
          -|                      (                @@@@@@@@@@@
          -|                      (                @@@@@@@@@@@
          -|                       (               @@@@@@@@@@
          -|                        (             @@@@@@@@@@
          -|                            (        @@@@@@@ 41%+

     *Note Moonphase `%?[DATE]' special texts: Moonphase, for more
     details.

`a'
`--include-resource-file-name'
     Extend fixed date text by the name of the resource file, which the
     fixed date 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
          ...

`B'
`--bypass-shell-command'
     Don't execute shell command `%![ARGUMENT]' special texts, display
     them textually only.  *Note Shell command `%![ARGUMENT]' special
     text: Shell Command, for more details.

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

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

`g[TEXT]'
`--grouping-text[=TEXT]'
     Group fixed dates by day using the TEXT separator.  If TEXT is not
     given, the built-in TEXT (8) 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 depreciate the special meaning of the `~' (tilde) character
     -- in case this character itself is needed -- by placing a `\'
     (backslash) character before it, e.g. `\~'.  If you need the `\~'
     characters themselves, you have to protect 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 depreciate the special meaning of the `_' (underscore)
     character -- in case this character itself is needed -- by placing
     a `\' (backslash) character before it, e.g. `\_'.  If you need the
     `\_' characters themselves, you have to protect the `\'
     (backslash) character by itself, e.g. `\\_'.

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

     *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 fixed date message in case
     more than one message refers to that date (9), e.g.:

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

`U'
`--suppress-date-part'
     Suppress displaying the leading date of a fixed date message, e.g.:

          $ gcal -cU
          -|
          -| Text 1
          -| Text 2
          ...

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

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

`Z'
`--zero-dates-only'
     Display only those dates, for which fixed dates doesn't exist,
     i.e. all "empty" fixed dates only consisting of the date.

*Fixed date period modifiers and options:*

`--leap-day=february|march'
     The "leap day" (10) is observed in non-leap years.

    `--leap-day=february'
          A fixed date that 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 fixed date that 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': Fixed date 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 assumes the actual system date is the *17th
     February of any year* (00000217).

`--period-of-fixed-dates=ARGUMENT'
`Nd'
`*dN'
     Single date of absolute day N == `1...365|366|999' of the actual
     year; the intensity level is the same as the 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 the actual year; the
     intensity level is the same as the `-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 the actual year;
     the intensity level is the same as the 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 the actual year; the intensity level
     is the same as the `-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 the actual
     year; the intensity level is the same as the `-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 occurring 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 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 messages are displayed and the program is
          terminated with an error code.  *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
     intensity level is the same as the `-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 the actual year; the
     intensity level is the same as the 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 the actual
     year; the intensity level is the same as the `-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 the
     actual year; the intensity level is the same as the 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 the actual year; the intensity level is the same as
     the `-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 the actual
     year; the intensity level is the same as the simple `-c' option.

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

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

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

        * E.g. `gcal -c*d99sun' displays all fixed dates which occur on
          the last Sunday (11) of the 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
     the actual year; the intensity level is the same as the `-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 the 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 the actual year.  If the actual year has no 52nd Sunday,
          no fixed date messages are displayed and the program is
          terminated with an error code.  *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 the actual year.  If the actual year has no 53nd Sunday,
          no fixed date messages are displayed and the program is
          terminated with an error code.  *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
          (12) of the actual year.

`*wN[WWW]'
     Single date of weekday WWW of N'th == `0|1...52|53|99' ISO-week of
     the actual year; the intensity level is the same as the 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 messages are displayed and the program
          is terminated with an error code.  *Note 126: Error Codes.

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

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

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

        * E.g. `gcal -c*w99sun' displays all fixed dates which occur on
          Sunday of the last ISO-week (13) of the 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 the actual year; the intensity level is the same as the
     `-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
          messages are displayed and the program is terminated with an
          error code.  *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 messages are
          displayed and the program is terminated with an error code.
          *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 messages are
          displayed and the program is terminated with an error code.
          *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 (14) of the actual year.

`@e[[+|-]N]'
     Single date of day N relative to the Easter Sunday's date of the
     actual year; the intensity level is the same as the 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 the actual year; the intensity level is the same as the
     `-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 the actual year; the intensity level is the same as the
     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 the actual year; the intensity level is the same
     as the `-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.

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

        * E.g. `gcal -c@t' displays all fixed dates which occur on
          today's date (== `gcal -c').

        * E.g. `gcal -c@t10' respectively `gcal -c@t+10' displays all
          fixed dates which occur 10 days after today's date (== `gcal
          -c10+').

        * E.g. `gcal -c@t-10' displays all fixed dates which occur 10
          days before today's date (== `gcal -c10-').

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

        * E.g. `gcal -cl@t' displays nothing.

        * E.g. `gcal -cl@t10' respectively `gcal -cl@t+10' displays a
          list of all fixed dates which start on the 18th February and
          end 10 days after today's date (== `gcal -cl10+').

        * E.g. `gcal -cl@t-10' displays a list of all fixed dates which
          start on the 18th February and end 10 days before today's date
          (== `gcal -cl10-').

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

        * E.g. `gcal -c@t3fri' respectively `gcal -c@t+3fri' displays
          all fixed dates which occur on the 3rd Friday after today's
          date.

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

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

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

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

`@DVAR[[+|-]N]'
     Single date of day N relative to date variables date of the actual
     year; the intensity level is the same as the 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 the actual year; the intensity level is the same as the `-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
     the actual year; the intensity level is the same as the 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 the actual year; the intensity level is the same
     as the `-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 dates related to the week.
     *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 dates related to the month.

        * `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-style option
     Display dates related to the year.

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

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

  (1)  Except the date variable E that is internally reserved for the
Easter Sunday's date, so it cannot be assigned or operated therefore.
And except the date variable T that is internally reserved for today's
date, so it likewise cannot be assigned or operated.

  (2)  Or another global date variable name, but *no* date given in the
`MMWWWN', `e|t|DVAR[+|-]N[WWW]' or the `*d|wN[WWW]' format.

  (3)  Except Gcal's line break up characters `~' and `^', so you have
to use `\~' and `\\^' in the PATTERN argument if you want to search
texts which contain these characters.

  (4)  This means, exclusive the `--include-today' option respectively
`d' modifier, the `--list-mode' option respectively `l' modifier, and
the `--leap-day=february|march' option.

  (5)  Respectively their according long-style options.

  (6)  Or their according alias names like `--today', `--tomorrow'...

  (7)  Or their according long-style options.

  (8)  `RC_GROUP_SEP' "" == empty line only.

  (9)  Only if the `--alternative-format' option respectively the `A'
modifier is not given.

  (10)  The 29th February.

  (11)  That's either the 51st, 52nd or 53rd Sunday.

  (12)  That's either the 51st, 52nd or 53rd Sunday.

  (13)  That's either the 52nd or 53rd ISO-week.

  (14)  That's either the 52nd or 53rd ISO-week.

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

  If a `@FILE' option is given in the command line, a "response file"
by the name of FILE will be used, i.e. options and commands are
preloaded from that file.  A response 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 they 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, fixed dates can
be checked for *any* year and are respected in the same way, as if they
would be fixed dates of the actual year.

The date must be denoted in one of these formats:

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

   * `YYYY*d|wN[WWW]'

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

   * `MONTH NAME[DD]'

   * `WEEKDAY NAME[N]'

   * DD

Some examples to this:

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

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

        * `gcal %1994Mar'

        * `gcal %19943'

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

        * `gcal %1994Mar3'

        * `gcal %1994033'

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

        * `gcal %1994MarWed3'

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

        * `gcal %0'

        * `gcal %00'

        * `gcal %000'

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

        * `gcal %0000Mar'

        * `gcal %00003'

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

        * `gcal %0000Mar3'

        * `gcal %0000033'

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

        * `gcal %0000MarWed3'

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

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

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

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

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

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

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

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

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

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

        * `gcal %1994@e10'

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

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

        * `gcal %0@e'

        * `gcal %00@e'

        * `gcal %000@e'

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

        * `gcal %0@e10'

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

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

        * `gcal %1994@e3Wed'

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

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

        * `gcal %0@e3wed'

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

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

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

        * `gcal %1994@t10'

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

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

        * `gcal %0@t'

        * `gcal %00@t'

        * `gcal %000@t'

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

        * `gcal %0@t10'

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

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

        * `gcal %1994@t3Wed'

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

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

        * `gcal %0@t3wed'

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

        * `gcal %april3'

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

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

        * `gcal %Friday2'

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

The DD format:
        * `gcal %3'

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

Commands
--------

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

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

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

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

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

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

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

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

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

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

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

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

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

          gcal may
          gcal OCTOBER
          gcal ja

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

          gcal 1992

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

          gcal 1:6

     or like this

          gcal 6+6

     to get the year six A.C.

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

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

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

          gcal :

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

          gcal 6:
          gcal feb:
          gcal NOVEMBER:

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

          gcal :1999

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

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

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

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

          gcal .

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

          gcal . 1992

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

          gcal ..

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

          gcal .. 1992

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

          gcal .+

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

          gcal .+ 1992

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

          gcal .-

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

          gcal .- 1992

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

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

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

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

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

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

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

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

          gcal 1992;1777;1899

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

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

*Other valid lists:*

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

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

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

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

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

          gcal 3:;august:;DEC:

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

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

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

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

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

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

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

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

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

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

          gcal 1992+1994

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

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

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

  The environment variable `GCAL' can hold a set of default options for
Gcal (*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 found in a `@FILE' response
file.  *Note Command line arguments::, and *Note Response file::, for
further information.

For example:

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

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

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

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

For example:

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

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

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

  In case you start Gcal without an explicit (fiscal) date and the
*eternal holiday list* argument (*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 sheet.

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

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

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

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

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

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

  In case you start Gcal with the *eternal holiday list* argument and a
special 3-Month mode command (*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-style year
calendar sheet, and trailing all holidays of the eternal holiday list
that refer to the these months.

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

Some annotations:

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

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

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

     --cc-holidays=de+fr

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

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

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

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

  This chapter describes how to use the *fixed date* feature of Gcal.
For that purpose, you may create a Gcal resource file for showing fixed
dates and appointments (*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* argument, e.g.:

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

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

Some more examples:

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

The fixed dates can be displayed in different ways:

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

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

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

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

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

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

Annotation to previous examples:

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

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

Gcal displays a leading month, year or fiscal year calendar sheet
before all other lists.  *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* 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 system date (==today)!  Gcal displays a leading year calendar
sheet, and all fixed dates found in the resource file that refer to the
actual day (week/month/year) of the actual year.

  You can list fixed dates of past, present or future month/years, too.
This can be done on the one hand, if you use the `%DATE' option in the
way you require (*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
     intensity level is the same as the `-cy' option.

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

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

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

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

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

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

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

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

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

Gcal uses a special file searching mechanism:

  1. The Gcal program expects the standard resource file in that
     directory which is referenced in the environment variable `HOME'.
     If no `HOME' environment variable is defined and set, Gcal omits
     this step.  *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 (`:') colon-separated
     (2) list of directories.  If no such environment variable is
     defined and set, Gcal also omits this step.

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

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

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

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

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

Annotation:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The line structure of fixed date entries is:

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

or more concrete, e.g.:

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

or much more concrete, e.g.:

     19940217 Hi, I'm the text!

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

Include directives...

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

Date variable assignments respectively operations...

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

Text variable assignments...

     TVAR=[TEXT]

Text variable references...

     TVAR

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

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

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

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

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

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

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

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

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

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

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

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

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

             * N == 9
               Last weekday WWW of month.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

*Please note:*

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

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

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

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

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

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

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

   * `YYYYMM...'

   * `YYYY*d|w...'

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

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

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

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

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

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

     19960001,15 Tax returns

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

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

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

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

Some examples to this:

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

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

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

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

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

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

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

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

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

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

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

     19960001#15 Inside work

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

   * `YYYYMMWWW#WWW'

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

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

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

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

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

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

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

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

Some examples to this:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  (2)  Implicit solution.

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 and the last day of the year are always reduced to this real
difference.  In this sense, any value greater 365 (1) 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 (2).

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

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

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

  (1)  Or 366 in leap years.

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

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 greater than the real difference
between the date of the occurrence of the fixed date and 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 (1).

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

   * `YYYY@e|t|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|t|DVAR:N.N,|[+|-]N[WWW]:N.N,[+|-]N[WWW]:N.N ...'

   * `YYYY@e|t|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|t|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).

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

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

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

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

  The "text part" of a line in a resource file can be any text you like.
Indeed, some characters have a special meaning (`%', `$', `~', `^' and
`\') and must be protected should the occasion arise that special
character combinations are formed with them (1) which might be used
only textually.  If the text part contains characters that 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
(2) 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 (3) may also occur 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* text part at any
place you 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 --
this means, they are lead by a definite number of space characters.

  You may depreciate the special meaning of the `~' (tilde) character
-- in case this character itself is needed -- by placing a `\'
(backslash) character before it, e.g. `\~'.  If you need the `\~'
characters themselves, you have to protect the `\' (backslash) character
by itself, e.g. `\\~'.

  Each time a `^' (caret) character is found in the text part, this
character is also replaced by a real `\n' (newline) character.  Such
texts will be displayed by Gcal at column 1, -- this means, they are not
lead by space characters.  The rules for protecting the `^' character
are the same as the rules used for protecting the `~' character.

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 I hope I'm also 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 also long enough
     -| here, a line break up
     -|                      and again
     -| and now for the last time...
     -| 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 (4), 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 protecting 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

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

  (1)  Like `%i', `$a'...

  (2)  These are potentially non-printable.

  (3)  That's the character with the value zero in the code table of
the used character set.

  (4)  These are internally skipped and remain undisplayed therefore.

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

  A line (1) 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.  *Note Text part
of a line::, for information how a `NUL' character can be used for
remarking purposes in a text part.

  The following example of the `remark.rc' resource file -- which
*only* consists of remarks -- should be enough to elucidate the above
facts:

     $ cat remark.rc
     ;00001031 ^\
                             ........^\
                              ;::;;::,^\
                              ;::;;::;,^\
                             ;;:::;;:;;,^\
               .vnmnv\%vnnv\%,.;;;:::;;:;;,  .,vnmnv\%vnmn,^\
            vnmmmn\%vnmmnv\%vnmmnv\%;;;;;;\%nmmmnv\%vnmnv\%vmmnv^\
          vnmmnv\%vmmmmnv\%vnmmmmmnv\%;:\%nmmmmmmnv\%vnmn\%vnmmmnv^\
         vnmmnv\%vnmmmnv\%vnmmmmmmmmnv\%nmmmmmmmmnv\%vnmmn\%vnmmmnv^\
        vnmmnv\%vnmmmnv\%vnmmmmmmmmnv\%vmmmmmmmmmmnv\%vnmmv\%vnmmmnv^\
       vnmmnv\%vnmmmnv\%vnmm;mmmmmmnv\%vmmmmmmmm;mmnv\%vnmnv\%vnmmmnv,^\
      vnmmnv\%vnmmmnv\%vnmm;' mmmmmnv\%vmmmmmmm;' mmnv\%vnmnv\%vnmmmnv,^\
      vnmmnv\%vnmmmnv\%vn;;    mmmmnv\%vmmmmmm;;    nv\%vnmmnv\%vnmmmnv^\
     vnmmnv\%vnmmmmnv\%v;;      mmmnv\%vmmmmm;;      v\%vnmmmnv\%vnmmmnv^\
     vnmmnv\%vnmmmmnv\%vnmmmmmmmmm;;      mmmmmmmmmnv\%vnmmmmnv\%vnmmmnv^\
     vnmmnv\%vnmmmmnv\%vnmmmmmmmmmm;;    mmmmmmmmmmnv\%vnmmmmnv\%vnmmmnv^\
     vnmmnv\%vnmmmmnv\%vnmmmmmmmmmmnv;,mmmmmmmmmmmmnv\%vn;mmmnv\%vnmmmnv^\
     vnmmnv\%vnmmm. nv\%vnmmmmmmmmmnv\%;mmmmmmmmmmmnv\%vn; mmmnv\%vnmmmnv^\
     `vnmmnv\%vnmm,  v\%vnmmmmmmmmmmnv\%nmmmmmmmmmmnv\%v;  mmnv\%vnnmmnv'^\
      vnmmnv\%vnmm;,   \%vnmmmmmmmmmnv\%nmmmmmmmmmnv\%;'   mmv\%vnmmmmnv^\
       vnmmnv\%vnmm;;,   nmmm;'             mmmm;;'    mnv\%vnmmmmnv'^\
       `vnmmnv\%vnmmm;;,.         mmnvv;,            mmnv\%vnmmmmnv'^\
        `vnmmnv\%vnmmmmnv\%vnmmmmmmmmnvvnmmmmmmnv\%vnmmmmv\%vnmmmmnv'^\
          `vnmvn\%vmmmmmnv\%vnmmmmmmmnvvnmmmmmnv\%vnmmmmn\%vnmmmnv'^\
              `vn\%nmmmmmn\%:\%vnmnmmmmn\%vnmmmnv\%:\%vnmnv\%nmnv'
     
     ; A remark line
           ; Also a remark line
     ;     A                          \
           formatted and multi-line   \
           remark

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

  (1)  Physically and logically.

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

  You may add `#include' directives in a resource file for searching and
loading further resource files (1).  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 (2)

     <FILE NAME>

  One *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 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 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 (3), because the resulting path name (4) 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 usable
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 (5) or cyclic includes (6) 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.  *Note 119: Error Codes, for more information.

  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)  A mechanism similar the method which is used by the C
Preprocessor.

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

  (3)  Even if operating systems like MS-DOS or OS/2 permits such a
disk/drive specification on principle.

  (4)  A path name lead by the user respectively system data directory
name.

  (5)  The included file tries to include itself again.

  (6)  The included file is included again by another file that occurs
at a deeper place in such a chain.

`%?'... special texts
---------------------

  The text part of a resource file line may contain 81 different
special texts which may occur in any (1) number and order.  All these
texts start with a `%' (percent) character which may be protected 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
special text to be used -- and if it is a letter, Gcal accepts it
*case-sensitive*.

  Mainly, the sense of these special texts is to suppress output of
fixed dates in definite cases, either, or to provide them with
particular texts respectively to start external commands.  *Note
`%?'... Special Texts: Special Texts, for a complete description of all
usable special texts, and *Note Summary of all `%?'... Special Texts:
Special Texts Summary, for an according short-list of them.

  For example, the resource file `special.rc'

     ; I'm veracious very special :)
     ;
     0 1. Today is %o , %u  %M  %Y !
     0 2. It's the %#  day of the year.
     0 3. The actual week number is: %k .
     0 4. Currently, it's %t12 o'clock.

is displayed as follows (in case today's date is the 4th October 1996):

     $ gcal --resource-file=special.rc -H no -ox
     -|
     -| Fr,   4 Oct 1996: 1. Today is Friday, 04th October 1996!
     -|                   2. It's the 278th day of the year.
     -|                   3. The actual week number is: 40.
     -|                   4. Currently, it's 01:25am o'clock.

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

  (1)  Rational!

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

  Gcal respects *global* and/or *local* date variables which may be
used either in the date part of a Gcal resource file line, or which may
be part of a special text in the text part of a Gcal resource file line.

  *Note `--date-variable=ARGUMENT': Fixed date options, for more
information how global date variables can be used.

  This means, up to *24* user defined date variables can be set and
referenced during program execution.  A date variable name DVAR
consists of a single, case-insensitive letter (1), 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 (2), e.g.:

     a=1127
     c=a

stores the 27th November into the local date variable A and into 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 --
and 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
(3) are always global.  If a resource file line contains a reference to
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, informational messages for each
undefined date variable will be shown on the *standard error channel*
(*note `--debug=internal': Global options.).  If the `--debug=abort'
option is given, the Gcal program will be aborted with an error code
when the first undefined global date variable reference occurs.  *Note
113: Error Codes, and *Note `--debug=abort': Global options, for more
information.

  A local date variable can be deleted.  This 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:

     ; dvar.rc
     ;
     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 effects 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 exactly know what you're
doing when applying this option; *you are expressively warned now!*

  Some basic operations can be performed on date variables.  These are:

*Operation*    *Description*                                              
`DVAR++'       Simple increment by one day.                               
`DVAR--'       Simple decrement 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 (4), not in further resource files
processed.  This means, the initial values of global date variables are
always restored if the resource file changes.

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

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

  (1)  Except the date variable E that is internally reserved for the
Easter Sunday's date, so it cannot be assigned or operated therefore.
And except the date variable T that is internally reserved for today's
date, so it likewise cannot be assigned or operated.

  (2)  Or the name of another date variable.

  (3)  In the command line, environment variable `GCAL' or response
file.

  (4)  They are only done locally.

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

  Gcal respects *global* and/or *local* text variables which may be
used anywhere in a line of a Gcal resource file.

  *Note `--text-variable=ARGUMENT': Fixed date options, for more
information how global text variables can be used.

  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, case-insensitive letter, 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 side 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 depreciate the special meaning of 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 themselves in the text, you have to protect 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 partial) date parts
(*note Date part of a line::.), likewise special texts (*note `%?'...
special texts: Special texts processed.) 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
(1) are always global.  If a resource file line contains a reference to
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 effects 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 exactly know 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 redefinitions are only valid in
that specific file (2), not in further resource files processed.  This
means, the initial values of global text variables are always restored
if the resource file changes.

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

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

  (1)  In the command line, environment variable `GCAL' or response
file.

  (2)  They are only done locally.

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 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%i1952#2062
     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%i#1979
     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
     ;
     ; Next entry is respected by ALL fixed date 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
     ; or
     0@a-1wed 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%i0000
     $b=#0000
     $c=fri2
     $d=fri3
     00000113 $a01$c$b01$c
     00000113 $a01$d$b01$d
     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, and
that by using the fact, that a Friday the 13th only occurs if the first
day of a month is a Sunday:

     $a=%n+12 is a Friday%i0000
     $b=#0000
     $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

Of course, preceding textual expense for the purpose of detecting all
Fridays the 13th of a year can be dramatically reduced by simply using
of

     0*d1fri#99fri.7 Friday the 13th%i00000013#00000013

in the resource file `demo3.rc', respectively,

     0*d1sun#99sun.7 n+12 is a Friday%i00000001#00000001

in the `demo4.rc' resource file.

On the one hand, preceding *one-liners* reduce the coding expense quite
considerably -- from 28 respectively 15 lines to 1 line in each case
--, but on the other hand, this partly increases the checking expense
of these *one-liners* considerably and results to a longer program
run-time therefore.  Both *one-liners* produce about 52 internal
productions respectively effective fixed date entries of themselves for
each year checked by Gcal, at which the `demo3.rc' and `demo4.rc'
resource files cause 24 respectively 12 effective fixed date entries
only.

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

     $a=%VWork day
     $c=%i#0000$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=%VWork day
     $c=%i#0000$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 August 1996 is as follows:

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

And of course, the preceding textual expense for the purpose of
detecting all work days of any month can be dramatically reduced by
simply using of

     00000001#0099 %V%rWork day

in the resource file `demo5.rc'.

And finally a resource file by the name of `swtime.rc' which results
fixed date messages for the change of daylight-saving time valid since
1980 for the Federal Republic of Germany (1).

     ;
     ; `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.)%i1980
     ;
     a=09sun9
     0@a-2#+2 Winter $a~-1 hrs. (03:00 --> 02:00 h.)%i1980#1995
     ;
     a=10sun9
     0@a-2#+2 Winter $a~-1 hrs. (03:00 --> 02:00 h.)%i1996

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

  (1)  Two days before adaptation till two days after adaptation.

Genesis of the Gregorian Calendar
*********************************

  The nowadays calendar was first formulated in several inaccurate
variations by the Romans based on methods developed by the Babylonians
and Egypts.  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 laid 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, so the 29th February was designed to be
the leap day now.

  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 Mohammedan moon calendar in 1979 after
removal of the Shah reign.  There are some efforts to improve our
currently 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 churches.

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

  Three small utility programs are part of the Gcal 2.40 package.  The
`tcal' program runs the Gcal program with the date set one day ahead.
The `txt2gcal' program creates a verbatim Gcal resource file from a text
file, and in contrast to this, the `gcal2txt' program creates a verbatim
text file from a Gcal resource file.

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

  The `tcal' program runs `gcal' with the date of tomorrow's day (1).
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 tomorrow's
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 system date (==today).
(Works only for Gregorian years.)  The `--shift' option must be given
before all other ARGUMENTS that 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, any other
value means an error has occurred.

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.

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

  (1)  This is equivalent the `--shift=1' option.

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 argument is given or/but `-', 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, any
other value means an error has occurred.

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

Invoking `gcal2txt'
===================

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

     gcal2txt [--help | --version] | [RESOURCE-FILE|-]

  If no RESOURCE-FILE argument is given or/but `-', the program reads
and processes all input received from the *standard input channel*.  All
results are always shown on the *standard output channel*.  An exit
status of 0 means all processing is successfully done, any other value
means an error has occurred.

  The sense and purpose of `gcal2txt' is to retrieve all additional
texts, which are put in output by means of `txt2gcal'.

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 `gcal2txt'.  For that purpose, let's
use the resource file `demo.rc' of the previous section (*note Invoking
`txt2gcal': Invoking txt2gcal.), which was created by means of
`txt2gcal' from a text file and which looks like this:

     $ cat 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'.

Now let's see, how this resource file will be processed by `gcal2txt':

     $ gcal2txt demo.rc
     -|         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.40 supports the following
native languages:

*Native Language*        *Language Code*                                  
English                  `en'                                             
German                   `de'                                             
French                   `fr'                                             
Dutch                    `nl'                                             
Swedish                  `sv'                                             

  It is only necessary to set one of the environment variables (1):

1.  `LANGUAGE'                                                            
2.  `LC_ALL'                                                              
3.  `LC_MESSAGES'                                                         
4.  `LANG'                                                                

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 level.  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 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 (2).

  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 criteria
are likewise bound to the language code (3).

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

   * U.S. American date format

   * Gregorian Reformation have occurred 1752

   * Week starts on Sunday

   * Representation of calendar sheet

             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

And a `de' language code (4) effects the following internal defaults:

   * German date format

   * Gregorian Reformation have occurred 1582

   * Week starts on Monday

   * Representation of calendar sheet

          September 1994
          
          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
          Sunday       4 11 18 25

  Remember, all these internal defaults are modifiable by the 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 (5).

  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 spoken all over the world unlike
the German or other native languages, so it is wise to use it here.
But the other criteria bound to the English native language are so
special for users of other native languages, that it is wise to use the
criteria taken for internal defaults of the `de' language code, because
most European countries (taken as standard) essentially use them.

  Now British users will certainly ask whether they could use their
date format as an internal default (6).  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 (Comit Europn 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 criteria.
The LANGUAGE component is equivalent to the simple language code
information and the TERRITORY component is a two-letter territory or
country 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, and after that, they can use the British date format
as an internal default.

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

  (1)  Listed in decreasing priority as they are respected.

  (2)  For example `fr' for French, `es' for Spanish...

  (3)  Strictly speaking, an extended language code information.

  (4)  Or other language codes, for which a *message catalog* will be
created and distributed in future.

  (5)  Or to be more precise, of the extended language code information
`en_US'.

  (6)  All other internal defaults of the simple `en' language code
information just meet their criteria.

Metasymbols
***********

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

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

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

`$TVAR'
     Argument is not optional and must be a single alphabetic character,
     that is lead by a `$' 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.

Regular Expressions
*******************

This appendix is derived from the `gawk-3.0.0' and `regex-0.12' manuals.

  A "regular expression", or "regexp", is a way of describing a set of
strings.  The simplest regular expression is a sequence of letters,
numbers, or both.  Such a regexp matches any string that contains that
sequence.  Thus, the regexp `foo' matches any string containing `foo'.
Other kinds of regular expressions let you specify more complicated
classes of strings.

  Gcal uses exactly one of the following regular expression programming
libraries respectively methods, and that in the decreasing priority how
it is chosen at configuration time, or better, compile time of the
software:

*No.**Function*                                             *Symbol*       
1.   GNU `re_compile_pattern()' and `regex.h'               `GNU-REGEX'    
2.   POSIX `regcomp()' and `regex.h'                        `POSIX-REGEX'  
3.   BSD `re_comp()'                                        `BSD-REGEX'    
4.   System V `regcmp()'                                    `SysV-REGEX'   
5.   Henry Spencer V8 `regcomp()' and `regexp.h'            `V8-REGEX'     
6.   Pattern matching is supported, but without             `NO-REGEX'     
     metacharacters                                                        

  Try `gcal --version' for detecting the kind of regular expression
programming library respectively method that is burned-in in your Gcal
program!

How to Use Regular Expressions
==============================

  A regular expression can be used as a pattern if Gcal's
`--filter-text=PATTERN' option is specified at program start-up.

  *Note `--filter-text=PATTERN': Fixed date options, for more details.

  Then the regular expression is tested against the entire, completely
expanded text of each *valid* fixed date, and the fixed date is only
displayed in case the pattern matches the text (1).

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

  (1)  Normally, it only needs to match some part of the text in order
to succeed.

Regular Expression Operators
============================

  You can combine regular expressions with the following characters,
called "regular expression operators", or "metacharacters", to increase
the power and versatility of regular expressions.

  Here is a table of these metacharacters.  All characters that are not
listed in the table stand for themselves.

`\'
     This is used to suppress the special meaning of a character when
     matching.  For example:

          \$

     matches the character `$'.

`^'
     This matches the beginning of a string.  For example:

          ^@chapter

     matches the `@chapter' at the beginning of a string, and can be
     used to identify chapter beginnings in Texinfo source files.  The
     `^' is known as an "anchor", since it anchors the pattern to
     matching only at the beginning of the string.

`$'
     This is similar to `^', but it matches only at the end of a string.
     For example:

          p$

     matches a string that ends with a `p'.  The `$' is also an anchor.

`.'
     The period, or dot, matches any single character.  For example:

          .P

     matches any single character followed by a `P' in a string.  Using
     concatenation we can make a regular expression like `U.A', which
     matches any three-character sequence that begins with `U' and ends
     with `A'.

`[...]'
     This is called a "character list".  It matches any *one* of the
     characters that are enclosed in the square brackets.  For example:

          [MVX]

     matches any one of the characters `M', `V', or `X' in a string.

     Ranges of characters are indicated by using a hyphen between the
     beginning and ending characters, and enclosing the whole thing in
     brackets.  For example:

          [0-9]

     matches any digit.  Multiple ranges are allowed. E.g., the list
     `[A-Za-z0-9]' is a common way to express the idea of "all
     alphanumeric characters."

     To include one of the characters `\', `]', `-' or `^' in a
     character list, put a `\' in front of it.  For example:

          [d\]]

     matches either `d', or `]'.

     "Character classes" are a new feature introduced in the POSIX
     standard.  A character class is a special notation for describing
     lists of characters that have a specific attribute, but where the
     actual characters themselves can vary from country to country
     and/or from character set to character set.  For example, the
     notion of what is an alphabetic character differs in the U.S.A.
     and in France.

     A character class is only valid in a regexp *inside* the brackets
     of a character list.  Character classes consist of `[:', a keyword
     denoting the class, and `:]'.  Here are the character classes
     defined by the POSIX standard:

    `[:alnum:]'
          Alphanumeric characters.

    `[:alpha:]'
          Alphabetic characters.

    `[:blank:]'
          Space and tab characters.

    `[:cntrl:]'
          Control characters.

    `[:digit:]'
          Numeric characters.

    `[:graph:]'
          Characters that are printable and are also visible (1).

    `[:lower:]'
          Lower-case alphabetic characters.

    `[:print:]'
          Printable characters (2).

    `[:punct:]'
          Punctuation characters (3).

    `[:space:]'
          Space characters (4).

    `[:upper:]'
          Upper-case alphabetic characters.

    `[:xdigit:]'
          Characters that are hexadecimal digits.

     For example, before the POSIX standard, to match alphanumeric
     characters, you had to write `[A-Za-z0-9]'.  If your character set
     had other alphabetic characters in it, this would not match them.
     With the POSIX character classes, you can write `[[:alnum:]]', and
     this will match *all* the alphabetic and numeric characters in
     your character set.

     Two additional special sequences can appear in character lists.
     These apply to non-ASCII character sets, which can have single
     symbols (called "collating elements") that are represented with
     more than one character, as well as several characters that are
     equivalent for "collating", or sorting, purposes.  (E.g., in
     French, a plain `e' and a grave-accented `' are equivalent.)

    Collating Symbols
          A "collating symbol" is a multi-character collating element
          enclosed in `[.' and `.]'.  For example, if `ch' is a
          collating element, then `[[.ch.]]' is a regexp that matches
          this collating element, while `[ch]' is a regexp that matches
          either `c' or `h'.

    Equivalence Classes
          An "equivalence class" is a list of equivalent characters
          enclosed in `[=' and `=]'.  Thus, `[[=e=]]' is regexp that
          matches either `e' or `'.

     These features are very valuable in non-English speaking locales.

     *Caution:*
     The library functions that `gcal' uses for regular expression
     matching currently only recognize POSIX character classes
     (possibly); they do not recognize collating symbols or equivalence
     classes.

`[^ ...]'
     This is a "negated character list" respectively "complemented
     character list".  The first character after the `[' *must* be a
     `^'.  It matches any characters *except* those in the square
     brackets.  For example:

          [^0-9]

     matches any character that is not a digit.

`|'
     This is the "alternation operator", and it is used to specify
     alternatives.  For example:

          ^P|[0-9]

     matches any string that matches either `^P' or `[0-9]'.  This
     means it matches any string that starts with `P' or contains a
     digit.

     The alternation applies to the largest possible regexps on either
     side.  In other words, `|' has the lowest precedence of all the
     regular expression operators.

`(...)'
     Parentheses are used for grouping in regular expressions as in
     arithmetic.  They can be used to concatenate regular expressions
     containing the alternation operator, `|'.  For example,
     `@(samp|code)\{[^}]+\}' matches both `@code{foo}' and
     `@samp{bar}'. (These are Texinfo formatting control sequences.)

`*'
     This symbol means that the preceding regular expression is to be
     repeated as many times as necessary to find a match.  For example:

          ph*

     applies the `*' symbol to the preceding `h' and looks for matches
     of one `p' followed by any number of `h's.  This will also match
     just `p' if no `h's are present.

     The `*' repeats the *smallest* possible preceding expression.
     (Use parentheses if you wish to repeat a larger expression.)  It
     finds as many repetitions as possible.  For example:

          gcal --filter-text='\(c[ad][ad]*r x\)' -f sample.rc -y

     prints every fixed date in `sample.rc' containing a fixed dates
     text of the form `(car x)', `(cdr x)', `(cadr x)', and so on.
     Notice the escaping of the parentheses by preceding them with
     backslashes.

`+'
     This symbol is similar to `*', but the preceding expression must be
     matched at least once.  This means that:

          wh+y

     would match `why' and `whhy' but not `wy', whereas `wh*y' would
     match all three of these strings.  This is a simpler way of
     writing the last `*' example:

          gcal --filter-text='\(c[ad]+r x\)' -f sample.rc -y

`?'
     This symbol is similar to `*', but the preceding expression can be
     matched either once or not at all.  For example:

          fe?d

     will match `fed' and `fd', but nothing else.

`{N}'
`{N,}'
`{N,M}'
     One or two numbers inside braces denote an "interval expression"
     which is available in the POSIX standard.  If there is one number
     in the braces, the preceding regexp is repeated N times.  If there
     are two numbers separated by a comma, the preceding regexp is
     repeated N to M times.  If there is one number followed by a
     comma, then the preceding regexp is repeated at least N times.

    `wh{3}y'
          matches `whhhy' but not `why' or `whhhhy'.

    `wh{3,5}y'
          matches `whhhy' or `whhhhy' or `whhhhhy', only.

    `wh{2,}y'
          matches `whhy' or `whhhy', and so on.

  GNU software that deals with regular expressions provides a number of
additional regexp operators.  These operators are described here.

  Most of the additional operators are for dealing with word matching.
For our purposes, a "word" is a sequence of one or more letters, digits,
or underscores (`_').

`\w'
     This operator matches any word-constituent character, i.e. any
     letter, digit, or underscore. Think of it as a short-hand for
     `[A-Za-z0-9_]' or `[[:alnum:]_]'.

`\W'
     This operator matches any character that is not word-constituent.
     Think of it as a short-hand for `[^A-Za-z0-9_]' or `[^[:alnum:]_]'.

`\<'
     This operator matches the empty string at the beginning of a word.
     For example, `\<away' matches `away', but not `stowaway'.

`\>'
     This operator matches the empty string at the end of a word.  For
     example, `stow\>' matches `stow', but not `stowaway'.

`\b'
     This operator matches the empty string at either the beginning or
     the end of a word (the word *b*oundary).  For example, `\bballs?\b'
     matches either `ball' or `balls' as a separate word.

`\B'
     This operator matches the empty string within a word. In other
     words, `\B' matches the empty string that occurs between two
     word-constituent characters. For example, `\Brat\B' matches
     `crate', but it does not match `dirty rat'.  `\B' is essentially
     the opposite of `\b'.

  There are two other operators that work on buffers.  In Emacs, a
"buffer" is, naturally, an Emacs buffer.  For other programs, the
regexp library routines that `gcal' uses consider the entire string to
be matched as the buffer (5).

  For `gcal', since `^' and `$' always work in terms of the beginning
and end of strings, these operators don't add any new capabilities.
They are provided for compatibility with other GNU software.

`\`'
     This operator matches the empty string at the beginning of the
     buffer.

`\''
     This operator matches the empty string at the end of the buffer.

  In regular expressions, the `*', `+', and `?' operators, as well as
the braces `{' and `}', have the highest precedence, followed by
concatenation, and finally by `|'.  As in arithmetic, parentheses can
change how operators are grouped.

  Case is normally significant in regular expressions, both when
matching ordinary characters (i.e. not metacharacters), and inside
character sets.  Thus a `w' in a regular expression matches only a
lower-case `w' and not an upper-case `W'.

  The simplest way to do a case-independent match is to use a character
list: `[Ww]'.  However, this can be cumbersome if you need to use it
often; and unfortunately, it can make the regular expressions harder to
read.

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

  (1)  A space is printable, but not visible, while an `a' is both.

  (2)  Characters that are not control characters.

  (3)  Characters that are not letter, digits, control characters, or
space characters.

  (4)  Such as Space, Tab, and Form-feed, to name a few.

  (5)  That's the *text part* of a Gcal resource file line.

Summary of all Regular Expressions
**********************************

  Regular expressions are based on POSIX EREs (Extended Regular
Expressions).  Regexps are composed of characters.  Here is a
short-list of all them all:

`C'
     matches the character C (assuming C is none of the characters
     listed below).

`\C'
     matches the literal character C.

`.'
     matches any character.

`^'
     matches the beginning of a string.

`$'
     matches the end of a string.

`[ABC...]'
     matches any of the characters ABC... (character list).

`[[:CLASS:]]'
     matches any character in the character class CLASS.  Allowable
     classes are `alnum', `alpha', `blank', `cntrl', `digit', `graph',
     `lower', `print', `punct', `space', `upper', and `xdigit'.

`[[.SYMBOL.]]'
     matches the multi-character collating symbol SYMBOL.  `gcal' does
     not currently support collating symbols.

`[[=CHARS=]]'
     matches any of the equivalent characters in CHARS.  `gcal' does
     not currently support equivalence classes.

`[^ABC...]'
     matches any character except ABC... (negated resp.  complemented
     character list).

`R1|R2'
     matches either R1 or R2 (alternation).

`R1R2'
     matches R1, and then R2 (concatenation).

`R+'
     matches one or more R's.

`R*'
     matches zero or more R's.

`R?'
     matches zero or one R's.

`(R)'
     matches R (grouping).

`R{N}'
`R{N,}'
`R{N,M}'
     matches at least N, N to any number, or N to M occurrences of R
     (interval expressions).

`\b'
     matches the empty string at either the beginning or the end of a
     word.

`\B'
     matches the empty string within a word.

`\<'
     matches the empty string at the beginning of a word.

`\>'
     matches the empty string at the end of a word.

`\w'
     matches any word-constituent character (alphanumeric characters and
     the underscore).

`\W'
     matches any character that is not word-constituent.

`\`'
     matches the empty string at the beginning of a buffer (1).

`\''
     matches the empty string at the end of a buffer.

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

  (1)  Same as a *text part* of a resource file line in `gcal'.

`%?'... Special Texts
*********************

  The `%?'... special texts which can be used in the text part of a
Gcal resource file line can coarsely be separated into three categories.
So there are special texts used for suppression output of fixed dates in
definite cases.  Others are replaced by particular texts or cause the
shell to start external commands.  *Note `%?'... special texts: Special
texts processed, for a general description of the special texts which
may be used in the text part of a Gcal resource file line.

  Some of these special text may have an optional simple or special date
argument (called DATE in the further context) or another argument
(called ARGUMENT in the further context).  The DATE argument must be
given in one of the following date formats in case a special text is
directly trailed by it:

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

   * `YYYY*d|wN[WWW]'

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

  Special texts that may have a DATE argument *must* always be trailed
by a *whitespace* character which is removed itself in output, no
matter whether DATE was given or not!

  *Note Summary of all `%?'... special texts: Special Texts Summary,
for a short-list of all applicable special texts.

`%?'... special texts for date exclusion
========================================

  `%?'... special texts used for exclusion of points of time or periods
of dates are very useful if they are used together with ranges of days
(*note Ranges of days::.).  The complete special text is always
suppressed in output in case the fixed date text must be displayed.

Exclusions with date argument `%?[DATE]' special texts
------------------------------------------------------

  First of all, an "inclusive date" period `%?[DATE]' special text can
be specified with the effect, that only those fixed dates are respected
and displayed which are part of this period.  And the specification of
an "exclusive date" period `%?[DATE]' special text effects, that only
those fixed dates are respected and displayed which are not part of
this period.

  Cleverly combined, these special texts offer very effective filtration
capabilities used for the definition of special periods in a highly
flexible manner, for example:

     0*d1#999 Every day of year: from January...August except April\
              %i00001#00008 %e00004#00004
     ;
     0*d1#999 Every day of year: from 1991...1993 and from 1996\
              except February 1992 and all September\
              %i1991#1993 %i1996# %e19922#19922 %e00009#00009

Inclusive date period `%i[DATE][#[DATE]]' special text
......................................................

  `%i[DATE][#[DATE]]' references an inclusive date period, i.e. all
dates which are part of the specified period are valid and are
displayed.  Of course this means, that all fixed dates which are not
part of this period (not covered by it) are invalid and remain
un-displayed therefore.

  The first specified date defines the "starting date" of the fixed
date, i.e. the first date the fixed date may occur.  For the starting
date, the following rules concerning definite omission values are
valid, elucidated by using the `YYYY[MM[DD|WWWN]]' date format:

   * 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,
     and the December is assumed in case MM is set to 99.

   * 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, and
     the last day of the month MM is assumed in case DD is set to 99.

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

  The second specified date defines the "ending date" of the fixed date,
i.e. the last date the fixed date may occur.  For the ending date, the
following rules concerning definite omission values are valid, likewise
elucidated by using the `YYYY[MM[DD|WWWN]]' date format:

   * 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,
     and the December is assumed in case MM is set to 99.

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

   * If DD is set to 00, the current day is assumed for the day, and
     the last day of the month MM is assumed in case DD is set to 99.

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

  The preceding rules are analogously valid for the other permitted
date formats.

  If the starting date which is encoded in the `%i...' special text is
later the ending date, so the `%i...' special text will be ignored.

  In case neither the starting date nor the ending date is specified,
means only `%i' is given, the implicit period 1st January 1...31st
December 9999 (00010101...99991231) will be used.

  If only the starting date is specified, means either `%iDATE' or
`%iDATE#' is given, the implicit ending date 31st December 9999
(99991231) will be used.

  In case only the ending date is specified, means `%i#DATE' is given,
the implicit starting date 1st January 1 (00010101) will be used.

For example:

     0d*1#999 Every day of year: only April and July\
              %i00004#00004 %i00007#00007
     ;
     0*d1#999 Every day of year: from January...October\
              %i#000010
     ;
     0*d1#999 Every day of year: from August 1990\
              %i19908
     ;
     0*d1#999 Every day of year: from August...December\
              %i00008
     ;
     0*d1#999 Every day of year: only today%i0@t#0@t

Exclusive date period `%e[DATE][#[DATE]]' special text
......................................................

  `%e[DATE][#[DATE]]' references an exclusive date period, i.e. all
dates which are part of the specified period are invalid and remain
un-displayed therefore.  Of course this means, that all fixed dates
which are not part of this period (not covered by it) are valid and are
displayed.

  The first specified date defines the "starting date" of the fixed
date, i.e. the first date the fixed date may occur.  For the starting
date, the following rules concerning definite omission values are
valid, elucidated by using the `YYYY[MM[DD|WWWN]]' date format:

   * 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,
     and the December is assumed in case MM is set to 99.

   * 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, and
     the last day of the month MM is assumed in case DD is set to 99.

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

  The second specified date defines the "ending date" of the fixed date,
i.e. the last date the fixed date may occur.  For the ending date, the
following rules concerning definite omission values are valid, likewise
elucidated by using the `YYYY[MM[DD|WWWN]]' date format:

   * 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,
     and the December is assumed in case MM is set to 99.

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

   * If DD is set to 00, the current day is assumed for the day, and
     the last day of the month MM is assumed in case DD is set to 99.

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

  The preceding rules are analogously valid for the other permitted
date formats.

  If the starting date which is encoded in the `%e...' special text is
later the ending date, so the `%i...' special text will be ignored.

  In case neither the starting date nor the ending date is specified,
means only `%e' is given, the implicit period 1st January 1...31st
December 9999 (00010101...99991231) will be used.

  If only the starting date is specified, means either `%eDATE' or
`%eDATE#' is given, the implicit ending date 31st December 9999
(99991231) will be used.

  In case only the ending date is specified, means `%e#DATE' is given,
the implicit starting date 1st January 1 (00010101) will be used.

For example:

     0d*1#999 Every day of year: except April and July\
             %e00004#00004 %e00007#00007
     ;
     0*d1#999 Every day of year: except January...October\
              %e#000010
     ;
     0*d1#999 Every day of year: until July 1990\
              %e19908
     ;
     0*d1#999 Every day of year: except August...December\
              %e00008
     ;
     0*d1#999 Every day of year: except today%e0@t#0@t

Exclusions without any argument `%?' special texts
--------------------------------------------------

  First of all, an "inclusive day" period `%?' special text can be
specified with the effect, that only those fixed dates are respected
and displayed which are part of this period.  And the specification of
an "exclusive day" period `%?' special text effects, that only those
fixed dates are respected and displayed which are not part of this
period.

  Cleverly combined, these special texts also offer very effective
filtration capabilities used for the definition of very special periods.

For example:

     0*d1#999 Every day of year: all Mondays...Fridays\
              except Wednesdays and all legal holidays\
              %r%F%V
     ;
     00001001#9999 Every day in last quarter of year: all holidays\
                   which are not on a Sunday%x %P

Inclusive day period `%?' special texts
.......................................

  The following inclusive day periods `%?' special texts are respected,
at which *inclusive* is meant for the period which is not excluded.

`%v'
     Excludes fixed date in case it is not listed as legal holiday in
     the *eternal holiday list*.

`%x'
     Excludes fixed date in case it is neither listed as legal holiday
     nor memorial day in the *eternal holiday list*.

`%a'
     Excludes fixed date in case it is no Monday.

`%c'
     Excludes fixed date in case it is no Tuesday.

`%f'
     Excludes fixed date in case it is no Wednesday.

`%g'
     Excludes fixed date in case it is no Thursday.

`%h'
     Excludes fixed date in case it is no Friday.

`%l'
     Excludes fixed date in case it is no Saturday.

`%p'
     Excludes fixed date in case it is no Sunday.

`%q'
     Excludes fixed date in case it is no Monday...Thursday.

`%r'
     Excludes fixed date in case it is no Monday...Friday.

Exclusive day period `%?' special texts
.......................................

  The following exclusive day periods `%?' special texts are respected,
at which *exclusive* is meant for the period which is excluded.

`%V'
     Excludes fixed date in case it is listed as legal holiday in the
     *eternal holiday list*.

`%X'
     Excludes fixed date in case it is either listed as legal holiday or
     memorial day in the *eternal holiday list*.

`%A'
     Excludes fixed date in case it is a Monday.

`%C'
     Excludes fixed date in case it is a Tuesday.

`%F'
     Excludes fixed date in case it is a Wednesday.

`%G'
     Excludes fixed date in case it is a Thursday.

`%H'
     Excludes fixed date in case it is a Friday.

`%L'
     Excludes fixed date in case it is a Saturday.

`%P'
     Excludes fixed date in case it is a Sunday.

`%Q'
     Excludes fixed date in case it is a Monday...Thursday.

`%R'
     Excludes fixed date in case it is a Monday...Friday.

`%?'... special texts for text replacement
==========================================

  `%?'... special texts which are replaced by particular texts at
program run-time effects interspersing of data into the fixed date text,
which quality is essentially depending on the command line arguments
given for running the program.  The complete special text is always
replaced accordingly in output if the fixed date text must be displayed.

  Cleverly combined, these special texts also offer very effective
mechanisms used for the definition of particular texts in a highly
flexible manner, for example:

     0*d1#999 Every day of year: Today is %o, the %n (%+)

Replacements with date argument `%?[DATE]' special texts
--------------------------------------------------------

  Apart from different representations of a weekday name, it is possible
to create its weekday number.  Likewise, the current day of year, the
day number, the week number, the month name, the month number, the year
number, the moonphase, the biorhythm, and some useful difference values
can be produced.

  For the DATE argument these `%?[DATE]' special text may have, the
following rules concerning definite omission values are valid,
elucidated by using the `YYYY[MM[DD|WWWN]]' date format (1):

   * If YYYY... is not given (==*no* date encoded), the 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 or set to 00, the current month is assumed for
     the month, and the December is assumed in case MM is set to 99.

   * If DD|WWW is not given or set to 00, the current day is assumed
     for the day, and the last day of the month is assumed in case DD
     is set to 99.

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

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

  (1)  The succeeding rules are analogously valid for the other
permitted date formats.

Weekday name `%?[DATE]' special texts
.....................................

  The following weekday name `%?[DATE]' special texts are respected:

`%o[DATE]'
     Is replaced by the complete *weekday name* of the current day,
     e.g.:

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

`%O[DATE]'
     Is replaced by the 3-letter *weekday name* of the current day,
     e.g.:

          The text `Today is %O0@t+1 , the %n+1' will be expanded to
          ==> `Today is Tue, the 11-Jun-1996', in case the actual
          system date is the 10th June 1996.

`%K[DATE]'
     Is replaced by the 2-letter *weekday name* of the current day,
     e.g.:

          The text `Today is %K , the %n' will be expanded to
          ==> `Today is Mo, the 10-Jun-1996', in case the actual system
          date is the 10th June 1996.

Weekday `%?[DATE]' special texts
................................

  The following weekday number `%?[DATE]' special texts are respected:

`%S[DATE]'
     Is replaced by the *weekday number* of the current day, and which
     is determined by the `Monday==1...Sunday==7' counting method, e.g.:

          The text `Today is weekday %S , the %n' will be expanded to
          ==> `Today is weekday 1, the 10-Jun-1996', in case the actual
          system date is the 10th June 1996.

`%I[DATE]'
     Is replaced by the *weekday number* with trailing Ordinal Number
     suffix of the current day, and which is determined by the
     `Monday==1...Sunday==7' counting method, e.g.:

          The text `Today is weekday %I0@t+1 , the %n+1' will be
          expanded to
          ==> `Today is weekday 2nd, the 11-Jun-1996', in case the
          actual system date is the 10th June 1996.

`%E[DATE]'
     Is replaced by the *weekday number* of the current day, and which
     is determined by the `Monday==0...Sunday==6' counting method, e.g.:

          The text `Today is weekday %E , the %n' will be expanded to
          ==> `Today is weekday 0, the 10-Jun-1996', in case the actual
          system date is the 10th June 1996.

`%J[DATE]'
     Is replaced by the *weekday number* with trailing Ordinal Number
     suffix of the current day, and which is determined by the
     `Monday==0...Sunday==6' counting method, e.g.:

          The text `Today is weekday %J , the %n' will be expanded to
          ==> `Today is weekday 0th, the 10-Jun-1996', in case the
          actual system date is the 10th June 1996.

`%([DATE]'
     Is replaced by the *weekday number* of the current day, and which
     is determined by the `Sunday==1...Saturday==7' counting method,
     e.g.:

          The text `Today is weekday %( , the %n' will be expanded to
          ==> `Today is weekday 2, the 10-Jun-1996', in case the actual
          system date is the 10th June 1996.

`%<[DATE]'
     Is replaced by the *weekday number* with trailing Ordinal Number
     suffix of the current day, and which is determined by the
     `Sunday==1...Saturday==7' counting method, e.g.:

          The text `Today is weekday %< , the %n' will be expanded to
          ==> `Today is weekday 2nd, the 10-Jun-1996', in case the
          actual system date is the 10th June 1996.

`%)[DATE]'
     Is replaced by the *weekday number* of the current day, and which
     is determined by the `Sunday==0...Saturday==6' counting method,
     e.g.:

          The text `Today is weekday %) , the %n' will be expanded to
          ==> `Today is weekday 1, the 10-Jun-1996', in case the actual
          system date is the 10th June 1996.

`%>[DATE]'
     Is replaced by the *weekday number* with trailing Ordinal Number
     suffix of the current day, and which is determined by the
     `Sunday==0...Saturday==6' counting method, e.g.:

          The text `Today is weekday %> , the %n' will be expanded to
          ==> `Today is weekday 1st, the 10-Jun-1996', in case the
          actual system date is the 10th June 1996.

`%[[DATE]'
     Is replaced by the *weekday number* of the current day, and which
     is determined by the `STARTING DAY OF WEEK==1...ENDING DAY OF
     WEEK==7' counting method (*note `--starting-day=ARGUMENT':
     Calendar options.), e.g.:

          The text `Today is weekday %[ , the %n' will be expanded to
          ==> `Today is weekday 4, the 10-Jun-1996', in case the actual
          system date is the 10th June 1996 and Friday (==5) is the
          starting day of week.

`%{[DATE]'
     Is replaced by the *weekday number* with trailing Ordinal Number
     suffix of the current day, and which is determined by the
     `STARTING DAY OF WEEK==1...ENDING DAY OF WEEK==7' counting method
     (*note `--starting-day=ARGUMENT': Calendar options.), e.g.:

          The text `Today is weekday %{ , the %n' will be expanded to
          ==> `Today is weekday 4th, the 10-Jun-1996', in case the
          actual system date is the 10th June 1996 and Friday (==5) is
          the starting day of week.

`%][DATE]'
     Is replaced by the *weekday number* of the current day, and which
     is determined by the `STARTING DAY OF WEEK==0...ENDING DAY OF
     WEEK==6' counting method (*note `--starting-day=ARGUMENT':
     Calendar options.), e.g.:

          The text `Today is weekday %] , the %n' will be expanded to
          ==> `Today is weekday 3, the 10-Jun-1996', in case the actual
          system date is the 10th June 1996 and Friday (==5) is the
          starting day of week.

`%}[DATE]'
     Is replaced by the *weekday number* with trailing Ordinal Number
     suffix of the current day, and which is determined by the
     `STARTING DAY OF WEEK==0...ENDING DAY OF WEEK==6' counting method
     (*note `--starting-day=ARGUMENT': Calendar options.), e.g.:

          The text `Today is weekday %} , the %n' will be expanded to
          ==> `Today is weekday 3rd, the 10-Jun-1996', in case the
          actual system date is the 10th June 1996 and Friday (==5) is
          the starting day of week.

Day number `%?[DATE]' special texts
...................................

  The following day number `%?[DATE]' special texts are respected:

`%+[DATE]'
     Is replaced by the *day number* of the current day of year, e.g.:

          The text `Day %+  of year, the %n' will be expanded to
          ==> `Day 53 of year, the 22-Feb-1996', in case the actual
          system date is the 22nd February 1996.

`%*[DATE]'
     Is replaced by the 3-digit *day number* with leading zeroes of the
     current day of year, e.g.:

          The text `Day %*0@t-1  of year, the %n-1' will be expanded to
          ==> `Day 052 of year, the 21-Feb-1996', in case the actual
          system date is the 22nd February 1996.

`%&[DATE]'
     Is replaced by the *day number* with trailing Ordinal Number suffix
     of the current day of year, e.g.:

          The text `Day %&  of year, the %n' will be expanded to
          ==> `Day 53rd of year, the 22-Feb-1996', in case the actual
          system date is the 22nd February 1996.

`%#[DATE]'
     Is replaced by the 3-digit *day number* with leading zeroes and
     trailing Ordinal Number suffix of the current day of year, e.g.:

          The text `Day %#  of year, the %n' will be expanded to
          ==> `Day 053rd of year, the 22-Feb-1996', in case the actual
          system date is the 22nd February 1996.

Day `%?[DATE]' special texts
............................

  The following day `%?[DATE]' special texts are respected:

`%D[DATE]'
     Is replaced by the *day number* of the current day of month, e.g.:

          The text `Day %D , %n' will be expanded to
          ==> `Day 2, 02-Feb-1996', in case the actual system date is
          the 2nd February 1996.

`%N[DATE]'
     Is replaced by the 2-digit *day number* with leading zero of the
     current day of month, e.g.:

          The text `Day %N0@t-1 , %n-1' will be expanded to
          ==> `Day 01, 01-Feb-1996', in case the actual system date is
          the 2nd February 1996.

`%s[DATE]'
     Is replaced by the *day number* with trailing Ordinal Number suffix
     of the current day of month, e.g.:

          The text `Day %s , %n' will be expanded to
          ==> `Day 2nd, 02-Feb-1996', in case the actual system date is
          the 2nd February 1996.

`%u[DATE]'
     Is replaced by the 2-digit *day number* with leading zero and
     trailing Ordinal Number suffix of the current day of month, e.g.:

          The text `Day %u , %n' will be expanded to
          ==> `Day 02nd, 02-Feb-1996', in case the actual system date
          is the 2nd February 1996.

Week `%?[DATE]' special text
............................

  The following week `%?[DATE]' special text are respected:

`%k[DATE]'
     Is replaced by the *ISO-week number* of the current week of year,
     e.g.:

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

Month name `%?[DATE]' special texts
...................................

  The following month name `%?[DATE]' special texts are respected:

`%M[DATE]'
     Is replaced by the complete *month name* of the current month of
     year, e.g.:

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

`%T[DATE]'
     Is replaced by the 3-letter *month name* of the current month of
     year, e.g.:

          The text `Today is %T19961010 , %n' will be expanded to
          ==> `Today is Oct, 10-Jun-1996', in case the actual system
          date is the 10th June 1996.

Month `%?[DATE]' special texts
..............................

  The following month `%?[DATE]' special texts are respected:

`%U[DATE]'
     Is replaced by the *month number* of the current month of year,
     e.g.:

          The text `Month %U , %n' will be expanded to
          ==> `Month 2, 22-Feb-1996', in case the actual system date is
          the 22nd February 1996.

`%W[DATE]'
     Is replaced by the 2-digit *month number* with leading zero of the
     current month of year, e.g.:

          The text `Month %W000001 , %n' will be expanded to
          ==> `Month 01, 22-Feb-1996', in case the actual system date
          is the 22nd February 1996.

`%z[DATE]'
     Is replaced by the *month number* with trailing Ordinal Number
     suffix of the current month of year, e.g.:

          The text `Month %z , %n' will be expanded to
          ==> `Month 2nd, 22-Feb-1996', in case the actual system date
          is the 22nd February 1996.

`%Z[DATE]'
     Is replaced by the 2-digit *month number* with leading zero and
     trailing Ordinal Number suffix of the current month of year, e.g.:

          The text `Month %Z , %n' will be expanded to
          ==> `Month 02nd, 22-Feb-1996', in case the actual system date
          is the 22nd February 1996.

Year `%?[DATE]' special texts
.............................

  The following year `%?[DATE]' special texts are respected:

`%Y[DATE]'
     Is replaced by the *year number* of the current year, e.g.:

          The text `Year %Y , %n' will be expanded to
          ==> `Year 933, 22-Feb-0933', in case the actual system date
          is the 22nd February 933.

`%=[DATE]'
     Is replaced by the 4-digit *year number* with leading zeroes of
     the current year, e.g.:

          The text `Year %=0015 , %n' will be expanded to
          ==> `Year 0015, 22-Feb-0933', in case the actual system date
          is the 22nd February 933.

Moonphase `%?[DATE]' special texts
..................................

  Gcal uses a very simple algorithm for detecting the moonphase, which
computes approximate values only.  The moonphase is always calculated
at 0 o'clock universal time.  The following moonphase `%?[DATE]'
special texts are respected:

`%-[DATE]'
     Is replaced by the *moonphase text* of the current day of year,
     e.g.:

          The text `Moonphase %- , %n' will be expanded to
          ==> `Moonphase 94%+, 22-Dec-1996', in case the actual system
          date is the 22nd December 1996.

     The constructed moonphase text consists of a percent value, which
     informs about the illuminated fraction of the Moon's disc, and a
     trailing sign that tells something about the state of the Moon.  A
     trailing `+' sign indicates a waxing Moon, a `-' sign a waning
     moon, a `@' sign indicates the Full Moon phase, and a `!' sign the
     New Moon phase.

`%_[DATE]'
     Is replaced by the 3-digit *moonphase text* with leading zeroes of
     the current day of year, e.g.:

          The text `Moonphase %_0@t+1 , %n+1' will be expanded to
          ==> `Moonphase 098%+, 23-Dec-1996', in case the actual system
          date is the 22nd December 1996.

     The constructed moonphase text consists of a percent value, which
     informs about the illuminated fraction of the Moon's disc, and a
     trailing sign that tells something about the state of the Moon.  A
     trailing `+' sign indicates a waxing Moon, a `-' sign a waning
     moon, a `@' sign indicates the Full Moon phase, and a `!' sign the
     New Moon phase.

`%:[DATE]'
     Is replaced by the *moonphase text graphics* of the current day of
     year, e.g.:

          The text `Date %n %:  --- Moonphase %_ ~Text' will be
          expanded to
          ==> `Date 08-Mar-1995 '
          ==> `           (       @@@@@@'
          ==> `      (              @@@@@@@@@'
          ==> `    (                @@@@@@@@@@@'
          ==> `  (                   @@@@@@@@@@@@'
          ==> ` (                    @@@@@@@@@@@@@'
          ==> `(                      @@@@@@@@@@@@@'
          ==> `(                      @@@@@@@@@@@@@'
          ==> ` (                    @@@@@@@@@@@@@'
          ==> `  (                   @@@@@@@@@@@@'
          ==> `   (                  @@@@@@@@@@@'
          ==> `      (             @@@@@@@@@'
          ==> `           (        @@@@@@@ --- Moonphase 041%+'
          ==> `Text', in case the actual system date is the 8th March
          1995.

     *Note `--moonimage-lines=NUMBER': Fixed date options, for how to
     change the size of a moonphase text graphics.

Biorhythm `%?[DATE]' special texts
..................................

  Gcal is able to create a "biorhythm" for any specified date of birth.
The created text shows the three standard biorhythm cycles, and that
are the 28 day emotional cycle, the 33 day intellectual cycle, and the
23 day physical cycle.  The emotional cycle governs sensibility,
nerves, moodiness, and creative ability.  The intellectual cycle
reflects intelligence, memory, mental alertness, and reasoning power.
The physical cycle represents physical strength, endurance, energy and
resistance.  All cycles start in the zero point at the date of birth
and swing like sine curves between their positive and negative maximum
values.  The periods above the zero point show the days of full
vitality and efficiency while the periods below the zero point indicate
days of reduced efficiency.  The biorhythm is implemented for
entertaining purposes only!  It is up to the user to interpret the
biorhythm texts.

  Gcal counts "critical" days, "positive" likewise "negative" days.
Critical days are those days in which one or more of the biological
cycles crosses the zero point.  At that time, one's system is said to
be in a state of flux and it may be desirable to exhibit caution.
Positive days are those days in which one or more of the biological
cycles have a positive maximum value.  At that time, one's system is
said to be in a raised state.  Negative days are those days in which
one or more of the biological cycles have a negative maximum value.  At
that time, one's system is said to be in a lessen state.

  The following biorhythm `%?[DATE]' special texts are respected:

`%,[DATE]'
     Is replaced by the *biorhythm text* of the current day of year,
     e.g.:

          The text `%,19620921' will be expanded to
          ==> `1! 0+ 0- , Emo=+022%- Int=-091%+ Phy=-014%-', in case
          the actual system date is the 12th December 1996.

     The preceding example shows the calculated biorhythm expressed as
     a series of values for a person born in 1962, September 21st.  The
     constructed text consists of two parts, and that is on the one
     hand a triplet of total values which indicate the critical,
     positive and negative day.  And on the other hand a triplet of
     values, which indicate the emotional, intellectual and physical
     cycle.

     In the first triplet of total values, a `!' suffix means a
     critical day, a `+' indicates a positive day, and a `-' suffix
     marks a negative day.

     In the second triplet of values, each single cycle percent value
     consists of a leading positive or negative sign, that tells
     something about the distance of this value to the zero point, and
     a trailing character, that tells something about the state of each
     cycle.  A trailing `+' character marks a waxing phase, a `-'
     suffix means a waning phase, and a `@' indicates the maximum value
     of a phase.

`%;[DATE]'
     Is replaced by the *biorhythm text graphics* of the current day of
     year, e.g.:

          The text `%;19620921' will be expanded to
          ==> `0-  I               P 1   E                +0', in case
          the actual system date is the 12th December 1996.

     The preceding example shows the calculated biorhythm expressed as
     a text graphics line for a person born in 1962, September 21st.
     The constructed line is a bar with a negative and positive axis of
     adjustable length (*note `--biorhythm-axis=NUMBER': Fixed date
     options.), which left margin is represented by the total value of
     the negative days (the `0-' in this case), and which right margin
     is represented by the total value of the positive days (the `+0'
     in this case).  The zero point of the co-ordinate is represented
     by the total value of the critical days, which is the `1' in this
     case.  The emotional, intellectual and the physical phase value is
     accordingly placed in scaled manner on this bar, and that by using
     the initial letter of the cycle in each case (`E', `I' and `P').
     Collapsing phase values are marked by a `@' character.

Difference value `%?[DATE]' special texts
.........................................

  The following difference value `%?[DATE]' special texts are respected:

`%yDATE'
     Is replaced by 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 the year
          of the actual system date is 1994.

`%b[DATE]'
     Is replaced by an *age value*, e.g.:

          The text `My %b1962  birthday%i1952#2062' will be expanded to
          ==> `My 32 birthday', in case the year of the actual system
          date is 1994.

     Those age values are only displayed, 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.

`%B[DATE]'
     Is replaced by an *age value* with trailing Ordinal Number suffix,
     e.g.:

          The text `My %B1962  birthday%i1952#2062' will be expanded to
          ==> `My 32nd birthday', in case the year of the actual system
          date is 1994.

     Those age values are only displayed, 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.

Replacements with other argument `%?[ARGUMENT]' special texts
-------------------------------------------------------------

  Apart from different representations of the actual system time, a
fixed format date text can be created.  Moreover, it is possible to
produce a day number, which bears the Julian date as base date and
which can be deferred if needed.

  For the ARGUMENT these `%?[ARGUMENT]' special text may have, no
special rules concerning definite omission values are valid.

Actual time `%t[ARGUMENT]' special 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 o'clock (hh:mm).

  If only `%t' is specified, the system time value will implicitly be
displayed using the *24-hour* format (==`%t24').  For displaying using
the *12-hour* format, add `12' directly behind `%t', e.g. `%t12'.

Textual date `%n[ARGUMENT]' special text
........................................

  `%n[[+|-]N]' references the current respectively queried "day number"
relative to the current date `+/-' N days and is replaced by a *date
text* in the fixed `DD-MMM-YYYY' format, e.g.:

     The resource file line `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 Single
     commands: `MM YYYY': Single commands.).

Julian day number `%j[ARGUMENT]' special text
.............................................

  `%j[[-]N]' references the current respectively queried "Julian day
number" relative to the actual system date (==today).  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.  Currently, Gcal does not evaluate the time
zone 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 special text always by one, e.g. `%j-1'.

For example:

     The resource file 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 (1), so you are able
to work with any reference values, e.g.:

     The resource file 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.

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

  (1)  A negative sign can be given to increase the readability of this
expression.

Replacements without any argument `%?' special texts
----------------------------------------------------

  Apart from further useful difference values, the text of a fixed date
can be provided with different texts used for highlighting.

Difference value `%?' special texts
...................................

  The following other difference values `%?' special texts are
respected:

`%d'
     Specifies the current respectively queried *day* relative to the
     actual system date (==today), e.g.:

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

`%w'
     Specifies the current respectively queried *week* relative to the
     actual system date (==today).

`%m'
     Specifies the current respectively queried *month* relative to the
     actual system date (==today).

`%y'
     Specifies the current respectively queried *year* relative to the
     actual system date (==today).

Highlighting `%?' special texts
...............................

  The following highlighting `%?' special texts are respected:

`%1'
     `%1' is replaced by the starting highlighting sequence respectively
     the starting marking character that is used for highlighting the
     actual day (*note `--highlighting=TEXT': Global options.).  This
     attains, that all succeeding text of the line after this special
     text is displayed in the same way as the highlighted respectively
     marked actual day.  `%1' is used together with the `%2' special
     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'
     `%2' is replaced by the ending highlighting sequence respectively
     the ending marking character that 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' special text.  The `%2' text has no effect if no preceding
     `%1' text was found on the line.

`%3'
     `%3' is replaced by the starting highlighting sequence respectively
     the starting marking character that is used for highlighting a
     holiday, (*note `--highlighting=TEXT': Global options.).  This
     attains, that all succeeding text of the line after this special
     text is displayed in the same way as the highlighted respectively
     marked holiday.  `%3' is used together with the `%4' special 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'
     `%4' is replaced by the ending highlighting sequence respectively
     the ending marking character that is used for highlighting a
     holiday.  This attains, that a possibly active highlighting
     according to a holiday is turned off respectively an ending
     marking character is produced.  `%4' is used together with the
     `%3' special text.  The `%4' text has no effect if no preceding
     `%3' text was found on the line.

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

`%6'
     `%6' is replaced by the ending highlighting sequence respectively
     the ending marking character that is used for highlighting the
     actual day if a fixed date is on today's date.  This attains, that
     a possibly active highlighting according to the actual day is
     turned off respectively an ending marking character is produced.
     `%6' is used together with the `%5' special text.  The `%6' text
     has no effect if no preceding `%5' text was found on the line.

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

`%8'
     `%8' is replaced by the ending highlighting sequence respectively
     the ending marking character that is used for highlighting a
     holiday if a fixed date is on a legal holiday date.  This attains,
     that a possibly active highlighting according to a holiday is
     turned off respectively an ending marking character is produced.
     `%8' is used together with the `%7' special text.  The `%8' text
     has no effect if no preceding `%7' text was found on the line.

`%9'
     `%9' is replaced by the starting highlighting sequence
     respectively the starting marking character that is used for
     highlighting the actual day if a fixed date is on today's date;
     otherwise `%9' is replaced by the starting highlighting sequence
     respectively the starting marking character that is used for
     highlighting a holiday if a fixed date is on a legal holiday date,
     (*note `--highlighting=TEXT': Global options.).  This attains,
     that all succeeding text of the line after this special text is
     displayed in the same way as the highlighted respectively marked
     actual day or holiday.  `%9' is used together with the `%0'
     special text -- which turns off this enabled highlighting sequence
     respectively produces the ending marking character.  If a `%9'
     text is not succeeded by a `%0' text on the line, Gcal
     automatically inserts such a `%0' text at the end of the line.

`%0'
     `%0' is replaced by the ending highlighting sequence respectively
     the ending marking character that is used for highlighting the
     actual day if a fixed date is on today's date; otherwise `%0' is
     replaced by the ending highlighting sequence respectively the
     ending marking character that is used for highlighting a holiday
     if a fixed date is on a legal holiday date.  This attains, that a
     possibly active highlighting according to today's date or a
     holiday is turned off respectively an ending marking character is
     produced.  `%0' is used together with the `%9' special text.  The
     `%0' text has no effect if no preceding `%9' text was found on the
     line.

Shell command `%![ARGUMENT]' special text
=========================================

  The ARGUMENT which trails `%!' until the end of the line, is passed
to the shell as a command for further processing.  But before, all
`%?'... special texts for replacing particular texts which are given in
ARGUMENT are interpreted by Gcal.  *Note Replacements with date
argument `%?[DATE]' special texts: Replacements with date argument.
All leading text before the `%!' special text is processed by Gcal as
usual.  If the simple `--debug' respectively `--debug=internal' option
is given at program start-up, informational messages about the executed
command and its *exit* code will be shown on the *standard error
channel* (*note `--debug=internal': Global options.).

  If the `--debug=abort' option is given, the Gcal program will be
aborted with an error code in case an *exit* code not equal zero have
occurred during the execution of the command.  *Note 2: Error Codes, and
*Note `--debug=abort': Global options, for more information.

  Use the `--bypass-shell-command' option if you want to see all
`%![ARGUMENT]' special texts textually and non-executed by the shell.
*Note `--bypass-shell-command': Fixed date options, for more details.

Summary of all `%?'... Special Texts
************************************

  Here is a short-list of all `%?'... special texts which can be used
in the text part of Gcal resource file line:

`%i[DATE][#[DATE]]'
     Exclusion of all non-inclusive date periods

`%e[DATE][#[DATE]]'
     Exclusion of all exclusive date periods

`%?' Inclusive day period
    `%v'
          Exclusion of all non-legal holidays

    `%x'
          Exclusion of all non-holidays

    `%a'
          Exclusion of all non-Mondays

    `%c'
          Exclusion of all non-Tuesdays

    `%f'
          Exclusion of all non-Wednesdays

    `%g'
          Exclusion of all non-Thursdays

    `%h'
          Exclusion of all non-Fridays

    `%l'
          Exclusion of all non-Saturdays

    `%p'
          Exclusion of all non-Sundays

    `%q'
          Exclusion of all non-Mondays...Thursdays

    `%r'
          Exclusion of all non-Mondays...Fridays

`%?' Exclusive day period
    `%V'
          Exclusion of all legal holidays

    `%X'
          Exclusion of all holidays

    `%A'
          Exclusion of all Mondays

    `%C'
          Exclusion of all Tuesdays

    `%F'
          Exclusion of all Wednesdays

    `%G'
          Exclusion of all Thursdays

    `%H'
          Exclusion of all Fridays

    `%L'
          Exclusion of all Saturdays

    `%P'
          Exclusion of all Sundays

    `%Q'
          Exclusion of all Mondays...Thursdays

    `%R'
          Exclusion of all Mondays...Fridays

`%?[DATE]' weekday name
    `%o[DATE]'
          Complete weekday name

    `%O[DATE]'
          3-letter weekday name

    `%K[DATE]'
          2-letter weekday name

`%?[DATE]' weekday
    `%S[DATE]'
          Weekday number, Mon==1...Sun==7

    `%I[DATE]'
          Weekday number, Mon==1...Sun==7, Ordinal Number suffix

    `%E[DATE]'
          Weekday number, Mon==0...Sun==6

    `%J[DATE]'
          Weekday number, Mon==0...Sun==6, Ordinal Number suffix

    `%([DATE]'
          Weekday number, Sun==1...Sat==7

    `%<[DATE]'
          Weekday number, Sun==1...Sat==7, Ordinal Number suffix

    `%)[DATE]'
          Weekday number, Sun==0...Sat==6, Ordinal Number suffix

    `%>[DATE]'
          Weekday number, Sun==0...Sat==6, Ordinal Number suffix

    `%[[DATE]'
          Weekday number, STARTING DAY OF WEEK==1

    `%{[DATE]'
          Weekday number, STARTING DAY OF WEEK==1, Ordinal Number suffix

    `%][DATE]'
          Weekday number, STARTING DAY OF WEEK==0

    `%}[DATE]'
          Weekday number, STARTING DAY OF WEEK==0, Ordinal Number suffix

`%?[DATE]' day number
    `%+[DATE]'
          Day number

    `%*[DATE]'
          Day number, 2-digits with leading zero

    `%&[DATE]'
          Day number, Ordinal Number suffix

    `%#[DATE]'
          Day number, 2-digits with leading zero, Ordinal Number suffix

`%?[DATE]' day
    `%D[DATE]'
          Day

    `%N[DATE]'
          Day, 2-digits with leading zero

    `%s[DATE]'
          Day, Ordinal Number suffix

    `%u[DATE]'
          Day, 2-digits with leading zero, Ordinal Number suffix

`%k[DATE]'
     ISO-week number

`%?[DATE]' month name
    `%M[DATE]'
          Complete month name

    `%T[DATE]'
          3-letter month name

`%?[DATE]' month
    `%U[DATE]'
          Month

    `%W[DATE]'
          Month, 2-digits with leading zero

    `%z[DATE]'
          Month, Ordinal Number suffix

    `%Z[DATE]'
          Month, 2-digits with leading zero, Ordinal Number suffix

`%?[DATE]' year
    `%Y[DATE]'
          Year

    `%=[DATE]'
          Year, 4-digits with leading zeroes

`%?[DATE]' moonphase
    `%-[DATE]'
          Moonphase text

    `%_[DATE]'
          Moonphase text, 3-digits with leading zeroes

    `%:[DATE]'
          Moonphase text graphics

`%?[DATE]' biorhythm
    `%,[DATE]'
          Biorhythm text (series of values)

    `%;[DATE]'
          Biorhythm text graphics (bar)

`%?[DATE]' difference value
    `%yDATE'
          Relative year number

    `%b[DATE]'
          Birthday (age value)

    `%B[DATE]'
          Birthday (age value), Ordinal Number suffix

`%t[12|24]'
     Actual time

`%n[[+|-]N]'
     Textual date in fixed `DD-MMM-YYYY' format

`%j[[-]N]'
     Julian day number

`%?' difference value
    `%d'
          Relative day number

    `%w'
          Relative week number

    `%m'
          Relative month number

    `%y'
          Relative year number

`%?' highlighting
    `%1'
          Start of highlighting sequence 1

    `%2'
          End of highlighting sequence 1

    `%3'
          Start of highlighting sequence 2

    `%4'
          End of highlighting sequence 2

    `%5'
          Start of highlighting sequence 1 if a fixed date is on
          today's date

    `%6'
          End of highlighting sequence 1 if a fixed date is on today's
          date

    `%7'
          Start of highlighting sequence 2 if a fixed date is on a
          legal holiday date

    `%8'
          End of highlighting sequence 2 if a fixed date is on a legal
          holiday date

    `%9'
          Start of highlighting sequence 1 if a fixed date is on
          today's date, otherwise start of highlighting sequence 2 if a
          fixed date is on a legal holiday date

    `%0'
          End of highlighting sequence 1 if a fixed date is on today's
          date, otherwise end of highlighting sequence 2 if a fixed
          date is on a legal holiday date

`%![ARGUMENT]'
     Shell executes ARGUMENT as a command

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 enabling the fixed
date feature -- respectively the `--period-of-fixed-dates=ARGUMENT'
long-style option 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* argument is given,
it respects only those entries which have a definite relation to the
*fixed date* argument to avoid the output of redundant information!

In the *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 length 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 length 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@?[[+|-]N[WWW]]', `-cMMDD'
and `-cMMWWWN' options respect *all* encode variations of the *date
part*!

*Date part*               *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@?[[+|-]N[WWW]]', `-clMMDD', `-clMMWWWN'    
`YYYY0000'                `-cN+|-'                                        
`YYYY00DD'                `-cNw|+|-', `-cw[+|-]', `-cm[+|-]'              
`YYYYMM00'                `-cN+|-'                                        
`YYYYMMDD'                `-cNw|+|-', `-cw[+|-]', `-cm[+|-]', `-cy[+|-]', 
                          `-clNd|w|+|-', `-cl*d|wN[WWW]',                 
                          `-cl@?[[+|-]N[WWW]]', `-clMMDD', `-clMMWWWN'    
`000000WWWN'              `-cNw|+|-', `-cw[+|-]', `-cm[+|-]'              
`0000MMWWWN'              `-cNw|+|-', `-cw[+|-]', `-cm[+|-]', `-cy[+|-]', 
                          `-clNd|w|+|-', `-cl*d|wN[WWW]',                 
                          `-cl@?[[+|-]N[WWW]]', `-clMMDD', `-clMMWWWN'    
`YYYY00WWWN'              `-cNw|+|-', `-cw[+|-]', `-cm[+|-]'              
`YYYYMMWWWN'              `-cNw|+|-', `-cw[+|-]', `-cm[+|-]', `-cy[+|-]', 
                          `-clNd|w|+|-', `-cl*d|wN[WWW]',                 
                          `-cl@?[[+|-]N[WWW]]', `-clMMDD', `-clMMWWWN'    
`0000*dN[WWW]'            `-cNw|+|-', `-cw[+|-]', `-cm[+|-]', `-cy[+|-]', 
                          `-clNd|w|+|-', `-cl*d|wN[WWW]',                 
                          `-cl@?[[+|-]N[WWW]]', `-clMMDD', `-clMMWWWN'    
`YYYY*dN[WWW]'            `-cNw|+|-', `-cw[+|-]', `-cm[+|-]', `-cy[+|-]', 
                          `-clNd|w|+|-', `-cl*d|wN[WWW]',                 
                          `-cl@?[[+|-]N[WWW]]', `-clMMDD', `-clMMWWWN'    
`0000*wN[WWW]'            `-cNw|+|-', `-cw[+|-]', `-cm[+|-]', `-cy[+|-]', 
                          `-clNd|w|+|-', `-cl*d|wN[WWW]',                 
                          `-cl@?[[+|-]N[WWW]]', `-clMMDD', `-clMMWWWN'    
`YYYY*wN[WWW]'            `-cNw|+|-', `-cw[+|-]', `-cm[+|-]', `-cy[+|-]', 
                          `-clNd|w|+|-', `-cl*d|wN[WWW]',                 
                          `-cl@?[[+|-]N[WWW]]', `-clMMDD', `-clMMWWWN'    
`0000@?[+|-]N[WWW]'       `-cNw|+|-', `-cw[+|-]', `-cm[+|-]', `-cy[+|-]', 
                          `-clNd|w|+|-', `-cl*d|wN[WWW]',                 
                          `-cl@?[[+|-]N[WWW]]', `-clMMDD', `-clMMWWWN'    
`YYYY@?[+|-]N[WWW]'       `-cNw|+|-', `-cw[+|-]', `-cm[+|-]', `-cy[+|-]', 
                          `-clNd|w|+|-', `-cl*d|wN[WWW]',                 
                          `-cl@?[[+|-]N[WWW]]', `-clMMDD', `-clMMWWWN'    

Coding Scheme Table 2
=====================

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

*Short-style option       *Date part*                                     
`-c|C[]'*                                                                 
`-c'                                                                      
`-ct'                                                                     
`-cNd|+|-'                                                                
`-cMMDD'                                                                  
`-cMMWWWN'                                                                
`-c*d|wN[WWW]'                                                            
`-c@?[[+|-]N[WWW]]'       `00000000', `0000MM00', `YYYY0000', `YYYYMM00', 
                          `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'               
`-cNw'                                                                    
`-cw[+|-]'                `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'               
`-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@?[[+|-]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 table 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 that 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 the 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.  This is 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.

`MAILPROG'
     Name of the mailer program which is used if the mailing option is
     wanted.  *Note `--mail=ADDRESS': Global options, for more details.

`PAGER'
     Name of the *external* pager program which is used if the paging
     option is wanted.  *Note `--pager': Global options, for more
     details.

`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 have failed.

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

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

`106'
     Invalid date format text specified.

`105'
     Invalid text variable definition.

`104'
     Invalid regular expression search pattern specified.

`3'
     Program aborted by signal.

`2'
     *Exit* code not equal zero returned by external command.

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

`0'
     Normal program termination.

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

  Here is an alphabetical list of the command line arguments processed
by Gcal:

(removed)


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

  Here is an alphabetical list of the environment variables checked by
Gcal:

(removed)


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

(removed)


