This is Info file en/gcal.info, produced by Makeinfo-1.64 from the
input file en/gcal.texi.

START-INFO-DIR-ENTRY
* Gcal: (gcal).              The GNU calendar program.
END-INFO-DIR-ENTRY

  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


File: gcal.info,  Node: %s macro text,  Next: %e macro text,  Prev: Special macro texts,  Up: Special macro texts

%s macro text
.............

  `%s[YYYY[MM[DD|WWWN]]]' references the "starting date" of the fixed
date, i.e. the first date the fixed date may occur.  If the date, which
is encoded in the `%s...' macro text, is later the current respectively
queried date, so the complete warning text will be suppressed.  If the
warning text must be shown, the text of this macro is always suppressed
in output.  This macro text *must* have a trailing *whitespace*
character, which is suppressed in output.

   * If YYYY... is not given (==*no* date encoded), the 01 January of
     current year is assumed for the date.

   * If YYYY is set to 0000, the current year is assumed for the year.

   * If MM is not given, then 01 (==January) is assumed for the month.

   * If MM is set to 00, the current month is assumed for the month.

   * If DD|WWW is not given, then 01 is assumed for the day.

   * If DD is set to 00, the current day is assumed for the day.

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


File: gcal.info,  Node: %e macro text,  Next: %o macro text,  Prev: %s macro text,  Up: Special macro texts

%e macro text
.............

  `%e[YYYY[MM[DD|WWWN]]]' references the "ending date" of the fixed
date, i.e. the last date the fixed date may occur.  If the date, which
is encoded in the `%e...' macro text, is earlier the current
respectively queried date, so the complete warning text will be
suppressed.  If the warning text must be shown, the text of this macro
is always suppressed in output.  This macro text *must* have a trailing
*whitespace* character, which is suppressed in output.

   * If YYYY... is not given (==*no* date encoded), the 31 December of
     current year is assumed for the date.

   * If YYYY is set to 0000, the current year is assumed for the year.

   * If MM is not given, then 12 (==December) is assumed for the month.

   * If MM is set to 00, the current month is assumed for the month.

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

   * If DD is set to 00, the current day is assumed for the day.

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


File: gcal.info,  Node: %o macro text,  Next: %k macro text,  Prev: %e macro text,  Up: Special macro texts

%o macro text
.............

  `%o[YYYY[MM[DD|WWWN]]]' references the "weekday name" and is
converted to a *weekday name text*, e.g.:

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

  If the warning text must be shown, the text of this macro is always
suppressed in output.  This macro text *must* have a trailing
*whitespace* character, which is suppressed in output.

   * If YYYY... ist not given (==*no* date encoded), the current date
     is assumed for the date.

   * If YYYY is set to 0000, the current year is assumed for the year.

   * If MM is not given or set to 00, the current month is assumed for
     the month.

   * If DD is not given or set to 00, the current day is assumed for
     the day.

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


File: gcal.info,  Node: %k macro text,  Next: %b macro text,  Prev: %o macro text,  Up: Special macro texts

%k macro text
.............

  `%k[YYYY[MM[DD|WWWN]]]' references the "week number" and is converted
to an ISO-*week number text*, e.g.:

     The text `Today is %o  of week %k' will be expanded to
     ==> `Today is Monday of week 24', in case the current date is the
     10th June 1996.

  If the warning text must be shown, the text of this macro is always
suppressed in output.  This macro text *must* have a trailing
*whitespace* character, which is suppressed in output.

   * If YYYY... ist not given (==*no* date encoded), the current date
     is assumed for the date.

   * If YYYY is set to 0000, the current year is assumed for the year.

   * If MM is not given or set to 00, the current month is assumed for
     the month.

   * If DD is not given or set to 00, the current day is assumed for
     the day.

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


File: gcal.info,  Node: %b macro text,  Next: %y macro text,  Prev: %k macro text,  Up: Special macro texts

