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

  Copyright (C) 1994, 1995, 1996 Thomas Esken

  This is the first edition of the Gcal documentation.

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

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

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

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

                                \\\_''/'
-------------------------oOO    (/o-o\)    OOo-------------------------
Thomas Esken                o  (.  "  .)  o   Internet :
Im Hagenfeld 84              \___) ~ (___/      (esken@uni-muenster.de)
D-48147 M"unster; GERMANY                     Phone    : +49 251 232585

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

`-v DEFINITION'
`--date-variable=ARG'
`--assign=ARG'
     Define "global" date variable, which is visible in all referenced
     resource files (see Date variables.).  DEFINITION must either
     be a valid single date variable definition or a (`:')
     colon-separated list of definitions.

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

     Some examples:

          `--date-variable=a=1127' respectively
          `--assign=a=1127' respectively
          `-v a=1127'
          stores the 27'th November to global date variable A.

          `--date-variable=a=Nov27:b=05fr4:c=a' respectively
          `--assign=a=Nov27:b=05fr4:c=a' respectively
          `-v a=Nov27:b=05fr4:c=a'
          stores the 27'th November to global date variable A, the date
          of the 4'th Friday in May to the global date variable B and
          the value of global date variable A to C.

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

`-c|C[-]'
`--list-of-fixed-dates[=short|long]'
`--descending-fixed-dates[=short|long]'
     Display fixed date warning messages.

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

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

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

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

`-f|F NAME[+...]'
`--resource-file=ARG'
     Use file NAME instead of the standard resource file.  You can use
     more than one resource file NAME by separating them with a `+'
     separator character, e.g.:

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

     respects all files, which are given in above list.  This argument
     implies the simple `-c' respectively `--list-of-fixed-dates=short'
     option *only* (see `--list-of-fixed-dates[=short|long]').
     Set NAME to `/dev/null' to avoid the use of
     the standard resource file, useful for creating empty fixed dates
     warning lists.

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

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

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

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

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

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

    First step: *Sorting-Order-Of-Text-Modifier*
          `-'

    Second step: *Representation-Of-Text-Modifier*
          `a', `A', `e|E', `k', `o', `x', `z'

    Third step: *Respected-Warning-Period-Modifier*
          `d', `l', `c|C', `t|T', `w|W|m|M|y|Y[+|-]', `N+|-', `Nd',
          `Nw', `*dN[WWW]', `*wN[WWW]', `@e|DVAR[[+|-]N]',
          `@e|DVAR[+|-]NWWW', `MMDD', `MMWWWN'

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

     -c-t
     -cw-
     -CaAdeklorxz12+

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

*Fixed date warning text modifiers:*

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

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

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

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

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

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

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

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

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

          $ gcal -Cw -cg

          => Sun, Nov   6'th 1994: Text 1
          => Sun, Nov   6'th 1994: Text 2
          =>
          => Mon, Nov   7'th 1994: Text 3
          =>
          => Tue, Nov   8'th 1994: Text 4
          ...

          $ gcal -Cw -cg---A_User_Defined_Grouping_Text

          => Sun, Nov   6'th 1994: Text 1
          => Sun, Nov   6'th 1994: Text 2
          => ---A_User_Defined_Grouping_Text
          => Mon, Nov   7'th 1994: Text 3
          => ---A_User_Defined_Grouping_Text
          => Tue, Nov   8'th 1994: Text 4
          ...

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

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

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

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

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

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

          $ gcal -co

          => Sun, Nov   6'th 1994: Text 1
          =>                       Text 2
          ...

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

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

*Fixed date warning period modifiers:*

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

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

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

`d'
`--include-today'
     If lists of periods are generated, include the actual date into
     the list.  See -list-mode, for how to
     create a list of periods.

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

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

`--period-of-fixed-dates=ARG'
`Nd'
`*dN'
     Single date of absolute day N == `1...365|366|999' of actual year;
     the warning level is same as simple `-c' option.  If the value 999
     for N is given, the last day of the year (31'st 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 10'th day of the year.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

        * E.g. `gcal -v a=0422 -c@a' displays all fixed dates, which
          occur on the 22'nd 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 22'nd April.

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

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

        * E.g. `gcal -v a=0422 -cl@a' displays a list of all fixed
          dates, which start on the 18'th February and end on the 22'nd
          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 18'th February and end 10 days after the 22'nd April.

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

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

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

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

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

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

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

`t|T'
     List dates related to tomorrow.

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

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

`w|W[+|-]'
     Display week warnings (see `--starting-day[=ARG]').

        * `w'
          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 17'th February is part of.

        * `w+'
          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 18'th February (tomorrow) and end on the last day
               of the week.

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

        * `w-'
          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 16'th
               February (yesterday).

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

`m|M[+|-]'
     Display month warnings.

        * `m'
          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+'
          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 18'th February (tomorrow) and end on the last day
               of the month February.

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

        * `m-'
          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
               16'th February (yesterday).

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

`y|Y[+|-]'
     Display year warnings.

        * `y'
          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+'
          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 18'th February (tomorrow) and end on the last day
               of the year.

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

        * `y-'
          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 16'th
               February (yesterday).

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

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

  If a `@FILE' option is given in command line, a "response file" FILE
will be used, i.e. options and commands are preloaded from that file.
A response file FILE may contain options and commands, which are
preloaded by Gcal, but *no* reference to further response files.  If
such references to further response files are found, they are ignored.
See `--response-file=ARG', 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.  See
File searching mechanism, for more details.  Multiple
response files may be given in the command line when Gcal is started
and are processed exactly in that order as given, i.e. strictly
sequential.

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

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

For example:

  1. Contents of response file `file':

          Line     Text
          1        -j
          2        -Cw
          EOF

          $ gcal -i -b 3 @file -s 3 1994

          ==> gcal -i -b 3 -j -Cw -s 3 1994

  2. Contents of response file `file':

          Line     Text
          1        -j
          2        -Cw
          3        may 1992
          EOF

          $ gcal -i -b 3 @file -s 3 1994

          ==> gcal -i -b 3 -j -Cw may

  3. Contents of response file `file':

          Line     Text
          1        -j
          2        -Cw
          3        may
          4        1992
          EOF

          $ gcal -i -b 3 @file -s 3 1994

          ==> gcal -i -b 3 -j -Cw may 1992

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

  It is allowed to use that date instead of the actual (system) date,
which is defined by the `%DATE' option.  This means that fixed date
warning messages can be created for *any* year and are like the warning
messages of the actual year.

The date must be denoted in one of these formats:

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

   * `YYYY*d|wN[WWW]'

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

   * `MONTH NAME[DD]'

   * `WEEKDAY NAME[N]'

   * DD

Some examples to this:

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

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

        * `gcal %1994Mar'

        * `gcal %19943'

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

        * `gcal %1994Mar3'

        * `gcal %1994033'

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

        * `gcal %1994Marth'

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

        * `gcal %1994MarWed3'

        * `gcal %199403wed3' (== YYYYMMWWWN)
          The actual date is set to the date 3'rd 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 17'th March 1993
          => 19930317.

        * `gcal %0000Mar3'

        * `gcal %0000033'

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

        * `gcal %0000MarThu'

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

        * `gcal %0000MarWed3'

        * `gcal %000003wed3' (== YYYYMMWWWN)
          The actual date is set to the date 3'rd 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 10'th absolute day in 1994
          (N == `1...365|366|999') => 19940110.

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

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

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

        * `gcal %1994*w10' (== `YYYY*wN')
          The actual date is set to the date Monday of the 10'th
          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 10'th
          ISO-week in 1994 => 19940313.

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

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

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

        * `gcal %1994@e10'

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

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

        * `gcal %0@e'

        * `gcal %00@e'

        * `gcal %000@e'

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

        * `gcal %0@e10'

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

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

        * `gcal %1994@e3Wed'

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

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

        * `gcal %0@e3wed'

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

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

        * `gcal -v a=0303 %1994@a' (== `YYYY@DVAR')
          The actual date is set to the date 3'rd 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 3'rd March
          1994 => 19940313.

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

        * `gcal -v a=0303 %0@a' (== `YYYY@DVAR')
          The actual date is set to the date 3'rd 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 3'rd March
          1993 => 19930313.

        * `gcal -v a=0303 %0@a-10' (== `YYYY@DVAR-N')
          The actual date is set to the date 10 days before 3'rd 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 3'rd Wednesday after 3'rd
          March 1994 => 19940323.

        * `gcal -v a=0303 %1994@a-3wed' (== `YYYY@DVAR-NWWW')
          The actual date is set to the date 3'rd Wednesday before 3'rd
          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 3'rd Wednesday after 3'rd
          March 1993 => 19930324.

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

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

        * `gcal %april3'

        * `gcal %april03' (== MONTH NAME DD)
          The actual date is set to the date 3'rd 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 2'nd 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 3'rd February 1993
          => 19930203.

Commands
--------

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

          gcal :

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

          gcal 6:
          gcal feb:
          gcal NOVEMBER:

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

          gcal :1999

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

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

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

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

          gcal .

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

          gcal . 1992

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

          gcal ..

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

          gcal .. 1992

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

          gcal .+

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

          gcal .+ 1992

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

          gcal .-

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

          gcal .- 1992

Lists of Commands
.................

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

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

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

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

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

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

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

          gcal 1992;1777;1899

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

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

*Other valid lists:*

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

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

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

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

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

          gcal 3:;august:;DEC:

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

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

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

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

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

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

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

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

          gcal 1992+1994

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

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

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

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

For example:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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