Gcal 4.1

Table of Contents

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 4.1 of Gcal, an Extended Calendar Program,
24 June 2000, for the 4.1 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

Appendices

Indices

  — The Detailed Node Listing —

Invoking Gcal

Command line arguments

Options

Commands

Fixed Dates

Resource file

Further date part attributes

Gcal Utilities

Regular Expressions

Special Texts

Exclusions

Exclusions with date argument

Exclusions without any argument

Replacements

Replacements with date argument

Replacements with other argument

Replacements without any argument

Obsolete Special Texts

Coding Scheme

1 Preface

The reason why I have written Gcal was mainly to have an off-line tool¹ 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 a lot more.

The accuracy 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²,
• 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 existing 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 existence 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 development 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. See Calendar option --cc-holidays=cc[_tt][+…], 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 historians 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 historians 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 criteria that are existing for the first sighting of the crescent 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 criteria, and on the other hand, there are also quite religiously-based criteria. 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 criteria. 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 religious 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 to determine the astronomical lunisolar Chinese calendar. This calendar is obligatory for (the Peoples Republic of) China since 1929 and is determined annually 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 exemplary manner only! A detailed description of all possible use is inexpedient here because there are simply too many of such possibilities which are caused by the existing variety of combinations of all useable modes of operation.

Furthermore, this manual does not contain detailed explanations 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 occurring 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!

2 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³.

There are two methods to display a preview of fixed dates⁴ or retrospective view of fixed dates⁵. 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 explanations respectively summaries and tables to definite details or themes from other disciplines can be found in the numerous appendices.

3 Invoking gcal

Gcal is a command line oriented program. It is usually called from the shell⁶ and processes given arguments that are options and commands. Options must be given before commands, i.e. you must call Gcal like this:

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. See Genesis of the Gregorian Calendar, and Aspects in Internationalization, for further details.

3.1 Command line arguments

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⁷ 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:

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

3.1.1 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⁸ 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 preselected 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.

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

3.1.1.2 Global options

-R name

--response-file=name

Write the contents of the environment variable GCAL (see Environment Variable GCAL), and then the arguments of command line (in the given order) to file name, i.e. create response file name. See Response file, for more details.

-S name

--shell-script=name

