This is Info file gcal.info, produced by Makeinfo-1.64 from the input file ./doc/tex/gcal-us.texi. START-INFO-DIR-ENTRY * Gcal: (gcal). The GNU calendar program. END-INFO-DIR-ENTRY This file documents Gcal, a program for printing calendars. Gcal displays a calendar for a month or a year, eternal holiday lists and fixed date warning lists, in many ways. The program correctly omits the dates that were skipped when the current Gregorian calendar replaced the earlier Julian calendar. Copyright (C) 1994, 1995, 1996 Thomas Esken This is the first edition of the Gcal documentation. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Free Software Foundation. Any suggestions, improvements, extensions, bug reports, donations, proposals for contract work, and so forth are welcome! Please send them directly to my Email address. If you like my work, I'd appreciate a postcard from you! \\\_''/' -------------------------oOO (/o-o\) OOo------------------------- Thomas Esken o (. " .) o Internet : Im Hagenfeld 84 \___) ~ (___/ (esken@uni-muenster.de) D-48147 M"unster; GERMANY Phone : +49 251 232585  File: gcal.info, Node: Top, Next: Gcal Introduction, Prev: (dir), Up: (dir) Gcal **** Gcal is a program for printing calendars. Gcal displays a calendar for a month or a year, eternal holiday lists and fixed date warning lists, in many ways. The program correctly omits the dates that were skipped when the current Gregorian calendar replaced the earlier Julian calendar. This is Edition 1.00 of the Gcal documentation, 09 March 1996, for Gcal 1.00. Any suggestions, improvements, extensions, bug reports, donations, proposals for contract work, and so forth are welcome! Please send them directly to my Email address. If you like my work, I'd appreciate a postcard from you! \\\_''/' -------------------------oOO (/o-o\) OOo------------------------- Thomas Esken o (. " .) o Internet : Im Hagenfeld 84 \___) ~ (___/ (esken@uni-muenster.de) D-48147 M"unster; GERMANY Phone : +49 251 232585 * Menu: * Gcal Introduction:: Gcal in brief. * Invoking Gcal:: How to run the `gcal' program. * Eternal holidays:: How to create an Eternal holiday list. * Fixed date warnings:: How to create a Fixed date warning list. Appendices * Todays calendar:: Genesis of the Gregorian calendar. * Meta Symbols:: Meta Symbols used in this document. * Coding scheme:: Coding scheme of date part in resource file. * Environment variables:: Respected Environment variables. * Error codes:: Which Error codes does Gcal return? Indices * Argument Index:: Index of Command line arguments. * Variable Index:: Index of Environment variables. * Concept Index:: Concept Index. -- The Detailed Node Listing -- Invoking Gcal * Command line arguments:: Command line arguments. * The GCAL environment variable:: How to use the `GCAL' environment variable. Command line arguments * Options:: How to use Options. * Response file:: How to use a `@FILE' Response file. * Actual date modifier:: How to use a `%DATE' Actual date modifier. * Commands:: How to use Commands. Options * Common options:: How to use Common options. * Global options:: How to use Global options. * Calendar options:: How to use Calendar options. * Date warning options:: How to use Date warning options. Commands * Single commands:: How to use a Single command. * 3-Month mode commands:: How to use a 3-Month mode command. * Lists of commands:: How to use a List of commands. * Ranges of commands:: How to use a Range of commands. Fixed date warnings * Resource file:: How to use a Resource file. * Resource file examples:: Examples of Resource file entries. Resource file * Structure of resource file:: How to write a Resource file. * Date part of a line:: How to write the Date part. * Further date part attributes:: What are Further date part attributes? * Text part of a line:: How to write the Text part. * Comment line:: What is a Comment line? * Include statements:: What are Include statements. * Special macro texts:: What is a Special macro text. * Date variables:: How Date variables can be used. Further date part attributes * Lists of days:: How Lists of days can be used. * Ranges of days:: How Ranges of days can be used. * Repetition factor of days:: How to use such a factor. * Appearance factor of days:: How to use such a factor. Special macro texts * %s macro text:: How to use the Start of event macro text. * %e macro text:: How to use the End of event macro text. * %b macro text:: How to use the Birthday macro text. * %y macro text:: How to use the Year number macro text. * %m macro text:: How to use the Month number macro text. * %w macro text:: How to use the Week number macro text. * %d macro text:: How to use the Day number macro text. * %j macro text:: How to use the Julian Day number macro text. * %n macro text:: How to use the Textual date macro text. * %t macro text:: How to use the Actual time macro text. * %1 macro text:: How to use the Start of highlighting sequence 1 macro text. * %2 macro text:: How to use the End of highlighting sequence 1 macro text. * %3 macro text:: How to use the Start of highlighting sequence 2 macro text. * %4 macro text:: How to use the End of highlighting sequence 2 macro text. Coding scheme * Coding scheme table 1:: * Coding scheme table 2::  File: gcal.info, Node: Gcal Introduction, Next: Invoking Gcal, Prev: Top, Up: Top Gcal Introduction ***************** Apart from the usual and well known calendar functions like the output of a month or a year calendar sheet, or the output of an eternal holiday list, Gcal offers the facility to display fixed dates on the day of their occurrence and to remind or inform the user about them. So it's imaginable after booting the computer or starting the work session, that the user is informed on screen or by means of electronic mail, about all holidays or appointments, which are observed or scheduled for that day. The period, for which Gcal respects occuring fixed dates, may be freely selected by the user. So it is possible that Gcal displays all fixed dates, which occur on tomorrow's date, the whole week, the whole month or in the whole year. Fixed dates which occur on a selected date of the year and those that occur relative to another given date, are displayed either related to this single date only or in listed manner starting at this date and ending (inclusive or exclusive) at the actual date. There are two ways to display a preview of fixed dates (future years) or retrospective view of fixed dates (past years). On the one hand, Gcal can be started using an option, which sets the system date of the computer to the given date during the time of the program execution with the result, the program assumes the system date is set to this given date and the user can define any needed period, which should be respected, by an option. On the other hand, Gcal can be started with a command, which forces the program to use a different year instead of the actual year, so Gcal will display all occuring fixed dates for this particular year. But this limits the user in that it disables defining any needed period by an option, because the period is always set to the whole year by default. Gcal isn't only able to display fixed dates, which are stored for a concrete date, e.g. `Fixed date on 1'st December 1995', rather than fixed dates occuring periodically again and again. So it's possible to define repeated events like `This fixed date occurs all days in May 1995' or `Every 15'th November in any years'. These fixed date definitions are stored in resource files and whenever Gcal is started, an option to evaluate the necessary resource files can be given. Once the user has set his/her preferred command line arguments for querying the fixed dates data base, it is possible to store them in a response file or shell script file. A response file contains all arguments delivered to Gcal, but unlike a shell script file, such a response file isn't executable; it is only a pool of command line options that can be preloaded if needed. A shell script file can be started and calls Gcal directly with all arguments, which are stored in it and all arguments, which are given further in the command line. A description of all usable command line arguments and their descriptions is listed in the next chapter, which helps one use Gcal in the most efficient and productive way possible.  File: gcal.info, Node: Invoking Gcal, Next: Eternal holidays, Prev: Gcal Introduction, Up: Top Invoking Gcal ************* Gcal is a command line oriented program. It is usually called from a "shell" (this is an operating system program, which interprets and runs given command lines) and processes given arguments, which are options and commands. Options must be given before commands, i.e. you must call Gcal in this way: `gcal [ [Option...] [%Date] [@File...] ] [Command]' If Gcal is started without any options or commands, a calendar of the current month is displayed. If the calendar of a definite year is wanted, the year must be fully specified, e.g. `gcal 94' displays a year calendar of the year 94, not of the year 1994. If two arguments are given in the command part, the *first* argument denotes the month and the *second* argument denotes the year. In case any illegal commands are given running Gcal, the program will use internal defaults. In the English program version, Gcal assumes the Gregorian Reformation have occurred in 1752 on the 3'rd of September, see *Note Todays calendar::, for more details. * Menu: * Command line arguments:: Command line arguments. * The GCAL environment variable:: How to use the `GCAL' Environment variable.  File: gcal.info, Node: Command line arguments, Next: The GCAL environment variable, Prev: Invoking Gcal, Up: Invoking Gcal 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 argument 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 (inclusive `%DATE' and `@FILE') *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 by a `\' character to avoid expansion by the shell. Here is an incomplete list of characters, which must potentially be protected: `(', `)', `<', `>', `[', `]', `{', `}', `\', `|', `$', `@', `!', `&', `~', `"', `'', ``', `;' * Menu: * Options:: How to use Options. * Response file:: How to use a `@FILE' Response file. * Actual date modifier:: How to use a `%DATE' Actual date modifier. * Commands:: How to use Commands.  File: gcal.info, Node: Options, Next: Response file, Prev: Command line arguments, Up: Command line arguments 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. The "global option class" contains options which modify the program output. The options of the "calendar option class" control the calendar layout, and the options of the "date warning option class" control the date warning 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. 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 `='. Gcal processes the GNU long-style options in a special, non-standard way. There are four different types of long-style options: 1. `--foo' Enables option `--foo'. 2. `--foo=BAR' Enables option `--foo' with 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 given list. If there is no argument choosen in this case, the first BAR argument of the argument list is pre-selected by default. 4. `--foo=BAR|...|BAR' Option `--foo' requires exactly one BAR argument, which must be selected from given argument list. Traditional short-style options differ as follows: 1. `-x' Enables option `-x'. 2. `-x BAR' Enables option `-x' with required argument BAR. The BAR argument may be separated by a leading *whitespace* character from the short-style option character `x'. This means 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. * Menu: * Common options:: How to use Common options. * Global options:: How to use Global options. * Calendar options:: How to use Calendar options. * Date warning options:: How to use Date warning options.  File: gcal.info, Node: Common options, Next: Global options, Prev: Options, Up: Options Common options .............. `-?' `-h' `--help' Print a short usage message listing most of all available options, then exit successfully. `-??' `-hh' `--usage[=ARG]' `--long-help[=ARG]' Print an extended usage message listing all available options, then exit successfully. If ARG is given and is a valid long-style option name, an extended help text related to the given long-style option name is displayed only, e.g.: --long-help=long-help displays the extended help text for the long option `--long-help'. If ARG consists only of a 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.  File: gcal.info, Node: Global options, Next: Calendar options, Prev: Common options, Up: Options Global options .............. `-R NAME' `--response-file=ARG' Write contents of environment variable `GCAL' (*note GCAL: Environment variables.), and then arguments of command line (in the given order) to file NAME, i.e. create response file `name'. *Note Response file::, for more details. `-S NAME' `--shell-script=ARG' Write contents of environment variable `GCAL' (*note GCAL: Environment variables.), and then arguments of command line (in the given order) to shell script file NAME, i.e. create file `name'. An automatically created shell script file is executable and calls Gcal directly with the arguments, which are stored in it. You may start the shell script with other command line arguments, which are directed to Gcal too. `--debug[=internal|handled|unhandled|all|abort]' Display some debug informations. `--debug=internal' Display warnings if program internal maximums are reached. `--debug=handled' Like `--debug=internal' and display file names which are handled, too. `--debug=unhandled' Like `--debug=internal' and display file names which are unhandled, too. `--debug=all' Like `--debug=handled' and `--debug=unhandled' together. `--debug=abort' Like `--debug=all' and abort program with error if file name can't be handled, see *Note 118: Error codes. `-p' `--pager' Enables either an *external* pager or a simple *internal* pager. If an environment variable `PAGER' is set, its value will be used for detecting the external pager program. *Note PAGER: Environment variables, for more information. If no `PAGER' environment variable is set or if its value is invalid, Gcal tries to use the `less' pager; if this program can't be found during scanning the `PATH' environment variable, Gcal tries to use the `more' pager, if this program can't be found, the `pg' pager in the same way (1). *Note PATH: Environment variables. If all these actions fail, Gcal will use its simple, built-in pager. If the internal pager is used, Gcal detects the number of lines shown before it prompts and waits for user input using these methods: 1. Gcal respects the values set in the environment variables `LINES' and `COLUMNS'. *Note LINES: Environment variables, and see *Note COLUMNS: Environment variables, for more details. 2. If above action fails, Gcal respects the values set in the environment variables `LI' and `CO'. *Note LI: Environment variables, and see *Note CO: Environment variables, for more details. 3. If above actions fails, Gcal uses a system dependent *low-level* function (on MS-DOS, OS/2 and some other operating systems) and respects the reported values. 4. If above action fails, Gcal respects the values set in the `termcap' (2) file, which refers to the terminal used (*note TERM: Environment variables.). This step is only done on systems which support the use of Termcap by default. 5. If all above actions fail, Gcal uses default values (either 23 or 24 lines, 80 columns). `-H yes' `--force-highlighting' `--highlighting=yes' If output of the program is redirected or piped, the highlighting sequences are *not* converted automatically into the according marking characters, they remain unchanged. This option has no effect if the output of the program is send by means of electronic mail, see *Note `--mail=ADR': Global options. `-H no' `--disable-highlighting' `--highlighting=no' Disable highlighting sequence / marking character pairs of current day, holiday respectively text explicitly. `-H TEXT' `--highlighting=ARG' Set highlighting sequence / marking character pairs explicitly. In this sense, "highlighting" sequences are control character sequences which cause a colour or intensity switch of output text. Typical control character sequences are the ANSI escape sequences, which have a leading escape character and trailing more characters, which define the type of the ANSI escape sequence. In this sense, "marking" characters are single, printable characters, which lead and succeed the output text. The argument TEXT 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 the actual day, the *second* for 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 allowed! Some examples: `-H \x20:\x20:\x1:#' respectively `--highlighting=\x20:\x20:\x1:#' marks the actual day like `\x20ACTUAL DATE\x20' (this means with leading and trailing blanks) and the holiday date like `\x1HOLIDAY DATE#' using 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 holiday, so default highlighting sequences for holidays are used (non-notated entries are always skipped). Please note the last abstract of this text part, which informs you more detailed to this coherence. *Note GCALANSI: Environment variables. 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 last in 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 last in single sequence. If the sequence separator character, the `:' (colon) character itself is used for marking character, it must be encoded either octal by `\072' or hexadecimal by `\x3A'. If the C Preprocessor symbol USE_PAGER was defined and output of program is redirected or piped, the highlighting sequences are converted automatically into the according marking characters; if USE_PAGER was not defined, they remain untouched. Incomplete or no given highlighting sequences will be replaced by internal default ANSI escape highlighting sequences if a `GCALANSI' environment variable is defined; otherwise completely replaced by their according marking characters. *Note GCALANSI: Environment variables. `-m ADR' `--mail=ARG' Send Gcal's output via `mail' (3) program to Email address ADR, e.g.: --mail=root -m esken@uni-muenster.de All highlighting sequences produced by Gcal itself are always disabled respectively converted automatically into the according marking characters if an Email must be send; no matter if the `--force-highlighting' option was given or not. This behavior of Gcal is an imperative necessaty, 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, (*note Text part of a line: Resource file.). ---------- Footnotes ---------- (1) See the standard *manual* pages for `less', `more' and `pg'. (2) See the standard *manual* pages for Termcap. (3) See the standard *manual* pages for `mail'.  File: gcal.info, Node: Calendar options, Next: Date warning options, Prev: Global options, Up: Options Calendar options ................ `-n|N[-]' `--descending-holiday-list[=long|short]' `--holiday-list[=long|short]' Display an eternal holiday list. *Note Eternal holidays::, for additional information. `-n' `--holiday-list=long' Display all holidays in eternal holiday list sorted in ascending order. `-n-' `--descending-holiday-list=long' Display all holidays in eternal holiday list sorted in descending order. `-N' `--holiday-list=short' Display legal days only in eternal holiday list sorted in ascending order. `-N-' `--descending-holiday-list=short' Display legal days only in eternal holiday list sorted in descending order. `-X' `--exclude-holiday-list-title' Suppresses the title text line of the eternal holiday list. `-i[-]' `--type=special|standard' To get the "standard" calendar format (similar BSD-`cal'), start Gcal omitting the `-i[-]' option because it is set by default, or by giving the `-i-' respectively the `--type=standard' option to force the output of a calendar sheet: $ 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 get the "special" calendar format and to force the output of a calendar sheet, start Gcal with the `-i' respectively the `--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 `-u' `--suppress-calendar' Suppress output of calendar sheet explicitly. `-b NUMBER' `--blocks=ARG' Set number of calendar sheet blocks (valid arguments: `1|2|3|4|6|12'). The default value 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 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 using the standard and special date format. `-jn[b]' `--holiday-dates=special|both' Use alternative date format in eternal holiday list instead of the default standard format, which displays the days of month in consecutive manner. *Note `--holiday-list[=long|short]': Calendar options. `-jn' `--holiday-dates=special' Display the eternal holiday list using the special date format. This means the days of year are displayed in consecutive manner instead of the days of month. `-jnb' `--holiday-dates=both' Display the eternal holiday list using the standard and special date format. `-jc[b]' `--fixed-dates=special|both' Use alternative date format in fixed date warning list instead of the default standard format, which displays the days of month in consecutive manner. *Note `--list-of-fixed-dates[=short|long]': Date warning options. `-jc' `--fixed-dates=special' Display the fixed date warning list using the special date format. This means the days of year are displayed in consecutive manner instead of the days of month. `-jcb' `--fixed-dates=both' Display the fixed date warning list using the standard and special date format. `-s ARG' `--starting-day=ARG' Set the starting day of week (valid arguments: `0, 1...7 | today | WEEKDAY NAME'). Example: --starting-day=Sunday or --starting-day=7 or -s SUNDAY or -s sund or -s Su 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 week is set to the actual weekday.