  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

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

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

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

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

  For example:

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

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

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

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

  Gcal respects *global* and/or *local* date variables (see
`--date-variable=ARG').  This means up to *25*
user defined date variables can be set and referenced during program
execution.  The name of a date variable DVAR is a single alphabetic
character (except the `e' character, which is internally reserved for
the Easter Sunday's date and unassignable/unoperatable) followed by the
assignment operator character `=' and the numerical values of month and
day MMDD this variable has to store or the reference to another date
variable, e.g.:

     a=1127
     b=05fr4
     c=a

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

     a=03su2
     b=JunMon9
     x=*d10
     y=*d10fri
     z=*w3Su

which means, date variable A stores the date of second Sunday in March
and B stores date of last Monday in June.  The date variable X stores
the date of the 10'th absolute day of the year (== 10'th January).  Y
stores the date of the 10'th Friday of the year, and the assignment to
Z is the date of the Sunday, which occurs in the 3'rd week of the year.

*Caution:*
These kinds of assignments to date variables are *only* computed
correctly in simple year bounds, which means during a current year, not
in fixed dates shown after the current year has changed, e.g. in
`fiscal years'.

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

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

  See Include statements.

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

Some basic operations can be performed on date variables.

These are:

`DVAR++'
     Simple incrementation by one day.

`DVAR--'
     Simple decrementation by one day.

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

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

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

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

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

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

  Here are some examples how a resource file can look like:

     ; This is an example of a resource file
     ;
     19940715 Time: %t --> Dentist at 10:00
     00000921 My %b1962 birthday%s1952 %e2062
     0000093 Gregorian~reformation\~is %y1752 year ago
     0000Sep03 Gregorian~reformation\~is %y1752 year ago
     0 Every day in every month in every year
     0000 Every day in every month in every year
     00000000 Every day in every month in every year
     199400fri        Every Friday in 1994
     000007mo3 Every third Monday~in July every year less 1980%e1979
     0000@e-10 Easter Sunday-10 days every year
     0@e-10 Easter Sunday-10 days every year
     00000000@e+10 Easter Sunday+10 days every year
     a=1127
     0@a+20 20 days after date of date variable `a'
     a=*W10FR
     0@a-1 The Thursday of the 10'th ISO-week every year
     0@a   The Friday of the 10'th ISO-week every year
     0@a1  The Saturday of the 10'th ISO-week every year
     1995*d10    The 10'th absolute day in 1995
     1995*d99tue The last Tuesday in 1995
     0*w99su The Sunday of the last ISO-week every year

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

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

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

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

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

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

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

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

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

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

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

`[TEXT]'
     Argument is optional and TEXT is a valid alphanumeric character
     constant.

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

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

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

          A, B, AB, BA ...

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

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

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

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

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

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

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

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

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

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

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

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

DD
     means any day number (01...28, 29, 30, 31 or 99).

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

?
     means any single alphabetic character.

N
     means any number (one or more digits).

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

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

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

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

`00000000'
     `-cN+|-'

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

`0000MM00'
     `-cN+|-'

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

`YYYY0000'
     `-cN+|-'

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

`YYYYMM00'
     `-cN+|-'

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

`GCAL'
     Flags which are passed to Gcal automatically.

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

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

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

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

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

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

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

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

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

  Gcal produces the following *exit* codes:

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

`126'
     Invalid command line argument / option.

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

`124'
     Virtual memory exhausted.

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

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

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

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

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

`118'
     Resource file or include file not found.

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

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

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

`114'
     Invalid date variable operation.

`113'
     Referenced date variable undefined.

`112'
     Invalid date value assigned to date variable.

`111'
     Sending output to Email address fails.

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

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

`108'
     Illegal character found in response file.

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

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

`0'
     Normal program termination.

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

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

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

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