Write the contents of the environment variable GCAL (see Environment Variable 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. See 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. See Environment Variable 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⁹. See Environment Variable 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. See Environment Variable GCAL_LINES, and Environment Variable GCAL_COLUMNS, for further information.
2. If above action fails, Gcal respects the values set in the environment variables LINES and COLUMNS. See Environment Variable LINES, and Environment Variable COLUMNS, for more details.
3. If above action fails, Gcal respects the values set in the termcap¹⁰ file which refers to the terminal used (see Environment Variable 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¹¹.

-H yes

--force-highlighting

--highlighting=yes

If the output of the program is redirected¹² or piped¹³, 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. See Global option --mail[=address].

-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’¹⁴ 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. See Environment Variable 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. See Environment Variable GCALANSI.

--mail[=address]

Send Gcal’s output via mail¹⁵ 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. See Environment Variable 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. See Environment Variable 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. See Environment Variable 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 explanations concerning the limitations of the text part of a resource file line (see 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. See Environment Variable MAILPROG, for more information.

3.1.1.3 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. See Eternal Holidays, and Calendar option --cc-holidays=cc[+…], 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. See Calendar option --time-offset=argument, 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. See Calendar option --time-offset=argument, 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). See Calendar option --time-offset=argument, how to change the timezone for which the Chinese holidays are calculated in a flexible manner. See 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 Beijing local time, for later dates fixed on the timezone GMT-8. See 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. See 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). See Calendar option --time-offset=argument, 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 Beijing 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. See Calendar option --time-offset=argument, 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. See Calendar option --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. See Calendar option --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. See Calendar option --time-offset=argument, 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¹⁶ 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

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/Northwest 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_AG

Switzerland/Aargau

CH_AI

Switzerland/Appenzell Innerrhoden

CH_AR

Switzerland/Appenzell Ausserrhoden

CH_BE

Switzerland/Bern

CH_BL

Switzerland/Basel-Land

CH_BS

Switzerland/Basel-Stadt

CH_FR

Switzerland/Fribourg

CH_GE

Switzerland/Genève

CH_GL

Switzerland/Glarus

CH_GR

Switzerland/Graubünden

CH_JU

Switzerland/Jura

CH_LU

Switzerland/Luzern

CH_NE

Switzerland/Neuchâtel

CH_NW

Switzerland/Nidwalden

CH_OW

Switzerland/Obwalden

CH_SG

Switzerland/St Gallen

CH_SH

Switzerland/Schaffhausen

CH_SO

Switzerland/Solothurn

CH_SZ

Switzerland/Schwyz

CH_TG

Switzerland/Thurgau

CH_TI

Switzerland/Ticino

CH_UR

Switzerland/Uri

CH_VD

Switzerland/Vaud

CH_VS

Switzerland/Valais

CH_ZG

Switzerland/Zug

CH_ZH

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_BB

Germany/Brandenburg

DE_BE

Germany/Berlin

DE_BW

Germany/Baden-Württemberg

DE_BY

Germany/Bavaria

DE_HB

Germany/Bremen

DE_HE

Germany/Hesse

DE_HH

Germany/Hamburg

DE_MV

Germany/Mecklenburg-West Pomerania

DE_NI

Germany/Lower Saxony

DE_NW

Germany/North Rhine-Westphalia

DE_RP

Germany/Rhineland Palatinate

DE_SH

Germany/Schleswig-Holstein

DE_SL

Germany/Saar

DE_SN

Germany/Saxony

DE_ST

Germany/Saxony-Anhalt

DE_TH

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 Island

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. See Calendar option --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. See Calendar option --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. See Calendar option --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. See Calendar option --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. See Calendar option --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. See Calendar option --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. See Calendar option --persian-jalaali-holidays, for further details.

-i[-]

--type=special|standard

To obtain the standard calendar format¹⁷, either start Gcal omitting the -i[-] option because it is set by default, Aspects in 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 hundreds 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 hundreds 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. See Calendar option --starting-day=argument, Calendar option --iso-week-number=yes|no, and Aspects in 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. See Calendar option --starting-day=argument, and Aspects in 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. See Calendar option --holiday-list[=long|short].

-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. See Fixed date option --list-of-fixed-dates[=short|long].

-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. See Aspects in 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 (see Calendar option --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.

See Sun data, and Moon data, likewise Moon phase, for further information.

The argument is either the ‘t’ or the ‘@’ character —where ‘t’ means a relation to the actual local time¹⁸ 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 (see Actual date modifier), the commands (see Commands), and the fixed date entries in a resource file (see 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. See 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 --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¹⁹. 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. See 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 occurred) 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. See 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 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²⁰, 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)’. See Environment Variable 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. See 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 ‘\’

See Table of Obsolete Date Formats, and 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. See 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.

3.1.1.4 Fixed date options

-v argument

--date-variable=argument

Define global date variable which is visible in all referenced resource files (see Date variables). The option argument must either be a valid single date variable definition or a (‘:’) colon-connected series of definitions.

A date variable name dvar consists of a single, case-insensitive letter²¹. In a definition, this name is trailed by the assignment operator character ‘=’, and the numerical values of month mm (or a short, three characters month name, e.g. ‘Jan’, ‘Feb’…) and day dd, this variable has to store²².

For example:

--date-variable=a=1127:c=a respectively
-v a=1127:c=a
stores the 27th November into the global date variable a and into the global date variable c.

--export-date-variables

Causes the export of local date variables from one resource file to another resource file. See Date variables, for more details.

-r argument

--text-variable=argument

Define global text variable which is visible in all referenced resource files (see Text variables). The option argument must either be a valid single text variable definition or a (‘:’) colon-connected series of definitions.

A text variable name tvar consists of the ‘$’ prefix and a single, case-insensitive letter.

A text variable is defined as follows:

• If the name of a text variable is trailed by the assignment operator character ‘=’, all the text which appears at the right side of this assignment operator is assigned to this text variable.
• If the name of a text variable is trailed by the assignment operator character ‘?’, all the text which appears at the right side of this assignment operator is assumed as an external command and executed by Gcal. The output, which is created on the standard output channel by the command run, is assigned to this text variable; and that in an interpreted manner. This means, Gcal interprets all special texts and references to other text variables which are contained in this output. See Text variables, and Special Texts processed, for further information.
• If the name of a text variable is trailed by the assignment operator character ‘:’, all the text which appears at the right side of this assignment operator is assumed as an external command and executed by Gcal. The output, which is created on the standard output channel by the command run, is assigned to this text variable; and that in an uninterpreted manner. This means, Gcal does not interpret any special texts and references to other text variables which are contained in this output. See also Text variables, and Special Texts processed, for further details.

Indeed, Gcal executes external commands only if the --execute-command option is given at program start-up. See Fixed date option --execute-command, for more details.

The text which appears at the right side of one of the valid assignment operator characters may reference names of already defined global text variables. These references are converted to the according textual values just before the assignment is performed by Gcal.

A global text variable is defined with an empty contents in case no text appears at the right side of one of the valid assignment operator characters.

For example:

--text-variable=$a=foo:$c=$a respectively
-r $a=foo:$c=$a
stores the ‘foo’ text into the global text variable $a and into the global text variable $c.

--text-variable=$a\:foo:$c?bar respectively
-r $a\:foo:$c?bar
stores the uninterpreted output of the foo command into the global text variable $a, and the interpreted output of the bar command into the global text variable $c.

You may depreciate the special meaning of the ‘:’ separator character —in case this character itself is needed— by placing a ‘\’ (backslash) character before it, e.g. ‘\:’. If you need the ‘\:’ characters themselves, you have to protect the ‘\’ (backslash) character by another ‘\’ (backslash) character, e.g. ‘\\:’.

You may depreciate the special meaning of the ‘$’ prefix character —in case this character itself is needed in the text— by placing a ‘\’ (backslash) character before it, e.g. ‘\$’. If you need the ‘\$’ characters themselves in the text, you have to protect the ‘\’ (backslash) character by another ‘\’ (backslash) character, e.g. ‘\\$’.

Each time a ‘_’ (underscore) character is found in argument, this character is replaced by a real ‘ ’ (space) character.

You may depreciate the special meaning of the ‘_’ (underscore) character —in case this character itself is needed— by placing a ‘\’ (backslash) character before it, e.g. ‘\_’. If you need the ‘\_’ themselves, you have to protect the ‘\’ (backslash) character by another ‘\’ (backslash) character, e.g. ‘\\_’.

--export-text-variables

Causes the export of local text variables from one resource file to another resource file. See Text variables, for more details.

--adjust-value=argument

Causes on the one hand, that the number given as argument to the --adjust-value option is used as reference altitude to calculate the rise and set times by the Sun and Moon oriented special texts. The option argument must be a rational number in range -90.0…+90.0, which declares the angle distance in decimal degrees from the center of astronomical object to the horizon. For example, you can detect the time when the center of the Sun or the Moon is 20.5 decimal degrees below the horizon if you use --adjust-value=-20.5.

And causes on the other hand, that the number that is given as argument is used as factor for computing the shadow length of a vertical pole by the Sun oriented special texts. The option argument must be a rational number in range 0.0…+90.0, which declares the shadow length. For example, you can detect the time when the shadow length of vertical pole is three and a half times longer than the shadow length that appears at astronomical noon if you use --adjust-value=3.5.

See Sun data, and Moon data, for further information.

--atmosphere=air-pressure[,temperature]

Set the base data of the Earth’s atmosphere that is necessary to calculate the amount of refraction²³, that is used by the Sun and Moon oriented special texts. The option argument consists of one or two rational numbers, which are separated by a ‘,’ character. The first number denotes the air pressure in millibar, and the second number specifies the air temperature in degree Celsius. The default value for the air pressure is 1013.25 millibar, and the default value for the temperature is 15.0 degree Celsius. For example, if you use --atmosphere=1010,10, you define atmospheric conditions as they are existing for an air pressure of 1010 millibar and a temperature of 10 degree Celsius. If you set an air pressure value less or equal zero, no atmospheric refraction will be respected by the Sun and Moon oriented special texts, as for example done by --atmosphere=0.

See Sun data, and Moon data, for further information.

--limit

Causes when calculating the rise and set times by the Sun oriented special texts for high latitudes, that a rise or set event which possibly occurs on a previous or next day, is not displayed as occurring on the actual day as it is done by default. At high latitudes, i.e. above the solar Arctic Circle, it is fact that no, or more than one sunrise or sunset happens during a day at definite dates of the year. As a special text basically leads in a single, atomical output, even it should result in several output in reality, Gcal puts such an event on a previous or next day. Then, data represented in this manner could be misinterpreted very easily.

The following example is used to explain this. It calculates the time the astronomical twilight ends for the location Münster, Germany, during some days in May 2000, and that with and without the --limit option in each case:

$ gcal %20000506 -f/dev/null -cxl4+ \ > -#'0*d1#999_%s9+5158+00738,120' -| -| Sun, May 7th 2000: 23:52 -| Mon, May 8th 2000: 23:57 -| Tue, May 9th 2000: 00:01 -| Wed, May 10th 2000: 00:06 $ gcal %20000506 -f/dev/null -cxl4+ --limit \ > -#'0*d1#999_%s9+5158+00738,120' -| -| Sun, May 7th 2000: 23:52 -| Mon, May 8th 2000: 23:57 -| Tue, May 9th 2000: **:** -| Wed, May 10th 2000: **:**

As one can see well in the above example, the output for the days since 9th May differs in that the times shown without the --limit option obviously exceeded the civil midnight time and actually cannot happen during these days, whereas no times are shown for the days since 9th May if the --limit option is used because the time circle is exceeded. Astronomically seen, it is the case that the end of the astronomical twilight is at 23:57 o’clock local time on 8th May, no end of astronomical twilight happens on 9th May because the center of the Sun’s disk is always above 18 degrees (the reference altitude of the astronomical twilight) below a geometric horizon, but on 10th May at 00:01 o’clock local time, this reference altitude is passed again. Thus, the time that is detected for the 9th May has properly to be moved to the 10th May, et cetera, as it is expressed by the output that is created by using the --limit option.

See Sun data, for further information.

--cycle-end=argument

Calculates the Sun and Moon oriented special texts that are dynamical, i.e. depending on the respective clocktime, for a series of clocktimes for the current day, i.e. determination is done for any time interval that can be individually defined by the user. Gcal is always put into such a cycle mode if the --cycle-end option is given at program start-up. The argument of the --cycle-end option is syntactically according to the argument which may be given to the --time-offset option, thus t|@|[t|@][+|-]mmmm|hh:[mm]. See Calendar option --time-offset=argument, for the detailed explanation of the preceding option argument. Thus, the --cycle-end option is used to fix the ending time of the time interval, whereas the --time-offset option is implicitly used to fix the starting time of the time interval, that is 0 o’clock by default²⁴.

If values for the time interval are given to both above mentioned options that fall short of 0 o’clock, these values are automatically set to 0 o’clock. If values for the time interval are given that exceed 23:39 o’clock, these values are automatically set to 23:59 o’clock.

The timestep value between the starting and the ending time of the time interval that is respected by Gcal is one minute by default. This value can at pleasure be changed by using the --cycle-step option. See Fixed date option --cycle-step=argument, for more details.

You should always keep in mind that the use of the cycle mode is efficient only if the current time of the time interval is also part of that resource file line that has to be evaluated in this manner. Otherwise, it is difficult to find out unobjectionably lateron when displaying the data and times, which Sun or Moon oriented value resulted in what time.

The following example shows how the topocentric elevation angle of the Sun for the location Münster, Germany, is calculated during two days in April 2000, and that for the time interval 12:00 o’clock until 12:05 o’clock local time in each case:

$ gcal %20000420 -Hno -f/dev/null -xdt -g::: \ > --here='0*d1#999_%ot+00+000_:_%oa+5158+00738,120' \ > --cycle-end=12:05 --time=12:00 -| -| Thu, Apr 20th 2000: +12h00': +045d58' -| Thu, Apr 20th 2000: +12h01': +046d03' -| Thu, Apr 20th 2000: +12h02': +046d07' -| Thu, Apr 20th 2000: +12h03': +046d12' -| Thu, Apr 20th 2000: +12h04': +046d17' -| Thu, Apr 20th 2000: +12h05': +046d22' -| ::: -| Fri, Apr 21st 2000: +12h00': +046d18' -| Fri, Apr 21st 2000: +12h01': +046d23' -| Fri, Apr 21st 2000: +12h02': +046d28' -| Fri, Apr 21st 2000: +12h03': +046d32' -| Fri, Apr 21st 2000: +12h04': +046d37' -| Fri, Apr 21st 2000: +12h05': +046d42'

See Sun data, and Moon data, for further information.

--cycle-step=argument

Changes the timestep value that is used between the starting and ending clocktime of the time interval, in which the Sun and Moon oriented special texts are calculated, that are dynamical, i.e. depending on the respective clocktime. See Fixed date option --cycle-end=argument, how to define such a time interval. Without the --cycle-end option, a --cycle-step option is completely ignored. It also does not enable Gcal’s cycle mode. The argument of the --cycle-step option is by change syntactically according to the argument which may be given to the --time-offset option, and that relative time offset value references based on the actual local time and Universal time cannot be made, respectively. Gcal always uses the amount of the given timestep value. Thus, the template for the argument that may be given to the --cycle-step option is [+|-]mmmm|hh:[mm]. See Calendar option --time-offset=argument, for the detailed explanation of the preceding option argument.

The timestep value between the starting and the ending time of the time interval that is respected by Gcal is one minute by default.

The following example shows how the topocentric elevation angle of the Sun for the location Münster, Germany, is calculated during two days in April 2000, and that for the time interval 10:00 o’clock until 17:00 o’clock local time with a timestep value of one hour and 15 minutes in each case:

$ gcal %20000420 -Hno -f/dev/null -xdt -g::: \ > --here='0*d1#999_%ot+00+000_:_%o*a+5158+00738,120' \ > --cycle-end=10:00 --time=17:00 --cycle-step=1:15 -| -| Thu, Apr 20th 2000: +10h45': +38.038 -| Thu, Apr 20th 2000: +12h00': +45.962 -| Thu, Apr 20th 2000: +13h15': +49.665 -| Thu, Apr 20th 2000: +14h30': +47.882 -| Thu, Apr 20th 2000: +15h45': +41.267 -| Thu, Apr 20th 2000: +17h00': +31.633 -| ::: -| Fri, Apr 21st 2000: +10h45': +38.355 -| Fri, Apr 21st 2000: +12h00': +46.299 -| Fri, Apr 21st 2000: +13h15': +50.006 -| Fri, Apr 21st 2000: +14h30': +48.198 -| Fri, Apr 21st 2000: +15h45': +41.545 -| Fri, Apr 21st 2000: +17h00': +31.881

See Sun data, and Moon data, for further information.

--precise

The astronomical data and times that are created by the Sun and Moon oriented special texts, and the geographical data that is created by the distance and course angle oriented special text, respectively, are displayed by using a higher precision, i.e. according to the mode or style of representation and the type of special text, decimal values are displayed with more decimal places, or output of the time seconds part or the arcseconds part.

See Sun data, and Moon data, likewise Geographical distance and course angle, for further information.

--execute-command

Causes on the one hand, that shell command %![argument] special texts are executed, and not displayed textually only. See Shell command %![argument] special text, for more details. And causes on the other hand, that ‘tvar?[command]’ and ‘tvar:[command]’ text variable definitions is assigned the output of an external command, and not the text which contains the call of the external command. See Text variables, for further information.

-D argument

--filter-day=argument

Displays only those fixed dates, whose date is not excluded by the given argument. See Date part of a line, and likewise Exclusions without any argument %? special texts. The argument consists of one or more characters as used in the exclusion without any argument %? special text; but without the leading ‘%’ character in each case.

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

gcal -f demo.rc --year --filter-day=Rv

-P argument

--filter-period=argument

Displays only those fixed dates, whose date is not excluded by the given argument. See Date part of a line, and likewise Exclusions with date argument %?[date] special texts. The argument consists of one or more expressions as used in the exclusion with date argument %?[date] special text; but without the leading ‘%’ character in each case. You can use more than one of these %?[date] expressions by connecting them with a ‘,’ character.

For example, it is possible to induce Gcal to display only those fixed dates from the resource 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.

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

-I pattern

--filter-text=pattern

Displays only those fixed dates, whose completely expanded text²⁵ is matched by the given pattern. See Text part of a line, and %?… special texts for text replacement. The pattern is a regular expression, as recognized by the Unix ed line-editor. See Regular Expressions, for further information.

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

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

Each time a ‘_’ (underscore) character is found in the pattern argument, this character is replaced by a real ‘ ’ (space) character.

You may depreciate the special meaning of the ‘_’ (underscore) character —in case this character itself is needed— by placing a ‘\’ (backslash) character before it, e.g. ‘\_’. If you need the ‘\_’ characters themselves, you have to protect the ‘\’ (backslash) character by another ‘\’ (backslash) character, e.g. ‘\\_’.

--ignore-case

Ignores all case distinctions in both the completely expanded text and the pattern of the --filter-text=pattern option. See Fixed date option --filter-text=pattern.

--revert-match

Displays all those fixed dates, whose completely expanded text does not match the pattern of the --filter-text=pattern option. See Fixed date option --filter-text=pattern.

-c|C[-]

--today

--list-of-fixed-dates[=short|long]

--descending-fixed-dates[=short|long]

Activate the fixed date function and display fixed date messages, if any.

-c

--today

--list-of-fixed-dates=short

Activate fixed date function (use standard resource file implicitly) and list all dates related to the actual system date (≡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. See Error Code 1.

-c-

--descending-fixed-dates=short

Activate fixed date function (use standard resource file implicitly) and list all dates related to the actual system date (≡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. See Error Code 1.

-C

--list-of-fixed-dates=long

Activate fixed date function (use standard resource file implicitly) and list all dates related to the actual system date (≡today), sorted in ascending order. If no fixed dates related to the current day are found, an “empty” fixed date message is displayed which is only consisting of the date.

-C-

--descending-fixed-dates=long

Activate fixed date function (use standard resource file implicitly) and list all dates related to the actual system date (≡today), sorted in descending order. If no fixed dates related to the current day are found, an “empty” fixed date message is displayed which is only consisting of the date.

-f|F name[+…]

--resource-file=name[+…]

Activate fixed date function and use file 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 (≡today) is used for the fixed date period. If the option letter f of the short-style option is used and no dates related to the fixed date period are found in name, no fixed date messages are displayed and the program is terminated with an error code. See Error Code 1. If the option letter F of the short-style option is used and no dates related to the fixed date period are found in name, an “empty” fixed date message is displayed which is only consisting of the date.

You can use more than one resource file name by connecting them with a ‘+’ character, e.g.:

--resource-file=./foo+xyz+/data/bar+$HOME/.gcalrc resp.,
-f ./foo+xyz+/data/bar+$HOME/.gcalrc

respects all files given in the preceding argument by using a special file search mechanism. See File searching mechanism, for more details. Use /dev/null to avoid the use of the standard resource file, useful for creating empty fixed date lists. If a single ‘-’ character is given as file name, like --resource-file=./foo+-+xyz or -F-, but not -F -, Gcal reads and processes all input received from the standard input channel.

You may depreciate the special meaning of the ‘+’ separator character —in case this character itself is needed— by placing a ‘\’ (backslash) character before it, e.g. ‘\+’. If you need the ‘\+’ characters themselves, you have to protect the ‘\’ (backslash) character by another ‘\’ (backslash) character, e.g. ‘\\+’.

Each time a ‘_’ (underscore) character is found in name, this character is replaced by a real ‘ ’ (space) character.

You may depreciate the special meaning of the ‘_’ (underscore) character —in case this character itself is needed— by placing a ‘\’ (backslash) character before it, e.g. ‘\_’. If you need the ‘\_’ characters themselves, you have to protect the ‘\’ (backslash) character by another ‘\’ (backslash) character, e.g. ‘\\_’.

-# line

--here=line

Activate fixed date function and use the line argument together with the standard resource file respectively additional resource files. The line argument has to be a valid line as it may occur in a Gcal resource file (see Structure of resource file), and is always evaluated last after the processing of all resource files, so dealing with references to exported local date or text variables is enabled. 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 (≡today) is used for the fixed date period. If no dates related to the fixed date period are found in the line, no fixed date messages are displayed and the program is terminated with an error code. See Error Code 1.

For example, the call:

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

causes the implicit processing of the standard resource file just before the further resource file line ‘0*d1su#99su.7 ^%Z’ and following ‘#include <foo>’ are processed, and that as if these lines were a physical part of the standard resource file.

Each time a ‘_’ (underscore) character is found in line, this character is replaced by a real ‘ ’ (space) character.

You may depreciate the special meaning of the ‘_’ (underscore) character —in case this character itself is needed— by placing a ‘\’ (backslash) character before it, e.g. ‘\_’. If you need the ‘\_’ characters themselves, you have to protect the ‘\’ (backslash) character by another ‘\’ (backslash) character, e.g. ‘\\_’.

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

-C
-F foo.bar
-CeT
-c-aW+
-CeaxY-
-c-M

Gcal displays fixed date messages for 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:

First step: Representation-of-text-modifier

a, A, e|E, J, k, o, Q, U, x, z, Z

Second step: Period-of-fixed-dates-modifier

d, l, t|T, w|W|m|M|y|Y[+|-], n+|-, nd, nw, *dn[www], *wn[www], @e|t|dvar[[+|-]n], @e|t|dvar[+|-]nwww, mmdd, mmwwwn

If you want to operate with the preceding modifiers, an explicit -c|C[-] short-style option must be leading on the one hand, e.g.:

-c-t
-cw-
-CZdekloQUzJaxA12+

and only one period defining fixed date period modifier may be given²⁶.

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 -c|C[-], -f|F name[+…] or -# line²⁷ must be given like:

-c -t
-w- -c
-a -Ad -e -kloQUxz -C12+
-F foo.bar -dJZA -l*d10
--here="; Comment" -dZAa

If the modifiers are given as single character options or composed into a single command line word, and one of the t|T|[w|W|m|M|y|Y[+|-]] modifiers is used²⁸, it is unnecessary to give a -c|C[-] respectively -f|F name[+…] short-style option²⁹ to activate the fixed date function of Gcal, because it is triggered implicitly by means of these modifiers / alias names.

See Coding Scheme, whose tables explain the relations between the date part (yyyy…) of a resource file line and the modifiers, the short-style option -c|C[] —which is used for enabling the fixed date feature— respectively the long-style option --period-of-fixed-dates=argument may have, i.e. they point out all possible correspondences. This is necessary because Gcal does not respect all entries found in a resource file if a fixed date argument is given, it respects only those entries which have a definite relation to the fixed date argument to avoid the output of redundant information!

Fixed date text modifiers and options:

--biorhythm-axis=number

The width of the biorhythm text graphics —which can be created by means of the biorhythm text graphics %;[date] special text— is changed to number characters for each axis of the bar. The number argument must be an integer value between 1…100, the default number of characters is 20. If the 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 number argument of 19 is internally reduced to 10.

For example:

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

See Biorhythm %?[date] special texts, for more details.

--moonimage-lines=number

The height of the Moon phase text graphics —which can be created by means of the Moon phase text graphics %Z[date] special text— is changed to number lines. The number argument must be an integer value between 6…30, the default number of lines is 12.

For example:

$ gcal -f/dev/null -#0*d1#999_%Z__%O %19950407 -x --moon=8 -| -| Fri, Apr < 7th>1995: ( @@@@@ -| ( @@@@@@@@ -| ( @@@@@@@@@@@ -| ( @@@@@@@@@@@@ -| ( @@@@@@@@@@@@ -| ( @@@@@@@@@@@ -| ( @@@@@@@@@@ -| ( @@@@@@@ 42%+

See Moon phase %[format]?[date] special texts, for more details.

a

--include-resource-file-name

Extend fixed date text by the name of the resource file and the line number which the fixed date text comes from, e.g.:

Mon, Jan   1st 1995: (`Eternal holiday list'#00003) New Year's day
Mon, Jan   1st 1995: (.gcalrc#00987) No fixed dates
…

A

--alternative-format

Instead of using the standard list format, e.g.:

Mon, Jan   1st 1995: New Year's day
Mon, Jan   1st 1995: No fixed dates
…

Gcal uses the alternative list format, e.g.:

Mon, Jan   1st 1995:
New Year's day
No fixed dates
…

e

--include-holidays=long

Enable inclusion of all built-in eternal holiday dates. This includes legal holidays and memorial days.

E

--include-holidays=short

Enable inclusion of those built-in eternal holiday dates which are legal holidays only.

g[text]

--grouping-text[=text]

Group fixed dates by day by using the text separator. If text is not given, the built-in text³⁰ is used for grouping, e.g.:

$ gcal -Cxw -cg -| -| Sun, Nov 6th 1994: Text 1 -| Sun, Nov 6th 1994: Text 2 -| -| Mon, Nov 7th 1994: Text 3 -| -| Tue, Nov 8th 1994: Text 4 … $ gcal -Cxw -g'-A_user\_defined-~-grouping text-' -| -| Sun, Nov 6th 1994: Text 1 -| Sun, Nov 6th 1994: Text 2 -| -A user_defined- -| -grouping text- -| Mon, Nov 7th 1994: Text 3 -| -A user_defined- -| -grouping text- -| Tue, Nov 8th 1994: Text 4 …

The text may contain references to global date and text variables (see Fixed date option --date-variable=argument, and Fixed date option --date-variable=argument). Furthermore, all special texts which cause a text replacement may be used in the text (see %?… special texts for text replacement).

Each time a ‘~’ (tilde) or ‘^’ (caret) character is found in text, this character is replaced by a real ‘\n’ (newline) character.

You may depreciate the special meaning of the ‘~’ (tilde) character —in case this character itself is needed— by placing a ‘\’ (backslash) character before it, e.g. ‘\~’. If you need the ‘\~’ characters themselves, you have to protect the ‘\’ (backslash) character by another ‘\’ (backslash) character, e.g. ‘\\_’. All above mentioned facts are also valid for the ‘^’ (caret) character.

Each time a ‘_’ (underscore) character is found in text, this character is replaced by a real ‘ ’ (space) character.

You may depreciate the special meaning of the ‘_’ (underscore) character —in case this character itself is needed— by placing a ‘\’ (backslash) character before it, e.g. ‘\_’. If you need the ‘\_’ characters themselves, you have to protect the ‘\’ (backslash) character by another ‘\’ (backslash) character, e.g. ‘\\_’.

k

--include-week-number

The leading date of a fixed date message is either extended by the ISO week number or the standard week number. See Calendar option --starting-day=argument, Calendar option --iso-week-number=yes|no, and Aspects in Internationalization, for further details.

o

--omit-multiple-date-part

Omit displaying the leading date of a fixed date message in case more than one message refers to that date³¹, e.g.:

$ gcal -cxo -| -| Sun, Nov 6th 1994: Text 1 -| Text 2 …

Q

--suppress-fixed-dates-list-separator

Suppress displaying of the blank line which is always leading a fixed date list. For example, to cause Gcal to print only the number of days between 1st January 1970 and 1st January 1980, you can call the program like this:

$ gcal -f /dev/null -QUx %19800101 -#0_%j-2440588 -| 3652

U

--suppress-date-part

Suppress displaying the leading date of a fixed date message, e.g.:

$ gcal -cxU -| -| Text 1 -| Text 2 …

J

--suppress-text-part

Suppress displaying the text part of a fixed date message, e.g.:

$ gcal -cxJ -| -| Sun, Nov 6th 1994: -| Sun, Nov 6th 1994: …

x

--exclude-fixed-dates-list-title

Suppress the title text line of the fixed date list.

--heading-text=text

Changes the title text line of the fixed date list. Instead of displaying the default ‘Fixed date list:’ text, any other text can be used as heading text of the fixed date list, e.g.:

$ gcal -cUJ --heading-text=Hello,_it_is_%K_,~%t__o'clock -| -| Hello, it is Sunday, -| 14:32 o'clock -| -| Sun, Nov 6th 1994: …

The text may contain references to global date and text variables (see Fixed date option --date-variable=argument, and Fixed date option --date-variable=argument). Furthermore, all special texts which cause a text replacement may be used in the text (see %?… special texts for text replacement).

Each time a ‘~’ (tilde) or ‘^’ (caret) character is found in text, this character is replaced by a real ‘\n’ (newline) character.

You may depreciate the special meaning of the ‘~’ (tilde) character —in case this character itself is needed— by placing a ‘\’ (backslash) character before it, e.g. ‘\~’. If you need the ‘\~’ characters themselves, you have to protect the ‘\’ (backslash) character by another ‘\’ (backslash) character, e.g. ‘\\_’. All above mentioned facts are also valid for the ‘^’ (caret) character.

Each time a ‘_’ (underscore) character is found in text, this character is replaced by a real ‘ ’ (space) character.

You may depreciate the special meaning of the ‘_’ (underscore) character —in case this character itself is needed— by placing a ‘\’ (backslash) character before it, e.g. ‘\_’. If you need the ‘\_’ characters themselves, you have to protect the ‘\’ (backslash) character by another ‘\’ (backslash) character, e.g. ‘\\_’.

z

--include-consecutive-number

Display consecutive numbers of fixed date messages.

Z

--zero-dates-only

Display only those dates, for which fixed dates do not exist, i.e. all “empty” fixed dates only consisting of the date.

Fixed date period modifiers and options:

--leap-day=february|march

The leap day³² is observed in non-leap years.

--leap-day=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.

--leap-day=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.

d

--include-today

If lists of periods are generated, include the actual date into the list. See Fixed date option --list-mode, how to create a list of periods.

l

--list-mode

Generate a list of periods instead of a single period.

Please note:
The following examples assumes the actual system date is the 17th February of any year (00000217), weeks start on Mondays and ISO week numbers are used!

--period-of-fixed-dates=argument

nd

*dn

Single date of absolute day n ≡ ‘1…365|366|999’ of the actual year; the intensity level is the same as the simple -c option. If the value 999 for n is given, the last day of the year (31st December) is assumed.

• E.g. ‘gcal -c10d’ respectively ‘gcal --period-of-fixed-dates=10d’ or ‘gcal -c*d10’ respectively ‘gcal --period-of-fixed-dates=*d10’ displays all fixed dates which occur on the 10th day of the year.

lnd

l*dn

List dates starting yesterday or tomorrow (depending on the given day number n) and ending on the n’th absolute day of the actual year; the intensity level is the same as the -cy option.

• E.g. ‘gcal -cl10d’ respectively ‘gcal -cl*d10’ displays a list of all fixed dates which start on the 10th day of year and end on the 16th February.

n+|-

Single date of day actual day ‘+/-’ n days of the actual year; the intensity level is the same as the simple -c option.

• E.g. ‘gcal -c10+’ displays all fixed dates which occur 10 days after the 17th February (today).
• E.g. ‘gcal -c10-’ displays all fixed dates which occur 10 days before the 17th February (today).

ln+|-

List dates starting yesterday ‘-’ or tomorrow ‘+’ and ending on actual day ‘+/-’ n days of the actual year; the intensity level is the same as the -cy option.

• E.g. ‘gcal -cl10+’ displays a list of all fixed dates which start on the 18th February and end 10 days after.
• E.g. ‘gcal -cl10-’ displays a list of all fixed dates which start 10 days before the 16th February and end on the 16th February.

nw

Single dates of week number n ≡ ‘0|1…52|53|99’ of the actual year; the intensity level is the same as the -cw option. See Calendar option --starting-day=argument, Calendar option --iso-week-number=yes|no, and Aspects in Internationalization, for more details.

• E.g. ‘gcal -c0w’ displays all fixed dates which occur in the 53rd week of the previous year, in case the previous year has a 53rd week. If the previous year has no 53rd week, all fixed dates occurring in the 1st week of the actual year are displayed.
• E.g. ‘gcal -c6w’ displays all fixed dates which occur in the 6th week of year.
• E.g. ‘gcal -c52w’ displays all fixed dates which occur in the 52nd week of year.
• E.g. ‘gcal -c53w’ displays all fixed dates which occur in the 53rd week of the actual year, in case the actual year has a 53rd week. If the actual year has no 53rd week, no fixed date messages are displayed and the program is terminated with an error code. See Error Code 126.
• E.g. ‘gcal -c99w’ displays all fixed dates which occur in the last week of the actual year, i.e. either the 52nd or the 53rd week.

lnw

List dates starting yesterday or tomorrow (depending on the given week number n) and ending on the first respectively last day of given week number n ≡ ‘0|1…52|53|99’ of the actual year; the intensity level is the same as the -cy option. See Calendar option --starting-day=argument, Calendar option --iso-week-number=yes|no, and Aspects in Internationalization, for further details.

• E.g. ‘gcal -cl12w’ displays a list of all fixed dates which start on the 18th February and end on the last day of the 12th week.
• E.g. ‘gcal -cl3w’ displays a list of all fixed dates which start on the first day of the 3rd week and end on the 16th February.

mmdd

Single date of day dd in month mm of the actual year; the intensity level is the same as the simple -c option.

• E.g. ‘gcal -c0225’ displays all fixed dates which occur on the 25th February.

lmmdd

List dates starting yesterday or tomorrow (depending on the value given in mmdd) and ending on day dd of month mm of the actual year; the intensity level is the same as the -cy option.

• E.g. ‘gcal -cl0225’ displays a list of all fixed dates which start on the 18th February and end on the 25th February.
• E.g. ‘gcal -cl0109’ displays a list of all fixed dates which start on the 9th January and end on the 16th February.

mmwwwn

Single date of n’th ≡ ‘1…5|9’ weekday dd|www in month mm of the actual year; the intensity level is the same as the simple -c option.

• E.g. ‘gcal -c01mon3’ displays all fixed dates which occur on the 3rd Monday in January.
• E.g. ‘gcal -c02fri9’ displays all fixed dates which occur on the last Friday in February.

lmmwwwn

List dates starting yesterday or tomorrow (depending on the value given in mmwwwn) and ending on n’th ≡ ‘1…5|9’ weekday dd of month mm of the actual year; the intensity level is the same as the -cy option.

• E.g. ‘gcal -cl01mon3’ displays a list of all fixed dates which start on the 3rd Monday in January and end on the 16th February.
• E.g. ‘gcal -cl02fri9’ displays a list of all fixed dates which start on the 18th February and end on the last Friday in February.

*dnwww

Single date of n’th ≡ ‘1…51|52|53|99’ weekday www of the actual year; the intensity level is the same as the simple -c option.

• E.g. ‘gcal -c*d16sun’ displays all fixed dates which occur on the 16th Sunday of the actual year.
• E.g. ‘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. See Error Code 126.
• E.g. ‘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. See Error Code 126.
• E.g. ‘gcal -c*d99sun’ displays all fixed dates which occur on the last Sunday³³ of the actual year.

l*dnwww

List dates starting yesterday or tomorrow (depending on the value given in n) and ending on n’th ≡ ‘1…51|52|53|99’ weekday www of the actual year; the intensity level is the same as the -cy option.

• E.g. ‘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.
• E.g. ‘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. See Error Code 126.
• E.g. ‘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. See Error Code 126.
• E.g. ‘gcal -cl*d99sun’ displays a list of all fixed dates which start on the 18th February and end on the last Sunday³⁴ of the actual year.

*wn[www]

Single date of weekday www of n’th ≡ ‘0|1…52|53|99’ week of the actual year; the intensity level is the same as the simple -c option. If no weekday www is given, the starting day of the week is assumed for the weekday www. See Calendar option --starting-day=argument, Calendar option --iso-week-number=yes|no, and Aspects in Internationalization, for more details.

• E.g. ‘gcal -c*w0sun’ displays all fixed dates which occur on the Sunday of the 52nd respectively 53rd week of the previous year. In case such a Sunday does not exist, no fixed date messages are displayed and the program is terminated with an error code. See Error Code 126.
• E.g. ‘gcal -c*w16sun’ displays all fixed dates which occur on the Sunday of the 16th week of the actual year.
• E.g. ‘gcal -c*w52sun’ displays all fixed dates which occur on the Sunday of the 52nd week of the actual year. If the actual year has no Sunday of the 52nd week, no fixed date messages are displayed and the program is terminated with an error code. See Error Code 126.
• E.g. ‘gcal -c*w53sun’ displays all fixed dates which occur on the Sunday of the 53rd week of the actual year. If the actual year has no Sunday of the 53rd week, no fixed date messages are displayed and the program is terminated with an error code. See Error Code 126.
• E.g. ‘gcal -c*w99sun’ displays all fixed dates which occur on the last Sunday³⁵ of the actual year.

l*wn[www]

List dates starting yesterday or tomorrow (depending on the value given in n) and ending on weekday www of n’th ≡ ‘0|1…52|53|99’ week of the actual year; the intensity level is the same as the -cy option. If no weekday www is given, the starting day of the week is assumed for the weekday www. See Calendar option --starting-day=argument, Calendar option --iso-week-number=yes|no, and Aspects in Internationalization, for further details.

• E.g. ‘gcal -cl*w0sun’ displays a list of all fixed dates which start on the Sunday of the 52nd respectively 53rd week of the previous year and end on the 16th February. In case such a Sunday does not exist, no fixed date messages are displayed and the program is terminated with an error code. See Error Code 126.
• E.g. ‘gcal -cl*w16sun’ displays a list of all fixed dates which start on the 18th February and end on the Sunday of the 16th week of the actual year.
• E.g. ‘gcal -cl*w52sun’ displays a list of all fixed dates which start on the 18th February and end on the Sunday of the 52nd week of the actual year. If the actual year has no Sunday of the 52nd week, no fixed date messages are displayed and the program is terminated with an error code. See Error Code 126.
• E.g. ‘gcal -cl*w53sun’ displays a list of all fixed dates which start on the 18th February and end on the Sunday of the 53rd week of the actual year. If the actual year has no Sunday of the 53rd week, no fixed date messages are displayed and the program is terminated with an error code. See Error Code 126.
• E.g. ‘gcal -cl*w99sun’ displays a list of all fixed dates which start on the 18th February and end on the last Sunday³⁶ of the actual year.

@e[[+|-]n]

Single date of day n relative to the Easter Sunday’s date of the actual year; the intensity level is the same as the simple -c option.

• E.g. ‘gcal -c@e’ displays all fixed dates which occur on the Easter Sunday’s date.
• E.g. ‘gcal -c@e10’ respectively ‘gcal -c@e+10’ displays all fixed dates which occur 10 days after the Easter Sunday’s date.
• E.g. ‘gcal -c@e-10’ displays all fixed dates which occur 10 days before the Easter Sunday’s date.

l@e[[+|-]n]

List dates starting yesterday or tomorrow (depending on the value given in n) and ending on n’th day relative to the Easter Sunday’s date of the actual year; the intensity level is the same as the -cy option.

• E.g. ‘gcal -cl@e’ displays a list of all fixed dates which start on the 18th February and end on the Easter Sunday’s date.
• E.g. ‘gcal -cl@e10’ respectively ‘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.
• E.g. ‘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.

@e[+|-]nwww

Single date of n’th weekday www relative to the Easter Sunday’s date of the actual year; the intensity level is the same as the simple -c option.

• E.g. ‘gcal -c@e3fri’ respectively ‘gcal -c@e+3fri’ displays all fixed dates which occur on the 3rd Friday after the Easter Sunday’s date.
• E.g. ‘gcal -c@e-3fri’ displays all fixed dates which occur on the 3rd Friday before the Easter Sunday’s date.

l@e[+|-]nwww

List dates starting yesterday or tomorrow (depending on the value given in n) and ending on n’th weekday www relative to the Easter Sunday’s date of the actual year; the intensity level is the same as the -cy option.

• E.g. ‘gcal -cl@e3fri’ respectively ‘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.
• E.g. ‘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.

@t[[+|-]n]

Single date of day n relative to today’s date of the actual year; the intensity level is the same as the simple -c option.

• E.g. ‘gcal -c@t’ displays all fixed dates which occur on today’s date (≡ ‘gcal -c’).
• E.g. ‘gcal -c@t10’ respectively ‘gcal -c@t+10’ displays all fixed dates which occur 10 days after today’s date (≡ ‘gcal -c10+’).
• E.g. ‘gcal -c@t-10’ displays all fixed dates which occur 10 days before today’s date (≡ ‘gcal -c10-’).

l@t[[+|-]n]

List dates starting yesterday or tomorrow (depending on the value given in n) and ending on n’th day relative to today’s date of the actual year; the intensity level is the same as the -cy option.

• E.g. ‘gcal -cl@t’ displays nothing.
• E.g. ‘gcal -cl@t10’ respectively ‘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 (≡ ‘gcal -cl10+’).
• E.g. ‘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 (≡ ‘gcal -cl10-’).

@t[+|-]nwww

Single date of n’th weekday www relative to today’s date of the actual year; the intensity level is the same as the simple -c option.

• E.g. ‘gcal -c@t3fri’ respectively ‘gcal -c@t+3fri’ displays all fixed dates which occur on the 3rd Friday after today’s date.
• E.g. ‘gcal -c@t-3fri’ displays all fixed dates which occur on the 3rd Friday before today’s date.

l@t[+|-]nwww

List dates starting yesterday or tomorrow (depending on the value given in n) and ending on n’th weekday www relative to today’s date of the actual year; the intensity level is the same as the -cy option.

• E.g. ‘gcal -cl@t3fri’ respectively ‘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.
• E.g. ‘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.

@dvar[[+|-]n]

Single date of the day n relative to that date of the actual year, which is referenced by the date variable dvar; the intensity level is the same as the simple -c option.

• E.g. ‘gcal -v a=0422 -c@a’ displays all fixed dates which occur on the 22nd April.
• E.g. ‘gcal -v a=0422 -c@a10’ respectively ‘gcal -v a=0422 -c@a+10’ displays all fixed dates which occur 10 days after the 22nd April.
• E.g. ‘gcal -v a=0422 -c@a-10’ displays all fixed dates which occur 10 days before the 22nd April.

l@dvar[[+|-]n]

List dates starting yesterday or tomorrow (depending on the value given in n) and ending on the n’th day relative to that date of the actual year, which is referenced by the date variable dvar; the intensity level is the same as the -cy option.

• E.g. ‘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.
• E.g. ‘gcal -v a=0422 -cl@a10’ respectively ‘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.
• E.g. ‘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.

@dvar[+|-]nwww

Single date of the n’th weekday www relative to that date of the actual year, which is referenced by the date variable dvar; the intensity level is the same as the simple -c option.

• E.g. ‘gcal -v a=0122 -c@a2sat’ respectively ‘gcal -v a=0122 -c@a+2sat’ displays all fixed dates which occur on the 2nd Saturday after the 22nd January.
• E.g. ‘gcal -v a=0122 -c@a-2sat’ displays all fixed dates which occur on the 2nd Saturday before the 22nd January.

l@dvar[+|-]nwww

List dates starting yesterday or tomorrow (depending on the value given in n) and ending on the n’th weekday www relative to that date of the actual year, which is referenced by the date variable dvar; the intensity level is the same as the -cy option.

• E.g. ‘gcal -v a=0122 -cl@a2sat’ respectively ‘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.
• E.g. ‘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.

t|T

--tomorrow long-style option

List dates related to tomorrow.

• E.g. ‘gcal -ct’ displays all fixed dates which occur on the 18th February (tomorrow).
• E.g. ‘gcal -cdt’ displays all fixed dates which occur on the 17th February (today) and on the 18th February (tomorrow).

w|W[+|-]

--week long-style option

--end-of-week long-style option

--start-of-week long-style option

Display dates related to the week.
See Calendar option --starting-day=argument.

• w or --week long-style option
  List dates between the starting day of the current week and the last day of the current week
  • - E.g. ‘gcal -cw’ displays all fixed dates which occur in the whole week the 17th February is part of.
• w+ or --end-of-week long-style option
  List dates between the day after the current day of the current week and the last day of the current week.
  • - E.g. ‘gcal -cw+’ displays all fixed dates which start on the 18th February (tomorrow) and end on the last day of the week.
  • - E.g. ‘gcal -cdw+’ displays all fixed dates which start on the 17th February (today) and end on the last day of the week.
• w- or --start-of-week long-style option
  List dates between the starting day of the current week and the day before the current day of the current week
  • - E.g. ‘gcal -cw-’ displays all fixed dates which start on the first day of the week and end on the 16th February (yesterday).
  • - E.g. ‘gcal -cdw-’ displays all fixed dates which start on the first day of the week and end on the 17th February (today).

m|M[+|-]

--month long-style option

--end-of-month long-style option

--start-of-month long-style option

Display dates related to the month.

• m or --month long-style option
  List dates between the first day of the current month and the last day of the current month.
  • - E.g. ‘gcal -cm’ displays all fixed dates which occur in the whole month of February.
• m+ or --end-of-month long-style option
  List dates between the day after the current day of the current month and the last day of the current month.
  • - E.g. ‘gcal -cm+’ displays all fixed dates which start on the 18th February (tomorrow) and end on the last day of the month February.
  • - E.g. ‘gcal -cdm+’ displays all fixed dates which start on the 17th February (today) and end on the last day of the month February.
• m- or --start-of-month long-style option
  List dates between the first day of the current month and the day before the current day of the current month.
  • - E.g. ‘gcal -cm-’ displays all fixed dates which start on the first day of the month February and end on the 16th February (yesterday).
  • - E.g. ‘gcal -cdm-’ displays all fixed dates which start on the first day of the month February and end on the 17th February (today).

y|Y[+|-]

--year long-style option

--end-of-year long-style option

--start-of-year long-style option

Display dates related to the year.

• y or --year long-style option
  List dates between the first day of the current year and the last day of the current year.
  • - E.g. ‘gcal -cy’ displays all fixed dates which occur in the whole year.
• y+ or --end-of-year long-style option
  List dates between the day after the current day of the current year and the last day of the current year.
  • - E.g. ‘gcal -cy+’ displays all fixed dates which start on the 18th February (tomorrow) and end on the last day of the year.
  • - E.g. ‘gcal -cdy+’ displays all fixed dates which start on the 17th February (today) and end on the last day of the year.
• y- or --start-of-year long-style option
  List dates between the first day of the current year and the day before the current day of the current year.
  • - E.g. ‘gcal -cy-’ displays all fixed dates which start on the first day of the year and end on the 16th February (yesterday).
  • - E.g. ‘gcal -cdy-’ displays all fixed dates which start on the first day of the year and end on the 17th February (today).

3.1.2 Response file

If a @file command line argument is given, a response file by the name of file will be used, i.e. options and commands are preloaded from that file. A response file may contain options and commands —which are preloaded by Gcal—, but no references to further response files. If such references to further response files are found, they are ignored. See Global option --response-file=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 no standard response file is respected. See 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.

Each option and command must be on a single line, i.e. separated by a real ‘\n’ (newline) character. A line beginning with a ‘;’ (semicolon) character in the response file is treated as a remark and will not be used by Gcal (see Comment line).

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

For example:

1. Contents of response file file:

   Line     Text
   1        -j
   2        -Cw
   EOF
   
   

   $ gcal -i -b 3 @file -s 3 1994 → gcal -i -b 3 -j -Cw -s 3 1994

2. Contents of response file file:

   Line     Text
   1        -j
   2        -Cw
   3        may 1992
   EOF
   
   

   $ gcal -i -b 3 @file -s 3 1994 → gcal -i -b 3 -j -Cw may

3. Contents of response file file:

   Line     Text
   1        -j
   2        -Cw
   3        may
   4        1992
   EOF
   
   

   $ gcal -i -b 3 @file -s 3 1994 → gcal -i -b 3 -j -Cw may 1992

3.1.3 Actual date modifier

It is allowed to use that date —instead of the actual system date— which is defined by the %date command line argument. This means, fixed dates can be checked for any year and are respected in the same way, as if they would be fixed dates of the actual year.

The date must be denoted in one of these formats:

• yyyy[mm[dd|wwwn]]
• yyyy*d|wn[www]
• yyyy@e|t|dvar[[+|-]n[www]]
• month name[dd]
• weekday name[n]
• dd

Some examples to this:

Please note:
The following examples assumes the actual system date is Wednesday, the 17th February 1993 (19930217), weeks start on Mondays and ISO week numbers are used!

The yyyy[mm[dd|wwwn]] format:

• ‘gcal %1994’ (≡ yyyy)
  The actual date is set to the date 17th February 1994 ⇒ 19940217.
• ‘gcal %1994Mar’
• ‘gcal %19943’
• ‘gcal %199403’ (≡ yyyymm)
  The actual date is set to the date 17th March 1994 ⇒ 19940317.
• ‘gcal %1994Mar3’
• ‘gcal %1994033’
• ‘gcal %19940303’ (≡ yyyymmdd)
  The actual date is set to the date 3rd March 1994 ⇒ 19940303.
• ‘gcal %1994MarWed3’
• ‘gcal %199403wed3’ (≡ yyyymmwwwn)
  The actual date is set to the date 3rd Wednesday in March 1994 (n ≡ ‘1…5|9’) ⇒ 19940316.
• ‘gcal %0’
• ‘gcal %00’
• ‘gcal %000’
• ‘gcal %0000’ (≡ yyyy)
  The actual date remains unchanged ⇒ 19930217.
• ‘gcal %0000Mar’
• ‘gcal %00003’
• ‘gcal %000003’ (≡ yyyymm)
  The actual date is set to the date 17th March 1993 ⇒ 19930317.
• ‘gcal %0000Mar3’
• ‘gcal %0000033’
• ‘gcal %00000303’ (≡ yyyymmdd)
  The actual date is set to the date 3rd March 1993 ⇒ 19930303.
• ‘gcal %0000MarWed3’
• ‘gcal %000003wed3’ (≡ yyyymmwwwn)
  The actual date is set to the date 3rd Wednesday in March 1993 (n ≡ ‘1…5|9’) ⇒ 19930317.

The yyyy*d|wn[www] format:

• ‘gcal %1994*d10’ (≡ yyyy*dn)
  The actual date is set to the date 10th absolute day in 1994 (n ≡ ‘1…365|366|999’) ⇒ 19940110.
• ‘gcal %1994*d10sun’ (≡ yyyy*dnwww)
  The actual date is set to the date 10th Sunday in 1994 (n ≡ ‘1…51|52|53|99’) ⇒ 19940306.
• ‘gcal %0*d10’ (≡ yyyy*dn)
  The actual date is set to the date 10th absolute day in 1993 ⇒ 19930110.
• ‘gcal %0*d10sun’ (≡ yyyy*dnwww)
  The actual date is set to the date 10th Sunday in 1993 ⇒ 19930307.
• ‘gcal %1994*w10’ (≡ yyyy*wn)
  The actual date is set to the date Monday of the 10th week in 1994
  (n ≡ ‘0|1…52|53|99’) ⇒ 19940307.
• ‘gcal %1994*w10sun’ (≡ yyyy*wnwww)
  The actual date is set to the date Sunday of the 10th week in 1994 ⇒ 19940313.
• ‘gcal %0*w10’ (≡ yyyy*wn)
  The actual date is set to the date Monday of the 10th week in 1993 ⇒ 19930308.
• ‘gcal %0*w10sun’ (≡ yyyy*wnwww)
  The actual date is set to the date Sunday of the 10th week in 1993 ⇒ 19930314.

The yyyy@e|t|dvar[[+|-]n[www]] format:

• ‘gcal %1994@e’ (≡ yyyy@e)
  The actual date is set to the date Easter Sunday 1994 ⇒ 19940403.
• ‘gcal %1994@e10’
• ‘gcal %1994@e+10’ (≡ yyyy@e[+]n)
  The actual date is set to the date 10 days after Easter Sunday 1994 ⇒ 19940413.
• ‘gcal %1994@e-10’ (≡ yyyy@e-n)
  The actual date is set to the date 10 days before Easter Sunday 1994 ⇒ 19940324.
• ‘gcal %0@e’
• ‘gcal %00@e’
• ‘gcal %000@e’
• ‘gcal %0000@e’ (≡ yyyy@e)
  The actual date is set to the date Easter Sunday 1993 ⇒ 19930411.
• ‘gcal %0@e10’
• ‘gcal %0@e+10’ (≡ yyyy@e[|]n)
  The actual date is set to the date 10 days after Easter Sunday 1993 ⇒ 19930421.
• ‘gcal %0@e-10’ (≡ yyyy@e-n)
  The actual date is set to the date 10 days before Easter Sunday 1993 ⇒ 19930401.
• ‘gcal %1994@e3Wed’
• ‘gcal %1994@e+3Wed’ (≡ yyyy@e[+]nwww)
  The actual date is set to the date 3rd Wednesday after Easter Sunday 1994 ⇒ 19940420.
• ‘gcal %1994@e-3wed’ (≡ yyyy@e-nwww)
  The actual date is set to the date 3rd Wednesday before Easter Sunday 1994 ⇒ 19940316.
• ‘gcal %0@e3wed’
• ‘gcal %0@e+3wed’ (≡ yyyy@e[+]nwww)
  The actual date is set to the date 3rd Wednesday after Easter Sunday 1993 ⇒ 19930428.
• ‘gcal %0@e-3we’ (≡ yyyy@e-nwww)
  The actual date is set to the date 3rd Wednesday before Easter Sunday 1993 ⇒ 19930324.
• ‘gcal %1994@t’ (≡ yyyy@t)
  The actual date is set to today’s date in 1994 ⇒ 199400217.
• ‘gcal %1994@t10’
• ‘gcal %1994@t+10’ (≡ yyyy@t[+]n)
  The actual date is set to the date 10 days after today’s date in 1994 ⇒ 19940227.
• ‘gcal %1994@t-10’ (≡ yyyy@e-n)
  The actual date is set to the date 10 days before today’s date in 1994 ⇒ 19940207.
• ‘gcal %0@t’
• ‘gcal %00@t’
• ‘gcal %000@t’
• ‘gcal %0000@t’ (≡ yyyy@t)
  The actual date is set to today’s date ⇒ 19930217.
• ‘gcal %0@t10’
• ‘gcal %0@t+10’ (≡ yyyy@t[|]n)
  The actual date is set to the date 10 days after today’s date ⇒ 19930227.
• ‘gcal %0@t-10’ (≡ yyyy@t-n)
  The actual date is set to the date 10 days before today’s date ⇒ 19930207.
• ‘gcal %1994@t3Wed’
• ‘gcal %1994@t+3Wed’ (≡ yyyy@t[+]nwww)
  The actual date is set to the date 3rd Wednesday after today’s date in 1994 ⇒ 19940309.
• ‘gcal %1994@t-3wed’ (≡ yyyy@t-nwww)
  The actual date is set to the date 3rd Wednesday before today’s date in 1994 ⇒ 19940302.
• ‘gcal %0@t3wed’
• ‘gcal %0@t+3wed’ (≡ yyyy@t[+]nwww)
  The actual date is set to the date 3rd Wednesday after today’s date ⇒ 19930310.
• ‘gcal %0@t-3we’ (≡ yyyy@t-nwww)
  The actual date is set to the date 3rd Wednesday before today’s date ⇒ 19930127.
• ‘gcal -v a=0303 %1994@a’ (≡ yyyy@dvar)
  The actual date is set to the date 3rd March 1994 ⇒ 19940303.
• ‘gcal -v a=0303 %1994@a10’
• ‘gcal -v a=0303 %1994@a+10’ (≡ yyyy@dvar[+]n)
  The actual date is set to the date 10 days after 3rd March 1994 ⇒ 19940313.
• ‘gcal -v a=0303 %1994@a-10’ (≡ yyyy@dvar-n)
  The actual date is set to the date 10 days before 3rd March 1994 ⇒ 19940221.
• ‘gcal -v a=0303 %0@a’ (≡ yyyy@dvar)
  The actual date is set to the date 3rd March 1993 ⇒ 19930303.
• ‘gcal -v a=0303 %0@a10’
• ‘gcal -v a=0303 %0@a+10’ (≡ yyyy@dvar[+]n)
  The actual date is set to the date 10 days after 3rd March 1993 ⇒ 19930313.
• ‘gcal -v a=0303 %0@a-10’ (≡ yyyy@dvar-n)
  The actual date is set to the date 10 days before 3rd March 1993 ⇒ 19930221.
• ‘gcal -v a=0303 %1994@a3wed’
• ‘gcal -v a=0303 %1994@a+3wed’ (≡ yyyy@dvar[+]nwww)
  The actual date is set to the date 3rd Wednesday after 3rd March 1994 ⇒ 19940323.
• ‘gcal -v a=0303 %1994@a-3wed’ (≡ yyyy@dvar-nwww)
  The actual date is set to the date 3rd Wednesday before 3rd March 1994 ⇒ 19940216.
• ‘gcal -v a=0303 %0@a3wed’
• ‘gcal -v a=0303 %0@a+3wed’ (≡ yyyy@dvar[+]nwww)
  The actual date is set to the date 3rd Wednesday after 3rd March 1993 ⇒ 19930324.
• ‘gcal -v a=0303 %0@a-3wed’ (≡ yyyy@dvar-nwww)
  The actual date is set to the date 3rd Wednesday before 3rd March 1993 ⇒ 19930210.

The month name[dd] format:

• ‘gcal %April’ (≡ month name)
  The actual date is set to the date 17th April 1993 ⇒ 19930417.
• ‘gcal %april3’
• ‘gcal %april03’ (≡ month name dd)
  The actual date is set to the date 3rd April 1993 ⇒ 19930403.

The weekday name[n] format:

• ‘gcal %Friday’ (≡ weekday name)
  The actual date is set to the date Friday of current week in February 1993 ⇒ 19930219.
• ‘gcal %Friday2’
• ‘gcal %Friday02’ (≡ weekday name n)
  The actual date is set to the date 2nd Friday in February 1993 (n ≡ ‘1…5|9’) ⇒ 19930212.

The dd format:

• ‘gcal %3’
• ‘gcal %03’ (≡ dd)
  The actual date is set to the date 3rd February 1993 ⇒ 19930203.

3.1.4 Commands

The commands control the periods Gcal respects. They can be partitioned into four major classes, namely single commands, special 3-Month mode commands, lists of commands and ranges of commands. Single commands and special 3-Month mode commands only create one calendar sheet, ranges of commands or list of commands create more than one calendar sheet per program 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, mm is either a number, a month name or one of the special 3-Month mode commands ., .., .+ and .-. No lists or ranges of months or years can be created in case a special 3-Month mode command is given.

The range of 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. yyyy is a number. The range of yyyy is valid from 1 to 9999. A range (mm-mm or yyyy+yyyy or …) must consist of two elements. A list (mm,…,mm or yyyy;…;yyyy or …) must contain two elements minimum and may have any number of elements.

Here is a list of all ranges of commands, lists of commands and other command separator characters:

• The ‘-’ character is the range of months separator.
• The ‘,’ character is the list of months separator.
• The ‘+’ character is the range of years separator.
• The ‘;’ character is the list of years separator.
• The ‘/’ character is the month of year separator.
• The ‘:’ character is the fiscal year separator.

3.1.4.1 Single commands

NOTHING

Current month of current year, called single month mode in the further context.

month name

Selected month of current year, e.g.:

gcal may
gcal OCTOBER
gcal ja

yyyy

Selected year, called single year mode in the further context, e.g.:

gcal 1992

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

gcal 1:6

or like this

gcal 6+6

to obtain the year AD 6.

mm yyyy

mm/yyyy

Single month of selected year, e.g.:

gcal 9 1992
gcal 9/1992
gcal Nov 1777
gcal Nov/1777

:

Single fiscal year, starting on the actual month of the actual year and ending on month actual month-1 of the actual year+1, called implicit fiscal year in the further context, e.g.:

gcal :

mm:

Single fiscal year, starting on month mm of the actual year and ending on month mm-1 of the actual year+1, called explicit fiscal year in the further context, e.g.:

gcal 6:
gcal feb:
gcal NOVEMBER:

:yyyy

Single fiscal year, starting on the actual month of year yyyy and ending on month actual month-1 of year yyyy+1, also called explicit fiscal year in the further context, e.g.:

gcal :1999

mm:yyyy

Single fiscal year, starting on month mm of year yyyy and ending at month mm-1 of year yyyy+1, called explicit fiscal year too in the further context, e.g.:

gcal 7:1999
gcal oct:1992
gcal February:1777

3.1.4.2 3-Month mode commands

.

Previous, actual and next month of the current year, e.g.:

gcal .

. yyyy

Previous, actual and next month of selected year, e.g.:

gcal . 1992

..

Actual quarter of the current year, e.g.:

gcal ..

.. yyyy

Actual quarter of selected year, e.g.:

gcal .. 1992

.+

Actual and next two months of the current year, e.g.:

gcal .+

.+ yyyy

Actual and next two months of selected year, e.g.:

gcal .+ 1992

.-

Actual and previous two months of the current year, e.g.:

gcal .-

.- yyyy

Actual and previous two months of selected year, e.g.:

gcal .- 1992

3.1.4.3 Lists of commands

mm,…,mm

List of specified months of the current year, e.g.:

gcal 1,5,12
gcal 3,1,5,3
gcal june,9,jan

mm/yyyy,…,mm/yyyy

List of months in specified year, e.g.:

gcal 1/1992,5,12/2001
gcal june/1991,9/1801,jan

mm,…,mm yyyy

List of specified months of selected year, e.g.:

gcal 3,7 1999
gcal 1,dec,july 1777

yyyy;…;yyyy

List of specified years, e.g.:

gcal 1992;1777;1899

mm:yyyy;…;mm:yyyy

List of specified fiscal years, e.g.:

gcal 7:1999;8:1992;April:3

Other valid lists:

mm,mm/yyyy,…

Mixed list of months consisting of: mm mm/yyyy

gcal 6,8,3/1999,feb/3,january

mm:;mm:yyyy;…

Mixed list of fiscal years of the given / actual year consisting of: mm: :yyyy mm:yyyy yyyy

gcal 3:;1994;february:1999;:1777;JAN:

mm:;mm:;…

List of fiscal years of the actual year consisting of: mm:

gcal 3:;august:;DEC: