This is gcal.info, produced by makeinfo version 4.0 from gcal.texi.

INFO-DIR-SECTION GNU packages
START-INFO-DIR-ENTRY
* Gcal: (gcal).                       GNU calendar program.
* Tcal: (gcal)Invoking tcal.          Run Gcal with tomorrow's date.
* Txt2gcal: (gcal)Invoking txt2gcal.  Calendar text to resource file.
* Gcal2txt: (gcal)Invoking gcal2txt.  Calendar resource to text file.
END-INFO-DIR-ENTRY

  This file documents Gcal, a program for calculating and printing
calendars.

  Copyright (c) 1994-1997, 2000 Thomas Esken

  This edition is for Gcal version 3.00.

  Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

  Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

  Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Free Software Foundation.

  Any suggestions, improvements, extensions, bug reports, donations,
proposals for contract work, and so forth are welcome!  Please send
them directly to my eMail address <esken@gmx.net>.  If you like my
work, I'd appreciate a postcard from you!

------------------------oOO      \\\_''/      OOo---------------------------
Thomas Esken               O     (/o-o\)     O  eMail: esken@gmx.net
Im Hagenfeld 84                 ((  ^  ))       Phone: +49 251 232585
D-48147 Muenster; Germany    \____) ~ (____/    MotD : 2old2live, 2young2die


File: gcal.info,  Node: Top,  Next: Preface,  Prev: (dir),  Up: (dir)

Gcal
****

  This file documents `gcal', a program for calculating and printing
calendars.

  Gcal displays hybrid and proleptic Julian and Gregorian calendar
sheets, respectively, for one month, three months or a whole year.  It
also displays eternal holiday lists for many countries around the globe,
and features a very powerful creation of fixed date lists that can be
used for reminding purposes.  Gcal can calculate various astronomical
data and times of the Sun and the Moon for at pleasure any location,
precisely enough for most civil purposes.  Gcal supports some other
calendar systems, for example the Chinese calendar, the Hebrew calendar
and the civil Islamic calendar, too.

  This is Edition 3.00 of `Gcal, an Extended Calendar Program',
7 June 2000, for the 3.00 version of the GNU implementation
of `cal' and `calendar'.

  Any suggestions, improvements, extensions, bug reports, donations,
proposals for contract work, and so forth are welcome!  Please send
them directly to my eMail address <esken@gmx.net>.  If you like my
work, I'd appreciate a postcard from you!

------------------------oOO      \\\_''/      OOo---------------------------
Thomas Esken               O     (/o-o\)     O  eMail: esken@gmx.net
Im Hagenfeld 84                 ((  ^  ))       Phone: +49 251 232585
D-48147 Muenster; Germany    \____) ~ (____/    MotD : 2old2live, 2young2die

* Menu:

* Preface::            Preliminary remarks to Gcal.
* Gcal Introduction::  Gcal in brief.
* Invoking Gcal::      How to run and use the `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 manual.
* Regular Expressions::    Description of all Regular Expressions.
* Regexp Summary::         Summary of all Regular Expressions.
* Special Texts::          Description of all `%?'... Special Texts.
* Special Texts Summary::  Summary of all `%?'... Special Texts.
* Obsolete Special Texts:: Tables of obsolete Special Texts et cetera.
* Format Instruction::     Description of the Format Instruction components.
* Coding Scheme::          Coding Scheme of date part in resource file.
* Environment Variables::  Used Environment Variables.
* Error Codes::            Which Error Codes does Gcal return?
* Glossary::               Short descriptions of the terms used here.

Indices

* Argument Index::  Index of Command line arguments respected.
* Variable Index::  Index of Environment Variables used.
* Table Index::     Index of Tables that can be found in this manual.
* Concept Index::   A menu covering many topics.

  --- The Detailed Node Listing ---

Invoking Gcal

* Command line arguments::         Command line arguments.
* The GCAL environment variable::  How to use the `GCAL' environment variable.

Command line arguments

* Options::               How to use Options.
* Response file::         How to use a `@FILE' Response file.
* Actual date modifier::  How to use a `%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.
* Special Texts processed::       What are `%?'... Special Texts?
* Comment line::                  What is a Comment line?
* Include directives::            What are Include directives?
* 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 `tcal' and a summary of its options.
* Invoking txt2gcal::  How to run `txt2gcal' and a summary of its options.
* Invoking gcal2txt::  How to run `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 number::
* Day-of-year number::
* Day number::
* Week number::
* Month name::
* Month number::
* Year number::
* Moon phase::
* Biorhythm::
* Difference value::

Replacements with other argument

* Actual clocktime::
* Textual date::
* Julian day number::
* Geographical distance and course angle::
* Sun data::
* Moon data::
* Contents of Environment variable::

Replacements without any argument

* Other difference values::
* Highlighting::

Obsolete Special Texts

* Table of Obsolete Special Texts::
* Table of Obsolete Date Format Elements::
* Table of Obsolete Date Formats::

Coding Scheme

* Coding Scheme Table 1::
* Coding Scheme Table 2::


File: gcal.info,  Node: Preface,  Next: Gcal Introduction,  Prev: Top,  Up: Top

Preface
*******

  The reason why I have written Gcal was mainly to have an _off-line_
tool(1) (*note Preface-Footnote-1::) which is able to display Julian
and Gregorian calendar sheets in a highly flexible and
internationalized manner, fixed date lists for reminding purposes and
country respectively territory specific holiday lists.  At a later
stage, Gcal was extended in the way to perform some basic astronomical
calculations like Moon phase, moonrise, moonset and other Moon based
data, sunset, sunrise, different twilight times and other Sun based
data, zodiacal markers, solar and lunar eclipses, equinoxes and
solstices.  Other gimmicks like biorhythm calculation and the
computation of a distance between two geographical point locations and
their course angles (true tracks) are also done by it now, plus alot
more.

  The accurancy of most of the astronomical calculations done by Gcal is
low because it is really hard to perform accurate astronomical
predictions more that 100 years ahead.  Of course, this also has
consequences for some country specific holidays which are based on such
astronomical calculations.  So it is really possible that some output
may differ from the real astronomical date and time of the event
calculated, and that by one or more minutes/hours/days.  This can
happen when the date of a real astronomical event occurs near around
midnight.  So don't be surprised!  Strictly speaking, take all such
astronomically based output as a more or less good approximation of the
true value, but do not rely on it!

  Because Gcal is not primarily designed for the purpose of having a
high precision astronomical calculation tool, the world currently has
to live with these limitations.  But if *you* have C source code
functions, which

   * perform the astronomical calculations more precise for the period
     that is respected by Gcal,

   * have the similar or faster processing speed than Gcal's actual
     functions,

   * are either put into the public domain or are covered by the GPL(2)
     (*note Preface-Footnote-2::),

   * have the same calling conventions and return types like Gcal's
     actual functions,

   * conform to the GNU coding standard and are therefore easy to
     maintain and extend,

   * do not break Gcal internal limitations and concepts,

and you want to grant them to the public, I would be very pleased if you
would contact me so I am able to implement your result to a next release
of this software.

  Some words to the build-in country specific holidays now...

  As you certainly know, there are several other calendar systems
actually exsting around the world among the Gregorian calendar.  The
Gregorian calendar that Gcal mainly represents as a software is only
one calendar of many others, but it is that one which is most respected
around the world today.  Even countries which use another calendar
system officially mostly respect the Gregorian calendar for civil and
administrative purposes.

  But when Gcal offers the ability to include holidays from a definite
country into its eternal holiday list, it is possible that not all
holidays are displayed which are respected in that country.  One reason
is that my various sources simply don't tell me about the existance of
a holiday.  A second reason is that the holiday is just designed or
changed or removed by political or society reality during Gcal's
developement phase.  And another reason is that the method to calculate
a holiday is not build-in Gcal yet.  This case is marked by a `#'
character behind the country name in the list of countries, which are
respected by Gcal.  *Note Calendar option
`--cc-holidays=CC[_TT][+...]': x-cc-holidays, for the above mentioned
list.
The holidays of "early" years that are included into the eternal holiday
list --i.e. those within the period AD 30 until the midth of the 20th
century-- are certainly not accomplishing the requirements of
historicans to such a list.  Gcal cannot be understood as a complete and
historically correct data base, and it is not designed for that purpose!
This is caused by the fact that the territorial borders and names of the
national structures and the settlement in earlier times was partly quite
different as it is nowadays.  Moreover, I am yet lacking reliable
information that tells me the precise date of the introduction of a
holiday in a region.  Here I appeal to the historicans to support me
with the concrete country and culture based data if they are bothered
by this fact and they want to have it removed.

  Still unsupported *alive* and *major* calendar systems, respectively
methods to derive country specific holidays from them, are:

   * Religious Islamic lunar calendar

   * Hindu solar and lunar calendars

   * Buddhist calendar

   * Sikh calendar

   * Jain calendar

  Even if the list of supported countries seems to be almost complete
if you compare it with the actual list of all nations existing around
the world, you should note that there are still some countries missing!
If you can grant me support to complete Gcal's list of respected
countries, or if you would work out or have C functions which manage
the missing calendar systems, I also would be very pleased about if you
would contact me.

  I have recorded the country specific holiday dates as good as I can,
but I cannot guarantee that I did not made any mistakes while I hacked
them in.  So it is possible that some country specific holiday lists
contain errors.

  Well, if you think that I forgot to provide Gcal with the specific
holidays of a/your country, or you think that a country specific
holiday list is incomplete, or you think that some of the already
implemented holidays are wrong, please feel free to send me a complete
list of all the holidays which are celebrated in this country
respectively to give me hints how to correct or to complete them!

  Such a list should ideally include the following information:

   * The English name of the holiday.

   * The rule how it is built (like 10th October each year, or 47 days
     after Easter Sunday's date, or three Fridays before the last
     Saturday in June...).  If there are any exceptions from such a
     general rule, please state them in a detailed manner.  And please
     tell me the date since what time the holiday is or was celebrated
     for the first time, respectively.

     By the way, if the holiday is tied to the Easter Sunday's date,
     please tell me whether you mean the Easter Sunday of the Christian
     Western churches or the Easter Sunday of the Orthodox Christian
     Eastern churches.

   * Whether it is a "legal holiday" which is respected in the whole
     country.  (Use a `+' character for marking this case.)  In this
     sense, a legal holiday means a day people don't have to work -- as
     in most companies, and businesses are closed; like `New Year's Day'
     on January 1st.

   * Whether it is a legal holiday in some parts of your country only.
     Please tell me whether such a holiday is valid in major parts of
     the country or not, try to express that by using percent points.
     (If such a holiday is celebrated in more than 70% of the country,
     use a `#' character for marking this case, otherwise use a `*'
     character.)

   * Whether it is a day only used for memorial or remembering purposes.
     (Use a `-' character for marking this case.)  Like
     `All Fool's Day' on April 1st is not a holiday in the sense that
     anyone has a day off from school or work, just a _play jokes_ day,
     pretty ordinary.  Other holidays may be celebrated with cards or
     presents etc. -- but they are working days such as:

          Valentine's day, Father's day, Mother's day.

  The Islamic holidays inserted into the country specific holiday list
are calculated arithmetically, not astronomically.  This is what people
call the "civil" Islamic lunar calendar.  This type of calendar is just
a rough estimate of the religious Islamic lunar calendar, which is
determined quite astronomically.  So don't be surprised too much if
some holiday dates differ from the religious Islamic calendar about
+/- 1...2 days in some years.
The main difficulty to implement the religious Islamic calendar
correctly into Gcal are the several different criterias that are
existing for the first sighting of the crescrent Moon after a New Moon
phase -- that event, which defines the beginning of a new (lunar) month
in the religious oriented Islamic calendar.  So on the one hand, there
are quite astronomically-based criterias, and on the other hand, there
are also quite religiously-based criterias.  Furthermore, the local
predominant weather conditions, the geographical co-ordinate of the
observer's location and the kind of the observance method used also
affect these criterias.  Moreover, to render all more difficult, I as
yet do not have any reliable information that tells me which kind of
criteria is used in the countries (around 60 world-wide) which respect
this religous Islamic calendar.  So due to all the above mentioned
facts of problematic nature, this religious Islamic calendar is not
included into Gcal yet.

  The Chinese (and Japanese) holidays also inserted into the country
specific holiday list are calculated by using that algorithm as it is
used by the Purple Mountain Observatory in Nanjing for determing the
astronomical lunisolar Chinese calendar.  This calendar is obligatory
for (the Peoples Republic of) China since 1929 and is determined
annualy always new.  Nevertheless and strictly speaking, in the
historic reality and depending on the region, the Chinese calendar,
especially in the 17th and 18th century, was either calculated using
this _modern_ algorithm, or by the use of a different method, so that a
different calendar structure for one and the same year was possibly
calculated as result.

  And last...

  This manual shows the possible use of the Gcal program only briefly
and deliberately renounces to present the topics that are covered by
this software arranged in a novel-like style.  The use of Gcal is
illustrated in an examplary manner only!  A detailed description of all
possible use is inexpedient here because there are simply too many of
such possiblities which are caused by the existing variety of
combinations of all useable modes of operation.

  Furthermore, this manual does not contain detailed explainations about
the calendar systems supported by Gcal, nor it can be understood as a
reference-book for the basics in celestial mechanics or spherical
trigonometry!  A detailed discussion of the above topics is completely
beyond the scope of this manual.  If you are interested to learn more
about these subjects, you unfortunately have to read the specific
pertinent literature.

  Any further errors occuring in the output of the above mentioned
holiday lists and in the astronomical calculations are my own fault,
and are not intended to offend members of any culture, religion or
profession!


File: gcal.info,  Node: Preface-Footnotes,  Up: Preface

  (1) I.e. no need to search for calendar information in the net so
phone and Internet Service Provider (ISP) costs are reduced, and
furthermore, neither searching for such information in books or data
files nor the need to use several other software which alltogether do
what Gcal actually also does.

  (2) The "General Public License" of the Free Software Foundation.


File: gcal.info,  Node: Gcal Introduction,  Next: Invoking Gcal,  Prev: Preface,  Up: Top

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, the Gregorian calendar program of the Free Software
Foundation, offers the facility to display fixed dates on the day of
their occurrence and to remind or inform the user about them.  So it is
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 on this date and ending on the actual date(1) (*note Gcal
Introduction-Footnote-1::).

  There are two methods to display a preview of fixed dates(2) (*note
Gcal Introduction-Footnote-2::) or retrospective view of fixed dates(3)
(*note Gcal Introduction-Footnote-3::).  On the one hand, Gcal can be
started by 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. `Fixed date on 1st December 1995', rather than
fixed dates occurring periodically again and again.  So it is possible
to define repeated events like `This fixed date occurs every day in May
1995' or `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 to use Gcal in the
most efficient and productive way possible.  After it follows the
description how to use the eternal holiday list, and in the succeeding
chapter, how to use the fixed date list.  Comprehensive explainations
respectively summaries and tables to definite details or themes from
other disciplines can be found in the numerous appendices.


File: gcal.info,  Node: Gcal Introduction-Footnotes,  Up: Gcal Introduction

  (1) Inclusive or exclusive.

  (2) Future years.

  (3) Past years.


File: gcal.info,  Node: Invoking Gcal,  Next: Eternal Holidays,  Prev: Gcal Introduction,  Up: Top

Invoking `gcal'
***************

* Menu:

* Command line arguments::         Command line arguments.
* The GCAL environment variable::  How to use the `GCAL' environment variable.

  Gcal is a command line oriented program.  It is usually called from
the "shell"(1) (*note Invoking Gcal-Footnote-1::) and processes given
arguments that are options and commands.  Options must be given before
commands, i.e. you must call Gcal like this:

             gcal [ [OPTION...] [%DATE] [@FILE...] ]  [COMMAND]


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

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

  In the English program version, Gcal assumes the Gregorian
Reformation has occurred in 1752 on the 3rd of September.  *Note
Genesis of the Gregorian Calendar: Todays Calendar, and *Note Aspects
in Internationalization: Internationalization, for further details.


File: gcal.info,  Node: Invoking Gcal-Footnotes,  Up: Invoking Gcal

  (1) This is an operating system program which interprets and runs
given command lines.


File: gcal.info,  Node: Command line arguments,  Next: The GCAL environment variable,  Prev: Invoking Gcal,  Up: Invoking Gcal

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

* Menu:

* Options::               How to use Options.
* Response file::         How to use a `@FILE' Response file.
* Actual date modifier::  How to use a `%DATE' Actual date modifier.
* Commands::              How to use Commands.

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

  An option is defined by a leading "switch" character; either the `-'
(dash) or the `/' (slash) character for traditional short-style options,
or `--' for mnemonic long-style options; a command may not have a
leading switch character.  Options(1) (*note Command line
arguments-Footnote-1::) *must* be given before commands!

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

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

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


File: gcal.info,  Node: Command line arguments-Footnotes,  Up: Command line arguments

  (1) Inclusive `%DATE' and `@FILE'.


File: gcal.info,  Node: Options,  Next: Response file,  Prev: Command line arguments,  Up: Command line arguments

Options
-------

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

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

  Gcal supports both short-style options and GNU long-style options.
Traditional short-style options are indicated by a single switch
character, and trailed by the option character itself and perhaps a
modifier or an argument.  The most single character options(1) (*note
Options-Footnote-1::) can be composed into a single command line word:
`-Ax' is equivalent to `-A -x'.  GNU long-style options are indicated
with `--', and trailed by the mnemonic option name itself and perhaps
an argument.  Long-style options and their arguments may be abbreviated
if done unambiguously.  When a long-style option takes an argument,
connect the option name and the argument with `='.

  Brackets ([ and ]) indicate in the following tables, that an option
takes an optional argument.  The `|' character is used to separate
several arguments from each other.

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

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

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

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

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

  5. `--foo=BAR|...|BAR|BAZ'
     Option `--foo' requires exactly one BAR argument which must be
     selected from the given BAR argument list, or the alternative BAZ
     argument.

  Traditional short-style options differ as follows:

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

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

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


File: gcal.info,  Node: Options-Footnotes,  Up: Options

  (1) Unless they take an argument.


File: gcal.info,  Node: Common options,  Next: Global options,  Prev: Options,  Up: Options

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

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

`-??'
`-hh'
`--usage[=ARGUMENT]'
`--long-help[=ARGUMENT]'
     Print an extended usage message listing all available options,
     then exit successfully.  If an 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.:

          --long-help=long-help

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

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

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

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

`--exit-status-help-non-zero'
     Set the exit state of program to 127 instead to 0, if one of the
     other options of the _common option class_ is used.


File: gcal.info,  Node: Global options,  Next: Calendar options,  Prev: Common options,  Up: Options

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

`-R NAME'
`--response-file=NAME'
     Write the contents of the environment variable `GCAL' (*note
     Environment Variable `GCAL': x-GCAL.), and then the arguments of
     command line (in the given order) to file NAME, i.e. create
     response file `name'.  *Note Response file::, for more details.

`-S NAME'
`--shell-script=NAME'
     Write the contents of the environment variable `GCAL' (*note
     Environment Variable `GCAL': x-GCAL.), and then the arguments of
     command line (in the given order) to file NAME, i.e. create shell
     script 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.

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

    `--debug=internal'
          Display informational texts if program internal maxima are
          reached or other conditions occurred, respectively.

    `--debug=handled'
          Like `--debug=internal', additionally display the file names
          which can be processed respectively handled.

    `--debug=unhandled'
          Like `--debug=internal', additionally display file names
          which cannot be processed respectively handled.

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

    `--debug=abort'
          Like `--debug=all' and abort program with an error code if
          the file name cannot be handled or other unmanageable
          conditions occurred, respectively.  *Note Error Codes::.

`-p'
`--pager'
     Enables either an _external_ pager or a simple, _internal_ pager.
     If an environment variable `PAGER' is set, its contents will be
     used for detecting the external pager program.  *Note Environment
     Variable `PAGER': x-PAGER, for more information.

     If no `PAGER' environment variable is set or if its contents is
     invalid, Gcal tries to use the `less' pager; if this program
     cannot be found during scanning the `PATH' environment variable,
     Gcal tries to use the `more' pager, if this program cannot be
     found, the `pg' pager in the same way(1) (*note Global
     options-Footnote-1::).  *Note Environment Variable `PATH': x-PATH.

     If all these actions fail, Gcal will use its simple, built-in
     pager.  If the internal pager is used, Gcal detects the number of
     lines shown before it prompts and waits for user input by using
     these methods:

       1. Gcal respects the values set in the environment variables
          `GCAL_LINES' and `GCAL_COLUMNS'.  *Note Environment Variable
          `GCAL_LINES': x-GCAL_LINES, and *Note Environment Variable
          `GCAL_COLUMNS': x-GCAL_COLUMNS, for further information.

       2. If above action fails, Gcal respects the values set in the
          environment variables `LINES' and `COLUMNS'.  *Note
          Environment Variable `LINES': x-LINES, and *Note Environment
          Variable `COLUMNS': x-COLUMNS, for more details.

       3. If above action fails, Gcal respects the values set in the
          `termcap'(2) (*note Global options-Footnote-2::) file which
          refers to the terminal used (*note Environment Variable
          `TERM': x-TERM.).  This step is only done on systems which
          support the use of Termcap by default.

          On MS-DOS, OS/2 and some other operating systems, Gcal uses a
          system dependent _low-level_ function and respects the
          reported values.

       4. If all above actions have failed, Gcal uses default values(3)
          (*note Global options-Footnote-3::).

`-H yes'
`--force-highlighting'
`--highlighting=yes'
     If the output of the program is redirected(4) (*note Global
     options-Footnote-4::) or piped(5) (*note Global
     options-Footnote-5::), the highlighting sequences are *not*
     automatically converted into the according marking characters,
     they remain unchanged.  This option takes no effect if the output
     of the program is sent by means of electronic mail.  *Note Global
     option `--mail[=ADDRESS]': x-mail.

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

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

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

     For example:

          `-H \x20:\x20:\x1:#' respectively
          `--highlighting=\x20:\x20:\x1:#'
          marks the actual day like `\x20ACTUAL DATE\x20'(6) (*note
          Global options-Footnote-6::) and the holiday date like
          `\x1HOLIDAY DATE#' using the given marking characters.

          `-H \x1b[34;42m:\x1b[0;40m' or
          `-H \033[34;42m:\033[0;40m' or
          `-H \E[34;42m:\E[0;40m'
          defines a starting ANSI escape highlighting sequence
          `\x1b[34;42m' used for actual day and ending ANSI escape
          highlighting sequence `\x1b[0;40m' with no given highlighting
          sequence for holidays, 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.  *Note Environment
          Variable `GCALANSI': x-GCALANSI, too.

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

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

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

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

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

     Incomplete or non-given highlighting sequences will be replaced by
     internal default ANSI escape highlighting sequences if a `GCALANSI'
     environment variable is defined; otherwise completely replaced by
     their according marking characters.  *Note Environment Variable
     `GCALANSI': x-GCALANSI.

`--mail[=ADDRESS]'
     Send Gcal's output via `mail'(7) (*note Global
     options-Footnote-7::) program to the given ADDRESS, e.g.:

          --mail=esken@gmx.net

     If no ADDRESS is given, Gcal tries to send the eMail by using the
     following methods:

       1. If an environment variable `MAILTO' is defined and set, the
          eMail is send to the address which is listed in this
          environment variable.  *Note Environment Variable `MAILTO':
          x-MAILTO, for more information.

       2. If above action fails, and if an environment variable `USER'
          is defined and set, the eMail is send to the address which is
          listed in this environment variable.  *Note Environment
          Variable `USER': x-USER, for more information.

       3. If above action fails, and if an environment variable
          `LOGNAME' is defined and set, the eMail is send to the
          address which is listed in this environment variable.  *Note
          Environment Variable `LOGNAME': x-LOGNAME, for more
          information.

       4. If all above actions have failed, no eMail is send.

     Generally, Gcal does not send electronic Mails whose message body
     is empty!  An informational message will be shown on the _standard
     error channel_ if this case occurs.

     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
     `--force-highlighting' option was given or not.  This behavior of
     Gcal is an imperative necessity, because it is possible that the
     `mail' program cannot perform the mailing correctly.  Please pay
     attention in this context to the further explainations concerning
     the limitations of the _text part_ of a resource file line (*note
     Text part of a line::).

     If an environment variable `MAILPROG' is defined and set, its
     contents will be used as the program name of the mailer instead of
     the standard name `mail'.  *Note Environment Variable `MAILPROG':
     x-MAILPROG, for more information.


File: gcal.info,  Node: Global options-Footnotes,  Up: Global options

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

  (2) See the standard manual pages for Termcap.

  (3) Either 23 or 24 lines, and 80 columns.

  (4) This means, sent to another device.

  (5) This means, used as an input data stream for another program.

  (6) This means with a leading and a trailing blank.

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


File: gcal.info,  Node: Calendar options,  Next: Fixed date options,  Prev: Global options,  Up: Options

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

`-n|N[-]'
`--holiday-list[=long|short]'
`--descending-holiday-list[=long|short]'
     Display the eternal holiday list.  By default, there are no
     entries in the eternal holiday list.  You have to choose country
     specific holidays or holidays from other calendar systems to
     provide the eternal holiday list with entries.  *Note Eternal
     Holidays::, and *Note Calendar option `--cc-holidays=CC[+...]':
     x-cc-holidays, for additional information.

    `-n'
    `--holiday-list=long'
          Display all holidays of eternal holiday list --this means,
          all legal holidays and all further memorial days-- sorted in
          ascending order.

    `-n-'
    `--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.

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

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

`-G'
`--suppress-holiday-list-separator'
     Suppress displaying of the blank line which is always leading an
     eternal holiday list.

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

`--astronomical-holidays'
     Provide the eternal holiday list additionally with some
     astronomical data, and that the Full and New Moon phases, waning
     and waxing Half Moon phases, solar and lunar eclipses, and the
     solstices and equinoxes.  *Note Calendar option
     `--time-offset=ARGUMENT': x-time-offset, how to change the
     timezone respectively base time for which the astronomical data is
     calculated.

`--bahai-holidays'
     Provide the eternal holiday list additionally with Bahá'ì holidays
     (only for dates after AD 1843).

`--celtic-holidays'
     Provide the eternal holiday list additionally with Celtic holidays.
     *Note Calendar option `--time-offset=ARGUMENT': x-time-offset, how
     to change the timezone for which the Celtic holidays are
     calculated.

`--chinese-flexible-holidays'
     Provide the eternal holiday list additionally with Chinese
     holidays, that are determined in a flexible manner (only for dates
     after AD 1644).  *Note Calendar option `--time-offset=ARGUMENT':
     x-time-offset, how to change the timezone for which the Chinese
     holidays are calculated in a flexible manner.  *Note Preface::,
     for further details.

`--chinese-holidays'
     Provide the eternal holiday list additionally with Chinese holidays
     (only for dates after AD 1644).  For dates until AD 1928 all
     computations done are depending fixed on Bejing local time, for
     later dates fixed on the timezone GMT-8.  *Note Preface::, for
     further details.

`--christian-holidays'
     Provide the eternal holiday list additionally with Christian
     holidays.

`--hebrew-holidays'
     Provide the eternal holiday list additionally with Hebrew holidays.

`--islamic-civil-holidays'
     Provide the eternal holiday list additionally with Islamic holidays
     (only for dates after AD 621), that are based on the civil Islamic
     calendar.  *Note Preface::, for further details.

`--japanese-flexible-holidays'
     Provide the eternal holiday list additionally with Japanese
     holidays, that are determined in a flexible manner (only for dates
     after AD 1644).  *Note Calendar option `--time-offset=ARGUMENT':
     x-time-offset, how to change the timezone for which the Japanese
     holidays are calculated in a flexible manner.

`--japanese-holidays'
     Provide the eternal holiday list additionally with Japanese
     holidays (only for dates after AD 1644).  For dates until AD 1887
     all computations done are depending fixed on Bejing local time,
     for later dates fixed on the timezone GMT-9.

`--multicultural-new-year-holidays'
     Provide the eternal holiday list additionally with multicultural
     New Year holidays.  *Note Calendar option
     `--time-offset=ARGUMENT': x-time-offset, how to change the
     timezone for which the multicultural New Year holidays are
     calculated.

`--orthodox-new-holidays'
     Provide the eternal holiday list additionally with Orthodox new
     calendar holidays, and it is assumed that the Gregorian
     Reformation has occurred from 10th till 22nd March 1924.  *Note
     Calendar option `--orthodox-calendar': x-orthodox-calendar, for
     further details.

`--orthodox-old-holidays'
     Provide the eternal holiday list additionally with Orthodox new
     calendar holidays, and it is assumed that the Gregorian
     Reformation has occurred from 10th till 22nd March 1924.  *Note
     Calendar option `--orthodox-calendar': x-orthodox-calendar, for
     further details.

`--persian-jalaali-holidays'
     Provide the eternal holiday list additionally with Persian holidays
     (only for dates after AD 621), which are based on the Persian
     _Jalaali_ calendar.  All computations done are depending on the
     timezone GMT-3.5.

`--zodiacal-marker-holidays'
     Provide the eternal holiday list additionally with zodiacal marker
     holidays, i.e. the dates when the Sun enters a zodiac sign or when
     the Sun reaches the turning-point in the zodiac sign.  *Note
     Calendar option `--time-offset=ARGUMENT': x-time-offset, how to
     change the timezone for which the zodiacal marker holidays are
     calculated.

`-q CC[_TT][+...]'
`--cc-holidays=CC[_TT][+...]'
     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.

     The CC argument is a two-letter country code as defined by the
     ISO-3166(1) (*note Calendar options-Footnote-1::) like `BE' for
     Belgium or `ES' for Spain.  See the pertinent literature for more
     details.

     In some cases, such a country code may be trailed by a two-letter
     territory code TT for better specification, which is separated by
     a `_' character from the country code.

     You can use more than one country code CC[_TT] by connecting them
     with a `+' character, e.g.:

          `--cc-holidays=be+Fr+IT' resp.,
          `-q be+Fr+IT'

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

     Actually, Gcal respects the following country codes, at which
     countries marked by a `#' character have only an incomplete
     recording of holidays:

    `AD'
          Andorra

    `AE'
          United Arab Emirates

    `AF'
          Afghanistan

    `AG'
          Antigua and Barbuda

    `AI'
          Anguilla

    `AL'
          Albania

    `AM'
          Armenia

    `AN_BO'
          Netherlands Antilles/Bonaire

    `AN_CU'
          Netherlands Antilles/Curaçao

    `AN_MA'
          Netherlands Antilles/St Maarten

    `AN_SA'
          Netherlands Antilles/Saba and Statia

    `AO'
          Angola #

    `AR'
          Argentina

    `AS'
          American Samoa

    `AT'
          Austria

    `AU_CT'
          Australia/Canberra

    `AU_NT'
          Australia/Northern Territory

    `AU_QU'
          Australia/Queensland

    `AU_SA'
          Australia/Southern Australia

    `AU_SW'
          Australia/New South Wales

    `AU_TA'
          Australia/Tasmania

    `AU_VI'
          Australia/Victoria

    `AU_WA'
          Australia/Western Australia

    `AW'
          Aruba

    `AZ'
          Azerbaijan

    `BA'
          Bosnia-Herzegovina

    `BB'
          Barbados

    `BD'
          Bangladesh #

    `BE'
          Belgium

    `BF'
          Burkina Faso

    `BG'
          Bulgaria

    `BH'
          Bahrain

    `BI'
          Burundi #

    `BJ'
          Benin #

    `BM'
          Bermuda

    `BN'
          Brunei Darussalam

    `BO'
          Bolivia

    `BR'
          Brazil

    `BS'
          Bahamas

    `BT'
          Bhutan #

    `BV'
          Bouvet Island

    `BW'
          Botswana

    `BY'
          Belarus

    `BZ'
          Belize

    `CA_AL'
          Canada/Alberta

    `CA_BC'
          Canada/British Columbia

    `CA_MA'
          Canada/Manitoba

    `CA_NB'
          Canada/New Brunswick

    `CA_NF'
          Canada/Newfoundland and Labrador

    `CA_NS'
          Canada/Nova Scotia

    `CA_NW'
          Canada/Nordwest Territories

    `CA_ON'
          Canada/Ontario

    `CA_PE'
          Canada/Prince Edward Island

    `CA_QU'
          Canada/Québec

    `CA_SA'
          Canada/Saskatchewan

    `CA_YU'
          Canada/Yukon

    `CC'
          Cocos Islands (Keeling)

    `CD'
          Democratic Republic of Congo #

    `CF'
          Central African Republic #

    `CG'
          Republic of Congo #

    `CH_AA'
          Switzerland/Appenzell Ausserrhoden

    `CH_AG'
          Switzerland/Aargau

    `CH_AI'
          Switzerland/Appenzell Innerrhoden

    `CH_BL'
          Switzerland/Basel-Land

    `CH_BN'
          Switzerland/Bern

    `CH_BS'
          Switzerland/Basel-Stadt

    `CH_FB'
          Switzerland/Fribourg

    `CH_GB'
          Switzerland/Graubünden

    `CH_GL'
          Switzerland/Glarus

    `CH_GV'
          Switzerland/Genève

    `CH_JR'
          Switzerland/Jura

    `CH_LZ'
          Switzerland/Luzern

    `CH_NC'
          Switzerland/Neuchâtel

    `CH_NW'
          Switzerland/Nidwalden

    `CH_OW'
          Switzerland/Obwalden

    `CH_SG'
          Switzerland/St Gallen

    `CH_ST'
          Switzerland/Solothurn

    `CH_SW'
          Switzerland/Schwyz

    `CH_TC'
          Switzerland/Ticino

    `CH_TG'
          Switzerland/Thurgau

    `CH_UI'
          Switzerland/Uri

    `CH_VD'
          Switzerland/Vaud

    `CH_VL'
          Switzerland/Valais

    `CH_ZG'
          Switzerland/Zug

    `CH_ZR'
          Switzerland/Zürich

    `CI'
          Côte d'Ivoire

    `CK'
          Cook Islands

    `CL'
          Chile

    `CM'
          Cameroon

    `CN'
          China

    `CO'
          Colombia

    `CR'
          Costa Rica

    `CU'
          Cuba

    `CV'
          Cape Verde

    `CX'
          Christmas Islands

    `CY'
          Cyprus

    `CZ'
          Czech Republic

    `DE_BA'
          Germany/Bavaria

    `DE_BB'
          Germany/Brandenburg

    `DE_BL'
          Germany/Berlin

    `DE_BR'
          Germany/Bremen

    `DE_BW'
          Germany/Baden-Württemberg

    `DE_HA'
          Germany/Hamburg

    `DE_HS'
          Germany/Hesse

    `DE_MV'
          Germany/Mecklenburg-West Pomerania

    `DE_NS'
          Germany/Lower Saxony

    `DE_NW'
          Germany/North Rhine-Westphalia

    `DE_RP'
          Germany/Rhineland Palatinate

    `DE_SA'
          Germany/Saxony-Anhalt

    `DE_SH'
          Germany/Schleswig-Holstein

    `DE_SL'
          Germany/Saar

    `DE_SN'
          Germany/Saxony

    `DE_TR'
          Germany/Thuringia

    `DJ'
          Djibouti

    `DK'
          Denmark

    `DM'
          Dominica

    `DO'
          Dominican Republic

    `DZ'
          Algeria

    `EC'
          Ecuador

    `EE'
          Estonia

    `EG'
          Egypt

    `EH'
          Western Sahara

    `ER'
          Eritrea

    `ES'
          Spain

    `ET'
          Ethiopia

    `FI'
          Finland

    `FJ'
          Fiji #

    `FK'
          Falkland Islands (Malvinas)

    `FM'
          Federated States of Micronesia

    `FO'
          Faroes

    `FR'
          France

    `GA'
          Gabon #

    `GB_EN'
          Great Britain/England and Wales

    `GB_NI'
          Great Britain/Northern Ireland

    `GB_SL'
          Great Britain/Scotland

    `GD'
          Grenada

    `GE'
          Georgia

    `GF'
          French Guiana

    `GH'
          Ghana

    `GI'
          Gibraltar

    `GL'
          Greenland

    `GM'
          Gambia

    `GN'
          Guinea

    `GP'
          Guadeloupe

    `GQ'
          Equatorial Guinea

    `GR'
          Greece

    `GS'
          South Georgia and South Sandwich Islands

    `GT'
          Guatemala

    `GU'
          Guam

    `GW'
          Guinea-Bissau #

    `GY'
          Guyana #

    `HK'
          Hong Kong

    `HM'
          Heard and Mc Donald Islands

    `HN'
          Honduras

    `HR'
          Croatia

    `HT'
          Haiti

    `HU'
          Hungary

    `ID'
          Indonesia #

    `IE'
          Ireland

    `IL'
          Israel

    `IN'
          India #

    `IQ'
          Iraq

    `IR'
          Islamic Republic of Iran

    `IS'
          Iceland

    `IT'
          Italy

    `JM'
          Jamaica

    `JO'
          Jordan

    `JP'
          Japan

    `KE'
          Kenya #

    `KG'
          Kyrgyzstan

    `KH'
          Cambodia #

    `KI'
          Kiribati #

    `KM'
          Comoros

    `KN'
          St Kitts and Nevis

    `KP'
          Democratic People's Republic of Korea #

    `KR'
          Republic of Korea

    `KW'
          Kuwait

    `KY'
          Cayman Islands

    `KZ'
          Kazakhstan

    `LA'
          Laos People's Democratic Republic #

    `LB'
          Lebanon

    `LC'
          St Lucia

    `LI'
          Liechtenstein

    `LK'
          Sri Lanka #

    `LR'
          Liberia

    `LS'
          Lesotho

    `LT'
          Lithuania

    `LU'
          Luxembourg

    `LV'
          Latvia

    `LY'
          Libyan Arab Jamahiriya (Libya)

    `MA'
          Morocco

    `MC'
          Monaco

    `MD'
          Republic of Moldova

    `MG'
          Madagascar #

    `MH'
          Marshall Islands

    `MK'
          Former Yugoslav Republic of Macedonia

    `ML'
          Mali

    `MN'
          Mongolia #

    `MO'
          Macau

    `MP'
          Northern Marian Islands (Saipan)

    `MQ'
          Martinique

    `MR'
          Mauritania

    `MS'
          Montserrat

    `MT'
          Malta

    `MU'
          Mauritius

    `MV'
          Maldives

    `MW'
          Malawi

    `MX'
          Mexico

    `MY'
          Malaysia #

    `MZ'
          Mozambique

    `NA'
          Namibia

    `NC'
          New Caledonia

    `NE'
          Niger

    `NF'
          Norfolk Islands

    `NG'
          Nigeria

    `NI'
          Nicaragua

    `NL'
          Netherlands

    `NM'
          Myanmar (Burma) #

    `NO'
          Norway

    `NP'
          Nepal #

    `NR'
          Nauru

    `NU'
          Niue

    `NZ'
          New Zealand

    `OM'
          Oman

    `PA'
          Panama

    `PE'
          Peru

    `PF'
          French Polynesia

    `PG'
          Papua New Guinea

    `PH'
          Philippines

    `PK'
          Pakistan

    `PL'
          Poland

    `PM'
          Saint-Pierre and Miquelon

    `PN'
          Pitcairn

    `PR'
          Puerto Rico

    `PT'
          Portugal

    `PW'
          Palau

    `PY'
          Paraguay

    `QA'
          Qatar

    `RE'
          Réunion

    `RO'
          Romania

    `RU'
          Russian Federation

    `RW'
          Rwanda

    `SA'
          Saudi Arabia

    `SB'
          Solomon Islands

    `SC'
          Seychellen

    `SD'
          Sudan

    `SE'
          Sweden

    `SG'
          Singapore #

    `SH'
          St Helena

    `SI'
          Slovenia

    `SJ'
          Svalbard and Jan Mayen Islands

    `SK'
          Slovakia

    `SL'
          Sierra Leone

    `SM'
          San Marino

    `SN'
          Senegal

    `SO'
          Somalia

    `SR'
          Suriname #

    `ST'
          Sao Tomé and Principe

    `SV'
          El Salvador

    `SY'
          Syrian Arab Republic (Syria)

    `SZ'
          Swaziland

    `TC'
          Turks and Caicos Islands

    `TD'
          Chad

    `TG'
          Togo #

    `TH'
          Thailand #

    `TJ'
          Tajikistan

    `TK'
          Tokelau

    `TM'
          Turkmenistan

    `TN'
          Tunisia

    `TO'
          Tonga

    `TR'
          Turkey

    `TT'
          Trinidad and Tobago #

    `TV'
          Tuvalu

    `TW'
          Taiwan

    `TZ'
          Tanzania

    `UA'
          Ukraine

    `UG'
          Uganda

    `US_AK'
          United States/Alaska

    `US_AL'
          United States/Alabama

    `US_AR'
          United States/Arkansas

    `US_AZ'
          United States/Arizona

    `US_CA'
          United States/California

    `US_CO'
          United States/Colorado

    `US_CT'
          United States/Connecticut

    `US_DC'
          United States/District of Columbia

    `US_DE'
          United States/Delaware

    `US_FL'
          United States/Florida

    `US_GA'
          United States/Georgia

    `US_HI'
          United States/Hawaii

    `US_IA'
          United States/Iowa

    `US_ID'
          United States/Idaho

    `US_IL'
          United States/Illinois

    `US_IN'
          United States/Indiana

    `US_KS'
          United States/Kansas

    `US_KY'
          United States/Kentucky

    `US_LA'
          United States/Louisiana

    `US_MA'
          United States/Massachusetts

    `US_MD'
          United States/Maryland

    `US_ME'
          United States/Maine

    `US_MI'
          United States/Michigan

    `US_MN'
          United States/Minnesota

    `US_MO'
          United States/Missouri

    `US_MS'
          United States/Mississippi

    `US_MT'
          United States/Montana

    `US_NC'
          United States/North Carolina

    `US_ND'
          United States/North Dakota

    `US_NE'
          United States/Nebraska

    `US_NH'
          United States/New Hampshire

    `US_NJ'
          United States/New Jersey

    `US_NM'
          United States/New Mexico

    `US_NV'
          United States/Nevada

    `US_NY'
          United States/New York

    `US_OH'
          United States/Ohio

    `US_OK'
          United States/Oklahoma

    `US_OR'
          United States/Oregon

    `US_PA'
          United States/Pennsylvania

    `US_RI'
          United States/Rhode Island

    `US_SC'
          United States/South Carolina

    `US_SD'
          United States/South Dakota

    `US_TN'
          United States/Tennessee

    `US_TX'
          United States/Texas

    `US_UT'
          United States/Utah

    `US_VA'
          United States/Virginia

    `US_VT'
          United States/Vermont

    `US_WA'
          United States/Washington

    `US_WI'
          United States/Wisconsin

    `US_WV'
          United States/West Virginia

    `US_WY'
          United States/Wyoming

    `UY'
          Uruguay

    `UZ'
          Uzbekistan

    `VC'
          St Vincent and Grenadines

    `VE'
          Venezuela

    `VG'
          British Virgin Islands

    `VI'
          U.S. Virgin Islands

    `VN'
          Viet Nam

    `VU'
          Vanuatu

    `WF'
          Wallis and Futuna Islands

    `WS'
          Samoa

    `YE'
          Yemen

    `YT'
          Mayotte

    `YU'
          Serbia and Montenegro

    `ZA'
          South Africa

    `ZM'
          Zambia

    `ZW'
          Zimbabwe

`--bahai-months'
     Provide the eternal holiday list additionally with the starting
     dates of the common and leap months, as they result from the
     Bahá'ì calendar.  *Note Calendar option `--bahai-holidays':
     x-bahai-holidays, for further details.

`--chinese-flexible-months'
     Provide the eternal holiday list additionally with the starting
     dates of the common and leap months, as they result from the
     Chinese calendar, that is determined in a flexible manner.  *Note
     Calendar option `--chinese-flexible-holidays':
     x-chinese-flexible-holidays, for further details.

`--chinese-months'
     Provide the eternal holiday list additionally with the starting
     dates of the common and leap months, as they result from the
     Chinese calendar.  *Note Calendar option `--chinese-holidays':
     x-chinese-holidays, for further details.

`--coptic-months'
     Provide the eternal holiday list additionally with the starting
     dates of the common and leap months, as they result from the
     Coptic calendar (only for dates after AD 283).

`--ethiopic-months'
     Provide the eternal holiday list additionally with the starting
     dates of the common and leap months, as they result from the
     Ethiopic calendar.

`--french-revolutionary-months'
     Provide the eternal holiday list additionally with the starting
     dates of the common and leap months, as they result from the
     French Revolutionary calendar (only for dates after AD 1791).

`--hebrew-months'
     Provide the eternal holiday list additionally with the starting
     dates of the common and leap months, as they result from the
     Hebrew calendar.

`--indian-civil-months'
     Provide the eternal holiday list additionally with the starting
     dates of the common and leap months, as they result from the civil
     Indian calendar (only for dates after AD 1956).

`--islamic-civil-months'
     Provide the eternal holiday list additionally with the starting
     dates of the common and leap months, as they result from the civil
     Islamic calendar.  *Note Calendar option
     `--islamic-civil-holidays': x-islamic-civil-holidays, for further
     details.

`--japanese-flexible-months'
     Provide the eternal holiday list additionally with the starting
     dates of the common and leap months, as they result from the
     Japanese calendar, that is determined in a flexible manner.  *Note
     Calendar option `--japanese-flexible-holidays':
     x-japanese-flexible-holidays, for further details.

`--japanese-months'
     Provide the eternal holiday list additionally with the starting
     dates of the common and leap months, as they result from the
     Japanese calendar.  *Note Calendar option `--japanese-holidays':
     x-japanese-holidays, for further details.

`--old-armenic-months'
     Provide the eternal holiday list additionally with the starting
     dates of the common and leap months, as they result from the
     Old-Armenic calendar (only for dates after AD 551).

`--old-egyptic-months'
     Provide the eternal holiday list additionally with the starting
     dates of the common and leap months, as they result from the
     Old-Egyptic calendar.

`--persian-jalaali-months'
     Provide the eternal holiday list additionally with the starting
     dates of the common and leap months, as they result from the
     Persian _Jalaali_ calendar.  *Note Calendar option
     `--persian-jalaali-holidays': x-persian-jalaali-holidays, for
     further details.

`-i[-]'
`--type=special|standard'
     To obtain the "standard calendar format"(2) (*note Calendar
     options-Footnote-2::), either start Gcal omitting the `-i[-]'
     option because it is set by default, *Note Aspects in
     Internationalization: Internationalization, or start Gcal with the
     `-i-' respectively `--type=standard' option:

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

     To obtain the "special calendar format", start Gcal with the `-i'
     respectively `--type=special' option:

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

`-O'
`--orthodox-calendar'
     Use the leap year rule as used by the Eastern Orthodox churches.

     Without specifying the `--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:

          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.

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

          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.

     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.

`-K'
`--with-week-number'
     Provide the calendar sheet with week numbers.  *Note Calendar
     option `--starting-day=ARGUMENT': x-starting-day, *Note Calendar
     option `--iso-week-number=yes|no': x-iso-week-number, and *Note
     Aspects in Internationalization: Internationalization, for further
     details.

`--iso-week-number=yes|no'
     Determine the type of week numbers which are used in the calendar
     sheet, in the fixed date list and by the `%DATE' actual date
     modifier.  *Note Calendar option `--starting-day=ARGUMENT':
     x-starting-day, and *Note Aspects in Internationalization:
     Internationalization, for more details.

    `--iso-week-number=yes'
          The methods of the ISO-8601:1988 are used for detecting week
          numbers; this means a week starts on Mondays, and the first
          week of a year is the one which includes the first Thursday;
          equivalently, the one which includes the 4th January.  This
          method is called "ISO week number" in the further context.
          If the starting day of the week is not set to Monday, 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!

    `--iso-week-number=no'
          Weeks start on the respective starting day of the week, and
          the days in a new year that are preceding the first starting
          day of the week are in the last week of the previous year,
          respectively in week zero of the new year.  This method is
          called "standard week number" in the further context.

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

`-b NUMBER'
`--blocks=NUMBER'
     Set NUMBER of calendar sheet blocks (valid arguments:
     `1|2|3|4|6|12').  The default NUMBER for the _standard calendar
     format_ is `-b4 ' respectively `--blocks=4', and for the _special
     calendar format_ `-b 3' respectively `--blocks=3'.  If this option
     is found, the program sees that a year calendar output is desired!

    `-b 1'
    `--blocks=1'
          Displays one block with twelve months at a time.

    `-b 2'
    `--blocks=2'
          Displays two blocks with six months at a time.

    `-b 3'
    `--blocks=3'
          Displays three blocks with four months at a time.

    `-b 4'
    `--blocks=4'
          Displays four blocks with three months at a time.

    `-b 6'
    `--blocks=6'
          Displays six blocks with two months at a time.

    `-b 12'
    `--blocks=12'
          Displays twelve blocks with one month at a time.

`-j[b]'
`--calendar-dates=special|both'
     Use alternative date format in calendar sheet instead of the
     default standard format which displays the days of month in
     consecutive manner.

    `-j'
    `--calendar-dates=special'
          Display the calendar sheet by using the special date format.
          This means, the days of year are displayed in consecutive
          manner instead of the days of month.

    `-jb'
    `--calendar-dates=both'
          Display the calendar sheet by using both the standard date
          format and special date format.

`-jn[b]'
`--holiday-dates=special|both'
     Use alternative date format in eternal holiday list instead of the
     default standard format which displays the days of month in
     consecutive manner.  *Note Calendar option
     `--holiday-list[=long|short]': x-holiday-list.

    `-jn'
    `--holiday-dates=special'
          Display the eternal holiday list by using the special date
          format.  This means, the days of year are displayed in
          consecutive manner instead of the days of month.

    `-jnb'
    `--holiday-dates=both'
          Display the eternal holiday list by using both the standard
          date format and special date format.

`-jc[b]'
`--fixed-dates=special|both'
     Use alternative date format in fixed date list instead of the
     default standard format which displays the days of month in
     consecutive manner.  *Note Fixed date option
     `--list-of-fixed-dates[=short|long]': x-list-of-fixed-dates.

    `-jc'
    `--fixed-dates=special'
          Display the fixed date list by using the special date format.
          This means, the days of year are displayed in consecutive
          manner instead of the days of month.

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

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

     For example:

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

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

     If the `-s today' option (or `--starting-day=today') or the `-s 0'
     option (or `--starting-day=0') is given, the starting day of the
     week is set to the actual weekday as it is delivered by the system
     date.  *Note Aspects in Internationalization: Internationalization,
     for more details.

`--time-offset=ARGUMENT'
     Change the base time of the astronomical functions (valid ARGUMENT:
     `t|@|[t|@][+|-]MMMM|HH:[MM]').

     If no `--time-offset=ARGUMENT' option is given, the astronomical
     data that is inserted into the eternal holiday list by the
     `--astronomical-holidays' option (*note Calendar option
     `--astronomical-holidays': x-astronomical-holidays.), and all Sun
     and Moon related special texts are always calculated for 0 o'clock
     Universal time (UTC/GMT), thus "civil midnight time".

     *Note Sun data::, and *Note Moon data::, likewise *Note Moon
     phase::, for further information.

     The ARGUMENT is either the `t' or the `@' character --where `t'
     means a relation to the actual local time(3) (*note Calendar
     options-Footnote-3::) and `@' denotes a relation to the actual
     Universal time--, or one of these characters followed by a
     displacement value, or only a displacement value which has to be
     specified either by using the `[+|-]MMMM' format or the
     `[+|-]HH:[MM]' format.  `[+|-]MMMM' adds respectively subtracts
     the specified amount of minutes MMMM from the base time value 0
     o'clock Universal time (range `0...9999'), while `[+|-]HH:[MM]'
     adds respectively subtracts the given amount of hours HH (range
     `0...99') and minutes MM (range `0...59') from the base time value
     0 o'clock Universal time.  The displacement value is always added
     to the base time value 0 o'clock Universal time in case it is
     specified without a `+|-' sign.

     For example, the `--time-offset=+1:' option causes that while
     displaying eternal holiday lists and fixed date lists, the time 0
     o'clock of the timezone GMT-1 (== CET) is used as the base time by
     the astronomical functions instead of the base time 0 o'clock
     Universal time (== GMT).

     For example, the `--time-offset=t-2:' option causes that while
     displaying eternal holiday lists and fixed date lists, the time
     that is two hours earlier than the actual local time is used as
     the base time by the astronomical functions instead of the base
     time 0 o'clock Universal time (== GMT).  For such a kind of
     relation, the term "relative time offset value" will be used in
     the further context.

`--transform-year=ARGUMENT'
     Change the base year of calendar (valid ARGUMENT:
     `-9999...[+]9999').

     For example, the `--transform-year=-543' option causes that while
     displaying calendar sheets, eternal holiday lists and fixed date
     lists, the year 543 BC is used as the base year of the calendar
     instead of the year AD 1.  This results in the case that --for
     example-- for the year 1999 (Christian era), the year number 1999
     is not used in the above mentioned outputs, but the year number
     2542 which is used in the western oriented Thai calendar.

     Nevertheless, Gcal does not respect the
     `--transform-year=ARGUMENT' option when using the actual date
     modifier `%DATE' (*note Actual date modifier::), the commands
     (*note Commands::), and the fixed date entries in a resource file
     (*note Date part of a line::).  There, all references made to a
     definite year are always treated in the way that the year AD 1 is
     the base year of the calendar, so in fact it is *only* possible to
     use references based on the Christian era.

`--gregorian-reform=1582|1700|1752|1753|ARGUMENT'
     Set the period which was skipped during the Gregorian Reformation.
     By default, Gcal runs in the "hybrid" calendar mode, i.e. Gcal
     automatically changes from the Julian calendar system to the
     Gregorian calendar system if output is related to dates after the
     Gregorian Reformation has happened.  *Note Aspects in
     Internationalization: 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 `--gregorian-reform=1582' option, it
     assumes the Gregorian Reformation has occurred from 5th till 14th
     October 1582.

     If Gcal is called with the `--gregorian-reform=1700' option, it
     assumes the Gregorian Reformation has occurred from 19th till 28th
     February 1700.

     If Gcal is called with the `--gregorian-reform=1752' option, it
     assumes the Gregorian Reformation has occurred from 3rd till 13th
     September 1752.

     If Gcal is called with the `--gregorian-reform=1753' option, it
     assumes the Gregorian Reformation has occurred from 18th till 28th
     February 1753.

     In case another period shall be respected, it can be arranged by
     the option ARGUMENT like `YYYYY,MM,FIRST-DAY,LAST-DAY'.  If the
     Gregorian Reformation has occurred for example on the 7th till the
     17th April 1802, this can be arranged as follows:

          --gregorian-reform=1802,4,7,17

     Gcal is able to represent so-called "proleptic" calendars of a
     definite calendar system.  This means, Gcal only uses a definite
     calendar system during a definite period, although there was a
     change to another calendar system in the historic reality during
     this definite period.  The following proleptic calendar systems
     are actually supported by Gcal:

        * Proleptic Gregorian calendars can be created from AD 302 until
          AD 9999 if `--gregorian-reform=301,12,31,31' is used.
          Unfortunately, Gcal actually cannot represent years before AD
          302 in a proleptic-Gregorian manner.

        * Proleptic Julian calendars can be created from AD 1 until AD
          9999 if `--gregorian-reform=10002,12,31,31' is used.  In this
          case, the actual system date that is normally based on the
          Gregorian calendar and that is used by Gcal, is internally
          and automatically converted into the according Julian date(4)
          (*note Calendar options-Footnote-4::).  The same happens if
          the actual system date is modified by using the actual date
          modifier `%DATE'.  In such a case, Gcal also assumes that the
          given date is a Gregorian date, and converts it automatically
          into the according Julian date internally.  *Note Actual date
          modifier::, for further details.

     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 has occured) if the
     argument of the `--gregorian-reform' option is not used with care.

`--date-format=de|us|gb|TEXT'
     Set the date format which affects the ordering and representation
     of a displayed date.  *Note Aspects in Internationalization:
     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
     day-of-year numbers instead of the day-of-month numbers must be
     displayed, or both types of numbers are used in a combined manner.

     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 `--date-format=de' option,
     the `%<2#K,  %1%>2*D%2 %<3#U %>04*Y' date format text is used.
     This result in that a date is displayed by using the
     `WW,  DD MMM YYYY' ordering, for example `Sa,  28 Aug 1999'.

     If Gcal is called with the `--date-format=us' option,
     the `%<3#K, %<3#U  %1%>2&*D%2 %>04*Y' date format text is used.
     This result in that a date is displayed by using the
     `WWW, MMM  DD YYYY' ordering, for example `Sat, Aug  28th 1999'.

     If Gcal is called with the `--date-format=gb' option,
     the `%<3#K,  %1%>2&*D%2 %<3#U %>04*Y' date format text is used.
     This result in that a date is displayed by using the
     `WWW,  DD MMM YYYY' ordering, for example `Sat,  28th Aug 1999'.

     In case another format text shall be respected, this format text
     can either be set in the `GCAL_DATE_FORMAT' environment
     variable(5) (*note Calendar options-Footnote-5::), or it can be
     arranged by the option argument TEXT.  For example,
     `--date-format='%Y %D %>02*M ; %1(%>5u#K)%2'' displays a date by
     using the `[[[Y]Y]Y]Y [D]D MM ; (WWWWW)' ordering, thus for
     example `1999 28 08 ; (SATUR)'.  *Note Environment Variable
     `GCAL_DATE_FORMAT': x-GCAL_DATE_FORMAT, for further information.

     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 elements which are transformed
     into their according values at run-time.  Some format elements may
     have a format instruction which is called FORMAT in the further
     context.  *Note Format Instruction::, for the detailed description
     of the format instruction and its components.

     A minimum date format text must contain the following format
     elements minimum:

          The day number, one component of the month group, the year
          number and both components of the highlighting group.

     A weekday name format element may be included optionally into the
     date format text.  The following format elements and character
     replacement instructions are currently supported:

    `%[FORMAT]D'
          Day number (must be defined)

    `%[FORMAT]Y'
          Year number (must be defined)

    `%[FORMAT]K'
          Weekday name (may be defined)

     Month group (exactly one member must be defined):

    `%[FORMAT]M'
          Month number

    `%[FORMAT]U'
          Month name

     Highlighting group (all members must be defined and `%1' must be
     specified before `%2'):

    `%1'
          Start of highlighting sequence / marking character

    `%2'
          End of highlighting sequence / marking character

     Character replacement instructions:

    `_'
          Space/blank character ` '

    `\_'
          Underscore character `_'

    `\%'
          Percent character `%'

    `\\'
          Backslash character `\'

     *Note Table of Obsolete Date Formats::, and *Note Table of
     Obsolete Date Format Elements::, for further information.

`--translate-string=TEXT'
     Define the country specific special character pairs which are
     respected or translated by a STYLE format instruction component,
     respectively.  *Note Format Instruction::, for the detailed
     description of the format instruction and its components.  The
     country specific special character pairs are arranged by the TEXT
     option argument as a sequence of single character pairs, and that
     in any number and order.  The upper-case representation of the
     country specific special character has to be specified at first,
     and after that its lower-case representation.  Country specific
     special characters which do not have an upper-case resp.,
     lower-case representation in the character set used, like e.g. the
     `ß'-character which is very usual in the German character set, are
     also specified as a special character pair (here: `ßß'), otherwise
     these special characters are not recognized and they are converted
     incorrectly by the STYLE format instruction component.  In case the
     lower-case representation of the country specific special
     character is specified at first, and after that its upper-case
     representation, this option does not cause any further affects to
     the STYLE format instruction component; resulting, the country
     specific special characters specified are not recognized as such
     and they remain untranslated therefore.

     For example, a `ÄäÖöÜüßß' option argument causes the correct
     conversion of the preceding special characters in an individual
     date format, which has a STYLE format instruction component, and
     that, how they are used by the character set used in Germany.

