  This file documents Gcal, a program for printing calendars.  Gcal
displays a calendar for a month or a year, eternal holiday lists and
fixed date lists, in many ways.  The program correctly omits the dates
that were skipped when the current Gregorian calendar replaced the
earlier Julian calendar.

  Copyright (C) 1994, 1995, 1996, 1997 Thomas Esken

  This is the second edition of the Gcal documentation.

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

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

Gcal Utilities
**************

  Three small utility programs are part of the Gcal 2.40 package.  The
`tcal' program runs the Gcal program with the date set one day ahead.
The `txt2gcal' program creates a verbatim Gcal resource file from a text
file, and in contrast to this, the `gcal2txt' program creates a verbatim
text file from a Gcal resource file.

Invoking `tcal'
===============

  The `tcal' program runs `gcal' with the date of tomorrow's day (1).
Its arguments are as follows:

     tcal [--help | --version] | [--shift=[+|-]NUMBER] [ARGUMENT...]

  All given ARGUMENTS are passed unmodified to the Gcal program.  If
the Gcal program shall be called with another date than tomorrow's
date, this desired date can be selected by using the
`--shift=[+|-]NUMBER' option, in which `[+|-]NUMBER' is the distance of
days the desired date is distant from the actual system date (==today).
(Works only for Gregorian years.)  The `--shift' option must be given
before all other ARGUMENTS that are passed to the Gcal program.

  In case a `GCALPROG' environment variable (see GCALPROG)
is defined and set with the file name of the
executable Gcal program, `tcal' will use this file name for calling
Gcal.  Otherwise, the file name `gcal' -- which is burned-in during the
compilation step of `tcal' -- is used for calling the Gcal program.  An
exit status of 0 means all processing is successfully done, any other
value means an error has occurred.

The program accepts the following options:

`--help'
     Print a usage message listing all available options, then exit
     successfully.

`--version'
     Print the version number, then exit successfully.

`--shift=[+|-]NUMBER'
     Define the displacement in `[+|-]NUMBER' days the desired date is
     distant from the actual date.

  ---------- Footnotes ----------

  (1)  This is equivalent the `--shift=1' option.

Invoking `txt2gcal'
===================

  The `txt2gcal' program creates a verbatim Gcal resource file from a
text file. Its arguments are as follows:

     txt2gcal [--help | --version] | [TEXT-FILE|-] [DATE-PART]

  If no TEXT-FILE argument is given or/but `-', the program reads and
processes all input received from the *standard input channel*.  If no
DATE-PART argument is given, `txt2gcal' creates a `0' for the date
part.  All results are always shown on the *standard output channel*.
An exit status of 0 means all processing is successfully done, any
other value means an error has occurred.

The program accepts the following options:

`--help'
     Print a usage message listing all available options, then exit
     successfully.

`--version'
     Print the version number, then exit successfully.

  Here comes an example how to use `txt2gcal'.  Let's suppose there is a
text file by the name of `demo' with the following contents:

             Hi friends,

     I'm the demo text containing funny characters and character
     sequences like ~~ \~ % %% $a $1 %%%\
     %\ %s %%foo %bar \%baz \\~ \~\ and so on...
     I'm be anxious how I'll be transformed by `txt2gcal'.

and `txt2gcal' processes this file, redirecting the output to
`demo.rc',:

     $ txt2gcal demo 0*d1#999 > demo.rc
     => 0*d1#999 \        Hi friends,~\
     => ~\
     => I'm the demo text containing funny characters and character~\
     => sequences like \~\~ \\~ % %% \$a $1 %%%\ ~\
     => %\ \%s %\%foo \%bar \\%baz \\\~ \\~\ and so on...~\
     => I'm be anxious how I'll be transformed by `txt2gcal'.

then `txt2gcal' has now created a new Gcal resource file `demo.rc' from
the text file `demo'.  Let's finally see, how Gcal will interpret this
new resource file:

     $ gcal -H no -Ax -f ./demo.rc
     -|
     -| Thu, May   2nd 1996:
     -|         Hi friends,
     -|
     -| I'm the demo text containing funny characters and character
     -| sequences like ~~ \~ % %% $a $1 %%%\
     -| %\ %s %%foo %bar \%baz \\~ \~\ and so on...
     -| I'm be anxious how I'll be transformed by `txt2gcal'.

Invoking `gcal2txt'
===================

  The `gcal2txt' program creates a verbatim text file from a Gcal
resource file. Its arguments are as follows:

     gcal2txt [--help | --version] | [RESOURCE-FILE|-]

  If no RESOURCE-FILE argument is given or/but `-', the program reads
and processes all input received from the *standard input channel*.  All
results are always shown on the *standard output channel*.  An exit
status of 0 means all processing is successfully done, any other value
means an error has occurred.

  The sense and purpose of `gcal2txt' is to retrieve all additional
texts, which are put in output by means of `txt2gcal'.

The program accepts the following options:

`--help'
     Print a usage message listing all available options, then exit
     successfully.

`--version'
     Print the version number, then exit successfully.

  Here comes an example how to use `gcal2txt'.  For that purpose, let's
use the resource file `demo.rc' of the previous section (see Invoking `txt2gcal'),
which was created by means of
`txt2gcal' from a text file and which looks like this:

     $ cat demo.rc
     -| 0*d1#999 \        Hi friends,~\
     -| ~\
     -| I'm the demo text containing funny characters and character~\
     -| sequences like \~\~ \\~ % %% \$a $1 %%%\ ~\
     -| %\ \%s %\%foo \%bar \\%baz \\\~ \\~\ and so on...~\
     -| I'm be anxious how I'll be transformed by `txt2gcal'.

Now let's see, how this resource file will be processed by `gcal2txt':

     $ gcal2txt demo.rc
     -|         Hi friends,
     -|
     -| I'm the demo text containing funny characters and character
     -| sequences like ~~ \~ % %% $a $1 %%%\
     -| %\ %s %%foo %bar \%baz \\~ \~\ and so on...
     -| I'm be anxious how I'll be transformed by `txt2gcal'.

Aspects in Internationalization
*******************************

  Starting with version 2.00, Gcal is able to display message texts
using any native languages instead of using the English language only,
because parts of the GNU `gettext' package are integrated into the
Software.  See Introduction (gettext), for more details.

  By default, Gcal displays all message texts using the English native
language in case no other native language is wanted.  A so-called
*message catalog* is read by Gcal at run-time if message texts from
another native language are required.  Gcal 2.40 supports the following
native languages:

*Native Language*        *Language Code*
English                  `en'
German                   `de'
French                   `fr'
Dutch                    `nl'
Swedish                  `sv'

  It is only necessary to set one of the environment variables (1):

1.  `LANGUAGE'
2.  `LC_ALL'
3.  `LC_MESSAGES'
4.  `LANG'

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

  Normally, users only have to set the `LANG' environment variable to
tell Gcal the native language to use at run-time level.  Presuming
users want to run Gcal using the German native language for displaying
message texts, they merely have to execute `setenv LANG de' (in `csh')
or `export LANG; LANG=de' (in `sh') at the shell prompt.  Of course
they could even do this from their `.login' or `.profile' file.  See
The User's View (gettext), for more details.

  As shown above, a simple setting of `de' in the environment variable
`LANG' is sufficient to enable German message texts.  `de' is the
two-letter language code for the German language defined in the
ISO-639:1988, and is called "simple language code information" in the
further context.  Other language codes can be taken from this
ISO-document (2).

  Because Gcal as calendar program must also comply the specifics of a
used native language concerning the ordering of day, month and year
(and further things) of a displayed date, the period of Gregorian
Reformation and the representation of calendar sheets, these criteria
are likewise bound to the language code (3).

A `en' language code effects the following internal defaults of above
criteria:

   * U.S. American date format

   * Gregorian Reformation have occurred 1752

   * Week starts on Sunday

   * Representation of calendar sheet

             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

And a `de' language code (4) effects the following internal defaults:

   * German date format

   * Gregorian Reformation have occurred 1582

   * Week starts on Monday

   * Representation of calendar sheet

          September 1994

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

  Remember, all these internal defaults are modifiable by the options
`--date-format', `--gregorian-reform', `--starting-day' and `--type'.

  If no language code is detected, Gcal takes the internal defaults of
the `en' language code (5).

  If a language code is specified for which no *message catalog* is
installed, Gcal takes the internal defaults of the `de' language code,
but displays the message texts using the English native language.
Actually, this behavior seems to me the most proper solution in such a
case.  The English native language is spoken all over the world unlike
the German or other native languages, so it is wise to use it here.
But the other criteria bound to the English native language are so
special for users of other native languages, that it is wise to use the
criteria taken for internal defaults of the `de' language code, because
most European countries (taken as standard) essentially use them.

  Now British users will certainly ask whether they could use their