%b macro text
.............

  `%b[YYYY[MM[DD|WWWN]]]' references a "year of birth" and is converted
to an *age value*, e.g.:

     The text `My %b1962  birthday%s1952 %e2062' will be expanded to
     ==> `My 32nd birthday', in case the current year is 1994.

  Those age values are evaluated/respected only, if the computation of
an age value is greater zero.  The fixed date warning in preceding
example is displayed only in case the current year is greater than 1952
and less than 2062.  If the warning text must be shown, the text of
this macro is always suppressed in output.  This macro text *must* have
a trailing *whitespace* character, which is suppressed in output.  If
the use of an ordinal suffix is encoded in the date format, which is
used to display dates, such computed age values also have a trailing
ordinal suffix automatically.  *Note `--date-format=de|us|gb|TEXT':
Calendar options, for more details.

   * If YYYY... ist not given (==*no* date encoded), the current date
     is assumed for the date.

   * If YYYY is set to 0000, the current year is assumed for the year.

   * If MM is not given or set to 00, the current month is assumed for
     the month.

   * If DD is not given or set to 00, the current day is assumed for
     the day.

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


File: gcal.info,  Node: %y macro text,  Next: %m macro text,  Prev: %b macro text,  Up: Special macro texts

%y macro text
.............

  `%y[YYYY[MM[DD|WWWN]]]' references any year and is converted to a
"year difference value", e.g.:

     The text `Sylvester 1912 is %y1912  years ago' will be expanded to
     ==> `Sylvester 1912 is -82 years ago', in case the current year is
     1994.

  If the warning text must be shown, the text of this macro is always
suppressed in output.  This macro text *must* have a trailing
*whitespace* character, which is suppressed in output.

   * If YYYY... is not given (==*no* date encoded), the current date is
     assumed for the date.

   * If YYYY is set to 0000, the current year is assumed for the year.

   * If MM is not given or set to 00, the current month is assumed for
     the month.

   * If DD is not given or set to 00, the current day is assumed for
     the day.

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


File: gcal.info,  Node: %m macro text,  Next: %w macro text,  Prev: %y macro text,  Up: Special macro texts

%m macro text
.............

  `%m' references the current respectively queried "month number"
relative to the actual (==todays) date.


File: gcal.info,  Node: %w macro text,  Next: %d macro text,  Prev: %m macro text,  Up: Special macro texts

%w macro text
.............

  `%w' references the current respectively queried "week number"
relative to the actual (==todays) date.


File: gcal.info,  Node: %d macro text,  Next: %j macro text,  Prev: %w macro text,  Up: Special macro texts

%d macro text
.............

  `%d' references the current respectively queried "day number"
relative to the actual (==todays) date, e.g.:

     A resource file line like `0 %d days gone' will be expanded to
     ==> `-10 days gone', in case you call Gcal with the `-c10-' option
     and no command.


File: gcal.info,  Node: %j macro text,  Next: %n macro text,  Prev: %d macro text,  Up: Special macro texts

%j macro text
.............

  `%j[[-]N]' references the current respectively queried "Julian Day
number" relative to the actual (==todays) date.  This day number is
tied with the date 1st January 4713 BCE, which is the starting day zero
of a consecutive day counting used in astronomical computations and is
known as the Julian Date (J.D.).  The real zero of this date is at 12
o'clock universal time; the day doesn't change at midnight, but at noon
universal time.  Actually, Gcal does not evalute the time zone, which
is returned by the systems date function.  For that reason, this day
number is represented without a time fraction on the supposition that
the day has already changed at noon.  If you don't like the feature
that the day has already changed at noon, you can decrease the
resulting Julian Day number of that macro text always by one, e.g.
`%j-1'.

  For example:

     The line `0 Julian Day %j since 01-Jan-4713 BCE' will be expanded
     to
     ==> `Julian Day 2437929 since 01-Jan-4713 BCE', in case you call
     Gcal with the `-c %19620921' option and no command.

  If the `%j' text is directly trailed by a number, this number is
always subtracted from the real Julian Day number (a negative sign can
be given to increase the readability of this expression), so you are
able to work with any reference values, e.g.:

     The line `0 Julian Day %j-2415021 since 01-Jan-1900' will be
     expanded to
     ==> `Julian Day 4 since 01-Jan-1900', in case you call Gcal with
     the `-c %19000105' option and no command.


File: gcal.info,  Node: %n macro text,  Next: %t macro text,  Prev: %j macro text,  Up: Special macro texts

%n macro text
.............

  `%n[[+|-]N]' references the current respectively queried "day number"
