\input texinfo  @c -*-texinfo-*-


@c  $Id: gcal.texi v2.05 1996/07/16 02:00:05 tom Exp $
@c
@c  gcal.texi:  English Texinfo source of info/dvi file
@c
@c  Copyright (C) 1994, 1995, 1996 Thomas Esken
@c
@c
@c  Permission is granted to make and distribute verbatim copies of
@c  this manual provided the copyright notice and this permission notice
@c  are preserved on all copies.
@c
@c  Permission is granted to copy and distribute modified versions of this
@c  manual under the conditions for verbatim copying, provided that the entire
@c  resulting derived work is distributed under the terms of a permission
@c  notice identical to this one.
@c
@c  Permission is granted to copy and distribute translations of this manual
@c  into another language, under the above conditions for modified versions,
@c  except that this permission notice may be stated in a translation approved
@c  by the Free Software Foundation.
@c
@c
@c                                  \\\_''/'
@c  -------------------------oOO    (/o-o\)    OOo-------------------------
@c  Thomas Esken                o  (.  "  .)  o   Internet :
@c  Im Hagenfeld 84              \___) ~ (___/      (esken@uni-muenster.de)
@c  D-48147 M"unster; GERMANY                     Phone    : +49 251 232585



@c %**Start of header part
@c
@setfilename gcal.info
@c
@c Some necessary constant definitions
@c
@set EDITION 2.05
@set UPDATE-DATE 16 July 1996
@set UPDATE-MONTH July 1996
@set GCAL-VERSION 2.10
@c
@c All actual supported native languages
@c
@set SLANG @r{English (}en@r{)}@*@r{German (}de@r{)}
@c
@c Maximum length of a resource file line
@c
@set GCAL-RCL INT_MAX
@c
@settitle Gcal @value{GCAL-VERSION}
@c @footnotestyle separate
@paragraphindent 2
@c @smallbook
@c
@c %**End of header part



@c %**Start of global definition part
@c
@c Index of command line arguments
@c
@defcodeindex ar
@c
@c %**End of global definition part



@c Set smallbook if printing in smallbook format so the example of the
@c smallbook font is actually written using smallbook; in bigbook, a
@c kludge is used for TeX output.
@c
@c @set smallbook
@c @clear smallbook

@c Experiment with smaller amounts of whitespace between chapters
@c and sections.
@c
@tex
\global\chapheadingskip = 15pt plus 4pt minus 2pt
\global\secheadingskip = 12pt plus 3pt minus 2pt
\global\subsecheadingskip = 9pt plus 2pt minus 2pt
@end tex

@c Experiment with smaller amounts of whitespace between paragraphs in
@c the 8.5 by 11 inch format.
@c
@ifclear smallbook
@tex
\global\parskip 6pt plus 1pt
@end tex
@end ifclear



@c %**Start of info dir entry
@c
@ifinfo
@format
START-INFO-DIR-ENTRY
* Gcal: (gcal).              The GNU calendar program.
END-INFO-DIR-ENTRY
@end format
@end ifinfo
@c
@c %**End of info dir entry



@finalout



@ifinfo
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.

@ignore
Permission is granted to process this file through TeX and print the
results, provided the printed document carries copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).

@end ignore
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!

@format
                                \\\_''/'
-------------------------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
@end format
@end ifinfo



@c %**Start of titlepage part
@c
@setchapternewpage odd
@titlepage
@title Gcal
@subtitle An Extended Calendar Program
@subtitle Edition @value{EDITION}
@subtitle @value{UPDATE-MONTH}
@author by Thomas Esken
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1994, 1995, 1996 Thomas Esken

@sp 2

@cartouche
@quotation
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!

@sp 2

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

@sp 2

This is Edition @value{EDITION} of @cite{Gcal, an Extended Calendar Program},@*
for the @value{GCAL-VERSION} (or later) version of the GNU implementation@*
of @code{cal} and @code{calendar}.
@sp 2

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.
@end titlepage
@c
@c %**End of titlepage part



@c %**Start of master menu part
@c
@headings on
@ifinfo
@node Top, Gcal Introduction, (dir), (dir)
@top 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 @value{EDITION} of the Gcal documentation,
@w{@value{UPDATE-DATE},} for Gcal @value{GCAL-VERSION}.

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!

@format
                                \\\_''/'
-------------------------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
@end format

@menu
* Gcal Introduction::    Gcal in brief.
* Invoking Gcal::        How to run the @code{gcal} program.
* Eternal holidays::     How to create an Eternal holiday list.
* Fixed date warnings::  How to create a Fixed date warning list.

Appendices

* Todays calendar::        Genesis of the Gregorian calendar.
* Gcal Utilities::         Utility programs which are part of the distribution.
* Internationalization::   Aspects of Internationalization been made.
* Meta Symbols::           Meta Symbols used in this document.
* Coding scheme::          Coding scheme of date part in resource file.
* Environment variables::  Respected Environment variables.
* Error codes::            Which Error codes does Gcal return?

Indices

* Argument Index::  Index of Command line arguments.
* Variable Index::  Index of Environment variables.
* Concept Index::   Concept Index.

  --- The Detailed Node Listing ---

Invoking Gcal

* Command line arguments::         Command line arguments.
* The GCAL environment variable::  How to use the @code{GCAL} environment variable.

Command line arguments

* Options::               How to use Options.
* Response file::         How to use a @samp{@@@var{file}} Response file.
* Actual date modifier::  How to use a @samp{%@var{date}} Actual date modifier.
* Commands::              How to use Commands.

Options

* Common options::        How to use Common options.
* Global options::        How to use Global options.
* Calendar options::      How to use Calendar options.
* Date warning options::  How to use Date warning options.

Commands

* Single commands::        How to use a Single command.
* 3-Month mode commands::  How to use a 3-Month mode command.
* Lists of commands::      How to use a List of commands.
* Ranges of commands::     How to use a Range of commands.

Fixed date warnings

* Resource file::           How to use a Resource file.
* Resource file examples::  Examples of Resource file entries.

Resource file

* Structure of resource file::    How to write a Resource file.
* Date part of a line::           How to write the Date part.
* Further date part attributes::  What are Further date part attributes?
* Text part of a line::           How to write the Text part.
* Comment line::                  What is a Comment line?
* Include directives::            What are Include directives.
* Special macro texts::           What is a Special macro text.
* Date variables::                How Date variables can be used.
* Text variables::                How Text variables can be used.

Further date part attributes

* Lists of days::              How Lists of days can be used.
* Ranges of days::             How Ranges of days can be used.
* Repetition factor of days::  How to use such a factor.
* Appearance factor of days::  How to use such a factor.

Special macro texts

* %s macro text::  How to use the Start of event macro text.
* %e macro text::  How to use the End of event macro text.
* %o macro text::  How to use the Weekday name macro text.
* %k macro text::  How to use the Week number macro text.
* %b macro text::  How to use the Birthday macro text.
* %y macro text::  How to use the Year number macro text.
* %m macro text::  How to use the Month number macro text.
* %w macro text::  How to use the Week number macro text.
* %d macro text::  How to use the Day number macro text.
* %j macro text::  How to use the Julian Day number macro text.
* %n macro text::  How to use the Textual date macro text.
* %t macro text::  How to use the Actual time macro text.
* %1 macro text::  How to use the Start of highlighting sequence 1 macro text.
* %2 macro text::  How to use the End of highlighting sequence 1 macro text.
* %3 macro text::  How to use the Start of highlighting sequence 2 macro text.
* %4 macro text::  How to use the End of highlighting sequence 2 macro text.

Gcal Utilities

* Invoking tcal::      How to run @code{tcal} and a summary of its options.
* Invoking txt2gcal::  How to run @code{txt2gcal} and a summary of its options.

Coding scheme

* Coding scheme table 1::
* Coding scheme table 2::
@end menu
@end ifinfo
@c
@c %**End of master menu part



@c %**Start of manual part
@c
@node Gcal Introduction, Invoking Gcal, Top, Top
@chapter Gcal Introduction
@cindex 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.@: @samp{Fixed date on 1st December 1995}, rather than fixed dates
occuring periodically again and again.  So it's possible to define repeated
events like @samp{This fixed date occurs all days in May 1995} or @samp{Every
15th November in any years}.  These fixed date definitions are stored in
resource files and whenever Gcal is started, an option to evaluate
the necessary resource files can be given.

Once the user has set his/her preferred command line arguments for querying
the fixed dates data base, it is possible to store them in a response file or
shell script file.  A response file contains all arguments delivered to Gcal,
but unlike a shell script file, such a response file isn't executable; it is
only a pool of command line 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.

@node Invoking Gcal, Eternal holidays, Gcal Introduction, Top
@chapter Invoking Gcal
@cindex Invoking Gcal
@cindex Shell
@cindex Command line interpreter

@menu
* Command line arguments::         Command line arguments.
* The GCAL environment variable::  How to use the @code{GCAL} Environment variable.
@end menu

Gcal is a command line oriented program.  It is usually called from a
@dfn{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:
@sp 2

@example
@center gcal @r{[ [}@var{option}@dots{}@r{] [}%@var{date}@r{] [}@@@var{file}@dots{}@r{] ]  [}@var{command}@r{]}
@end example

@sp 2

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.@: @samp{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 @strong{first} argument
denotes the month and the @strong{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 3rd of September, see @ref{Todays calendar}, and
@ref{Internationalization} for more details.

@page
@node Command line arguments, The GCAL environment variable, Invoking Gcal, Invoking Gcal
@section Command line arguments
@cindex Command line arguments
@cindex Arguments of command line
@cindex Options
@cindex @samp{%@var{date}}, Option
@cindex Option @samp{%@var{date}}
@cindex @samp{@@@var{file}}, Option
@cindex Option @samp{@@@var{file}}
@cindex Commands

@menu
* Options::               How to use Options.
* Response file::         How to use a @samp{@@@var{file}} Response file.
* Actual date modifier::  How to use a @samp{%@var{date}} Actual date modifier.
* Commands::              How to use Commands.
@end menu

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 @dfn{options} which control how Gcal behaves.  Other types
of arguments are the @samp{%@var{date}} and the @samp{@@@var{file}} options.
The @samp{%@var{date}} option sets the period Gcal shall work on to any
starting date; the @samp{@@@var{file}} option preloads options and commands
from a response file.  The most important arguments are the @dfn{commands}
which control the periods Gcal respects.

@cindex Switch character, @samp{-}
@cindex @samp{-} switch character
@cindex Switch character, @samp{/}
@cindex @samp{/} switch character
@cindex Switch character, @samp{--}
@cindex @samp{--} switch character
An option is defined by a leading @dfn{switch} character; either the @samp{-}
(dash) or the @samp{/} (slash) character for traditional short-style options,
or @samp{--} for mnemonic long-style options; a command may not have a leading
switch character!  Options (inclusive @samp{%@var{date}} and
@samp{@@@var{file}}) @strong{must} be given before commands!

@cindex Quotation of special characters
@cindex Shell
Depending on operating system and used shell, some of the arguments and texts
given in command line must be quoted by @samp{"} or @samp{'} characters
respectively protected by a @samp{\} character to avoid expansion by the shell.

@sp 2

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

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

@page
@node Options, Response file, Command line arguments, Command line arguments
@subsection Options
@cindex Options
@cindex Command line options

@menu
* Common options::        How to use Common options.
* Global options::        How to use Global options.
* Calendar options::      How to use Calendar options.
* Date warning options::  How to use Date warning options.
@end menu

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

@cindex Options, short-style
@cindex Short-style options
@cindex Options, long-style
@cindex Long-style options
@cindex GNU style options
@cindex Single character options
@cindex Single command line word
Gcal supports both short-style options and GNU long-style options. Traditional
short-style options are indicated by a single switch character and trailed
by the option character itself and perhaps a modifier or an argument.  The
most single character options (unless they take an argument) can be composed
into a single command line word: @samp{-Ax} is equivalent to @samp{-A -x}.
GNU long-style options are indicated with @samp{--} 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 @samp{=}.

Brackets ([ and ]) indicate that an option takes an optional argument.  The
@samp{|} character is used to separate several selectable arguments from each
other.

@noindent
Gcal processes the GNU long-style options in a special, non-standard way.
There are five different types of long-style options:

@enumerate
@item
@samp{--foo}@*
Enables option @samp{--foo}.

@item
@samp{--foo=@var{bar}}@*
Enables option @samp{--foo} with required argument @var{bar}.

@item
@samp{--foo@r{[}=@var{bar}@r{[|}@dots{}@r{|}@var{bar}@r{]]}}@*
Option @samp{--foo} may have one @var{bar} argument.  If no argument list is
given, any argument can be given to this option.  If an argument list is
given, exactly one @var{bar} argument may be selected from given list.  If
there is no argument choosen in this case, the first @var{bar} argument of
the argument list is pre-selected by default.

@item
@samp{--foo=@var{bar}@r{|}@dots{}@r{|}@var{bar}}@*
Option @samp{--foo} requires exactly one @var{bar} argument, which must be
selected from given argument list.

@item
@samp{--foo=@var{bar}@r{|}@dots{}@r{|}@var{bar}@r{|}@var{baz}}@*
Option @samp{--foo} requires exactly one @var{bar} argument, which must be
selected from given @var{bar} argument list, or the alternative @var{baz}
argument.
@end enumerate

@noindent
Traditional short-style options differ as follows:

@enumerate
@item
@samp{-x}@*
Enables option @samp{-x}.

@item
@cindex Separator character, whitespace
@cindex Whitespace separator character
@samp{-x @var{bar}}@*
Enables option @samp{-x} with required argument @var{bar}.  The @var{bar}
argument may be separated by a leading @emph{whitespace} character from the
short-style option character @samp{x}.  This means following notations are
valid for giving an argument, namely @samp{-x @var{bar}} or @samp{-x@var{bar}}.

@item
@cindex Separator character, whitespace
@cindex Whitespace separator character
@samp{-x@r{[}@var{bar}@r{|}@dots{}@r{|}@var{bar}@r{]}}@*
Option @samp{-x} may have one or more @var{bar} @dfn{modifier}.  In this sense,
modifiers are one or more characters which define a special mode of operation
enabled by the @samp{-x} option.  A modifier may not be separated by a leading
@emph{whitespace} character from the short-style option character.
@end enumerate

@node Common options, Global options, Options, Options
@subsubsection Common options
@cindex Common options

@table @samp
@item -?
@itemx -h
@itemx --help
@arindex -?
@arindex -h
@arindex --help
@cindex Help, online
@cindex Short help text
@cindex Help text, short
Print a short usage message listing most of all available options,
then exit successfully.

@need 1500
@item -??
@itemx -hh
@itemx --usage@r{[}=@var{argument}@r{]}
@itemx --long-help@r{[}=@var{argument}@r{]}
@arindex -??
@arindex -hh
@arindex --usage@r{[}=@var{argument}@r{]}
@arindex --long-help@r{[}=@var{argument}@r{]}
@cindex Help, online
@cindex Extended help text
@cindex Help text, extended
@cindex Long help text
@cindex Help text, long
Print an extended usage message listing all available options,
then exit successfully.  If @var{argument} 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.@::

@example
--long-help=long-help
@end example

displays the extended help text for the long option @w{@samp{--long-help}}.

@arindex --usage=?
@arindex --long-help=?
@cindex List of all long-style option names
@cindex Long-style option names, list of
If @var{arguments} consists only of a single @samp{?} character or is no
valid long-style option name, a list of all valid long-style option names
is displayed.

@item -L
@itemx --license
@itemx --copyleft
@itemx --copyright
@arindex -L
@arindex --license
@arindex --copyleft
@arindex --copyright
@cindex Software license, finding
@cindex Copyleft
@cindex Copyright
Print the software license message, then exit successfully.

@item -V
@itemx --version
@arindex -V
@arindex --version
@cindex Version number, finding
Print the version number and compilation options, then exit successfully.

@item --exit-status-help-127
@arindex --exit-status-help-127
@cindex Program exit state 127
@cindex Exit code 127
Set exit state of program to 127 instead to 0, if one of the other
options of the @emph{common option class} is used.
@end table

@need 2000
@node Global options, Calendar options, Common options, Options
@subsubsection Global options
@cindex Global options

@table @samp
@item -R @var{name}
@itemx --response-file=@var{name}
@arindex -R @var{name}
@arindex --response-file=@var{name}
@cindex Response file, creation
@cindex Environment variable, @code{GCAL}
@cindex @code{GCAL} environment variable
@vindex GCAL
Write contents of environment variable @code{GCAL}
(@pxref{Environment variables, , GCAL}) and then arguments of command line
(in the given order) to file @var{name}, i.e.@: create response file
@file{name}.  @xref{Response file}, for more details.

@item -S @var{name}
@itemx --shell-script=@var{name}
@arindex -S @var{name}
@arindex --shell-script=@var{name}
@cindex Shell script, creation
@cindex Environment variable, @code{GCAL}
@cindex @code{GCAL} environment variable
@vindex GCAL
Write contents of environment variable @code{GCAL}
(@pxref{Environment variables, , GCAL}) and then arguments of command line
(in the given order) to shell script file @var{name}, i.e.@: create file
@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.

@item --debug@r{[}=internal@r{|}handled@r{|}unhandled@r{|}all@r{|}abort@r{]}
@arindex --debug@r{[}=internal@r{|}handled@r{|}unhandled@r{|}all@r{|}abort@r{]}
Display some debug informations.

@table @samp
@item --debug=internal
@arindex --debug=internal
Display warnings if program internal maximums are reached.

@item --debug=handled
@arindex --debug=handled
Like @samp{--debug=internal} and display file names which are handled, too.

@item --debug=unhandled
@arindex --debug=unhandled
Like @samp{--debug=internal} and display file names which are unhandled, too.

@item --debug=all
@arindex --debug=all
Like @samp{--debug=handled} and @samp{--debug=unhandled} together.

@need 1000
@item --debug=abort
@arindex --debug=abort
Like @samp{--debug=all} and abort program with error if file name can't be
handled, see @ref{Error codes, , 118}.
@end table

@item -p
@itemx --pager
@arindex -p
@arindex --pager
@cindex Pager, using
@cindex Pager, external
@cindex Pager program
@cindex External pager program
@cindex Environment variable, @code{PAGER}
@cindex @code{PAGER} environment variable
@vindex PAGER
Enables either an @emph{external} pager or a simple @emph{internal} pager.
If an environment variable @code{PAGER} is set, its value will be used for
detecting the external pager program.  @xref{Environment variables, , PAGER},
for more information.

@cindex Environment variable, @code{PATH}
@cindex @code{PATH} environment variable
@vindex PATH
If no @code{PAGER} environment variable is set or if its value is invalid,
Gcal tries to use the @code{less} pager; if this program can't be found
during scanning the @code{PATH} environment variable, Gcal tries to use
the @code{more} pager, if this program can't be found, the @code{pg} pager
in the same way @footnote{See the standard manual pages for @code{less},
@code{more} and @code{pg}.}.  @xref{Environment variables, , PATH}.

@cindex Pager, internal
@cindex Internal pager, simple
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:

@enumerate
@item
@vindex LINES
@vindex COLUMNS
@ifinfo
Gcal respects the values set in the environment variables @code{LINES}
and @code{COLUMNS}.  @xref{Environment variables, , LINES}, and see
@ref{Environment variables, , COLUMNS}, for more details.
@end ifinfo
@iftex
Gcal respects the values set in the environment variables @code{LINES}
and @code{COLUMNS}.  For more information, see @ref{Environment variables}.
@end iftex

@item
@vindex LI
@vindex CO
@ifinfo
If above action fails, Gcal respects the values set in the environment
variables @code{LI} and @code{CO}.  @xref{Environment variables, , LI}, and
see @ref{Environment variables, , CO}, for more details.
@end ifinfo
@iftex
If above action fails, Gcal respects the values set in the environment
variables @code{LI} and @code{CO}.  For more details, see
@ref{Environment variables}.
@end iftex

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

@item
@vindex TERM
If above action fails, Gcal respects the values set in the @file{termcap}
@footnote{See the standard manual pages for Termcap.} file, which refers to
the terminal used (@pxref{Environment variables, , TERM}).  This step is only
done on systems which support the use of Termcap by default.

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

@item -H yes
@itemx --force-highlighting
@itemx --highlighting=yes
@arindex -H yes
@arindex --force-highlighting
@arindex --highlighting=yes
@cindex Highlighting sequences, forcing
If output of the program is redirected or piped, the highlighting sequences
are @strong{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
@ref{Global options, , @samp{--mail=@var{address}}}.

@need 1500
@item -H no
@itemx --disable-highlighting
@itemx --highlighting=no
@arindex -H no
@arindex --disable-highlighting
@arindex --highlighting=no
@cindex Highlighting sequences, disabling
@cindex Marking characters, disabling
Disable highlighting sequence / marking character pairs of
current day, holiday respectively text explicitly.

@item -H @var{text}
@itemx --highlighting=@var{text}
@arindex -H @var{text}
@arindex --highlighting=@var{text}
@cindex Highlighting sequences, setting
@cindex Marking characters, setting
@cindex @samp{:} separator character
@cindex Separator character, @samp{:}
@cindex Sequence of control characters
@cindex Control character sequence
@cindex Escape sequence
Set highlighting sequence / marking character pairs explicitly.  In this sense,
@dfn{highlighting} sequences are control character sequences which cause a
colour or intensity switch of output text.  Typical control character sequences
are the @sc{ansi} escape sequences, which have a leading escape character and
trailing more characters, which define the type of the @sc{ansi} escape sequence.
In this sense, @dfn{marking} characters are single, printable characters, which
lead and succeed the output text.

The @var{text} argument must be a (@samp{:}) colon-separated text, which is
structured in this way: @w{@var{seq1_start}:@var{seq1_end}:@var{seq2_start}:@var{seq2_end}}.
The @strong{first} sequence is used for highlighting/marking the actual day,
the @strong{second} for holiday.  The sequences must be given in form of a
sequence pair; @w{@var{seq?_start}} enables the highlighting/marking,
@w{@var{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:

@quotation
@samp{-H \x20:\x20:\x1:#} respectively@*
@samp{--highlighting=\x20:\x20:\x1:#}@*
marks the actual day like @w{@samp{\x20@var{actual date}\x20}}
(this means with leading and trailing blanks) and the holiday date like
@w{@samp{\x1@var{holiday date}#}} using given marking characters.
@end quotation

@quotation
@samp{-H \x1b[34;42m:\x1b[0;40m} or@*
@samp{-H \033[34;42m:\033[0;40m} or@*
@samp{-H \E[34;42m:\E[0;40m}@*
defines a starting @sc{ansi} escape highlighting sequence
@w{@samp{\x1b[34;42m}} used for actual day and ending @sc{ansi}
escape highlighting sequence @w{@samp{\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. @xref{Environment variables, , GCALANSI}.
@end quotation

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

A character can be encoded octal by typing @samp{\@var{nnn}}
@w{(backslash-octal digit(s))}, where @var{n} must be a valid octal digit
(0@dots{}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 @samp{\x@var{nn}}
(@w{backslash-x} hexadecimal digit(s)), where @var{n} must be a valid
hexadecimal digit (0@dots{}9A@dots{}Fa@dots{}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.

@cindex Separator character, @samp{:}
@cindex @samp{:} separator character
If the sequence separator character, the @samp{:} (colon) character itself
is used for marking character, it must be encoded either octal by @code{\072}
or hexadecimal by @code{\x3A}.

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

@cindex Environment variable, @code{GCALANSI}
@cindex @code{GCALANSI} environment variable
@vindex GCALANSI
Incomplete or no given highlighting sequences will be replaced by internal
default @sc{ansi} escape highlighting sequences if a @code{GCALANSI}
environment variable is defined; otherwise completely replaced by their
according marking characters.  @xref{Environment variables, , GCALANSI}.

@item -m @var{address}
@itemx --mail=@var{address}
@arindex -m @var{address}
@arindex --mail=@var{address}
@cindex Mail, sending
@cindex Email, option
@cindex Electronic mail
Send Gcal's output via @code{mail} @footnote{See the standard manual pages
for @code{mail}.} program to Email-address @var{address}, e.g.@::

@example
@group
--mail=root
-m esken@@uni-muenster.de
@end group
@end example

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 @samp{--force-highlighting}
option was given or not.  This behavior of Gcal is an imperative necessaty,
because it is possible that the @code{mail} program cannot perform the mailing
correctly.  Please pay attention in this context to the further explanations
concerning the limitations of the @emph{text part} of a resource file line
(@pxref{Text part of a line}).
@end table

@need 2000
@node Calendar options, Date warning options, Global options, Options
@subsubsection Calendar options
@cindex Calendar options

@table @samp
@item -n@r{|}N@r{[}-@r{]}
@itemx --holiday-list@r{[}=long@r{|}short@r{]}
@itemx --descending-holiday-list@r{[}=long@r{|}short@r{]}
@arindex -n@r{|}N@r{[}-@r{]}
@arindex --holiday-list@r{[}=long@r{|}short@r{]}
@arindex --descending-holiday-list@r{[}=long@r{|}short@r{]}
@cindex Eternal holiday list, option
Display the eternal holiday list.  @xref{Eternal holidays}, for
additional information.

@need 1000
@table @samp
@item -n
@itemx --holiday-list=long
@arindex -n
@arindex --holiday-list=long
Display all holidays in eternal holiday list (this means all legal days
and all further memorial days) sorted in ascending order.

@need 1000
@item -n-
@itemx --descending-holiday-list=long
@arindex -n-
@arindex --descending-holiday-list=long
Display all holidays in eternal holiday list (this means all legal days
and all further memorial days) sorted in descending order.

@need 1000
@item -N
@itemx --holiday-list=short
@arindex -N
@arindex --holiday-list=short
Display legal days only in eternal holiday list sorted in ascending order.

@need 1000
@item -N-
@itemx --descending-holiday-list=short
@arindex -N-
@arindex --descending-holiday-list=short
Display legal days only in eternal holiday list sorted in descending order.
@end table

@need 2000
@item -X
@itemx --exclude-holiday-list-title
@arindex -X
@arindex --exclude-holiday-list-title
@cindex Eternal holiday list, suppression of title text
Suppresses the title text line of the eternal holiday list.

@item --christan-holidays
@arindex --christian-holidays
@cindex Eternal holiday list, Christian holidays
Provides the eternal holiday list with additional Christian holidays.
Furthermore, all additionally highlighted days of the eternal holiday list
are highlighted in the calendar sheets, too.

@item --de-holidays
@arindex --de-holidays
@cindex Eternal holiday list, German holidays
Provides the eternal holiday list with additional German holidays.
Furthermore, all additionally highlighted days of the eternal holiday list
are highlighted in the calendar sheets, too.

@item --us-holidays
@arindex --us-holidays
@cindex Eternal holiday list, U.S.@: American holidays
Provides the eternal holiday list with additional U.S.@: American holidays.
Furthermore, all additionally highlighted days of the eternal holiday list
are highlighted in the calendar sheets, too.

@item -i@r{[}-@r{]}
@itemx --type=special@r{|}standard
@arindex -i@r{[}-@r{]}
@arindex -i
@arindex --type=special@r{|}standard
@cindex Standard calendar format
@cindex Special calendar format
@cindex Calendar format, standard
@cindex Calendar format, special
@cindex Calendar sheet, force
To get the @dfn{standard} calendar format (similar @w{@sc{bsd}-@code{cal}}),
start Gcal omitting the @w{@samp{-i@r{[}-@r{]}}} option because it is set by
default.  @xref{Internationalization}, for more details.  Or start Gcal with
the @samp{-i-} respectively the @w{@samp{--type=standard}} option to force
the output of a calendar sheet:

@example
@group
@cartouche
$ gcal -i-
@print{}
@print{}    September 1994
@print{} Su Mo Tu We Th Fr Sa
@print{}              1  2  3
@print{}  4  5  6  7  8  9 10
@print{} 11 12 13 14 15 16 17
@print{} 18 19 20 21 22 23 24
@print{} 25 26 27 28 29 30
@end cartouche
@end group
@end example
@sp 2

@need 1500
To get the @dfn{special} calendar format and to force the output of a calendar
sheet, start Gcal with the @samp{-i} respectively the @w{@samp{--type=special}}
option:
@sp 2

@example
@group
@cartouche
$ gcal -i
@print{}
@print{} September 1994
@print{}
@print{} Sunday          4 11 18 25
@print{} Monday          5 12 19 26
@print{} Tuesday         6 13 20 27
@print{} Wednesday       7 14 21 28
@print{} Thursday     1  8 15 22 29
@print{} Friday       2  9 16 23 30
@print{} Saturday     3 10 17 24
@end cartouche
@end group
@end example

@item -u
@itemx --suppress-calendar
@arindex -u
@arindex --suppress-calendar
@cindex Calendar sheet, suppress
@cindex Suppress calendar sheet
Suppress output of calendar sheet explicitly.

@item -b @var{number}
@itemx --blocks=@var{number}
@arindex -b @var{number}
@arindex --blocks=@var{number}
@cindex Year calendar sheet blocks, number of
@cindex Year calendar sheet, force
Set @var{number} of calendar sheet blocks (valid arguments:
@w{@samp{1@r{|}2@r{|}3@r{|}4@r{|}6@r{|}12}).}  The default @var{number}
for the @emph{standard} calendar format is @samp{-b4 } respectively
@w{@samp{--blocks=4}}, and for the @emph{special} calendar format
@samp{-b 3} respectively @w{@samp{--blocks=3}}.  If this option is
found, the program sees that a year calendar output is desired!

@table @samp
@item -b 1
@itemx --blocks=1
@arindex -b 1
@arindex --blocks=1
Displays one block with twelve months at a time.

@need 1000
@item -b 2
@itemx --blocks=2
@arindex -b 2
@arindex --blocks=2
Displays two blocks with six months at a time.

@item -b 3
@itemx --blocks=3
@arindex -b 3
@arindex --blocks=3
Displays three blocks with four months at a time.

@item -b 4
@itemx --blocks=4
@arindex -b 4
@arindex --blocks=4
Displays four blocks with three months at a time.

@need 1000
@item -b 6
@itemx --blocks=6
@arindex -b 6
@arindex --blocks=6
Displays six blocks with two months at a time.

@item -b 12
@item --blocks=12
@arindex -b 12
@arindex --blocks=12
Displays twelve blocks with one month at a time.
@end table

@item -j@r{[}b@r{]}
@itemx --calendar-dates=special@r{|}both
@arindex -j@r{[}b@r{]}
@arindex --calendar-dates=special@r{|}both
@cindex Alternative date format in calendar sheet
@cindex Calendar sheet, alternative date format in
Use alternative date format in calendar sheet instead of the default
standard format, which displays the days of month in consecutive manner.

@table @samp
@item -j
@itemx --calendar-dates=special
@arindex -j
@arindex --calendar-dates=special
@cindex Special date format in calendar sheet
@cindex Calendar sheet, special date format in
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.

@item -jb
@itemx --calendar-dates=both
@arindex -jb
@arindex --calendar-dates=both
@cindex Standard and special date format in calendar sheet
@cindex Calendar sheet, standard and special date format in
Display the calendar sheet using the standard and special date format.
@end table

@item -jn@r{[}b@r{]}
@itemx --holiday-dates=special@r{|}both
@arindex -jn@r{[}b@r{]}
@arindex --holiday-dates=special@r{|}both
@cindex Alternative date format in eternal holiday list
@cindex Eternal holiday list, alternative date format in
Use alternative date format in eternal holiday list instead of the default
standard format, which displays the days of month in consecutive manner.
@xref{Calendar options, , @samp{--holiday-list@r{[}=long@r{|}short@r{]}}}.

@need 1000
@table @samp
@item -jn
@itemx --holiday-dates=special
@arindex -jn
@arindex --holiday-dates=special
@cindex Special date format in eternal holiday list
@cindex Eternal holiday list, special date format in
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.

@item -jnb
@itemx --holiday-dates=both
@arindex -jnb
@arindex --holiday-dates=both
@cindex Standard and special date format in eternal holiday list
@cindex Eternal holiday list, standard and special date format in
Display the eternal holiday list using the standard and special date format.
@end table

@item -jc@r{[}b@r{]}
@itemx --fixed-dates=special@r{|}both
@arindex -jc@r{[}b@r{]}
@arindex --fixed-dates=special@r{|}both
@cindex Alternative date format in fixed date warning list
@cindex Fixed date warning list, alternative date format in
Use alternative date format in fixed date warning list instead of the default
standard format, which displays the days of month in consecutive manner.
@xref{Date warning options, , @samp{--list-of-fixed-dates@r{[}=short@r{|}long@r{]}}}.

@table @samp
@item -jc
@itemx --fixed-dates=special
@arindex -jc
@arindex --fixed-dates=special
@cindex Special date format in fixed date warning list
@cindex Fixed date warning list, special date format in
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.

@item -jcb
@itemx --fixed-dates=both
@arindex -jcb
@arindex --fixed-dates=both
@cindex Standard and special date format in fixed date warning list
@cindex Fixed date warning list, standard and special date format in
Display the fixed date warning list using the standard and special date format.
@end table

@item -s @var{argument}
@itemx --starting-day=@var{argument}
@arindex -s @var{argument}
@arindex --starting-day=@var{argument}
@cindex Starting day of week, setting
Set the starting day of week (valid @var{argument}:
@w{@samp{0@r{,} 1@r{@dots{}}7 @r{|} today @r{|} @var{weekday name}}).}

Example:

@example
@group
--starting-day=Sunday @r{or}
--starting-day=7 @r{or}
-s SUNDAY @r{or}
-s sund @r{or}
-s Su @r{or}
-s 7 
@end group
@end example

thus all specifies the Sunday @w{(1@equiv{}Mon, 2@equiv{}Tue @dots{} 7@equiv{}Sun)}.

If the @w{@samp{-s today}} option (or @w{@samp{--starting-day=today}}) or
the @w{@samp{-s 0}} option (or
@iftex
@*
@end iftex
@w{@samp{--starting-day=0}}) is given, the starting day of week is set to
the actual weekday.

@xref{Internationalization}, for more details.

@item --gregorian-reform=1582@r{|}1752@r{|}@var{argument}
@arindex --gregorian-reform=1582@r{|}1752@r{|}@var{argument}
@cindex Period of Gregorian Reformation, set
@cindex Gregorian Reformation, set period of
Set the period which was skipped during the Gregorian Reformation.
@xref{Internationalization}, for more details.  Actually, two fixed default
periods (on the one hand of the year 1582 and on the other hand of the year
1752) are supported.  If Gcal is called with the
@w{@samp{--gregorian-reform=1582}} option, it assumes the Gregorian Reformation
have occured from 5th till 14th October 1582.  If Gcal is called with the
@w{@samp{--gregorian-reform=1752}} option, it assumes the Gregorian Reformation
have occured from 3rd till 13th September 1752.

In case another period shall be respected, it can be arranged by the option
argument @var{argument} like @samp{@var{yyyy},@var{mm},@var{first day},@var{last day}}.
If the Gregorian Reformation have occured for example on the 7th till the
17th April 1802, this can be declared as follows:

@example
--gregorian-reform=1802,4,7,17
@end example

@item --date-format=de@r{|}us@r{|}gb@r{|}@var{text}
@arindex --date-format=de@r{|}us@r{|}gb@r{|}@var{text}
Set the date format which controls the ordering and representation of a
displayed date.  @xref{Internationalization}, for more details.  The date
format text is respected by Gcal in the eternal holiday list, in the fixed
date warning list and the calendar sheets.  Moreover, Gcal internally tries
to obtain the best representation of a displayed date in case the days of the
year instead of the days of the months must be displayed.

Actually, three fixed default date formats (for German users, U.S.@: American
users and for users in Great Britain) are supported.  If Gcal is called
with the @w{@samp{--date-format=de}} option, the @w{@samp{%w,  %1%D%2 %b %y}}
format text is used.  If Gcal is called with the @w{@samp{--date-format=us}}
option, the @w{@samp{%W, %b  %1%U%2 %y}} format text is used.  If Gcal is
called with the @w{@samp{--date-format=gb}} option, the
@w{@samp{%W,  %1%U%2 %b %y}} format text is used.

@vindex GCAL_DATE_FORMAT
In case another format text shall be respected, this format text can
either be set in the @code{GCAL_DATE_FORMAT} environment variable (but
@code{GCAL_DATE_FORMAT} is only used in case no
@w{@samp{--date-format=de@r{|}us@r{|}gb@r{|}@var{text}}} option is given),
or it can be arranged by the option argument @var{text}, e.g.@::

@example
--date-format="%Y %D %m ; %1(%A)%2"
@end example

The format text may contain on the one hand all characters, which can be
managed by Gcal and on the other hand character replacement instructions
and format statements, which are transformed into their according values
at run-time.  A minimum date format text must contain components from the
day group, the month group, the year group and the highlighting group.
A component of the weekday name group is optional.  The following format
statements and character replacement instructions are actually supported:

Day group (exactly one member must be defined):

@table @code
@item %d
Day number with leading zeroes

@item %D
Day number with leading spaces

@item %u
Day number with leading zeroes and trailing Ordinal Number suffix

@item %U
Day number with leading spaces and trailing Ordinal Number suffix
@end table

Month group (exactly one member must be defined):

@table @code
@item %B
Complete month name

@item %b
Abbreviated month name (3 letters)

@item %m
Month number with leading zeroes

@item %M
Month number with leading spaces
@end table

Year group (exactly one member must be defined):

@table @code
@item %y
Complete year number with leading zeroes

@item %Y
Complete year number with leading spaces

@item %z
Last two digits of year number with leading zeroes

@item %Y
Last two digits of year number with leading spaces
@end table

@need 1000
Weekday name group (one member may be defined):

@table @code
@item %A
Complete weekday name

@item %W
Abbreviated weekday name (3 letters)

@item %w
Abbreviated weekday name (2 letters)
@end table

Highlighting group (all members must be defined and @code{%1} must be
specified before @code{%2}):

@table @code
@item %1
Start of highlighting sequence / marking character

@item %2
End of highlighting sequence / marking character
@end table

Character replacement instructions:

@table @code
@item _
Space/blank character @samp{ }

@item \_
Underscore character @samp{_}

@item \%
Percent character @samp{%}
@end table
@end table

@node Date warning options, , Calendar options, Options
@subsubsection Date warning options
@cindex Date warning options

@table @samp
@item -v @var{argument}
@itemx --date-variable=@var{argument}
@arindex -v @var{argument}
@arindex --date-variable=@var{argument}
@cindex Date variables, global
@cindex Global date variables, definition of
@cindex Definition of global date variables
@cindex Definition of date variables
@cindex Date variables, definition of
@cindex Management of date variables
@cindex Date variables, management of
@cindex Scope of date variables
@cindex Date variables, scope of
@cindex Operations on date variables
@cindex Date variables, operations on
@cindex Assignments to date variables
@cindex Date variables, assignments to
@cindex Name space of date variables
@cindex Date variables, name space of
@cindex @samp{:} separator character
@cindex Separator character, @samp{:}
Define @dfn{global} date variable, which is visible in all referenced resource
files (@pxref{Date variables}).  The option argument @var{argument} must either
be a valid single date variable definition or a (@samp{:}) colon-separated list
of definitions.

A date variable name @var{dvar} consists of a single letter (case-insensitive
and except the letter @samp{e}, which is internally reserved for the Easter
Sunday's date and which is unassignable/inoperatable therefore) and is trailed
in a definition by the assignment operator character @samp{=} and the numerical
values of month @var{mm} (or a short, three characters month name, e.g.@:
@samp{Jan}, @samp{Feb}@dots{}) and day @var{dd} this variable has to store
(or another global date variable name, but @strong{no} date given in the
@samp{@var{mm}@var{www}@var{n}},
@samp{@var{dvar}@r{[}+@r{|}-@r{]}@var{n}@r{[}@var{www}@r{]}} or the
@samp{*d@r{|}w@var{n}@r{[}@var{www}@r{]}} format).

Some examples:

@quotation
@samp{--date-variable=a=1127:c=a} respectively@*
@samp{-v a=1127:c=a}@*
stores the 27th November to the global date variable @var{a} and to the
global date variable @var{c}.
@end quotation

@need 1000
@item --export-date-variables
@arindex --export-date-variables
@cindex Date variables, export of local
@cindex Export of local date variables
@cindex Visibility of local date variables
@cindex Date variables, visibility of local
Affects the export of local date variables from one resource file to another
resource file.  @xref{Date variables}, for more details.

@item -r @var{argument}
@itemx --text-variable=@var{argument}
@arindex -r @var{argument}
@arindex --text-variable=@var{argument}
@cindex Text variables, global
@cindex Global text variables, definition of
@cindex Definition of global text variables
@cindex Definition of text variables
@cindex Text variables, definition of
@cindex Management of text variables
@cindex Text variables, management of
@cindex Scope of text variables
@cindex Text variables, scope of
@cindex Assignments to text variables
@cindex Text variables, assignments to
@cindex Name space of text variables
@cindex Text variables, name space of
@cindex @samp{:} separator character
@cindex Separator character, @samp{:}
Define @dfn{global} text variable, which is visible in all referenced resource
files (@pxref{Text variables}).  The option argument @var{argument} must either
be a valid single text variable definition or a (@samp{:}) colon-separated list
of definitions.

A text variable name @var{tvar} consists of the @samp{$} prefix and a single
letter (case-insensitive), and is trailed in a definition by the assignment
operator character @samp{=} and the text this variable has to store.  A global
text variable is defined with an @emph{empty} contents in case no text is
specified on the right of the assignment operator character.

Some examples:

@quotation
@samp{--text-variable=$a=foo:$c=$a} respectively@*
@samp{-r $a=foo:$c=$a}@*
stores the @samp{foo} text to the global text variable @var{$a} and to the
global text variable @var{$c}.
@end quotation

@cindex Quotation of special characters
@cindex Quotation character, @samp{\}
@cindex @samp{\} quotation character
You may quote the @samp{:} separator character @minus{} in case this
character itself is needed in the text @minus{} by placing a @samp{\}
(backslash) character before it, e.g.@: @samp{\:}.

If you need the characters @samp{\:} itself in the text, you have to quote
the @samp{\} (backslash) character by itself, e.g.@: @samp{\\:}.

@cindex Quotation of special characters
@cindex Quotation character, @samp{\}
@cindex @samp{\} quotation character
You may quote the @samp{$} prefix character @minus{} in case this
character itself is needed in the text @minus{} by placing a @samp{\}
(backslash) character before it, e.g.@: @samp{\$}.

If you need the characters @samp{\$} itself in the text, you have to quote
the @samp{\} (backslash) character by itself, e.g.@: @samp{\\$}.

@cindex Pseudo space character, @samp{_}
@cindex @samp{_} pseudo space character
Each time a @samp{_} (underscore) character is found in @var{argument}, this
character is replaced by a real @samp{ } (space) character.

@cindex Quotation of special characters
@cindex Quotation character, @samp{\}
@cindex @samp{\} quotation character
You may quote the @samp{_} (underscore) character @minus{} in case this
character itself is needed @minus{} by placing a @samp{\} (backslash)
character before it, e.g.@: @samp{\_}.

If you need the characters @samp{\_} itself, you have to quote the
@samp{\} (backslash) character by itself, e.g.@: @samp{\\_}.

@need 1000
@item --export-text-variables
@arindex --export-text-variables
@cindex Text variables, export of local
@cindex Export of local text variables
@cindex Visibility of local text variables
@cindex Text variables, visibility of local
Affects the export of local text variables from one resource file to another
resource file.  @xref{Text variables}, for more details.

@item -c@r{|}C@r{[}-@r{]}
@itemx --today
@itemx --list-of-fixed-dates@r{[}=short@r{|}long@r{]}
@itemx --descending-fixed-dates@r{[}=short@r{|}long@r{]}
@arindex -c@r{|}C@r{[}-@r{]}
@arindex --today
@arindex --list-of-fixed-dates@r{[}=short@r{|}long@r{]}
@arindex --descending-fixed-dates@r{[}=short@r{|}long@r{]}
@cindex Date warnings, option
@cindex Fixed date warnings
@cindex Date warning period long-style option, @samp{--today}
@cindex Today warnings
@cindex Fixed date warnings related to @emph{today}
@cindex Aktivate fixed date warning function
@cindex Fixed date warning function, activate
Activate fixed date warning function and display fixed date warning messages.

@table @samp
@item -c
@itemx --today
@itemx --list-of-fixed-dates=short
@arindex -c
@arindex --today
@arindex --list-of-fixed-dates=short
Activate fixed date warning function (use standard resource file implicitly)
and list all dates related to current day sorted in ascending order.  If no
fixed dates related to the current day are found, no fixed date warning
messages are displayed and the program is terminated with error code, see
@ref{Error codes, , 1}.

@need 1000
@item -c-
@itemx --descending-fixed-dates=short
@arindex -c-
@arindex --descending-fixed-dates=short
Activate fixed date warning function (use standard resource file implicitly)
and list all dates related to current day sorted in descending order.  If no
fixed dates related to the current day are found, no fixed date warning
messages are displayed and the program is terminated with error code, see
@ref{Error codes, , 1}.

@need 1000
@item -C
@itemx --list-of-fixed-dates=long
@arindex -C
@arindex --list-of-fixed-dates=long
Activate fixed date warning function (use standard resource file implicitly)
and list all dates related to current day sorted in ascending order.  If no
fixed dates related to the current day are found, a fixed date warning text
which consists only of the date is displayed.

@need 1000
@item -C-
@item --descending-fixed-dates=long
@arindex -C-
@arindex --descending-fixed-dates=long
Activate fixed date warning function (use standard resource file implicitly)
and list all dates related to current day sorted in descending order.  If no
fixed dates related to the current day are found, a fixed date warning text
which consists only of the date is displayed.
@end table

@item -f@r{|}F @var{name}@r{[}+@dots{}@r{]}
@itemx --resource-file=@var{name}
@arindex -f@r{|}F @var{name}@r{[}+@dots{}@r{]}
@arindex --resource-file=@var{name}
@cindex Resource file, additional
@cindex Aktivate fixed date warning function
@cindex Fixed date warning function, activate
Activate fixed date warning function and use file @var{name} instead of the
standard resource file.  Then list all dates sorted in ascending order, which
occur in the fixed date warning period.  If no other fixed date warning period
is specified, the current day is used for the fixed date warning period.  If
the option letter @samp{f} of the short-style option is used and no dates
related to the fixed date warning period are found in @var{name}, no fixed date
warning messages are displayed and the program is terminated with error code,
see @ref{Error codes, , 1}.  If the option letter @samp{F} of the short-style
option is used and no dates related to the fixed date warning period are found
in @var{name}, a fixed date warning text which consists only of the date is
displayed.

@cindex Separator character, @samp{+}
@cindex @samp{+} separator character
@vindex HOME
You can use more than one resource file @var{name} by separating them with a
@samp{+} separator character, e.g.@::

@quotation
@samp{--resource-file=./foo+xyz+/data/foo.bar+$HOME/.gcalrc} resp.,@*
@samp{-f ./foo+xyz+/data/foo.bar+$HOME/.gcalrc}
@end quotation

respects all files, which are given in above argument using a special file
search mechanism.  @xref{Resource file, File searching mechanism}, for more
details.  Use @file{/dev/null} to avoid the use of the standard resource file,
useful for creating empty fixed dates warning lists.

@cindex Quotation of special characters
@cindex Quotation character, @samp{\}
@cindex @samp{\} quotation character
You may quote the @samp{+} separator character @minus{} in case this
character itself is needed @minus{} by placing a @samp{\} (backslash)
character before it, e.g.@: @samp{\+}.

If you need the characters @samp{\+} itself, you have to quote the
@samp{\} (backslash) character by itself, e.g.@: @samp{\\+}.

@cindex Pseudo space character, @samp{_}
@cindex @samp{_} pseudo space character
Each time a @samp{_} (underscore) character is found in @var{name}, this
character is replaced by a real @samp{ } (space) character.

@cindex Quotation of special characters
@cindex Quotation character, @samp{\}
@cindex @samp{\} quotation character
You may quote the @samp{_} (underscore) character @minus{} in case this
character itself is needed @minus{} by placing a @samp{\} (backslash)
character before it, e.g.@: @samp{\_}.

If you need the characters @samp{\_} itself, you have to quote the
@samp{\} (backslash) character by itself, e.g.@: @samp{\\_}.
@end table

@noindent
@strong{Please note:}@*
If the short-style option @samp{-c} and/or its modifiers
@w{@samp{t@r{|[}w@r{|}m@r{|}y@r{[}+@r{|}-@r{]}}}, or the short-style option
@samp{-f} is/are given in @strong{upper case}, e.g.@::

@example
@group
-C
-F foo.bar
-CeT
-c-aW+
-CeaxY-
-c-M
@end group
@end example

@noindent
Gcal displays fixed date messages for @strong{every} day of the requested
period.

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

@quotation
@table @asis
@item First step: @emph{Representation-of-text-modifier}
@cindex Representation-of-text-modifier
@samp{a},
@samp{A},
@samp{e@r{|}E},
@samp{k},
@samp{o},
@samp{x},
@samp{z}

@item Second step: @emph{Respected-warning-period-modifier}
@cindex Respected-warning-period-modifier
@w{@samp{d},}
@w{@samp{l},}
@w{@samp{t@r{|}T},}
@w{@samp{w@r{|}W@r{|}m@r{|}M@r{|}y@r{|}Y@r{[}+@r{|}-@r{]}},}
@w{@samp{@var{n}+@r{|}-},}
@w{@samp{@var{n}d},}
@w{@samp{@var{n}w},}
@w{@samp{*d@var{n}@r{[}@var{www}@r{]}},}
@w{@samp{*w@var{n}@r{[}@var{www}@r{]}},}
@w{@samp{@@e@r{|}@var{dvar}@r{[[}+@r{|}-@r{]}@var{n}@r{]}},}
@w{@samp{@@e@r{|}@var{dvar}@r{[}+@r{|}-@r{]}@var{n}@var{www}},}
@w{@samp{@var{mm}@var{dd}},}
@w{@samp{@var{mm}@var{www}@var{n}}}
@end table
@end quotation
@sp 2

If you want to operate with the following modifiers, an @strong{explicit}
@w{@samp{-c@r{|}C@r{[}-@r{]}}} short-style option must be leading, e.g.@::

@example
@group
-c-t
-cw-
-CaAdeklorxz12+
@end group
@end example

@cindex Date warning period modifier, @samp{d}
@cindex Date warning period modifier, @samp{l}
@cindex Date warning period option, @samp{--leap-day=february@r{|}march}
@noindent
and only @strong{one} period defining fixed date warning period modifier
may be given (this means exclusive the @samp{--include-today} option
respectively @samp{d} modifier, the @samp{--list-mode} option respectively
@samp{l} modifier and the @samp{--leap-day=february@r{|}march}).

@cindex Single character options
@cindex Single command line word
Or the modifiers must be given as single character options or composed into
a single command line word, and additionally either the short-style option
@w{@samp{-c@r{|}C@r{[}-@r{]}}} (or the according long-style option) or
@w{@samp{-f@r{|}F @var{name}@r{[}+@dots{}@r{]}}} (or the according long-style
option) must be given like:

@example
@group
-c -t
-w- -c
-a -Ad -e -klorxz -C12+
-F foo.bar -Ad -l*d10
@end group
@end example

@cindex Single character options
@cindex Single command line word
@cindex Date warnings, option
@cindex Fixed date warnings
@cindex Aktivate fixed date warning function
@cindex Fixed date warning function, activate
If modifiers are given as single character options or composed into a single
command line word and one of the
@w{@samp{t@r{|}T@r{|[}w@r{|}W@r{|}m@r{|}M@r{|}y@r{|}Y@r{[}+@r{|}-@r{]]}}}
modifiers is used (or their according alias names like @samp{--today},
@samp{--tomorrow}@dots{}), it's not necessary to give a
@w{@samp{-c@r{|}C@r{[}-@r{]}}} short-style option (or its according long-style
option) respectively @w{@samp{-f@r{|}F @var{name}@r{[}+@dots{}@r{]}}} (or its
according long-style option) to activate the fixed date warning function of
Gcal, because it is triggered implicitly by means of these modifiers.

@page
@cindex Fixed date warning text modifiers
@cindex Modifiers, fixed date warning text
@noindent
@strong{Fixed date warning text modifiers:}

@table @samp
@item a
@itemx --include-resource-file-name
@arindex -a
@arindex -ca
@arindex --include-resource-file-name
@cindex Date warning text modifier, @samp{a}
Extend fixed date warning text by the name of the resource file,
which the warning text comes from, e.g.@::

@example
@group
Mon, Jan   1st 1995: (`Eternal holiday list') New Year's day
Mon, Jan   1st 1995: (.gcalrc) No fixed dates
@dots{}
@end group
@end example

@item A
@itemx --alternative-format
@arindex -A
@arindex -cA
@arindex --alternative-format
@cindex Date warning text modifier, @samp{A}
Instead of using the @dfn{standard} list format, e.g.@::

@example
@group
Mon, Jan   1st 1995: New Year's day
Mon, Jan   1st 1995: No fixed dates
@dots{}
@end group
@end example

Gcal uses the @dfn{alternative} list format, e.g.@::

@example
@group
Mon, Jan   1st 1995:
New Year's day
No fixed dates
@dots{}
@end group
@end example

@item e
@itemx --include-holidays=long
@arindex -e
@arindex -ce
@arindex --include-holidays=long
@cindex Date warning text modifier, @samp{e}
Enable inclusion of all built-in eternal holiday dates, this includes
legal days and memorial days.

@item E
@itemx --include-holidays=short
@arindex -E
@arindex -cE
@arindex --include-holidays=short
@cindex Date warning text modifier, @samp{E}
Enable inclusion of those built-in eternal holiday dates, which are legal
days only.

@need 1000
@item g@r{[}@var{text}@r{]}
@itemx --grouping-text@r{[}=@var{text}@r{]}
@arindex -g@r{[}@var{text}@r{]}
@arindex -cg@r{[}@var{text}@r{]}
@arindex --grouping-text@r{[}=@var{text}@r{]}
@cindex Date warning text modifier, @samp{g@r{[}@var{text}@r{]}}
Group fixed date warnings by day using separator @var{text}.  If @var{text} is
not given, the built-in text @var{text} (@w{@code{RC_GROUP_SEP}} "" @equiv{}
empty line only) is used for grouping, e.g.@::

@example
@group
@cartouche
$ gcal -Cw -cg
@print{}
@print{} Sun, Nov   6th 1994: Text 1
@print{} Sun, Nov   6th 1994: Text 2
@print{}
@print{} Mon, Nov   7th 1994: Text 3
@print{}
@print{} Tue, Nov   8th 1994: Text 4
@dots{}


$ gcal -Cw -g'-A_user\_defined-~-grouping text-'
@print{}
@print{} Sun, Nov   6th 1994: Text 1
@print{} Sun, Nov   6th 1994: Text 2
@print{} -A user_defined-
@print{} -grouping text-
@print{} Mon, Nov   7th 1994: Text 3
@print{} -A user_defined-
@print{} -grouping text-
@print{} Tue, Nov   8th 1994: Text 4
@dots{}
@end cartouche
@end group
@end example

@cindex Force line break
@cindex Line-break character, @samp{~}
@cindex @samp{~} line-break character
Each time a @samp{~} (tilde) character is found in @var{text}, this
character is replaced by a real @samp{\n} (newline) character.

@cindex Quotation of special characters
@cindex Quotation character, @samp{\}
@cindex @samp{\} quotation character
You may quote the @samp{~} (tilde) character @minus{} in case this
character itself is needed @minus{} by placing a @samp{\} (backslash)
character before it, e.g.@: @samp{\~}.

If you need the characters @samp{\~} itself, you have to quote the
@samp{\} (backslash) character by itself, e.g.@: @samp{\\~}.

@cindex Pseudo space character, @samp{_}
@cindex @samp{_} pseudo space character
Each time a @samp{_} (underscore) character is found in @var{text}, this
character is replaced by a real @samp{ } (space) character.

@cindex Quotation of special characters
@cindex Quotation character, @samp{\}
@cindex @samp{\} quotation character
You may quote the @samp{_} (underscore) character @minus{} in case this
character itself is needed @minus{} by placing a @samp{\} (backslash)
character before it, e.g.@: @samp{\_}.

If you need the characters @samp{\_} itself, you have to quote the
@samp{\} (backslash) character by itself, e.g.@: @samp{\\_}.

@item k
@itemx --include-weeknumber
@arindex -k
@arindex -ck
@arindex --include-weeknumber
@cindex Date warning text modifier, @samp{k}
@cindex @sc{iso}-8601:1988
The leading date of a warning message is extended by the
@sc{iso}-8601:1988 week number of that date.

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

@need 1000
@item o
@itemx --omit-multiple-date-part
@arindex -o
@arindex -co
@arindex --omit-multiple-date-part
@cindex Date warning text modifier, @samp{o}
Omit displaying the leading date of a warning message in case more than one
warning message refers to that date (only if the @samp{--alternative-format}
option respectively the @samp{A} modifier is not given), e.g.@::

@example
@group
@cartouche
$ gcal -co
@print{}
@print{} Sun, Nov   6th 1994: Text 1
@print{}                      Text 2
@dots{}
@end cartouche
@end group
@end example

@item x
@itemx --exclude-fixed-dates-list-title
@arindex -cx
@arindex --exclude-fixed-dates-list-title
@cindex Date warning text modifier, @samp{x}
Suppresses the title text line of the fixed date warning list.

@need 1000
@item z
@itemx --include-consecutive-number
@arindex -z
@arindex -cz
@arindex --include-consecutive-number
@cindex Date warning text modifier, @samp{z}
Display consecutive numbers of fixed date warning messages.
@end table

@page
@cindex Fixed date warning period modifiers
@cindex Modifiers, fixed date warning period
@noindent
@strong{Fixed date warning period modifiers:}

@table @samp
@item --leap-day=february@r{|}march
@arindex --leap-day=february@r{|}march
@cindex Date warning period option, @samp{--leap-day=february@r{|}march}
@cindex Leap day
The @dfn{leap day} (i.e.@: the 29th February) is observed in non-leap years.

@table @samp
@item --leap-day=february
@arindex --leap-day=february
@cindex Date warning period option, @samp{--leap-day=february}
@cindex Move leap day to 28th February
A warning message which appears in every year and which is related
to the leap day, is displayed on the 28th February in non-leap years.

@item --leap-day=march
@arindex --leap-day=march
@cindex Date warning period option, @samp{--leap-day=march}
@cindex Move leap day to 1st March
A warning message which appears in every year and which is related
to the leap day, is displayed on the 1st March in non-leap years.
@end table

@item d
@itemx --include-today
@arindex -d
@arindex -cd
@arindex --include-today
@cindex Date warning period modifier, @samp{d}
If lists of periods are generated, include the actual date into the list.
@xref{Date warning options, , @samp{--list-mode}}, for how to create a list
of periods.

@need 1000
@item l
@itemx --list-mode
@arindex -l
@arindex -cl
@arindex --list-mode
@cindex Date warning period modifier, @samp{l}
Generate a list of periods instead of a single period.
@end table
@sp 2

@quotation
@strong{Please note:}@*
The following examples assume the current date is the 17th February
of any year.
@end quotation
@sp 2

@table @asis
@item @samp{--period-of-fixed-dates=@var{argument}}
@arindex --period-of-fixed-dates=@var{argument}
@sp 2

@item @samp{@var{n}d}
@itemx @samp{*d@var{n}}
@arindex -c@var{n}d
@arindex -*d@var{n}
@arindex -c*d@var{n}
@cindex Date warning period modifier, @samp{@var{n}d}
@cindex Date warning period modifier, @samp{*d@var{n}}
Single date of absolute day @w{@var{n} @equiv{} @samp{1@dots{}365@r{|}366@r{|}999}}
of actual year; the warning level is same as simple @samp{-c} option.  If the
value 999 for @var{n} is given, the last day of the year (31st December) is
assumed.

@itemize @bullet
@item
E.g.@: @samp{gcal -c10d} respectively @w{@samp{gcal --period-of-fixed-dates=10d}}
or @samp{gcal -c*d10} respectively @w{@samp{gcal --period-of-fixed-dates=*d10}}
displays all fixed dates, which occur on the 10th day of the year.
@end itemize

@need 1000
@item @samp{l@var{n}d}
@itemx @samp{l*d@var{n}}
@arindex -l@var{n}d
@arindex -cl@var{n}d
@arindex -l*d@var{n}
@arindex -cl*d@var{n}
@cindex Date warning period modifier, @samp{l@var{n}d}
@cindex Date warning period modifier, @samp{l*d@var{n}}
List dates starting yesterday or tomorrow (depending on given day
number @var{n}) and ending at @w{@var{n}'th} absolute day of actual year;
the warning level is same as @samp{-cy} option.

@itemize @bullet
@item
E.g.@: @samp{gcal -cl10d} respectively @samp{gcal -cl*d10} displays a list of
all fixed dates, which start on the 10th day of year and end on 16th February.
@end itemize

@need 1000
@item @samp{@var{n}+@r{|}-}
@arindex -c@var{n}+@r{|}-
@cindex Date warning period modifier, @samp{@var{n}+@r{|}-}
Single date of day
@ifinfo
@emph{actual day @w{@samp{+@r{/}-}} @var{n} days}
@end ifinfo
@tex
\emph{actual day $\pm$ \smartitalic{n} days}
@end tex
of actual year; the warning level is same as simple @samp{-c}
option.

@itemize @bullet
@item
E.g.@: @samp{gcal -c10+} displays all fixed dates, which occur
10 days after the 17th February (today).

@item
E.g.@: @samp{gcal -c10-} displays all fixed dates, which occur
10 days before the 17th February (today).
@end itemize

@item @samp{l@var{n}+@r{|}-}
@arindex -l@var{n}+@r{|}-
@arindex -cl@var{n}+@r{|}-
@cindex Date warning period modifier, @samp{l@var{n}+@r{|}-}
List dates starting yesterday @samp{-} or tomorrow @samp{+} and ending at
@ifinfo
@emph{actual day @w{@samp{+@r{/}-}} @var{n} days}
@end ifinfo
@tex
\emph{actual day $\pm$ \smartitalic{n} days}
@end tex
of actual year; the warning level is same as @samp{-cy} option.

@itemize @bullet
@item
E.g.@: @samp{gcal -cl10+} displays a list of all fixed dates, which start
on the 18th February and end 10 days after.

@item
E.g.@: @samp{gcal -cl10-} displays a list of all fixed dates, which start
10 days before the 16th February and end on the 16th February.
@end itemize

@need 1000
@item @samp{@var{n}w}
@arindex -c@var{n}w
@cindex Date warning period modifier, @samp{@var{n}w}
Single dates of week number
@w{@var{n} @equiv{} @samp{0@r{|}1@r{@dots{}}52@r{|}53@r{|}99}}
of actual year; the warning level is same as @samp{-cw} option.

@itemize @bullet
@item
E.g.@: @samp{gcal -c0w} displays all fixed dates, which occur
in the 53rd @sc{iso}-week of previous year, in case the previous year has a
53rd @sc{iso}-week.  If the previous year has 52 @sc{iso}-weeks only, all
fixed dates occuring on the 1st week of the actual year are displayed.

@item
E.g.@: @samp{gcal -c6w} displays all fixed dates, which occur
in the 6th @sc{iso}-week of year.

@item
E.g.@: @samp{gcal -c52w} displays all fixed dates, which occur
in the 52nd @sc{iso}-week of year.

@item
E.g.@: @samp{gcal -c53w} displays all fixed dates, which occur
in the 53rd @sc{iso}-week of the actual year, in case the actual year has a
53rd @sc{iso}-week.  If the actual year has 52 @sc{iso}-weeks only, no fixed
date warning messages are displayed and the program is terminated with error
code, see @ref{Error codes, , 126}.

@item
E.g.@: @samp{gcal -c99w} displays all fixed dates, which occur
in the last @sc{iso}-week of the actual year, i.e.@ either the 52nd or the
53rd @sc{iso}-week.
@end itemize

@item @samp{l@var{n}w}
@arindex -l@var{n}w
@arindex -cl@var{n}w
@cindex Date warning period modifier, @samp{l@var{n}w}
List dates starting yesterday or tomorrow (depending on given @sc{iso}-week
number @var{n}) and ending at first respectively last day of given @sc{iso}-week
number @w{@var{n} @equiv{} @samp{0@r{|}1@r{@dots{}}52@r{|}53@r{|}99}} of actual
year; the warning level is same as @samp{-cy} option.

@itemize @bullet
@item
E.g.@: @samp{gcal -cl12w} displays a list of all fixed dates, which start
on the 18th February and end on the last day of the 12th @sc{iso}-week.

@item
E.g.@: @samp{gcal -cl3w} displays a list of all fixed dates, which start
on the first day of the 3rd @sc{iso}-week and end on the 16th February.
@end itemize

@need 1000
@item @samp{@var{mm}@var{dd}}
@arindex -c@var{mm}@var{dd}
@cindex Date warning period modifier, @samp{@var{mm}@var{dd}}
Single date of day @var{dd} in month @var{mm} of actual year;
the warning level is same as simple @samp{-c} option.

@itemize @bullet
@item
E.g.@: @samp{gcal -c0225} displays all fixed dates, which occur
on the 25th February.
@end itemize

@item @samp{l@var{mm}@var{dd}}
@arindex -l@var{mm}@var{dd}
@arindex -cl@var{mm}@var{dd}
@cindex Date warning period modifier, @samp{0@var{mm}@var{dd}}
List dates starting yesterday or tomorrow (depending on the value given in
@var{mm}@var{dd}) and ending at day @var{dd} of month @var{mm} of actual year;
the warning level is same as @samp{-cy} option.

@itemize @bullet
@item
E.g.@: @samp{gcal -cl0225} displays a list of all fixed dates, which start
on the 18th February and end on the 25th February.

@item
E.g.@: @samp{gcal -cl0109} displays a list of all fixed dates, which start
on the 9th January and end on the 16th February.
@end itemize

@item @samp{@var{mm}@var{www}@var{n}}
@arindex -c@var{mm}@var{www}@var{n}
@cindex Date warning period modifier, @samp{@var{mm}@var{www}@var{n}}
Single date of @w{@var{n}'th @equiv{} @samp{1@r{@dots{}}5@r{|}9}} weekday
@w{@var{dd}|@var{www}} in month @var{mm} of actual year;
the warning level is same as simple @samp{-c} option.

@itemize @bullet
@item
E.g.@: @samp{gcal -c01mon3} displays all fixed dates, which occur
on the 3rd Monday in January.

@item
E.g.@: @samp{gcal -c02fri9} displays all fixed dates, which occur
on the last Friday in February.
@end itemize

@item @samp{l@var{mm}@var{www}@var{n}}
@arindex -l@var{mm}@var{www}@var{n}
@arindex -cl@var{mm}@var{www}@var{n}
@cindex Date warning period modifier, @samp{l@var{mm}@var{www}@var{n}}
List dates starting yesterday or tomorrow (depending on the value given
in @w{@var{mm}@var{www}@var{n}}) and ending at @w{@var{n}'th @equiv{}
@samp{1@r{@dots{}}5@r{|}9}} weekday @var{dd} of month @var{mm} of
actual year; the warning level is same as @samp{-cy} option.

@itemize @bullet
@item
E.g.@: @samp{gcal -cl01mon3} displays a list of all fixed dates, which start
on the 3rd Monday in January and end on the 16th February.

@item
E.g.@: @samp{gcal -cl02fri9} displays a list of all fixed dates, which start
on the 18th February and end on the last Friday in February.
@end itemize

@item @samp{*d@var{n}@var{www}}
@arindex -*d@var{n}@var{www}
@arindex -c*d@var{n}@var{www}
@cindex Date warning period modifier, @samp{*d@var{n}@var{www}}
Single date of @w{@var{n}'th @equiv{} @samp{1@r{@dots{}}51@r{|}52@r{|}53@r{|}99}}
weekday @var{www} of actual year; the warning level is same as simple
@samp{-c} option.

@itemize @bullet
@item
E.g.@: @samp{gcal -c*d16sun} displays all fixed dates, which occur on the
16th Sunday of actual year.

@item
E.g.@: @samp{gcal -c*d52sun} displays all fixed dates, which occur on the
52nd Sunday of actual year.  If the actual year has no 52nd Sunday, no fixed
date warning messages are displayed and the program is terminated with error
code, see @ref{Error codes, , 126}.

@item
E.g.@: @samp{gcal -c*d53sun} displays all fixed dates, which occur on the
53rd Sunday of actual year.  If the actual year has no 53rd Sunday, no fixed
date warning messages are displayed and the program is terminated with error
code, see @ref{Error codes, , 126}.

@item
E.g.@: @samp{gcal -c*d99sun} displays all fixed dates, which occur on the
last Sunday (that's either the 51st, 52nd or 53rd Sunday) of actual year.
@end itemize

@item @samp{l*d@var{n}@var{www}}
@arindex -l*d@var{n}@var{www}
@arindex -cl*d@var{n}@var{www}
@cindex Date warning period modifier, @samp{l*d@var{n}@var{www}}
List dates starting yesterday or tomorrow (depending on the value given
in @var{n}) and ending at
@w{@var{n}'th @equiv{} @samp{1@r{@dots{}}51@r{|}52@r{|}53@r{|}99}}
weekday @var{www} of actual year; the warning level is same as @samp{-cy}
option.

@itemize @bullet
@item
E.g.@: @samp{gcal -cl*d16sun} displays a list of all fixed dates, which start
on the 18th February and end on the 16th Sunday of actual year.

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

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

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

@item @samp{*w@var{n}@r{[}@var{www}@r{]}}
@arindex -*w@var{n}@r{[}@var{www}@r{]}
@arindex -c*w@var{n}@r{[}@var{www}@r{]}
@cindex Date warning period modifier, @samp{*w@var{n}@r{[}@var{www}@r{]}}
Single date of weekday @var{www} of
@w{@var{n}'th @equiv{} @samp{0@r{|}1@r{@dots{}}52@r{|}53@r{|}99}}
@sc{iso}-week of actual year; the warning level is same as simple @samp{-c}
option. If no weekday @var{www} is given, then Monday is assumed for the
weekday.

@itemize @bullet
@item
E.g.@: @samp{gcal -c*w0sun} displays all fixed dates, which occur on
Sunday, which is located in the 52nd respectively 53rd @sc{iso}-week of
previous year.  In case such a Sunday doesn't exist, no fixed date warning
messages are displayed an the program is terminated with error code, see
@ref{Error codes, , 126}.

@item
E.g.@: @samp{gcal -c*w16sun} displays all fixed dates, which occur on
Sunday of the 16th @sc{iso}-week of actual year.

@item
E.g.@: @samp{gcal -c*w52sun} displays all fixed dates, which occur on
Sunday of the 52nd @sc{iso}-week of actual year.  If the actual year has no
Sunday of the 52nd @sc{iso}-week, no fixed date warning messages are displayed
and the program is terminated with error code, see @ref{Error codes, , 126}.

@item
E.g.@: @samp{gcal -c*w53sun} displays all fixed dates, which occur on
Sunday of the 53rd @sc{iso}-week of actual year.  If the actual year has no
Sunday of the 53rd @sc{iso}-week, no fixed date warning messages are displayed
and the program is terminated with error code, see @ref{Error codes, , 126}.

@item
E.g.@: @samp{gcal -c*w99sun} displays all fixed dates, which occur on
Sunday of the last @sc{iso}-week (that's either the 52nd or 53rd @sc{iso}-week)
of actual year.
@end itemize

@item @samp{l*w@var{n}@r{[}@var{www}@r{]}}
@arindex -l*w@var{n}@r{[}@var{www}@r{]}
@arindex -cl*w@var{n}@r{[}@var{www}@r{]}
@cindex Date warning period modifier, @samp{l*w@var{n}@r{[}@var{www}@r{]}}
List dates starting yesterday or tomorrow (depending on the value given
in @var{n}) and ending at weekday @var{www} of
@w{@var{n}'th @equiv{} @samp{0@r{|}1@r{@dots{}}52@r{|}53@r{|}99}}
@sc{iso}-week of actual year; the warning level is same as @samp{-cy} option.
If no weekday @var{www} is given, then Monday is assumed for the weekday.

@itemize @bullet
@item
E.g.@: @samp{gcal -cl*w0sun} displays a list of all fixed dates, which start
on Sunday, which is located in the 52nd respectively 53rd @sc{iso}-week of
previous year and end on 16th February.  In case such a Sunday doesn't exist,
no fixed date warning messages are displayed an the program is terminated with
error code, see @ref{Error codes, , 126}.

@item
E.g.@: @samp{gcal -cl*w16sun} displays a list of all fixed dates, which start
on the 18th February and end on Sunday of the 16th @sc{iso}-week of actual
year.

@item
E.g.@: @samp{gcal -cl*w52sun} displays a list of all fixed dates, which start
on the 18th February and end on Sunday of the 52nd @sc{iso}-week of actual
year.  If the actual year has no Sunday of the 52nd @sc{iso}-week, no fixed
date warning messages are displayed and the program is terminated with error
code, see @ref{Error codes, , 126}.

@item
E.g.@: @samp{gcal -cl*w53sun} displays a list of all fixed dates, which start
on the 18th February and end on Sunday of the 53rd @sc{iso}-week of actual
year.  If the actual year has no Sunday of the 53rd @sc{iso}-week, no fixed
date warning messages are displayed and the program is terminated with error
code, see @ref{Error codes, , 126}.

@item
E.g.@: @samp{gcal -cl*w99sun} displays a list of all fixed dates, which start
on the 18th February and end on Sunday of the last @sc{iso}-week (that's either
the 52nd or 53rd @sc{iso}-week) of actual year.
@end itemize

@item @samp{@@e@r{[[}+@r{|}-@r{]}@var{n}@r{]}}
@arindex -@@e@r{[[}+@r{|}-@r{]}@var{n}@r{]}
@arindex -c@@e@r{[[}+@r{|}-@r{]}@var{n}@r{]}
@cindex Date warning period modifier, @samp{@@e@r{[[}+@r{|}-@r{]}@var{n}@r{]}}
Single date of day @var{n} relative to the Easter Sunday's date of actual year;
the warning level is same as simple @samp{-c} option.

@itemize @bullet
@item
E.g.@: @samp{gcal -c@@e} displays all fixed dates, which occur
on the Easter Sunday's date.

@item
E.g.@: @samp{gcal -c@@e10} respectively @samp{gcal -c@@e+10} displays all
fixed dates, which occur 10 days after the Easter Sunday's date.

@item
E.g.@: @samp{gcal -c@@e-10} displays all fixed dates, which occur
10 days before the Easter Sunday's date.
@end itemize

@need 2000
@item @samp{l@@e@r{[[}+@r{|}-@r{]}@var{n}@r{]}}
@arindex -l@@e@r{[[}+@r{|}-@r{]}@var{n}@r{]}
@arindex -cl@@e@r{[[}+@r{|}-@r{]}@var{n}@r{]}
@cindex Date warning period modifier, @samp{l@@e@r{[[}+@r{|}-@r{]}@var{n}@r{]}}
List dates starting yesterday or tomorrow (depending on the value
given in @var{n}) and ending at @w{@var{n}'th} day relative to the Easter
Sunday's date of actual year; the warning level is same as @samp{-cy} option.

@itemize @bullet
@item
E.g.@: @samp{gcal -cl@@e} displays a list of all fixed dates, which start
on the 18th February and end on the Easter Sunday's date.

@item
E.g.@: @samp{gcal -cl@@e10} respectively @samp{gcal -cl@@e+10} displays a list
of all fixed dates, which start on the 18th February and end 10 days after the
Easter Sunday's date.

@item
E.g.@: @samp{gcal -cl@@e-10} displays a list of all fixed dates, which start
on the 18th February and end 10 days before the Easter Sunday's date.
@end itemize

@item @samp{@@e@r{[}+@r{|}-@r{]}@var{n}@var{www}}
@arindex -@@e@r{[}+@r{|}-@r{]}@var{n}@var{www}
@arindex -c@@e@r{[}+@r{|}-@r{]}@var{n}@var{www}
@cindex Date warning period modifier, @samp{@@e@r{[}+@r{|}-@r{]}@var{n}@var{www}}
Single date of @w{@var{n}'th} weekday @var{www} relative to the Easter Sunday's
date of actual year; the warning level is same as simple @samp{-c} option.

@itemize @bullet
@item
E.g.@: @samp{gcal -c@@e3fri} respectively @samp{gcal -c@@e+3fri} displays all
fixed dates, which occur on the 3rd Friday after the Easter Sunday's date.

@item
E.g.@: @samp{gcal -c@@e-3fri} displays all fixed dates, which occur
on the 3rd Friday before the Easter Sunday's date.
@end itemize

@need 1500
@item @samp{l@@e@r{[}+@r{|}-@r{]}@var{n}@var{www}}
@arindex -l@@e@r{[}+@r{|}-@r{]}@var{n}@var{www}
@arindex -cl@@e@r{[}+@r{|}-@r{]}@var{n}@var{www}
@cindex Date warning period modifier, @samp{l@@e@r{[}+@r{|}-@r{]}@var{n}@var{www}}
List dates starting yesterday or tomorrow (depending on the value
given in @var{n}) and ending at @w{@var{n}'th} weekday @var{www} relative to
the Easter Sunday's date of actual year; the warning level is same as @samp{-cy}
option.

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

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

@item @samp{@@@var{dvar}@r{[[}+@r{|}-@r{]}@var{n}@r{]}}
@arindex -@@@var{dvar}@r{[[}+@r{|}-@r{]}@var{n}@r{]}
@arindex -c@@@var{dvar}@r{[[}+@r{|}-@r{]}@var{n}@r{]}
@cindex Date warning period modifier, @samp{@@@var{dvar}@r{[[}+@r{|}-@r{]}@var{n}@r{]}}
Single date of day @var{n} relative to date variables date of actual year;
the warning level is same as simple @samp{-c} option.

@itemize @bullet
@item
E.g.@: @samp{gcal -v a=0422 -c@@a} displays all fixed dates, which occur
on the 22nd April.

@item
E.g.@: @samp{gcal -v a=0422 -c@@a10} respectively @samp{gcal -v a=0422 -c@@a+10}
displays all fixed dates, which occur 10 days after the 22nd April.

@item
E.g.@: @samp{gcal -v a=0422 -c@@a-10} displays all fixed dates, which occur
10 days before the 22nd April.
@end itemize

@need 2000
@item @samp{l@@@var{dvar}@r{[[}+@r{|}-@r{]}@var{n}@r{]}}
@arindex -l@@@var{dvar}@r{[[}+@r{|}-@r{]}@var{n}@r{]}
@arindex -cl@@@var{dvar}@r{[[}+@r{|}-@r{]}@var{n}@r{]}
@cindex Date warning period modifier, @samp{l@@@var{dvar}@r{[[}+@r{|}-@r{]}@var{n}@r{]}}
List dates starting yesterday or tomorrow (depending on the value
given in @var{n}) and ending at @w{@var{n}'th} day relative to date variables
date of actual year; the warning level is same as @samp{-cy} option.

@itemize @bullet
@item
E.g.@: @samp{gcal -v a=0422 -cl@@a} displays a list of all fixed dates, which
start on the 18th February and end on the 22nd April.

@item
E.g.@: @samp{gcal -v a=0422 -cl@@a10} respectively @samp{gcal -v a=0422 -cl@@a+10}
displays a list of all fixed dates, which start on the 18th February and end
10 days after the 22nd April.

@item
E.g.@: @samp{gcal -v a=0422 -cl@@a-10} displays a list of all fixed dates,
which start on the 18th February and end 10 days before the 22nd April.
@end itemize

@item @samp{@@@var{dvar}@r{[}+@r{|}-@r{]}@var{n}@var{www}}
@arindex -@@@var{dvar}@r{[}+@r{|}-@r{]}@var{n}@var{www}
@arindex -c@@@var{dvar}@r{[}+@r{|}-@r{]}@var{n}@var{www}
@cindex Date warning period modifier, @samp{@@@var{dvar}@r{[}+@r{|}-@r{]}@var{n}@var{www}}
Singe date of @w{@var{n}'th} weekday @var{www} relative to date variables date
of actual year; the warning level is same as simple @samp{-c} option.

@itemize @bullet
@item
E.g.@: @samp{gcal -v a=0122 -c@@a2sat} respectively @samp{gcal -v a=0122 -c@@a+2sat}
displays all fixed dates, which occur on the 2nd Saturday after the 22nd
January.

@item
E.g.@: @samp{gcal -v a=0122 -c@@a-2sat} displays all fixed dates, which occur
on the 2nd Saturday before the 22nd January.
@end itemize

@need 1500
@item @samp{l@@@var{dvar}@r{[}+@r{|}-@r{]}@var{n}@var{www}}
@arindex -l@@@var{dvar}@r{[}+@r{|}-@r{]}@var{n}@var{www}
@arindex -cl@@@var{dvar}@r{[}+@r{|}-@r{]}@var{n}@var{www}
@cindex Date warning period modifier, @samp{l@@@var{dvar}@r{[}+@r{|}-@r{]}@var{n}@var{www}}
List dates starting yesterday or tomorrow (depending on the value
given in @var{n}) and ending at @w{@var{n}'th} weekday @var{www} relative to
date variables date of actual year; the warning level is same as @samp{-cy}
option.

@itemize @bullet
@item
E.g.@: @samp{gcal -v a=0122 -cl@@a2sat} respectively @samp{gcal -v a=0122 -cl@@a+2sat}
displays a list of all fixed dates, which start on the 2nd Saturday after the
22nd January and end on the 16th February.

@item
E.g.@: @samp{gcal -v a=0122 -cl@@a-2sat} displays a list of all fixed dates,
which start on the 2nd Saturday before the 22nd January and end on the
16th February.
@end itemize

@item @samp{t@r{|}T}
@itemx @samp{--tomorrow} long-style option
@arindex -c@r{[}t@r{|}T@r{]}
@arindex -t
@arindex -ct
@arindex -T
@arindex -cT
@arindex --tomorrow
@cindex Date warning period modifier, @samp{t@r{|}T}
@cindex Date warning period long-style option, @samp{--tomorrow}
@cindex Fixed date warnings related to @emph{tomorrow}
@cindex Tomorrow warnings
List dates related to tomorrow.

@itemize @bullet
@item
E.g.@: @samp{gcal -ct} displays all fixed dates, which occur
on the 18th February (tomorrow).

@item
E.g.@: @samp{gcal -cdt} displays all fixed dates, which occur
on the 17th February (today) and on the 18th February (tomorrow).
@end itemize

@item @samp{w@r{|}W@r{[}+@r{|}-@r{]}}
@itemx @samp{--week} long-style option
@itemx @samp{--end-of-week} long-style option
@itemx @samp{--start-of-week} long-style option
@arindex -w
@arindex -w@r{[}+@r{|}-@r{]}@r{]}
@arindex -W
@arindex -W@r{[}+@r{|}-@r{]}@r{]}
@arindex -w@r{|}W@r{[}+@r{|}-@r{]}@r{]}
@arindex -c@r{[}w@r{|}W@r{[}+@r{|}-@r{]}@r{]}
@arindex --week
@arindex --end-of-week
@arindex --start-of-week
@cindex Date warning period modifier, @samp{w@r{|}W@r{[}+@r{|}-@r{]}}
@cindex Date warning period long-style option, @samp{--week}
@cindex Date warning period long-style option, @samp{--end-of-week}
@cindex Date warning period long-style option, @samp{--start-of-week}
@cindex Fixed date warnings related to the @emph{week}
@cindex Week warnings
Display week warnings
(@pxref{Calendar options, , @samp{--starting-day@r{[}=@var{argument}@r{]}}}).

@itemize @bullet
@item
@samp{w} or @samp{--week} long-style option@*
@arindex -w
@arindex -cw
@arindex --week
List dates between @emph{starting day} of current week
and last day of current week

@itemize @minus
@item
E.g.@: @samp{gcal -cw} displays all fixed dates, which occur
in the whole week the 17th February is part of.
@end itemize

@item
@samp{w+} or @samp{--end-of-week} long-style option@*
@arindex -w+
@arindex -cw+
@arindex --end-of-week
List dates between day after current day of current week and last day of
current week.

@itemize @minus
@item
E.g.@: @samp{gcal -cw+} displays all fixed dates, which start on the
18th February (tomorrow) and end on the last day of the week.

@item
E.g.@: @samp{gcal -cdw+} displays all fixed dates, which start on the
17th February (today) and end on the last day of the week.
@end itemize

@item
@samp{w-} or @samp{--start-of-week} long-style option@*
@arindex -w-
@arindex -cw-
@arindex --start-of-week
List dates between @emph{starting day} of current week
and day before current day of current week

@itemize @minus
@item
E.g.@: @samp{gcal -cw-} displays all fixed dates, which start on the
first day of the week and end on the 16th February (yesterday).

@item
E.g.@: @samp{gcal -cdw-} displays all fixed dates, which start on the
first day of the week and end on the 17th February (today).
@end itemize
@end itemize

@item @samp{m@r{|}M@r{[}+@r{|}-@r{]}}
@itemx @samp{--month} long-style option
@itemx @samp{--end-of-month} long-style option
@itemx @samp{--start-of-month} long-style option
@arindex -m
@arindex -m@r{[}+@r{|}-@r{]}@r{]}
@arindex -M
@arindex -M@r{[}+@r{|}-@r{]}@r{]}
@arindex -m@r{|}M@r{[}+@r{|}-@r{]}@r{]}
@arindex -c@r{[}m@r{|}M@r{[}+@r{|}-@r{]}@r{]}
@cindex Date warning period modifier, @samp{m@r{|}M@r{[}+@r{|}-@r{]}}
@cindex Date warning period long-style option, @samp{--month}
@cindex Date warning period long-style option, @samp{--end-of-month}
@cindex Date warning period long-style option, @samp{--start-of-month}
@cindex Fixed date warnings related to the @emph{month}
@cindex Month warnings
Display month warnings.

@itemize @bullet
@item
@samp{m} or @samp{--month} long-style option@*
@arindex -m
@arindex -cm
@arindex --month
List dates between first day of current month and last day of current month.

@itemize @minus
@item
E.g.@: @samp{gcal -cm} displays all fixed dates, which occur
in the whole month of February.
@end itemize

@item
@samp{m+} or @samp{--end-of-month} long-style option@*
@arindex -m+
@arindex -cm+
@arindex --end-of-month
List dates between day after current day of current month and last day of
current month.

@itemize @minus
@item
E.g.@: @samp{gcal -cm+} displays all fixed dates, which start on the
18th February (tomorrow) and end on the last day of the month February.

@item
E.g.@: @samp{gcal -cdm+} displays all fixed dates, which start on the
17th February (today) and end on the last day of the month February.
@end itemize

@need 1000
@item
@samp{m-} or @samp{--start-of-month} long-style option@*
@arindex -m-
@arindex -cm-
@arindex --start-of-month
List dates between first day of current month and day before current day
of current month.

@itemize @minus
@item
E.g.@: @samp{gcal -cm-} displays all fixed dates, which start on the
first day of the month February and end on the 16th February (yesterday).

@item
E.g.@: @samp{gcal -cdm-} displays all fixed dates, which start on the
first day of the month February and end on the 17th February (today).
@end itemize
@end itemize

@item @samp{y@r{|}Y@r{[}+@r{|}-@r{]}}
@itemx @samp{--year} long-style option
@itemx @samp{--end-of-year} long-style option
@itemx @samp{--start-of-year} long-stlye option
@arindex -y
@arindex -y@r{[}+@r{|}-@r{]}@r{]}
@arindex -Y
@arindex -Y@r{[}+@r{|}-@r{]}@r{]}
@arindex -y@r{|}Y@r{[}+@r{|}-@r{]}@r{]}
@arindex -c@r{[}y@r{|}Y@r{[}+@r{|}-@r{]}@r{]}
@cindex Date warning period modifier, @samp{y@r{|}Y@r{[}+@r{|}-@r{]}}
@cindex Date warning period long-style option, @samp{--year}
@cindex Date warning period long-style option, @samp{--end-of-year}
@cindex Date warning period long-style option, @samp{--start-of-year}
@cindex Fixed date warnings related to the @emph{year}
@cindex Year warnings
Display year warnings.

@itemize @bullet
@item
@samp{y} or @samp{--year} long-style option@*
@arindex -y
@arindex -cy
@arindex --year
List dates between first day of current year and last day of current year.

@itemize @minus
@item
E.g.@: @samp{gcal -cy} displays all fixed dates, which occur
in the whole year.
@end itemize

@item
@samp{y+} or @samp{--end-of-year} long-style option@*
@arindex -y+
@arindex -cy+
@arindex --end-of-year
List dates between day after current day of current year and last day of
current year.

@itemize @minus
@item
E.g.@: @samp{gcal -cy+} displays all fixed dates, which start on the
18th February (tomorrow) and end on the last day of the year.

@item
E.g.@: @samp{gcal -cdy+} displays all fixed dates, which start on the
17th February (today) and end on the last day of the year.
@end itemize

@item
@samp{y-} or @samp{--start-of-year} long-style option@*
@arindex -y-
@arindex -cy-
@arindex --start-of-year
List dates between first day of current year and day before current day
of current year.

@itemize @minus
@item
E.g.@: @samp{gcal -cy-} displays all fixed dates, which start on the
first day of the year and end on the 16th February (yesterday).

@item
E.g.@: @samp{gcal -cdy-} displays all fixed dates, which start on the
first day of the year and end on the 17th February (today).
@end itemize
@end itemize
@end table

@page
@node Response file, Actual date modifier, Options, Command line arguments
@subsection Response file
@cindex Response file, @samp{@@@var{file}}
@cindex @samp{@@@var{file}}
@cindex Option @samp{@@@var{file}}
@cindex @samp{@@@var{file}}, Option
@cindex Quotation of special characters
@arindex @@@var{file}

If a @samp{@@@var{file}} option is given in command line, a @dfn{response file}
@var{file} will be used, i.e.@: options and commands are preloaded from
that file.  A response file @var{file} may contain options and commands,
which are preloaded by Gcal, but @strong{no} reference to further response
files.  If such references to further response files are found, they are
ignored.  @xref{Global options, , @samp{--response-file=@var{name}}}, for
hints how to generate a response file automatically.

The searching scheme for a response file is the same as that for resource
files, except @strong{no} standard response file is respected.
@xref{Resource file, File searching mechanism}, for more details.  Multiple
response files may be given in the command line when Gcal is started and are
processed exactly in that order as given, i.e.@: strictly sequential.

@cindex Comment character, @samp{;}
@cindex @samp{;} comment character
Each option and command must be on a single line, i.e.@: separated by a
real @samp{\n} (newline) character.  A line beginning with a @samp{;}
(semicolon) character in the response file is treated as a remark and
will not be used by Gcal (@pxref{Comment line}).

Options must be defined before commands.  If a response file contains any
commands, then all further arguments after the @samp{@@@var{file}} option
of the command line are ignored.

@need 3000
@noindent
For example:

@enumerate
@item
Contents of response file @file{file}:

@example
@group
Line     Text
1        -j
2        -Cw
@var{EOF}

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

@expansion{} gcal -i -b 3 -j -Cw -s 3 1994
@end cartouche
@end group
@end example

@need 2000
@item
Contents of response file @file{file}:

@example
@group
Line     Text
1        -j
2        -Cw
3        may 1992
@var{EOF}

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

@expansion{} gcal -i -b 3 -j -Cw may
@end cartouche
@end group
@end example

@need 3000
@item
Contents of response file @file{file}:

@example
@group
Line     Text
1        -j
2        -Cw
3        may
4        1992
@var{EOF}

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

@expansion{} gcal -i -b 3 -j -Cw may 1992
@end cartouche
@end group
@end example
@end enumerate

@page
@node Actual date modifier, Commands, Response file, Command line arguments
@subsection Actual date modifier
@cindex Actual date modifier, @samp{%@var{date}}
@cindex @samp{%@var{date}}
@cindex Option @samp{%@var{date}}
@cindex @samp{%@var{date}}, Option
@arindex %@var{date}

It is allowed to use that date instead of the actual (system) date, which is
defined by the @samp{%@var{date}} option.  This means that fixed date warning
messages can be created for @strong{any} year and are like the warning messages
of the actual year.
@sp 2

@noindent
The date must be denoted in one of these formats:

@itemize @bullet
@item
@w{@code{@var{yyyy}@r{[}@var{mm}@r{[}@var{dd}@r{|}@var{www}@r{[}@var{n}@r{]]]}}}

@item
@w{@code{@var{yyyy}*d@r{|}w@var{n}@r{[}@var{www}@r{]}}}

@item
@w{@code{@var{yyyy}@@e@r{|}@var{dvar}@r{[[}+@r{|}-@r{]}@var{n}@r{[}@var{www}@r{]]}}}

@item
@w{@code{@var{month name}@r{[}@var{dd}@r{]}}}

@item
@w{@code{@var{weekday name}@r{[}@var{n}@r{]}}}

@item
@w{@var{dd}}
@end itemize
@sp 2

@noindent
Some examples to this:

@quotation
@strong{Please note:}@*
Following examples assume the current date is Wednesday,
the 17th February 1993 (19930217)!
@end quotation

@table @asis
@item The @code{@var{yyyy}@r{[}@var{mm}@r{[}@var{dd}@r{|}@var{www}@r{[}@var{n}@r{]]]}} format:

@itemize @bullet
@item
@samp{gcal %1994} @w{(@equiv{} @var{yyyy})}@*
The actual date is set to the date 17th February 1994
@w{@result{} 19940217.}

@need 1000
@item
@samp{gcal %1994Mar}

@item
@samp{gcal %19943}

@item
@samp{gcal %199403} @w{(@equiv{} @var{yyyy}@var{mm})}@*
The actual date is set to the date 17th March 1994
@w{@result{} 19940317.}

@item
@samp{gcal %1994Mar3}

@item
@samp{gcal %1994033}

@item
@samp{gcal %19940303} @w{(@equiv{} @var{yyyy}@var{mm}@var{dd})}@*
The actual date is set to the date 3rd March 1994
@w{@result{} 19940303.}

@item
@samp{gcal %1994Marth}

@item
@samp{gcal %199403th} @w{(@equiv{} @var{yyyy}@var{mm}@var{www})}@*
The actual date is set to the date 4th March 1994
@w{@result{} 19940304.}

@need 1000
@item
@samp{gcal %1994MarWed3}

@item
@samp{gcal %199403wed3} @w{(@equiv{} @var{yyyy}@var{mm}@var{www}@var{n})}@*
The actual date is set to the date 3rd Wednesday in March 1994
@w{(@var{n} @equiv{} @samp{1@r{@dots{}}5@r{|}9})} @w{@result{} 19940316.}

@item
@samp{gcal %0}

@item
@samp{gcal %00}

@item
@samp{gcal %000}

@item
@samp{gcal %0000} @w{(@equiv{} @var{yyyy})}@*
The actual date remains unchanged @w{@result{} 19930217.}

@item
@samp{gcal %0000Mar}

@item
@samp{gcal %00003}

@item
@samp{gcal %000003} @w{(@equiv{} @var{yyyy}@var{mm})}@*
The actual date is set to the date 17th March 1993
@w{@result{} 19930317.}

@item
@samp{gcal %0000Mar3}

@item
@samp{gcal %0000033}

@item
@samp{gcal %00000303} @w{(@equiv{} @var{yyyy}@var{mm}@var{dd})}@*
The actual date is set to the date 3rd March 1993
@w{@result{} 19930303.}

@need 1000
@item
@samp{gcal %0000MarThu}

@item
@samp{gcal %000003thu} @w{(@equiv{} @var{yyyy}@var{mm}@var{www})}@*
The actual date is set to the date 4th March 1993
@w{@result{} 19930304.}

@item
@samp{gcal %0000MarWed3}

@item
@samp{gcal %000003wed3} @w{(@equiv{} @var{yyyy}@var{mm}@var{www}@var{n})}@*
The actual date is set to the date 3rd Wednesday in March 1993
@w{(@var{n} @equiv{} @samp{1@r{@dots{}}5@r{|}9})} @w{@result{} 19930317.}
@end itemize

@need 1000
@item The @code{@var{yyyy}*d@r{|}w@var{n}@r{[}@var{www}@r{]}} format:

@itemize @bullet
@item
@samp{gcal %1994*d10} @w{(@equiv{} @code{@var{yyyy}*d@var{n}})}@*
The actual date is set to the date 10th absolute day in 1994
@w{(@var{n} @equiv{} @samp{1@r{@dots{}}365@r{|}366@r{|}999})}
@w{@result{} 19940110.}

@item
@samp{gcal %1994*d10sun} @w{(@equiv{} @code{@var{yyyy}*d@var{n}@var{www}})}@*
The actual date is set to the date 10th Sunday in 1994
@w{(@var{n} @equiv{} @samp{1@r{@dots{}}51@r{|}52@r{|}53@r{|}99})}
@w{@result{} 19940306.}

@item
@samp{gcal %0*d10} @w{(@equiv{} @code{@var{yyyy}*d@var{n}})}@*
The actual date is set to the date 10th absolute day in 1993
@w{@result{} 19930110.}

@item
@samp{gcal %0*d10sun} @w{(@equiv{} @code{@var{yyyy}*d@var{n}@var{www}})}@*
The actual date is set to the date 10th Sunday in 1993
@w{@result{} 19930307.}

@item
@samp{gcal %1994*w10} @w{(@equiv{} @code{@var{yyyy}*w@var{n}})}@*
The actual date is set to the date Monday of the 10th @sc{iso}-week in 1994@*
@w{(@var{n} @equiv{} @samp{0@r{|}1@r{@dots{}}52@r{|}53@r{|}99})}
@w{@result{} 19940307.}

@item
@samp{gcal %1994*w10sun} @w{(@equiv{} @code{@var{yyyy}*w@var{n}@var{www}})}@*
The actual date is set to the date Sunday of the 10th @sc{iso}-week in 1994
@w{@result{} 19940313.}

@item
@samp{gcal %0*w10} @w{(@equiv{} @code{@var{yyyy}*w@var{n}})}@*
The actual date is set to the date Monday of the 10th @sc{iso}-week in 1993
@w{@result{} 19930308.}

@item
@samp{gcal %0*w10sun} @w{(@equiv{} @code{@var{yyyy}*w@var{n}@var{www}})}@*
The actual date is set to the date Sunday of the 10th @sc{iso}-week in 1993
@w{@result{} 19930314.}
@end itemize

@need 1000
@item The @code{@var{yyyy}@@e@r{|}@var{dvar}@r{[[}+@r{|}-@r{]}@var{n}@r{[}@var{www}@r{]]}} format:

@itemize @bullet
@item
@samp{gcal %1994@@e} @w{(@equiv{} @code{@var{yyyy}@@e})}@*
The actual date is set to the date Easter Sunday 1994
@w{@result{} 19940403.}

@item
@samp{gcal %1994@@e10}

@item
@samp{gcal %1994@@e+10} @w{(@equiv{} @code{@var{yyyy}@@e@r{[}+@r{]}@var{n}})}@*
The actual date is set to the date 10 days after Easter Sunday 1994
@w{@result{} 19940413.}

@item
@samp{gcal %1994@@e-10} @w{(@equiv{} @code{@var{yyyy}@@e-@var{n}})}@*
The actual date is set to the date 10 days before Easter Sunday 1994
@w{@result{} 19940324.}

@need 1500
@item
@samp{gcal %0@@e}

@item
@samp{gcal %00@@e}

@item
@samp{gcal %000@@e}

@item
@samp{gcal %0000@@e} @w{(@equiv{} @code{@var{yyyy}@@e})}@*
The actual date is set to the date Easter Sunday 1993
@w{@result{} 19930411.}

@item
@samp{gcal %0@@e10}

@item
@samp{gcal %0@@e+10} @w{(@equiv{} @code{@var{yyyy}@@e@r{[}|@r{]}@var{n}})}@*
The actual date is set to the date 10 days after Easter Sunday 1993
@w{@result{} 19930421.}

@item
@samp{gcal %0@@e-10} @w{(@equiv{} @code{@var{yyyy}@@e-@var{n}})}@*
The actual date is set to the date 10 days before Easter Sunday 1993
@w{@result{} 19930401.}

@item
@samp{gcal %1994@@e3Wed}

@item
@samp{gcal %1994@@e+3Wed} @w{(@equiv{} @code{@var{yyyy}@@e@r{[}+@r{]}@var{n}@var{www}})}@*
The actual date is set to the date 3rd Wednesday after Easter Sunday 1994
@w{@result{} 19940420.}

@item
@samp{gcal %1994@@e-3wed} @w{(@equiv{} @code{@var{yyyy}@@e-@var{n}@var{www}})}@*
The actual date is set to the date 3rd Wednesday before Easter Sunday 1994
@w{@result{} 19940316.}

@item
@samp{gcal %0@@e3wed}

@item
@samp{gcal %0@@e+3wed} @w{(@equiv{} @code{@var{yyyy}@@e@r{[}+@r{]}@var{n}@var{www}})}@*
The actual date is set to the date 3rd Wednesday after Easter Sunday 1993
@w{@result{} 19930428.}

@item
@samp{gcal %0@@e-3we} @w{(@equiv{} @code{@var{yyyy}@@e-@var{n}@var{www}})}@*
The actual date is set to the date 3rd Wednesday before Easter Sunday 1993
@w{@result{} 19930324.}

@item
@samp{gcal -v a=0303 %1994@@a} @w{(@equiv{} @code{@var{yyyy}@@@var{dvar}})}@*
The actual date is set to the date 3rd March 1994
@w{@result{} 19940303.}

@item
@samp{gcal -v a=0303 %1994@@a10}

@item
@samp{gcal -v a=0303 %1994@@a+10} @w{(@equiv{} @code{@var{yyyy}@@@var{dvar}@r{[}+@r{]}@var{n}})}@*
The actual date is set to the date 10 days after 3rd March 1994
@w{@result{} 19940313.}

@item
@samp{gcal -v a=0303 %1994@@a-10} @w{(@equiv{} @code{@var{yyyy}@@@var{dvar}-@var{n}})}@*
The actual date is set to the date 10 days before 3rd March 1994
@w{@result{} 19940221.}

@item
@samp{gcal -v a=0303 %0@@a} @w{(@equiv{} @code{@var{yyyy}@@@var{dvar}})}@*
The actual date is set to the date 3rd March 1993
@w{@result{} 19930303.}

@item
@samp{gcal -v a=0303 %0@@a10}

@item
@samp{gcal -v a=0303 %0@@a+10} @w{(@equiv{} @code{@var{yyyy}@@@var{dvar}@r{[}+@r{]}@var{n}})}@*
The actual date is set to the date 10 days after 3rd March 1993
@w{@result{} 19930313.}

@item
@samp{gcal -v a=0303 %0@@a-10} @w{(@equiv{} @code{@var{yyyy}@@@var{dvar}-@var{n}})}@*
The actual date is set to the date 10 days before 3rd March 1993
@w{@result{} 19930221.}

@item
@samp{gcal -v a=0303 %1994@@a3wed}

@item
@samp{gcal -v a=0303 %1994@@a+3wed} @w{(@equiv{} @code{@var{yyyy}@@@var{dvar}@r{[}+@r{]}@var{n}@var{www}})}@*
The actual date is set to the date 3rd Wednesday after 3rd March 1994
@w{@result{} 19940323.}

@item
@samp{gcal -v a=0303 %1994@@a-3wed} @w{(@equiv{} @code{@var{yyyy}@@@var{dvar}-@var{n}@var{www}})}@*
The actual date is set to the date 3rd Wednesday before 3rd March 1994
@w{@result{} 19940216.}

@item
@samp{gcal -v a=0303 %0@@a3wed}

@item
@samp{gcal -v a=0303 %0@@a+3wed} @w{(@equiv{} @code{@var{yyyy}@@@var{dvar}@r{[}+@r{]}@var{n}@var{www}})}@*
The actual date is set to the date 3rd Wednesday after 3rd March 1993
@w{@result{} 19930324.}

@item
@samp{gcal -v a=0303 %0@@a-3wed} @w{(@equiv{} @code{@var{yyyy}@@@var{dvar}-@var{n}@var{www}})}@*
The actual date is set to the date 3rd Wednesday before 3rd March 1993
@w{@result{} 19930210.}
@end itemize

@item The @code{@var{month name}@r{[}@var{dd}@r{]}} format:

@itemize @bullet
@item
@samp{gcal %April} @w{(@equiv{} @var{month name})}@*
The actual date is set to the date 17th April 1993
@w{@result{} 19930417.}

@item
@samp{gcal %april3}

@item
@samp{gcal %april03} @w{(@equiv{} @var{month name} @var{dd})}@*
The actual date is set to the date 3rd April 1993
@w{@result{} 19930403.}
@end itemize

@need 1000
@item The @code{@var{weekday name}@r{[}@var{n}@r{]}} format:

@itemize @bullet
@item
@samp{gcal %Friday} @w{(@equiv{} @var{weekday name})}@*
The actual date is set to the date Friday of current week in February 1993
@w{@result{} 19930219.}

@need 1000
@item
@samp{gcal %Friday2}

@item
@samp{gcal %Friday02} @w{(@equiv{} @var{weekday name} @var{n})}@*
The actual date is set to the date 2nd Friday in February 1993
@w{(@var{n} @equiv{} @samp{1@r{@dots{}}5@r{|}9})} @w{@result{} 19930212.}
@end itemize

@item The @var{dd} format:

@itemize @bullet
@item
@samp{gcal %3}

@item
@samp{gcal %03} @w{(@equiv{} @var{dd})}@*
The actual date is set to the date 3rd February 1993
@w{@result{} 19930203.}
@end itemize
@end table

@page
@node Commands, , Actual date modifier, Command line arguments
@subsection Commands
@cindex Commands, overview of
@cindex Single Commands
@cindex Commands, single
@cindex Lists of commands
@cindex Command, lists of
@cindex Ranges of commands
@cindex Command, ranges of
@cindex 3-Month mode commands
@cindex Special 3-Month mode commands

@menu
* Single commands::        How to use a Single command.
* 3-Month mode commands::  How to use a 3-Month mode command.
* Lists of commands::      How to use a List of commands.
* Ranges of commands::     How to use a Range of commands.
@end menu

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

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

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

@sp 2

@cindex List of used separator characters
@cindex Separator characters, list of
@noindent
Here is a list of all ranges of commands, lists of commands and other command
separator characters:

@quotation
@enumerate
@item
The @samp{-} character is the @emph{range of months} separator.

@item
The @samp{,} character is the @emph{list of months} separator.

@item
The @samp{+} character is the @emph{range of years} separator.

@item
The @samp{;} character is the @emph{list of years} separator.

@item
The @samp{/} character is the @emph{month of year} separator.

@item
The @samp{:} character is the @emph{fiscal year} separator.
@end enumerate
@end quotation

@node Single commands, 3-Month mode commands, Commands, Commands
@subsubsection Single commands
@cindex Single Commands
@cindex Commands, single

@table @samp
@item @var{NOTHING}
@arindex Command, @var{NOTHING}
@cindex Command, @samp{@var{NOTHING}}
@cindex Month mode, single
@cindex Single month mode
@cindex Current month of current year
Current month of current year, called @dfn{single month mode}
in the further context.

@item @var{month name}
@arindex Command, @var{month name}
@cindex Command, @samp{@var{month name}}
@cindex Selected month mode
@cindex Month mode, selected
@cindex Selected month of current year
Selected month of current year, e.g.@::

@example
@group
gcal may
gcal OCTOBER
gcal ja
@end group
@end example

@need 1000
@item @var{yyyy}
@arindex Command, @var{yyyy}
@cindex Command, @samp{@var{yyyy}}
@cindex Single year mode
@cindex Year mode, single
@cindex Selected year
Selected year, called @dfn{single year mode} in the further context, e.g.@::

@example
gcal 1992
@end example

But there is an exception of this general rule.  If the specified year number
is less or equal twelve, Gcal assumes that a selected month of the current
year is wanted.  If you want to have a selected year less or equal twelve,
call Gcal like this

@example
gcal 1:6
@end example

or like this

@example
gcal 6+6
@end example

to get the year six A.C.

@need 1000
@item @var{mm} @var{yyyy}
@itemx @var{mm}/@var{yyyy}
@arindex Command, @var{mm} @var{yyyy}
@arindex Command, @var{mm}/@var{yyyy}
@cindex Command, @samp{@var{mm} @var{yyyy}}
@cindex Command, @samp{@var{mm}/@var{yyyy}}
@cindex Single month of selected year
Single month of selected year, e.g.@::

@example
@group
gcal 9 1992
gcal 9/1992
gcal Nov 1777
gcal Nov/1777
@end group
@end example

@item :
@arindex Command, :
@cindex Command, @samp{:}
@cindex Single fiscal year
@cindex Fiscal year, single
@cindex Implicit fiscal year
@cindex Fiscal year, implicit
Single fiscal year, starting at @emph{actual month} of @emph{actual year}
and ending at month @emph{actual month}-1 of @emph{actual year}+1, called
@dfn{implicit fiscal year} in the further context, e.g.@::

@example
gcal :
@end example

@item @var{mm}:
@arindex Command, @var{mm}:
@cindex Command, @samp{@var{mm}:}
@cindex Single fiscal year
@cindex Fiscal year, single
@cindex Explicit fiscal year
@cindex Fiscal year, explicit
Single fiscal year, starting at month @var{mm} of @emph{actual year} and
ending at month @var{mm}-1 of @emph{actual year}+1, called @dfn{explicit
fiscal year} in the further context, e.g.@::

@example
@group
gcal 6:
gcal feb:
gcal NOVEMBER:
@end group
@end example

@need 1000
@item :@var{yyyy}
@arindex Command, :@var{yyyy}
@cindex Command, @samp{:@var{yyyy}}
@cindex Single fiscal year
@cindex Fiscal year, single
@cindex Explicit fiscal year
@cindex Fiscal year, explicit
Single fiscal year, starting at @emph{actual month} of year @var{yyyy}
and ending at month @emph{actual month}-1 of year @var{yyyy}+1, called
@dfn{explicit fiscal year} too in the further context, e.g.@::

@example
gcal :1999
@end example

@item @var{mm}:@var{yyyy}
@arindex Command, @var{mm}:@var{yyyy}
@cindex Command, @samp{@var{mm}:@var{yyyy}}
@cindex Single fiscal year
@cindex Fiscal year, single
@cindex Explicit fiscal year
@cindex Fiscal year, explicit
Single fiscal year, starting at month @var{mm} of year @var{yyyy} and ending
at month @var{mm}-1 of year @var{yyyy}+1, called @dfn{explicit fiscal year}
too in the further context, e.g.@::

@example
@group
gcal 7:1999
gcal oct:1992
gcal February:1777
@end group
@end example
@end table

@need 1500
@node 3-Month mode commands, Lists of commands, Single commands, Commands
@subsubsection 3-Month mode commands
@cindex 3-Month mode commands
@cindex Special 3-Month mode commands

@table @samp
@item .
@arindex Command, .
@cindex Command, @samp{.}
@cindex Special 3-Month mode, @samp{.}
@cindex 3-Month mode command @samp{.}, special
Previous, actual and next month of current year, e.g.@::

@example
gcal .
@end example

@need 1000
@item . @var{yyyy}
@arindex Command, . @var{yyyy}
@cindex Command, @samp{. @var{yyyy}}
@cindex Special 3-Month mode, @samp{. @var{yyyy}}
@cindex 3-Month mode command @samp{. @var{yyyy}}, special
Previous, actual and next month of selected year, e.g.@::

@example
gcal . 1992
@end example

@need 1000
@item ..
@arindex Command, ..
@cindex Command, @samp{..}
@cindex Special 3-Month mode, @samp{..}
@cindex 3-Month mode command @samp{..}, special
Actual quarter of current year, e.g.@::

@example
gcal ..
@end example

@item .. @var{yyyy}
@arindex Command, .. @var{yyyy}
@cindex Command, @samp{.. @var{yyyy}}
@cindex Special 3-Month mode, @samp{.. @var{yyyy}}
@cindex 3-Month mode command @samp{.. @var{yyyy}}, special
Actual quarter of selected year, e.g.@::

@example
gcal .. 1992
@end example

@need 1000
@item .+
@arindex Command, .+
@cindex Command, @samp{.+}
@cindex Special 3-Month mode, @samp{.+}
@cindex 3-Month mode command @samp{.+}, special
Actual and next two months of current year, e.g.@::

@example
gcal .+
@end example

@need 1000
@item .+ @var{yyyy}
@arindex Command, .+ @var{yyyy}
@cindex Command, @samp{.+ @var{yyyy}}
@cindex Special 3-Month mode, @samp{.+ @var{yyyy}}
@cindex 3-Month mode command @samp{.+ @var{yyyy}}, special
Actual and next two months of selected year, e.g.@::

@example
gcal .+ 1992
@end example

@item .-
@arindex Command, .-
@cindex Command, @samp{.-}
@cindex Special 3-Month mode, @samp{.-}
@cindex 3-Month mode command @samp{.-}, special
Actual and previous two months of current year, e.g.@::

@example
gcal .-
@end example

@item .- @var{yyyy}
@arindex Command, .- @var{yyyy}
@cindex Command, @samp{.- @var{yyyy}}
@cindex Special 3-Month mode, @samp{.- @var{yyyy}}
@cindex 3-Month mode command @samp{.- @var{yyyy}}, special
Actual and previous two months of selected year, e.g.@::

@example
gcal .- 1992
@end example
@end table

@node Lists of commands, Ranges of commands, 3-Month mode commands, Commands
@subsubsection Lists of Commands
@cindex Commands, lists of
@cindex Lists of commands

@table @samp
@item @var{mm},@dots{},@var{mm}
@arindex Command, @var{mm},@dots{},@var{mm}
@cindex Command, @samp{@var{mm},@dots{},@var{mm}}
@cindex List of specified months in current year
@cindex Specified months in current year, list of
List of specified months in current year, e.g.@::

@example
@group
gcal 1,5,12
gcal 3,1,5,3
gcal june,9,jan
@end group
@end example

@need 1500
@item @var{mm}/@var{yyyy},@dots{},@var{mm}/@var{yyyy}
@arindex Command, @var{mm}/@var{yyyy},@dots{},@var{mm}/@var{yyyy}
@cindex Command, @samp{@var{mm}/@var{yyyy},@dots{},@var{mm}/@var{yyyy}}
@cindex List of months in specified year
@cindex Months in specified year, list of
List of months in specified year, e.g.@::

@example
@group
gcal 1/1992,5,12/2001
gcal june/1991,9/1801,jan
@end group
@end example

@item @var{mm},@dots{},@var{mm} @var{yyyy}
@arindex Command, @var{mm},@dots{},@var{mm} @var{yyyy}
@cindex Command, @samp{@var{mm},@dots{},@var{mm} @var{yyyy}}
@cindex List of specified months of selected year
@cindex Specified months of selected year, list of
List of specified months of selected year, e.g.@::

@example
@group
gcal 3,7 1999
gcal 1,dec,july 1777
@end group
@end example

@item @var{yyyy};@dots{};@var{yyyy}
@arindex Command, @var{yyyy};@dots{};@var{yyyy}
@cindex Command, @samp{@var{yyyy};@dots{};@var{yyyy}}
@cindex List of specified years
@cindex Specified years, list of
List of specified years, e.g.@::

@example
gcal 1992;1777;1899
@end example

@item @var{mm}:@var{yyyy};@dots{};@var{mm}:@var{yyyy}
@arindex Command, @var{mm}:@var{yyyy};@dots{};@var{mm}:@var{yyyy}
@cindex Command, @samp{@var{mm}:@var{yyyy};@dots{};@var{mm}:@var{yyyy}}
@cindex List of specified fiscal years
@cindex Specified fiscal years, list of
@cindex List of fiscal years
@cindex Fiscal years, list of
List of specified fiscal years, e.g.@::

@example
gcal 7:1999;8:1992;April:3
@end example
@end table

@need 1500
@noindent
@strong{Other valid lists:}

@table @samp
@item @var{mm},@var{mm}/@var{yyyy},@dots{}
@arindex Command, @var{mm},@var{mm}/@var{yyyy},@dots{}
@cindex Command, @samp{@var{mm},@var{mm}/@var{yyyy},@dots{}}
@cindex Mixed list of months
@cindex Months, mixed list of
Mixed list of months consisting of: @samp{@var{mm} @var{mm}/@var{yyyy}}

@example
gcal 6,8,3/1999,feb/3,january
@end example

@need 1500
@item @var{mm}:;@var{mm}:@var{yyyy};@dots{}
@arindex Command, @var{mm}:;@var{mm}:@var{yyyy};@dots{}
@cindex Command, @samp{@var{mm}:;@var{mm}:@var{yyyy};@dots{}}
@cindex Mixed list of fiscal years
@cindex Fiscal years, mixed list of
Mixed list of fiscal years of given / actual year consisting of:
@samp{@var{mm}: :@var{yyyy} @var{mm}:@var{yyyy} @var{yyyy}}

@example
gcal 3:;1994;february:1999;:1777;JAN:
@end example

@need 1000
@item @var{mm}:;@var{mm}:;@dots{}
@arindex Command, @var{mm}:;@var{mm}:;@dots{}
@cindex Command, @samp{@var{mm}:;@var{mm}:;@dots{}}
@cindex List of fiscal years of actual year
@cindex Fiscal years of actual year, list of
List of fiscal years of actual year consisting of: @samp{@var{mm}:}

@example
gcal 3:;august:;DEC:
@end example
@end table

@node Ranges of commands, , Lists of commands, Commands
@subsubsection Ranges of commands
@cindex Ranges of commands
@cindex Commands, ranges of

@table @samp
@item @var{mm}-@var{mm}
@arindex Command, @var{mm}-@var{mm}
@cindex Command, @samp{@var{mm}-@var{mm}}
@cindex Range of current months
@cindex Current months, range of
Range of current months, e.g.@::

@example
@group
gcal 3-7
gcal 11-8
gcal MAY-dec
gcal 12-aug
@end group
@end example

@item @var{mm}/@var{yyyy}-@var{mm}/@var{yyyy}
@arindex Command, @var{mm}/@var{yyyy}-@var{mm}/@var{yyyy}
@cindex Command, @samp{@var{mm}/@var{yyyy}-@var{mm}/@var{yyyy}}
@cindex Range of months of year
@cindex Months of year, range of
Range of months of year, e.g.@::

@example
@group
gcal 3/1991-july/1992
gcal dec/1994-3
gcal sep-dec/2000
@end group
@end example

@item @var{mm}-@var{mm} @var{yyyy}
@arindex Command, @var{mm}-@var{mm} @var{yyyy}
@cindex Command, @samp{@var{mm}-@var{mm} @var{yyyy}}
@cindex Range of specified months of selected year
@cindex Specified months of selected year, range of
Range of specified months of selected year, e.g.@::

@example
@group
gcal 3-7 1999
gcal nov-3 1777
gcal aug-dec 1992
@end group
@end example

@need 1000
@item @var{mm} @var{yyyy}-@var{yyyy}
@itemx @var{mm}/@var{yyyy}-@var{yyyy}
@arindex Command, @var{mm} @var{yyyy}-@var{yyyy}
@arindex Command, @var{mm}/@var{yyyy}-@var{yyyy}
@cindex Command, @samp{@var{mm} @var{yyyy}-@var{yyyy}}
@cindex Command, @samp{@var{mm}/@var{yyyy}-@var{yyyy}}
@cindex Range of specified month of selected years
@cindex Specified month of selected years, range of
Range of specified month of selected years, e.g.@::

@example
@group
gcal AUGUST 1494-1497
gcal 3/1993-1999
gcal nov/3-1777
@end group
@end example

@need 1500
@item @var{yyyy}+@var{yyyy}
@arindex Command, @var{yyyy}+@var{yyyy}
@cindex Command, @samp{@var{yyyy}+@var{yyyy}}
@cindex Range of specified years
@cindex Specified years, range of
Range of specified years, e.g.@::

@example
gcal 1992+1994
@end example

@item @var{mm}:@var{yyyy}+@var{mm}:@var{yyyy}
@arindex Command, @var{mm}:@var{yyyy}+@var{mm}:@var{yyyy}
@cindex Command, @samp{@var{mm}:@var{yyyy}+@var{mm}:@var{yyyy}}
@cindex Range of specified fiscal years
@cindex Specified fiscal years, range of
@cindex Range of fiscal years
@cindex Fiscal years, range of
Range of specified fiscal years, e.g.@::

@example
@group
gcal 7:1999+8:1992
gcal aug:1992+july:1999
@end group
@end example
@end table

@page
@node The GCAL environment variable, , Command line arguments, Invoking Gcal
@section The @code{GCAL} environment variable
@cindex Environment variable, @code{GCAL}
@cindex @code{GCAL} environment variable
@vindex GCAL
@vindex GCAL_OPT

The environment variable @code{GCAL} can hold a set of default options for
Gcal (@pxref{Environment variables, , GCAL}).  These options are interpreted
first at program start-up and some can be overwritten by explicit command
line arguments or values which are found in a response file option
@samp{@@@var{file}}.  @xref{Command line arguments}, and @ref{Response file}.

@noindent
@need 1000
For example:

@itemize @bullet
@item
for @strong{sh}:
@smallexample
GCAL="-i @@colour -b 3"; export GCAL
@end smallexample

@item
for @strong{csh}:
@smallexample
setenv GCAL "-i @@colour -b 3"
@end smallexample

@item
for @strong{MS-DOS}:
@smallexample
set GCAL=-i @@colour -b 3
@end smallexample
@end itemize
@sp 2

On Vax/VMS, the name of the environment variable is @w{@code{GCAL_OPT}}, to
avoid a conflict with the symbol @code{GCAL} set for invocation of the program.

@noindent
For example:

@itemize @bullet
@item
for @strong{VMS}:
@smallexample
define GCAL_OPT "-i @@colour -b 3"
@end smallexample
@end itemize

@node Eternal holidays, Fixed date warnings, Invoking Gcal, Top
@chapter Eternal holidays
@cindex Eternal holidays
@cindex Holiday list, eternal

@noindent
The @emph{eternal holiday list} is created only for dates after @sc{a.d.463}.@*
It can be displayed in different ways:
@sp 2

In case you start Gcal without an explicit (fiscal) date and the
@emph{eternal holiday list} argument
(@pxref{Calendar options, , @samp{--holiday-list@r{[}=long@r{|}short@r{]}}}),
e.g.@::

@example
@group
gcal --holiday-list
gcal -n
gcal -n :
@end group
@end example

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

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

@example
@group
gcal --holiday-list july
gcal -n july
gcal -n 7 1993
gcal -n 7/1993
@end group
@end example

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

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

@example
@group
gcal --holiday-list 1993
gcal -n 1993
gcal -n july:
gcal -n :1993
gcal -n 7:1993
@end group
@end example

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

In case you start Gcal with the @emph{eternal holiday list}
argument and a special 3-Month mode command
(@pxref{3-Month mode commands, @samp{. @var{yyyy}}}), e.g.@::

@example
@group
gcal --holiday-list .
gcal -n .
gcal -n ..
gcal -n .+
gcal -n .-
@end group
@end example

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

In case you start Gcal with the @emph{eternal holiday list} argument and
a @emph{list} or @emph{range} of commands, it produces the according series
of eternal holiday lists.  @xref{Lists of commands,
@samp{@var{mm},@dots{},@var{mm}}}, and @ref{Ranges of commands,
@samp{@var{mm}-@var{mm}}}, for more details.

@node Fixed date warnings, Todays calendar, Eternal holidays, Top
@chapter Fixed date warnings
@cindex Fixed date warnings

@menu
* Resource file::           How to use a Resource file.
* Resource file examples::  Examples of Resource file entries.
@end menu

This chapter describes how to use the @emph{fixed date warning} feature
of Gcal.  For that purpose, you may create a Gcal resource file for
showing fixed dates/appointments (@pxref{Resource file}).

Each time you execute Gcal in simple single month mode, i.e.@: no explicit
month, year or fiscal year is given in the command line, but the @emph{fixed
date warning} argument, e.g.@::

@example
@group
gcal --list-of-fixed-dates
gcal -c
@end group
@end example

@noindent
it checks the resource file for dates and processes those that refer to the
actual (@equiv{}todays) date.  Then Gcal displays all fixed date warnings
found in the resource file, that refer to the actual day (week/month/year)
of the actual year without a leading calendar.

@noindent
Some more examples:

@example
@group
gcal -ce
gcal -cw-
gcal -c-m
gcal -c-y-
gcal -jcb -c-et
gcal -cey-
gcal -jc -cey
@end group
@end example
@sp 2

@noindent
The fixed date warnings can be displayed in different ways:

In case you start Gcal with the @emph{fixed date warning} argument and/or
a month and/or an explicit year or fiscal year; respectively with the special
3-Month mode command, e.g.@::

@example
@group
gcal -c july
gcal -ce 7 1994
gcal -c-y 7/1994
gcal -c 7:1993
gcal -c 1993
gcal -c .
gcal -c .+
@end group
@end example

@noindent
Gcal displays a (three) month / year calendar of the specified respectively
actual month / year and trailing those fixed date warnings found in the
resource file, that refer to the given period; the warning level is same as
@samp{-cy} option if the warning period refers to a year or fiscal year or to
a three month period respectively is same as @samp{-cm} option if the warning
period refers to a month.

@need 1500
In case you start Gcal without an explicit date and the @emph{fixed date
warning} argument @strong{in connection with} the @emph{eternal holiday list}
argument, e.g.@::

@example
@group
gcal -c -n
gcal -Cm -n
gcal -Cl1224 -n
gcal -cl3+ -n
@end group
@end example

@noindent
then Gcal displays all fixed date warnings found in the resource file, that
refer to the requested period and trailing all holidays of the eternal holiday
list that refer to the whole actual year without a leading calendar.  For more
details how to use an @emph{eternal holiday list}, see @ref{Eternal holidays}.

@sp 2

@noindent
@strong{Annotation to previous examples:}

In case an additional @emph{standard/special calendar format} argument
or an additional @emph{starting day of week} argument (except the
@w{@samp{--starting-day=today}} respectively the
@w{@samp{--starting-day=0}} option) is found in the command line, e.g.@::

@example
@group
gcal -c -n -i
gcal -c -i-
gcal -n -i- :
gcal -n -s Sunday
@end group
@end example

@noindent
Gcal displays a leading month, year or fiscal year calendar before all other
lists.  @xref{Calendar options, , @samp{--type=special@r{|}standard}}, and
@ref{Calendar options, , @samp{--starting-day@r{[}=@var{argument}@r{]}}},
for more information.

Each time you execute Gcal in simple single year mode, i.e.@: no explicit
month, year or fiscal year is given in the command line, but the @emph{fixed
date warning} argument (with optional modifiers) and the @emph{number of
blocks} argument (@pxref{Calendar options, , @samp{--blocks=@var{number}}}),
e.g.@::

@example
@group
gcal -c --blocks=3
gcal -C-em -b 3
gcal -c-t -b 6 -jc
@end group
@end example

@noindent
it checks the resource file for dates and processes those that refer to the
actual (@equiv{}todays) date!  Gcal displays a leading year calendar and
all fixed date warnings, found in the resource file, that refer to the
actual day (week/month/year) of the actual year.

@sp 2

You can list fixed date warnings of past, present or future month/years, too.
This can be done on the one hand, if you use the @samp{%@var{date}} option in
the fashion you require (@pxref{Actual date modifier}), and on the other hand,
if a command respectively a @emph{list} or @emph{range} of commands is used.

@need 1500
@noindent
For example:

@table @samp
@item gcal -c -n- 1993
Lists all fixed dates of entire 1993 in ascending order, and the eternal
holiday list of entire 1993 in descending order; the warning level is same as
@samp{-cy} option.

@item gcal -c- july:1993
Lists all fixed dates related to fiscal year @minus{} starting in July 1993
and ending in June 1994 @minus{} in descending order; the warning level is
same as @samp{-cy} option.

@item gcal -ce july 1993
Lists all fixed dates related to July 1993 inclusive all eternal holidays
merged into this list in ascending order; the warning level is same as
@samp{-cm} option.

@item gcal -c-e -n 1993+1996
Lists all fixed dates related to entire 1993, 1994, 1995 and 1996
(series of years) inclusive all eternal holidays merged into this list
in descending order, and the eternal holiday list related to all above
years in ascending order; the warning level is same as @samp{-cy} option.
@end table

@page
@node Resource file, Resource file examples, Fixed date warnings, Fixed date warnings
@section Resource file
@cindex .gcalrc resource file
@cindex Resource file, .gcalrc
@cindex Resource file, using
@cindex Resource file, name of
@cindex Resource file, searching mechanism
@cindex Resource file, standard
@cindex Resource file, additional
@cindex Resource file, loading
@cindex File searching mechanism
@cindex Searching resource file

@menu
* Structure of resource file::    How to write a Resource file.
* Date part of a line::           How to write the Date part.
* Further date part attributes::  What are Further date part attributes?
* Text part of a line::           How to write the Text part.
* Comment line::                  What is a Comment line?
* Include directives::            What are Include directives.
* Special macro texts::           What is a Special macro text.
* Date variables::                How Date variables can be used.
* Text variables::                How Text variables can be used.
@end menu

This sections describes how to use a @dfn{resource file}, which contains
fixed dates and appointments.  The name of the standard resource file is
@file{~/.gcalrc} @footnote{On @w{MS-DOS}, OS/2 and some other operating systems,
the name of the @emph{standard} resource file is @file{~/gcalrc}.}.

@noindent
Gcal uses a special file searching mechanism:

@cindex Actual directory
@cindex Directory, actual
@cindex Environment variable, @code{HOME}
@cindex @code{HOME} environment variable
@vindex HOME
@enumerate
@item
The Gcal program expects the standard resource file that directory, which
is referenced in the environment variable @code{HOME}.  If no @code{HOME}
environment variable is defined and set, Gcal omits this step.
@xref{Environment variables, , HOME}.

@need 1500
@cindex Environment variable, @code{GCALPATH}
@cindex @code{GCALPATH} environment variable
@vindex GCALPATH
@item
If the above action fails, Gcal scans the directories, which
are referenced in the environment variable @code{GCALPATH}
(@pxref{Environment variables, , GCALPATH}) for the standard resource file.
The @code{GCALPATH} environment variable contains a (@samp{:}) @footnote{On
@w{MS-DOS}, OS/2 and some other operating systems, another character will
be used, e.g.@: @samp{;} on @w{MS-DOS} and OS/2.} colon-separated list of
directories.  If no such environment variable is defined and set, Gcal
omits this step.

@cindex Environment variable, @code{GCAL_USR_DATADIR}
@cindex @code{GCAL_USR_DATADIR} environment variable
@vindex GCAL_USR_DATADIR
@item
If the above action fails, Gcal inspects the @emph{user data} directory
(normally @w{@file{$HOME/share/gcal}}) to find the standard resource
file.  This directory is a directory relative to the @code{HOME} directory.
If an environment variable @w{@code{GCAL_USR_DATADIR}} is set, Gcal appends
the contents of this environment variable to the contents of the @code{HOME}
environment variable and tries to use that directory first instead of using
the burned-in default name of that directory
(@pxref{Environment variables, , GCAL_USR_DATADIR}).  If no @code{HOME}
environment variable is defined and set, Gcal omits this step.

@cindex Environment variable, @code{GCAL_SYS_DATADIR}
@cindex @code{GCAL_SYS_DATADIR} environment variable
@vindex GCAL_SYS_DATADIR
@item
If all above actions fail, Gcal inspects the @emph{system data} directory
(normally @w{@file{/usr/local/share/gcal}} or @w{@file{$(prefix)/share/gcal}})
to find the standard resource file.  This directory is a directory
absolute the @emph{root}/@emph{$(prefix)} directory.  If an environment
variable @w{@code{GCAL_SYS_DATADIR}} is set, Gcal tries to use that directory
first instead of using the burned-in default name of that directory
(@pxref{Environment variables, , GCAL_SYS_DATADIR}).
@end enumerate

If the standard resource file is not found during steps 1@dots{}4 of the file
searching mechanism, no fixed date warnings will be created!

If a @w{@samp{-f@r{|}F @var{name}@r{[}+@dots{}@r{]}}} respectively
@w{@samp{--resource-file=@var{name}}} command line argument is given, a file
@var{name} will be used for the resource file instead of the standard resource
file.  @xref{Date warning options, , @samp{--resource-file=@var{name}}}.

@page
@cindex Extended file name
@cindex File name, extended
An @dfn{extended file name} contains one ore more @samp{/} @footnote{Operating
systems like @w{MS-DOS} or OS/2 use the @samp{\} (Backslash) character for
separating a directory from a file name.} (slash) characters and denotes a file,
which fixed access path either starts from the root directory, like
@samp{/foo/bar/file}, or from the actual directory, like @samp{./bar/file} or
@samp{../bar/file}.  If @var{name} is an extended file name:

@quotation
In case file @var{name} is found, Gcal will use it.@*
In case file @var{name} is not found, Gcal will not use it.
@end quotation

@sp 2

@cindex Simple file name
@cindex File name, simple
A @dfn{simple file name} does denote a file, which access path doesn't
either starts from the root directory or from the actual directory, like
@samp{file} or @samp{bar/file}.  If @var{name} is a simple file name:

@quotation
Gcal tries to find this file @var{name} using the previously explained
file searching mechanism.
@end quotation

@page
@node Structure of resource file, Date part of a line, Resource file, Resource file
@subsection Structure of resource file
@cindex Structure of resource file
@cindex Resource file, structure
@cindex Resource file, two parts of a line
@cindex Separator character, whitespace
@cindex Whitespace separator character
@cindex List of whitespace character
@cindex Resource file, limitations
@cindex Limitations in a resource file

First of all, a Gcal resource file is a plain @sc{ascii} text file.  This text
file may be created by any text editor or by redirecting the @emph{standard
output channel} to a file, e.g.@::

@cindex Redirection of standard output, appending to file
@example
@cartouche
$ echo '19930217 Text'>> resource-file @key{RET}
@end cartouche
@end example

A special but simple line structure is required so Gcal is able to interpret
its contents.  Each fixed date warning entry in a resource file must be
splitted into two parts, namely a @emph{date part} and an optional @emph{text
part}, which @strong{must} be separated by @strong{one} @dfn{whitespace}
character (Tab, Space, Form-Feed @dots{}) minimum.  It's not necessary to
give a whitespace separator character if no @emph{text part} is specified.

@cindex Redirection of standard output
A line must always end with a @samp{\n} (newline) character, except it's the
last line of a resource file.  The maximum length of a line is limited to
@value{GCAL-RCL} @footnote{Normally, this is for example equivalent to a value
of @w{@t{32,767}} @equiv{} @w{@t{(2^15)-1}} on a @w{16-Bit} machine
architecture; to a value of @w{@t{2,147,483,648}} @equiv{} @w{@t{(2^31)-1}}
on a @w{32-Bit} machine architecture etc.} characters.  A newline character is
automatically appended to the line if the @emph{standard output channel} is
directed to a file.  A newline character is appended to the typed line in a
text editor window if it is completed by pressing the @key{RET} key.  In case
the used text editor doesn't generate the newline character in this way, it
should be set to this mode of operation, otherwise this text editor is useless
for creating Gcal resource files.

@sp 2

@noindent
The line structure of fixed date warning entries is:

@example
@var{date part} @r{[} @emph{whitespace} @var{text part} @r{]} @emph{newline}
@end example

@noindent
or more concrete, e.g.@::

@example
@var{yyyy}@r{[}@var{mm}@r{[}@var{dd}@r{|}@var{www}@r{[}@var{n}@r{]]]} @r{[} @emph{whitespace} @var{text} @r{]} @emph{newline}
@end example

@noindent
or much more concrete, e.g.@::

@example
19940217 Hi, I'm the text!
@end example

@sp 2

@noindent
Besides fixed date warning entries, a resource file may contain further
entries like:

@noindent
Include directives@dots{}

@example
#include <@var{file name}>
#include "@var{file name}"
@end example

@need 1000
@noindent
Date variable assignments respectively operations@dots{}

@example
@group
@var{dvar}=@var{NOTHING}
@var{dvar}=@var{mm}@var{dd}
@var{dvar}=@var{mm}@var{www}@var{n}
@var{dvar}=*d@var{n}@r{[}@var{www}@r{]}
@var{dvar}=*w@var{n}@r{[}@var{www}@r{]}
@var{dvar}=@var{dvar}@r{[[}+@r{|}-@r{]}@var{n}@r{[}@var{www}@r{]]}
@var{dvar}++
@var{dvar}--
@var{dvar}+=@var{n}@r{[}@var{www}@r{]}
@var{dvar}-=@var{n}@r{[}@var{www}@r{]}
@end group
@end example

@noindent
Text variable assignments@dots{}

@example
@var{tvar}=@r{[}@var{text}@r{]}
@end example

@noindent
Text variable references@dots{}

@example
@var{tvar}
@end example

Text variable references in the beginning of a Gcal resource file line
may only be used if it is ensured that they are expanded to a valid Gcal
resource file line.

@page
@node Date part of a line, Further date part attributes, Structure of resource file, Resource file
@subsection Date part of a line
@cindex Date part of a line
@cindex Resource file, date part

The structure of a @dfn{date part} @minus{} which gives Gcal the information
at which date a fixed date happens @minus{} of a line in the resource
file is

@noindent
@w{@strong{Either}: @samp{@var{yyyy}@r{[}@var{mm}@r{[}@var{dd}@r{|}@var{www}@r{[}@var{n}@r{]]]}}}

@quotation
@table @samp
@item @var{yyyy}
(4 digits), is the year including the century (range 0000@dots{}9999).  Leading
zeroes are required in case given year is less than 1000 and other components
of the date part are trailing the year.

@item @var{mm}
(2 digits or 3 characters), is the month (range 00@dots{}12 or 99, respectively
Jan, Feb@dots{}).  A given 99 for the month means the last month of the year
(@equiv{} December).  Leading zeroes are required in case given month is less
than 10 and other components of the date part are trailing the month.

@item @var{dd}
(2 digits), is the day (range 00@dots{}31 or 99).  A given 99 for the day means
the last day of the month.  Leading zeroes are required in case given day is
less than 10 and other components of the date part are trailing the day.

@item @var{www}
(2@dots{}3 characters), is a short weekday name (range Mon@dots{}Sun).

@item @var{n}
(1 digit), is the @w{@var{n}'th} weekday @var{www} of month
(range 1@dots{}5 or 9).

@itemize @bullet
@item
@var{n} @equiv{} 1@dots{}5@*
@w{@var{n}'th} weekday @var{www} of month.

@item
@var{n} @equiv{} 9@*
Last weekday @var{www} of month.
@end itemize
@end table
@end quotation

@noindent
@w{@strong{Or}: @samp{@var{yyyy}*d@r{|}w@var{n}@r{[}@var{www}@r{]}}}

@quotation
@table @samp
@item @var{yyyy}
(4 digits), is the year including the century (range 0000@dots{}9999).  Leading
zeroes are required in case given year is less than 1000 and other components
of the date part are trailing the year.

@item *d
(2 characters), is the reference to an ordinary date.

@item *w
@cindex @sc{iso}-8601:1988
(2 characters), is the reference to a date of an @sc{iso}-8601:1988 week.

@item @var{n}
(1@dots{}3 digits), is the value in days or in weeks, the fixed date occurs.
A given 99 in connection with a short weekday name means the last weekday
@var{www} of the year.  A given 999 in connection with @samp{*d} means the
last day of a year, i.e.@: the 31st December.  If the computed date doesn't
occur in year, i.e.@: exceeds the year bounds, the fixed date warning message
is suppressed.

@item @var{www}
(2@dots{}3 characters), is a short weekday name (range Mon@dots{}Sun).
@end table
@end quotation

@need 1000
@noindent
@w{@strong{Or}: @samp{@var{yyyy}@@e@r{|}@var{dvar}@r{[[}+@r{|}-@r{]}@var{n}@r{]}}}

@quotation
@table @samp
@item @var{yyyy}
(4 digits), is the year including the century (range 0000@dots{}9999).  Leading
zeroes are required in case given year is less than 1000 and other components
of the date part are trailing the year.

@item @@e
(2 characters), is the reference to the Easter Sunday's date.

@item @@@var{dvar}
(2 characters), is the reference to a date variable.

@item @r{[}+@r{|}-@r{]}@var{n}
(1@dots{}4 alphanumeric characters), is the optional displacement value in
days, the fixed date occurs relative to the Easter Sunday's date or date
variables date.  A given -999 means the first day of a year, i.e.@: the 1st
January.  A given +999 or 999 means the last day of a year, i.e.@: the 31st
December.  If the computed date doesn't occur in year, i.e.@: exceeds the year
bounds, the fixed date warning message is suppressed.
@end table
@end quotation

@noindent
@w{@strong{Or}: @samp{@var{yyyy}@@e@r{|}@var{dvar}@r{[}+@r{|}-@r{]}@var{n}@var{www}}}

@quotation
@table @samp
@item @var{yyyy}
(4 digits), is the year including the century (range 0000@dots{}9999).  Leading
zeroes are required in case given year is less than 1000 and other components
of the date part are trailing the year.

@item @@e
(2 characters), is the reference to the Easter Sunday's date.

@item @@@var{dvar}
(2 characters), is the reference to a date variable.

@item @r{[}+@r{|}-@r{]}@var{n}@var{www}
(3@dots{}7 alphanumeric characters), is the optional displacement value in
weekdays, the fixed date occurs relative to the Easter Sunday's date or date
variables date.  A given -99 means the first weekday @var{www} of the year.
A given +99 or 99 means the last weekday @var{www} of the year.  If the
computed date doesn't occur in year, i.e.@: exceeds the year bounds, the
fixed date warning message is suppressed.
@end table
@end quotation

@need 2000
@noindent
@strong{Please note:}

@itemize @bullet
@item
If @var{yyyy} is specified as 0000:@*
The month and day are assumed to be annual events and the @emph{text part} will
be displayed for any year.

@item
If @var{mm} is not given or specified as 00:@*
The day is assumed to be a monthly event for the specified year and the
@emph{text part} will be displayed for any month.

@item
If @var{dd} is not given or specified as 00:@*
Each day is assumed to be a daily event for the specified year and month and
the @emph{text part} will be displayed for any day.

@item
If @var{www} is specified as a short (2@dots{}3 characters) weekday name,
e.g.@: @samp{Mon, Tue@dots{}}:@*
The given weekday name is assumed to be a weekly event for the specified year
and month and the @emph{text part} will be displayed for any week.
@end itemize

@page
@node Further date part attributes, Text part of a line, Date part of a line, Resource file
@subsection Further date part attributes
@cindex Further date part attributes

@menu
* Lists of days::              How Lists of days can be used.
* Ranges of days::             How Ranges of days can be used.
* Repetition factor of days::  How to use such a factor.
* Appearance factor of days::  How to use such a factor.
@end menu

The date part of a Gcal resource file may be provided with further attributes,
which are either specifications of lists of days or ranges of days, which
provide the information at which date a fixed date happens.  More further
attributes are the repetition factor as well as the appearance factor.

@noindent
All date parts of a Gcal resource file, which are structured as follows, may
be provided generally with further attributes:

@itemize @bullet
@item
@w{@samp{@var{yyyy}@var{mm}@dots{}}}

@item
@w{@samp{@var{yyyy}*d@r{|}w@dots{}}}

@item
@w{@samp{@var{yyyy}@@e@r{|}@var{dvar}@dots{}}}
@end itemize

@cindex Fiscal year, limitations
@cindex Limitations of use of fiscal years
@cindex 3-Month mode, limitations
@cindex Limitations of use of 3-Month modes
@noindent
@strong{Attention:}@*
If the date part is supplied with further attributes and the year of the fixed
date is not given in a concrete manner, i.e.@: the year @samp{@var{yyyy}} is
set to zero, such kinds of fixed dates are @strong{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 @strong{fiscal years}.

@node Lists of days, Ranges of days, Further date part attributes , Further date part attributes
@subsubsection Lists of days
@cindex Lists of days
@cindex @samp{,} separator character of lists of days
@cindex Separator character of lists of days, @samp{,}

A list of days is specified by a @samp{,} separator character; it must contain
two elements minimum and may have any number of elements.  A single element of
the list may not be set to a zero value and be unconcrete therefore, which
wouldn't make any sense in this coherence.

A list of days is used to define recurrent fixed dates and to use only one line
in the resource file for them, instead of using several lines in a resource
file needed for defining these recurrent fixed dates separately.  Assuming
a fixed date shall always occur on the 1st and the 15th day in every month
of the year 1996, e.g.@: @samp{Tax returns}, one solution would be on the
one hand a fixed date entry in the resource file for the 1st of the month
and another entry for the 15th of the month, which would be a total of two
entries in the resource file for such a fixed date.

On the other hand, this expense can be reduced to a total of only one entry
in the resource file by using a list of days, which is likewise valid for the
1st and the 15th day in every month, that is

@example
19960001,15 Tax returns
@end example

@cindex Valid date parts of lists of days
@cindex Lists of days, valid date parts of
The use of lists of days in the date part is permitted as follows:

@itemize @bullet
@item
@w{@samp{@var{yyyy}@var{mm}@var{dd}@r{|}@var{www}@r{|}@var{www}@var{n},@r{[}@var{mm}@r{]}@var{dd}@r{|}@r{[}@var{mm}@r{]}@var{www}@r{|[}@var{mm}@r{]}@var{www}@var{n} @dots{}}}

@item
@w{@samp{@var{yyyy}*d@r{|}w@var{n}@r{|}@var{n}@var{www},@var{n}@r{|}@var{n}@var{www} @dots{}}}

@item
@w{@samp{@var{yyyy}@@e@r{|}@var{dvar},@r{|[}+@r{|}-@r{]}@var{n}@r{[}@var{www}@r{]},@r{[}+@r{|}-@r{]}@var{n}@r{[}@var{www}@r{]} @dots{}}}
@end itemize

@need 1000
@cindex Examples to lists of days
@cindex Lists of days, examples to
Some examples to this:

@table @samp
@item 000001fr3,12,99,mon,apr14,993,julfri3,08fr
In every year in January: on the 3rd Friday, on the 12th, on the last day
of the month and on every Monday.  And in every year: on the 14th April,
on the 3rd December, on the 3rd Friday in July and on every Friday in August.

@item 199600mon,fr,12
In the year 1996 in every month: on every Monday, on every Friday and on
the 12th.

@item 0*d1,1fr,999,17mo
In every year: on the first day of the year, on the 1st Friday of the year,
on the last day of the year and on the 17th Monday of the year.

@item 1996*w1fr,1,17mo,99fr
In the year 1996: on Friday of the 1st @sc{iso}-week, on Monday of the first
@sc{iso}-week, on Monday of the 17th @sc{iso}-week and on Friday of the last
@sc{iso}-week.

@item 0@@a,+1,-3,5,+4fr,2fr,-10sa
In every year: on the date of the date variable @var{a}, one day after the
date of @var{a}, three days before the date of @var{a}, five days after the
date of @var{a}, four Fridays after the date of @var{a}, two Fridays after
the date of @var{a} and ten Saturdays before the date of @var{a}.

@item 1996@@e+1,-3,5,+4fr,2fr,-10sa
In the year 1996: one day after the Easter Sunday's date, three days before
the Easter Sunday's date, five days after the Easter Sunday's date, four
Fridays after the Easter Sunday's date, two Fridays after the Easter Sunday's
date and ten Saturdays before the Easter Sunday's date.
@end table

@node Ranges of days, Repetition factor of days, Lists of days, Further date part attributes
@subsubsection Ranges of days
@cindex Ranges of days
@cindex @samp{#} separator character of ranges of days
@cindex Separator character of ranges of days, @samp{#}

A range of days is specified by a @samp{#} separator character and must consist
of two elements, namely the starting day and the final day.  The starting day
and likewise the final day of the range may not be set to a zero value and be
unconcrete therefore, which wouldn't make any sense in this coherence.

A range of days just as a list of days is used to define recurrent fixed dates
and to use only one line in the resource file for them, instead of using
several lines in a resource file needed for defining these recurrent fixed
dates separately.  Assuming a fixed date shall always occur during the 1st
and the 15th day (inclusive) in every month of the year 1996, e.g.@:
@samp{Inside work}, one solution would be on the one hand a fixed date entry
in the resource file for the 1st of the month, another one for the 2nd of
the month until the 15th of the month, which would be a total of 15 entries
in the resource file for such a fixed date (apart from the possibility, that
a list of days can be used in such a case).

On the other hand, this expense can be reduced to a total of only one entry
in the resource file by using a range of days, which is likewise valid for the
1st until the 15th day in every month, that is

@example
19960001#15 Inside work
@end example

@cindex Valid date parts of ranges of days
@cindex Ranges of days, valid date parts of
The use of ranges of days in the date part is permitted as follows:

@itemize @bullet
@item
@w{@samp{@var{yyyy}@var{mm}@var{www}#@var{www}}}

@item
@w{@samp{@var{yyyy}@var{mm}@var{dd}@r{|}@var{www}@var{n}#@r{[}@var{mm}@r{]}@var{dd}@r{|[}@var{mm}@r{]}@var{www}@var{n}}}

@item
@w{@samp{@var{yyyy}*d@r{|}w@var{n}@r{[}@var{www}@r{]}#@var{n}@r{[}@var{www}@r{]}}}

@item
@w{@samp{@var{yyyy}@@e@r{|}@var{dvar}@r{[[}+@r{|}-@r{]}@var{n}@r{[}@var{www}@r{]]}#@r{[}+@r{|}-@r{]}@var{n}@r{[}@var{www}@r{]}}}
@end itemize

@cindex Examples to ranges of days
@cindex Ranges of days, examples to
Some examples to this:

@table @samp
@item 199600mon#fr
In the year 1996 in every month: every day that appears within the day
sequence @samp{mon, tue, wed, thu, fri}.

@item 000000fr#mon
In every year in every month: every day that appears within the day
sequence @samp{fri, sat, sun, mon}.

@item 000001fr3#12
In every year in January: every day that appears within the period
of the 3rd Friday of the month until the 12th of the month.

@item 00000112#fr3
In every year in January: every day that appears within the period
of the 12th of the month until the 3rd Friday of the month.

@item 00000112#augfri3
In every year: every day that appears within the period
of the 12th January until the 3rd Friday of August.

@item 0000sep13#99fr9
In every year: every day that appears within the period
of the 13th September until the last Friday of December.

@item 0*d1#1fr
In every year: every day that appears within the period
of the 1st day of the year until the 1rd Friday of the year.

@item 0*d99fr#333
In every year: every day that appears within the period
of the last Friday of the year until the 333rd day of the year.

@item 1996*w1fr#17mo
In the year 1996: every day that appears within the period
of the Friday of the 1st @sc{iso}-week until the Monday of the
17th @sc{iso}-week.

@item 0@@a#+4fr
In every year: every day that appears within the period
of the date of the date variable @var{a} until the 4th Friday after the
date of the date variable @var{a}.

@item 1996@@e-3#+9fr
In the year 1996: every day that appears within the period
of the date three days before the Easter Sunday's date until the 9th Friday
after the date of the Easter Sunday's date.
@end table

@node Repetition factor of days, Appearance factor of days, Ranges of days, Further date part attributes
@subsubsection Repetition factor of days
@cindex Repetition factor of days, @samp{:@var{n}}
@cindex @samp{:@var{n}} repetition factor of days

A repetition factor of days (@samp{:@var{n}}) is specified by a @samp{:}
character and must trail the day field, which must have a concrete value
in a date part of a Gcal resource file and has not been set to a zero value,
respectively either lead or trail an appearance factor of days.  Except
ranges of days or fixed dates, which occur only on a definite weekday like
@samp{199600mon Every Monday 1996}, such a repetition factor may be specified
in all possible codings of date parts of a Gcal resource file.

This factor may have values in range @samp{1}@dots{}@samp{999}.  Values
greater than the real difference between the date of the first occurrence
of the fixed date und the last day of the year are always reduced to this
real difference.  In this sense, any value greater @samp{365} (or @samp{366}
in leap years) means a repetition factor until the last day of the year.

A repetition factor of days is used to define recurrent fixed dates and to use
only one line in the resource file for them, instead of using several lines in
a resource file needed for defining these recurrent fixed dates separately.
Assuming a fixed date shall always occur on the 15th day in every month of
the year 1996 and covers a period of four days (inclusive the 15th itself),
e.g.@: @samp{Co-workers training}, one solution would be on the one hand a
fixed date entry in the resource file for the 15th of the month and the
succeeding three days, which would be a total of four entries in the resource
file for such a fixed date (apart from the possibility, that a list or a range
of days can be used in such a case).

On the other hand, this expense can be reduced to a total of only one entry
in the resource file by using a repetition factor of days, which is likewise
valid for the 15th and the three days, which succeed the 15th in every month,
namely

@example
19960015:4 Co-workers training
@end example

@cindex Valid date parts of repetition factors of days
@cindex Repetition factors of days, valid date parts of
The use of repetition factors of days in the date part is permitted as follows:

@itemize @bullet
@item
@w{@samp{@var{yyyy}@var{mm}@var{dd}:@var{n}@r{|}@var{www}@var{n}:@var{n}}}

@item
@w{@samp{@var{yyyy}*d@r{|}w@var{n}:@var{n}@r{|}@var{n}@var{www}:@var{n}}}

@item
@w{@samp{@var{yyyy}@@e@r{|}@var{dvar}@r{[[}+@r{|}-@r{]}@var{n}@r{[}@var{www}@r{]]}:@var{n}}}

@item
@w{@samp{@var{yyyy}@var{mm}@var{dd}:@var{n}@r{|}@var{www}@var{n}:@var{n},@r{[}@var{mm}@r{]}@var{dd}:@var{n}@r{|[}@var{mm}@r{]}@var{www}@var{n}:@var{n} @dots{}}}

@item
@w{@samp{@var{yyyy}*d@r{|}w@var{n}:@var{n}@r{|}@var{n}@var{www}:@var{n},@var{n}:@var{n}@r{|}@var{n}@var{www}:@var{n} @dots{}}}

@item
@w{@samp{@var{yyyy}@@e@r{|}@var{dvar}:@var{n},@r{|[}+@r{|}-@r{]}@var{n}@r{[}@var{www}@r{]}:@var{n},@r{[}+@r{|}-@r{]}@var{n}@r{[}@var{www}@r{]}:@var{n} @dots{}}}
@end itemize

@cindex Examples to repetition factors of days
@cindex Repetition factors of days, examples to
Some examples to this:

@table @samp
@item 000001fr3:11
In every year in January: every day that appears within the period
of the 3rd Friday of the month and the succeeding ten days.

@item 00000112:3
In every year in January: every day that appears within the period
of the 12th of the month and the succeeding two days.

@item 00000112:3,fr3:5
In every year in January: every day that appears within the period
of the 12th of the month and the succeeding two days, and that
appears within the period of the 3rd Friday of the month and the
succeeding four days.

@item 0*d1:1
In every year: every day that appears within the period
of the 1st day of the year and no succeeding day.

@item 0*d1:2
In every year: every day that appears within the period
of the 1st day of the year and the succeeding day.

@item 0*d99fr:333
In every year: every day that appears within the period
of the last Friday of the year and the succeeding 332 days.
Well, in cases a fixed date exceeds the year bounds, it will only
be produced until the last day of the year.

@item 1996*w1fr:17
In the year 1996: every day that appears within the period
of the Friday of the 1st @sc{iso}-week and the succeeding 16 days.

@item 0@@a:4
In every year: every day that appears within the period
of the date of the date variable @var{a} and the succeeding three days.

@item 1996@@e-3:9
In the year 1996: every day that appears within the period
of the date three days before the Easter Sunday's date and the succeeding
eight days.
@end table

@node Appearance factor of days, , Repetition factor of days, Further date part attributes
@subsubsection Appearance factor of days
@cindex Appearance factor of days, @samp{.@var{n}}
@cindex @samp{.@var{n}} appearance factor of days

An appearance factor of days (@samp{.@var{n}}) is specified by a @samp{.}
character and must trail the day field, which must have a concrete value
in a date part of a Gcal resource file and has not been set to a zero value,
respectively either lead or trail a repetition factor of days.  Except
fixed dates, which occur only on a definite weekday and are not specified
by using a range of days, like @samp{199600mon Every Monday 1996}, such an
appearance factor may be specified in all possible codings of date parts
of a Gcal resource file.  This factor may be specified with each single
element of lists of days, but in a range of days, this factor may trail
@strong{only} the final day of the range.  Well, the use of such an appearance
factor is only helpful if it is either given in a range of days, or if it is
given together with a repetition factor.

This factor may have values in range @samp{1}@dots{}@samp{999}.  Fixed dates
will be ignored if the factor takes values, which are greater than the real
difference between the date of the occurrence of the fixed date und the last
day of the year, respectively the end of the period, for which the fixed dates
shall either be produced or respected.

An appearance factor of days is used to define a concrete displacement of
recurrent fixed dates.  Assuming a fixed date shall always occur on the
15th day in every month of the year 1996 and covers a period of seven days
(inclusive the 15th itself), but shall only be respected every third day
(i.e.@: two days have to be skipped at a time) within this period,
e.g.@: @samp{Training-college}, one solution would be on the one hand a fixed
date entry in the resource file for the 15th of the month, for the 18th and
for the 21st of the month, which would be a total of three entries in the
resource file for such a fixed date (apart from the possibility, that a list
of days can be used in such a case).

On the other hand, this expense can be reduced to a total of only one entry
in the resource file by using an appearance factor of days, which is likewise
valid for the 15th, the 18th and the 21st in every month, namely on the
one hand by the use of a repetition factor

@example
19960015:7.3 Training-college
@end example

or on the other hand by the use of a range of days

@example
19960015#21.3 Training-college
@end example

@cindex Valid date parts of appearance factors of days
@cindex Appearance factors of days, valid date parts of
The use of appearance factors of days in the date part is permitted as follows:

@itemize @bullet
@item
@w{@samp{@var{yyyy}@var{mm}@var{dd}:@var{n}.@var{n}@r{|}@var{dd}.@var{n}:@var{n}}}

@item
@w{@samp{@var{yyyy}@var{mm}@var{www}@var{n}:@var{n}.@var{n}@r{|}@var{www}@var{n}.@var{n}:@var{n}}}

@item
@w{@samp{@var{yyyy}*d@r{|}w@var{n}:@var{n}.@var{n}@r{|}@var{n}.@var{n}:@var{n}}}

@item
@w{@samp{@var{yyyy}*d@r{|}w@var{n}@var{www}:@var{n}.@var{n}@r{|}@var{n}@var{www}.@var{n}:@var{n}}}

@item
@w{@samp{@var{yyyy}@@e@r{|}@var{dvar}@r{[[}+@r{|}-@r{]}@var{n}@r{[}@var{www}@r{]]}:@var{n}.@var{n}}}

@item
@w{@samp{@var{yyyy}@@e@r{|}@var{dvar}@r{[[}+@r{|}-@r{]}@var{n}@r{[}@var{www}@r{]]}.@var{n}:@var{n}}}

@item
@w{@samp{@var{yyyy}@var{mm}@var{dd}:@var{n}.@var{n}@r{|}@var{www}@var{n}:@var{n}.@var{n},@r{[}@var{mm}@r{]}@var{dd}:@var{n}.@var{n}@r{|[}@var{mm}@r{]}@var{www}@var{n}:@var{n}.@var{n} @dots{}}}

@item
@w{@samp{@var{yyyy}@var{mm}@var{dd}.@var{n}:@var{n}@r{|}@var{www}@var{n}.@var{n}:@var{n},@r{[}@var{mm}@r{]}@var{dd}:@var{n}.@var{n}@r{|[}@var{mm}@r{]}@var{www}@var{n}.@var{n}:@var{n} @dots{}}}

@item
@w{@samp{@var{yyyy}*d@r{|}w@var{n}:@var{n}.@var{n}@r{|}@var{n}@var{www}:@var{n}.@var{n},@var{n}:@var{n}.@var{n}@r{|}@var{n}@var{www}:@var{n}.@var{n} @dots{}}}

@item
@w{@samp{@var{yyyy}*d@r{|}w@var{n}.@var{n}:@var{n}@r{|}@var{n}@var{www}.@var{n}:@var{n},@var{n}.@var{n}:@var{n}@r{|}@var{n}@var{www}.@var{n}:@var{n} @dots{}}}

@item
@w{@samp{@var{yyyy}@@e@r{|}@var{dvar}:@var{n}.@var{n},@r{|[}+@r{|}-@r{]}@var{n}@r{[}@var{www}@r{]}:@var{n}.@var{n},@r{[}+@r{|}-@r{]}@var{n}@r{[}@var{www}@r{]}:@var{n}.@var{n} @dots{}}}

@item
@w{@samp{@var{yyyy}@@e@r{|}@var{dvar}.@var{n}:@var{n},@r{|[}+@r{|}.@r{]}@var{n}@r{[}@var{www}@r{]}.@var{n}:@var{n},@r{[}+@r{|}.@r{]}@var{n}@r{[}@var{www}@r{]}.@var{n}:@var{n} @dots{}}}

@item
@w{@samp{@var{yyyy}@var{mm}@var{www}#@var{www}.@var{n}}}

@item
@w{@samp{@var{yyyy}@var{mm}@var{dd}@r{|}@var{www}@var{n}#@r{[}@var{mm}@r{]}@var{dd}@r{|[}@var{mm}@r{]}@var{www}@var{n}.@var{n}}}

@item
@w{@samp{@var{yyyy}*d@r{|}w@var{n}@r{[}@var{www}@r{]}#@var{n}@r{[}@var{www}@r{]}.@var{n}}}

@item
@w{@samp{@var{yyyy}@@e@r{|}@var{dvar}@r{[[}+@r{|}-@r{]}@var{n}@r{[}@var{www}@r{]]}#@r{[}+@r{|}-@r{]}@var{n}@r{[}@var{www}@r{]}.@var{n}}}
@end itemize

@cindex Examples to appearance factors of days
@cindex Appearance factors of days, examples to
Some examples to this:

@table @samp
@item 000001fr3:11.3
In every year in January: every day that appears within the period
of the 3rd Friday of the month and the succeeding ten days, but only
every 3rd day within this period (skip two days at a time).

@item 00000112:3.2
In every year in January: every day that appears within the period
of the 12th of the month and the succeeding two days, but only
every 2nd day within this period (skip one day at a time).

@item 00000112:3.2,fr3:5.3
In every year in January: every day that appears within the period
of the 12th of the month and the succeeding two days, but only
every 2nd day within this period (skip one day at a time), and that
appears within the period of the 3rd Friday of the month and the
succeeding four days, but only every 3rd day within this period
(skip two days at a time).

@item 0*d1:10.1
In every year: every day that appears within the period
of the 1st day of the year and the succeeding nine days, and this
for any day within this period (skip zero days at a time).

@item 0*d1:2.5
In every year: every day that appears within the period
of the 1st day of the year and the succeeding day, but only
every 5th day within this period (skip four days at a time).
Well, the succeeding days (only one in this example) of the starting day
(1st day of year) are not respected, because the next day resulted by
the appearance factor exceeds the final day (resulted by the repetition factor)
of the period.

@item 0*d99fr:333.61
In every year: every day that appears within the period
of the last Friday of the year and the succeeding 332 days, but only
every 61st day within this period (skip 60 days at a time). Well, in cases
a fixed date exceeds the year bounds, it will only be produced until the last
day of the year.  No succeeding day (332 in this example) of the starting
day (last Friday of the year) is respected by reason of the displacement value
of 60 days, because the next day resulted by the appearance factor exceeds the
final day (resulted by the repetition factor) of the period (the last day of
the year).

@item 1996*w1fr:17.8
In the year 1996: every day that appears within the period
of the Friday of the 1st @sc{iso}-week and the succeeding 16 days, but only
every 8th day within this period (skip seven days at a time).

@item 0@@a:4.3
In every year: every day that appears within the period
of the date of the date variable @var{a} and the succeeding three days, but
only every 3rd day within this period (skip two days at a time).

@item 1996@@e-3:9.4
In the year 1996: every day that appears within the period
of the date three days before the Easter Sunday's date and the succeeding
eight days, but only every 4th day within this period (skip three days at
a time).

@item 1996@@e3#-20sun.15
In the year 1996: every day that appears within the period
of the date three days after the Easter Sunday's date until the 20th Sunday
before the Easter Sunday's date, but only every 15th day within this period
(skip 14 days at a time).
@end table

@page
@node Text part of a line, Comment line, Further date part attributes, Resource file
@subsection Text part of a line
@cindex Text part of a line
@cindex Text part of a line, limitations
@cindex Limitations in the text part of a line
@cindex Handling of non-printable characters in the text part
@cindex Non-printable characters in the text part, handling
@cindex Handling of special character sequences in the text part
@cindex Special character sequences in the text part, handling
@cindex Resource file, text part
@cindex Resource file, limitations
@cindex Limitations in a resource file

The @dfn{text part} of a line in a resource file can be any text you like.
If the text part contains characters, which are used for highlighting the text
or format it for a printer, or characters with decimal values above 127 in
the code table of the used character set (these are potentially non-printable),
which are not produced by Gcal itself, such characters respectively sequences
are displayed by Gcal in an @strong{uninterpreted} manner!  For that very reason
it can happen that the output of such characters can potentially create problems
with the used screen device driver software and/or the external pager program,
likewise mailing of such texts by means of electronic mail.

@cindex Resource file, remarking of text part
@cindex Handling of @code{NUL} characters in the text part
@cindex @code{NUL} characters in the text part, handling
So-called @code{NUL} characters (that's the character with the value zero in
the code table of the used character set) may occur too in the text part, but
their effect is only the suppression of all succeeding characters of the line.
In my opinion it makes no perceptible sense to output these @code{NUL}
characters uninterpreted so they are used for remarking purposes only;
besides the @code{NUL} characters would cause the same problems already
mentioned above.

@cindex Line continuation character, @samp{\}
@cindex @samp{\} line continuation character
@cindex Resource file, line contination
@cindex Continue line in resource file
A line of the resource file is continued on the next line if a
@w{@samp{\@r{-}\n}} @w{(backslash-newline)} character sequence is found, e.g.@::

@need 3000
@noindent
the line:
@example
000000Mo Every Monday
@end example

@noindent
and the lines:
@example
@group
000000Mo \
Every \
Monday
@end group
@end example

@noindent
produce the same output and are essentially equivalent.

@cindex Resource file, force line break up
@cindex Force line break up in resource file
@cindex Line break up character, @samp{~}
@cindex @samp{~} line break up character
Furthermore you can break up the text of a @emph{long} resource file line at
any place your like.  The term @emph{long} means in this context, that the
text displayed by Gcal would override the right text margin of the screen
respectively break up at that margin.  Each time a @samp{~} (tilde) character
is found in the text part, this character is replaced by a real @samp{\n}
(newline) character.  Such texts will be displayed by Gcal in a formatted
manner at a left margin.

@cindex Quotation of special characters
@cindex Quotation character, @samp{\}
@cindex @samp{\} quotation character
You may quote the @samp{~} (tilde) character @minus{} in case this
character itself is needed @minus{} by placing a @samp{\} (backslash)
character before it, e.g.@: @samp{\~}.

If you need the characters @samp{\~} itself, you have to quote the
@samp{\} (backslash) character by itself, e.g.@: @samp{\\~}.

@need 3000
@noindent
The resource file @file{example.rc}

@example
@group
;
; Hi, I'm `example.rc' and alive now
;
0 I know I'm a short text
0 I hope I'm long enough~here, a line break up\
~and again~and now for the last time...
0 Am I another short text? Dunno...
@end group
@end example

@need 3000
@noindent
is displayed as follows:

@example
@group
@cartouche
$ gcal --resource-file=example.rc --disable-highlighting
@print{}
@print{} Fixed date list:
@print{}
@print{} Wed, Sep  14th 1994: Am I another short text? Dunno...
@print{} Wed, Sep  14th 1994: I hope I'm long enough
@print{}                      here, a line break up
@print{}                      and again
@print{}                      and now for the last time...
@print{} Wed, Sep  14th 1994: I know I'm a short text
@end cartouche
@end group
@end example

@cindex Whitespace character
@cindex Quotation of special characters
@cindex Quotation character, @samp{\}
@cindex @samp{\} quotation character
Because @emph{whitespace} characters are used to separate the date part from
the text part (these are internally skipped and remain undisplayed therefore),
it's not possible to supply the text part with leading @emph{whitespace}
characters without further ado.  If one or more @emph{whitespace} characters
shall lead the text part, this can be arranged by quoting the @strong{first} of
these @emph{whitespace} characters (and that by placing a @samp{\} (backslash)
character before it), e.g.@: @samp{\ } if it is a space character.  By means of
such a character sequence, Gcal notices that the text trailing the @samp{\}
character is no longer used for separating purposes, but is member of the text
part.  Gcal skips this specific marking backslash character (avoids its output)
and processes the rest of the line as usual.

@need 3000
@noindent
The following example should be enough to elucidate the above facts.  The
resource file @file{whitespc.rc}

@example
@group
0 BANG BANG
0 bogus
0         bogomips
0    \hello world
0    \ main()@{for(;;)fork();@}
0 \     sh $0 & $0 &
0    \  a  \  b  \\  c  \\\  d
0    What happens now?\
~0  \  This!
0    What happens now?\\
~0  \  That!
@end group
@end example

@need 3000
@noindent
is displayed as follows:

@example
@group
@cartouche
$ gcal --resource-file=whitespc.rc --disable-highlighting
@print{}
@print{} Fixed date list:
@print{} 
@print{} Wed, Sep  14th 1994:      sh $0 & $0 &
@print{} Wed, Sep  14th 1994:   a  \  b  \\  c  \\\  d
@print{} Wed, Sep  14th 1994:  main()@{for(;;)fork();@}
@print{} Wed, Sep  14th 1994: BANG BANG
@print{} Wed, Sep  14th 1994: What happens now?~0  \  That!
@print{} Wed, Sep  14th 1994: What happens now?
@print{}                      0  \  This!
@print{} Wed, Sep  14th 1994: \hello world
@print{} Wed, Sep  14th 1994: bogomips
@print{} Wed, Sep  14th 1994: bogus
@end cartouche
@end group
@end example

@page
@node Comment line, Include directives, Text part of a line, Resource file
@subsection Comment line
@cindex Comment line
@cindex Resource file, line comment
@cindex Remark character, @samp{;}
@cindex @samp{;} remark character
@cindex Comment character, @samp{;}
@cindex @samp{;} comment character
@cindex Whitespace character

A line beginning with a @samp{;} (semicolon) character in the resource file
is treated as a remark and will not be used by Gcal!  Any @emph{whitespace}
characters may lead the remark character.  For information for how a
@code{NUL} character can be used for remarking in a text part, see
@ref{Text part of a line}.

@page
@node Include directives, Special macro texts, Comment line, Resource file
@subsection Include directives
@cindex Include directives
@cindex Resource file, include directives

You may add @code{#include} directives in a resource file (a mechanism similar
the method, which is used by the C Preprocessor) for searching and loading
further resource files.  An @code{#include} directive tells Gcal to suspend
reading the current resource file and read one other resource file before
continuing.  The directive is a line in the resource file that looks like
this template:

@example
#include @emph{whitespace} @var{argument} @r{[}@emph{whitespace}@r{]} @emph{newline}
@end example

@noindent
The @var{argument} can either be

@example
"@var{file name}"
@end example

@noindent
or

@example
<@var{file name}>
@end example

@noindent
(thus a file name, which is embraced by @samp{""} or @samp{<>}).

@cindex Separator character, whitespace
@cindex Whitespace separator character
A @emph{whitespace} character minimum is required between @code{#include}
and the @var{argument}.  The @var{argument} may be trailed by extra
@emph{whitespace} characters and the line must always end with a @samp{\n}
(newline) character, except it's the last line of a resource file.

@noindent
Let's inspect a bit more concrete example:

@enumerate
@item
#include "foo/bar"

@item
#include <bar>
@end enumerate

The first @code{#include} directive tells Gcal to load the file @file{bar}
in the directory @file{foo} from the actual directory.  If this fails, Gcal
tries to load this file using steps 1@dots{}4 of the previously explained
mechanism, which is used for searching files
(@pxref{Resource file, File searching mechanism}).

The second @code{#include} directive tells Gcal to load the file @file{bar}
from the user respectively system data directory using steps 3@dots{}4
of the previously explained mechanism, which is used for searching files.
It is not allowed to include files, which have a fixed access path starting
from the root directory by such an @code{#include} directive like
@w{@samp{#include </file>}} or @w{@samp{#include </foo/bar/file>}}; just as
the specification of a single or an extended file name containing a disk/drive
specifier (even if operating systems like @w{MS-DOS} or OS/2 would permit
such a disk/drive specification on principle), because the resulting path
name (lead by the user respectively system data directory name) wouldn't
be a valid file name any longer.

Included files may include other files again.  But the nesting level of
included files is limited on the one hand by the amount of useable working
storage of the computer, and on the other hand by the value, which is given
by the operating system respectively the compiler for the number of files
which can be opened simultaneously.  Recursive includes @footnote{The included
file tries to include itself again.} or cyclic includes @footnote{The included
file is included again by another file, which occurs at a deeper place of such
a chain.} are not permitted, because such backward references would produce an
infinite loop in the program internally!  Gcal recognizes such situations and
terminates immediately with a fatal error.

If an included resource file cannot be found and no @samp{--debug=abort} option
is given, processing of the resource file containing the @code{#include}
continues.

@page
@node Special macro texts, Date variables, Include directives, Resource file
@subsection Special macro texts
@cindex Special macro texts
@cindex Macro text starting character, @samp{%}
@cindex @samp{%} macro text starting character
@cindex Quotation of special characters
@cindex Quotation character, @samp{\}
@cindex @samp{\} quotation character

@menu
* %s macro text::  How to use the Start of event macro text.
* %e macro text::  How to use the End of event macro text.
* %o macro text::  How to use the Weekday name macro text.
* %k macro text::  How to use the Week number macro text.
* %b macro text::  How to use the Birthday macro text.
* %y macro text::  How to use the Year number macro text.
* %m macro text::  How to use the Month number macro text.
* %w macro text::  How to use the Week number macro text.
* %d macro text::  How to use the Day number macro text.
* %j macro text::  How to use the Julian Day number macro text.
* %n macro text::  How to use the Textual date macro text.
* %t macro text::  How to use the Actual time macro text.
* %1 macro text::  How to use the Start of highlighting sequence 1 macro text.
* %2 macro text::  How to use the End of highlighting sequence 1 macro text.
* %3 macro text::  How to use the Start of highlighting sequence 2 macro text.
* %4 macro text::  How to use the End of highlighting sequence 2 macro text.
@end menu

The text part of a resource file line may contain 16 different, special macro
texts, which may occur in any (senseful) number and order.  These texts start
with a @samp{%} (percent) character, which may be quoted by a leading @samp{\}
(backslash) character if the @samp{%} (percent) character itself is wanted
to be used in the text part, e.g.@: @samp{\%}.  The @samp{%} character
is trailed by a distinguishing mark, which defines the kind of the macro
text to be used and if it is a letter, Gcal accepts it case-insentive.

@quotation
@strong{Please note:}@*
The optional date after the @w{@code{%s@dots{}},} @w{@code{%e@dots{}},}
@w{@code{%o@dots{}},} @w{@code{%k@dots{}},} @w{@code{%b@dots{}}} and
@w{@code{%y@dots{}}} macro texts may be denoted either using the date format
@w{@samp{@var{yyyy}@r{[}@var{mm}@r{[}@var{dd}@r{|}@var{www}@var{n}@r{]]}}},
@w{@samp{@var{yyyy}*d@r{|}w@var{n}@r{[}@var{www}@r{]}}} or
@w{@samp{@var{yyyy}@@e@r{|}@var{dvar}@r{[[}+@r{|}-@r{]}@var{n}@r{[}@var{www}@r{]]}}}
date format.
@end quotation

@node %s macro text, %e macro text, Special macro texts, Special macro texts
@subsubsection %s macro text
@cindex %s macro text
@cindex Whitespace character
@cindex Macro text, start of event
@cindex Event, start of
@cindex Start of event macro text

@w{@code{%s@r{[}@var{yyyy}@r{[}@var{mm}@r{[}@var{dd}@r{|}@var{www}@var{n}@r{]]]}}}
references the @dfn{starting date} of the fixed date, i.e.@: the first date the
fixed date may occur.  If the date, which is encoded in the @w{@code{%s@dots{}}}
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 @strong{must}
have a trailing @emph{whitespace} character, which is suppressed in output.

@itemize @bullet
@item
If @var{yyyy}@dots{} is not given (@equiv{}@strong{no} date encoded),
the 01 January of current year is assumed for the date.

@item
If @var{yyyy} is set to 0000, the current year is assumed for the year.

@item
If @var{mm} is not given, then 01 (@equiv{}January) is assumed for the month.

@item
If @var{mm} is set to 00, the current month is assumed for the month.

@item
If @w{@var{dd}|@var{www}} is not given, then 01 is assumed for the day.

@item
If @var{dd} is set to 00, the current day is assumed for the day.

@item
If the @var{n} field is given (range 1@dots{}5 or 9), a @var{www} field
must be given then.
@end itemize

@need 2000
@node %e macro text, %o macro text, %s macro text, Special macro texts
@subsubsection %e macro text
@cindex %e macro text
@cindex Macro text, end of event
@cindex Whitespace character
@cindex Event, end of
@cindex End of event macro text

@w{@code{%e@r{[}@var{yyyy}@r{[}@var{mm}@r{[}@var{dd}@r{|}@var{www}@var{n}@r{]]]}}}
references the @dfn{ending date} of the fixed date, i.e.@: the last date the
fixed date may occur.  If the date, which is encoded in the @w{@code{%e@dots{}}}
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 @strong{must}
have a trailing @emph{whitespace} character, which is suppressed in output.

@itemize @bullet
@item
If @var{yyyy}@dots{} is not given (@equiv{}@strong{no} date encoded),
the 31 December of current year is assumed for the date.

@item
If @var{yyyy} is set to 0000, the current year is assumed for the year.

@item
If @var{mm} is not given, then 12 (@equiv{}December) is assumed for the month.

@item
If @var{mm} is set to 00, the current month is assumed for the month.

@item
If @w{@var{dd}|@var{www}} is not given, then the last day of month @var{mm}
is assumed for the day.

@item
If @var{dd} is set to 00, the current day is assumed for the day.

@item
If the @var{n} field is given (range 1@dots{}5 or 9), a @var{www} field
must be given then.
@end itemize

@node %o macro text, %k macro text, %e macro text, Special macro texts
@subsubsection %o macro text
@cindex %o macro text
@cindex Macro text, Weekday name
@cindex Whitespace character
@cindex Weekday name macro text

@w{@code{%o@r{[}@var{yyyy}@r{[}@var{mm}@r{[}@var{dd}@r{|}@var{www}@var{n}@r{]]]}}}
references the @dfn{weekday name} and is converted to a @strong{weekday name text},
e.g.@::

@quotation
The text @w{@samp{Today is %o , the %n}}
will be expanded to@*
@w{@expansion{} @samp{Today is Monday, the 10-Jun-1996}},
in case the current date is the 10th June 1996.
@end quotation

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

@itemize @bullet
@item
If @var{yyyy}@dots{} ist not given (@equiv{}@strong{no} date encoded),
the current date is assumed for the date.

@item
If @var{yyyy} is set to 0000, the current year is assumed for the year.

@item
If @var{mm} is not given or set to 00, the current month is assumed
for the month.

@item
If @var{dd} is not given or set to 00, the current day is assumed
for the day.

@item
If the @var{n} field is given (range 1@dots{}5 or 9), a @var{www} field
must be given then.
@end itemize

@node %k macro text, %b macro text, %o macro text, Special macro texts
@subsubsection %k macro text
@cindex %k macro text
@cindex Macro text, Week number
@cindex Whitespace character
@cindex Week number macro text
@cindex @sc{iso}-8601:1988

@w{@code{%k@r{[}@var{yyyy}@r{[}@var{mm}@r{[}@var{dd}@r{|}@var{www}@var{n}@r{]]]}}}
references the @dfn{week number} and is converted to an
@sc{iso}-@strong{week number text}, e.g.@::

@quotation
The text @w{@samp{Today is %o  of week %k}}
will be expanded to@*
@w{@expansion{} @samp{Today is Monday of week 24}},
in case the current date is the 10th June 1996.
@end quotation

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

@itemize @bullet
@item
If @var{yyyy}@dots{} ist not given (@equiv{}@strong{no} date encoded),
the current date is assumed for the date.

@item
If @var{yyyy} is set to 0000, the current year is assumed for the year.

@item
If @var{mm} is not given or set to 00, the current month is assumed
for the month.

@item
If @var{dd} is not given or set to 00, the current day is assumed
for the day.

@item
If the @var{n} field is given (range 1@dots{}5 or 9), a @var{www} field
must be given then.
@end itemize

@need 2000
@node %b macro text, %y macro text, %k macro text, Special macro texts
@subsubsection %b macro text
@cindex %b macro text
@cindex Macro text, birthday
@cindex Whitespace character
@cindex Age value
@cindex Birthday macro text

@w{@code{%b@r{[}@var{yyyy}@r{[}@var{mm}@r{[}@var{dd}@r{|}@var{www}@var{n}@r{]]]}}}
references a @dfn{year of birth} and is converted to an @strong{age value}, e.g.@::

@quotation
The text @w{@samp{My %b1962  birthday%s1952 %e2062}}
will be expanded to@*
@w{@expansion{} @samp{My 32nd birthday}},
in case the current year is 1994.
@end quotation

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 @strong{must} have a
trailing @emph{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.  @xref{Calendar options, ,
@samp{--date-format=de@r{|}us@r{|}gb@r{|}@var{text}}}, for more details.

@itemize @bullet
@item
If @var{yyyy}@dots{} ist not given (@equiv{}@strong{no} date encoded),
the current date is assumed for the date.

@item
If @var{yyyy} is set to 0000, the current year is assumed for the year.

@item
If @var{mm} is not given or set to 00, the current month is assumed
for the month.

@item
If @var{dd} is not given or set to 00, the current day is assumed
for the day.

@item
If the @var{n} field is given (range 1@dots{}5 or 9), a @var{www} field
must be given then.
@end itemize

@need 2000
@node %y macro text, %m macro text, %b macro text, Special macro texts
@subsubsection %y macro text
@cindex %y macro text
@cindex Macro text, year number
@cindex Whitespace character
@cindex Year difference value
@cindex Year number, relative
@cindex Year number macro text

@w{@code{%y@r{[}@var{yyyy}@r{[}@var{mm}@r{[}@var{dd}@r{|}@var{www}@var{n}@r{]]]}}}
references any year and is converted to a @dfn{year difference value}, e.g.@::

@quotation
The text @w{@samp{Sylvester 1912 is %y1912  years ago}}
will be expanded to@*
@w{@expansion{} @samp{Sylvester 1912 is -82 years ago}},
in case the current year is 1994.
@end quotation

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

@itemize @bullet
@item
If @var{yyyy}@dots{} is not given (@equiv{}@strong{no} date encoded),
the current date is assumed for the date.

@item
If @var{yyyy} is set to 0000, the current year is assumed for the year.

@item
If @var{mm} is not given or set to 00, the current month is assumed
for the month.

@item
If @var{dd} is not given or set to 00, the current day is assumed
for the day.

@item
If the @var{n} field is given (range 1@dots{}5 or 9), a @var{www} field
must be given then.
@end itemize

@node %m macro text, %w macro text, %y macro text, Special macro texts
@subsubsection %m macro text
@cindex %m macro text
@cindex Macro text, month number
@cindex Month number, relative
@cindex Month number macro text

@code{%m} references the current respectively queried @dfn{month number}
relative to the actual (@equiv{}todays) date.

@node %w macro text, %d macro text, %m macro text, Special macro texts
@subsubsection %w macro text
@cindex %w macro text
@cindex Macro text, week number
@cindex Week number, relative
@cindex Week number macro text

@code{%w} references the current respectively queried @dfn{week number}
relative to the actual (@equiv{}todays) date.

@node %d macro text, %j macro text, %w macro text, Special macro texts
@subsubsection %d macro text
@cindex %d macro text
@cindex Macro text, day number
@cindex Day number, relative
@cindex Day number macro text

@code{%d} references the current respectively queried @dfn{day number}
relative to the actual (@equiv{}todays) date, e.g.@::

@quotation
A resource file line like @w{@samp{0 %d days gone}}
will be expanded to@*
@w{@expansion{} @samp{-10 days gone}},
in case you call Gcal with the @w{@samp{-c10-}} option and no command.
@end quotation

@node %j macro text, %n macro text, %d macro text, Special macro texts
@subsubsection %j macro text
@cindex %j macro text
@cindex Macro text, Julian Day number
@cindex Julian Day number macro text

@code{%j@r{[[}-@r{]}@var{n}@r{]}} references the current respectively
queried @dfn{Julian Day number} relative to the actual (@equiv{}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.@: @samp{%j-1}.

For example:

@quotation
The line @w{@samp{0 Julian Day %j since 01-Jan-4713 BCE}}
will be expanded to@*
@w{@expansion{} @samp{Julian Day 2437929 since 01-Jan-4713 BCE}},
in case you call Gcal with the @w{@samp{-c %19620921}} option and no command.
@end quotation

If the @code{%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.@::

@quotation
The line @w{@samp{0 Julian Day %j-2415021 since 01-Jan-1900}}
will be expanded to@*
@w{@expansion{} @samp{Julian Day 4 since 01-Jan-1900}},
in case you call Gcal with the @w{@samp{-c %19000105}} option and no command.
@end quotation

@node %n macro text, %t macro text, %j macro text, Special macro texts
@subsubsection %n macro text
@cindex %n macro text
@cindex Macro text, textual date
@cindex Date text, effective
@cindex Textual date macro text

@code{%n@r{[[}+@r{|}-@r{]}@var{n}@r{]}} references the current respectively
queried @dfn{day number} relative to the current date
@ifinfo
@w{@samp{+@r{/}-}}
@end ifinfo
@tex
$\pm$
@end tex
@var{n} days and is converted to an effective @dfn{date text}, e.g.@::

@quotation
A resource file line like @w{@samp{1962Sep21 10000 days old: %n+10000}}
will be expanded to@*
@w{@expansion{} @samp{10000 days old: 06-Feb-1990}},
in case you call Gcal with the simple @samp{-c} option and the command
@samp{sep 1962} (@pxref{Single commands, , @samp{@var{mm} @var{yyyy}}}).
@end quotation

@node %t macro text, %1 macro text, %n macro text, Special macro texts
@subsubsection %t macro text
@cindex %t macro text
@cindex %t12 macro text
@cindex %t24 macro text
@cindex Macro text, actual time
@cindex System time, showing
@cindex Actual time macro text

@code{%t@r{[}12@r{|}24@r{]}} references the @dfn{actual system time}, e.g.@::

@quotation
The text @w{@samp{Time: %t --> Dentist at 10:00}}
will be expanded to@*
@w{@expansion{} @samp{Time: 07:32 --> Dentist at 10:00}},
in case the actual system time value is @w{07:32} @w{(hh:mm)}.
@end quotation

A system time value is always displayed in the @emph{24-hour} format by
default.  For displaying in the @emph{12-hour} format, add @code{12} behind
@code{%t}, e.g.@: @samp{%t12}.

@node %1 macro text, %2 macro text, %t macro text, Special macro texts
@subsubsection %1 macro text
@cindex %1 macro text
@cindex Macro text, start of highlighting sequence 1
@cindex Start of highlighting sequence 1 macro text

@code{%1} is replaced by the starting highlighting sequence respectively
the starting marking character, which is used for highlighting the actual
day, (@pxref{Global options, , @samp{--highlighting=@var{text}}}).  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.  @code{%1}
is used together with the @code{%2} macro text, which turns off this enabled
highlighting sequence respectively produces the ending marking character.
If a @code{%1} text is not succeeded by a @code{%2} text on the line,
Gcal automatically inserts such a @code{%2} text at the end of the line.

For example:

@example
@group
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.
@end group
@end example
  
@node %2 macro text, %3 macro text, %1 macro text, Special macro texts
@subsubsection %2 macro text
@cindex %2 macro text
@cindex Macro text, end of highlighting sequence 1
@cindex End of highlighting sequence 1 macro text

@code{%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.  @code{%2} is used together with the @code{%1} macro text.
The @code{%2} text has no effect if no preceeding @code{%1} text was
found on the line.

@node %3 macro text, %4 macro text, %2 macro text, Special macro texts
@subsubsection %3 macro text
@cindex %3 macro text
@cindex Macro text, start of highlighting sequence 2
@cindex Start of highlighting sequence 2 macro text

@code{%3} is replaced by the starting highlighting sequence respectively
the starting marking character, which is used for highlighting a holiday,
(@pxref{Global options, , @samp{--highlighting=@var{text}}}).  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.  @code{%3}
is used together with the @code{%4} macro text, which turns off this enabled
highlighting sequence respectively produces the ending marking character.
If a @code{%3} text is not succeeded by a @code{%4} text on the line,
Gcal automatically inserts such a @code{%4} text at the end of the line.

@need 1000
For example:

@example
@group
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.
@end group
@end example

@node %4 macro text, , %3 macro text, Special macro texts
@subsubsection %4 macro text
@cindex %4 macro text
@cindex Macro text, end of highlighting sequence 2
@cindex End of highlighting sequence 2 macro text

@code{%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.  @code{%4} is used together with the @code{%3} macro text.
The @code{%4} text has no effect if no preceeding @code{%3} text was
found on the line.

@page
@node Date variables, Text variables, Special macro texts, Resource file
@subsection Date variables
@cindex Date variables
@cindex Local date variables
@cindex Date variables, global
@cindex Date variables, local
@cindex Definition of local date variables
@cindex Local date variables, definition of
@cindex Definition of date variables
@cindex Date variables, definition of
@cindex Management of date variables
@cindex Date variables, management of
@cindex Assignments to date variables
@cindex Date variables, assignments to
@cindex Resource file, limitations
@cindex Limitations in a resource file
@cindex Date variables, total number of
@cindex Total number of date variables

Gcal respects @emph{global} and/or @emph{local} date variables
(@pxref{Date warning options, , @samp{--date-variable=@var{argument}}}),
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 @strong{25} user defined date variables
can be set and referenced during program execution.  A date variable name
@var{dvar} consists of a single letter (case-insensitive and except the letter
@samp{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 @samp{=} and the numerical values of month
@var{mm} (or a short, three characters month name, e.g.@: @samp{Jan},
@samp{Feb}@dots{}) and day @var{dd} this variable has to store (or another
date variable name), e.g.@::

@example
@group
a=1127
c=a
@end group
@end example

@noindent
stores the 27th November to the local date variable @var{a} and to the local
date variable @var{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
@w{@samp{@var{mm}@var{www}@var{n}}},
@w{@samp{@var{dvar}@r{[}+@r{|}-@r{]}@var{n}@r{[}@var{www}@r{]}}} or
@w{@samp{*d@r{|}w@var{n}@r{[}@var{www}@r{]}}} format, e.g.@::

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

@noindent
which means, date variable @var{a} stores the date of second Sunday in March
and @var{b} stores date of last Monday in June.  The date variable @var{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 @var{d} to that date, which
is four Saturdays after the date of @var{c}.  The date variable @var{x}
stores the date of the 10th absolute day of the year (@equiv{} 10th January).
@var{y} stores the date of the 10th Friday of the year, and the assignment to
@var{z} is the date of the Sunday, which occurs in the 3rd week of the year.

@cindex Fiscal year, limitations
@cindex Limitations of use of fiscal years
@cindex 3-Month mode, limitations
@cindex Limitations of use of 3-Month modes
@noindent
@strong{Caution:}@*
These kinds of assignments to date variables are @strong{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 @strong{fiscal years}.

@cindex Visibility of date variables
@cindex Date variables, visibility of
@cindex Name space of date variables
@cindex Date variables, name space of
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 @strong{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 @code{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 @samp{--debug}
respectively @w{@samp{--debug=internal}} option is given, warning messages
for each undefined date variable will be shown
(@pxref{Global options, , @samp{--debug=internal}}).  If the
@w{@samp{--debug=abort}} option is given, Gcal will abort program execution
when the first undefined global date variable reference occurs.  For more
information, see @ref{Global options, , @samp{--debug=abort}}.

@need 1500
@cindex Deletion of local date variables
@cindex Local date variables, deletion of 
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 @file{dvar.rc} elucidates these facts:

@example
@group
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'
@end group
@end example

@need 3000
@noindent
So Gcal creates the following output:

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

@arindex --export-date-variables
@cindex Date variables, export of local
@cindex Export of local date variables
@cindex Visibility of local date variables
@cindex Date variables, visibility of local
Only advanced users should apply the @samp{--export-date-variables}
option, which affects that the actual incarnation of a local date variable
@minus{} which was previously defined in a resource file and not in an
included file @minus{} 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.  @xref{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 @samp{--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; @strong{you are expressively warned now!}

@cindex Operations on date variables
@cindex Date variables, operations on
@noindent
Some basic operations can be performed on date variables.

@noindent
These are:

@table @code
@item @var{dvar}++
@cindex Date variables, simple incrementation
@cindex Simple incrementation of a date variable
Simple incrementation by one day.

@item @var{dvar}--
@cindex Date variables, simple decrementation
@cindex Simple decrementation of a date variable
Simple decrementation by one day.

@item @var{dvar}+=@var{n}
@cindex Date variables, addition by days
@cindex Addition of a date variable
Addition of a constant numeric day factor @var{n}.

@item @var{dvar}-=@var{n}
@cindex Date variables, subtraction by days
@cindex Subtraction of a date variable
Subtraction of a constant numeric day factor @var{n}.

@item @var{dvar}+=@var{n}@var{www}
@cindex Date variables, addition by weekdays
@cindex Addition of a date variable
Addition of @var{n} weekdays @var{www}.

@item @var{dvar}-=@var{n}@var{www}
@cindex Date variables, subtraction by weekdays
@cindex Subtraction of a date variable
Subtraction of @var{n} weekdays @var{www}.
@end table

@cindex Scope of date variables
@cindex Date variables, scope of
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.

@page
@node Text variables, , Date variables, Resource file
@subsection Text variables
@cindex Text variables
@cindex Local text variables
@cindex Text variables, global
@cindex Text variables, local
@cindex Definition of local text variables
@cindex Local text variables, definition of
@cindex Definition of text variables
@cindex Text variables, definition of
@cindex Management of text variables
@cindex Text variables, management of
@cindex Assignments to text variables
@cindex Text variables, assignments to
@cindex Text variables, total number of
@cindex Total number of text variables

Gcal respects @emph{global} and/or @emph{local} text variables
(@pxref{Date warning options, , @samp{--text-variable=@var{argument}}}),
which may be used anywhere in a line of a Gcal resource file.  This means up
to @strong{26} user defined text variables can be set and referenced during
program execution.  A text variable name @var{tvar} consists of the @samp{$}
prefix and a single letter (case-insensitive), and is trailed in a definition
by the assignment operator character @samp{=} 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.

@cindex Quotation of special characters
@cindex Quotation character, @samp{\}
@cindex @samp{\} quotation character
You may quote the @samp{$} prefix character @minus{} in case this
character itself is needed in the text @minus{} by placing a @samp{\}
(backslash) character before it, e.g.@: @samp{\$}.

If you need the characters @samp{\$} itself in the text, you have to quote
the @samp{\} (backslash) character by itself, e.g.@: @samp{\\$}.

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

@example
@group
$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!
@end group
@end example

@need 3000
@noindent
So Gcal creates the following output:

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

@noindent
Or a resource file by the name of @file{demo2.rc} exists with the
following contents:

@example
@group
$a=$b foo
$b=0@@e
$a bar
$b \$b
0 \$a:$a
0 \$b:$b
@end group
@end example

@noindent
So Gcal creates the following output:

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

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

@cindex Visibility of text variables
@cindex Text variables, visibility of
@cindex Name space of text variables
@cindex Text variables, name space of
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 @strong{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 @code{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.

@arindex --export-text-variables
@cindex Text variables, export of local
@cindex Export of local text variables
@cindex Visibility of local text variables
@cindex Text variables, visibility of local
Only advanced users should apply the @samp{--export-text-variables}
option, which affects that the actual incarnation of a local text variable
@minus{} which was previously defined in a resource file and not in an
included file @minus{} 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.  @xref{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 @samp{--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; @strong{you are expressively warned now!}

@cindex Scope of text variables
@cindex Text variables, scope of
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.

@page
@node Resource file examples, , Resource file, Fixed date warnings
@section Resource file examples
@cindex 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.

@noindent
Let's begin with a common example:

@example
@group
; 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
@end group
@end example

@need 4000
@noindent
And here is a resource file by the name of @file{demo3.rc} used to detect
all Fridays the 13th of a year:

@example
@group
$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
@end group
@end example

@page
@noindent
The result for the years 1996@dots{}2002 is as follows:

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

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

@example
@group
$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
@end group
@end example

@need 4000
@noindent
The result for the years 1996@dots{}2002 is as follows:

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

@noindent
And here is a resource file by the name of @file{demo5.rc} used to detect
all working-days of any month:

@example
@group
$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
@end group
@end example

@noindent
Respectively a bit shorter version of the resource file @file{demo5.rc}:

@example
@group
$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
@end group
@end example

@noindent
And a resource file by the name of @file{include.rc} exists, which
is only used to include one given resource file:

@example
#include "$f"
@end example

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

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

@noindent
And finally a resource file by the name of @file{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).

@example
@group
;
; `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
@end group
@end example


@node Todays calendar, Gcal Utilities, Fixed date warnings, Top
@appendix Genesis of the Gregorian calendar
@cindex Calendar, Gregorian
@cindex Gregorian calendar, Genesis of
@cindex Calendar, Julian
@cindex Julian 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 @w{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 @strong{July}.
Offhandedly he named another month to himself and so the month name
@strong{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 @dfn{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 @dfn{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 @dfn{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 @w{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.

@node Gcal Utilities, Internationalization, Todays calendar, Top
@appendix Gcal Utilities
@cindex Gcal Utilities
@cindex Utilities to Gcal

@menu
* Invoking tcal::      How to run @code{tcal} and a summary of its options.
* Invoking txt2gcal::  How to run @code{txt2gcal} and a summary of its options.
@end menu

Two small utility programs are part of the Gcal @value{GCAL-VERSION} package.
The @code{tcal} program runs the Gcal program with the date set one day ahead.
And the @code{txt2gcal} program creates a verbatim Gcal resource file from a
text file.

@node Invoking tcal, Invoking txt2gcal, Gcal Utilities, Gcal Utilities
@appendixsec Invoking @code{tcal}
@cindex Invoking @code{tcal}
@cindex The @code{tcal} utility
@cindex Utility @code{tcal}
@cindex @code{tcal}, utility

The @code{tcal} program runs @code{gcal} with the date of tomorrows day
(equivalent the @w{@samp{--shift=1}} option).  Its arguments are as follows:

@example
tcal @r{[}--help @r{|} --version@r{] | [}--shift=@r{[}+@r{|}-@r{]}@var{number}@r{] [}@var{Argument}@dots{}@r{]}
@end example

All given @var{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 @w{@samp{--shift=@r{[}+@r{|}-@r{]}@var{number}}} option, in
which @w{@samp{@r{[}+@r{|}-@r{]}@var{number}}} is the distance
of days, the desired date is distant from the actual date.  The
@samp{--shift} option must be given before all other @var{arguments},
which are passed to the Gcal program.

@cindex @code{GCALPROG} environment variable
@cindex Environment variable, @code{GCALPROG}
@vindex GCALPROG
In case a @code{GCALPROG} environment variable
(@pxref{Environment variables, , GCALPROG}) is defined and set with the file
name of the executable Gcal program, @code{tcal} will use this file name for
calling Gcal.  Otherwise, the file name @code{gcal}, which is burned-in during
the compilation step of @code{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:

@table @samp
@item --help
@arindex --help
Print a usage message listing all available options, then exit successfully.

@item --version
@arindex --version
Print the version number, then exit successfully.

@item --shift=@r{[}+@r{|}-@r{]}@var{number}
@arindex --shift=@r{[}+@r{|}-@r{]}@var{number}
Define the displacement in @samp{@r{[}+@r{|}-@r{]}@var{number}} days the
desired date is distant from the actual date.
@end table

@node Invoking txt2gcal, , Invoking tcal, Gcal Utilities
@appendixsec Invoking @code{txt2gcal}
@cindex Invoking @code{txt2gcal}
@cindex The @code{txt2gcal} utility
@cindex Utility @code{txt2gcal}
@cindex @code{txt2gcal}, utility

The @code{txt2gcal} program creates a verbatim Gcal resource file from
a text file. Its arguments are as follows:

@example
txt2gcal @r{[}--help @r{|} --version@r{] | [}@var{Text-file}@r{|}-@r{] [}@var{Date-part}@r{]}
@end example

If no @var{text-file} or @code{-} argument is given, the program reads and
processes all input received from the standard input channel. If no
@var{date-part} argument is given, @code{txt2gcal} creates a @samp{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:

@table @samp
@item --help
@arindex --help
Print a usage message listing all available options, then exit successfully.

@item --version
@arindex --version
Print the version number, then exit successfully.
@end table

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

@example
@group
        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'.
@end group
@end example

@need 2000
@noindent
and @code{txt2gcal} processes this file, redirecting the output to
@file{demo.rc}:

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

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

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

@node Internationalization, Meta Symbols, Gcal Utilities, Top
@appendix Aspects in Internationalization
@cindex Aspects in Internationalization
@cindex Internationalization aspects
@cindex Used native language
@cindex Native language, used

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 @code{gettext} package are integrated into the Software.
@xref{Top, , Introduction, gettext, GNU gettext tools}, for more details.

@cindex Message catalog
By default, Gcal displays all message texts using the English native language
in case no other native language is wanted.  A so-called @emph{message catalog}
is read by Gcal at run-time if message texts from another native language are
required.  Gcal @value{GCAL-VERSION} supports the following native languages:

@example
@group
@value{SLANG}
@end group
@end example

@cindex Selection of native language
@cindex Native language, selection of
It is only necessary to set one of the environment variables (which are listed
here with decreasing priority)

@enumerate
@item
@vindex LANGUAGE
@cindex @code{LANGUAGE} environment variable
@cindex Environment variable, @code{LANGUAGE}
@code{LANGUAGE} (@pxref{Environment variables, , LANGUAGE})

@item
@vindex LC_ALL
@cindex @code{LC_ALL} environment variable
@cindex Environment variable, @code{LC_ALL}
@code{LC_ALL} (@pxref{Environment variables, , LC_ALL})

@item
@vindex LC_MESSAGES
@cindex @code{LC_MESSAGES} environment variable
@cindex Environment variable, @code{LC_MESSAGES}
@code{LC_MESSAGES} (@pxref{Environment variables, , LC_MESSAGES})

@item
@vindex LANG
@cindex @code{LANG} environment variable
@cindex Environment variable, @code{LANG}
@code{LANG} (@pxref{Environment variables, , LANG})
@end enumerate

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

Normally, users only have to set the @code{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 @w{@samp{setenv LANG de}} (in @code{csh}) or
@w{@samp{export LANG; LANG=de}} (in @code{sh}) at the shell prompt.  Of course
they could even do this from their @file{.login} or @file{.profile} file.
@xref{Users, , The User's View, gettext, GNU gettext tools}, for more details.

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

@sp 2

@cindex Native language defaults
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).

@noindent
A @code{en} language code effects the following internal defaults of above
criterias:

@itemize @bullet
@item
U.S. American date format

@item
Gregorian Reformation have occured 1752

@item
Week starts on Sunday

@item
Representation of calendar sheet

@example
@group
   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
@end group
@end example
@end itemize

@noindent
And a @code{de} language code (or other language codes, for which a
@emph{message catalog} will be created and distributed in future) effects
the following internal defaults:

@itemize @bullet
@item
German date format

@item
Gregorian Reformation have occured 1582

@item
Week starts on Monday

@item
Representation of calendar sheet

@example
@group
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
@end group
@end example
@end itemize

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

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

If a language code is specified for which no @emph{message catalog} is
installed, Gcal takes the internal defaults of the @code{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 @code{de}
language code, because most european countries (taken as standard) use them.

@cindex @sc{iso}-3166
@cindex Extended language code information
@cindex Language code information, extended
@vindex LANG
Now British users will certainly ask whether they could use their date format
as an internal default (all other internal defaults of the simple @code{en}
language code information meet their criterias).  The answer to this is a
simple @cite{yes}, nevertheless these users have to set the environment
variable @code{LANG} with an @dfn{extended language code information} instead
of a simple language code information.  The usual template of an extended
language code information is as follows:

@need 2000
@itemize @bullet
@item
For XPG syntax (X/Open Portability Guide):
@smallexample
@var{language}@r{[}_@var{territory}@r{][}.@var{codeset}@r{][}@@@var{modifier}@r{]}
@end smallexample

@item
For CEN syntax (Comite Europen de Normalisation):
@smallexample
@var{language}@r{[}_@var{territory}@r{][}+@var{audience}@r{][}+@var{special}@r{][},@var{sponsor}@r{][}_@var{revision}@r{]}
@end smallexample
@end itemize

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

@node Meta Symbols, Coding scheme, Internationalization, Top
@appendix Meta Symbols
@cindex Meta Symbols, used
@cindex Meta language, used

Within this document the following @emph{metasyntactic} conventions will be used
when discussing command line options, arguments, commands and templates:
@sp 2

@table @code
@item @var{n}
Argument is not optional and @var{n} must be a valid number.

@item e@r{|}@var{dvar}
Argument is not optional and must be a single alphabetic character.

@item @r{[}@var{text}@r{]}
Argument is optional and @var{text} is a valid string of text.

@item @r{[}@var{a}@var{b}@r{]}
Arguments are optional, any number may be used in any order, e.g.@::

@example
@var{NOTHING}, @var{a}, @var{b}, @var{a}@var{b}, @var{b}@var{a} @dots{}
@end example

@item @r{@{}@var{a}@var{b}@r{@}}
Arguments are not optional, minimum one up to any number may be used
in any order, e.g.@::

@example
@var{a}, @var{b}, @var{a}@var{b}, @var{b}@var{a} @dots{}
@end example

@item @r{[}@var{a}@r{|}@var{b}@r{]}
Arguments are optional, select either @var{a} or @var{b}, but not both.

@item @var{a}@r{|}@var{b}
Arguments are not optional, select either @var{a} or @var{b}, but not both.

@item @r{[}@var{a}@r{[}@var{b}@r{]]}
Arguments are optional, select either @var{a} or @var{a}@var{b}, but
not @var{b}.

@item @r{[}@var{a}@r{|}@var{b}@r{[}@var{c}@r{]}@r{]}
Arguments are optional, select @var{a} or @var{b} or @var{a}@var{c}
or @var{b}@var{c}, but not @var{c}.

@item @r{[}@var{a}@r{|}@var{b}@var{c}@r{]}
Arguments are optional, select either @var{a}@var{c} or @var{b}@var{c},
but not @var{a} or @var{b} or @var{c}.

@item @r{[}@var{a}@r{]|[}@var{b}@r{]}
Argument @emph{lists} are optional, select either list @var{a} or list
@var{b}, but not both.

@item @r{[}@dots{}@r{]}
Additional arguments/files may be specified and are optional.
@end table

@node Coding scheme, Environment variables, Meta Symbols, Top
@appendix Coding scheme
@cindex Coding scheme of resource file
@cindex Resource file, coding scheme
@cindex Resource file, date part

@menu
* Coding scheme table 1::
* Coding scheme table 2::
@end menu

The following coding scheme tables explain the relations between the
@emph{date part} @w{(@var{yyyy}@dots{})} of a resource file line and
the modifiers, the short-style option @w{@samp{-c@r{|}C@r{[]}}}, which
is used for the fixed date warnings respectively the long-style option
@w{@samp{--period-of-fixed-dates=@var{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 @emph{fixed date warning}
argument is given, it respects only those entries which have a definite
relation to the @emph{fixed date warning} argument to avoid the output
of redundant information!
@sp 2

@noindent
In @emph{date part} @code{@var{yyyy}@dots{}}:

@table @var
@item yyyy
represents any year number (0001@dots{}9999).

@item mm
represents any month number (01@dots{}12 or 99) respectively any textual short
month name with lenght of 3 characters (Jan, Feb@dots{}).

@item dd
represents any day number (1@dots{}28, 29, 30, 31 or 99).

@item www
represents any textual short weekday name with lenght of 2@dots{}3 characters
(Mon@dots{}Sun).

@item ?
represents any case-insensitive single letter.

@item n
represents any positive integer number (one or more digits).
@end table

@page
@node Coding scheme table 1, Coding scheme table 2, Coding scheme, Coding scheme
@appendixsec Coding scheme table 1
@cindex Coding scheme table 1

This table opposes all possible encode variations of a date given in
the @emph{date part} of resource file with all fitting modifiers of the
short-style option @w{@samp{-c@r{|}C@r{[]}}}.
@sp 2

@quotation
@strong{Please note:}@*
The
@w{@samp{-c},}
@w{@samp{-ct},}
@w{@samp{-c@var{n}d},}
@w{@samp{-c*d@r{|}w@var{n}@r{[}@var{www}@r{]}},}
@w{@samp{-c@@e@r{|}@var{dvar}@r{[[}+@r{|}-@r{]}@var{n}@r{[}@var{www}@r{]]}},}
@w{@samp{-c@var{mm}@var{dd}}} and
@w{@samp{-c@var{mm}@var{www}@var{n}}} options respect
@strong{all} encode variations of the @emph{date part}!
@end quotation
@sp 2

@table @code
@item @strong{Date part of resource file}
@strong{Short-style option -c@r{|}C@r{[]}}
@sp 2

@item 00000000
@w{@code{-c@var{n}+@r{|}-}}

@item 000000@var{dd}
@w{@code{-c@var{n}w@r{|}+@r{|}-},}
@w{@code{-cw@r{[}+@r{|}-@r{]}},}
@w{@code{-cm@r{[}+@r{|}-@r{]}}}

@item 0000@var{mm}00
@w{@code{-c@var{n}+@r{|}-}}

@item 0000@var{mm}@var{dd}
@w{@code{-c@var{n}w@r{|}+@r{|}-},}
@w{@code{-cw@r{[}+@r{|}-@r{]}},}
@w{@code{-cm@r{[}+@r{|}-@r{]}},}
@w{@code{-cy@r{[}+@r{|}-@r{]}},}
@w{@code{-cl@var{n}d@r{|}w@r{|}+@r{|}-},}
@w{@code{-cl*d@r{|}w@var{n}@r{[}@var{www}@r{]}},}@*
@w{@code{-cl@@e@r{|}@var{dvar}@r{[[}+@r{|}-@r{]}@var{n}@r{[}@var{www}@r{]]}},}
@w{@code{-cl@var{mm}@var{dd}},}
@w{@code{-cl@var{mm}@var{www}@var{n}}}

@item @var{yyyy}0000
@w{@code{-c@var{n}+@r{|}-}}

@item @var{yyyy}00@var{dd}
@w{@code{-c@var{n}w@r{|}+@r{|}-},}
@w{@code{-cw@r{[}+@r{|}-@r{]}},}
@w{@code{-cm@r{[}+@r{|}-@r{]}}}

@item @var{yyyy}@var{mm}00
@w{@code{-c@var{n}+@r{|}-}}

@item @var{yyyy}@var{mm}@var{dd}
@w{@code{-c@var{n}w@r{|}+@r{|}-},}
@w{@code{-cw@r{[}+@r{|}-@r{]}},}
@w{@code{-cm@r{[}+@r{|}-@r{]}},}
@w{@code{-cy@r{[}+@r{|}-@r{]}},}
@w{@code{-cl@var{n}d@r{|}w@r{|}+@r{|}-},}
@w{@code{-cl*d@r{|}w@var{n}@r{[}@var{www}@r{]}},}@*
@w{@code{-cl@@e@r{|}@var{dvar}@r{[[}+@r{|}-@r{]}@var{n}@r{[}@var{www}@r{]]}},}
@w{@code{-cl@var{mm}@var{dd}},}
@w{@code{-cl@var{mm}@var{www}@var{n}}}

@item 000000@var{www}
@w{@code{-c@var{n}w@r{|}+@r{|}-},}
@w{@code{-cw@r{[}+@r{|}-@r{]}}}

@item 0000@var{mm}@var{www}
@w{@code{-c@var{n}w@r{|}+@r{|}-},}
@w{@code{-cw@r{[}+@r{|}-@r{]}}}

@item @var{yyyy}00@var{www}
@w{@code{-c@var{n}w@r{|}+@r{|}-},}
@w{@code{-cw@r{[}+@r{|}-@r{]}}}

@item @var{yyyy}@var{mm}@var{www}
@w{@code{-c@var{n}w@r{|}+@r{|}-},}
@w{@code{-cw@r{[}+@r{|}-@r{]}}}

@item 000000@var{www}@var{n}
@w{@code{-c@var{n}w@r{|}+@r{|}-},}
@w{@code{-cw@r{[}+@r{|}-@r{]}},}
@w{@code{-cm@r{[}+@r{|}-@r{]}}}

@item 0000@var{mm}@var{www}@var{n}
@w{@code{-c@var{n}w@r{|}+@r{|}-},}
@w{@code{-cw@r{[}+@r{|}-@r{]}},}
@w{@code{-cm@r{[}+@r{|}-@r{]}},}
@w{@code{-cy@r{[}+@r{|}-@r{]}},}
@w{@code{-cl@var{n}d@r{|}w@r{|}+@r{|}-},}
@w{@code{-cl*d@r{|}w@var{n}@r{[}@var{www}@r{]}},}@*
@w{@code{-cl@@e@r{|}@var{dvar}@r{[[}+@r{|}-@r{]}@var{n}@r{[}@var{www}@r{]]}},}
@w{@code{-cl@var{mm}@var{dd}},}
@w{@code{-cl@var{mm}@var{www}@var{n}}}

@item @var{yyyy}00@var{www}@var{n}
@w{@code{-c@var{n}w@r{|}+@r{|}-},}
@w{@code{-cw@r{[}+@r{|}-@r{]}},}
@w{@code{-cm@r{[}+@r{|}-@r{]}}}

@item @var{yyyy}@var{mm}@var{www}@var{n}
@w{@code{-c@var{n}w@r{|}+@r{|}-},}
@w{@code{-cw@r{[}+@r{|}-@r{]}},}
@w{@code{-cm@r{[}+@r{|}-@r{]}},}
@w{@code{-cy@r{[}+@r{|}-@r{]}},}
@w{@code{-cl@var{n}d@r{|}w@r{|}+@r{|}-},}
@w{@code{-cl*d@r{|}w@var{n}@r{[}@var{www}@r{]}},}@*
@w{@code{-cl@@e@r{|}@var{dvar}@r{[[}+@r{|}-@r{]}@var{n}@r{[}@var{www}@r{]]}},}
@w{@code{-cl@var{mm}@var{dd}},}
@w{@code{-cl@var{mm}@var{www}@var{n}}}

@item 0000*d@var{n}@r{[}@var{www}@r{]}
@w{@code{-c@var{n}w@r{|}+@r{|}-},}
@w{@code{-cw@r{[}+@r{|}-@r{]}},}
@w{@code{-cm@r{[}+@r{|}-@r{]}},}
@w{@code{-cy@r{[}+@r{|}-@r{]}},}
@w{@code{-cl@var{n}d@r{|}w@r{|}+@r{|}-},}
@w{@code{-cl*d@r{|}w@var{n}@r{[}@var{www}@r{]}},}@*
@w{@code{-cl@@e@r{|}@var{dvar}@r{[[}+@r{|}-@r{]}@var{n}@r{[}@var{www}@r{]]}},}
@w{@code{-cl@var{mm}@var{dd}},}
@w{@code{-cl@var{mm}@var{www}@var{n}}}

@item @var{yyyy}*d@var{n}@r{[}@var{www}@r{]}
@w{@code{-c@var{n}w@r{|}+@r{|}-},}
@w{@code{-cw@r{[}+@r{|}-@r{]}},}
@w{@code{-cm@r{[}+@r{|}-@r{]}},}
@w{@code{-cy@r{[}+@r{|}-@r{]}},}
@w{@code{-cl@var{n}d@r{|}w@r{|}+@r{|}-},}
@w{@code{-cl*d@r{|}w@var{n}@r{[}@var{www}@r{]}},}@*
@w{@code{-cl@@e@r{|}@var{dvar}@r{[[}+@r{|}-@r{]}@var{n}@r{[}@var{www}@r{]]}},}
@w{@code{-cl@var{mm}@var{dd}},}
@w{@code{-cl@var{mm}@var{www}@var{n}}}

@item 0000*w@var{n}@r{[}@var{www}@r{]}
@w{@code{-c@var{n}w@r{|}+@r{|}-},}
@w{@code{-cw@r{[}+@r{|}-@r{]}},}
@w{@code{-cm@r{[}+@r{|}-@r{]}},}
@w{@code{-cy@r{[}+@r{|}-@r{]}},}
@w{@code{-cl@var{n}d@r{|}w@r{|}+@r{|}-},}
@w{@code{-cl*d@r{|}w@var{n}@r{[}@var{www}@r{]}},}@*
@w{@code{-cl@@e@r{|}@var{dvar}@r{[[}+@r{|}-@r{]}@var{n}@r{[}@var{www}@r{]]}},}
@w{@code{-cl@var{mm}@var{dd}},}
@w{@code{-cl@var{mm}@var{www}@var{n}}}

@item @var{yyyy}*w@var{n}@r{[}@var{www}@r{]}
@w{@code{-c@var{n}w@r{|}+@r{|}-},}
@w{@code{-cw@r{[}+@r{|}-@r{]}},}
@w{@code{-cm@r{[}+@r{|}-@r{]}},}
@w{@code{-cy@r{[}+@r{|}-@r{]}},}
@w{@code{-cl@var{n}d@r{|}w@r{|}+@r{|}-},}
@w{@code{-cl*d@r{|}w@var{n}@r{[}@var{www}@r{]}},}@*
@w{@code{-cl@@e@r{|}@var{dvar}@r{[[}+@r{|}-@r{]}@var{n}@r{[}@var{www}@r{]]}},}
@w{@code{-cl@var{mm}@var{dd}},}
@w{@code{-cl@var{mm}@var{www}@var{n}}}

@item 0000@@@var{?}@r{[}+@r{|}-@r{]}@var{n}@r{[}@var{www}@r{]}
@w{@code{-c@var{n}w@r{|}+@r{|}-},}
@w{@code{-cw@r{[}+@r{|}-@r{]}},}
@w{@code{-cm@r{[}+@r{|}-@r{]}},}
@w{@code{-cy@r{[}+@r{|}-@r{]}},}
@w{@code{-cl@var{n}d@r{|}w@r{|}+@r{|}-},}
@w{@code{-cl*d@r{|}w@var{n}@r{[}@var{www}@r{]}},}@*
@w{@code{-cl@@e@r{|}@var{dvar}@r{[[}+@r{|}-@r{]}@var{n}@r{[}@var{www}@r{]]}},}
@w{@code{-cl@var{mm}@var{dd}},}
@w{@code{-cl@var{mm}@var{www}@var{n}}}

@item @var{yyyy}@@@var{?}@r{[}+@r{|}-@r{]}@var{n}@r{[}@var{www}@r{]}
@w{@code{-c@var{n}w@r{|}+@r{|}-},}
@w{@code{-cw@r{[}+@r{|}-@r{]}},}
@w{@code{-cm@r{[}+@r{|}-@r{]}},}
@w{@code{-cy@r{[}+@r{|}-@r{]}},}
@w{@code{-cl@var{n}d@r{|}w@r{|}+@r{|}-},}
@w{@code{-cl*d@r{|}w@var{n}@r{[}@var{www}@r{]}},}@*
@w{@code{-cl@@e@r{|}@var{dvar}@r{[[}+@r{|}-@r{]}@var{n}@r{[}@var{www}@r{]]}},}
@w{@code{-cl@var{mm}@var{dd}},}
@w{@code{-cl@var{mm}@var{www}@var{n}}}
@end table

@page
@node Coding scheme table 2, , Coding scheme table 1, Coding scheme
@appendixsec Coding scheme table 2
@cindex Coding scheme table 2

This table opposes all possible encode variations of the short-style
option @w{@samp{-c@r{|}C@r{[]}}} with all fitting modifiers of a date
given in the @emph{date part} of resource file.
@sp 2

@table @code
@item @strong{Short-style option -c@r{|}C@r{[]}}
@code{@strong{Date part of resource file}}
@sp 2

@item -c
@itemx -ct
@itemx -c@var{n}d@r{|}+@r{|}-
@itemx -c@var{mm}@var{dd}
@itemx -c@var{mm}@var{www}@var{n}
@itemx -c*d@r{|}w@var{n}@r{[}@var{www}@r{]}
@itemx -c@@e@r{|}@var{dvar}@r{[[}+@r{|}-@r{]}@var{n}@r{[}@var{www}@r{]]}
@w{@code{00000000},}
@w{@code{0000@var{mm}00},}
@w{@code{@var{yyyy}0000},}
@w{@code{@var{yyyy}@var{mm}00},}
@w{@code{000000@var{dd}},}
@w{@code{0000@var{mm}@var{dd}},}
@w{@code{@var{yyyy}00@var{dd}},}
@w{@code{@var{yyyy}@var{mm}@var{dd}},}
@w{@code{000000@var{www}},}
@w{@code{0000@var{mm}@var{www}},}
@w{@code{@var{yyyy}00@var{www}},}
@w{@code{@var{yyyy}@var{mm}@var{www}},}
@w{@code{000000@var{www}@var{n}},}
@w{@code{0000@var{mm}@var{www}@var{n}},}
@w{@code{@var{yyyy}00@var{www}@var{n}},}
@w{@code{@var{yyyy}@var{mm}@var{www}@var{n}},}
@w{@code{0000*d@var{n}},}
@w{@code{0000*d@var{n}@var{www}},}
@w{@code{@var{yyyy}*d@var{n}},}
@w{@code{@var{yyyy}*d@var{n}@var{www}},}
@w{@code{0000*w@var{n}},}
@w{@code{0000*w@var{n}@var{www}},}
@w{@code{@var{yyyy}*w@var{n}},}
@w{@code{@var{yyyy}*w@var{n}@var{www}},}
@w{@code{0000@@@var{?}@r{[}+@r{|}-@r{]}@var{n}},}@*
@w{@code{0000@@@var{?}@r{[}+@r{|}-@r{]}@var{n}@var{www}},}
@w{@code{@var{yyyy}@@@var{?}@r{[}+@r{|}-@r{]}@var{n}},}
@w{@code{@var{yyyy}@@@var{?}@r{[}+@r{|}-@r{]}@var{n}@var{www}}}

@item -cw@r{[}+@r{|}-@r{]}
@itemx -c@var{n}w
@w{@code{000000@var{dd}},}
@w{@code{0000@var{mm}@var{dd}},}
@w{@code{@var{yyyy}00@var{dd}},}
@w{@code{@var{yyyy}@var{mm}@var{dd}},}
@w{@code{000000@var{www}},}
@w{@code{0000@var{mm}@var{www}},}
@w{@code{@var{yyyy}00@var{www}},}
@w{@code{@var{yyyy}@var{mm}@var{www}},}
@w{@code{000000@var{www}@var{n}},}
@w{@code{0000@var{mm}@var{www}@var{n}},}
@w{@code{@var{yyyy}00@var{www}@var{n}},}
@w{@code{@var{yyyy}@var{mm}@var{www}@var{n}},}
@w{@code{0000*d@var{n}},}
@w{@code{0000*d@var{n}@var{www}},}
@w{@code{@var{yyyy}*d@var{n}},}
@w{@code{@var{yyyy}*d@var{n}@var{www}},}
@w{@code{0000*w@var{n}},}
@w{@code{0000*w@var{n}@var{www}},}
@w{@code{@var{yyyy}*w@var{n}},}
@w{@code{@var{yyyy}*w@var{n}@var{www}},}
@w{@code{0000@@@var{?}@r{[}+@r{|}-@r{]}@var{n}},}
@w{@code{0000@@@var{?}@r{[}+@r{|}-@r{]}@var{n}@var{www}},}
@w{@code{@var{yyyy}@@@var{?}@r{[}+@r{|}-@r{]}@var{n}},}
@w{@code{@var{yyyy}@@@var{?}@r{[}+@r{|}-@r{]}@var{n}@var{www}}}

@item -cm@r{[}+@r{|}-@r{]}
@w{@code{000000@var{dd}},}
@w{@code{0000@var{mm}@var{dd}},}
@w{@code{@var{yyyy}00@var{dd}},}
@w{@code{@var{yyyy}@var{mm}@var{dd}},}
@w{@code{000000@var{www}@var{n}},}
@w{@code{0000@var{mm}@var{www}@var{n}},}
@w{@code{@var{yyyy}00@var{www}@var{n}},}
@w{@code{@var{yyyy}@var{mm}@var{www}@var{n}},}
@w{@code{0000*d@var{n}},}
@w{@code{0000*d@var{n}@var{www}},}
@w{@code{@var{yyyy}*d@var{n}},}
@w{@code{@var{yyyy}*d@var{n}@var{www}},}
@w{@code{0000*w@var{n}},}
@w{@code{0000*w@var{n}@var{www}},}
@w{@code{@var{yyyy}*w@var{n}},}
@w{@code{@var{yyyy}*w@var{n}@var{www}},}
@w{@code{0000@@@var{?}@r{[}+@r{|}-@r{]}@var{n}},}
@w{@code{0000@@@var{?}@r{[}+@r{|}-@r{]}@var{n}@var{www}},}
@w{@code{@var{yyyy}@@@var{?}@r{[}+@r{|}-@r{]}@var{n}},}
@w{@code{@var{yyyy}@@@var{?}@r{[}+@r{|}-@r{]}@var{n}@var{www}}}

@item -cy@r{[}+@r{|}-@r{]}
@itemx -cl@var{n}d@r{|}w@r{|}+@r{|}-
@itemx -cl@var{mm}@var{dd}
@itemx -cl@var{mm}@var{www}@var{n}
@itemx -cl*d@r{|}w@var{n}@r{[}@var{www}@r{]}
@itemx -cl@@e@r{|}@var{dvar}@r{[[}+@r{|}-@r{]}@var{n}@r{[}@var{www}@r{]]}
@w{@code{0000@var{mm}@var{dd}},}
@w{@code{@var{yyyy}@var{mm}@var{dd}},}
@w{@code{0000@var{mm}@var{www}@var{n}},}
@w{@code{@var{yyyy}@var{mm}@var{www}@var{n}},}
@w{@code{0000*d@var{n}},}
@w{@code{0000*d@var{n}@var{www}},}
@w{@code{@var{yyyy}*d@var{n}},}
@w{@code{@var{yyyy}*d@var{n}@var{www}},}
@w{@code{0000*w@var{n}},}
@w{@code{0000*w@var{n}@var{www}},}
@w{@code{@var{yyyy}*w@var{n}},}
@w{@code{@var{yyyy}*w@var{n}@var{www}},}
@w{@code{0000@@@var{?}@r{[}+@r{|}-@r{]}@var{n}},}
@w{@code{0000@@@var{?}@r{[}+@r{|}-@r{]}@var{n}@var{www}},}
@w{@code{@var{yyyy}@@@var{?}@r{[}+@r{|}-@r{]}@var{n}},}
@w{@code{@var{yyyy}@@@var{?}@r{[}+@r{|}-@r{]}@var{n}@var{www}}}
@end table

@node Environment variables, Error codes, Coding scheme, Top
@appendix Environment variables
@cindex Environment variables
@cindex Respected environment variables
@cindex Environment variable, respected

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

@table @code
@item COLUMNS
@itemx CO
@cindex Environment variable, @code{COLUMNS}
@cindex Environment variable, @code{CO}
@cindex @code{COLUMNS} environment variable
@cindex @code{CO} environment variable
@vindex COLUMNS
@vindex CO
Sets the number of columns on the screen.  Takes precedence over the
number of columns specified by the @code{TERM} environment variable or
the system itself.

@item GCAL
@cindex Environment variable, @code{GCAL}
@cindex @code{GCAL} environment variable
@vindex GCAL
Flags which are passed to Gcal automatically.

@item GCALANSI
@cindex Environment variable, @code{GCALANSI}
@cindex @code{GCALANSI} environment variable
@vindex GCALANSI
If defined or set, @sc{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.

@item GCAL_DATE_FORMAT
@cindex Environment variable, @code{GCAL_DATE_FORMAT}
@cindex @code{GCAL_DATE_FORMAT} environment variable
@vindex GCAL_DATE_FORMAT
Contains the date format text, which defines the ordering of a displayed
date.  Takes precedence over the default date format text.

@item GCALPATH
@cindex Environment variable, @code{GCALPATH}
@cindex @code{GCALPATH} environment variable
@vindex GCALPATH
(@samp{:}) colon-separated list of directories which are searched to find the
@file{.gcalrc} file.  Takes precedence over @w{@code{GCAL_USR_DATADIR}} and
@w{@code{GCAL_SYS_DATADIR}}.

@item GCALPROG
@cindex @code{GCALPROG} environment variable
@cindex Environment variable, @code{GCALPROG}
@vindex GCALPROG
Contains the file name of the executable Gcal program, which is used by
the @code{tcal} program to call Gcal.  Takes precedence over the file name
@code{gcal}, which is burned-in during the compilation step of @code{tcal}.

@item GCAL_USR_DATADIR
@cindex Environment variable, @code{GCAL_USR_DATADIR}
@cindex @code{GCAL_USR_DATADIR} environment variable
@cindex Private access resource files
@vindex GCAL_USR_DATADIR
Name of a directory relative to @code{HOME} directory, where user stores
personal respectively @emph{private access} resource files (dates files).
Takes precedence over @w{@code{GCAL_SYS_DATADIR}}.

@item GCAL_SYS_DATADIR
@cindex Environment variable, @code{GCAL_SYS_DATADIR}
@cindex @code{GCAL_SYS_DATADIR} environment variable
@cindex Public access resource files
@vindex GCAL_SYS_DATADIR
Name of a directory absolute @emph{root}/@emph{$(prefix)} directory, where
the system-administrator stores common @emph{public access} resource files
(dates files).

@item HOME
@cindex Environment variable, @code{HOME}
@cindex @code{HOME} environment variable
@vindex HOME
Name of the users home directory (used to find the @file{.gcalrc} file).
Takes precedence over @w{@code{GCALPATH}}, @w{@code{GCAL_USR_DATADIR}} and
@w{@code{GCAL_SYS_DATADIR}}.

@item LANGUAGE
@cindex Environment variable, @code{LANGUAGE}
@cindex @code{LANGUAGE} environment variable
@vindex LANGUAGE
The national language and other cultural-specific conventions used by Gcal
at run-time.  Takes precedence over @w{@code{LC_ALL}}, @w{@code{LC_MESSAGES}}
and @code{LANG}.

@item LC_ALL
@cindex Environment variable, @code{LC_ALL}
@cindex @code{LC_ALL} environment variable
@vindex LC_ALL
The national language and other cultural-specific conventions used by Gcal
at run-time.  Takes precedence over @w{@code{LC_MESSAGES}} and @code{LANG}.

@item LC_MESSAGES
@cindex Environment variable, @code{LC_MESSAGES}
@cindex @code{LC_MESSAGES} environment variable
@vindex LC_MESSAGES
The national language and other cultural-specific conventions used by Gcal
at run-time.  Takes precedence over @code{LANG}.

@item LANG
@cindex Environment variable, @code{LANG}
@cindex @code{LANG} environment variable
@vindex LANG
The national language and other cultural-specific conventions used by Gcal
at run-time.

@item LINES
@itemx LI
@cindex Environment variable, @code{LINES}
@cindex Environment variable, @code{LI}
@cindex @code{LINES} environment variable
@cindex @code{LI} environment variable
@vindex LINES
@vindex LI
Sets the number of lines on the screen.  Takes precedence over the number of
lines specified by the @code{TERM} environment variable or the system itself.

@item PAGER
@cindex Environment variable, @code{PAGER}
@cindex @code{PAGER} environment variable
@vindex PAGER
Name of the @emph{external} pager program, which is used if the
paging option @samp{-p} respectively @samp{--pager} is wanted.

@item PATH
@cindex Environment variable, @code{PATH}
@cindex @code{PATH} environment variable
@vindex PATH
(@samp{:}) colon-separated list of directories which are searched to find the
@emph{external pager} program.  @xref{Global options, , @samp{--pager}}, for
more details.

@item TERM
@cindex Environment variable, @code{TERM}
@cindex @code{TERM} environment variable
@vindex TERM
The type of terminal on which Gcal is being run.

@item TZ
@cindex Environment variable, @code{TZ}
@cindex @code{TZ} environment variable
@vindex TZ
The time zone information, which is added to the date text of send Emails,
created response files and created shell script files.
@end table

@node Error codes, Argument Index, Environment variables, Top
@appendix Error codes
@cindex Error codes
@cindex Exit codes
@cindex Program exit states
@cindex Run-time error codes
@cindex Whitespace character
@cindex Email, error

Gcal produces the following @emph{exit} codes:
@sp 2

@table @code
@item 127
Request for help screen, software license or program version (adjustable).

@item 126
Invalid command line argument / option.

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

@item 124
Virtual memory exhausted.

@item 123
Invalid date part in resource file or in include file.

@item 122
Invalid month field entry in resource file or in include file.

@item 121
Invalid day field entry in resource file or in include file.

@item 120
Malformed @emph{#include} statement in resource file or in include file.

@item 119
Illegal recursive/cyclic @emph{#include} statement in resource file
or in include file.

@item 118
Resource file or include file not found.

@item 117
Invalid @w{@var{n}'th} weekday field (only 1@dots{}5 or 9 valid).

@item 116
Missing @emph{whitespace} separator character between @emph{date part}
and @emph{text part}.

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

@item 114
Invalid date variable operation.

@item 113
Referenced date variable undefined.

@item 112
Invalid date value assigned to date variable.

@item 111
Sending output to Email address fails.

@item 110
Internal error, C function pipe(), fork(), execlp() or unlink() fails.

@item 109
Error reading resource, include respectively response file.

@item 108
Illegal character found in response file.

@item 107
Internal error, invalid value for the size of an internal table occured.

@item 106
Invalid date format text specified.

@item 105
Invalid text variable definition.

@item 1
Activated @w{@samp{-c@r{|}C@r{[]}}} or
@w{@samp{-f@r{|}F @var{name}@r{[}+@dots{}@r{]}}} option
causes no output of resource file entries.
@sp 2

@item 0
Normal program termination.
@end table
@c
@c %**End of manual part



@c %**Start of index part
@c
@node Argument Index, Variable Index, Error codes, Top
@unnumbered Command Line Argument Index
This is an alphabetical list of the command line arguments that Gcal processes.
@printindex ar

@node Variable Index, Concept Index, Argument Index, Top
@unnumbered Environment Variable Index
This is an alphabetical list of the environment variables that Gcal checks.
@printindex vr

@node Concept Index, , Variable Index, Top
@unnumbered Concept Index
@printindex cp
@c
@c %**End of index part



@c %**Start of contents part
@c
@c @summarycontents
@contents
@c
@c %**End of contents part



@bye