date format as an internal default (6).  The answer to this is a simple
`yes', nevertheless, these users have to set the environment variable
`LANG' with an "extended language code information" instead of a simple
language code information.

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

   * For XPG syntax (X/Open Portability Guide):
          LANGUAGE[_TERRITORY][.CODESET][@MODIFIER]

   * For CEN syntax (Comit'e Europ'en de Normalisation):
          LANGUAGE[_TERRITORY][+AUDIENCE][+SPECIAL][,SPONSOR][_REVISION]

  Both syntax's contain the LANGUAGE and TERRITORY components, which
are used by Gcal to select the native language and the other criteria.
The LANGUAGE component is equivalent to the simple language code
information and the TERRITORY component is a two-letter territory or
country code as defined by the ISO-3166 like `GB' for Great Britain or
`US' for the U.S.A.  See the pertinent literature for more details.  So
British users only have to set the `LANG' environment variable with a
`en_GB' contents, and after that, they can use the British date format
as an internal default.

  ---------- Footnotes ----------

  (1)  Listed in decreasing priority as they are respected.

  (2)  For example `fr' for French, `es' for Spanish...

  (3)  Strictly speaking, an extended language code information.

  (4)  Or other language codes, for which a *message catalog* will be
created and distributed in future.

  (5)  Or to be more precise, of the extended language code information
`en_US'.

  (6)  All other internal defaults of the simple `en' language code
information just meet their criteria.

Metasymbols
***********

  Within this document, the following *metasyntactic* conventions will
be used when discussing command line options, commands, arguments and
templates:

`N'
     Argument is not optional and N must be a valid number.

`e|t|DVAR'
     Argument is not optional and must be a single alphabetic character.

`$TVAR'
     Argument is not optional and must be a single alphabetic character,
     that is lead by a `$' character.

`[TEXT]'
     Argument is optional and TEXT is a valid string of text.

`[AB]'
     Arguments are optional, any number may be used in any order, e.g.:

          NOTHING, A, B, AB, BA ...

`{AB}'
     Arguments are not optional, minimum one up to any number may be
     used in any order, e.g.:

          A, B, AB, BA ...

`[A|B]'
     Arguments are optional, select either A or B, but not both.

`A|B'
     Arguments are not optional, select either A or B, but not both.

`[A[B]]'
     Arguments are optional, select either A or AB, but not B.

`[A|B[C]]'
     Arguments are optional, select A or B or AC or BC, but not C.

`[A|BC]'
     Arguments are optional, select either AC or BC, but not A or B or
     C.

`[A]|[B]'
     Argument *lists* are optional, select either list A or list B, but
     not both.

`[...]'
     Additional arguments/files may be specified and are optional.

Regular Expressions
*******************

This appendix is derived from the `gawk-3.0.0' and `regex-0.12' manuals.

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

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

*No.**Function*                                             *Symbol*
1.   GNU `re_compile_pattern()' and `regex.h'               `GNU-REGEX'
2.   POSIX `regcomp()' and `regex.h'                        `POSIX-REGEX'
3.   BSD `re_comp()'                                        `BSD-REGEX'
4.   System V `regcmp()'                                    `SysV-REGEX'
5.   Henry Spencer V8 `regcomp()' and `regexp.h'            `V8-REGEX'
6.   Pattern matching is supported, but without             `NO-REGEX'
     metacharacters

  Try `gcal --version' for detecting the kind of regular expression
programming library respectively method that is burned-in in your Gcal
program!

How to Use Regular Expressions
==============================

  A regular expression can be used as a pattern if Gcal's
`--filter-text=PATTERN' option is specified at program start-up.

  See `--filter-text=PATTERN', for more details.

  Then the regular expression is tested against the entire, completely
expanded text of each *valid* fixed date, and the fixed date is only
displayed in case the pattern matches the text (1).

  ---------- Footnotes ----------

  (1)  Normally, it only needs to match some part of the text in order
to succeed.

Regular Expression Operators
============================

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

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

`\'
     This is used to suppress the special meaning of a character when
     matching.  For example:

          \$

     matches the character `$'.

