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



@c $Id: gcal.texi v2.40 1997/05/06 02:04:00 tom Exp $
@c
@c gcal.texi:  English Texinfo source of info/dvi file
@c
@c Copyright (C) 1994, 1995, 1996, 1997 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 ------------------------oOO      \\\_''/      OOo---------------------------
@c Thomas Esken               O     (/o-o\)     O  eMail: esken@uni-muenster.de
@c Im Hagenfeld 84                 ((  ^  ))       Phone: +49 251 232585
@c D-48147 Muenster; Germany    \____) ~ (____/    MotD : 2old2live, 2young2die



@c %**Start of header part
@c
@setfilename gcal.info
@c
@c Some necessary constant definitions
@c
@set EDITION 2.40
@set UPDATE-DATE 06 May 1997
@set UPDATE-MONTH May 1997
@set GCAL-VERSION 2.40
@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 %**Start of info dir entry
@c
@dircategory GNU packages
@direntry
* Gcal: (gcal).                       The GNU calendar program.
* tcal: (gcal)Invoking tcal.          Run Gcal with tomorrow's date.
* txt2gcal: (gcal)Invoking txt2gcal.  Convert text file to resource file.
* gcal2txt: (gcal)Invoking gcal2txt.  Convert resource file to text file.
@end direntry
@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 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, 1997 Thomas Esken

This is the second 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      \\\_''/      OOo---------------------------
Thomas Esken               O     (/o-o\)     O  eMail: esken@@uni-muenster.de
Im Hagenfeld 84                 ((  ^  ))       Phone: +49 251 232585
D-48147 Muenster; Germany    \____) ~ (____/    MotD : 2old2live, 2young2die
@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, 1997 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!

@example
@group
@center ------------------------oOO      \\\_''/      OOo---------------------------
@center Thomas Esken               O     (/o-o\)     O  eMail: esken@@uni-muenster.de
@center Im Hagenfeld 84                 ((  ^  ))       Phone:        +49 251 232585
@center D-48147 Muenster; Germany    \____) ~ (____/    MotD : 2old2live, 2young2die
@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 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      \\\_''/      OOo---------------------------
Thomas Esken               O     (/o-o\)     O  eMail: esken@@uni-muenster.de
Im Hagenfeld 84                 ((  ^  ))       Phone: +49 251 232585
D-48147 Muenster; Germany    \____) ~ (____/    MotD : 2old2live, 2young2die
@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 Dates::        How to create a Fixed Date 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.
* Metasymbols::            Metasymbols used in this document.
* Regular Expressions::    Description of all Regular Expressions.
* Regexp Summary::         Summary of all Regular Expressions.
* Special Texts::          Description of all @code{%@var{?}}@dots{} Special Texts.
* Special Texts Summary::  Summary of all @code{%@var{?}}@dots{} Special Texts.
* 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.
* Fixed date options::  How to use Fixed date 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 Dates

* 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 texts processed::       What are @code{%@var{?}}@dots{} Special texts?
* 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.

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.
* Invoking gcal2txt::  How to run @code{gcal2txt} and a summary of its options.

Regular Expressions

* Regexp Usage::      How to Use Regular Expressions.
* Regexp Operators::  Regular Expression Operators.

Special Texts

* Exclusions::     How to Exclude dates.
* Replacements::   How to Replace texts.
* Shell Command::  How to run a Shell Command.

Exclusions

* Exclusions with date argument::
* Exclusions without any argument::

Exclusions with date argument

* Inclusive date period::
* Exclusive date period::

Exclusions without any argument

* Inclusive day period::
* Exclusive day period::

Replacements

* Replacements with date argument::
* Replacements with other argument::
* Replacements without any argument::

Replacements with date argument

* Weekday name::
* Weekday::
* Day number::
* Day::
* Week::
* Month name::
* Month::
* Year::
* Moonphase::
* Biorhythm::
* Difference value::

Replacements with other argument

* Actual time::
* Textual date::
* Julian day number::

Replacements without any argument

* Other difference values::
* Highlighting::

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 occurring 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
at the actual date @footnote{Inclusive or exclusive.}.

There are two ways to display a preview of fixed dates @footnote{Future years.}
or retrospective view of fixed dates @footnote{Past years.}.  On the one hand,
Gcal can be started using an option that 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 that 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 
occurring 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
occurring 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 arguments which can be preloaded if needed.  A
shell script file can be started and calls Gcal directly with all arguments
stored in it, and all arguments which are given further in the command line.

A list of all usable command line arguments and their descriptions can be
found 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 @code{gcal}
@cindex Invoking @code{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 the
@dfn{shell} @footnote{This is an operating system program which interprets
and runs given command lines.} and processes given arguments that 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 incorrect 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.
@xref{Todays Calendar, , Genesis of the Gregorian Calendar},
and
@ref{Internationalization, , Aspects in 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 Options of @code{gcal}
@cindex @code{gcal}, options of
@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
arguments 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 @footnote{Inclusive @samp{%@var{date}} and
@samp{@@@var{file}}.} @strong{must} be given before commands!

@cindex Quotation of special characters
@cindex Depreciation of special characters
@cindex Protection 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 or depreciated by a @samp{\} character to avoid
expansion by the shell.

@sp 2

@noindent
Here is an incomplete list of characters which must potentially be protected:
@sp 2

@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 @code{gcal} options
@cindex Command line options, @code{gcal}

@menu
* Common options::      How to use Common options.
* Global options::      How to use Global options.
* Calendar options::    How to use Calendar options.
* Fixed date options::  How to use Fixed date 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{fixed date option class} control the fixed date 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 @footnote{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 in the following tables, that an option takes
an optional argument.  The @samp{|} character is used to separate several
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 1
@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 chosen 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 1
@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, the 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, on-line
@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, on-line
@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 an @var{argument} is given and it 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 the @var{argument} only consists 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
@cindex Eror code 127
Set the 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

@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 of
@cindex Environment variable, @code{GCAL}
@cindex @code{GCAL} environment variable
@vindex GCAL
Write the contents of the environment variable @code{GCAL}
(@pxref{Environment Variables, GCAL, Environment Variables: @code{GCAL}}),
and then the 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 of
@cindex Environment variable, @code{GCAL}
@cindex @code{GCAL} environment variable
@vindex GCAL
Write the contents of the environment variable @code{GCAL}
(@pxref{Environment Variables, GCAL, Environment Variables: @code{GCAL}}),
and then the arguments of command line (in the given order) to file @var{name},
i.e.@: create shell script file @file{name}.  An automatically created shell
script file is executable and calls Gcal directly with the arguments 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 @w{--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 informational texts if program internal maximums are reached
respectively other conditions have occurred.

@item --debug=handled
@arindex --debug=handled
Like @samp{--debug=internal} and display the file names which can be
processed respectively handled, too.

@item --debug=unhandled
@arindex --debug=unhandled
Like @samp{--debug=internal} and display file names which cannot be
processed respectively handled, 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 an error code if the file name
cannot be handled, respectively other unmanageable conditions have occurred.
@xref{Error Codes}.
@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 contents will be used for
detecting the external pager program.
@xref{Environment Variables, PAGER, Environment Variables: @code{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 contents 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, Environment Variables: @code{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 1
@item
@vindex LINES
@vindex COLUMNS
Gcal respects the values set in the environment variables @code{LINES}
and @code{COLUMNS}.
@xref{Environment Variables, LINES, Environment Variables: @code{LINES}},
and
@ref{Environment Variables, COLUMNS, Environment Variables: @code{COLUMNS}},
for more information.

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

@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, Environment Variables: @code{TERM}}).
This step is only done on systems which support the use of Termcap by default.

On @w{MS-DOS}, OS/2 and some other operating systems, Gcal uses a system
dependent @emph{low-level} function and respects the reported values.

@item
If all above actions have failed, Gcal uses default values
@footnote{Either 23 or 24 lines, and 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
@cindex Forcing highlighting sequences
If the output of the program is redirected @footnote{This means, send
to another device.} or piped @footnote{This means, used as an input data
stream for another program.}, the highlighting sequences are @strong{not}
automatically converted 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.
@xref{Global options, @samp{--mail=@var{address}}, Global options: @samp{--mail=@var{address}}}.

@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
@cindex Disable highlighting sequences
@cindex Disable marking characters
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 Set highlighing sequences
@cindex Marking characters, setting
@cindex Set marking characters
@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
color 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 that define the type of the @sc{ansi} escape sequence.
In this sense, @dfn{marking} characters are single, printable characters which
lead and trail 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 an actual day,
the @strong{second} for a 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 permitted!

For example:

@quotation
@samp{-H \x20:\x20:\x1:#} respectively@*
@samp{--highlighting=\x20:\x20:\x1:#}@*
marks the actual day like @w{@samp{\x20@var{actual date}\x20}}
@footnote{This means with a leading and a trailing blank.} 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-given entries are always skipped).  Please note the last
abstract of this text part which informs you more detailed of this context.
@xref{Environment Variables, GCALANSI, Environment Variables: @code{GCALANSI}},
too.
@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, thus the @samp{:} (colon) character itself,
is used as a 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 Output, redirection of
@cindex Pipeing of output
@cindex Output, pipeing of
If the C Preprocessor symbol @w{USE_PAGER} was defined and the output of
program is redirected or used in a pipe, the highlighting sequences are
automatically converted 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 non-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, Environment Variables: @code{GCALANSI}}.

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

@example
--mail=esken@@uni-muenster.de
@end example

All highlighting sequences produced by Gcal itself are always disabled
respectively automatically converted 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 necessity,
because it is possible that the @code{mail} program cannot perform the mailing
correctly.  Please pay attention in this context to the further explainations
concerning the limitations of the @emph{text part} of a resource file line
(@pxref{Text part of a line}).

@cindex Environment variable, @code{MAILPROG}
@cindex @code{MAILPROG} environment variable
@vindex MAILPROG
If an environment variable @code{MAILPROG} is defined and set, its contents
will be used as the program name of the mailer instead of the standard
@code{mail} program.
@xref{Environment Variables, MAILPROG, Environment Variables: @code{MAILPROG}},
for more information.
@end table

@need 2000
@node Calendar options, Fixed date 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 of eternal holiday list --- this means, all legal
holidays 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 of eternal holiday list --- this means, all legal
holidays 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 holidays only of 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 holidays only of 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
@cindex Suppress title text of eternal holiday list
Suppress the title text line of the eternal holiday list.

@item --without-standard-holidays
@arindex --without-standard-holidays
@cindex Eternal holiday list, without standard holidays in
@cindex Without standard holidays in eternal holiday list
@cindex Eternal holiday list, suppress standard holidays in
@cindex Suppression of standard holidays in eternal holiday list
Suppress all standard holidays in the eternal holiday list.
Furthermore, all days of the eternal holiday list which are highlighted
by default are no longer highlighted in the calendar sheets, too.

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

@item -q @var{cc}@r{[}+@dots{}@r{]}
@itemx --cc-holidays=@var{cc}@r{[}+@dots{}@r{]}
@arindex -q @var{cc}@r{[}+@dots{}@r{]}
@arindex --cc-holidays=@var{cc}@r{[}+@dots{}@r{]}
@cindex Eternal holiday list, country specific holidays in
@cindex Country specific holidays in eternal holiday list
Provide the eternal holiday list additionally with country specific holidays.
Furthermore, all additionally highlighted days of the eternal holiday list
are highlighted in the calendar sheets, too.

@cindex @sc{iso}-3166
@cindex Country code
@cindex Territory code
The @var{cc} argument is a two-letter territory or country 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.

@cindex Separator character, @samp{+}
@cindex @samp{+} separator character
You can use more than one country code @var{cc} by connecting
them with a @samp{+} character, e.g.@::

@quotation
@samp{--cc-holidays=ca+DE+fr+it} resp.,@*
@samp{-q ca+DE+fr+it}
@end quotation

includes all the country specific holidays given in the preceding argument into
the eternal holiday list, i.e.@: Canadian, German, French and Italian holidays.

Actually, Gcal respects the following country codes:

@table @code
@item at
Austria

@item au
Australia

@item be
Belgium

@item ca
Canada

@item ch
Switzerland

@item cz
Czech Republic

@item de
Germany

@item dk
Denmark

@item es
Spain

@item fi
Finland

@item fr
France

@item gb
Great Britain

@item gr
Greece

@item hu
Hungary

@item it
Italy

@item mx
Mexico

@item nl
Netherlands

@item no
Norway

@item pl
Poland

@item pt
Portugal

@item se
Sweden

@item si
Slovenia

@item th
Thailand

@item us
U.S.A.
@end table

@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 output of
@cindex Force output of month calendar sheet
To get the @dfn{standard} calendar format @footnote{Similar
the @w{@sc{bsd}-@code{cal}} program.}, start Gcal omitting the
@w{@samp{-i@r{[}-@r{]}}} option because it is set by default.
@xref{Internationalization, , Aspects in 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 -O
@itemx --orthodox-calendar
@arindex -O
@arindex --orthodox-calendar
@cindex Calendar, leap year rule as used by Eastern churches
@cindex Use Eastern orthodox churches' leap year rule
@cindex Eastern churches' leap year rule, using
@cindex Leap year rule as used by Eastern orthodox churches
Use the leap year rule as used by the Eastern orthodox churches.

Without specifying the @code{--orthodox-calendar} option, Gcal is unable to
display Gregorian years later than 2799 in the correct way for the Eastern
churches, because they use a different scheme for calculating the leap years.
The method for computing leap years within the common Gregorian calendar,
which Gcal uses by default, is as follows:

@quotation
A leap year is any year, which number can be divided by 4 without a remainder,
and years ending in hundrets are no leap years unless they are divisible by
400.
@end quotation

But the Eastern orthodox churches compute leap years within the Gregorian
calendar by using another rule:

@quotation
A leap year is any year, which number can be divided by 4 without a remainder,
and years ending in hundrets are leap years, if a remainder of 2 or 6 occurs
when such a year is divided by 9.
@end quotation

The first difference therefore occurs in the year 2800, which is a leap year
in the common Gregorian calendar, but an ordinary year only in the calendar
as used by the Eastern orthodox churches.

@item -K
@itemx --with-week-number
@arindex -K
@arindex --with-week-number
@cindex Calendar sheet, provide with week numbers
@cindex Provide calendar sheet with week numbers
@cindex Week numbers in calendar sheet
@cindex @sc{iso}-8601:1988
Provide the calendar sheet with @sc{iso}-8601:1988 week numbers.

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

If the starting day of week is not set to Monday
(@pxref{Calendar options, @samp{--starting-day=@var{argument}}, Calendar options: @samp{--starting-day=@var{argument}}}),
the week numbers are not represented correctly in most cases.  If you use
this option, you should take care of setting Monday as the starting day of
the week!
@xref{Internationalization, , Aspects in Internationalization},
for more details.

@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 Number of year calendar sheet blocks
@cindex Year calendar sheet, force output of
@cindex Force year calendar sheet
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{]}}, 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 list
@cindex Fixed date list, alternative date format in
Use alternative date format in fixed date list instead of the default
standard format which displays the days of month in consecutive manner.
@xref{Fixed date options, @samp{--list-of-fixed-dates@r{[}=short@r{|}long@r{]}}, Fixed date 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 list
@cindex Fixed date list, special date format in
Display the fixed date 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 list
@cindex Fixed date list, standard and special date format in
Display the fixed date 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
@cindex Set starting day of week
Set the starting day of week (valid @var{argument}:
@w{@samp{0@r{,} 1@r{@dots{}}7 @r{|} today @r{|} @var{weekday name}}).}

For example:

@example
@group
--starting-day=Sunday @r{or}
--starting-day=7 @r{or}
-s SUNDAY @r{or}
-s sund @r{or}
-sSu @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 which is delivered by the system date.

@xref{Internationalization, , Aspects in Internationalization},
for more details.

@item --gregorian-reform=1582@r{|}1700@r{|}1752@r{|}1753@r{|}@var{argument}
@arindex @w{--gregorian-reform=1582@r{|}1700@r{|}1752@r{|}1753@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, , Aspects in Internationalization},
for more details.  Actually, four fixed default periods are supported,
and that of the year 1582, of the year 1700, of the year 1752 and of
the year 1753.

If Gcal is called with the @w{@samp{--gregorian-reform=1582}} option, it
assumes the Gregorian Reformation have occurred from 5th till 14th October
1582.

If Gcal is called with the @w{@samp{--gregorian-reform=1700}} option, it
assumes the Gregorian Reformation have occurred from 19th till 28th February
1700.

If Gcal is called with the @w{@samp{--gregorian-reform=1752}} option, it
assumes the Gregorian Reformation have occurred from 3rd till 13th September
1752.

If Gcal is called with the @w{@samp{--gregorian-reform=1753}} option, it
assumes the Gregorian Reformation have occurred from 18th till 28th February
1753.

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

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

Please note that it is possible to corrupt the calendars likewise the fixed
date feature logically (which works correctly now for the year in which the
Gregorian Reformation have occured) if @var{argument} is not used with care.

@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, , Aspects in Internationalization},
for more details.  The date format text is respected by Gcal in the eternal
holiday list, in the fixed date 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 are supported, and that
for German users, U.S.@: American users and for users in Great Britain.

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
@footnote{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 currently 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 zero

@item %M
Month number with leading space
@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 zero

@item %Z
Last two digits of year number with leading space
@end table

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 Fixed date options, , Calendar options, Options
@subsubsection Fixed date options
@cindex Fixed date 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 @var{argument} must either be a valid single date variable
definition or a (@samp{:}) colon-connected series of definitions.

A date variable name @var{dvar} consists of a single, case-insensitive letter
@footnote{Except the date variable @var{e} that is internally reserved for the
Easter Sunday's date, so it cannot be assigned or operated therefore.  And
except the date variable @var{t} that is internally reserved for today's date,
so it likewise cannot be assigned or operated.}, 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 @footnote{Or
another global date variable name, but @strong{no} date given in the
@samp{@var{mm}@var{www}@var{n}},
@samp{e@r{|}t@r{|}@var{dvar}@r{[}+@r{|}-@r{]}@var{n}@r{[}@var{www}@r{]}} or the
@samp{*d@r{|}w@var{n}@r{[}@var{www}@r{]}} format.}.

For example:

@quotation
@samp{--date-variable=a=1127:c=a} respectively@*
@samp{-v a=1127:c=a}@*
stores the 27th November into the global date variable @var{a}
and into 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
Effects 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 @var{argument} must either be a valid single text variable
definition or a (@samp{:}) colon-connected series of definitions.

A text variable name @var{tvar} consists of the @samp{$} prefix and a single,
case-insensitive letter, 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 side of the assignment operator character.

For example:

@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 Depreciation of special characters
@cindex Depreciation character, @samp{\}
@cindex @samp{\} depreciation character
@cindex Protection of special characters
@cindex Protection character, @samp{\}
@cindex @samp{\} protection character
You may depreciate the special meaning of the @samp{:} separator character
--- in case this character itself is needed --- by placing a @samp{\}
(backslash) character before it, e.g.@: @samp{\:}.  If you need the @samp{\:}
characters themselves, you have to protect the @samp{\} (backslash) character
by itself, e.g.@: @samp{\\:}.

@cindex Depreciation of special characters
@cindex Depreciation character, @samp{\}
@cindex @samp{\} depreciation character
@cindex Protection of special characters
@cindex Protection character, @samp{\}
@cindex @samp{\} protection character
You may depreciate the special meaning of the @samp{$} prefix character
--- in case this character itself is needed in the text --- by placing a
@samp{\} (backslash) character before it, e.g.@: @samp{\$}.  If you need
the @samp{\$} characters themselves in the text, you have to protect 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 Depreciation of special characters
@cindex Depreciation character, @samp{\}
@cindex @samp{\} depreciation character
@cindex Protection of special characters
@cindex Protection character, @samp{\}
@cindex @samp{\} protection character
You may depreciate the special meaning of the @samp{_} (underscore) character
--- in case this character itself is needed --- by placing a @samp{\}
(backslash) character before it, e.g.@: @samp{\_}.  If you need the @samp{\_}
themselves, you have to protect 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
Effects the export of local text variables from
one resource file to another resource file.
@xref{Text variables},
for more details.

@item -D @var{argument}
@itemx --filter-day=@var{argument}
@arindex -D @var{argument}
@arindex --filter-day=@var{argument}
@cindex Filtration, days of fixed dates
@cindex Fixed dates, filtration of days
Displays only those fixed dates, whose date is not excluded
by the given @var{argument}.
@xref{Date part of a line},
and likewise
@ref{Exclusions without any argument, , Exclusions without any argument @code{%@var{?}} special texts}.
The @var{argument} consists of one or more characters as used in the exclusion
without any argument @code{%@var{?}} special text; but without the leading
@samp{%} character in each case.

For example, it is possible to induce Gcal to display only those fixed dates
from the resource file @file{demo.rc} for the whole year, which are legals
holidays, and moreover, Saturdays or Sundays:

@example
gcal -f demo.rc --year --filter-day=Rv
@end example

@item -P @var{argument}
@itemx --filter-period=@var{argument}
@arindex -P @var{argument}
@arindex --filter-period=@var{argument}
@cindex Filtration, periods of fixed dates
@cindex Fixed dates, filtration of periods
Displays only those fixed dates, whose date is not excluded
by the given @var{argument}.
@xref{Date part of a line},
and likewise
@ref{Exclusions with date argument, , Exclusions with date argument @code{%@var{?}@r{[}@var{date}@r{]}} special texts}.
The @var{argument} consists of one or more expressions as used in the exclusion
with date argument @code{%@var{?}@r{[}@var{date}@r{]}} special text; but without
the leading @samp{%} character in each case.  You can use more than one of these
@code{%@var{?}@r{[}@var{date}@r{]}} expressions by connecting them with a
@samp{,} character.

For example, it is possible to induce Gcal to display only those fixed dates
from the resource file @file{demo.rc} for the whole year, which appear within
the period of the 17th and the 20th of any month, and which appear on the 31st
of any month.

@example
gcal -f demo.rc -y -P i00000017#00000020,i00000031#00000031
@end example

@item -I @var{pattern}
@itemx --filter-text=@var{pattern}
@arindex -I @var{pattern}
@arindex --filter-text=@var{pattern}
@cindex Filtration, fixed date texts
@cindex Fixed date texts, filtration of
@cindex Regular Expression
@cindex Line break up character, @samp{~}
@cindex @samp{~} line break up character
@cindex Line break up character, @samp{^}
@cindex @samp{^} line break up character
Displays only those fixed dates, whose completely expanded text
@footnote{Except Gcal's line break up characters @samp{~} and @samp{^},
so you have to use @samp{\~} and @samp{\\^} in the @var{pattern}
argument if you want to search texts which contain these characters.}
contains the given @var{pattern}.
@xref{Text part of a line},
and
@ref{Replacements, , @code{%@var{?}}@dots{} special texts for text replacement}.
The @var{pattern} is a @emph{regular expression},
as recognized by the Unix @code{ed} line-editor.
@xref{Regular Expressions},
for more information.

For example, it is possible to induce Gcal to display all fixed dates from
the resource file @file{doctor.rc} for the current month, which are defined
for dentists or oculists:

@example
gcal -f doctor.rc --month -I "[dD]entist|[oO]culist"
@end example

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

@cindex Depreciation of special characters
@cindex Depreciation character, @samp{\}
@cindex @samp{\} depreciation character
@cindex Protection of special characters
@cindex Protection character, @samp{\}
@cindex @samp{\} protection character
You may depreciate the special meaning of the @samp{_} (underscore) character
--- in case this character itself is needed --- by placing a @samp{\}
(backslash) character before it, e.g.@: @samp{\_}.  If you need the @samp{\_}
characters themselves, you have to protect the @samp{\} (backslash) character
by itself, e.g.@: @samp{\\_}.

@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 Fixed date, option
@cindex Fixed dates
@cindex Fixed date period long-style option, @samp{--today}
@cindex Today's fixed dates
@cindex Fixed dates for @emph{today}
@cindex Activate fixed date function
@cindex Fixed date function, activate
Activate the fixed date function and display fixed date messages, if any.

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

@need 1000
@item -c-
@itemx --descending-fixed-dates=short
@arindex -c-
@arindex --descending-fixed-dates=short
@cindex Error code 1
@cindex Exit code 1
Activate fixed date function (use standard resource file implicitly) and
list all dates related to the actual system date (@equiv{}today), sorted in
descending order.  If no fixed dates related to the current day are found, no
fixed date messages are displayed and the program is terminated with an error
code.
@xref{Error Codes, 1, Error Codes: 1}.

@need 1000
@item -C
@itemx --list-of-fixed-dates=long
@arindex -C
@arindex --list-of-fixed-dates=long
Activate fixed date function (use standard resource file implicitly) and
list all dates related to the actual system date (@equiv{}today), sorted in
ascending order.  If no fixed dates related to the current day are found, an
``empty'' fixed date message only consisting of the date is displayed.

@need 1000
@item -C-
@item --descending-fixed-dates=long
@arindex -C-
@arindex --descending-fixed-dates=long
Activate fixed date function (use standard resource file implicitly) and
list all dates related to the actual system date (@equiv{}today), sorted in
descending order.  If no fixed dates related to the current day are found, an
``empty'' fixed date message only consisting of the date is displayed.
@end table

@item -f@r{|}F @var{name}@r{[}+@dots{}@r{]}
@itemx --resource-file=@var{name}@r{[}+@dots{}@r{]}
@arindex -f@r{|}F @var{name}@r{[}+@dots{}@r{]}
@arindex --resource-file=@var{name}@r{[}+@dots{}@r{]}
@cindex Resource file, additional
@cindex Additional resource file
@cindex Resource file, other
@cindex Other resource file
@cindex Activate fixed date function
@cindex Fixed date function, activate
@cindex Error code 1
@cindex Exit code 1
Activate fixed date 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 period.  If no other fixed date period is specified, the actual
system date (@equiv{}today) is used for the fixed date period.  If the option
letter @samp{f} of the short-style option is used and no dates related to the
fixed date period are found in @var{name}, no fixed date messages are displayed
and the program is terminated with an error code.
@xref{Error Codes, 1, Error Codes: 1}.
If the option letter @samp{F} of the short-style option is used and no dates
related to the fixed date period are found in @var{name}, an ``empty''
fixed date message only consisting of the date is displayed.

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

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

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

@cindex Depreciation of special characters
@cindex Depreciation character, @samp{\}
@cindex @samp{\} depreciation character
@cindex Protection of special characters
@cindex Protection character, @samp{\}
@cindex @samp{\} protection character
You may depreciate the special meaning of the @samp{+} separator character
--- in case this character itself is needed --- by placing a @samp{\}
(backslash) character before it, e.g.@: @samp{\+}.  If you need the @samp{\+}
characters themselves, you have to protect 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 Depreciation of special characters
@cindex Depreciation character, @samp{\}
@cindex @samp{\} depreciation character
@cindex Protection of special characters
@cindex Protection character, @samp{\}
@cindex @samp{\} protection character
You may depreciate the special meaning of the @samp{_} (underscore) character
--- in case this character itself is needed --- by placing a @samp{\}
(backslash) character before it, e.g.@: @samp{\_}.  If you need the @samp{\_}
characters themselves, you have to protect the @samp{\} (backslash) character
by itself, e.g.@: @samp{\\_}.

@item -# @var{line}
@itemx --here=@var{line}
@arindex -# @var{line}
@arindex --here=@var{line}
@cindex Resource file line, additional
@cindex Additional resource file line
@cindex Resource file line, further
@cindex Further resource file line
@cindex Activate fixed date function
@cindex Fixed date function, activate
@cindex Error code 1
@cindex Exit code 1
Activate fixed date function and use the @var{line} argument together with
the standard resource file respectively additional resource files.  The
@var{line} argument has to be a valid logical line as it may occur in a
Gcal resource file
(@pxref{Structure of resource file}),
and is always evaluated at last @strong{after} the processing of all resource
files, which allows the dealing with references to exported local date or
text variables.  This option may be given multiple and it will be processed
exactly in the given order.  All dates are listed, sorted in ascending order,
which occur in the fixed date period.  If no other fixed date period is
specified, the actual system date (@equiv{}today) is used for the fixed date
period.  If no dates related to the fixed date period are found in the
@var{line}, no fixed date messages are displayed and the program is
terminated with an error code.
@xref{Error Codes, 1, Error Codes: 1}.

For example, the call:

@example
gcal -# "0*d1su#99su.7 ^%:" --here="#include <foo>" -y
@end example

effects the implicit processing of the standard resource file just before
the further resource file line @samp{0*d1su#99su.7 ^%:} and following
@samp{#include <foo>} are processed, and that as if these lines were a
physical part of the standard resource file.

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

@cindex Depreciation of special characters
@cindex Depreciation character, @samp{\}
@cindex @samp{\} depreciation character
@cindex Protection of special characters
@cindex Protection character, @samp{\}
@cindex @samp{\} protection character
You may depreciate the special meaning of the @samp{_} (underscore) character
--- in case this character itself is needed --- by placing a @samp{\}
(backslash) character before it, e.g.@: @samp{\_}.  If you need the @samp{\_}
characters themselves, you have to protect 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 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{B},
@samp{e@r{|}E},
@samp{k},
@samp{o},
@samp{U},
@samp{x},
@samp{z},
@samp{Z}

@item Second step: @emph{Period-of-fixed-dates-modifier}
@cindex Period-of-fixed-dates-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{|}t@r{|}@var{dvar}@r{[[}+@r{|}-@r{]}@var{n}@r{]}},}
@w{@samp{@@e@r{|}t@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

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

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

@cindex Fixed date period modifier, @samp{d}
@cindex Fixed date period modifier, @samp{l}
@cindex Fixed date period option, @samp{--leap-day=february@r{|}march}
@noindent
and only @strong{one} period defining fixed date period modifier
may be given @footnote{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}
option.}.

@cindex Single character options
@cindex Options, single character
@cindex Single command line word
@cindex Command line word, single
Or on the other hand, 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{]}}},
@w{@samp{-f@r{|}F @var{name}@r{[}+@dots{}@r{]}}} or
@w{@samp{-# @var{line}}}
@footnote{Respectively their according long-style options.} must be given like:

@example
@group
-c -t
-w- -c
-a -ABd -e -kloUxz -C12+
-F foo.bar -dZA -l*d10
--here="; Comment" -dZAa
@end group
@end example

@need 1500
@cindex Single character options
@cindex Options, single character
@cindex Single command line word
@cindex Command line word, single
@cindex Fixed date, option
@cindex Fixed dates
@cindex Activate fixed date function
@cindex Fixed date function, activate
If the 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 @footnote{Or their according alias names like @samp{--today},
@samp{--tomorrow}@dots{}}, it is unnecessary to give a
@w{@samp{-c@r{|}C@r{[}-@r{]}}} respectively
@w{@samp{-f@r{|}F @var{name}@r{[}+@dots{}@r{]}}} short-style option
@footnote{Or their according long-style options.} to activate the fixed
date function of Gcal, because it is triggered implicitly by means of
these modifiers / alias names.

@xref{Coding Scheme},
whose 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 enabling the fixed date feature --- 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} argument is given, it respects only those entries
which have a definite relation to the @emph{fixed date} argument to
avoid the output of redundant information!

@page
@cindex Fixed date text modifiers
@cindex Modifiers, fixed date text
@cindex Options, fixed date text
@noindent
@strong{Fixed date text modifiers and options:}

@table @samp
@item --biorhythm-axis=@var{number}
@arindex --biorhythm-axis=@var{number}
@cindex Fixed date text option, @samp{--biorhythm-axis=@var{number}}
The width of the biorhythm text graphics --- which can be created by means of
the biorhythm text graphics @code{%;@r{[}@var{date}@r{]}} special text --- is
changed to @var{number} characters for each axis of the bar.  The @var{number}
argument must be an integer value between 1@dots{}100, the default number of
characters is 20.  If the @var{number} divides 100 with a remainder, it is
internally reduced to the nearest number that divides 100 without any remainder.
This means, only the numbers 1, 2, 4, 5, 10, 20, 25, 50 and 100 are factually
respected, so a @var{number} argument of 19 is internally reduced to 10.

For example:

@example
@group
@cartouche
$ cat bio.rc
@print{} 0*d1#999 %;19620921
$ gcal -f bio.rc %19961212 -s0 -xw --biorhythm-axis=19
@print{}
@print{} Thu, Dec <12th>1996: 0- I       P1 E        +0
@print{} Fri, Dec  13th 1996: 0-  I   P   1          +0
@print{} Sat, Dec  14th 1996: 0-    @@   E 0          +0
@print{} Sun, Dec  15th 1996: 0-  P  IE   0          +0
@print{} Mon, Dec  16th 1996: 0- P  E  I  0          +0
@print{} Tue, Dec  17th 1996: 1-P  E     I0          +0
@print{} Wed, Dec  18th 1996: 0- @@        1          +0
@end cartouche
@end group
@end example

@xref{Biorhythm, , Biorhythm @code{%@var{?}@r{[}@var{date}@r{]}} special texts},
for more details.

@item --moonimage-lines=@var{number}
@arindex --moonimage-lines=@var{number}
@cindex Fixed date text option, @samp{--moonimage-lines=@var{number}}
The height of the moonphase text graphics --- which can be created by means of
the moonphase text graphics @code{%:@r{[}@var{date}@r{]}} special text --- is
changed to @var{number} lines.  The @var{number} argument must be an integer
value between 6@dots{}30, the default number of lines is 12.

@page
For example:

@example
@group
@cartouche
$ gcal -f/dev/null -#0*d1#999_%:__%- %19950308 -x --moon=8
@print{}
@print{} Wed, Mar < 8th>1995:          (    @@@@@@@@@@
@print{}                          (           @@@@@@@@@@@@@@@@
@print{}                       (               @@@@@@@@@@@@@@@@@@@@
@print{}                      (                @@@@@@@@@@@@@@@@@@@@@@
@print{}                      (                @@@@@@@@@@@@@@@@@@@@@@
@print{}                       (               @@@@@@@@@@@@@@@@@@@@
@print{}                        (             @@@@@@@@@@@@@@@@@@@@
@print{}                            (        @@@@@@@@@@@@@@ 41%+
@end cartouche
@end group
@end example

@xref{Moonphase, , Moonphase @code{%@var{?}@r{[}@var{date}@r{]}} special texts},
for more details.

@item a
@itemx --include-resource-file-name
@arindex -a
@arindex -ca
@arindex --include-resource-file-name
@cindex Fixed date text modifier, @samp{a}
Extend fixed date text by the name of the resource file,
which the fixed date 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 Fixed date 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 B
@itemx --bypass-shell-command
@arindex -B
@arindex -cB
@arindex --bypass-shell-command
@cindex Fixed date text modifier, @samp{B}
@cindex Shell
Don't execute shell command @code{%!@r{[}@var{argument}@r{]}} special texts,
display them textually only.
@xref{Shell Command, , Shell command @code{%!@r{[}@var{argument}@r{]}} special text},
for more details.

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

@item E
@itemx --include-holidays=short
@arindex -E
@arindex -cE
@arindex --include-holidays=short
@cindex Fixed date text modifier, @samp{E}
Enable inclusion of those built-in eternal holiday dates which are legal
holidays 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 Fixed date text modifier, @samp{g@r{[}@var{text}@r{]}}
Group fixed dates by day using the @var{text} separator.  If @var{text} is
not given, the built-in @var{text} @footnote{@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 up
@cindex Line break up character, @samp{~}
@cindex @samp{~} line break up character
Each time a @samp{~} (tilde) character is found in @var{text}, this
character is replaced by a real @samp{\n} (newline) character.

@cindex Depreciation of special characters
@cindex Depreciation character, @samp{\}
@cindex @samp{\} depreciation character
@cindex Protection of special characters
@cindex Protection character, @samp{\}
@cindex @samp{\} protection character
You may depreciate the special meaning of the @samp{~} (tilde) character
--- in case this character itself is needed --- by placing a @samp{\}
(backslash) character before it, e.g.@: @samp{\~}.  If you need the @samp{\~}
characters themselves, you have to protect 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 Depreciation of special characters
@cindex Depreciation character, @samp{\}
@cindex @samp{\} depreciation character
@cindex Protection of special characters
@cindex Protection character, @samp{\}
@cindex @samp{\} protection character
You may depreciate the special meaning of the @samp{_} (underscore) character
--- in case this character itself is needed --- by placing a @samp{\}
(backslash) character before it, e.g.@: @samp{\_}.  If you need the @samp{\_}
characters themselves, you have to protect the @samp{\} (backslash) character
by itself, e.g.@: @samp{\\_}.

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

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

@item o
@itemx --omit-multiple-date-part
@arindex -o
@arindex -co
@arindex --omit-multiple-date-part
@cindex Fixed date text modifier, @samp{o}
Omit displaying the leading date of a fixed date message in case more than one
message refers to that date @footnote{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 U
@itemx --suppress-date-part
@arindex -U
@arindex -cU
@arindex --suppress-date-part
@cindex Fixed date text modifier, @samp{U}
Suppress displaying the leading date of a fixed date message, e.g.@:: 

@example
@group
@cartouche
$ gcal -cU
@print{}
@print{} 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 Fixed date text modifier, @samp{x}
@cindex Fixed date list, suppression of title text
@cindex Suppress title text of fixed date list
Suppress the title text line of the fixed date list.

@item z
@itemx --include-consecutive-number
@arindex -z
@arindex -cz
@arindex --include-consecutive-number
@cindex Fixed date text modifier, @samp{z}
Display consecutive numbers of fixed date messages.

@item Z
@itemx --zero-dates-only
@arindex -Z
@arindex -cZ
@arindex --zero-dates-only
@cindex Fixed date text modifier, @samp{Z}
Display only those dates, for which fixed dates doesn't exist,
i.e.@: all ``empty'' fixed dates only consisting of the date.
@end table

@page
@cindex Fixed date period modifiers and options
@cindex Modifiers, fixed date period
@cindex Options, fixed date period
@noindent
@strong{Fixed date period modifiers and options:}

@table @samp
@item --leap-day=february@r{|}march
@arindex --leap-day=february@r{|}march
@cindex Fixed date period option, @samp{--leap-day=february@r{|}march}
@cindex Leap day
The @dfn{leap day} @footnote{The 29th February.} is observed in non-leap years.

@table @samp
@item --leap-day=february
@arindex --leap-day=february
@cindex Fixed date period option, @samp{--leap-day=february}
@cindex Move leap day to 28th February
A fixed date that 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 Fixed date period option, @samp{--leap-day=march}
@cindex Move leap day to 1st March
A fixed date that 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 Fixed date period modifier, @samp{d}
If lists of periods are generated, include the actual date into the list.
@xref{Fixed date options, @samp{--list-mode}, Fixed date 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 Fixed date 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 assumes the actual system date is the
@strong{17th February of any year} (00000217).
@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 Fixed date period modifier, @samp{@var{n}d}
@cindex Fixed date period modifier, @samp{*d@var{n}}
Single date of absolute day @w{@var{n} @equiv{} @samp{1@dots{}365@r{|}366@r{|}999}}
of the actual year; the intensity level is the same as the 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 Fixed date period modifier, @samp{l@var{n}d}
@cindex Fixed date 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 the
actual year; the intensity level is the same as the @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

@page
@item @samp{@var{n}+@r{|}-}
@arindex -c@var{n}+@r{|}-
@cindex Fixed date 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 the actual year; the intensity level is the same as the 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 Fixed date 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 the actual year; the intensity level is the same as the @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 Fixed date 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 the actual year; the intensity level is the same as the @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 occurring 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.

@cindex Error code 126
@cindex Exit code 126
@item
E.g.@: @samp{gcal -c53w} displays all fixed dates which occur
in the 53rd @sc{iso}-week of the 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 messages are displayed and the program is terminated with an error code.
@xref{Error Codes, 126, 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 Fixed date 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 intensity level is the same as the @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 Fixed date period modifier, @samp{@var{mm}@var{dd}}
Single date of day @var{dd} in month @var{mm} of the actual year;
the intensity level is the same as the 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 Fixed date 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 the actual
year; the intensity level is the same as the @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 Fixed date 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 the actual year;
the intensity level is the same as the 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 Fixed date 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
the actual year; the intensity level is the same as the @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 Fixed date 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 the actual year; the intensity level is the same as the
simple @samp{-c} option.

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

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

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

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

@page
@item @samp{l*d@var{n}@var{www}}
@arindex -l*d@var{n}@var{www}
@arindex -cl*d@var{n}@var{www}
@cindex Fixed date 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 the actual year; the intensity level is the same as the
@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 the actual year.

@cindex Error code 126
@cindex Exit code 126
@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 the actual year.  If the
actual year has no 52nd Sunday, no fixed date messages are displayed and the
program is terminated with an error code.
@xref{Error Codes, 126, Error Codes: 126}.

@cindex Error code 126
@cindex Exit code 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 the actual year.  If the
actual year has no 53nd Sunday, no fixed date messages are displayed and the
program is terminated with an error code.
@xref{Error Codes, 126, 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 @footnote{That's either the
51st, 52nd or 53rd Sunday.} of the 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 Fixed date 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 the actual year; the intensity level is the same as the simple
@samp{-c} option.  If no weekday @var{www} is given, then Monday is assumed
for the weekday.

@itemize @bullet
@cindex Error code 126
@cindex Exit code 126
@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 messages are displayed and
the program is terminated with an error code.
@xref{Error Codes, 126, 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 the actual year.

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

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

@item
E.g.@: @samp{gcal -c*w99sun} displays all fixed dates which occur on
Sunday of the last @sc{iso}-week @footnote{That's either the 52nd or
53rd @sc{iso}-week.} of the 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 Fixed date 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 the actual year; the intensity level is the same as the
@samp{-cy} option.  If no weekday @var{www} is given, then Monday is assumed
for the weekday.

@itemize @bullet
@cindex Error code 126
@cindex Exit code 126
@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 messages are displayed and the program is terminated with an error
code.
@xref{Error Codes, 126, 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.

@cindex Error code 126
@cindex Exit code 126
@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 messages are displayed and the program is terminated with an error code.
@xref{Error Codes, 126, Error Codes: 126}.

@cindex Error code 126
@cindex Exit code 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 messages are displayed and the program is terminated with an error code.
@xref{Error Codes, 126, 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
@footnote{That's either the 52nd or 53rd @sc{iso}-week.} of the 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 Fixed date period modifier, @samp{@@e@r{[[}+@r{|}-@r{]}@var{n}@r{]}}
Single date of day @var{n} relative to the Easter Sunday's date of the actual
year; the intensity level is the same as the 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

@page
@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 Fixed date 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 the actual year; the intensity level is the same as the
@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 Fixed date 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 the actual year; the intensity level is the same as the 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

@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 Fixed date 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 the actual year; the intensity level is the same
as the @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{@@t@r{[[}+@r{|}-@r{]}@var{n}@r{]}}
@arindex -@@t@r{[[}+@r{|}-@r{]}@var{n}@r{]}
@arindex -c@@t@r{[[}+@r{|}-@r{]}@var{n}@r{]}
@cindex Fixed date period modifier, @samp{@@t@r{[[}+@r{|}-@r{]}@var{n}@r{]}}
Single date of day @var{n} relative to today's date of the actual year;
the intensity level is the same as the simple @samp{-c} option.

@itemize @bullet
@item
E.g.@: @samp{gcal -c@@t} displays all fixed dates which occur
on today's date (@equiv{} @samp{gcal -c}).

@item
E.g.@: @samp{gcal -c@@t10} respectively @samp{gcal -c@@t+10} displays all
fixed dates which occur 10 days after today's date (@equiv{} @samp{gcal -c10+}).

@item
E.g.@: @samp{gcal -c@@t-10} displays all fixed dates which occur
10 days before today's date (@equiv{} @samp{gcal -c10-}).
@end itemize

@page
@item @samp{l@@t@r{[[}+@r{|}-@r{]}@var{n}@r{]}}
@arindex -l@@t@r{[[}+@r{|}-@r{]}@var{n}@r{]}
@arindex -cl@@t@r{[[}+@r{|}-@r{]}@var{n}@r{]}
@cindex Fixed date period modifier, @samp{l@@t@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 today's date of the
actual year; the intensity level is the same as the @samp{-cy} option.

@itemize @bullet
@item
E.g.@: @samp{gcal -cl@@t} displays nothing.

@item
E.g.@: @samp{gcal -cl@@t10} respectively @samp{gcal -cl@@t+10} displays a list
of all fixed dates which start on the 18th February and end 10 days after
today's date (@equiv{} @samp{gcal -cl10+}).

@item
E.g.@: @samp{gcal -cl@@t-10} displays a list of all fixed dates which start
on the 18th February and end 10 days before today's date
(@equiv{} @samp{gcal -cl10-}).
@end itemize

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

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

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

@need 1500
@item @samp{l@@t@r{[}+@r{|}-@r{]}@var{n}@var{www}}
@arindex -l@@t@r{[}+@r{|}-@r{]}@var{n}@var{www}
@arindex -cl@@t@r{[}+@r{|}-@r{]}@var{n}@var{www}
@cindex Fixed date period modifier, @samp{l@@t@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
today's date of the actual year; the intensity level is the same as the
@samp{-cy} option.

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

@item
E.g.@: @samp{gcal -cl@@t-3fri} displays a list of all fixed dates which start
on the 18th February and end on the 3rd Friday before today'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 Fixed date period modifier, @samp{@@@var{dvar}@r{[[}+@r{|}-@r{]}@var{n}@r{]}}
Single date of day @var{n} relative to date variables date of the actual year;
the intensity level is the same as the 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

@page
@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 Fixed date 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 the actual year; the intensity level is the same as the @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 Fixed date 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 the actual year; the intensity level is the same as the 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 Fixed date 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 the actual year; the intensity level is the same as
the @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 Fixed date period modifier, @samp{t@r{|}T}
@cindex Fixed date period long-style option, @samp{--tomorrow}
@cindex Fixed dates for @emph{tomorrow}
@cindex Tomorrow's fixed dates
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

@page
@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 Fixed date period modifier, @samp{w@r{|}W@r{[}+@r{|}-@r{]}}
@cindex Fixed date period long-style option, @samp{--week}
@cindex Fixed date period long-style option, @samp{--end-of-week}
@cindex Fixed date period long-style option, @samp{--start-of-week}
@cindex Fixed dates for the @emph{week}
@cindex Week's fixed dates
Display dates related to the week.@*
@xref{Calendar options, @samp{--starting-day@r{[}=@var{argument}@r{]}}, 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 Fixed date period modifier, @samp{m@r{|}M@r{[}+@r{|}-@r{]}}
@cindex Fixed date period long-style option, @samp{--month}
@cindex Fixed date period long-style option, @samp{--end-of-month}
@cindex Fixed date period long-style option, @samp{--start-of-month}
@cindex Fixed dates for the @emph{month}
@cindex Month's fixed dates
Display dates related to the month.

@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-style 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 Fixed date period modifier, @samp{y@r{|}Y@r{[}+@r{|}-@r{]}}
@cindex Fixed date period long-style option, @samp{--year}
@cindex Fixed date period long-style option, @samp{--end-of-year}
@cindex Fixed date period long-style option, @samp{--start-of-year}
@cindex Fixed dates for the @emph{year}
@cindex Year's fixed dates
Display dates related to the year.

@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}} response file
@cindex Option @samp{@@@var{file}}
@cindex @samp{@@@var{file}}, Option
@cindex Quotation of special characters
@cindex Depreciation of special characters
@cindex Protection of special characters
@arindex @@@var{file}

If a @samp{@@@var{file}} option is given in the command line, a @dfn{response
file} by the name of @var{file} will be used, i.e.@: options and commands are
preloaded from that file.  A response @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}}, 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, Resource file: File searching mechanism},
for more details.  Multiple response files may be given in the command line
when Gcal is started, and they 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.

@noindent
For example:

@enumerate 1
@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

@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

@page
@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}} actual date modifier
@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, fixed dates can be
checked for @strong{any} year and are respected in the same way, as if they
would be fixed dates of the actual year.

@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}@var{n}@r{]]}}}

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

@item
@w{@code{@var{yyyy}@@e@r{|}t@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:}@*
The following examples assumes the actual system date is
@strong{Wednesday, the 17th February 1993} (19930217)!
@end quotation

@table @asis
@item The @code{@var{yyyy}@r{[}@var{mm}@r{[}@var{dd}@r{|}@var{www}@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.}

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

@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{|}t@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.}

@page
@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 %1994@@t} @w{(@equiv{} @code{@var{yyyy}@@t})}@*
The actual date is set to today's date in 1994
@w{@result{} 199400217.}

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

@item
@samp{gcal %1994@@t+10} @w{(@equiv{} @code{@var{yyyy}@@t@r{[}+@r{]}@var{n}})}@*
The actual date is set to the date 10 days after today's date in 1994
@w{@result{} 19940227.}

@item
@samp{gcal %1994@@t-10} @w{(@equiv{} @code{@var{yyyy}@@e-@var{n}})}@*
The actual date is set to the date 10 days before today's date in 1994
@w{@result{} 19940207.}

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

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

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

@item
@samp{gcal %0000@@t} @w{(@equiv{} @code{@var{yyyy}@@t})}@*
The actual date is set to today's date
@w{@result{} 19930217.}

@page
@item
@samp{gcal %0@@t10}

@item
@samp{gcal %0@@t+10} @w{(@equiv{} @code{@var{yyyy}@@t@r{[}|@r{]}@var{n}})}@*
The actual date is set to the date 10 days after today's date
@w{@result{} 19930227.}

@item
@samp{gcal %0@@t-10} @w{(@equiv{} @code{@var{yyyy}@@t-@var{n}})}@*
The actual date is set to the date 10 days before today's date
@w{@result{} 19930207.}

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

@item
@samp{gcal %1994@@t+3Wed} @w{(@equiv{} @code{@var{yyyy}@@t@r{[}+@r{]}@var{n}@var{www}})}@*
The actual date is set to the date 3rd Wednesday after today's date in 1994
@w{@result{} 19940309.}

@item
@samp{gcal %1994@@t-3wed} @w{(@equiv{} @code{@var{yyyy}@@t-@var{n}@var{www}})}@*
The actual date is set to the date 3rd Wednesday before today's date in 1994
@w{@result{} 19940302.}

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

@item
@samp{gcal %0@@t+3wed} @w{(@equiv{} @code{@var{yyyy}@@t@r{[}+@r{]}@var{n}@var{www}})}@*
The actual date is set to the date 3rd Wednesday after today's date
@w{@result{} 19930310.}

@item
@samp{gcal %0@@t-3we} @w{(@equiv{} @code{@var{yyyy}@@t-@var{n}@var{www}})}@*
The actual date is set to the date 3rd Wednesday before today's date
@w{@result{} 19930127.}

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

For understanding 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 command separator characters
@cindex Command separator characters, list of
@noindent
Here is a list of all ranges of commands, lists of commands and other command
separator characters:

@itemize @bullet
@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 itemize

@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

@page
@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 the @emph{actual month} of the @emph{actual
year} and ending at month @emph{actual month}-1 of the @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 the @emph{actual year} and
ending at month @var{mm}-1 of the @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 the @emph{actual month} of year @var{yyyy}
and ending at month @emph{actual month}-1 of year @var{yyyy}+1, also called
@dfn{explicit fiscal year} 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 the 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 the 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 the 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 the 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 of the current year
@cindex Specified months of the current year, list of
List of specified months of the 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

@page
@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 the 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 the actual year
@cindex Fiscal years of the actual year, list of
List of fiscal years of the 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, Environment Variables: @code{GCAL}}).
These options are interpreted first at program start-up, and some can be
overwritten by explicit command line arguments or values found in a
@samp{@@@var{file}} response file.
@xref{Command line arguments},
and
@ref{Response file},
for further information.

@sp 2

@noindent
For example:

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

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

@item
for @strong{MS-DOS}:
@smallexample
set GCAL=-i @@color -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.

@sp 2

@noindent
For example:

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

@node Eternal Holidays, Fixed Dates, 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.29}.@*
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{]}}, 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 sheet.

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 sheet of the specified month (of year),
and trailing those holidays of the eternal holiday list that refer to the
given month (of the 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 sheet 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}}, 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-style year calendar
sheet, 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.
@sp 2

@noindent
Some annotations:
@sp 2

The following table lists all those characters which are used for marking
an entry in the eternal holiday list, i.e.@: directly leads its date:

@multitable @columnfractions .18 .82
@item @strong{Character}
@tab @strong{Description}
@item @code{+}
@tab Legal holiday which is valid in the whole country.
Is automatically provided with highlighting sequences respectively marking
characters.
@item @code{#}
@tab Legal holiday which is valid in major parts of the whole country.
Is automatically provided with highlighting sequences respectively marking
characters.
@item @code{*}
@tab Legal holiday which is valid in minor parts of the whole country.
Is not provided with highlighting sequences respectively marking characters.
@item @code{-}
@tab Other holiday which serves for memorial or remarking purposes only.
Is not provided with highlighting sequences respectively marking characters.
@end multitable

@sp 2

By using the @samp{--cc-holidays=@var{cc}@r{[}+@dots{}@r{]}} option, it is
possible to provide the eternal holiday list with additional country specific
holidays.  Thereafter, those country specific holidays are part of the list
likewise the standard holidays, too.
@xref{Calendar options, @samp{--cc-holidays=@var{cc}@r{[}+@dots{}@r{]}}, Calendar options: @samp{--cc-holidays=@var{cc}@r{[}+@dots{}@r{]}}}.
For example:

@example
--cc-holidays=de+fr
@end example

@noindent
effects the inclusion of German and French holidays into the eternal holiday
list.  The inclusion of country specific holidays is not coupled to Gcal's
internationalization
(@pxref{Internationalization, , Aspects in Internationalization}).
This means, no country specific holidays are automatically respected at program
start-up for a definite territory or country.  So it's up to the user to decide
which country specific holidays are included into the eternal holiday list.
@xref{The GCAL environment variable, , The @code{GCAL} environment variable},
for informations, how Gcal can be induced to include the country specific
holidays automatically into the eternal holiday list at program start-up.

The free selection of the different country specific holidays can be used very
ingenious in case informations of a definite territory or country are required.
Assuming a business man from Germany proposes to travel to the U.S.A.@: in
November and needs the information which legal holidays are celebrated there on
work days so he is able to plan his dates.  This can be determined as follows:

@example
gcal -f /dev/null -q US -D r -cE nov
@end example

@node Fixed Dates, Todays Calendar, Eternal Holidays, Top
@chapter Fixed Dates
@cindex Fixed Dates

@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} feature of Gcal.
For that purpose, you may create a Gcal resource file for showing fixed
dates and 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} 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 system date (@equiv{}today)!  Then Gcal displays all fixed dates found
in the resource file which refer to the actual day (week/month/year) of the
actual year, without a leading calendar sheet.

@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 dates can be displayed in different ways:

In case you start Gcal with the @emph{fixed date} 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 sheet of the specified
respectively actual month / year, and trailing those fixed dates found
in the resource file that refer to the given period; the intensity level
is the same as the @samp{-cy} option if the period refers to a year or
fiscal year or to a three month period, respectively, is the same as the
@samp{-cm} option if the period refers to a month.

@need 1500
In case you start Gcal without an explicit date and the @emph{fixed date}
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 dates found in the resource file that refer to
the requested period, and after that all holidays of the eternal holiday list
that refer to the whole actual year, without a leading calendar sheet.
@xref{Eternal Holidays},
for more details how to use an @emph{eternal holiday list}.
@sp 2

@noindent
Annotation to previous examples:
@sp 2

In case an additional @emph{standard/special calendar format} argument
or an additional @emph{starting day of week} argument @footnote{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 sheet before all
other lists.
@xref{Calendar options, @samp{--type=special@r{|}standard}, Calendar options: @samp{--type=special@r{|}standard}},
and
@ref{Calendar options, @samp{--starting-day@r{[}=@var{argument}@r{]}}, 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}
argument (with optional modifiers) and the @emph{number of blocks} argument
(@pxref{Calendar options, @samp{--blocks=@var{number}}, 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 system date (@equiv{}today)!  Gcal displays a leading year calendar
sheet, and all fixed dates found in the resource file that refer to the
actual day (week/month/year) of the actual year.

You can list fixed dates 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 way 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.

@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 intensity level is the
same as the @samp{-cy} option.

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

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

@item gcal -c-e -n 1993+1996
Lists all fixed dates of 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
intensity level is the same as the @samp{-cy} option.

@item gcal -cm %19920317
Lists all fixed dates of March 1992 in ascending order.

@item gcal %1994@@e -n -c
Lists all fixed dates of Easter Sunday 1994 in ascending order, and the eternal
holiday list of entire 1994 in ascending order.
@end table

@page
@node Resource file, Resource file examples, Fixed Dates, Fixed Dates
@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 texts processed::       What are @code{%@var{?}}@dots{} Special texts?
* Date variables::                How Date variables can be used.
* Text variables::                How Text variables can be used.
@end menu

This section describes how to use a @dfn{resource file} that contains
fixed dates and appointments.  The name of the standard resource file is
@file{$HOME/.gcalrc} @footnote{On @w{MS-DOS}, OS/2 and some other
operating systems, the name of the @emph{standard} resource file is
@file{$HOME/gcalrc} (without a leading @samp{.}).}.

@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 1
@item
The Gcal program expects the standard resource file in 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, Environment Variables: @code{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, Environment Variables: @code{GCALPATH}})
for the standard resource file.  The @code{GCALPATH} environment variable
contains a (@samp{:}) colon-separated @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.} list of directories.  If no such environment variable
is defined and set, Gcal also 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
@footnote{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, Environment Variables: @code{GCAL_USR_DATADIR}}).
If no @code{HOME} environment variable is defined and set,
naturally Gcal also 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
@footnote{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, Environment Variables: @code{GCAL_SYS_DATADIR}}).
@end enumerate

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

@cindex Error code 118
@cindex Exit code 118
In case the @w{@samp{--debug=abort}} option is given and no standard resource
file is found during the steps @w{1@dots{}4} of the file searching mechanism,
the Gcal program will be aborted with an error code.
@xref{Error Codes, 118, Error Codes: 118},
and
@ref{Global options, @samp{--debug=abort}, Global options: @samp{--debug=abort}},
for more information.

@sp 2

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{Fixed date options, @samp{--resource-file=@var{name}}, Fixed date options: @samp{--resource-file=@var{name}}}.
@sp 2

@noindent
Annotation:
@sp 2

@cindex Extended file name
@cindex File name, extended
An @dfn{extended file name} contains one ore more @samp{/} (slash) characters
@footnote{Operating systems like @w{MS-DOS} or OS/2 use the @samp{\}
(Backslash) character for separating a directory from a file name.} 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:

@itemize @bullet
@item
In case file @var{name} is found, Gcal will use it.

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

@sp 2

@cindex Simple file name
@cindex File name, simple
A @dfn{simple file name} denotes 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:

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

@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 entry in a resource file must be
split into two parts, namely a @emph{date part} and an optional
@emph{text part} which @strong{must} be separated by @strong{one}
@dfn{whitespace} @footnote{For example @emph{Tab}, @emph{Space},
@emph{Form-feed} and similar characters.} character minimum.
It is unnecessary 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
@w{@code{INT_MAX}} @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 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}@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 entries, a resource file may contain further entries like:
@sp 2

@noindent
Include directives@dots{}

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

@page
@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 Line, date part of
@cindex Resource file, date part of

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

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

@quotation
@table @code
@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}: @code{@var{yyyy}*d@r{|}w@var{n}@r{[}@var{www}@r{]}}}

@quotation
@table @code
@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 the year, i.e.@: exceeds the year bounds, the fixed date 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}: @code{@var{yyyy}@@e@r{|}t@r{|}@var{dvar}@r{[[}+@r{|}-@r{]}@var{n}@r{]}}}

@quotation
@table @code
@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 @@t
(2 characters), is the reference to today'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 the year, i.e.@: exceeds the
year bounds, the fixed date message is suppressed.
@end table
@end quotation

@noindent
@w{@strong{or}: @code{@var{yyyy}@@e@r{|}t@r{|}@var{dvar}@r{[}+@r{|}-@r{]}@var{n}@var{www}}}

@quotation
@table @code
@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 @@t
(2 characters), is the reference to today'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 the year, i.e.@: exceeds the year bounds, the
fixed date 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
@cindex Date part, further 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 --- which leads a fixed date entry of a Gcal resource
file line --- may be provided with further attributes, that 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.

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

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

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

@item
@w{@code{@var{yyyy}@@e@r{|}t@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 @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 --- and 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 Date part, 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 not concrete therefore.
(This wouldn't make any sense in this context.)

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
@noindent
The use of lists of days in the date part is permitted as follows:

@itemize @bullet
@item
@w{@code{@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{@code{@var{yyyy}*d@r{|}w@var{n}@r{|}@var{n}@var{www},@var{n}@r{|}@var{n}@var{www} @dots{}}}

@item
@w{@code{@var{yyyy}@@e@r{|}t@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
@noindent
Some examples to this:

@table @code
@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.

@item 1996@@t+1,-3,5,+4fr,2fr,-10sa
In the year 1996: one day after today's date, three days before today's date,
five days after today's date, four Fridays after the today's date, two Fridays
after today's date and ten Saturdays before today'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 Date part, 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
not concrete therefore.  (This wouldn't make any sense in this context.)

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 @footnote{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

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

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

@item
@w{@code{@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{@code{@var{yyyy}*d@r{|}w@var{n}@r{[}@var{www}@r{]}#@var{n}@r{[}@var{www}@r{]}}}

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

Preceding table shows that the starting and ending day can only be specified
by using date formats of the same type left and right the @samp{#} separator
character.  Thus, it is not explicitly possible to define a range of days
using different types of date formats, means, fixed date entries like:

@example
1996@@e+3fr#1012 In the year 1996: every day that appears within the\
                period of the date 3 Fridays after Easter Sunday's\
                date until the 12th October.
@end example

@noindent
cannot be defined in this way.  But this problem can be solved by using
an inclusive date period @code{%i@r{[}@var{date}@r{][}#@r{[}@var{date}@r{]]}}
special text for defining the ending day of the range @footnote{Implicit
solution.}, and the fixed dates are simply produced until the last day of the
year, e.g.@::

@example
1996@@e+3fr#+999 In the year 1996: every day that appears within the\
                period of the date 3 Fridays after Easter Sunday's\
                date until the 12th October.%i0#19961012
@end example

@xref{Inclusive date period, , Inclusive date period @code{%i@r{[}@var{date}@r{][}#@r{[}@var{date}@r{]]}} special text},
for more details.

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

@table @code
@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.

@item 1996@@t-3#+99fr
In the year 1996: every day that appears within the period
of the date three days before today's date until the last Friday of
the year.
@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
@cindex Date part, 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 1@dots{}999.  Values greater than the
real difference between the date of the first occurrence of the fixed date
and the last day of the year are always reduced to this real difference.
In this sense, any value greater 365 @footnote{Or 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 @footnote{Apart from the possibility, that a list
or a range of days can be used in such a case.}.

@need 2000
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
@noindent
The use of repetition factors of days in the date part is permitted as follows:

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

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

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

@item
@w{@code{@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{@code{@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{@code{@var{yyyy}@@e@r{|}t@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
@noindent
Some examples to this:

@table @code
@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.

@item 1996@@t-3:9
In the year 1996: every day that appears within the period
of the date three days before today'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
@cindex Date part, 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 1@dots{}999.  Fixed dates will be ignored
if the factor takes values greater than the real difference between the date
of the occurrence of the fixed date and 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 @footnote{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

@noindent
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
@noindent
The use of appearance factors of days in the date part is permitted as follows:

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

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

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

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

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

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

@item
@w{@code{@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{@code{@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{@code{@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{@code{@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{@code{@var{yyyy}@@e@r{|}t@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{@code{@var{yyyy}@@e@r{|}t@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{@code{@var{yyyy}@var{mm}@var{www}#@var{www}.@var{n}}}

@item
@w{@code{@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{@code{@var{yyyy}*d@r{|}w@var{n}@r{[}@var{www}@r{]}#@var{n}@r{[}@var{www}@r{]}.@var{n}}}

@item
@w{@code{@var{yyyy}@@e@r{|}t@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
@noindent
Some examples to this:

@table @code
@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).

@item 1996@@t3#-20sun.15
In the year 1996: every day that appears within the period
of the date three days after today's date until the 20th Sunday before today'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 resource file 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 of
@cindex Resource file, limitations of
@cindex Limitations in a resource file
@cindex Line break up character, @samp{~}
@cindex @samp{~} line break up character
@cindex Line break up character, @samp{^}
@cindex @samp{^} line break up character

The @dfn{text part} of a line in a resource file can be any text you like.
Indeed, some characters have a special meaning (@samp{%}, @samp{$}, @samp{~},
@samp{^} and @samp{\}) and must be protected should the occasion arise that
special character combinations are formed with them @footnote{Like @samp{%i},
@samp{$a}@dots{}} which might be used only textually.  If the text part
contains characters that 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 @footnote{These are potentially non-printable.} 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 @footnote{That's the character with the value
zero in the code table of the used character set.} may also occur 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
Furthermore, you can break up the text of a @emph{long} text part at any
place you 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.

@cindex Line break up character, @samp{~}
@cindex @samp{~} line break up character
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
--- this means, they are lead by a definite number of space characters.

@cindex Depreciation of special characters
@cindex Depreciation character, @samp{\}
@cindex @samp{\} depreciation character
@cindex Protection of special characters
@cindex Protection character, @samp{\}
@cindex @samp{\} protection character
You may depreciate the special meaning of the @samp{~} (tilde) character
--- in case this character itself is needed --- by placing a @samp{\}
(backslash) character before it, e.g.@: @samp{\~}.  If you need the @samp{\~}
characters themselves, you have to protect the @samp{\} (backslash) character
by itself, e.g.@: @samp{\\~}.

@cindex Line break up character, @samp{^}
@cindex @samp{^} line break up character
Each time a @samp{^} (caret) character is found in the text part, this
character is also replaced by a real @samp{\n} (newline) character.  Such
texts will be displayed by Gcal at column 1, --- this means, they are not
lead by space characters.  The rules for protecting the @samp{^} character
are the same as the rules used for protecting the @samp{~} character.

@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 I hope I'm also 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 also long enough
@print{} here, a line break up
@print{}                      and again
@print{} and now for the last time...
@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 Depreciation of special characters
@cindex Depreciation character, @samp{\}
@cindex @samp{\} depreciation character
@cindex Protection of special characters
@cindex Protection character, @samp{\}
@cindex @samp{\} protection character
Because @emph{whitespace} characters are used to separate the date part from
the text part @footnote{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 protecting 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.

@page
@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 @footnote{Physically and logically.} 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.
@xref{Text part of a line},
for information how a @code{NUL} character can be used for remarking
purposes in a text part.

The following example of the @file{remark.rc} resource file --- which
@strong{only} consists of remarks --- should be enough to elucidate
the above facts:

@example
@group
@cartouche
$ cat remark.rc
;00001031 ^\
                        ........^\
                         ;::;;::,^\
                         ;::;;::;,^\
                        ;;:::;;:;;,^\
          .vnmnv\%vnnv\%,.;;;:::;;:;;,  .,vnmnv\%vnmn,^\
       vnmmmn\%vnmmnv\%vnmmnv\%;;;;;;\%nmmmnv\%vnmnv\%vmmnv^\
     vnmmnv\%vmmmmnv\%vnmmmmmnv\%;:\%nmmmmmmnv\%vnmn\%vnmmmnv^\
    vnmmnv\%vnmmmnv\%vnmmmmmmmmnv\%nmmmmmmmmnv\%vnmmn\%vnmmmnv^\
   vnmmnv\%vnmmmnv\%vnmmmmmmmmnv\%vmmmmmmmmmmnv\%vnmmv\%vnmmmnv^\
  vnmmnv\%vnmmmnv\%vnmm;mmmmmmnv\%vmmmmmmmm;mmnv\%vnmnv\%vnmmmnv,^\
 vnmmnv\%vnmmmnv\%vnmm;' mmmmmnv\%vmmmmmmm;' mmnv\%vnmnv\%vnmmmnv,^\
 vnmmnv\%vnmmmnv\%vn;;    mmmmnv\%vmmmmmm;;    nv\%vnmmnv\%vnmmmnv^\
vnmmnv\%vnmmmmnv\%v;;      mmmnv\%vmmmmm;;      v\%vnmmmnv\%vnmmmnv^\
vnmmnv\%vnmmmmnv\%vnmmmmmmmmm;;      mmmmmmmmmnv\%vnmmmmnv\%vnmmmnv^\
vnmmnv\%vnmmmmnv\%vnmmmmmmmmmm;;    mmmmmmmmmmnv\%vnmmmmnv\%vnmmmnv^\
vnmmnv\%vnmmmmnv\%vnmmmmmmmmmmnv;,mmmmmmmmmmmmnv\%vn;mmmnv\%vnmmmnv^\
vnmmnv\%vnmmm. nv\%vnmmmmmmmmmnv\%;mmmmmmmmmmmnv\%vn; mmmnv\%vnmmmnv^\
`vnmmnv\%vnmm,  v\%vnmmmmmmmmmmnv\%nmmmmmmmmmmnv\%v;  mmnv\%vnnmmnv'^\
 vnmmnv\%vnmm;,   \%vnmmmmmmmmmnv\%nmmmmmmmmmnv\%;'   mmv\%vnmmmmnv^\
  vnmmnv\%vnmm;;,   nmmm;'             mmmm;;'    mnv\%vnmmmmnv'^\
  `vnmmnv\%vnmmm;;,.         mmnvv;,            mmnv\%vnmmmmnv'^\
   `vnmmnv\%vnmmmmnv\%vnmmmmmmmmnvvnmmmmmmnv\%vnmmmmv\%vnmmmmnv'^\
     `vnmvn\%vmmmmmnv\%vnmmmmmmmnvvnmmmmmnv\%vnmmmmn\%vnmmmnv'^\
         `vn\%nmmmmmn\%:\%vnmnmmmmn\%vnmmmnv\%:\%vnmnv\%nmnv'

; A remark line
      ; Also a remark line
;     A                          \
      formatted and multi-line   \
      remark
@end cartouche
@end group
@end example

@page
@node Include directives, Special texts processed, 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 for searching and
loading further resource files @footnote{A mechanism similar the method
which is used by the C Preprocessor.}.  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 @footnote{Thus, a file name which is embraced by @samp{""} or @samp{<>}.}

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

@cindex Separator character, whitespace
@cindex Whitespace separator character
One @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 1
@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 @w{1@dots{}4} of the previously explained
mechanism used for searching files
(@pxref{Resource file, File searching mechanism, 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 @w{3@dots{}4}
of the previously explained mechanism 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 @footnote{Even if operating systems like @w{MS-DOS} or OS/2 permits
such a disk/drive specification on principle.}, because the resulting path
name @footnote{A path name lead by the user respectively system data
directory name.} wouldn't be a valid file name any longer.

@cindex Error code 119
@cindex Exit code 119
Included files may include other files again.  But the nesting level of
included files is limited on the one hand by the amount of usable 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 that occurs at a deeper place in 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.
@xref{Error Codes, 119, Error Codes: 119},
for more information.

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 texts processed, Date variables, Include directives, Resource file
@subsection @code{%@var{?}}@dots{} special texts
@cindex @code{%@var{?}}@dots{} spezial texts
@cindex Special text starting character, @samp{%}
@cindex @samp{%} special text starting character
@cindex Depreciation of special characters
@cindex Depreciation character, @samp{\}
@cindex @samp{\} depreciation character
@cindex Protection of special characters
@cindex Protection character, @samp{\}
@cindex @samp{\} protection character

The text part of a resource file line may contain 81 different special texts
which may occur in any @footnote{Rational!} number and order.  All these texts
start with a @samp{%} (percent) character which may be protected 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
special text to be used --- and if it is a letter, Gcal accepts
it @strong{case-sensitive}.
@sp 2

Mainly, the sense of these special texts is to suppress output of fixed dates
in definite cases, either, or to provide them with particular texts
respectively to start external commands.
@xref{Special Texts, , @code{%@var{?}}@dots{} Special Texts},
for a complete description of all usable special texts, and
@ref{Special Texts Summary, , Summary of all @code{%@var{?}}@dots{} Special Texts},
for an according short-list of them.
@sp 2

For example, the resource file @file{special.rc}

@example
@group
; I'm veracious very special :)
;
0 1. Today is %o , %u  %M  %Y !
0 2. It's the %#  day of the year.
0 3. The actual week number is: %k .
0 4. Currently, it's %t12 o'clock.
@end group
@end example

@noindent
is displayed as follows (in case today's date is the 4th October 1996):

@example
@group
@cartouche
$ gcal --resource-file=special.rc -H no -ox
@print{}
@print{} Fr,   4 Oct 1996: 1. Today is Friday, 04th October 1996!
@print{}                   2. It's the 278th day of the year.
@print{}                   3. The actual week number is: 40.
@print{}                   4. Currently, it's 01:25am o'clock.
@end cartouche
@end group
@end example

@page
@node Date variables, Text variables, Special texts processed, 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 which may
be used either in the date part of a Gcal resource file line, or which may
be part of a special text in the text part of a Gcal resource file line.

@xref{Fixed date options, @samp{--date-variable=@var{argument}}, Fixed date options: @samp{--date-variable=@var{argument}}},
for more information how global date variables can be used.

This means, up to @strong{24} user defined date variables can be set
and referenced during program execution.  A date variable name @var{dvar}
consists of a single, case-insensitive letter @footnote{Except the date
variable @var{e} that is internally reserved for the Easter Sunday's date,
so it cannot be assigned or operated therefore.  And except the date variable
@var{t} that is internally reserved for today's date, so it likewise cannot
be assigned or operated.}, 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 @footnote{Or the name of another
date variable.}, e.g.@::

@example
@group
a=1127
c=a
@end group
@end example

@noindent
stores the 27th November into the local date variable @var{a} and into 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{@code{@var{mm}@var{www}@var{n}}},
@w{@code{@var{dvar}@r{[}+@r{|}-@r{]}@var{n}@r{[}@var{www}@r{]}}} or
@w{@code{*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.
@sp 2

@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 ---
and not in fixed dates shown after the current year has changed,
e.g.@: in @strong{fiscal years}.

@page
@cindex Visibility of date variables
@cindex Date variables, visibility of
@cindex Name space of date variables
@cindex Date variables, name space of
@cindex Error code 113
@cindex Exit code 113
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 @footnote{In the command
line, environment variable @code{GCAL} or response file.} are always global.
If a resource file line contains a reference to 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,
informational messages for each undefined date variable will be shown on
the @emph{standard error channel}
(@pxref{Global options, @samp{--debug=internal}, Global options: @samp{--debug=internal}}).
If the @w{@samp{--debug=abort}} option is given, the Gcal program will be
aborted with an error code when the first undefined global date variable
reference occurs.
@xref{Error Codes, 113, Error Codes: 113},
and
@ref{Global options, @samp{--debug=abort}, Global options: @samp{--debug=abort}},
for more information.

@cindex Deletion of local date variables
@cindex Local date variables, deletion of 
A local date variable can be deleted.  This 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
; dvar.rc
;
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

@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

@page
@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 effects that the actual incarnation of a local date variable ---
which was previously defined in a resource file and not in an included file
--- is being exported to further resource files instead of using its
global value, in case that date variable isn't locally defined in that
further resource file.
@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 exactly know what you're doing when applying this
option; @strong{you are expressively warned now!}
@sp 2

@cindex Operations on date variables
@cindex Date variables, operations on
Some basic operations can be performed on date variables.  These are:

@multitable @columnfractions .2 .8
@item @strong{Operation}
@tab @strong{Description}
@item @code{@var{dvar}++}
@cindex Date variables, simple incrementing
@cindex Simple incrementing date variables
@tab Simple increment by one day.
@item @code{@var{dvar}--}
@cindex Date variables, simple decrementing
@cindex Simple decrementing date variables
@tab Simple decrement by one day.
@item @code{@var{dvar}+=@var{n}}
@cindex Date variables, addition by days
@cindex Addition by days, date variables
@tab Addition of a constant numeric day factor @var{n}.
@item @code{@var{dvar}-=@var{n}}
@cindex Date variables, subtraction by days
@cindex Subtraction by days, date variables
@tab Subtraction of a constant numeric day factor @var{n}.
@item @code{@var{dvar}+=@var{n}@var{www}}
@cindex Date variables, addition by weekdays
@cindex Addition by weekdays, date variables
@tab Addition of @var{n} weekdays @var{www}.
@item @code{@var{dvar}-=@var{n}@var{www}}
@cindex Date variables, subtraction by weekdays
@cindex Subtraction by weekdays, date variables
@tab Subtraction of @var{n} weekdays @var{www}.
@end multitable

@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 @footnote{They are only 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 finally note, 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 which may
be used anywhere in a line of a Gcal resource file.

@xref{Fixed date options, @samp{--text-variable=@var{argument}}, Fixed date options: @samp{--text-variable=@var{argument}}},
for more information how global text variables can be used.

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, case-insensitive letter, 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 side 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 Depreciation of special characters
@cindex Depreciation character, @samp{\}
@cindex @samp{\} depreciation character
@cindex Protection of special characters
@cindex Protection character, @samp{\}
@cindex @samp{\} protection character
You may depreciate the special meaning of the @samp{$} prefix character
--- in case this character itself is needed in the text --- by placing a
@samp{\} (backslash) character before it, e.g.@: @samp{\$}.  If you need
the @samp{\$} characters themselves in the text, you have to protect 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 partial) date parts
(@pxref{Date part of a line}),
likewise special texts
(@pxref{Special texts processed, , @code{%@var{?}}@dots{} special 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 @footnote{In the command
line, environment variable @code{GCAL} or response file.} are always global.
If a resource file line contains a reference to 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 effects that the actual incarnation of a local text variable ---
which was previously defined in a resource file and not in an included file
--- is being exported to further resource files instead of using its
global value, in case that text variable isn't locally defined in that
further resource file.
@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 exactly know 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 redefinitions are only valid in that specific file
@footnote{They are only 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 finally note, 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 Dates
@section Resource file examples
@cindex Resource file examples
@cindex Examples of resource files

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
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%i1952#2062
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%i#1979
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
;
; Next entry is respected by ALL fixed date 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
; or
0@@a-1wed Day of Prayer & Repentance
@end group
@end example

@page
@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%i0000
$b=#0000
$c=fri2
$d=fri3
00000113 $a01$c$b01$c
00000113 $a01$d$b01$d
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, and
that by using the fact, that a Friday the 13th only occurs if the first day
of a month is a Sunday:

@example
@group
$a=%n+12 is a Friday%i0000
$b=#0000
$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

@page
@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
Of course, preceding textual expense for the purpose of detecting all Fridays
the 13th of a year can be dramatically reduced by simply using of

@example
0*d1fri#99fri.7 Friday the 13th%i00000013#00000013
@end example

@noindent
in the resource file @file{demo3.rc}, respectively,

@example
0*d1sun#99sun.7 n+12 is a Friday%i00000001#00000001
@end example

@noindent
in the @file{demo4.rc} resource file.
@sp 2

@noindent
On the one hand, preceding @emph{one-liners} reduce the coding expense quite
considerably --- from 28 respectively 15 lines to 1 line in each case
---, but on the other hand, this partly increases the checking expense
of these @emph{one-liners} considerably and results to a longer program
run-time therefore.  Both @emph{one-liners} produce about 52 internal
productions respectively effective fixed date entries of themselves for
each year checked by Gcal, at which the @file{demo3.rc} and @file{demo4.rc}
resource files cause 24 respectively 12 effective fixed date entries only.

@page
@noindent
And here is a resource file by the name of @file{demo5.rc}, used to detect
all work days of any month:

@example
@group
$a=%VWork day
$c=%i#0000$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=%VWork day
$c=%i#0000$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

@page
@noindent
Then the result for the month August 1996 is as follows:

@example
@group
@cartouche
$ gcal -H no -u -x -r '$b=08:$f=demo5.rc' -f ./include.rc Aug 1996
@print{}
@print{} Thu, Aug   1st 1996: Work day
@print{} Fri, Aug   2nd 1996: Work day
@print{} Mon, Aug   5th 1996: Work day
@print{} Tue, Aug   6th 1996: Work day
@print{} Wed, Aug   7th 1996: Work day
@print{} Thu, Aug   8th 1996: Work day
@print{} Fri, Aug   9th 1996: Work day
@print{} Mon, Aug  12th 1996: Work day
@print{} Tue, Aug  13th 1996: Work day
@print{} Wed, Aug  14th 1996: Work day
@print{} Thu, Aug  15th 1996: Work day
@print{} Fri, Aug  16th 1996: Work day
@print{} Mon, Aug  19th 1996: Work day
@print{} Tue, Aug  20th 1996: Work day
@print{} Wed, Aug  21st 1996: Work day
@print{} Thu, Aug  22nd 1996: Work day
@print{} Fri, Aug  23rd 1996: Work day
@print{} Mon, Aug  26th 1996: Work day
@print{} Tue, Aug  27th 1996: Work day
@print{} Wed, Aug  28th 1996: Work day
@print{} Thu, Aug  29th 1996: Work day
@print{} Fri, Aug  30th 1996: Work day
@end cartouche
@end group
@end example

@noindent
And of course, the preceding textual expense for the purpose of detecting
all work days of any month can be dramatically reduced by simply using of

@example
00000001#0099 %V%rWork day
@end example

@noindent
in the resource file @file{demo5.rc}.

@page
@noindent
And finally a resource file by the name of @file{swtime.rc} which results
fixed date messages for the change of daylight-saving time valid since 1980
for the Federal Republic of Germany @footnote{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.)%i1980
;
a=09sun9
0@@a-2#+2 Winter $a~-1 hrs. (03:00 --> 02:00 h.)%i1980#1995
;
a=10sun9
0@@a-2#+2 Winter $a~-1 hrs. (03:00 --> 02:00 h.)%i1996
@end group
@end example

@node Todays Calendar, Gcal Utilities, Fixed Dates, Top
@appendix Genesis of the Gregorian Calendar
@cindex Gregorian calendar, Genesis of
@cindex Calendar, Gregorian
@cindex Calendar, Julian
@cindex Julian calendar

The nowadays calendar was first formulated in several inaccurate variations by
the Romans based on methods developed by the Babylonians and Egypts.  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 laid 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, so the 29th February
was designed to be the leap day now.

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
Mohammedan moon calendar in 1979 after removal of the Shah reign.  There
are some efforts to improve our currently 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 churches.

@node Gcal Utilities, Internationalization, Todays Calendar, Top
@appendix Gcal Utilities
@cindex Gcal Utilities
@cindex Utilities for 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.
* Invoking gcal2txt::  How to run @code{gcal2txt} and a summary of its options.
@end menu

Three 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.
The @code{txt2gcal} program creates a verbatim Gcal resource file from a text
file, and in contrast to this, the @code{gcal2txt} program creates a verbatim
text file from a Gcal resource 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
@cindex Options of @code{tcal}
@cindex @code{tcal}, options of

The @code{tcal} program runs @code{gcal} with the date of tomorrow's
day @footnote{This is 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 tomorrow's 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 system date (@equiv{}today).
(Works only for Gregorian years.)  The @samp{--shift} option must be given
before all other @var{arguments} that 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, Environment Variables: @code{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, any other value means
an error has occurred.

@noindent
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 gcal2txt, 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
@cindex Options of @code{txt2gcal}
@cindex @code{txt2gcal}, options of

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} argument is given or/but @samp{-}, the program reads and
processes all input received from the @emph{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 @emph{standard output
channel}.  An exit status of 0 means all processing is successfully done,
any other value means an error has occurred.

@page
@noindent
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 Invoking gcal2txt, , Invoking txt2gcal, Gcal Utilities
@appendixsec Invoking @code{gcal2txt}
@cindex Invoking @code{gcal2txt}
@cindex The @code{gcal2txt} utility
@cindex Utility @code{gcal2txt}
@cindex @code{gcal2txt}, utility
@cindex Options of @code{gcal2txt}
@cindex @code{gcal2txt}, options of

The @code{gcal2txt} program creates a verbatim text file from
a Gcal resource file. Its arguments are as follows:

@example
gcal2txt @r{[}--help @r{|} --version@r{] | [}@var{Resource-file}@r{|}-@r{]}
@end example

If no @var{resource-file} argument is given or/but @samp{-}, the program reads
and processes all input received from the @emph{standard input channel}.  All
results are always shown on the @emph{standard output channel}.  An exit
status of 0 means all processing is successfully done, any other value
means an error has occurred.

The sense and purpose of @code{gcal2txt} is to retrieve all additional texts,
which are put in output by means of @code{txt2gcal}.

@noindent
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{gcal2txt}.  For that purpose,
let's use the resource file @file{demo.rc} of the previous section
(@pxref{Invoking txt2gcal, , Invoking @code{txt2gcal}}),
which was created by means of @code{txt2gcal} from a text file
and which looks like this:

@example
@group
@cartouche
$ cat demo.rc
@print{} 0*d1#999 \        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

@noindent
Now let's see, how this resource file will be processed by @code{gcal2txt}:

@example
@group
@cartouche
$ gcal2txt demo.rc
@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, Metasymbols, Gcal Utilities, Top
@appendix Aspects in Internationalization
@cindex Aspects in Internationalization
@cindex Internationalization aspects
@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:

@multitable @columnfractions .33 .66
@item @strong{Native Language}
@tab @strong{Language Code}
@item English
@tab @code{en}
@item German
@tab @code{de}
@item French
@tab @code{fr}
@item Dutch
@tab @code{nl}
@item Swedish
@tab @code{sv}
@end multitable

@sp 2

@cindex Selection of native language
@cindex Native language, selection of
It is only necessary to set one of the environment variables
@footnote{Listed in decreasing priority as they are respected.}:

@multitable @columnfractions .04 .96
@item 1.
@vindex LANGUAGE
@cindex @code{LANGUAGE} environment variable
@cindex Environment variable, @code{LANGUAGE}
@tab @code{LANGUAGE}
@item 2.
@vindex LC_ALL
@cindex @code{LC_ALL} environment variable
@cindex Environment variable, @code{LC_ALL}
@tab @code{LC_ALL}
@item 3.
@vindex LC_MESSAGES
@cindex @code{LC_MESSAGES} environment variable
@cindex Environment variable, @code{LC_MESSAGES}
@tab @code{LC_MESSAGES}
@item 4.
@vindex LANG
@cindex @code{LANG} environment variable
@cindex Environment variable, @code{LANG}
@tab @code{LANG}
@end multitable

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

@sp 2

Normally, users only have to set the @code{LANG} environment variable to tell
Gcal the native language to use at run-time level.  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 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 @footnote{For example @code{fr} for French, @code{es}
for Spanish@dots{}}.

@page
@cindex Native language defaults
@cindex Defaults of native language
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 criteria are likewise bound to the
language code @footnote{Strictly speaking, an extended language code
information.}.

@noindent
A @code{en} language code effects the following internal defaults of above
criteria:

@itemize @bullet
@item
U.S. American date format

@item
Gregorian Reformation have occurred 1752

@item
Week starts on Sunday

@item
Representation of calendar sheet

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

@noindent
And a @code{de} language code @footnote{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 occurred 1582

@item
Week starts on Monday

@item
Representation of calendar sheet

@example
@group
September 1994

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
Sunday       4 11 18 25
@end group
@end example
@end itemize

Remember, all these internal defaults are modifiable by the options
@samp{--date-format}, @samp{--gregorian-reform}, @samp{--starting-day}
and @samp{--type}.
@sp 2

If no language code is detected, Gcal takes the internal defaults of the
@code{en} language code @footnote{Or to be more precise, of the extended
language code information @code{en_US}.}.

@page
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 spoken all over the world unlike the German or other native
languages, so it is wise to use it here.  But the other criteria bound to the
English native language are so special for users of other native languages,
that it is wise to use the criteria taken for internal defaults of the
@code{de} language code, because most European countries (taken as standard)
essentially use them.

@cindex @sc{iso}-3166
@cindex Country code
@cindex Territory code
@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 @footnote{All other internal defaults of the simple
@code{en} language code information just meet their criteria.}.  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.

@noindent
The usual template of an extended language code information is as follows:

@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 (Comit@'e Europ@'en 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 criteria.
The @var{language} component is equivalent to the simple language code
information and the @var{territory} component is a two-letter territory or
country 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, and after that, they can use the British date format
as an internal default.

@node Metasymbols, Regular Expressions, Internationalization, Top
@appendix Metasymbols
@cindex Metasymbols within this document, list of all
@cindex List of all Metasymbols within the document

Within this document, the following @emph{metasyntactic} conventions will be
used when discussing command line options, commands, arguments and templates:
@sp 2

@table @code
@item @var{n}
Argument is not optional and @var{n} must be a valid number.

@item e@r{|}t@r{|}@var{dvar}
Argument is not optional and must be a single alphabetic character.

@item $@var{tvar}
Argument is not optional and must be a single alphabetic character,
that is lead by a @samp{$} 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 Regular Expressions, Regexp Summary, Metasymbols, Top
@appendix Regular Expressions
@c
@c This appendix is derived from the gawk-3.0.0 and regex-0.12 manuals.
@c
@cindex Pattern, regular expressions
@cindex Regexp
@cindex Regular expression
@cindex Regular expressions as patterns

@menu
* Regexp Usage::      How to Use Regular Expressions.
* Regexp Operators::  Regular Expression Operators.
@end menu

@noindent
This appendix is derived from the @code{gawk-3.0.0} and @code{regex-0.12}
manuals.

A @dfn{regular expression}, or @dfn{regexp}, is a way of describing a
set of strings.  The simplest regular expression is a sequence of letters,
numbers, or both.  Such a regexp matches any string that contains that
sequence.  Thus, the regexp @samp{foo} matches any string containing
@samp{foo}.  Other kinds of regular expressions let you specify more
complicated classes of strings.

Gcal uses exactly one of the following regular expression programming
libraries respectively methods, and that in the decreasing priority how
it is chosen at configuration time, or better, compile time of the
software:

@multitable @columnfractions .05 .75 .2
@item @strong{No.}
@tab @strong{Function}
@tab @strong{Symbol}
@item 1.
@tab GNU @code{re_compile_pattern()} and @file{regex.h}
@tab @code{GNU-REGEX}
@item 2.
@tab POSIX @code{regcomp()} and @file{regex.h}
@tab @code{POSIX-REGEX}
@item 3.
@tab BSD @code{re_comp()}
@tab @code{BSD-REGEX}
@item 4.
@tab System V @code{regcmp()}
@tab @code{SysV-REGEX}
@item 5.
@tab Henry Spencer V8 @code{regcomp()} and @file{regexp.h}
@tab @code{V8-REGEX}
@item 6.
@tab Pattern matching is supported, but without metacharacters
@tab @code{NO-REGEX}
@end multitable

Try @w{@samp{gcal --version}} for detecting the kind of regular expression
programming library respectively method that is burned-in in your Gcal program!

@node Regexp Usage, Regexp Operators, Regular Expressions, Regular Expressions
@appendixsec How to Use Regular Expressions
@cindex How to use regular expressions
@cindex Regular expressions, how to use

A regular expression can be used as a pattern if Gcal's
@w{@samp{--filter-text=@var{pattern}}} option is specified at program start-up.

@xref{Fixed date options, @samp{--filter-text=@var{pattern}}, Fixed date options: @samp{--filter-text=@var{pattern}}},
for more details.

Then the regular expression is tested against the entire, completely
expanded text of each @strong{valid} fixed date, and the fixed date
is only displayed in case the pattern matches the text @footnote{Normally,
it only needs to match some part of the text in order to succeed.}.

@node Regexp Operators, , Regexp Usage, Regular Expressions
@appendixsec Regular Expression Operators
@cindex Metacharacters, regexp
@cindex Regexp metacharacters
@cindex Operators, regexp
@cindex Regexp operators
@cindex Regular expression metacharacters
@cindex Regular expression operators

You can combine regular expressions with the following characters,
called @dfn{regular expression operators}, or @dfn{metacharacters}, to
increase the power and versatility of regular expressions.

@page
Here is a table of these metacharacters.  All characters that are not
listed in the table stand for themselves.

@table @code
@item \
This is used to suppress the special meaning of a character when
matching.  For example:

@example
\$
@end example

matches the character @samp{$}.

@cindex Anchors in regexps
@cindex Regexp, anchors in
@item ^
This matches the beginning of a string.  For example:

@example
^@@chapter
@end example

matches the @samp{@@chapter} at the beginning of a string, and can be used
to identify chapter beginnings in Texinfo source files.
The @samp{^} is known as an @dfn{anchor}, since it anchors the pattern to
matching only at the beginning of the string.

@item $
This is similar to @samp{^}, but it matches only at the end of a string.
For example:

@example
p$
@end example

matches a string that ends with a @samp{p}.  The @samp{$} is also an anchor.

@item .
The period, or dot, matches any single character.  For example:

@example
.P
@end example

matches any single character followed by a @samp{P} in a string.  Using
concatenation we can make a regular expression like @w{@samp{U.A}}, which
matches any three-character sequence that begins with @samp{U} and ends
with @samp{A}.

@cindex Character list, regexp
@cindex Regexp, character list in
@item [@dots{}]
This is called a @dfn{character list}.  It matches any @emph{one} of the
characters that are enclosed in the square brackets.  For example:

@example
[MVX]
@end example

matches any one of the characters @samp{M}, @samp{V}, or @samp{X} in a string.

Ranges of characters are indicated by using a hyphen between the beginning
and ending characters, and enclosing the whole thing in brackets.  For
example:

@example
[0-9]
@end example

matches any digit.
Multiple ranges are allowed. E.g., the list @w{@code{[A-Za-z0-9]}} is a
common way to express the idea of ``all alphanumeric characters.''

To include one of the characters @samp{\}, @samp{]}, @samp{-} or @samp{^} in a
character list, put a @samp{\} in front of it.  For example:

@example
[d\]]
@end example

matches either @samp{d}, or @samp{]}.

@cindex Character classes, regexp
@cindex Regexp, character classes in
@cindex POSIX regexp
@cindex Regexp, POSIX
@dfn{Character classes} are a new feature introduced in the POSIX standard.
A character class is a special notation for describing
lists of characters that have a specific attribute, but where the 
actual characters themselves can vary from country to country and/or
from character set to character set.  For example, the notion of what
is an alphabetic character differs in the U.S.A.@: and in France.

A character class is only valid in a regexp @emph{inside} the
brackets of a character list.  Character classes consist of @samp{[:},
a keyword denoting the class, and @samp{:]}.  Here are the character
classes defined by the POSIX standard:

@need 1500
@table @code
@item [:alnum:]
Alphanumeric characters.

@item [:alpha:]
Alphabetic characters.

@item [:blank:]
Space and tab characters.

@item [:cntrl:]
Control characters.

@item [:digit:]
Numeric characters.

@item [:graph:]
Characters that are printable and are also visible @footnote{A space is
printable, but not visible, while an @samp{a} is both.}.

@item [:lower:]
Lower-case alphabetic characters.

@item [:print:]
Printable characters @footnote{Characters that are not control characters.}.

@item [:punct:]
Punctuation characters @footnote{Characters that are not letter, digits,
control characters, or space characters.}.

@item [:space:]
Space characters @footnote{Such as Space, Tab, and Form-feed, to name a few.}.

@item [:upper:]
Upper-case alphabetic characters.

@item [:xdigit:]
Characters that are hexadecimal digits.
@end table

For example, before the POSIX standard, to match alphanumeric
characters, you had to write @w{@code{[A-Za-z0-9]}}.  If your
character set had other alphabetic characters in it, this would not
match them.  With the POSIX character classes, you can write
@w{@code{[[:alnum:]]}}, and this will match @emph{all} the alphabetic
and numeric characters in your character set.

@cindex Collating elements, regexp
@cindex Regexp, collating elements in
Two additional special sequences can appear in character lists.
These apply to non-@sc{ascii} character sets, which can have single symbols
(called @dfn{collating elements}) that are represented with more than one
character, as well as several characters that are equivalent for
@dfn{collating}, or sorting, purposes.  (E.g., in French, a plain @samp{e}
and a grave-accented @samp{@`e} are equivalent.)

@table @asis
@cindex Collating symbols, regexp
@cindex Regexp, collating symbols in
@item Collating Symbols
A @dfn{collating symbol} is a multi-character collating element enclosed in
@samp{[.} and @samp{.]}.  For example, if @samp{ch} is a collating element,
then @w{@code{[[.ch.]]}} is a regexp that matches this collating element,
while @w{@code{[ch]}} is a regexp that matches either @samp{c} or @samp{h}.

@cindex Equivalence classes, regexp
@cindex Regexp, equivalence classes in
@item Equivalence Classes
An @dfn{equivalence class} is a list of equivalent characters enclosed in
@samp{[=} and @samp{=]}.  Thus, @code{[[=e@`e=]]} is regexp that matches
either @samp{e} or @samp{@`e}.
@end table

These features are very valuable in non-English speaking locales.

@strong{Caution:}@*
The library functions that @code{gcal} uses for regular expression matching
currently only recognize POSIX character classes (possibly); they do not
recognize collating symbols or equivalence classes.

@cindex Complemented character list, regexp
@cindex Regexp, complemented character list in
@cindex Character list in regexp, complemented
@cindex Negated character list, regexp
@cindex Regexp, negated character list in
@cindex Character list in regexp, negated
@item [^ @dots{}]
This is a @dfn{negated character list} respectively @dfn{complemented
character list}.  The first character after the @samp{[} @emph{must}
be a @samp{^}.  It matches any characters @emph{except} those in the
square brackets.  For example:

@example
[^0-9]
@end example

matches any character that is not a digit.

@item |
This is the @dfn{alternation operator}, and it is used to specify
alternatives.  For example:

@example
^P|[0-9]
@end example

matches any string that matches either @samp{^P} or @w{@samp{[0-9]}}.  This
means it matches any string that starts with @samp{P} or contains a digit.

The alternation applies to the largest possible regexps on either side.
In other words, @samp{|} has the lowest precedence of all the regular
expression operators.

@item (@dots{})
Parentheses are used for grouping in regular expressions as in arithmetic.
They can be used to concatenate regular expressions containing the alternation
operator, @samp{|}.  For example, @w{@samp{@@(samp|code)\@{[^@}]+\@}}} matches
both @w{@samp{@@code@{foo@}}} and @w{@samp{@@samp@{bar@}}}. (These are Texinfo
formatting control sequences.)

@item *
This symbol means that the preceding regular expression is to be
repeated as many times as necessary to find a match.  For example:

@example
ph*
@end example

applies the @samp{*} symbol to the preceding @samp{h} and looks for matches
of one @samp{p} followed by any number of @samp{h}s.  This will also match
just @samp{p} if no @samp{h}s are present.

The @samp{*} repeats the @emph{smallest} possible preceding expression.
(Use parentheses if you wish to repeat a larger expression.)  It finds
as many repetitions as possible.  For example:

@example
gcal --filter-text='\(c[ad][ad]*r x\)' -f sample.rc -y
@end example

prints every fixed date in @file{sample.rc} containing a fixed dates text
of the form @w{@samp{(car x)}}, @w{@samp{(cdr x)}}, @w{@samp{(cadr x)}},
and so on. Notice the escaping of the parentheses by preceding them with
backslashes.

@item +
This symbol is similar to @samp{*}, but the preceding expression must be
matched at least once.  This means that:

@example
wh+y
@end example

would match @w{@samp{why}} and @w{@samp{whhy}} but not @w{@samp{wy}}, whereas
@w{@samp{wh*y}} would match all three of these strings.  This is a simpler
way of writing the last @samp{*} example:

@example
gcal --filter-text='\(c[ad]+r x\)' -f sample.rc -y
@end example

@item ?
This symbol is similar to @samp{*}, but the preceding expression can be
matched either once or not at all.  For example:

@example
fe?d
@end example

will match @w{@samp{fed}} and @w{@samp{fd}}, but nothing else.

@cindex Interval expressions, regexp
@cindex Regexp, interval expressions
@cindex POSIX regexp
@cindex Regexp, POSIX
@item @{@var{n}@}
@itemx @{@var{n},@}
@itemx @{@var{n},@var{m}@}
One or two numbers inside braces denote an @dfn{interval expression}
which is available in the POSIX standard.  If there is one number in
the braces, the preceding regexp is repeated @var{n} times.
If there are two numbers separated by a comma, the preceding regexp is
repeated @var{n} to @var{m} times.  If there is one number followed by
a comma, then the preceding regexp is repeated at least @var{n} times.

@table @code
@item wh@{3@}y
matches @w{@samp{whhhy}} but not @w{@samp{why}} or @w{@samp{whhhhy}}.

@item wh@{3,5@}y
matches @w{@samp{whhhy}} or @w{@samp{whhhhy}} or @w{@samp{whhhhhy}}, only.

@item wh@{2,@}y
matches @w{@samp{whhy}} or @w{@samp{whhhy}}, and so on.
@end table
@end table

@sp 2

@cindex Regexp operators, GNU specific
@cindex GNU specific regexp operators
GNU software that deals with regular expressions provides a number of
additional regexp operators.  These operators are described here.

@cindex Regexp, definition of a word
@cindex Word, regexp definition of
Most of the additional operators are for dealing with word matching.
For our purposes, a @dfn{word} is a sequence of one or more letters, digits,
or underscores (@samp{_}).

@table @code
@cindex @code{\w} regexp operator
@cindex Regexp operator, @code{\w}
@item \w
This operator matches any word-constituent character, i.e.@: any
letter, digit, or underscore. Think of it as a short-hand for
@w{@code{[A-Za-z0-9_]}} or
@w{@code{[[:alnum:]_]}}.

@cindex @code{\W} regexp operator
@cindex Regexp operator, @code{\W}
@item \W
This operator matches any character that is not word-constituent.
Think of it as a short-hand for
@w{@code{[^A-Za-z0-9_]}} or
@w{@code{[^[:alnum:]_]}}.

@cindex @code{\<} regexp operator
@cindex Regexp operator, @code{\<}
@item \<
This operator matches the empty string at the beginning of a word.
For example, @code{\<away} matches @samp{away}, but not
@samp{stowaway}.

@cindex @code{\>} regexp operator
@cindex Regexp operator, @code{\>}
@item \>
This operator matches the empty string at the end of a word.
For example, @code{stow\>} matches @samp{stow}, but not @samp{stowaway}.

@cindex @code{\b} regexp operator
@cindex Regexp operator, @code{\b}
@cindex Word boundaries, matching in regexp
@cindex Regexp, matching word boundaries
@item \b
This operator matches the empty string at either the beginning or the
end of a word (the word @strong{b}oundary).  For example, @samp{\bballs?\b}
matches either @samp{ball} or @samp{balls} as a separate word.

@cindex @code{\B} regexp operator
@cindex Regexp operator, @code{\B}
@item \B
This operator matches the empty string within a word. In other words,
@samp{\B} matches the empty string that occurs between two
word-constituent characters. For example,
@code{\Brat\B} matches @samp{crate}, but it does not match @samp{dirty rat}.
@samp{\B} is essentially the opposite of @samp{\b}.
@end table

There are two other operators that work on buffers.  In Emacs, a
@dfn{buffer} is, naturally, an Emacs buffer.  For other programs, the
regexp library routines that @code{gcal} uses consider the entire
string to be matched as the buffer @footnote{That's the @emph{text part}
of a Gcal resource file line.}.

For @code{gcal}, since @samp{^} and @samp{$} always work in terms
of the beginning and end of strings, these operators don't add any
new capabilities.  They are provided for compatibility with other GNU
software.

@cindex Buffer matching operators, regexp
@cindex Regexp, buffer matching operators
@table @code
@cindex @code{\`} regexp operator
@cindex Regexp operator, @code{\`}
@item \`
This operator matches the empty string at the
beginning of the buffer.

@cindex @code{\'} regexp operator
@cindex Regexp operator, @code{\'}
@item \'
This operator matches the empty string at the
end of the buffer.
@end table

@sp 2

@cindex Precedence, regexp operators
@cindex Regexp operators, precedence of
In regular expressions, the @samp{*}, @samp{+}, and @samp{?} operators,
as well as the braces @samp{@{} and @samp{@}}, have the highest precedence,
followed by concatenation, and finally by @samp{|}.  As in arithmetic,
parentheses can change how operators are grouped.

@cindex Case sensitivity in matching, regexp
@cindex Regexp, case sensitivity in matching
Case is normally significant in regular expressions, both when matching
ordinary characters (i.e.@: not metacharacters), and inside character
sets.  Thus a @samp{w} in a regular expression matches only a lower-case
@samp{w} and not an upper-case @samp{W}.

@cindex Ignoring case, regexp
@cindex Regexp, ignoring case in
The simplest way to do a case-independent match is to use a character
list: @w{@samp{[Ww]}}.  However, this can be cumbersome if you need to use it
often; and unfortunately, it can make the regular expressions harder to read.

@node Regexp Summary, Special Texts, Regular Expressions, Top
@appendix Summary of all Regular Expressions
@cindex Regular expressions, short-list of all
@cindex Regular expressions, summary of all
@cindex Summary of all regular expressions
@cindex Short-list of all regular expressions

Regular expressions are based on POSIX EREs (Extended Regular Expressions).
Regexps are composed of characters.  Here is a short-list of all them all:
@sp 2

@table @code
@item @var{c}
matches the character @var{c} (assuming @var{c} is none of the characters
listed below).

@item \@var{c}
matches the literal character @var{c}.

@item .
matches any character.

@item ^
matches the beginning of a string.

@item $
matches the end of a string.

@item [@var{abc}@dots{}]
matches any of the characters @var{abc}@dots{} (character list).

@item [[:@var{class}:]]
matches any character in the character class @var{class}.
Allowable classes are @code{alnum}, @code{alpha}, @code{blank},
@code{cntrl}, @code{digit}, @code{graph}, @code{lower}, @code{print},
@code{punct}, @code{space}, @code{upper}, and @code{xdigit}.

@item [[.@var{symbol}.]]
matches the multi-character collating symbol @var{symbol}.
@code{gcal} does not currently support collating symbols.

@item [[=@var{chars}=]]
matches any of the equivalent characters in @var{chars}.
@code{gcal} does not currently support equivalence classes.

@item [^@var{abc}@dots{}]
matches any character except @var{abc}@dots{} (negated resp.@:
complemented character list).

@item @var{r1}|@var{r2}
matches either @var{r1} or @var{r2} (alternation).

@item @var{r1r2}
matches @var{r1}, and then @var{r2} (concatenation).

@item @var{r}+
matches one or more @var{r}'s.

@item @var{r}*
matches zero or more @var{r}'s. 

@item @var{r}?
matches zero or one @var{r}'s. 

@item (@var{r})
matches @var{r} (grouping).

@item @var{r}@{@var{n}@}
@itemx @var{r}@{@var{n},@}
@itemx @var{r}@{@var{n},@var{m}@}
matches at least @var{n}, @var{n} to any number, or @var{n} to @var{m}
occurrences of @var{r} (interval expressions).

@item \b
matches the empty string at either the beginning or the
end of a word.

@item \B
matches the empty string within a word.

@item \<
matches the empty string at the beginning of a word.

@item \>
matches the empty string at the end of a word.

@item \w
matches any word-constituent character (alphanumeric characters and
the underscore).

@item \W
matches any character that is not word-constituent.

@item \`
matches the empty string at the beginning of a buffer @footnote{Same as a
@emph{text part} of a resource file line in @code{gcal}.}.

@item \'
matches the empty string at the end of a buffer.
@end table

@node Special Texts, Special Texts Summary, Regexp Summary, Top
@appendix @code{%@var{?}}@dots{} Special Texts
@cindex @code{%@var{?}}@dots{} special texts, description of all
@cindex Description of all @code{%@var{?}}@dots{} special texts

@menu
* Exclusions::     How to Exclude dates.
* Replacements::   How to Replace texts.
* Shell Command::  How to run a Shell Command.
@end menu

The @code{%@var{?}}@dots{} special texts which can be used in the text part
of a Gcal resource file line can coarsely be separated into three categories.
So there are special texts used for suppression output of fixed dates in
definite cases.  Others are replaced by particular texts or cause the shell
to start external commands.
@xref{Special texts processed, , @code{%@var{?}}@dots{} special texts},
for a general description of the special texts which may be used
in the text part of a Gcal resource file line.

Some of these special text may have an optional simple or special date
argument (called @var{date} in the further context) or another argument
(called @var{argument} in the further context).  The @var{date} argument
must be given in one of the following date formats in case a special text
is directly trailed by it:

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

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

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

Special texts that may have a @var{date} argument @strong{must} always be
trailed by a @emph{whitespace} character which is removed itself in output,
no matter whether @var{date} was given or not!

@xref{Special Texts Summary, , Summary of all @code{%@var{?}}@dots{} special texts},
for a short-list of all applicable special texts.

@node Exclusions, Replacements, Special Texts, Special Texts
@appendixsec @code{%@var{?}}@dots{} special texts for date exclusion
@cindex @code{%@var{?}}@dots{} special texts for date exclusion

@menu
* Exclusions with date argument::
* Exclusions without any argument::
@end menu

@code{%@var{?}}@dots{} special texts used for exclusion of points of time or
periods of dates are very useful if they are used together with ranges of days
(@pxref{Ranges of days}).
The complete special text is always suppressed in output
in case the fixed date text must be displayed.

@node Exclusions with date argument, Exclusions without any argument, Exclusions, Exclusions
@appendixsubsec Exclusions with date argument @code{%@var{?}@r{[}@var{date}@r{]}} special texts
@cindex Exclusions with date argument @code{%@var{?}@r{[}@var{date}@r{]}} special texts

@menu
* Inclusive date period::
* Exclusive date period::
@end menu

First of all, an @dfn{inclusive date} period @code{%@var{?}@r{[}@var{date}@r{]}}
special text can be specified with the effect, that only those fixed dates are
respected and displayed which are part of this period.  And the specification
of an @dfn{exclusive date} period @code{%@var{?}@r{[}@var{date}@r{]}} special
text effects, that only those fixed dates are respected and displayed which
are not part of this period.

Cleverly combined, these special texts offer very effective filtration
capabilities used for the definition of special periods in a highly flexible
manner, for example:

@example
0*d1#999 Every day of year: from January@dots{}August except April\
         %i00001#00008 %e00004#00004
;
0*d1#999 Every day of year: from 1991@dots{}1993 and from 1996\
         except February 1992 and all September\
         %i1991#1993 %i1996# %e19922#19922 %e00009#00009
@end example

@node Inclusive date period, Exclusive date period, Exclusions with date argument, Exclusions with date argument
@appendixsubsubsec Inclusive date period @code{%i@r{[}@var{date}@r{][}#@r{[}@var{date}@r{]]}} special text
@cindex Special text @code{%i@r{[}@var{date}@r{][}#@r{[}@var{date}@r{]]}}
@cindex Inclusive date period, @code{%i@r{[}@var{date}@r{][}#@r{[}@var{date}@r{]]}} special text
@cindex @code{%i@r{[}@var{date}@r{][}#@r{[}@var{date}@r{]]}} special text, inclusive date period

@w{@code{%i@r{[}@var{date}@r{][}#@r{[}@var{date}@r{]]}}}
references an inclusive date period, i.e.@: all dates which are part of the
specified period are valid and are displayed.  Of course this means, that all
fixed dates which are not part of this period (not covered by it) are invalid
and remain un-displayed therefore.

@cindex Fixed date, starting date of
@cindex Starting date of fixed date
The first specified date defines the @dfn{starting date} of the fixed date,
i.e.@: the first date the fixed date may occur.  For the starting date, the
following rules concerning definite omission values are valid, elucidated
by using the
@w{@code{@var{yyyy}@r{[}@var{mm}@r{[}@var{dd}@r{|}@var{www}@var{n}@r{]]}}}
date format:

@itemize @bullet
@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,
and the December is assumed in case @var{mm} is set to 99.

@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,
and the last day of the month @var{mm} is assumed in case @var{dd} is set to 99.

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

@cindex Fixed date, ending date of
@cindex Ending date of fixed date
The second specified date defines the @dfn{ending date} of the fixed date,
i.e.@: the last date the fixed date may occur.  For the ending date, the
following rules concerning definite omission values are valid, likewise
elucidated by using the
@w{@code{@var{yyyy}@r{[}@var{mm}@r{[}@var{dd}@r{|}@var{www}@var{n}@r{]]}}}
date format:

@itemize @bullet
@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,
and the December is assumed in case @var{mm} is set to 99.

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

@item
If @var{dd} is set to 00, the current day is assumed for the day,
and the last day of the month @var{mm} is assumed in case @var{dd} is set to 99.

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

The preceding rules are analogously valid for the other permitted date formats.

If the starting date which is encoded in the @w{@code{%i@dots{}}} special text
is later the ending date, so the @w{@code{%i@dots{}}} special text will be
ignored.

In case neither the starting date nor the ending date is specified, means only
@samp{%i} is given, the implicit period 1st January 1@dots{}31st December 9999
@w{(00010101@dots{}99991231)} will be used.

If only the starting date is specified, means either @samp{%i@var{date}} or
@samp{%i@var{date}#} is given, the implicit ending date 31st December 9999
@w{(99991231)} will be used.

In case only the ending date is specified, means @samp{%i#@var{date}} is given,
the implicit starting date 1st January 1 @w{(00010101)} will be used.

@page
@noindent
For example:

@example
0d*1#999 Every day of year: only April and July\
         %i00004#00004 %i00007#00007
;
0*d1#999 Every day of year: from January@dots{}October\
         %i#000010
;
0*d1#999 Every day of year: from August 1990\
         %i19908
;
0*d1#999 Every day of year: from August@dots{}December\
         %i00008
;
0*d1#999 Every day of year: only today%i0@@t#0@@t
@end example

@node Exclusive date period, , Inclusive date period, Exclusions with date argument
@appendixsubsubsec Exclusive date period @code{%e@r{[}@var{date}@r{][}#@r{[}@var{date}@r{]]}} special text
@cindex Special text @code{%e@r{[}@var{date}@r{][}#@r{[}@var{date}@r{]]}}
@cindex Exclusive date period, @code{%e@r{[}@var{date}@r{][}#@r{[}@var{date}@r{]]}} special text
@cindex @code{%e@r{[}@var{date}@r{][}#@r{[}@var{date}@r{]]}} special text, exclusive date period

@w{@code{%e@r{[}@var{date}@r{][}#@r{[}@var{date}@r{]]}}}
references an exclusive date period, i.e.@: all dates which are part of the
specified period are invalid and remain un-displayed therefore.  Of course
this means, that all fixed dates which are not part of this period
(not covered by it) are valid and are displayed.

@cindex Fixed date, starting date of
@cindex Starting date of fixed date
The first specified date defines the @dfn{starting date} of the fixed date,
i.e.@: the first date the fixed date may occur.  For the starting date, the
following rules concerning definite omission values are valid, elucidated
by using the
@w{@code{@var{yyyy}@r{[}@var{mm}@r{[}@var{dd}@r{|}@var{www}@var{n}@r{]]}}}
date format:

@itemize @bullet
@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,
and the December is assumed in case @var{mm} is set to 99.

@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,
and the last day of the month @var{mm} is assumed in case @var{dd} is set to 99.

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

@cindex Fixed date, ending date of
@cindex Ending date of fixed date
The second specified date defines the @dfn{ending date} of the fixed date,
i.e.@: the last date the fixed date may occur.  For the ending date, the
following rules concerning definite omission values are valid, likewise
elucidated by using the
@w{@code{@var{yyyy}@r{[}@var{mm}@r{[}@var{dd}@r{|}@var{www}@var{n}@r{]]}}}
date format:

@itemize @bullet
@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,
and the December is assumed in case @var{mm} is set to 99.

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

@item
If @var{dd} is set to 00, the current day is assumed for the day,
and the last day of the month @var{mm} is assumed in case @var{dd} is set to 99.

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

The preceding rules are analogously valid for the other permitted date formats.

If the starting date which is encoded in the @w{@code{%e@dots{}}} special text
is later the ending date, so the @w{@code{%i@dots{}}} special text will be
ignored.

In case neither the starting date nor the ending date is specified, means only
@samp{%e} is given, the implicit period 1st January 1@dots{}31st December 9999
@w{(00010101@dots{}99991231)} will be used.

If only the starting date is specified, means either @samp{%e@var{date}} or
@samp{%e@var{date}#} is given, the implicit ending date 31st December 9999
@w{(99991231)} will be used.

In case only the ending date is specified, means @samp{%e#@var{date}} is given,
the implicit starting date 1st January 1 @w{(00010101)} will be used.

@noindent
For example:

@example
0d*1#999 Every day of year: except April and July\
        %e00004#00004 %e00007#00007
;
0*d1#999 Every day of year: except January@dots{}October\
         %e#000010
;
0*d1#999 Every day of year: until July 1990\
         %e19908
;
0*d1#999 Every day of year: except August@dots{}December\
         %e00008
;
0*d1#999 Every day of year: except today%e0@@t#0@@t
@end example

@node Exclusions without any argument, , Exclusions with date argument, Exclusions
@appendixsubsec Exclusions without any argument @code{%@var{?}} special texts
@cindex Exclusions without any argument @code{%@var{?}} special texts

@menu
* Inclusive day period::
* Exclusive day period::
@end menu

First of all, an @dfn{inclusive day} period @code{%@var{?}} special text
can be specified with the effect, that only those fixed dates are respected
and displayed which are part of this period.  And the specification of an
@dfn{exclusive day} period @code{%@var{?}} special text effects, that only
those fixed dates are respected and displayed which are not part of this period.

Cleverly combined, these special texts also offer very effective filtration
capabilities used for the definition of very special periods.

@noindent
For example:

@example
0*d1#999 Every day of year: all Mondays@dots{}Fridays\
         except Wednesdays and all legal holidays\
         %r%F%V
;
00001001#9999 Every day in last quarter of year: all holidays\
              which are not on a Sunday%x %P
@end example

@page
@node Inclusive day period, Exclusive day period, Exclusions without any argument, Exclusions without any argument
@appendixsubsubsec Inclusive day period @code{%@var{?}} special texts
@cindex Inclusive day period @code{%@var{?}} special texts

The following inclusive day periods @code{%@var{?}} special texts
are respected, at which @emph{inclusive} is meant for the period
which is not excluded.

@table @code
@item %v
@cindex Special text @code{%v}
@cindex @code{%v} special text, inclusive legal holidays
@cindex Inclusive legal holidays, @code{%v} special text
Excludes fixed date in case it is not listed as legal holiday in the
@emph{eternal holiday list}.

@item %x
@cindex Special text @code{%x}
@cindex @code{%x} special text, inclusive all holidays
@cindex Inclusive all holidays, @code{%x} special text
Excludes fixed date in case it is neither listed as legal holiday nor
memorial day in the @emph{eternal holiday list}.

@item %a
@cindex Special text @code{%a}
@cindex @code{%a} special text, inclusive Monday
@cindex Inclusive Monday, @code{%a} special text
Excludes fixed date in case it is no Monday.

@item %c
@cindex Special text @code{%c}
@cindex @code{%c} special text, inclusive Tuesday
@cindex Inclusive Tuesday, @code{%c} special text
Excludes fixed date in case it is no Tuesday.

@item %f
@cindex Special text @code{%f}
@cindex @code{%f} special text, inclusive Wednesday
@cindex Inclusive Wednesday, @code{%f} special text
Excludes fixed date in case it is no Wednesday.

@item %g
@cindex Special text @code{%g}
@cindex @code{%g} special text, inclusive Thursday
@cindex Inclusive Thursday, @code{%g} special text
Excludes fixed date in case it is no Thursday.

@item %h
@cindex Special text @code{%h}
@cindex @code{%h} special text, inclusive Friday
@cindex Inclusive Friday, @code{%h} special text
Excludes fixed date in case it is no Friday.

@item %l
@cindex Special text @code{%l}
@cindex @code{%l} special text, inclusive Saturday
@cindex Inclusive Saturday, @code{%l} special text
Excludes fixed date in case it is no Saturday.

@item %p
@cindex Special text @code{%p}
@cindex @code{%p} special text, inclusive Sunday
@cindex Inclusive Sunday, @code{%p} special text
Excludes fixed date in case it is no Sunday.

@item %q
@cindex Special text @code{%q}
@cindex @code{%q} special text, inclusive Monday@dots{}Thursday
@cindex Inclusive Monday@dots{}Thursday, @code{%q} special text
Excludes fixed date in case it is no Monday@dots{}Thursday.

@item %r
@cindex Special text @code{%r}
@cindex @code{%r} special text, inclusive Monday@dots{}Friday
@cindex Inclusive Monday@dots{}Friday, @code{%r} special text
Excludes fixed date in case it is no Monday@dots{}Friday.
@end table

@node Exclusive day period, , Inclusive day period, Exclusions without any argument
@appendixsubsubsec Exclusive day period @code{%@var{?}} special texts
@cindex Exclusive day period @code{%@var{?}} special texts

The following exclusive day periods @code{%@var{?}} special texts
are respected, at which @emph{exclusive} is meant for the period
which is excluded.

@table @code
@item %V
@cindex Special text @code{%V}
@cindex @code{%V} special text, exclusive legal holidays
@cindex Exclusive legal holidays, @code{%V} special text
Excludes fixed date in case it is listed as legal holiday in the
@emph{eternal holiday list}.

@item %X
@cindex Special text @code{%X}
@cindex @code{%X} special text, exclusive all holidays
@cindex Exclusive all holidays, @code{%X} special text
Excludes fixed date in case it is either listed as legal holiday or
memorial day in the @emph{eternal holiday list}.

@item %A
@cindex Special text @code{%A}
@cindex @code{%A} special text, exclusive Monday
@cindex Exclusive Monday, @code{%A} special text
Excludes fixed date in case it is a Monday.

@item %C
@cindex Special text @code{%C}
@cindex @code{%C} special text, exclusive Tuesday
@cindex Exclusive Tuesday, @code{%C} special text
Excludes fixed date in case it is a Tuesday.

@item %F
@cindex Special text @code{%F}
@cindex @code{%F} special text, exclusive Wednesday
@cindex Exclusive Wednesday, @code{%F} special text
Excludes fixed date in case it is a Wednesday.

@item %G
@cindex Special text @code{%G}
@cindex @code{%G} special text, exclusive Thursday
@cindex Exclusive Thursday, @code{%G} special text
Excludes fixed date in case it is a Thursday.

@item %H
@cindex Special text @code{%H}
@cindex @code{%H} special text, exclusive Friday
@cindex Exclusive Friday, @code{%H} special text
Excludes fixed date in case it is a Friday.

@item %L
@cindex Special text @code{%L}
@cindex @code{%L} special text, exclusive Saturday
@cindex Exclusive Saturday, @code{%L} special text
Excludes fixed date in case it is a Saturday.

@item %P
@cindex Special text @code{%P}
@cindex @code{%P} special text, exclusive Sunday
@cindex Exclusive Sunday, @code{%P} special text
Excludes fixed date in case it is a Sunday.

@item %Q
@cindex Special text @code{%Q}
@cindex @code{%Q} special text, exclusive Monday@dots{}Thursday
@cindex Exclusive Monday@dots{}Thursday, @code{%Q} special text
Excludes fixed date in case it is a Monday@dots{}Thursday.

@item %R
@cindex Special text @code{%R}
@cindex @code{%R} special text, exclusive Monday@dots{}Friday
@cindex Exclusive Monday@dots{}Friday, @code{%R} special text
Excludes fixed date in case it is a Monday@dots{}Friday.
@end table

@node Replacements, Shell Command, Exclusions, Special Texts
@appendixsec @code{%@var{?}}@dots{} special texts for text replacement
@cindex @code{%@var{?}}@dots{} special texts for text replacement

@menu
* Replacements with date argument::
* Replacements with other argument::
* Replacements without any argument::
@end menu

@code{%@var{?}}@dots{} special texts which are replaced by particular texts
at program run-time effects interspersing of data into the fixed date text,
which quality is essentially depending on the command line arguments given
for running the program.  The complete special text is always replaced
accordingly in output if the fixed date text must be displayed.

Cleverly combined, these special texts also offer very effective mechanisms
used for the definition of particular texts in a highly flexible manner,
for example:

@example
0*d1#999 Every day of year: Today is %o, the %n (%+)
@end example

@node Replacements with date argument, Replacements with other argument, Replacements, Replacements
@appendixsubsec Replacements with date argument @code{%@var{?}@r{[}@var{date}@r{]}} special texts
@cindex Replacements with date argument @code{%@var{?}@r{[}@var{date}@r{]}} special texts

@menu
* Weekday name::
* Weekday::
* Day number::
* Day::
* Week::
* Month name::
* Month::
* Year::
* Moonphase::
* Biorhythm::
* Difference value::
@end menu

Apart from different representations of a weekday name, it is possible
to create its weekday number.  Likewise, the current day of year, the
day number, the week number, the month name, the month number, the year
number, the moonphase, the biorhythm, and some useful difference values
can be produced.

For the @var{date} argument these @code{%@var{?}@r{[}@var{date}@r{]}}
special text may have, the following rules concerning definite omission
values are valid, elucidated by using the
@w{@code{@var{yyyy}@r{[}@var{mm}@r{[}@var{dd}@r{|}@var{www}@var{n}@r{]]}}}
date format @footnote{The succeeding rules are analogously valid for the
other permitted date formats.}:

@itemize @bullet
@item
If @var{yyyy}@dots{} is not given (@equiv{}@strong{no} date encoded),
the 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 or set to 00, the current month is assumed for
the month, and the December is assumed in case @var{mm} is set to 99.

@item
If @w{@var{dd}|@var{www}} is not given or set to 00, the current day is
assumed for the day, and the last day of the month is assumed in case
@var{dd} is set to 99.

@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 Weekday name, Weekday, Replacements with date argument, Replacements with date argument
@appendixsubsubsec Weekday name @code{%@var{?}@r{[}@var{date}@r{]}} special texts
@cindex Weekday name @code{%@var{?}@r{[}@var{date}@r{]}} special texts

The following weekday name @code{%@var{?}@r{[}@var{date}@r{]}} special texts
are respected:

@table @code
@item %o@r{[}@var{date}@r{]}
@cindex Special text @code{%o@r{[}@var{date}@r{]}}
@cindex @code{%o@r{[}@var{date}@r{]}} special text, complete weekday name
@cindex Complete weekday name, @code{%o@r{[}@var{date}@r{]}} special text
Is replaced by the complete @strong{weekday name} of the current day, 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 actual system date is the 10th June 1996.
@end quotation

@item %O@r{[}@var{date}@r{]}
@cindex Special text @code{%O@r{[}@var{date}@r{]}}
@cindex @code{%O@r{[}@var{date}@r{]}} special text, 3-letter weekday name
@cindex 3-letter weekday name, @code{%O@r{[}@var{date}@r{]}} special text
Is replaced by the 3-letter @strong{weekday name} of the current day, e.g.@::

@quotation
The text @w{@samp{Today is %O0@@t+1 , the %n+1}}
will be expanded to@*
@w{@expansion{} @samp{Today is Tue, the 11-Jun-1996}},
in case the actual system date is the 10th June 1996.
@end quotation

@need 1000
@item %K@r{[}@var{date}@r{]}
@cindex Special text @code{%K@r{[}@var{date}@r{]}}
@cindex @code{%K@r{[}@var{date}@r{]}} special text, 2-letter weekday name
@cindex 2-letter weekday name, @code{%K@r{[}@var{date}@r{]}} special text
Is replaced by the 2-letter @strong{weekday name} of the current day, e.g.@::

@quotation
The text @w{@samp{Today is %K , the %n}}
will be expanded to@*
@w{@expansion{} @samp{Today is Mo, the 10-Jun-1996}},
in case the actual system date is the 10th June 1996.
@end quotation
@end table

@node Weekday, Day number, Weekday name, Replacements with date argument
@appendixsubsubsec Weekday @code{%@var{?}@r{[}@var{date}@r{]}} special texts
@cindex Weekday @code{%@var{?}@r{[}@var{date}@r{]}} special texts

The following weekday number @code{%@var{?}@r{[}@var{date}@r{]}} special texts
are respected:

@table @code
@item %S@r{[}@var{date}@r{]}
@cindex Special text @code{%S@r{[}@var{date}@r{]}}
@cindex @code{%S@r{[}@var{date}@r{]}} special text, weekday number
@cindex Weekday number, @code{%S@r{[}@var{date}@r{]}} special text
Is replaced by the @strong{weekday number} of the current day, and which is
determined by the @cite{Monday@equiv{}1@dots{}Sunday@equiv{}7} counting
method, e.g.@::

@quotation
The text @w{@samp{Today is weekday %S , the %n}}
will be expanded to@*
@w{@expansion{} @samp{Today is weekday 1, the 10-Jun-1996}},
in case the actual system date is the 10th June 1996.
@end quotation

@item %I@r{[}@var{date}@r{]}
@cindex Special text @code{%I@r{[}@var{date}@r{]}}
@cindex @code{%I@r{[}@var{date}@r{]}} special text, weekday number
@cindex Weekday number, @code{%I@r{[}@var{date}@r{]}} special text
Is replaced by the @strong{weekday number} with trailing Ordinal Number suffix
of the current day, and which is determined by the
@cite{Monday@equiv{}1@dots{}Sunday@equiv{}7} counting method, e.g.@::

@quotation
The text @w{@samp{Today is weekday %I0@@t+1 , the %n+1}}
will be expanded to@*
@w{@expansion{} @samp{Today is weekday 2nd, the 11-Jun-1996}},
in case the actual system date is the 10th June 1996.
@end quotation

@item %E@r{[}@var{date}@r{]}
@cindex Special text @code{%E@r{[}@var{date}@r{]}}
@cindex @code{%E@r{[}@var{date}@r{]}} special text, weekday number
@cindex Weekday number, @code{%E@r{[}@var{date}@r{]}} special text
Is replaced by the @strong{weekday number} of the current day, and which is
determined by the @cite{Monday@equiv{}0@dots{}Sunday@equiv{}6}
counting method, e.g.@::

@quotation
The text @w{@samp{Today is weekday %E , the %n}}
will be expanded to@*
@w{@expansion{} @samp{Today is weekday 0, the 10-Jun-1996}},
in case the actual system date is the 10th June 1996.
@end quotation

@item %J@r{[}@var{date}@r{]}
@cindex Special text @code{%J@r{[}@var{date}@r{]}}
@cindex @code{%J@r{[}@var{date}@r{]}} special text, weekday number
@cindex Weekday number, @code{%J@r{[}@var{date}@r{]}} special text
Is replaced by the @strong{weekday number} with trailing Ordinal Number suffix
of the current day, and which is determined by the
@cite{Monday@equiv{}0@dots{}Sunday@equiv{}6} counting method, e.g.@::

@quotation
The text @w{@samp{Today is weekday %J , the %n}}
will be expanded to@*
@w{@expansion{} @samp{Today is weekday 0th, the 10-Jun-1996}},
in case the actual system date is the 10th June 1996.
@end quotation

@item %(@r{[}@var{date}@r{]}
@cindex Special text @code{%(@r{[}@var{date}@r{]}}
@cindex @code{%(@r{[}@var{date}@r{]}} special text, weekday number
@cindex Weekday number, @code{%(@r{[}@var{date}@r{]}} special text
Is replaced by the @strong{weekday number} of the current day, and which is
determined by the @cite{Sunday@equiv{}1@dots{}Saturday@equiv{}7} counting
method, e.g.@::

@quotation
The text @w{@samp{Today is weekday %( , the %n}}
will be expanded to@*
@w{@expansion{} @samp{Today is weekday 2, the 10-Jun-1996}},
in case the actual system date is the 10th June 1996.
@end quotation

@item %<@r{[}@var{date}@r{]}
@cindex Special text @code{%<@r{[}@var{date}@r{]}}
@cindex @code{%<@r{[}@var{date}@r{]}} special text, weekday number
@cindex Weekday number, @code{%<@r{[}@var{date}@r{]}} special text
Is replaced by the @strong{weekday number} with trailing Ordinal Number suffix
of the current day, and which is determined by the
@cite{Sunday@equiv{}1@dots{}Saturday@equiv{}7} counting method, e.g.@::

@quotation
The text @w{@samp{Today is weekday %< , the %n}}
will be expanded to@*
@w{@expansion{} @samp{Today is weekday 2nd, the 10-Jun-1996}},
in case the actual system date is the 10th June 1996.
@end quotation

@need 1000
@item %)@r{[}@var{date}@r{]}
@cindex Special text @code{%)@r{[}@var{date}@r{]}}
@cindex @code{%)@r{[}@var{date}@r{]}} special text, weekday number
@cindex Weekday number, @code{%)@r{[}@var{date}@r{]}} special text
Is replaced by the @strong{weekday number} of the current day, and which is
determined by the @cite{Sunday@equiv{}0@dots{}Saturday@equiv{}6} counting
method, e.g.@::

@quotation
The text @w{@samp{Today is weekday %) , the %n}}
will be expanded to@*
@w{@expansion{} @samp{Today is weekday 1, the 10-Jun-1996}},
in case the actual system date is the 10th June 1996.
@end quotation

@item %>@r{[}@var{date}@r{]}
@cindex Special text @code{%>@r{[}@var{date}@r{]}}
@cindex @code{%>@r{[}@var{date}@r{]}} special text, weekday number
@cindex Weekday number, @code{%>@r{[}@var{date}@r{]}} special text
Is replaced by the @strong{weekday number} with trailing Ordinal Number suffix
of the current day, and which is determined by the
@cite{Sunday@equiv{}0@dots{}Saturday@equiv{}6} counting method, e.g.@::

@quotation
The text @w{@samp{Today is weekday %> , the %n}}
will be expanded to@*
@w{@expansion{} @samp{Today is weekday 1st, the 10-Jun-1996}},
in case the actual system date is the 10th June 1996.
@end quotation

@item %[@r{[}@var{date}@r{]}
@cindex Special text @code{%[@r{[}@var{date}@r{]}}
@cindex @code{%[@r{[}@var{date}@r{]}} special text, weekday number
@cindex Weekday number, @code{%[@r{[}@var{date}@r{]}} special text
Is replaced by the @strong{weekday number} of the current day, and which is
determined by the
@cite{@var{starting day of week}@equiv{}1@dots{}@var{ending day of week}@equiv{}7}
counting method
(@pxref{Calendar options, @samp{--starting-day=@var{argument}}, Calendar options: @samp{--starting-day=@var{argument}}}),
e.g.@::

@quotation
The text @w{@samp{Today is weekday %[ , the %n}}
will be expanded to@*
@w{@expansion{} @samp{Today is weekday 4, the 10-Jun-1996}},
in case the actual system date is the 10th June 1996 and Friday (@equiv{}5)
is the starting day of week.
@end quotation

@item %@{@r{[}@var{date}@r{]}
@cindex Special text @code{%@{@r{[}@var{date}@r{]}}
@cindex @code{%@{@r{[}@var{date}@r{]}} special text, weekday number
@cindex Weekday number, @code{%@{@r{[}@var{date}@r{]}} special text
Is replaced by the @strong{weekday number} with trailing Ordinal Number suffix
of the current day, and which is determined by the
@cite{@var{starting day of week}@equiv{}1@dots{}@var{ending day of week}@equiv{}7}
counting method
(@pxref{Calendar options, @samp{--starting-day=@var{argument}}, Calendar options: @samp{--starting-day=@var{argument}}}),
e.g.@::

@quotation
The text @w{@samp{Today is weekday %@{ , the %n}}
will be expanded to@*
@w{@expansion{} @samp{Today is weekday 4th, the 10-Jun-1996}},
in case the actual system date is the 10th June 1996 and Friday (@equiv{}5)
is the starting day of week.
@end quotation

@item %]@r{[}@var{date}@r{]}
@cindex Special text @code{%]@r{[}@var{date}@r{]}}
@cindex @code{%]@r{[}@var{date}@r{]}} special text, weekday number
@cindex Weekday number, @code{%]@r{[}@var{date}@r{]}} special text
Is replaced by the @strong{weekday number} of the current day, and which is
determined by the
@cite{@var{starting day of week}@equiv{}0@dots{}@var{ending day of week}@equiv{}6}
counting method
(@pxref{Calendar options, @samp{--starting-day=@var{argument}}, Calendar options: @samp{--starting-day=@var{argument}}}),
e.g.@::

@quotation
The text @w{@samp{Today is weekday %] , the %n}}
will be expanded to@*
@w{@expansion{} @samp{Today is weekday 3, the 10-Jun-1996}},
in case the actual system date is the 10th June 1996 and Friday (@equiv{}5)
is the starting day of week.
@end quotation

@item %@}@r{[}@var{date}@r{]}
@cindex Special text @code{%@}@r{[}@var{date}@r{]}}
@cindex @code{%@}@r{[}@var{date}@r{]}} special text, weekday number
@cindex Weekday number, @code{%@}@r{[}@var{date}@r{]}} special text
Is replaced by the @strong{weekday number} with trailing Ordinal Number suffix
of the current day, and which is determined by the
@cite{@var{starting day of week}@equiv{}0@dots{}@var{ending day of week}@equiv{}6}
counting method
(@pxref{Calendar options, @samp{--starting-day=@var{argument}}, Calendar options: @samp{--starting-day=@var{argument}}}),
e.g.@::

@quotation
The text @w{@samp{Today is weekday %@} , the %n}}
will be expanded to@*
@w{@expansion{} @samp{Today is weekday 3rd, the 10-Jun-1996}},
in case the actual system date is the 10th June 1996 and Friday (@equiv{}5)
is the starting day of week.
@end quotation
@end table

@node Day number, Day, Weekday, Replacements with date argument
@appendixsubsubsec Day number @code{%@var{?}@r{[}@var{date}@r{]}} special texts
@cindex Day number @code{%@var{?}@r{[}@var{date}@r{]}} special texts

The following day number @code{%@var{?}@r{[}@var{date}@r{]}} special texts
are respected:

@table @code
@item %+@r{[}@var{date}@r{]}
@cindex Special text @code{%+@r{[}@var{date}@r{]}}
@cindex @code{%+@r{[}@var{date}@r{]}} special text, day number
@cindex Day number, @code{%+@r{[}@var{date}@r{]}} special text
Is replaced by the @strong{day number} of the current day of year, e.g.@::

@quotation
The text @w{@samp{Day %+ @ of year, the %n}}
will be expanded to@*
@w{@expansion{} @samp{Day 53 of year, the 22-Feb-1996}},
in case the actual system date is the 22nd February 1996.
@end quotation

@item %*@r{[}@var{date}@r{]}
@cindex Special text @code{%*@r{[}@var{date}@r{]}}
@cindex @code{%*@r{[}@var{date}@r{]}} special text, day number
@cindex Day number, @code{%*@r{[}@var{date}@r{]}} special text
Is replaced by the 3-digit @strong{day number} with leading zeroes
of the current day of year, e.g.@::

@quotation
The text @w{@samp{Day %*0@@t-1 @ of year, the %n-1}}
will be expanded to@*
@w{@expansion{} @samp{Day 052 of year, the 21-Feb-1996}},
in case the actual system date is the 22nd February 1996.
@end quotation

@item %&@r{[}@var{date}@r{]}
@cindex Special text @code{%&@r{[}@var{date}@r{]}}
@cindex @code{%&@r{[}@var{date}@r{]}} special text, Day number
@cindex Day number, @code{%&@r{[}@var{date}@r{]}} special text
Is replaced by the @strong{day number} with trailing Ordinal Number suffix
of the current day of year, e.g.@::

@quotation
The text @w{@samp{Day %& @ of year, the %n}}
will be expanded to@*
@w{@expansion{} @samp{Day 53rd of year, the 22-Feb-1996}},
in case the actual system date is the 22nd February 1996.
@end quotation

@item %#@r{[}@var{date}@r{]}
@cindex Special text @code{%#@r{[}@var{date}@r{]}}
@cindex @code{%#@r{[}@var{date}@r{]}} special text, day number
@cindex Day number, @code{%#@r{[}@var{date}@r{]}} special text
Is replaced by the 3-digit @strong{day number} with leading zeroes and trailing
Ordinal Number suffix of the current day of year, e.g.@::

@quotation
The text @w{@samp{Day %# @ of year, the %n}}
will be expanded to@*
@w{@expansion{} @samp{Day 053rd of year, the 22-Feb-1996}},
in case the actual system date is the 22nd February 1996.
@end quotation
@end table

@node Day, Week, Day number, Replacements with date argument
@appendixsubsubsec Day @code{%@var{?}@r{[}@var{date}@r{]}} special texts
@cindex Day @code{%@var{?}@r{[}@var{date}@r{]}} special texts

The following day @code{%@var{?}@r{[}@var{date}@r{]}} special texts
are respected:

@table @code
@item %D@r{[}@var{date}@r{]}
@cindex Special text @code{%D@r{[}@var{date}@r{]}}
@cindex @code{%D@r{[}@var{date}@r{]}} special text, day
@cindex Day, @code{%D@r{[}@var{date}@r{]}} special text
Is replaced by the @strong{day number} of the current day of month, e.g.@::

@quotation
The text @w{@samp{Day %D , %n}}
will be expanded to@*
@w{@expansion{} @samp{Day 2, 02-Feb-1996}},
in case the actual system date is the 2nd February 1996.
@end quotation

@item %N@r{[}@var{date}@r{]}
@cindex Special text @code{%N@r{[}@var{date}@r{]}}
@cindex @code{%N@r{[}@var{date}@r{]}} special text, day
@cindex Day, @code{%N@r{[}@var{date}@r{]}} special text
Is replaced by the 2-digit @strong{day number} with leading zero of the
current day of month, e.g.@::

@quotation
The text @w{@samp{Day %N0@@t-1 , %n-1}}
will be expanded to@*
@w{@expansion{} @samp{Day 01, 01-Feb-1996}},
in case the actual system date is the 2nd February 1996.
@end quotation

@item %s@r{[}@var{date}@r{]}
@cindex Special text @code{%s@r{[}@var{date}@r{]}}
@cindex @code{%s@r{[}@var{date}@r{]}} special text, day
@cindex Day, @code{%s@r{[}@var{date}@r{]}} special text
Is replaced by the @strong{day number} with trailing Ordinal Number suffix
of the current day of month, e.g.@::

@quotation
The text @w{@samp{Day %s , %n}}
will be expanded to@*
@w{@expansion{} @samp{Day 2nd, 02-Feb-1996}},
in case the actual system date is the 2nd February 1996.
@end quotation

@item %u@r{[}@var{date}@r{]}
@cindex Special text @code{%u@r{[}@var{date}@r{]}}
@cindex @code{%u@r{[}@var{date}@r{]}} special text, day
@cindex Day, @code{%u@r{[}@var{date}@r{]}} special text
Is replaced by the 2-digit @strong{day number} with leading zero and trailing
Ordinal Number suffix of the current day of month, e.g.@::

@quotation
The text @w{@samp{Day %u , %n}}
will be expanded to@*
@w{@expansion{} @samp{Day 02nd, 02-Feb-1996}},
in case the actual system date is the 2nd February 1996.
@end quotation
@end table

@page
@node Week, Month name, Day, Replacements with date argument
@appendixsubsubsec Week @code{%@var{?}@r{[}@var{date}@r{]}} special text
@cindex Week @code{%@var{?}@r{[}@var{date}@r{]}} special text

The following week @code{%@var{?}@r{[}@var{date}@r{]}} special text
are respected:

@table @code
@item %k@r{[}@var{date}@r{]}
@cindex Special text @code{%k@r{[}@var{date}@r{]}}
@cindex @code{%k@r{[}@var{date}@r{]}} special text, week
@cindex Week, @code{%k@r{[}@var{date}@r{]}} special text
@cindex @sc{iso}-8601:1988
Is replaced by the @strong{@sc{iso}-week number} of the current week of year,
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 actual system date is the 10th June 1996.
@end quotation
@end table

@node Month name, Month, Week, Replacements with date argument
@appendixsubsubsec Month name @code{%@var{?}@r{[}@var{date}@r{]}} special texts
@cindex Month name @code{%@var{?}@r{[}@var{date}@r{]}} special texts

The following month name @code{%@var{?}@r{[}@var{date}@r{]}} special texts
are respected:

@table @code
@item %M@r{[}@var{date}@r{]}
@cindex Special text @code{%M@r{[}@var{date}@r{]}}
@cindex @code{%M@r{[}@var{date}@r{]}} special text, complete month name
@cindex Complete month name, @code{%M@r{[}@var{date}@r{]}} special text
Is replaced by the complete @strong{month name} of the current month of year,
e.g.@::

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

@item %T@r{[}@var{date}@r{]}
@cindex Special text @code{%T@r{[}@var{date}@r{]}}
@cindex @code{%T@r{[}@var{date}@r{]}} special text, 3-letter month name
@cindex 3-letter month name, @code{%T@r{[}@var{date}@r{]}} special text
Is replaced by the 3-letter @strong{month name} of the current month of year,
e.g.@::

@quotation
The text @w{@samp{Today is %T19961010 , %n}}
will be expanded to@*
@w{@expansion{} @samp{Today is Oct, 10-Jun-1996}},
in case the actual system date is the 10th June 1996.
@end quotation
@end table

@node Month, Year, Month name, Replacements with date argument
@appendixsubsubsec Month @code{%@var{?}@r{[}@var{date}@r{]}} special texts
@cindex Month @code{%@var{?}@r{[}@var{date}@r{]}} special texts

The following month @code{%@var{?}@r{[}@var{date}@r{]}} special texts
are respected:

@table @code
@item %U@r{[}@var{date}@r{]}
@cindex Special text @code{%U@r{[}@var{date}@r{]}}
@cindex @code{%U@r{[}@var{date}@r{]}} special text, month
@cindex Month, @code{%U@r{[}@var{date}@r{]}} special text
Is replaced by the @strong{month number} of the current month of year, e.g.@::

@quotation
The text @w{@samp{Month %U , %n}}
will be expanded to@*
@w{@expansion{} @samp{Month 2, 22-Feb-1996}},
in case the actual system date is the 22nd February 1996.
@end quotation

@cindex Special text @code{%W@r{[}@var{date}@r{]}}
@item %W@r{[}@var{date}@r{]}
@cindex @code{%W@r{[}@var{date}@r{]}} special text, Month
@cindex Month, @code{%W@r{[}@var{date}@r{]}} special text
Is replaced by the 2-digit @strong{month number} with leading zero
of the current month of year, e.g.@::

@quotation
The text @w{@samp{Month %W000001 , %n}}
will be expanded to@*
@w{@expansion{} @samp{Month 01, 22-Feb-1996}},
in case the actual system date is the 22nd February 1996.
@end quotation

@item %z@r{[}@var{date}@r{]}
@cindex Special text @code{%z@r{[}@var{date}@r{]}}
@cindex @code{%z@r{[}@var{date}@r{]}} special text, Month
@cindex Month, @code{%z@r{[}@var{date}@r{]}} special text
Is replaced by the @strong{month number} with trailing Ordinal Number suffix
of the current month of year, e.g.@::

@quotation
The text @w{@samp{Month %z , %n}}
will be expanded to@*
@w{@expansion{} @samp{Month 2nd, 22-Feb-1996}},
in case the actual system date is the 22nd February 1996.
@end quotation

@item %Z@r{[}@var{date}@r{]}
@cindex Special text @code{%Z@r{[}@var{date}@r{]}}
@cindex @code{%Z@r{[}@var{date}@r{]}} special text, Month
@cindex Month, @code{%Z@r{[}@var{date}@r{]}} special text
Is replaced by the 2-digit @strong{month number} with leading zero and trailing
Ordinal Number suffix of the current month of year, e.g.@::

@quotation
The text @w{@samp{Month %Z , %n}}
will be expanded to@*
@w{@expansion{} @samp{Month 02nd, 22-Feb-1996}},
in case the actual system date is the 22nd February 1996.
@end quotation
@end table

@node Year, Moonphase, Month, Replacements with date argument
@appendixsubsubsec Year @code{%@var{?}@r{[}@var{date}@r{]}} special texts
@cindex Year @code{%@var{?}@r{[}@var{date}@r{]}} special texts

The following year @code{%@var{?}@r{[}@var{date}@r{]}} special texts
are respected:

@table @code
@item %Y@r{[}@var{date}@r{]}
@cindex Special text @code{%Y@r{[}@var{date}@r{]}}
@cindex @code{%Y@r{[}@var{date}@r{]}} special text, year
@cindex Year, @code{%Y@r{[}@var{date}@r{]}} special text
Is replaced by the @strong{year number} of the current year, e.g.@::

@quotation
The text @w{@samp{Year %Y , %n}}
will be expanded to@*
@w{@expansion{} @samp{Year 933, 22-Feb-0933}},
in case the actual system date is the 22nd February 933.
@end quotation

@item %=@r{[}@var{date}@r{]}
@cindex Special text @code{%=@r{[}@var{date}@r{]}}
@cindex @code{%=@r{[}@var{date}@r{]}} special text, year
@cindex Year, @code{%=@r{[}@var{date}@r{]}} special text
Is replaced by the 4-digit @strong{year number} with leading zeroes
of the current year, e.g.@::

@quotation
The text @w{@samp{Year %=0015 , %n}}
will be expanded to@*
@w{@expansion{} @samp{Year 0015, 22-Feb-0933}},
in case the actual system date is the 22nd February 933.
@end quotation
@end table

@node Moonphase, Biorhythm, Year, Replacements with date argument
@appendixsubsubsec Moonphase @code{%@var{?}@r{[}@var{date}@r{]}} special texts
@cindex Moonphase @code{%@var{?}@r{[}@var{date}@r{]}} special texts

Gcal uses a very simple algorithm for detecting the moonphase, which computes
approximate values only.  The moonphase is always calculated at 0 o'clock
universal time.  The following moonphase @code{%@var{?}@r{[}@var{date}@r{]}}
special texts are respected:

@table @code
@item %-@r{[}@var{date}@r{]}
@cindex Special text @code{%-@r{[}@var{date}@r{]}}
@cindex @code{%-@r{[}@var{date}@r{]}} special text, moonphase
@cindex Moonphase, @code{%-@r{[}@var{date}@r{]}} special text
Is replaced by the @strong{moonphase text} of the current day of year, e.g.@::

@quotation
The text @w{@samp{Moonphase %- , %n}}
will be expanded to@*
@w{@expansion{} @samp{Moonphase 94%+, 22-Dec-1996}},
in case the actual system date is the 22nd December 1996.
@end quotation

The constructed moonphase text consists of a percent value, which informs
about the illuminated fraction of the Moon's disc, and a trailing sign that
tells something about the state of the Moon.  A trailing @samp{+} sign 
indicates a waxing Moon, a @samp{-} sign a waning moon, a @samp{@@} sign
indicates the Full Moon phase, and a @samp{!} sign the New Moon phase.

@item %_@r{[}@var{date}@r{]}
@cindex Special text @code{%_@r{[}@var{date}@r{]}}
@cindex @code{%_@r{[}@var{date}@r{]}} special text, moonphase
@cindex Moonphase, @code{%_@r{[}@var{date}@r{]}} special text
Is replaced by the 3-digit @strong{moonphase text} with leading zeroes
of the current day of year, e.g.@::

@quotation
The text @w{@samp{Moonphase %_0@@t+1 , %n+1}}
will be expanded to@*
@w{@expansion{} @samp{Moonphase 098%+, 23-Dec-1996}},
in case the actual system date is the 22nd December 1996.
@end quotation

The constructed moonphase text consists of a percent value, which informs
about the illuminated fraction of the Moon's disc, and a trailing sign that
tells something about the state of the Moon.  A trailing @samp{+} sign 
indicates a waxing Moon, a @samp{-} sign a waning moon, a @samp{@@} sign
indicates the Full Moon phase, and a @samp{!} sign the New Moon phase.

@page
@item %:@r{[}@var{date}@r{]}
@cindex Special text @code{%:@r{[}@var{date}@r{]}}
@cindex @code{%:@r{[}@var{date}@r{]}} special text, moonphase text graphics
@cindex Moonphase text graphics, @code{%:@r{[}@var{date}@r{]}} special text
Is replaced by the @strong{moonphase text graphics} of the current day of year,
e.g.@::

@quotation
The text @w{@samp{Date %n %: @ --- Moonphase %_ ~Text}}
will be expanded to@*
@w{@expansion{} @samp{Date 08-Mar-1995 }}@*
@w{@expansion{} @samp{ @ @ @ @ @ @ @ @ @ @ ( @ @ @ @ @ @ @@@@@@@@@@@@}}@*
@w{@expansion{} @samp{ @ @ @ @ @ ( @ @ @ @ @ @ @ @ @ @ @ @ @ @@@@@@@@@@@@@@@@@@}}@*
@w{@expansion{} @samp{ @ @ @ ( @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @@@@@@@@@@@@@@@@@@@@@@}}@*
@w{@expansion{} @samp{ @ ( @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @@@@@@@@@@@@@@@@@@@@@@@@}}@*
@w{@expansion{} @samp{ ( @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @@@@@@@@@@@@@@@@@@@@@@@@@@}}@*
@w{@expansion{} @samp{( @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @@@@@@@@@@@@@@@@@@@@@@@@@@}}@*
@w{@expansion{} @samp{( @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @@@@@@@@@@@@@@@@@@@@@@@@@@}}@*
@w{@expansion{} @samp{ ( @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @@@@@@@@@@@@@@@@@@@@@@@@@@}}@*
@w{@expansion{} @samp{ @ ( @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @@@@@@@@@@@@@@@@@@@@@@@@}}@*
@w{@expansion{} @samp{ @ @ ( @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @@@@@@@@@@@@@@@@@@@@@@}}@*
@w{@expansion{} @samp{ @ @ @ @ @ ( @ @ @ @ @ @ @ @ @ @ @ @ @@@@@@@@@@@@@@@@@@}}@*
@w{@expansion{} @samp{ @ @ @ @ @ @ @ @ @ @ ( @ @ @ @ @ @ @ @@@@@@@@@@@@@@ --- Moonphase 041%+}}@*
@w{@expansion{} @samp{Text}},
in case the actual system date is the 8th March 1995.
@end quotation

@xref{Fixed date options, @samp{--moonimage-lines=@var{number}}, Fixed date options: @samp{--moonimage-lines=@var{number}}},
for how to change the size of a moonphase text graphics.
@end table

@node Biorhythm, Difference value, Moonphase, Replacements with date argument
@appendixsubsubsec Biorhythm @code{%@var{?}@r{[}@var{date}@r{]}} special texts
@cindex Biorhythm @code{%@var{?}@r{[}@var{date}@r{]}} special texts

Gcal is able to create a @dfn{biorhythm} for any specified date of birth.
The created text shows the three standard biorhythm cycles, and that are the
28 day emotional cycle, the 33 day intellectual cycle, and the 23 day physical
cycle.  The emotional cycle governs sensibility, nerves, moodiness, and
creative ability.  The intellectual cycle reflects intelligence, memory,
mental alertness, and reasoning power.  The physical cycle represents physical
strength, endurance, energy and resistance.  All cycles start in the zero point
at the date of birth and swing like sine curves between their positive and
negative maximum values.  The periods above the zero point show the days of
full vitality and efficiency while the periods below the zero point indicate
days of reduced efficiency.  The biorhythm is implemented for entertaining
purposes only!  It is up to the user to interpret the biorhythm texts.

@cindex Biorhythm, critical day 
@cindex Critical day, biorhythm 
@cindex Biorhythm, positive day 
@cindex Positive day, biorhythm 
@cindex Biorhythm, negative day 
@cindex Negative day, biorhythm 
Gcal counts @dfn{critical} days, @dfn{positive} likewise @dfn{negative} days.
Critical days are those days in which one or more of the biological cycles
crosses the zero point.  At that time, one's system is said to be in a state
of flux and it may be desirable to exhibit caution.
Positive days are those days in which one or more of the biological cycles have
a positive maximum value.  At that time, one's system is said to be in a raised
state.
Negative days are those days in which one or more of the biological cycles have
a negative maximum value.  At that time, one's system is said to be in a lessen
state.

The following biorhythm @code{%@var{?}@r{[}@var{date}@r{]}} special texts
are respected:

@table @code
@item %,@r{[}@var{date}@r{]}
@cindex Special text @code{%,@r{[}@var{date}@r{]}}
@cindex @code{%,@r{[}@var{date}@r{]}} special text, biorhythm
@cindex Biorhythm, @code{%,@r{[}@var{date}@r{]}} special text
Is replaced by the @strong{biorhythm text} of the current day of year, e.g.@::

@quotation
The text @w{@samp{%,19620921}}
will be expanded to@*
@w{@expansion{} @samp{1! 0+ 0- , Emo=+022%- Int=-091%+ Phy=-014%-}},
in case the actual system date is the 12th December 1996.
@end quotation

The preceding example shows the calculated biorhythm expressed as a series
of values for a person born in 1962, September 21st.  The constructed text
consists of two parts, and that is on the one hand a triplet of total values
which indicate the critical, positive and negative day.  And on the other
hand a triplet of values, which indicate the emotional, intellectual and
physical cycle.

In the first triplet of total values, a @samp{!} suffix means a critical day,
a @samp{+} indicates a positive day, and a @samp{-} suffix marks a negative day.

In the second triplet of values, each single cycle percent value consists of
a leading positive or negative sign, that tells something about the distance
of this value to the zero point, and a trailing character, that tells something
about the state of each cycle.  A trailing @samp{+} character marks a waxing
phase, a @samp{-} suffix means a waning phase, and a @samp{@@} indicates the
maximum value of a phase.

@item %;@r{[}@var{date}@r{]}
@cindex Special text @code{%;@r{[}@var{date}@r{]}}
@cindex @code{%;@r{[}@var{date}@r{]}} special text, biorhythm text graphics
@cindex Biorhythm text graphics, @code{%;@r{[}@var{date}@r{]}} special text
Is replaced by the @strong{biorhythm text graphics} of the current day of year,
e.g.@::

@quotation
The text @w{@samp{%;19620921}}
will be expanded to@*
@w{@expansion{} @samp{0- @ I @ @ @ @ @ @ @ @ @ @ @ @ @ @ P 1 @ @ E @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ +0}},
in case the actual system date is the 12th December 1996.
@end quotation

The preceding example shows the calculated biorhythm expressed as a text
graphics line for a person born in 1962, September 21st.  The constructed
line is a bar with a negative and positive axis of adjustable length
(@pxref{Fixed date options, @samp{--biorhythm-axis=@var{number}}, Fixed date options: @samp{--biorhythm-axis=@var{number}}}),
which left margin is represented by the total value of the negative days (the
@samp{0-} in this case), and which right margin is represented by the total
value of the positive days (the @samp{+0} in this case).  The zero point of
the co-ordinate is represented by the total value of the critical days, which
is the @samp{1} in this case.  The emotional, intellectual and the physical
phase value is accordingly placed in scaled manner on this bar, and that by
using the initial letter of the cycle in each case (@samp{E}, @samp{I} and
@samp{P}).  Collapsing phase values are marked by a @samp{@@} character.
@end table

@node Difference value, , Biorhythm, Replacements with date argument
@appendixsubsubsec Difference value @code{%@var{?}@r{[}@var{date}@r{]}} special texts
@cindex Difference value @code{%@var{?}@r{[}@var{date}@r{]}} special texts

The following difference value @code{%@var{?}@r{[}@var{date}@r{]}} special texts
are respected:

@table @code
@item %y@var{date}
@cindex Special text @code{%y@var{date}}
@cindex @code{%y@var{date}} special text, relative year number
@cindex Relative year number, @code{%y@var{date}} special text
@cindex Year difference value
Is replaced by a @strong{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 the year of the actual system date is 1994.
@end quotation

@item %b@r{[}@var{date}@r{]}
@cindex Special text @code{%b@r{[}@var{date}@r{]}}
@cindex @code{%b@r{[}@var{date}@r{]}} special text, birthday
@cindex Birthday, @code{%b@r{[}@var{date}@r{]}} special text
@cindex Age value
Is replaced by an @strong{age value}, e.g.@::

@quotation
The text @w{@samp{My %b1962 @ birthday%i1952#2062}}
will be expanded to@*
@w{@expansion{} @samp{My 32 birthday}},
in case the year of the actual system date is 1994.
@end quotation

Those age values are only displayed, 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.

@item %B@r{[}@var{date}@r{]}
@cindex Special text @code{%B@r{[}@var{date}@r{]}}
@cindex @code{%B@r{[}@var{date}@r{]}} special text, birthday
@cindex Birthday, @code{%B@r{[}@var{date}@r{]}} special text
@cindex Age value
Is replaced by an @strong{age value} with trailing Ordinal Number suffix,
e.g.@::

@quotation
The text @w{@samp{My %B1962 @ birthday%i1952#2062}}
will be expanded to@*
@w{@expansion{} @samp{My 32nd birthday}},
in case the year of the actual system date is 1994.
@end quotation

Those age values are only displayed, 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.
@end table

@node Replacements with other argument, Replacements without any argument, Replacements with date argument, Replacements
@appendixsubsec Replacements with other argument @code{%@var{?}@r{[}@var{argument}@r{]}} special texts
@cindex Replacements with other argument @code{%@var{?}@r{[}@var{argument}@r{]}} special texts

@menu
* Actual time::
* Textual date::
* Julian day number::
@end menu

Apart from different representations of the actual system time, a fixed
format date text can be created.  Moreover, it is possible to produce
a day number, which bears the Julian date as base date and which can be
deferred if needed.

For the @var{argument} these @code{%@var{?}@r{[}@var{argument}@r{]}}
special text may have, no special rules concerning definite omission
values are valid.

@node Actual time, Textual date, Replacements with other argument, Replacements with other argument
@appendixsubsubsec Actual time @code{%t@r{[}@var{argument}@r{]}} special text
@cindex Special text @code{%t@r{[}@var{argument}@r{]}}
@cindex Actual time @code{%t@r{[}@var{argument}@r{]}} special text
@cindex @code{%t@r{[}@var{argument}@r{]}} special text, actual time
@cindex Actual system time, display the

@code{%t@r{[}12@r{|}24@r{]}} references the @strong{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 o'clock} @w{(hh:mm)}.
@end quotation

@cindex @code{%t12} special text
@cindex @code{%t24} special text
If only @code{%t} is specified, the system time value will implicitly
be displayed using the @emph{24-hour} format (@equiv{}@code{%t24}).  For
displaying using the @emph{12-hour} format, add @code{12} directly behind
@code{%t}, e.g.@: @samp{%t12}.

@node Textual date, Julian day number, Actual time, Replacements with other argument
@appendixsubsubsec Textual date @code{%n@r{[}@var{argument}@r{]}} special text
@cindex Special text @code{%n@r{[}@var{argument}@r{]}}
@cindex Textual date @code{%n@r{[}@var{argument}@r{]}} special text
@cindex @code{%n@r{[}@var{argument}@r{]}} special text, textual date
@cindex Fixed format date 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 replaced by a @strong{date text} in the fixed
@samp{@var{dd}-@var{mmm}-@var{yyyy}} format, e.g.@::

@quotation
The resource file line @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, , Single commands: @samp{@var{mm} @var{yyyy}}}).
@end quotation

@node Julian day number, , Textual date, Replacements with other argument
@appendixsubsubsec Julian day number @code{%j@r{[}@var{argument}@r{]}} special text
@cindex Special text @code{%j@r{[}@var{argument}@r{]}}
@cindex Julian day number @code{%j@r{[}@var{argument}@r{]}} special text
@cindex @code{%j@r{[}@var{argument}@r{]}} special text, Julian day number

@code{%j@r{[[}-@r{]}@var{n}@r{]}} references the current respectively
queried @dfn{Julian day number} relative to the actual system date
(@equiv{}today).  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.  Currently, Gcal does not
evaluate the time zone 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 special text always by one, e.g.@: @samp{%j-1}.

@page
@noindent
For example:

@quotation
The resource file 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 @footnote{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 resource file 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 Replacements without any argument, , Replacements with other argument, Replacements
@appendixsubsec Replacements without any argument @code{%@var{?}} special texts
@cindex Replacements without any argument @code{%@var{?}} special texts

@menu
* Other difference values::
* Highlighting::
@end menu

Apart from further useful difference values, the text of a fixed date can
be provided with different texts used for highlighting.

@node Other difference values, Highlighting, Replacements without any argument, Replacements without any argument
@appendixsubsubsec Difference value @code{%@var{?}} special texts
@cindex Difference value @code{%@var{?}} special texts

The following other difference values @code{%@var{?}} special texts
are respected:

@table @code
@item %d
@cindex Special text @code{%d}
@cindex @code{%d} special text, relative day number
@cindex Relative day number, @code{%d} special text
Specifies the current respectively queried @strong{day}
relative to the actual system date (@equiv{}today), e.g.@::

@quotation
The resource file line @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

@item %w
@cindex Special text @code{%w}
@cindex @code{%w} special text, relative week number
@cindex Relative week number, @code{%w} special text
Specifies the current respectively queried @strong{week}
relative to the actual system date (@equiv{}today).

@item %m
@cindex Special text @code{%m},
@cindex @code{%m} special text, relative month number
@cindex Relative month number, @code{%m} special text
Specifies the current respectively queried @strong{month}
relative to the actual system date (@equiv{}today).

@item %y
@cindex Special text @code{%y}
@cindex @code{%y} special text, relative year number
@cindex Relative year number, @code{%y} special text
Specifies the current respectively queried @strong{year}
relative to the actual system date (@equiv{}today).
@end table

@node Highlighting, , Other difference values, Replacements without any argument
@appendixsubsubsec Highlighting @code{%@var{?}} special texts
@cindex Highlighting @code{%@var{?}} special texts

The following highlighting @code{%@var{?}} special texts
are respected:

@table @code
@item %1
@cindex Special text @code{%1}
@cindex @code{%1} special text, start of highlighting sequence 1
@cindex Start of highlighting sequence 1, @code{%1} special text
@code{%1} is replaced by the starting highlighting sequence respectively
the starting marking character that is used for highlighting the actual day
(@pxref{Global options, @samp{--highlighting=@var{text}}, Global options: @samp{--highlighting=@var{text}}}).
This attains, that all succeeding text of the line after this special text is
displayed in the same way as the highlighted respectively marked actual day.
@code{%1} is used together with the @code{%2} special 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

@item %2
@cindex Special text @code{%2}
@cindex @code{%2} special text, end of highlighting sequence 1
@cindex End of highlighting sequence 1, @code{%2} special text
@code{%2} is replaced by the ending highlighting sequence respectively
the ending marking character that 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} special text.
The @code{%2} text has no effect if no preceding @code{%1} text was
found on the line.

@item %3
@cindex Special text @code{%3}
@cindex @code{%3} special text, start of highlighting sequence 2
@cindex Start of highlighting sequence 2, @code{%3} special text
@code{%3} is replaced by the starting highlighting sequence respectively
the starting marking character that is used for highlighting a holiday,
(@pxref{Global options, @samp{--highlighting=@var{text}}, Global options: @samp{--highlighting=@var{text}}}).
This attains, that all succeeding text of the line after this special text
is displayed in the same way as the highlighted respectively marked holiday.
@code{%3} is used together with the @code{%4} special 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.

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

@item %4
@cindex Special text @code{%4}
@cindex @code{%4} special text, end of highlighting sequence 2
@cindex End of highlighting sequence 2, @code{%4} special text
@code{%4} is replaced by the ending highlighting sequence respectively
the ending marking character that is used for highlighting a holiday.
This attains, that a possibly active highlighting according to a holiday
is turned off respectively an ending marking character is produced.
@code{%4} is used together with the @code{%3} special text.  The @code{%4}
text has no effect if no preceding @code{%3} text was found on the line.

@item %5
@cindex Special text @code{%5}
@cindex @code{%5} special text, start of highlighting sequence 1
@cindex Start of highlighting sequence 1, @code{%5} special text
@code{%5} is replaced by the starting highlighting sequence respectively
the starting marking character that is used for highlighting the actual day
if a fixed date is on today's date,
(@pxref{Global options, @samp{--highlighting=@var{text}}, Global options: @samp{--highlighting=@var{text}}}).
This attains, that all succeeding text of the line after this special text is
displayed in the same way as the highlighted respectively marked actual day.
@code{%5} is used together with the @code{%6} special text --- which turns
off this enabled highlighting sequence respectively produces the ending marking
character.  If a @code{%5} text is not succeeded by a @code{%6} text on the
line, Gcal automatically inserts such a @code{%6} text at the end of the line.

@item %6
@cindex Special text @code{%6}
@cindex @code{%6} special text, end of highlighting sequence 1
@cindex End of highlighting sequence 1, @code{%6} special text
@code{%6} is replaced by the ending highlighting sequence respectively
the ending marking character that is used for highlighting the actual
day if a fixed date is on today's date.  This attains, that a possibly
active highlighting according to the actual day is turned off respectively
an ending marking character is produced.  @code{%6} is used together with
the @code{%5} special text.  The @code{%6} text has no effect if no preceding
@code{%5} text was found on the line.

@item %7
@cindex Special text @code{%7}
@cindex @code{%7} special text, start of highlighting sequence 2
@cindex Start of highlighting sequence 2, @code{%7} special text
@code{%7} is replaced by the starting highlighting sequence respectively
the starting marking character that is used for highlighting a holiday
if a fixed date is on a legal holiday date,
(@pxref{Global options, @samp{--highlighting=@var{text}}, Global options: @samp{--highlighting=@var{text}}}).
This attains, that all succeeding text of the line after this special text
is displayed in the same way as the highlighted respectively marked holiday.
@code{%7} is used together with the @code{%8} special text --- which turns
off this enabled highlighting sequence respectively produces the ending marking
character.  If a @code{%7} text is not succeeded by a @code{%8} text on the
line, Gcal automatically inserts such a @code{%8} text at the end of the line.

@item %8
@cindex Special text @code{%8}
@cindex @code{%8} special text, end of highlighting sequence 2
@cindex End of highlighting sequence 2, @code{%8} special text
@code{%8} is replaced by the ending highlighting sequence respectively
the ending marking character that is used for highlighting a holiday if
a fixed date is on a legal holiday date.  This attains, that a possibly
active highlighting according to a holiday is turned off respectively an
ending marking character is produced.  @code{%8} is used together with the
@code{%7} special text.  The @code{%8} text has no effect if no preceding
@code{%7} text was found on the line.

@item %9
@cindex Special text @code{%9}
@cindex @code{%9} special text, start of highlighting sequence 1 or 2
@cindex Start of highlighting sequence 1 or 2, @code{%9} special text
@code{%9} is replaced by the starting highlighting sequence respectively the
starting marking character that is used for highlighting the actual day if a
fixed date is on today's date; otherwise @code{%9} is replaced by the starting
highlighting sequence respectively the starting marking character that is used
for highlighting a holiday if a fixed date is on a legal holiday date,
(@pxref{Global options, @samp{--highlighting=@var{text}}, Global options: @samp{--highlighting=@var{text}}}).
This attains, that all succeeding text of the line after this special text
is displayed in the same way as the highlighted respectively marked actual
day or holiday.  @code{%9} is used together with the @code{%0} special text
--- which turns off this enabled highlighting sequence respectively produces
the ending marking character.  If a @code{%9} text is not succeeded by a
@code{%0} text on the line, Gcal automatically inserts such a @code{%0}
text at the end of the line.

@item %0
@cindex Special text @code{%0}
@cindex @code{%0} special text, end of highlighting sequence 1 or 2
@cindex End of highlighting sequence 1 or 2, @code{%0} special text
@code{%0} is replaced by the ending highlighting sequence respectively the
ending marking character that is used for highlighting the actual day if a
fixed date is on today's date; otherwise @code{%0} is replaced by the ending
highlighting sequence respectively the ending marking character that is used
for highlighting a holiday if a fixed date is on a legal holiday date.
This attains, that a possibly active highlighting according to today's date
or a holiday is turned off respectively an ending marking character is produced.
@code{%0} is used together with the @code{%9} special text.  The @code{%0} text
has no effect if no preceding @code{%9} text was found on the line.
@end table

@node Shell Command, , Replacements, Special Texts
@appendixsec Shell command @code{%!@r{[}@var{argument}@r{]}} special text
@cindex Special text @code{%!@r{[}@var{argument}@r{]}}
@cindex Shell command @code{%!@r{[}@var{argument}@r{]}} special text
@cindex @code{%!@r{[}@var{argument}@r{]}} special text, shell Kommando
@cindex Shell command, execution of
The @var{argument} which trails @code{%!} until the end of the line, is
passed to the shell as a command for further processing.  But before, all
@code{%@var{?}}@dots{} special texts for replacing particular texts which
are given in @var{argument} are interpreted by Gcal.
@xref{Replacements with date argument, , Replacements with date argument @code{%@var{?}@r{[}@var{date}@r{]}} special texts}.
All leading text before the @code{%!} special text is processed by Gcal as
usual.  If the simple @samp{--debug} respectively @w{@samp{--debug=internal}}
option is given at program start-up, informational messages about the executed
command and its @emph{exit} code will be shown on the @emph{standard error
channel}
(@pxref{Global options, @samp{--debug=internal}, Global options: @samp{--debug=internal}}).

@cindex Error code 2
@cindex Exit code 2
If the @w{@samp{--debug=abort}} option is given, the Gcal program will be
aborted with an error code in case an @emph{exit} code not equal zero have
occurred during the execution of the command.
@xref{Error Codes, 2, Error Codes: 2},
and
@ref{Global options, @samp{--debug=abort}, Global options: @samp{--debug=abort}},
for more information.

Use the @samp{--bypass-shell-command} option if you want to see all
@code{%!@r{[}@var{argument}@r{]}} special texts textually and non-executed
by the shell.
@xref{Fixed date options, @samp{--bypass-shell-command}, Fixed date options: @samp{--bypass-shell-command}},
for more details.

@node Special Texts Summary, Coding Scheme, Special Texts, Top
@appendix Summary of all @code{%@var{?}}@dots{} Special Texts
@cindex @code{%@var{?}}@dots{} special texts, short-list of all
@cindex @code{%@var{?}}@dots{} special texts, summary of all
@cindex Summary of all @code{%@var{?}}@dots{} special texts
@cindex Short-list of all @code{%@var{?}}@dots{} special texts

Here is a short-list of all @code{%@var{?}}@dots{} special texts which
can be used in the text part of Gcal resource file line:
@sp 2

@table @asis
@item @code{%i@r{[}@var{date}@r{][}#@r{[}@var{date}@r{]]}}
@cindex Inclusive date period, @code{%i@r{[}@var{date}@r{][}#@r{[}@var{date}@r{]]}} special text
Exclusion of all non-inclusive date periods

@item @code{%e@r{[}@var{date}@r{][}#@r{[}@var{date}@r{]]}}
@cindex Exclusive date period, @code{%e@r{[}@var{date}@r{][}#@r{[}@var{date}@r{]]}} special text
Exclusion of all exclusive date periods

@item @code{%@var{?}} Inclusive day period
@cindex Inclusive day period @code{%@var{?}} special texts

@table @asis
@item @code{%v}
@cindex @code{%v} special text, inclusive legal holidays
Exclusion of all non-legal holidays

@item @code{%x}
@cindex @code{%x} special text, inclusive all holidays
Exclusion of all non-holidays

@item @code{%a}
@cindex @code{%a} special text, inclusive Monday
Exclusion of all non-Mondays

@item @code{%c}
@cindex @code{%c} special text, inclusive Tuesday
Exclusion of all non-Tuesdays

@item @code{%f}
@cindex @code{%f} special text, inclusive Wednesday
Exclusion of all non-Wednesdays

@item @code{%g}
@cindex @code{%g} special text, inclusive Thursday
Exclusion of all non-Thursdays

@item @code{%h}
@cindex @code{%h} special text, inclusive Friday
Exclusion of all non-Fridays

@item @code{%l}
@cindex @code{%l} special text, inclusive Saturday
Exclusion of all non-Saturdays

@item @code{%p}
@cindex @code{%p} special text, inclusive Sunday
Exclusion of all non-Sundays

@item @code{%q}
@cindex @code{%q} special text, inclusive Monday@dots{}Thursday
Exclusion of all non-Mondays@dots{}Thursdays

@item @code{%r}
@cindex @code{%r} special text, inclusive Monday@dots{}Friday
Exclusion of all non-Mondays@dots{}Fridays
@end table

@item @code{%@var{?}} Exclusive day period
@cindex Exclusive day period @code{%@var{?}} special texts

@table @asis
@item @code{%V}
@cindex @code{%V} special text, exclusive legal holidays
Exclusion of all legal holidays

@item @code{%X}
@cindex @code{%X} special text, exclusive all holidays
Exclusion of all holidays

@item @code{%A}
@cindex @code{%A} special text, exclusive Monday
Exclusion of all Mondays

@item @code{%C}
@cindex @code{%C} special text, exclusive Tuesday
Exclusion of all Tuesdays

@item @code{%F}
@cindex @code{%F} special text, exclusive Wednesday
Exclusion of all Wednesdays

@item @code{%G}
@cindex @code{%G} special text, exclusive Thursday
Exclusion of all Thursdays

@item @code{%H}
@cindex @code{%H} special text, exclusive Friday
Exclusion of all Fridays

@item @code{%L}
@cindex @code{%L} special text, exclusive Saturday
Exclusion of all Saturdays

@item @code{%P}
@cindex @code{%P} special text, exclusive Sunday
Exclusion of all Sundays

@item @code{%Q}
@cindex @code{%Q} special text, exclusive Monday@dots{}Thursday
Exclusion of all Mondays@dots{}Thursdays

@item @code{%R}
@cindex @code{%R} special text, exclusive Monday@dots{}Friday
Exclusion of all Mondays@dots{}Fridays
@end table

@page
@item @code{%@var{?}@r{[}@var{date}@r{]}} weekday name
@cindex Weekday name @code{%@var{?}@r{[}@var{date}@r{]}} special texts

@table @asis
@item @code{%o@r{[}@var{date}@r{]}}
@cindex @code{%o@r{[}@var{date}@r{]}} special text, complete weekday name
Complete weekday name

@item @code{%O@r{[}@var{date}@r{]}}
@cindex @code{%O@r{[}@var{date}@r{]}} special text, 3-letter weekday name
3-letter weekday name

@item @code{%K@r{[}@var{date}@r{]}}
@cindex @code{%K@r{[}@var{date}@r{]}} special text, 2-letter weekday name
2-letter weekday name
@end table

@item @code{%@var{?}@r{[}@var{date}@r{]}} weekday
@cindex Weekday @code{%@var{?}@r{[}@var{date}@r{]}} special texts

@table @asis
@item @code{%S@r{[}@var{date}@r{]}}
@cindex @code{%S@r{[}@var{date}@r{]}} special text, weekday number
Weekday number, Mon@equiv{}1@dots{}Sun@equiv{}7

@item @code{%I@r{[}@var{date}@r{]}}
@cindex @code{%I@r{[}@var{date}@r{]}} special text, weekday number
Weekday number, Mon@equiv{}1@dots{}Sun@equiv{}7, Ordinal Number suffix

@item @code{%E@r{[}@var{date}@r{]}}
@cindex @code{%E@r{[}@var{date}@r{]}} special text, weekday number
Weekday number, Mon@equiv{}0@dots{}Sun@equiv{}6

@item @code{%J@r{[}@var{date}@r{]}}
@cindex @code{%J@r{[}@var{date}@r{]}} special text, weekday number
Weekday number, Mon@equiv{}0@dots{}Sun@equiv{}6, Ordinal Number suffix

@item @code{%(@r{[}@var{date}@r{]}}
@cindex @code{%(@r{[}@var{date}@r{]}} special text, weekday number
Weekday number, Sun@equiv{}1@dots{}Sat@equiv{}7

@item @code{%<@r{[}@var{date}@r{]}}
@cindex @code{%<@r{[}@var{date}@r{]}} special text, weekday number
Weekday number, Sun@equiv{}1@dots{}Sat@equiv{}7, Ordinal Number suffix

@item @code{%)@r{[}@var{date}@r{]}}
@cindex @code{%)@r{[}@var{date}@r{]}} special text, weekday number
Weekday number, Sun@equiv{}0@dots{}Sat@equiv{}6, Ordinal Number suffix

@item @code{%>@r{[}@var{date}@r{]}}
@cindex @code{%>@r{[}@var{date}@r{]}} special text, weekday number
Weekday number, Sun@equiv{}0@dots{}Sat@equiv{}6, Ordinal Number suffix

@item @code{%[@r{[}@var{date}@r{]}}
@cindex @code{%[@r{[}@var{date}@r{]}} special text, weekday number
Weekday number, @var{starting day of week}@equiv{}1

@item @code{%@{@r{[}@var{date}@r{]}}
@cindex @code{%@{@r{[}@var{date}@r{]}} special text, weekday number
Weekday number, @var{starting day of week}@equiv{}1, Ordinal Number suffix

@item @code{%]@r{[}@var{date}@r{]}}
@cindex @code{%]@r{[}@var{date}@r{]}} special text, weekday number
Weekday number, @var{starting day of week}@equiv{}0

@item @code{%@}@r{[}@var{date}@r{]}}
@cindex @code{%@}@r{[}@var{date}@r{]}} special text, weekday number
Weekday number, @var{starting day of week}@equiv{}0, Ordinal Number suffix
@end table

@item @code{%@var{?}@r{[}@var{date}@r{]}} day number
@cindex Day number @code{%@var{?}@r{[}@var{date}@r{]}} special texts

@table @asis
@item @code{%+@r{[}@var{date}@r{]}}
@cindex @code{%+@r{[}@var{date}@r{]}} special text, day number
Day number

@item @code{%*@r{[}@var{date}@r{]}}
@cindex @code{%*@r{[}@var{date}@r{]}} special text, day number
Day number, 2-digits with leading zero

@item @code{%&@r{[}@var{date}@r{]}}
@cindex @code{%&@r{[}@var{date}@r{]}} special text, day number
Day number, Ordinal Number suffix

@item @code{%#@r{[}@var{date}@r{]}}
@cindex @code{%#@r{[}@var{date}@r{]}} special text, day number
Day number, 2-digits with leading zero, Ordinal Number suffix
@end table

@item @code{%@var{?}@r{[}@var{date}@r{]}} day
@cindex Day @code{%@var{?}@r{[}@var{date}@r{]}} special texts

@table @asis
@item @code{%D@r{[}@var{date}@r{]}}
@cindex @code{%D@r{[}@var{date}@r{]}} special text, day
Day

@item @code{%N@r{[}@var{date}@r{]}}
@cindex @code{%N@r{[}@var{date}@r{]}} special text, day
Day, 2-digits with leading zero

@item @code{%s@r{[}@var{date}@r{]}}
@cindex @code{%s@r{[}@var{date}@r{]}} special text, day
Day, Ordinal Number suffix

@item @code{%u@r{[}@var{date}@r{]}}
@cindex @code{%u@r{[}@var{date}@r{]}} special text, day
Day, 2-digits with leading zero, Ordinal Number suffix
@end table

@item @code{%k@r{[}@var{date}@r{]}}
@cindex Week @code{%@var{?}@r{[}@var{date}@r{]}} special text
@sc{iso}-week number

@item @code{%@var{?}@r{[}@var{date}@r{]}} month name
@cindex Month name @code{%@var{?}@r{[}@var{date}@r{]}} special texts

@table @asis
@item @code{%M@r{[}@var{date}@r{]}}
@cindex @code{%M@r{[}@var{date}@r{]}} special text, complete month name
Complete month name

@item @code{%T@r{[}@var{date}@r{]}}
@cindex @code{%T@r{[}@var{date}@r{]}} special text, 3-letter month name
3-letter month name
@end table

@item @code{%@var{?}@r{[}@var{date}@r{]}} month
@cindex Month @code{%@var{?}@r{[}@var{date}@r{]}} special texts

@table @asis
@item @code{%U@r{[}@var{date}@r{]}}
@cindex @code{%U@r{[}@var{date}@r{]}} special text, month
Month

@item @code{%W@r{[}@var{date}@r{]}}
@cindex @code{%W@r{[}@var{date}@r{]}} special text, month
Month, 2-digits with leading zero

@item @code{%z@r{[}@var{date}@r{]}}
@cindex @code{%z@r{[}@var{date}@r{]}} special text, month
Month, Ordinal Number suffix

@item @code{%Z@r{[}@var{date}@r{]}}
@cindex @code{%Z@r{[}@var{date}@r{]}} special text, month
Month, 2-digits with leading zero, Ordinal Number suffix
@end table

@item @code{%@var{?}@r{[}@var{date}@r{]}} year
@cindex Year @code{%@var{?}@r{[}@var{date}@r{]}} special texts

@table @asis
@item @code{%Y@r{[}@var{date}@r{]}}
@cindex @code{%Y@r{[}@var{date}@r{]}} special text, year
Year

@item @code{%=@r{[}@var{date}@r{]}}
@cindex @code{%=@r{[}@var{date}@r{]}} special text, year
Year, 4-digits with leading zeroes
@end table

@item @code{%@var{?}@r{[}@var{date}@r{]}} moonphase
@cindex Moonphase @code{%@var{?}@r{[}@var{date}@r{]}} special texts

@table @asis
@item @code{%-@r{[}@var{date}@r{]}}
@cindex @code{%-@r{[}@var{date}@r{]}} special text, moonphase
Moonphase text

@item @code{%_@r{[}@var{date}@r{]}}
@cindex @code{%_@r{[}@var{date}@r{]}} special text, moonphase
Moonphase text, 3-digits with leading zeroes

@item @code{%:@r{[}@var{date}@r{]}}
@cindex @code{%:@r{[}@var{date}@r{]}} special text, moonphase text graphics
Moonphase text graphics
@end table

@item @code{%@var{?}@r{[}@var{date}@r{]}} biorhythm
@cindex Biorhythm @code{%@var{?}@r{[}@var{date}@r{]}} special texts

@table @asis
@item @code{%,@r{[}@var{date}@r{]}}
@cindex @code{%,@r{[}@var{date}@r{]}} special text, biorhythm
Biorhythm text (series of values)

@item @code{%;@r{[}@var{date}@r{]}}
@cindex @code{%;@r{[}@var{date}@r{]}} special text, biorhythm text graphics
Biorhythm text graphics (bar)
@end table

@item @code{%@var{?}@r{[}@var{date}@r{]}} difference value
@cindex Difference value @code{%@var{?}@r{[}@var{date}@r{]}} special texts

@table @asis
@item @code{%y@var{date}}
@cindex @code{%y@var{date}} special text, relative year number
Relative year number

@item @code{%b@r{[}@var{date}@r{]}}
@cindex @code{%b@r{[}@var{date}@r{]}} special text, birthday
Birthday (age value)

@item @code{%B@r{[}@var{date}@r{]}}
@cindex @code{%B@r{[}@var{date}@r{]}} special text, birthday
Birthday (age value), Ordinal Number suffix
@end table

@item @code{%t@r{[}12@r{|}24@r{]}}
@cindex Actual time @code{%t@r{[}@var{argument}@r{]}} special text
Actual time

@item @code{%n@r{[[}+@r{|}-@r{]}@var{n}@r{]}}
@cindex Textual date @code{%n@r{[}@var{argument}@r{]}} special text
Textual date in fixed @samp{@var{dd}-@var{mmm}-@var{yyyy}} format

@item @code{%j@r{[[}-@r{]}@var{n}@r{]}}
@cindex Julian day number @code{%j@r{[}@var{argument}@r{]}} special text
Julian day number

@item @code{%@var{?}} difference value
@cindex Difference value @code{%@var{?}} special texts

@table @asis
@item @code{%d}
@cindex @code{%d} special text, relative day number
Relative day number

@item @code{%w}
@cindex @code{%w} special text, relative week number
Relative week number

@item @code{%m}
@cindex @code{%m} special text, relative month number
Relative month number

@item @code{%y}
@cindex @code{%y} special text, relative year number
Relative year number
@end table

@item @code{%@var{?}} highlighting
@cindex Highlighting @code{%@var{?}} special texts

@table @asis
@item @code{%1}
@cindex @code{%1} special text, start of highlighting sequence 1
Start of highlighting sequence 1

@item @code{%2}
@cindex @code{%2} special text, end of highlighting sequence 1
End of highlighting sequence 1

@item @code{%3}
@cindex @code{%3} special text, start of highlighting sequence 2
Start of highlighting sequence 2

@item @code{%4}
@cindex @code{%4} special text, end of highlighting sequence 2
End of highlighting sequence 2

@item @code{%5}
@cindex @code{%5} special text, start of highlighting sequence 1
Start of highlighting sequence 1 if a fixed date is on today's date

@item @code{%6}
@cindex @code{%6} special text, end of highlighting sequence 1
End of highlighting sequence 1 if a fixed date is on today's date

@item @code{%7}
@cindex @code{%7} special text, start of highlighting sequence 2
Start of highlighting sequence 2 if a fixed date is on a legal holiday date

@item @code{%8}
@cindex @code{%8} special text, end of highlighting sequence 2
End of highlighting sequence 2 if a fixed date is on a legal holiday date

@item @code{%9}
@cindex @code{%9} special text, start of highlighting sequence 1 or 2
Start of highlighting sequence 1 if a fixed date is on today's date, otherwise
start of highlighting sequence 2 if a fixed date is on a legal holiday date

@item @code{%0}
@cindex @code{%0} special text, end of highlighting sequence 1 or 2
End of highlighting sequence 1 if a fixed date is on today's date, otherwise
end of highlighting sequence 2 if a fixed date is on a legal holiday date
@end table

@item @code{%!@r{[}@var{argument}@r{]}}
@cindex Shell command @code{%!@r{[}@var{argument}@r{]}} special text
Shell executes @var{argument} as a command
@end table

@node Coding Scheme, Environment Variables, Special Texts Summary, 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 enabling the fixed date feature --- respectively
the @w{@samp{--period-of-fixed-dates=@var{argument}}} long-style option
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} argument is given, it respects only those
entries which have a definite relation to the @emph{fixed date} argument
to avoid the output of redundant information!
@sp 2

@noindent
In the @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 length 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 length 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

@noindent
@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@@@var{?}@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}!
@sp 2

@multitable @columnfractions .35 .65
@item @strong{Date part}
@tab @strong{Short-style option @samp{-c@r{|}C@r{[]}}}
@item @code{00000000}
@tab @w{@code{-c@var{n}+@r{|}-}}
@item @code{000000@var{dd}}
@tab @w{@code{-c@var{n}w@r{|}+@r{|}-},}
@w{@code{-cw@r{[}+@r{|}-@r{]}},}
@w{@code{-cm@r{[}+@r{|}-@r{]}}}
@item @code{0000@var{mm}00}
@tab @w{@code{-c@var{n}+@r{|}-}}
@item @code{0000@var{mm}@var{dd}}
@tab @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@@@var{?}@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 @code{@var{yyyy}0000}
@tab @w{@code{-c@var{n}+@r{|}-}}
@item @code{@var{yyyy}00@var{dd}}
@tab @w{@code{-c@var{n}w@r{|}+@r{|}-},}
@w{@code{-cw@r{[}+@r{|}-@r{]}},}
@w{@code{-cm@r{[}+@r{|}-@r{]}}}
@item @code{@var{yyyy}@var{mm}00}
@tab @w{@code{-c@var{n}+@r{|}-}}
@item @code{@var{yyyy}@var{mm}@var{dd}}
@tab @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@@@var{?}@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 @code{000000@var{www}@var{n}}
@tab @w{@code{-c@var{n}w@r{|}+@r{|}-},}
@w{@code{-cw@r{[}+@r{|}-@r{]}},}
@w{@code{-cm@r{[}+@r{|}-@r{]}}}
@item @code{0000@var{mm}@var{www}@var{n}}
@tab @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@@@var{?}@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 @code{@var{yyyy}00@var{www}@var{n}}
@tab @w{@code{-c@var{n}w@r{|}+@r{|}-},}
@w{@code{-cw@r{[}+@r{|}-@r{]}},}
@w{@code{-cm@r{[}+@r{|}-@r{]}}}
@item @code{@var{yyyy}@var{mm}@var{www}@var{n}}
@tab @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@@@var{?}@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 @code{0000*d@var{n}@r{[}@var{www}@r{]}}
@tab @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@@@var{?}@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 @code{@var{yyyy}*d@var{n}@r{[}@var{www}@r{]}}
@tab @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@@@var{?}@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 @code{0000*w@var{n}@r{[}@var{www}@r{]}}
@tab @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@@@var{?}@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 @code{@var{yyyy}*w@var{n}@r{[}@var{www}@r{]}}
@tab @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@@@var{?}@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 @code{0000@@@var{?}@r{[}+@r{|}-@r{]}@var{n}@r{[}@var{www}@r{]}}
@tab @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@@@var{?}@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 @code{@var{yyyy}@@@var{?}@r{[}+@r{|}-@r{]}@var{n}@r{[}@var{www}@r{]}}
@tab @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@@@var{?}@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 multitable

@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 fitting modifiers of the short-style option
@w{@samp{-c@r{|}C@r{[]}}} with all possible encode variations of a
date given in the @emph{date part} of resource file.
@sp 2

@multitable @columnfractions .35 .65
@item @strong{Short-style option @samp{-c@r{|}C@r{[]}}}
@tab @strong{Date part}
@item @code{-c}
@item @code{-ct}
@item @code{-c@var{n}d@r{|}+@r{|}-}
@item @code{-c@var{mm}@var{dd}}
@item @code{-c@var{mm}@var{www}@var{n}}
@item @code{-c*d@r{|}w@var{n}@r{[}@var{www}@r{]}}
@item @code{-c@@@var{?}@r{[[}+@r{|}-@r{]}@var{n}@r{[}@var{www}@r{]]}}
@tab @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}@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 @code{-c@var{n}w}
@item @code{-cw@r{[}+@r{|}-@r{]}}
@tab @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 @code{-cm@r{[}+@r{|}-@r{]}}
@tab @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 @code{-cy@r{[}+@r{|}-@r{]}}
@item @code{-cl@var{n}d@r{|}w@r{|}+@r{|}-}
@item @code{-cl@var{mm}@var{dd}}
@item @code{-cl@var{mm}@var{www}@var{n}}
@item @code{-cl*d@r{|}w@var{n}@r{[}@var{www}@r{]}}
@item @code{-cl@@@var{?}@r{[[}+@r{|}-@r{]}@var{n}@r{[}@var{www}@r{]]}}
@tab @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 multitable

@node Environment Variables, Error Codes, Coding Scheme, Top
@appendix Environment Variables
@cindex Environment Variables, table of all
@cindex Table of all environment variables
@cindex Respected environment variables, table of all
@cindex Environment variables, table of all respected

Here is a table 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 that 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 the 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.  This is 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 MAILPROG
@cindex Environment variable, @code{MAILPROG}
@cindex @code{MAILPROG} environment variable
@vindex MAILPROG
Name of the mailer program which is used if the mailing option is wanted.
@xref{Global options, @samp{--mail=@var{address}}, Global options: @samp{--mail=@var{address}}},
for more details.

@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 is wanted.
@xref{Global options, @samp{--pager}, Global options: @samp{--pager}},
for more details.

@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}, 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, table of all
@cindex Table of all error codes
@cindex Exit Codes, table of all
@cindex Table of all exit codes
@cindex Program exit states, table of
@cindex Run-time error codes, table of
@cindex Whitespace character
@cindex EMail, error code

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 have failed.

@item 110
Internal error, C function pipe(), fork(), execlp() or unlink() have failed.

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

@item 106
Invalid date format text specified.

@item 105
Invalid text variable definition.

@item 104
Invalid regular expression search pattern specified.

@item 3
Program aborted by signal.

@item 2
@emph{Exit} code not equal zero returned by external command.

@item 1
Activated @w{@samp{-c@r{|}C@r{[]}}},
@w{@samp{-f@r{|}F @var{name}@r{[}+@dots{}@r{]}}} or @w{@samp{-# @var{line}}}
option caused no output of resource file entries.

@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
Here is an alphabetical list of the command line arguments processed by Gcal:
@printindex ar

@node Variable Index, Concept Index, Argument Index, Top
@unnumbered Environment Variable Index
Here is an alphabetical list of the environment variables checked by Gcal:
@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