relative to the current date `+/-' N days and is converted to an
effective "date text", e.g.:

     A resource file line like `1962Sep21 10000 days old: %n+10000'
     will be expanded to
     ==> `10000 days old: 06-Feb-1990', in case you call Gcal with the
     simple `-c' option and the command `sep 1962' (*note `MM YYYY':
     Single commands.).


File: gcal.info,  Node: %t macro text,  Next: %1 macro text,  Prev: %n macro text,  Up: Special macro texts

%t macro text
.............

  `%t[12|24]' references the "actual system time", e.g.:

     The text `Time: %t --> Dentist at 10:00' will be expanded to
     ==> `Time: 07:32 --> Dentist at 10:00', in case the actual system
     time value is 07:32 (hh:mm).

  A system time value is always displayed in the *24-hour* format by
default.  For displaying in the *12-hour* format, add `12' behind `%t',
e.g. `%t12'.


File: gcal.info,  Node: %1 macro text,  Next: %2 macro text,  Prev: %t macro text,  Up: Special macro texts

%1 macro text
.............

  `%1' is replaced by the starting highlighting sequence respectively
the starting marking character, which is used for highlighting the
actual day, (*note `--highlighting=TEXT': Global options.).  This
attains that all succeeding text of the line after this macro text is
displayed in the same way as the highlighted respectively marked actual
day.  `%1' is used together with the `%2' macro text, which turns off
this enabled highlighting sequence respectively produces the ending
marking character.  If a `%1' text is not succeeded by a `%2' text on
the line, Gcal automatically inserts such a `%2' text at the end of the
line.

  For example:

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


File: gcal.info,  Node: %2 macro text,  Next: %3 macro text,  Prev: %1 macro text,  Up: Special macro texts

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


File: gcal.info,  Node: %3 macro text,  Next: %4 macro text,  Prev: %2 macro text,  Up: Special macro texts

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

  `%3' is replaced by the starting highlighting sequence respectively
the starting marking character, which is used for highlighting a
holiday, (*note `--highlighting=TEXT': Global options.).  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.


File: gcal.info,  Node: %4 macro text,  Prev: %3 macro text,  Up: Special macro texts

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


File: gcal.info,  Node: Date variables,  Next: Text variables,  Prev: Special macro texts,  Up: Resource file

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

  Gcal respects *global* and/or *local* date variables (*note
`--date-variable=ARGUMENT': Date warning options.), which may be used
either in the date part of a Gcal resource file line or which may be
part of a special macro text in the text part of a Gcal resource file
line.  This means up to *25* user defined date variables can be set and
referenced during program execution.  A date variable name DVAR
consists of a single letter (case-insensitive and except the letter
`e', which is internally reserved for the Easter Sunday's date and
unassignable/inoperatable therefore) and is trailed in a definition by
the assignment operator character `=' and the numerical values of month
MM (or a short, three characters month name, e.g. `Jan', `Feb'...) and
day DD this variable has to store (or another date variable name), e.g.:

     a=1127
     c=a

stores the 27th November to the local date variable A and to the local
date variable C.  You should always remember that date variables can
only be referenced in a line if they are already defined, because Gcal
processes a resource file line by line.

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

     a=03su2
     b=JunMon9
     c=b-3
     d=c+4Sa
     x=*d10
     y=*d10fri
     z=*w3Su

which means, date variable A stores the date of second Sunday in March
and B stores date of last Monday in June.  The date variable C stores
the date, which is three days before the date of the last Monday in
June and this date is set in the date variable D to that date, which is
four Saturdays after the date of C.  The date variable X stores the
date of the 10th absolute day of the year (== 10th January).  Y stores
the date of the 10th Friday of the year, and the assignment to Z is the
date of the Sunday, which occurs in the 3rd week of the year.

*Caution:*
These kinds of assignments to date variables are *only* computed
correctly in simple year bounds, which means during a current year, 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 `GCAL' 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 (*note `--debug=internal': Global options.).  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 *Note `--debug=abort': Global options.

  A local date variable can be deleted, which means, that this date
variable is no longer valid in its local scope and be undefined
therefore.  So it is possible to use its potentially defined global
value in succeeding lines if this date variable is referenced there.
The following example of the resource file `dvar.rc' elucidates these
facts:

     z=0202
     0@z The local assigned date to `z'
     z=
     0@z The global assigned date to `z'
     z=0404
     0@z The local assigned date to `z'

So Gcal creates the following output:

     $ gcal %1777 -H no -x -v z=1212 -f ./dvar.rc -y
     -|
     -| Sun, Feb   2nd 1777: The local assigned date to `z'
     -| Fri, Apr   4th 1777: The local assigned date to `z'
     -| Fri, Dec  12th 1777: The global assigned date to `z'
     $ gcal %1777 -H no -x -f ./dvar.rc -y
     -|
     -| Sun, Feb   2nd 1777: The local assigned date to `z'
     -| Fri, Apr   4th 1777: The local assigned date to `z'

  Only advanced users should apply the `--export-date-variables'
option, which 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.  *Note Include directives::, for more
details.

  But be aware, the use of this option could create unwanted results,
because the order of processing the resource files is an important
entity in managing the `--export-date-variables' option, so it's not
recommended using it.  You, the user, must 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.

`DVAR+=NWWW'
     Addition of N weekdays WWW.

`DVAR-=NWWW'
     Subtraction of N weekdays WWW.

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

  If operations on a global date variable are performed in a resource
file or that file which is included by it, these operations are only
valid in that specific file (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 finally, that each date variable assignment/operation
must be given separately on a single line in the resource file.


File: gcal.info,  Node: Text variables,  Prev: Date variables,  Up: Resource file

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

  Gcal respects *global* and/or *local* text variables (*note
`--text-variable=ARGUMENT': Date warning options.), which may be used
anywhere in a line of a Gcal resource file.  This means up to *26* user
defined text variables can be set and referenced during program
execution.  A text variable name TVAR consists of the `$' prefix and a
single letter (case-insensitive), and is trailed in a definition by the
assignment operator character `=' and the text this variable has to
store.  Only local text variables are set to an undefined value in case
no text is specified on the right of the assignment operator character.
You should always remember that text variables can only be referenced
in a line if they are already defined, because Gcal processes a
resource file line by line.  Gcal always expands text variable
references recursively until all sub-references to other text variables
are resolved.

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

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

  Here are some examples showing how Gcal processes text variables.
Let's assume a resource file by the name of `demo.rc' exists with the
following contents:

     $a=foo
     0 \$a:1=$a
     $c=$a
     0 \$c=$c
     $b=$c bar $a
     0 \$b=$b
     $a=bar $b baz $a booz
     0 \$a:2=$a
     $a=
     $b=0 $b $c frozz $a frozz
     $b --> That's \$b
     0 \$x='$x' and \$d is undefined: $d...
     $a= 0 ~ 1~2~\$3~%n~$c~now it's enough!
     0 \$a=---$a---
     $a=0 \   \ \\ And this...
     $a works too!

So Gcal creates the following output:

     $ gcal %19960101 -H no -x -r '$A=FROBOZZ:$x=' -f ./demo.rc
     -|
     -| Mon, Jan   1st 1996: $a:1=foo
     -| Mon, Jan   1st 1996: $a:2=bar foo bar foo baz foo booz
     -| Mon, Jan   1st 1996: $a=--- 0
     -|                       1
     -|                      2
     -|                      $3
     -|                      01-Jan-1996
     -|                      foo
     -|                      now it's enough!---
     -| Mon, Jan   1st 1996: $b=foo bar foo
     -| Mon, Jan   1st 1996: $c=foo
     -| Mon, Jan   1st 1996:    \ \\  And this... works too!
     -| Mon, Jan   1st 1996: $x='' and $d is undefined: $d...
     -| Mon, Jan   1st 1996: foo bar foo foo frozz FROBOZZ frozz --> That's $b

Or a resource file by the name of `demo2.rc' exists with the following
contents:

     $a=$b foo
     $b=0@e
     $a bar
     $b \$b
     0 \$a:$a
     0 \$b:$b

So Gcal creates the following output:

     $ gcal %19960101 -H no -x -f ./demo2.rc
     -|
     -| Mon, Jan   1st 1996: $a:0@e foo
     -| Mon, Jan   1st 1996: $b:0@e
     $ gcal %19960101 -H no -x -f ./demo2.rc -y
     -|
     -| Sun, Apr   7th 1996: $b
     -| Sun, Apr   7th 1996: foo bar

  As seen before, it's allowed to store complete (or partitial) date
parts (*note Date part of a line::.), likewise special macro texts
(*note Special macro texts::.) into text variables or references to
other text variables, which are processed by Gcal after their expansion.

  Text variables which are defined in a resource file are always local
and only respected in this specific file and that file, which is
included by it.  This means for the included file that *all* local
variables of the caller are visible.  The included file itself may
define its own local variables in its own name-space, which are not
exported to caller on return.  All other definitions of text variables
(in command line, environment variable `GCAL' or response file) are
always global.  If a resource file line contains a reference of a text
variable, which is not locally defined in that file, Gcal will try to
use the global values held by this variable.  If this fails because no
global definition of this text variable is given, Gcal keeps the name
of this text variable untouched in this line.

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

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

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

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

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


File: gcal.info,  Node: Resource file examples,  Prev: Resource file,  Up: Fixed date warnings

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

  Here are some examples of problem oriented resource files, which
might be useful to get a deeper impression about the attributes of
Gcal's fixed date warning feature.

Let's begin with a common example:

     ; This is general example of a resource file.
     ;
     19940715 Time: %t --> Dentist at 10:00
     00000921 My %b1962 birthday%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 10th ISO-week every year
     0@a   The Friday of the 10th ISO-week every year
     0@a1  The Saturday of the 10th ISO-week every year
     1995*d10    The 10th absolute day in 1995
     1995*d99tue The last Tuesday in 1995
     0*w99su The Sunday of the last ISO-week every year
     ;
     ; The next entry is respected by ALL
     ;   fixed date warning period modifiers.
     ;
     1994*d1sun#99SUN.7 Each Sunday in 1994
     ;
     ; Day of Prayer & Repentance is Wednesday before the Sunday,
     ;   which is before the 1st Advent's Sunday.
     ;
     a=1225
     a=a-5sun
     0@a-4 Day of Prayer & Repentance

And here is a resource file by the name of `demo3.rc' used to detect
all Fridays the 13th of a year:

     $a=Friday the 13th%s0000
     $b= %e0000
     $c=fri2
     $d=fri3
     00000113 $a01$c$b01$c
     00000113 $a01$d$b0$1d
     00000213 $a02$c$b02$c
     00000213 $a02$d$b02$d
     00000313 $a03$c$b03$c
     00000313 $a03$d$b03$d
     00000413 $a04$c$b04$c
     00000413 $a04$d$b04$d
     00000513 $a05$c$b05$c
     00000513 $a05$d$b05$d
     00000613 $a06$c$b06$c
     00000613 $a06$d$b06$d
     00000713 $a07$c$b07$c
     00000713 $a07$d$b07$d
     00000813 $a08$c$b08$c
     00000813 $a08$d$b08$d
     00000913 $a09$c$b09$c
     00000913 $a09$d$b09$d
     00001013 $a10$c$b10$c
     00001013 $a10$d$b10$d
     00001113 $a11$c$b11$c
     00001113 $a11$d$b11$d
     00001213 $a12$c$b12$c
     00001213 $a12$d$b12$d

The result for the years 1996...2002 is as follows:

     $ gcal -H no -u -x -f ./demo3.rc 1996+2002
     -|
     -| Fri, Sep  13th 1996: Friday the 13th
     -| Fri, Dec  13th 1996: Friday the 13th
     -|
     -| Fri, Jun  13th 1997: Friday the 13th
     -|
     -| Fri, Feb  13th 1998: Friday the 13th
     -| Fri, Mar  13th 1998: Friday the 13th
     -| Fri, Nov  13th 1998: Friday the 13th
     -|
     -| Fri, Aug  13th 1999: Friday the 13th
     -|
     -| Fri, Oct  13th 2000: Friday the 13th
     -|
     -| Fri, Apr  13th 2001: Friday the 13th
     -| Fri, Jul  13th 2001: Friday the 13th
     -|
     -| Fri, Sep  13th 2002: Friday the 13th
     -| Fri, Dec  13th 2002: Friday the 13th

Or a bit shorter version of the resource file `demo3.rc' by the name of
`demo4.rc' likewise used to detect all Fridays the 13th of a year:

     $a=%n+12 is a Friday%s0000
     $b=1 %e0000
     $c=sun1
     00000101 $a01$c$b01$c
     00000201 $a02$c$b02$c
     00000301 $a03$c$b03$c
     00000401 $a04$c$b04$c
     00000501 $a05$c$b05$c
     00000601 $a06$c$b06$c
     00000701 $a07$c$b07$c
     00000801 $a08$c$b08$c
     00000901 $a09$c$b09$c
     00001001 $a10$c$b10$c
     00001101 $a11$c$b11$c
     00001201 $a12$c$b12$c

The result for the years 1996...2002 is as follows:

     $ gcal -H no -u -x -f ./demo4.rc 1996+2002
     -|
     -| Sun, Sep   1st 1996: 13-Sep-1996 is a Friday
     -| Sun, Dec   1st 1996: 13-Dec-1996 is a Friday
     -|
     -| Sun, Jun   1st 1997: 13-Jun-1997 is a Friday
     -|
     -| Sun, Feb   1st 1998: 13-Feb-1998 is a Friday
     -| Sun, Mar   1st 1998: 13-Mar-1998 is a Friday
     -| Sun, Nov   1st 1998: 13-Nov-1998 is a Friday
     -|
     -| Sun, Aug   1st 1999: 13-Aug-1999 is a Friday
     -|
     -| Sun, Oct   1st 2000: 13-Oct-2000 is a Friday
     -|
     -| Sun, Apr   1st 2001: 13-Apr-2001 is a Friday
     -| Sun, Jul   1st 2001: 13-Jul-2001 is a Friday
     -|
     -| Sun, Sep   1st 2002: 13-Sep-2002 is a Friday
     -| Sun, Dec   1st 2002: 13-Dec-2002 is a Friday

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

     $a=Working-day
     $c=%e0000$b99
     a=$bmon1
     0@a#+4 $a
     a=$btue1
     0@a#+3 $a
     a=$bwed1
     0@a#+2 $a
     a=$bthu1
     0@a#+1 $a
     a=$bfri1
     0@a $a
     a=$bmon2
     0@a#+4 $a
     a=$bmon3
     0@a#+4 $a
     a=$bmon4
     0@a#+4 $a$c
     a=$bmon9
     0@a#+4 $a$c

Respectively a bit shorter version of the resource file `demo5.rc':

     $a=Working-day
     $c=%e0000$b99
     0000$bmon1:5 $a
     0000$btue1:4 $a
     0000$bwed1:3 $a
     0000$bthu1:2 $a
     0000$bfri1:1 $a
     0000$bmon2:5 $a
     0000$bmon3:5 $a
     0000$bmon4:5 $a$c
     0000$bmon9:5 $a$c

And a resource file by the name of `include.rc' exists, which is only
used to include one given resource file:

     #include "$f"

Then the result for the month February 1996 is as follows:

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

And finally a resource file by the name of `swtime.rc', which results
fixed date warnings for the change of daylight-saving time valid since
1980 for the Federal Republic of Germany (two days before adaptation
till two days after adaptation).

     ;
     ; `swtime.rc'; daylight-saving time BRD
     ;
     $a=daylight-saving time starts Sunday
     ;
     a=03sun9
     0@a-2#+2 Summer $a~+1 hrs. (02:00 --> 03:00 h.)%s1980
     ;
     a=09sun9
     0@a-2#+2 Winter $a~-1 hrs. (03:00 --> 02:00 h.)%s1980 %e1995
     ;
     a=10sun9
     0@a-2#+2 Winter $a~-1 hrs. (03:00 --> 02:00 h.)%s1996


File: gcal.info,  Node: Todays calendar,  Next: Gcal Utilities,  Prev: Fixed date warnings,  Up: Top

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 23rd day in February a leap day was layed in, so the 24th February
occurred twice.  The use of the leap year was an improvement but not
entirely accurate.

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

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

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

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

  Up to now, China was the last country to change over its chronology,
conforming with the Gregorian calendar in 1949.  The era of a world
wide uniform calendar is already part of history today.  The Iran
returned to the traditional Mohammedian moon calendar in 1979 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.


File: gcal.info,  Node: Gcal Utilities,  Next: Internationalization,  Prev: Todays calendar,  Up: Top

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

* Menu:

* Invoking tcal::      How to run `tcal' and a summary of its options.
* Invoking txt2gcal::  How to run `txt2gcal' and a summary of its options.

  Two small utility programs are part of the Gcal 2.10 package.  The
`tcal' program runs the Gcal program with the date set one day ahead.
And the `txt2gcal' program creates a verbatim Gcal resource file from a
text file.


File: gcal.info,  Node: Invoking tcal,  Next: Invoking txt2gcal,  Prev: Gcal Utilities,  Up: Gcal Utilities

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

  The `tcal' program runs `gcal' with the date of tomorrows day
(equivalent the `--shift=1' option).  Its arguments are as follows:

     tcal [--help | --version] | [--shift=[+|-]NUMBER] [ARGUMENT...]

  All given ARGUMENTS are passed unmodified to the Gcal program.  If
the Gcal program shall be called with another date than tomorrows date,
this desired date can be selected by using the `--shift=[+|-]NUMBER'
option, in which `[+|-]NUMBER' is the distance of days, the desired
date is distant from the actual date.  The `--shift' option must be
given before all other ARGUMENTS, which are passed to the Gcal program.

  In case a `GCALPROG' environment variable (*note GCALPROG:
Environment variables.) is defined and set with the file name of the
executable Gcal program, `tcal' will use this file name for calling
Gcal.  Otherwise, the file name `gcal', which is burned-in during the
compilation step of `tcal', is used for calling the Gcal program.  An
exit status of 0 means all processing is successfully done, and any
other value means an error has occured.

  The program accepts the following options:

`--help'
     Print a usage message listing all available options, then exit
     successfully.

`--version'
     Print the version number, then exit successfully.

`--shift=[+|-]NUMBER'
     Define the displacement in `[+|-]NUMBER' days the desired date is
     distant from the actual date.


File: gcal.info,  Node: Invoking txt2gcal,  Prev: Invoking tcal,  Up: Gcal Utilities

Invoking `txt2gcal'
===================

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

     txt2gcal [--help | --version] | [TEXT-FILE|-] [DATE-PART]

  If no TEXT-FILE or `-' argument is given, the program reads and
processes all input received from the standard input channel. If no
DATE-PART argument is given, `txt2gcal' creates a `0' for the date
part.  All results are always shown on the standard output channel.  An
exit status of 0 means all processing is successfully done, and any
other value means an error has occured.

  The program accepts the following options:

`--help'
     Print a usage message listing all available options, then exit
     successfully.

`--version'
     Print the version number, then exit successfully.

  Here comes an example how to use `txt2gcal'.  Let's suppose there is a
text file by the name of `demo' with the following contents:

             Hi friends,
     
     I'm the demo text containing funny characters and character
     sequences like ~~ \~ % %% $a $1 %%%\
     %\ %s %%foo %bar \%baz \\~ \~\ and so on...
     I'm be anxious how I'll be transformed by `txt2gcal'.

and `txt2gcal' processes this file, redirecting the output to `demo.rc':

     $ txt2gcal demo 0*d1#999 > demo.rc
     => 0*d1#999 \        Hi friends,~\
     => ~\
     => I'm the demo text containing funny characters and character~\
     => sequences like \~\~ \\~ % %% \$a $1 %%%\ ~\
     => %\ \%s %%foo \%bar \\%baz \\\~ \\~\ and so on...~\
     => I'm be anxious how I'll be transformed by `txt2gcal'.

then `txt2gcal' has now created a new Gcal resource file `demo.rc' from
the text file `demo'.  Let's finally see how Gcal will interpret this
new resource file:

     $ gcal -H no -Ax -f ./demo.rc
     -|
     -| Thu, May   2nd 1996:
     -|         Hi friends,
     -|
     -| I'm the demo text containing funny characters and character
     -| sequences like ~~ \~ % %% $a $1 %%%\
     -| %\ %s %%foo %bar \%baz \\~ \~\ and so on...
     -| I'm be anxious how I'll be transformed by `txt2gcal'.


File: gcal.info,  Node: Internationalization,  Next: Meta Symbols,  Prev: Gcal Utilities,  Up: Top

Aspects in Internationalization
*******************************

  Starting with version 2.00, Gcal is able to display message texts
using any native languages instead of using the English language only,
because parts of the GNU `gettext' package are integrated into the
Software.  *Note Introduction: (gettext)Top, for more details.

  By default, Gcal displays all message texts using the English native
language in case no other native language is wanted.  A so-called
*message catalog* is read by Gcal at run-time if message texts from
another native language are required.  Gcal 2.10 supports the following
native languages:

     English (en)
     German (de)

  It is only necessary to set one of the environment variables (which
are listed here with decreasing priority)

  1. `LANGUAGE' (*note LANGUAGE: Environment variables.)

  2. `LC_ALL' (*note LC_ALL: Environment variables.)

  3. `LC_MESSAGES' (*note LC_MESSAGES: Environment variables.)

  4. `LANG' (*note LANG: Environment variables.)

with a language code to select another native language instead of the
English native language.

  Normally, users only have to set the `LANG' environment variable to
tell Gcal the native language to use at run-time.  Presuming users want
to run Gcal using the German native language for displaying message
texts, they merely have to execute `setenv LANG de' (in `csh') or
`export LANG; LANG=de' (in `sh') at the shell prompt.  Of course they
could even do this from their `.login' or `.profile' file.  *Note The
User's View: (gettext)Users, for more details.

  As shown above, a simple setting of `de' in the environment variable
`LANG' is sufficient to enable German message texts.  `de' is the
two-letter language code for the German language, which is defined in
the ISO-639:1988 and is called "simple language code information" in
the further context.  Other language codes can be taken from this
ISO-document (e.g. `fr' for French, `es' for Spanish etc.).

  Because Gcal as calendar program must also comply the specifics of a
used native language concerning the ordering of day, month and year
(and further things) of a displayed date, the period of Gregorian
Reformation and the representation of calendar sheets, these criterias
are likewise bound to the language code (strictly speaking, an extended
language code information).

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

   * U.S. American date format

   * Gregorian Reformation have occured 1752

   * Week starts on Sunday

   * Representation of calendar sheet

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

And a `de' language code (or other language codes, for which a *message
catalog* will be created and distributed in future) effects the
following internal defaults:

   * German date format

   * Gregorian Reformation have occured 1582

   * Week starts on Monday

   * Representation of calendar sheet

          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

  Remember, all these internal defaults are modifiable by the according
options (`--date-format', `--gregorian-reform', `--starting-day' and
`--type').

  If no language code is detected, Gcal takes the internal defaults of
the `en' language code (or to be more precise, of the extended language
code information `en_us').

  If a language code is specified for which no *message catalog* is
installed, Gcal takes the internal defaults of the `de' language code,
but displays the message texts using the English native language.
Actually, this behavior seems to me the most proper solution in such a
case.  The English native language is speaken all over the world unlike
the German or other native languages, so it is wise to use it here.
But the other criterias bound to the English native language are so
special for users of other native languages that it is wise to use the
criterias taken for internal defaults of the `de' language code,
because most european countries (taken as standard) use them.

  Now British users will certainly ask whether they could use their
date format as an internal default (all other internal defaults of the
simple `en' language code information meet their criterias).  The
answer to this is a simple `yes', nevertheless these users have to set
the environment variable `LANG' with an "extended language code
information" instead of a simple language code information.  The usual
template of an extended language code information is as follows:

   * For XPG syntax (X/Open Portability Guide):
          LANGUAGE[_TERRITORY][.CODESET][@MODIFIER]

   * For CEN syntax (Comite Europen de Normalisation):
          LANGUAGE[_TERRITORY][+AUDIENCE][+SPECIAL][,SPONSOR][_REVISION]

  Both syntax's contain the LANGUAGE and TERRITORY components, which
are used by Gcal to select the native language and the other criterias.
The LANGUAGE component is equivalent to the simple language code
information and the TERRITORY component is a two-letter territory code
as defined by the ISO-3166 like `gb' for Great Britain or `us' for the
U.S.A.  See the pertinent literature for more details.  So British
users only have to set the `LANG' environment variable with a `en_gb'
contents, after that they can use the British date format as an internal
default.


File: gcal.info,  Node: Meta Symbols,  Next: Coding scheme,  Prev: Internationalization,  Up: Top

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

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

`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 string of text.

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

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

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

          A, B, AB, BA ...

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

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

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

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

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

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

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


File: gcal.info,  Node: Coding scheme,  Next: Environment variables,  Prev: Meta Symbols,  Up: Top

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

* Menu:

* Coding scheme table 1::
* Coding scheme table 2::

  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=ARGUMENT'
may have, i.e. they point out all possible correspondences.  This is
necessary because Gcal does not respect all entries found in a resource
file if a *fixed date warning* argument is given, it respects only
those entries which have a definite relation to the *fixed date
warning* argument to avoid the output of redundant information!

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

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

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

DD
     represents any day number (1...28, 29, 30, 31 or 99).

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

?
     represents any case-insensitive single letter.

N
     represents any positive integer number (one or more digits).

