  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.

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

Appendices

Indices

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.  See
Genesis of the Gregorian Calendar, and Aspects in 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' (see GCAL),
     and then the arguments of command line
     (in the given order) to file NAME, i.e. create response file
     `name'.  See Response file, for more details.

`-S NAME'
`--shell-script=NAME'
     Write the contents of the environment variable `GCAL' (see GCAL),
     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.  See 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.  See PAGER,
     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).  See PATH.

     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'.  See LINES,
          and COLUMNS, for more
          information.

       2. If above action fails, Gcal respects the values set in the
          environment variables `LI' and `CO'.  See LI,
          and CO, for more
          details.

       3. If above action fails, Gcal respects the values set in the
          `termcap' (2) file which refers to the terminal used (see
          TERM).  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.  See `--mail=ADDRESS'.

`-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.  See GCALANSI,
          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.  See GCALANSI.

`--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 (see
     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.  See MAILPROG,
     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.  See 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.  See Aspects in 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 (see
     `--starting-day=ARGUMENT'), 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!  See Aspects in 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.  See `--holiday-list[=long|short]'.

    `-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.  See `--list-of-fixed-dates[=short|long]'.

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

     See Aspects in Internationalization, for
     more details.

`--gregorian-reform=1582|1700|1752|1753|ARGUMENT'
     Set the period which was skipped during the Gregorian Reformation.
     See Aspects in 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.  See Aspects in 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.