`^'
     This matches the beginning of a string.  For example:

          ^@chapter

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

`$'
     This is similar to `^', but it matches only at the end of a string.
     For example:

          p$

     matches a string that ends with a `p'.  The `$' is also an anchor.

`.'
     The period, or dot, matches any single character.  For example:

          .P

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

`[...]'
     This is called a "character list".  It matches any *one* of the
     characters that are enclosed in the square brackets.  For example:

          [MVX]

     matches any one of the characters `M', `V', or `X' in a string.

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

          [0-9]

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

     To include one of the characters `\', `]', `-' or `^' in a
     character list, put a `\' in front of it.  For example:

          [d\]]

     matches either `d', or `]'.

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

     A character class is only valid in a regexp *inside* the brackets
     of a character list.  Character classes consist of `[:', a keyword
     denoting the class, and `:]'.  Here are the character classes
     defined by the POSIX standard:

    `[:alnum:]'
          Alphanumeric characters.

    `[:alpha:]'
          Alphabetic characters.

    `[:blank:]'
          Space and tab characters.

    `[:cntrl:]'
          Control characters.

    `[:digit:]'
          Numeric characters.

    `[:graph:]'
          Characters that are printable and are also visible (1).

    `[:lower:]'
          Lower-case alphabetic characters.

    `[:print:]'
          Printable characters (2).

    `[:punct:]'
          Punctuation characters (3).

    `[:space:]'
          Space characters (4).

    `[:upper:]'
          Upper-case alphabetic characters.

    `[:xdigit:]'
          Characters that are hexadecimal digits.

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

     Two additional special sequences can appear in character lists.
     These apply to non-ASCII character sets, which can have single
     symbols (called "collating elements") that are represented with
     more than one character, as well as several characters that are
     equivalent for "collating", or sorting, purposes.  (E.g., in
     French, a plain `e' and a grave-accented ``e' are equivalent.)

    Collating Symbols
          A "collating symbol" is a multi-character collating element
          enclosed in `[.' and `.]'.  For example, if `ch' is a
          collating element, then `[[.ch.]]' is a regexp that matches
          this collating element, while `[ch]' is a regexp that matches
          either `c' or `h'.

    Equivalence Classes
          An "equivalence class" is a list of equivalent characters
          enclosed in `[=' and `=]'.  Thus, `[[=e`e=]]' is regexp that
          matches either `e' or ``e'.

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

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

`[^ ...]'
     This is a "negated character list" respectively "complemented
     character list".  The first character after the `[' *must* be a
     `^'.  It matches any characters *except* those in the square
     brackets.  For example:

          [^0-9]

     matches any character that is not a digit.

`|'
     This is the "alternation operator", and it is used to specify
     alternatives.  For example:

          ^P|[0-9]

     matches any string that matches either `^P' or `[0-9]'.  This
     means it matches any string that starts with `P' or contains a
     digit.

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

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

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

          ph*

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

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

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

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

`+'
     This symbol is similar to `*', but the preceding expression must be
     matched at least once.  This means that:

          wh+y

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

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

`?'
     This symbol is similar to `*', but the preceding expression can be
     matched either once or not at all.  For example:

          fe?d

     will match `fed' and `fd', but nothing else.

`{N}'
`{N,}'
`{N,M}'
     One or two numbers inside braces denote an "interval expression"
     which is available in the POSIX standard.  If there is one number
     in the braces, the preceding regexp is repeated N times.  If there
     are two numbers separated by a comma, the preceding regexp is
     repeated N to M times.  If there is one number followed by a
     comma, then the preceding regexp is repeated at least N times.

    `wh{3}y'
          matches `whhhy' but not `why' or `whhhhy'.

    `wh{3,5}y'
          matches `whhhy' or `whhhhy' or `whhhhhy', only.

    `wh{2,}y'
          matches `whhy' or `whhhy', and so on.

  GNU software that deals with regular expressions provides a number of
additional regexp operators.  These operators are described here.

  Most of the additional operators are for dealing with word matching.
For our purposes, a "word" is a sequence of one or more letters, digits,
or underscores (`_').

`\w'
     This operator matches any word-constituent character, i.e. any
     letter, digit, or underscore. Think of it as a short-hand for
     `[A-Za-z0-9_]' or `[[:alnum:]_]'.

`\W'
     This operator matches any character that is not word-constituent.
     Think of it as a short-hand for `[^A-Za-z0-9_]' or `[^[:alnum:]_]'.

`\<'
     This operator matches the empty string at the beginning of a word.
     For example, `\<away' matches `away', but not `stowaway'.

`\>'
     This operator matches the empty string at the end of a word.  For
     example, `stow\>' matches `stow', but not `stowaway'.

`\b'
     This operator matches the empty string at either the beginning or
     the end of a word (the word *b*oundary).  For example, `\bballs?\b'
     matches either `ball' or `balls' as a separate word.

`\B'
     This operator matches the empty string within a word. In other
     words, `\B' matches the empty string that occurs between two
     word-constituent characters. For example, `\Brat\B' matches
     `crate', but it does not match `dirty rat'.  `\B' is essentially
     the opposite of `\b'.

  There are two other operators that work on buffers.  In Emacs, a
"buffer" is, naturally, an Emacs buffer.  For other programs, the
regexp library routines that `gcal' uses consider the entire string to
be matched as the buffer (5).

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

`\`'
     This operator matches the empty string at the beginning of the
     buffer.

`\''
     This operator matches the empty string at the end of the buffer.

  In regular expressions, the `*', `+', and `?' operators, as well as
the braces `{' and `}', have the highest precedence, followed by
concatenation, and finally by `|'.  As in arithmetic, parentheses can
change how operators are grouped.

  Case is normally significant in regular expressions, both when
matching ordinary characters (i.e. not metacharacters), and inside
character sets.  Thus a `w' in a regular expression matches only a
lower-case `w' and not an upper-case `W'.

  The simplest way to do a case-independent match is to use a character
list: `[Ww]'.  However, this can be cumbersome if you need to use it
often; and unfortunately, it can make the regular expressions harder to
read.

  ---------- Footnotes ----------

  (1)  A space is printable, but not visible, while an `a' is both.

  (2)  Characters that are not control characters.

  (3)  Characters that are not letter, digits, control characters, or
space characters.

  (4)  Such as Space, Tab, and Form-feed, to name a few.

  (5)  That's the *text part* of a Gcal resource file line.

Summary of all Regular Expressions
**********************************

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

`C'
     matches the character C (assuming C is none of the characters
     listed below).

`\C'
     matches the literal character C.

`.'
     matches any character.

`^'
     matches the beginning of a string.

`$'
     matches the end of a string.

`[ABC...]'
     matches any of the characters ABC... (character list).

`[[:CLASS:]]'
     matches any character in the character class CLASS.  Allowable
     classes are `alnum', `alpha', `blank', `cntrl', `digit', `graph',
     `lower', `print', `punct', `space', `upper', and `xdigit'.

`[[.SYMBOL.]]'
     matches the multi-character collating symbol SYMBOL.  `gcal' does
     not currently support collating symbols.

`[[=CHARS=]]'
     matches any of the equivalent characters in CHARS.  `gcal' does
     not currently support equivalence classes.

`[^ABC...]'
     matches any character except ABC... (negated resp.  complemented
     character list).

`R1|R2'
     matches either R1 or R2 (alternation).

`R1R2'
     matches R1, and then R2 (concatenation).

`R+'
     matches one or more R's.

`R*'
     matches zero or more R's.

`R?'
     matches zero or one R's.

`(R)'
     matches R (grouping).

`R{N}'
`R{N,}'
`R{N,M}'
     matches at least N, N to any number, or N to M occurrences of R
     (interval expressions).

`\b'
     matches the empty string at either the beginning or the end of a
     word.

`\B'
     matches the empty string within a word.

`\<'
     matches the empty string at the beginning of a word.

`\>'
     matches the empty string at the end of a word.

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

`\W'
     matches any character that is not word-constituent.

`\`'
     matches the empty string at the beginning of a buffer (1).

`\''
     matches the empty string at the end of a buffer.

  ---------- Footnotes ----------

  (1)  Same as a *text part* of a resource file line in `gcal'.

`%?'... Special Texts
*********************

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

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

   * `YYYY[MM[DD|WWWN]]'

   * `YYYY*d|wN[WWW]'

   * `YYYY@e|t|DVAR[[+|-]N[WWW]]'

  Special texts that may have a DATE argument *must* always be trailed
by a *whitespace* character which is removed itself in output, no
matter whether DATE was given or not!

  See Summary of all `%?'... special texts,
for a short-list of all applicable special texts.

`%?'... special texts for date exclusion
========================================

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

Exclusions with date argument `%?[DATE]' special texts
------------------------------------------------------

  First of all, an "inclusive date" period `%?[DATE]' special text can
be specified with the effect, that only those fixed dates are respected
and displayed which are part of this period.  And the specification of
an "exclusive date" period `%?[DATE]' special text effects, that only
those fixed dates are respected and displayed which are not part of
this period.

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

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

Inclusive date period `%i[DATE][#[DATE]]' special text
......................................................

  `%i[DATE][#[DATE]]' references an inclusive date period, i.e. all
dates which are part of the specified period are valid and are
displayed.  Of course this means, that all fixed dates which are not
part of this period (not covered by it) are invalid and remain
un-displayed therefore.

  The first specified date defines the "starting date" of the fixed
date, i.e. the first date the fixed date may occur.  For the starting
date, the following rules concerning definite omission values are
valid, elucidated by using the `YYYY[MM[DD|WWWN]]' date format:

   * If YYYY is set to 0000, the current year is assumed for the year.

   * If MM is not given, then 01 (==January) is assumed for the month.

   * If MM is set to 00, the current month is assumed for the month,
     and the December is assumed in case MM is set to 99.

   * If DD|WWW is not given, then 01 is assumed for the day.

   * If DD is set to 00, the current day is assumed for the day, and
     the last day of the month MM is assumed in case DD is set to 99.

   * If the N field is given (range 1...5 or 9), a WWW field must be
     given then.

  The second specified date defines the "ending date" of the fixed date,
i.e. the last date the fixed date may occur.  For the ending date, the
following rules concerning definite omission values are valid, likewise
elucidated by using the `YYYY[MM[DD|WWWN]]' date format:

   * If YYYY is set to 0000, the current year is assumed for the year.

   * If MM is not given, then 12 (==December) is assumed for the month.

   * If MM is set to 00, the current month is assumed for the month,
     and the December is assumed in case MM is set to 99.

   * If DD|WWW is not given, the last day of the month MM is assumed
     for the day.

   * If DD is set to 00, the current day is assumed for the day, and
     the last day of the month MM is assumed in case DD is set to 99.

   * If the N field is given (range 1...5 or 9), a WWW field must be
     given then.

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

  If the starting date which is encoded in the `%i...' special text is
later the ending date, so the `%i...' special text will be ignored.

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

  If only the starting date is specified, means either `%iDATE' or
`%iDATE#' is given, the implicit ending date 31st December 9999
(99991231) will be used.

  In case only the ending date is specified, means `%i#DATE' is given,
the implicit starting date 1st January 1 (00010101) will be used.

For example:

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

Exclusive date period `%e[DATE][#[DATE]]' special text
......................................................

  `%e[DATE][#[DATE]]' references an exclusive date period, i.e. all
dates which are part of the specified period are invalid and remain
un-displayed therefore.  Of course this means, that all fixed dates
which are not part of this period (not covered by it) are valid and are
displayed.

  The first specified date defines the "starting date" of the fixed
date, i.e. the first date the fixed date may occur.  For the starting
date, the following rules concerning definite omission values are
valid, elucidated by using the `YYYY[MM[DD|WWWN]]' date format:

   * If YYYY is set to 0000, the current year is assumed for the year.

   * If MM is not given, then 01 (==January) is assumed for the month.

   * If MM is set to 00, the current month is assumed for the month,
     and the December is assumed in case MM is set to 99.

   * If DD|WWW is not given, then 01 is assumed for the day.

   * If DD is set to 00, the current day is assumed for the day, and
     the last day of the month MM is assumed in case DD is set to 99.

   * If the N field is given (range 1...5 or 9), a WWW field must be
     given then.

  The second specified date defines the "ending date" of the fixed date,
i.e. the last date the fixed date may occur.  For the ending date, the
following rules concerning definite omission values are valid, likewise
elucidated by using the `YYYY[MM[DD|WWWN]]' date format:

   * If YYYY is set to 0000, the current year is assumed for the year.

   * If MM is not given, then 12 (==December) is assumed for the month.

   * If MM is set to 00, the current month is assumed for the month,
     and the December is assumed in case MM is set to 99.

   * If DD|WWW is not given, the last day of the month MM is assumed
     for the day.

   * If DD is set to 00, the current day is assumed for the day, and
     the last day of the month MM is assumed in case DD is set to 99.

   * If the N field is given (range 1...5 or 9), a WWW field must be
     given then.

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

  If the starting date which is encoded in the `%e...' special text is
later the ending date, so the `%i...' special text will be ignored.

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

  If only the starting date is specified, means either `%eDATE' or
`%eDATE#' is given, the implicit ending date 31st December 9999
(99991231) will be used.

  In case only the ending date is specified, means `%e#DATE' is given,
the implicit starting date 1st January 1 (00010101) will be used.

For example:

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

Exclusions without any argument `%?' special texts
--------------------------------------------------

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

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

For example:

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

Inclusive day period `%?' special texts
.......................................

  The following inclusive day periods `%?' special texts are respected,
at which *inclusive* is meant for the period which is not excluded.

`%v'
     Excludes fixed date in case it is not listed as legal holiday in
     the *eternal holiday list*.

`%x'
     Excludes fixed date in case it is neither listed as legal holiday
     nor memorial day in the *eternal holiday list*.

`%a'
     Excludes fixed date in case it is no Monday.

`%c'
     Excludes fixed date in case it is no Tuesday.

`%f'
     Excludes fixed date in case it is no Wednesday.

`%g'
     Excludes fixed date in case it is no Thursday.

`%h'
     Excludes fixed date in case it is no Friday.

`%l'
     Excludes fixed date in case it is no Saturday.

`%p'
     Excludes fixed date in case it is no Sunday.

`%q'
     Excludes fixed date in case it is no Monday...Thursday.

`%r'
     Excludes fixed date in case it is no Monday...Friday.

Exclusive day period `%?' special texts
.......................................

  The following exclusive day periods `%?' special texts are respected,
at which *exclusive* is meant for the period which is excluded.

`%V'
     Excludes fixed date in case it is listed as legal holiday in the
     *eternal holiday list*.

`%X'
     Excludes fixed date in case it is either listed as legal holiday or
     memorial day in the *eternal holiday list*.

`%A'
     Excludes fixed date in case it is a Monday.

`%C'
     Excludes fixed date in case it is a Tuesday.

`%F'
     Excludes fixed date in case it is a Wednesday.

`%G'
     Excludes fixed date in case it is a Thursday.

`%H'
     Excludes fixed date in case it is a Friday.

`%L'
     Excludes fixed date in case it is a Saturday.

`%P'
     Excludes fixed date in case it is a Sunday.

`%Q'
     Excludes fixed date in case it is a Monday...Thursday.

`%R'
     Excludes fixed date in case it is a Monday...Friday.

`%?'... special texts for text replacement
==========================================

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

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

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

Replacements with date argument `%?[DATE]' special texts
--------------------------------------------------------

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

  For the DATE argument these `%?[DATE]' special text may have, the
following rules concerning definite omission values are valid,
elucidated by using the `YYYY[MM[DD|WWWN]]' date format (1):

   * If YYYY... is not given (==*no* date encoded), the current year is
     assumed for the date.

   * If YYYY is set to 0000, the current year is assumed for the year.

   * If MM is not given or set to 00, the current month is assumed for
     the month, and the December is assumed in case MM is set to 99.

   * If DD|WWW is not given or set to 00, the current day is assumed
     for the day, and the last day of the month is assumed in case DD
     is set to 99.

   * If the N field is given (range 1...5 or 9), a WWW field must be
     given then.

  ---------- Footnotes ----------

  (1)  The succeeding rules are analogously valid for the other
permitted date formats.

Weekday name `%?[DATE]' special texts
.....................................

  The following weekday name `%?[DATE]' special texts are respected:

`%o[DATE]'
     Is replaced by the complete *weekday name* of the current day,
     e.g.:

          The text `Today is %o , the %n' will be expanded to
          ==> `Today is Monday, the 10-Jun-1996', in case the actual
          system date is the 10th June 1996.

`%O[DATE]'
     Is replaced by the 3-letter *weekday name* of the current day,
     e.g.:

          The text `Today is %O0@t+1 , the %n+1' will be expanded to
          ==> `Today is Tue, the 11-Jun-1996', in case the actual
          system date is the 10th June 1996.

`%K[DATE]'
     Is replaced by the 2-letter *weekday name* of the current day,
     e.g.:

          The text `Today is %K , the %n' will be expanded to
          ==> `Today is Mo, the 10-Jun-1996', in case the actual system
          date is the 10th June 1996.