  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.

Gcal
****

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

  This is Edition 1.00 of the Gcal documentation, 09 March 1996, for
Gcal 1.00.

  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

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

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

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

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

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

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

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

         `gcal [ [Option...] [%Date] [@File...] ]  [Command]'

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

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

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

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

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

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

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

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

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

Options
-------

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

  Gcal supports both short-style options and GNU long-style options.
Traditional short-style options are indicated by a single switch
character and trailed by the option character itself and perhaps a
modifier or an argument.  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 `='.  Gcal processes the
GNU long-style options in a special, non-standard way.

There are four different types of long-style options:

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

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

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

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

Traditional short-style options differ as follows:

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

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

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

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

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

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

          --long-help=long-help

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

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

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

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

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

`-R NAME'
`--response-file=ARG'
     Write contents of environment variable `GCAL' (see GCAL),
     and then 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=ARG'
     Write contents of environment variable `GCAL' (see GCAL),
     and then arguments of command line (in
     the given order) to shell script file NAME, i.e. create file
     `name'.  An automatically created shell script file is executable
     and calls Gcal directly with the arguments, which are stored in
     it.  You may start the shell script with other command line
     arguments, which are directed to Gcal too.

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

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

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

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

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

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

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

     If no `PAGER' environment variable is set or if its value is
     invalid, Gcal tries to use the `less' pager; if this program can't
     be found during scanning the `PATH' environment variable, Gcal
     tries to use the `more' pager, if this program can't be found, the
     `pg' pager in the same way (1).  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 see COLUMNS, for more
          details.

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

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

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

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

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

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

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

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

     Some examples:

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

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

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

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

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

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

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

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

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

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

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

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

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

  (2)  See the standard *manual* pages for Termcap.

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

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

`-n|N[-]'
`--descending-holiday-list[=long|short]'
`--holiday-list[=long|short]'
     Display an eternal holiday list.  See Eternal holidays, for
     additional information.

    `-n'
    `--holiday-list=long'
          Display all holidays in eternal holiday list sorted in
          ascending order.

    `-n-'
    `--descending-holiday-list=long'
          Display all holidays in eternal holiday list sorted in
          descending order.

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

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

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

`-i[-]'
`--type=special|standard'
     To get the "standard" calendar format (similar BSD-`cal'), start
     Gcal omitting the `-i[-]' option because it is set by default, or
     by giving the `-i-' respectively the `--type=standard' option to
     force the output of a calendar sheet:

          $ gcal -i-

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

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

          $ gcal -i

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

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

`-b NUMBER'
`--blocks=ARG'
     Set number of calendar sheet blocks (valid arguments:
     `1|2|3|4|6|12').  The default value 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 warning 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 warning list using the special date
          format.  This means the days of year are displayed in
          consecutive manner instead of the days of month.

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

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

     Example:

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

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

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