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

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

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

  Copyright (c) 1994, 95, 96, 1997, 2000 Thomas Esken

  This edition is for Gcal version 3.01.

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

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

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

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

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


File: gcal.info,  Node: Text variables,  Prev: Date variables,  Up: Resource file

Text variables
--------------

  Gcal respects _global_ and/or _local_ text variables which may be
used anywhere in a line of a Gcal resource file.  This means, up to
*26* user-defined text variables can be set and referenced during
program execution.  *Note Fixed date option `--text-variable=ARGUMENT':
x-text-variable, for more information how global text variables can be
used.

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 that are contained in this output.  *Note 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 that are contained in this output.  See also *Note
     Special Texts processed::, for further details.

  Indeed, Gcal executes external commands only if the
`--execute-command' option is given at program start-up.  *Note Fixed
date option `--execute-command': x-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
text variables.  These references are converted to the according
textual values just before the assignment is performed by Gcal.  You
should always remember that text variables can only be referenced in a
line if they are already defined, because Gcal processes a resource
file line by line.  Gcal always expands text variable references
recursively until all sub-references to other text variables are
resolved.

  Local text variables are set to an _empty value_ and thus defined in
a special mode in case no text appears at the right side of one of the
valid assignment operator characters.

  If a text variable is referenced, an optional format instruction may
be specified between the `$' prefix and the single letter (here: the
variable name), which makes it possible to modify the representation of
the text (here: the contents) at which the text variable points to.  Let
us assume a resource file by the name of `tvarf-1.rc' exists with the
following contents:

     $ cat tvarf-1.rc
     -| ; tvarf-1.rc
     -| ;
     -| $a=123
     -| $b=$:010*a
     -| $c=$b
     -| $b=
     -| 0 1. \$c=.$c.
     -| 0 2. \$c=.$:20*c.
     -| 0 3. \$b=.$>1w*b.
     -| 0 4. \$a=.$>5#a.

So Gcal creates the following output:

     $ gcal -Ux --text-variable='$b=XXX YY' --resource-file=./tvarf-1.rc
     -|
     -| 1. $c=.0000000123.
     -| 2. $c=.      0000000123       .
     -| 3. $b=.Xxx Yy.
     -| 4. $a=.  123.

  *Note Format Instruction::, for the detailed description of the
format instruction and its components.

  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. `\\$'.

  External commands are not directly executed by Gcal, they are executed
by means of the command line interpreter of the operating system, the
shell.  As consequence to this, of course the commands have to be
specified according to the syntax conventions of the used shell,
concerning the grouping conventions, list processing conventions,
redirection conventions et cetera!  For example, it is possible that
you have to write `$a?(cat text)' instead of the simple `$a?cat text'.
See the pertinent literature for more details.

  If the output of external commands, which appears on the _standard
output channel_, is assigned to text variables in an interpreted manner,
this output is internally directed by Gcal into a temporary file.
Thereafter, the contents of the temporary file is transfered to the
text variable and the temporary file is removed.

  If the output of external commands, which appears on the _standard
output channel_, is assigned to text variables in an uninterpreted
manner, this output is internally processed by the Txt2gcal program
first (*note Invoking `txt2gcal': Invoking txt2gcal.), and then this
output is directed by Gcal into a temporary file.  Thereafter, the
contents of the temporary file is transfered to the text variable and
the temporary file is removed.  In case a `TXT2GCALPROG' environment
variable (*note Environment Variable `TXT2GCALPROG': x-TXT2GCALPROG.)
is defined and set with the file name of the executable Txt2gcal
program, Gcal will use this file name for calling Txt2gcal.  Otherwise,
the file name `txt2gcal' --which is burned-in during the compilation
step of the Gcal program-- is used for calling the Txt2gcal program.
The `TXT2GCALPROG' environment variable must always be set if the
Txt2gcal program is installed under another name than the standard name
`txt2gcal', otherwise Gcal is unable to execute the Txt2gcal program
automatically!

  If the simple `--debug' respectively `--debug=internal' option is
given at program start-up, informational messages about the executed
command and its _exit code_ will be shown on the _standard error
channel_ (*note Global option `--debug=internal': x-debug-internal.).

  If the `--debug=abort' option is given, the Gcal program will be
aborted with an error code in case an _exit code_ not equal zero
occurred during the execution of the command.  *Note Error Code 2:
x-2-Error-code, and *Note Global option `--debug=abort': x-debug-abort,
for further information.

  Here is an example which explains how the output of external commands
can be assigned to text variables.  Supposing there is a resource file
by the name of `tvarc-1.rc' with the following contents:

     $ cat tvarc-1.rc
     -| %t  $a $>+06*b $>1u*c

This file is used in the resource file `tvarc-1a.rc' and processed by
Gcal as follows:

     $ cat tvarc-1a.rc
     -| ; tvarc-1a.rc
     -| ;
     -| $a=bonjour
     -| $b=123
     -| $c=bonsoir
     -| $x?cat $f
     -| 0 \$x=---$:30*x---
     -| $y:cat $f
     -| 0 \$y=---$y---
     -| 0 \$y=:::$>1u*y:::
     $ gcal -f tvarc-1a.rc -QUx --exe -r'$f=./tvarc-1.rc'
     -| $x=---    18:54 bonjour +00123 BONSOIR     ---
     -| $y=---%t  $a $>+06*b $>1u*c---
     -| $y=:::%T  $A $>+06*B $>1U*C:::

  Here are some more examples showing how Gcal processes text variables.
Let us assume a resource file by the name of `tvar-1.rc' exists with
the following contents:

     $ cat tvar-1.rc
     -| ; tvar-1.rc
     -| ;
     -| $a=foo
     -| 0 \$a:1=$a
     -| $c=$a
     -| 0 \$c=$c
     -| $b=$c bar $a
     -| 0 \$b=$b
     -| $a=bar $b baz $a booz
     -| 0 \$a:2=$a
     -| $a=
     -| $b=0 $b $c frozz $a frozz
     -| $b ->That's \$b
     -| 0 \$x='$x' and \$d is undefined: $d...
     -| $a= 0 ~ 1~2~\$3~%n~$c~\
     -| now it's enough!
     -| 0 \$a=---$a---
     -| $a=0 \   \ \\ And this...
     -| $a works too!

So Gcal creates the following output:

     $ gcal %19960101 -H no -x -r '$A=FROBOZZ:$x=' -f ./tvar-1.rc
     -|
     -| Mon, Jan   1st 1996:    \ \\ And this... works too!
     -| Mon, Jan   1st 1996: $a:1=foo
     -| Mon, Jan   1st 1996: $a:2=bar foo bar foo baz foo booz
     -| Mon, Jan   1st 1996: $a=--- 0
     -|                       1
     -|                      2
     -|                      $3
     -|                      01-Jan-1996
     -|                      foo
     -|                      now it's enough!---
     -| Mon, Jan   1st 1996: $b=foo bar foo
     -| Mon, Jan   1st 1996: $c=foo
     -| Mon, Jan   1st 1996: $x='' and $d is undefined: $d...
     -| Mon, Jan   1st 1996: foo bar foo foo frozz FROBOZZ frozz ->That's $b

Or a resource file by the name of `tvar-2.rc' exists with the following
contents:

     $ cat tvar-2.rc
     -| ; tvar-2.rc
     -| ;
     -| $a=$b foo
     -| $b=0@e
     -| $a bar
     -| $b \$b
     -| 0 \$a:$a
     -| 0 \$b:$b

So Gcal creates the following output:

     $ gcal %19960101 -H no -x -f ./tvar-2.rc
     -|
     -| Mon, Jan   1st 1996: $a:0@e foo
     -| Mon, Jan   1st 1996: $b:0@e
     $ gcal %19960101 -H no -x -f ./tvar-2.rc -y
     -|
     -| Sun, Apr   7th 1996: $b
     -| Sun, Apr   7th 1996: foo bar

  As seen before, it is allowed to store complete (or partial) date
parts (*note Date part of a line::), likewise special texts (*note
`%?'... Special Texts: Special Texts processed.)  into text variables
or references to other text variables, which are processed by Gcal
after their expansion.  *Note Description of all `%?'... Special Texts:
Special Texts, for limitations concerning the assignment of special
texts to text variables.

  Text variables which are defined in a resource file are always local
and only respected in this specific file, and that file which is
included by it.  This means for the included file, that *all* local
variables of the caller are visible.  The included file itself may
define its own local variables in its own name-space, which are not
exported to caller on return.  All other definitions of text
variables(1) (*note Text variables-Footnote-1::) are always global.  If
a resource file line contains a reference to a text variable which is
not locally defined in that file, Gcal will try to use the global
values held by this variable.  If this fails because no global
definition of this text variable is given, Gcal keeps the name of this
text variable untouched in this line, except this text variable held an
_empty value_.  In such a case, Gcal completely ignores this text
variable while processing and displaying instead of keeping its name
untouched in this line.

  An example to this.  Supposing a resource file by the name of
`tvar-3.rc' exists with the following contents:

     $ cat tvar-3.rc
     -| ; tvar-3.rc
     -| ;
     -| $c=+00+000
     -| $h=
     -| $d=$c$h
     -| 0 %o$d  %s$d
     -| 0 \$c=$c  \$h=$h  \$d=$d  \$x=$x

So Gcal creates the following output:

     $ gcal -QUx -f ./tvar-3.rc
     -| $c=+00+000  $h=  $d=+00+000  $x=$x
     -| 05:57 18:04
     $ gcal -QUx -r '$h=+1000:$x=' -f ./tvar-3.rc
     -| $c=+00+000  $h=+1000  $d=+00+000+1000  $x=
     -| 05:52 18:09

  Only advanced users should apply the `--export-text-variables' option
which causes that the actual incarnation of a local text variable
--which was previously defined in a resource file and not in an
included file-- is being exported to further resource files instead of
using its global value, in case that text variable is not locally
defined in that further resource file.  *Note Include directives::, for
more details.

  But be aware, the use of this option could create unwanted results,
because the order of processing the resource files is an important
entity in managing the `--export-text-variables' option, so it is not
recommended to use it.  You, the user, must exactly know what you are
doing when applying this option; *you are expressively warned now!*

Some basic operations can be performed on text variables in case they
contain integer values.  These are:

*Operation*    *Description*

`TVAR++'       Simple increment by one.
`TVAR--'       Simple decrement by one.
`TVAR+=[+|-]N' Addition of a constant numerical factor [+|-]N.
`TVAR-=[+|-]N' Subtraction of a constant numerical factor [+|-]N.

  Here is an example showing how Gcal processes text variable
operations.  Let us assume a resource file by the name of `tvaro-1.rc'
exists with the following contents:

     $ cat tvaro-1.rc
     -| ; tvaro-1.rc
     -| ;
     -| $a=130
     -| $b=2
     -| 0 1. \$b=$b
     -| $b++
     -| 0 2. \$b=$b
     -| $b+=7
     -| 0 3. \$b=$b
     -| $b--
     -| 0 4. \$b=$b
     -| $b-=-5
     -| 0 5. \$b=$b
     -| $b+=123
     -| 0 6. \$b=$b
     -| $b-=$a
     -| 0 7. \$b=$b
     -| $b-=10000
     -| 0 8. \$b=$b
     -| $b+=10000
     -| 0 9. \$b=$b
     -| $b=02
     -| 0 a. \$b=$b
     -| $b++
     -| 0 b. \$b=$b

So Gcal creates the following output:

     $ gcal -QUx -f ./tvaro-1.rc
     -| 1. $b=2
     -| 2. $b=3
     -| 3. $b=10
     -| 4. $b=09
     -| 5. $b=14
     -| 6. $b=137
     -| 7. $b=007
     -| 8. $b=-9993
     -| 9. $b=00007
     -| a. $b=02
     -| b. $b=03

As you can see in the former example, if operations are made like these,
the default behavior of Gcal is to fill with leading zeroes to preserve
a former length of a text variable, in case a carry into one of the next
decimal places has happened and is taken back by an operation at a later
place in the resource file.  But this default behavior can be disabled
respectively changed by using the already above mentioned format
instruction.

  The scope of the definitions which are done on a local text variable,
is that resource or include file, where the local text variable is
defined.

  If a global text variable is redefined in a resource file or that file
which is included by it, these redefinitions are only valid in that
specific file(2) (*note Text variables-Footnote-2::), not in further
resource files processed.  This means, the initial values of global
text variables are always restored if the resource file changes.

  Please finally note, that each text variable assignment/operation
must be given separately on a single line in the resource file.


File: gcal.info,  Node: Text variables-Footnotes,  Up: Text variables

  (1) In the command line, environment variable `GCAL' or response file.

  (2) They are only done locally.


File: gcal.info,  Node: Resource file examples,  Prev: Resource file,  Up: Fixed Dates

Resource file examples
======================

  Here are some examples of problem oriented resource files which might
be useful to get a deeper impression about the attributes of Gcal's
fixed date feature.

  Let us begin with a common example, the resource file `common.rc':

     $ cat common.rc
     -| ; common.rc, a common example of a resource file.
     -| ;
     -| 19940715 Local time: %t  --> Dentist at 10:00
     -| 00000921 My %B1962  birthday%i1952#2062
     -| 0000093 Gregorian~Reformation\~is %y1752  years ago
     -| 0000Sep03 Gregorian~Reformation\~is %y1752 years ago
     -| 0 Every day in every month in every year
     -| 0000 Every day in every month in every year
     -| 00000000 Every day in every month in every year
     -| 199400fri        Every Friday in 1994
     -| 000007mo3 Every third Monday~in July every year less 1980%i#1979
     -| 0000@e-10 Easter Sunday-10 days every year
     -| 0@e-10 Easter Sunday-10 days every year
     -| 0000@e+10 Easter Sunday+10 days every year
     -| a=1127
     -| 0@a+20 20 days after date of date variable `a'
     -| a=*W10FR
     -| 0@a-1 The Thursday of the 10th week every year
     -| 0@a   The Friday of the 10th week every year
     -| 0@a1  The Saturday of the 10th week every year
     -| 1995*d10    The 10th absolute day in 1995
     -| 1995*d99tue The last Tuesday in 1995
     -| 0*w99su The Sunday of the last week every year
     -| ;
     -| ; Next entry is respected by ALL fixed date period modifiers.
     -| ;
     -| 1994*d1sun#99SUN.7 Each Sunday in 1994
     -| ;
     -| ; Day of Prayer & Repentance is Wednesday before the Sunday,
     -| ;   which is before the 1st Advent's Sunday.
     -| ;
     -| a=1225
     -| a=a-5sun
     -| 0@a-4 Day of Prayer & Repentance
     -| ; or
     -| 0@a-1wed Day of Prayer & Repentance

  And here is a resource file by the name of `demo-1.rc', used to detect
all Fridays the 13th of a year:

     $ cat demo-1.rc
     -| ; demo-1.rc
     -| ;
     -| $a=Friday the 13th%i0000
     -| $b=#0000
     -| $c=fri2
     -| $d=fri3
     -| 00000113 $a01$c$b01$c
     -| 00000113 $a01$d$b01$d
     -| 00000213 $a02$c$b02$c
     -| 00000213 $a02$d$b02$d
     -| 00000313 $a03$c$b03$c
     -| 00000313 $a03$d$b03$d
     -| 00000413 $a04$c$b04$c
     -| 00000413 $a04$d$b04$d
     -| 00000513 $a05$c$b05$c
     -| 00000513 $a05$d$b05$d
     -| 00000613 $a06$c$b06$c
     -| 00000613 $a06$d$b06$d
     -| 00000713 $a07$c$b07$c
     -| 00000713 $a07$d$b07$d
     -| 00000813 $a08$c$b08$c
     -| 00000813 $a08$d$b08$d
     -| 00000913 $a09$c$b09$c
     -| 00000913 $a09$d$b09$d
     -| 00001013 $a10$c$b10$c
     -| 00001013 $a10$d$b10$d
     -| 00001113 $a11$c$b11$c
     -| 00001113 $a11$d$b11$d
     -| 00001213 $a12$c$b12$c
     -| 00001213 $a12$d$b12$d

The result for the years 1996...2002 is as follows:

     $ gcal -H no -u -x -f ./demo-1.rc 1996+2002
     -|
     -| Fri, Sep  13th 1996: Friday the 13th
     -| Fri, Dec  13th 1996: Friday the 13th
     -|
     -| Fri, Jun  13th 1997: Friday the 13th
     -|
     -| Fri, Feb  13th 1998: Friday the 13th
     -| Fri, Mar  13th 1998: Friday the 13th
     -| Fri, Nov  13th 1998: Friday the 13th
     -|
     -| Fri, Aug  13th 1999: Friday the 13th
     -|
     -| Fri, Oct  13th 2000: Friday the 13th
     -|
     -| Fri, Apr  13th 2001: Friday the 13th
     -| Fri, Jul  13th 2001: Friday the 13th
     -|
     -| Fri, Sep  13th 2002: Friday the 13th
     -| Fri, Dec  13th 2002: Friday the 13th

  Or a bit shorter version of the resource file `demo-1.rc' by the name
of `demo-2.rc', likewise used to detect all Fridays the 13th of a year,
and that by using the fact, that a Friday the 13th only occurs if the
first day of a month is a Sunday:

     $ cat demo-2.rc
     -| ; demo-2.rc
     -| ;
     -| $a=%n+12 is a Friday%i0000
     -| $b=#0000
     -| $c=sun1
     -| 00000101 $a01$c$b01$c
     -| 00000201 $a02$c$b02$c
     -| 00000301 $a03$c$b03$c
     -| 00000401 $a04$c$b04$c
     -| 00000501 $a05$c$b05$c
     -| 00000601 $a06$c$b06$c
     -| 00000701 $a07$c$b07$c
     -| 00000801 $a08$c$b08$c
     -| 00000901 $a09$c$b09$c
     -| 00001001 $a10$c$b10$c
     -| 00001101 $a11$c$b11$c
     -| 00001201 $a12$c$b12$c

The result for the years 1996...2002 is as follows:

     $ gcal -H no -u -x -f ./demo-2.rc 1996+2002
     -|
     -| Sun, Sep   1st 1996: 13-Sep-1996 is a Friday
     -| Sun, Dec   1st 1996: 13-Dec-1996 is a Friday
     -|
     -| Sun, Jun   1st 1997: 13-Jun-1997 is a Friday
     -|
     -| Sun, Feb   1st 1998: 13-Feb-1998 is a Friday
     -| Sun, Mar   1st 1998: 13-Mar-1998 is a Friday
     -| Sun, Nov   1st 1998: 13-Nov-1998 is a Friday
     -|
     -| Sun, Aug   1st 1999: 13-Aug-1999 is a Friday
     -|
     -| Sun, Oct   1st 2000: 13-Oct-2000 is a Friday
     -|
     -| Sun, Apr   1st 2001: 13-Apr-2001 is a Friday
     -| Sun, Jul   1st 2001: 13-Jul-2001 is a Friday
     -|
     -| Sun, Sep   1st 2002: 13-Sep-2002 is a Friday
     -| Sun, Dec   1st 2002: 13-Dec-2002 is a Friday

Of course, preceding textual expense for the purpose of detecting all
Fridays the 13th of a year can be dramatically reduced by simply using
of

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

in the resource file `demo-1.rc', respectively,

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

in the `demo-2.rc' resource file.

On the one hand, preceding _one-liners_ reduce the coding expense quite
considerably --from 28 respectively 15 lines to 1 line in each case--,
but on the other hand, this partly increases the checking expense of
these _one-liners_ considerably and result in a longer program run-time
therefore.  Both _one-liners_ produce about 52 internal productions
respectively effective fixed date entries of themselves for each year
checked by Gcal, at which the `demo-1.rc' and `demo-2.rc' resource files
cause 24 respectively 12 effective fixed date entries only.

  And here is a resource file by the name of `demo-3.rc', used to detect
all working-days of any month:

     $ cat demo-3.rc
     -| ; demo-3.rc
     -| ;
     -| $a=%VWork day
     -| $c=%i#0000$b99
     -| a=$bmon1
     -| 0@a#+4 $a
     -| a=$btue1
     -| 0@a#+3 $a
     -| a=$bwed1
     -| 0@a#+2 $a
     -| a=$bthu1
     -| 0@a#+1 $a
     -| a=$bfri1
     -| 0@a $a
     -| a=$bmon2
     -| 0@a#+4 $a
     -| a=$bmon3
     -| 0@a#+4 $a
     -| a=$bmon4
     -| 0@a#+4 $a$c
     -| a=$bmon9
     -| 0@a#+4 $a$c

Respectively a bit shorter version of the resource file `demo-3.rc':

     ; demo-3.rc
     ;
     $a=%VWork day
     $c=%i#0000$b99
     0000$bmon1:5 $a
     0000$btue1:4 $a
     0000$bwed1:3 $a
     0000$bthu1:2 $a
     0000$bfri1:1 $a
     0000$bmon2:5 $a
     0000$bmon3:5 $a
     0000$bmon4:5 $a$c
     0000$bmon9:5 $a$c

And a resource file by the name of `include.rc' exists which is only
used to include one given resource file:

     $ cat include.rc
     -| #include "$f"

Then the result for the month August 1996 is as follows:

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

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

     00000001#0099 %V%rWork day

in the resource file `demo-3.rc'.

  And next the resource file by the name of `sun-1.rc' which detects
the actual local time, the approximate time of sunrise and sunset, day
and night length of two geographic locations:

     $ cat sun-1.rc
     -| ; sun-1.rc, comparison of sunrise / sunset, day length and night
     -| ; length of two locations, namely:  Muenster.DE / Bangkok.TH
     -| ; All references are based on Muenster.DE !
     -| ;
     -| ; Common definitions
     -| $p=0*d1#999
     -| $v=%2%4 for that places local time
     -| $z=actual local time in
     -| ; Definitions for winter time
     -| $a=%e#1980 %e0@a#0@b-1
     -| $x=Sun:~%o$c,$w rise, %s$c,$w set, %u$c,$w day, %z$c,$w night~$l
     -| ; Winter time in Germany == CEWT/GMT-1 (+60 minutes)
     -| $w=+60
     -| ; Starting date of winter time in Germany
     -| b=10sun9
     -| ; Definitions for summer time (daylight-saving time)
     -| $b=%e#1980 %i0@a#0@b-1
     -| $y=Sun:~%o$c,$s rise, %s$c,$s set, %u$c,$s day, %z$c,$s night~$l
     -| ; Summer time in Germany == CEST/GMT-2 (+120 minutes)
     -| $s=+120
     -| ; Starting date of summer time in Germany
     -| a=03sun9
     -| ; Geographic co-ordinate and name of the location Muenster, Germany
     -| $c=+5158+00738+61
     -| $l=%1Muenster
     -| ; Muenster's local time sunrise etc. for that places local time
     -| $p $a $x$v
     -| $p $b $y$v
     -| ; Muenster's actual local time
     -| 0 $a %1%@$w %2 $z $l
     -| 0 $b %1%@$s %2 $z $l
     -| ; Geographic co-ordinate and name of the location Bangkok, Thailand
     -| $c=+1345+10031+10
     -| $l=%3Bangkok%4-time converted to $l's%2 local time
     -| ; Bangkok's sunrise etc. based on Muenster's local time
     -| $p $a $x
     -| $p $b $y
     -| ; Bangkok's local time == WAST/GMT-7 (+420 minutes)
     -| $t=+420
     -| $w=$t
     -| ; Bangkok's actual local time
     -| $l=%3Bangkok
     -| 0 $a %3%@$t %4 $z $l
     -| 0 $b %3%@$t %4 $z $l
     -| ; Bangkok's sunrise etc. for that places local time
     -| $l=$l$v
     -| $p $x

The result for the 12th September 1999 is as follows:

     $ gcal -fsun-1.rc -Ux -Hno
     -|
     -| 18:53/12-Sep-1999 actual local time in Muenster
     -| 23:53/12-Sep-1999 actual local time in Bangkok
     -| Sun:
     -| 01:06rise, 13:22set, 12h16'day, 11h44'night
     -| Bangkok-time converted to Muenster's local time
     -| Sun:
     -| 06:06rise, 18:22set, 12h16'day, 11h44'night
     -| Bangkok for that places local time
     -| Sun:
     -| 06:56rise, 19:54set, 12h58'day, 11h02'night
     -| Muenster for that places local time

  The next example is the resource file `redir-1.rc' which demonstrates
the use of the shell command `%![ARGUMENT]' special text:

     $ cat redir-1.rc
     -| ; redir.rc, run shell command $c and redirect it to $f
     -| ;
     -| $p=0*d1#999
     -| $c=$p %!$c
     -| $g=|txt2gcal - $p
     -| ;
     -| $c $g>$f

The result of succeeding call of Gcal, to which you can also add the
`--debug=all' option for a better understanding of the execution
methods, is as follows:

     $ gcal --exe -QUx -f./redir-1.rc+XX -r'$f=XX:$c=echo $f' -#'0 %!rm $f'
     -| XX

  And finally a resource file by the name of `swtim-1.rc' which produces
fixed date messages reminding Daylight Saving that are valid since 1981
for the Federal Republic of Germany(1) (*note Resource file
examples-Footnote-1::).

     $ cat swtim-1.rc
     -| ; swtim-1.rc, daylight-saving time BRD
     -| ;
     -| $a=daylight-saving time starts Sunday
     -| ;
     -| a=03sun9
     -| 0@a-2#+2 Summer $a~+1 hrs. (02:00 --> 03:00 h.)%i1981
     -| ;
     -| a=09sun9
     -| 0@a-2#+2 Winter $a~-1 hrs. (03:00 --> 02:00 h.)%i1981#1995
     -| ;
     -| a=10sun9
     -| 0@a-2#+2 Winter $a~-1 hrs. (03:00 --> 02:00 h.)%i1996

The result for the year 1998 is as follows:

     $ gcal %1998 -Hno -xy -f ./swtim-1.rc
     -|
     -| Fri, Mar  27th 1998: Summer daylight-saving time starts Sunday
     -|                      +1 hrs. (02:00 --> 03:00 h.)
     -| Sat, Mar  28th 1998: Summer daylight-saving time starts Sunday
     -|                      +1 hrs. (02:00 --> 03:00 h.)
     -| Sun, Mar  29th 1998: Summer daylight-saving time starts Sunday
     -|                      +1 hrs. (02:00 --> 03:00 h.)
     -| Mon, Mar  30th 1998: Summer daylight-saving time starts Sunday
     -|                      +1 hrs. (02:00 --> 03:00 h.)
     -| Tue, Mar  31st 1998: Summer daylight-saving time starts Sunday
     -|                      +1 hrs. (02:00 --> 03:00 h.)
     -| Fri, Oct  23rd 1998: Winter daylight-saving time starts Sunday
     -|                      -1 hrs. (03:00 --> 02:00 h.)
     -| Sat, Oct  24th 1998: Winter daylight-saving time starts Sunday
     -|                      -1 hrs. (03:00 --> 02:00 h.)
     -| Sun, Oct  25th 1998: Winter daylight-saving time starts Sunday
     -|                      -1 hrs. (03:00 --> 02:00 h.)
     -| Mon, Oct  26th 1998: Winter daylight-saving time starts Sunday
     -|                      -1 hrs. (03:00 --> 02:00 h.)
     -| Tue, Oct  27th 1998: Winter daylight-saving time starts Sunday
     -|                      -1 hrs. (03:00 --> 02:00 h.)


File: gcal.info,  Node: Resource file examples-Footnotes,  Up: Resource file examples

  (1) Two days before adaptation till two days after adaptation.


File: gcal.info,  Node: Todays Calendar,  Next: Gcal Utilities,  Prev: Fixed Dates,  Up: Top

Genesis of the Gregorian Calendar
*********************************

  The nowadays calendar was first formulated in several inaccurate
variations by the Romans based on methods developed by the Babylonians
and Egypts.  The aim of all these calendars was to harmonize the cycles
of the Moon and the Sun.  During Julius Caesar's reign, January was
falling in autumn so he ordered Sosigenes to make changes to the
calendar.  He added 90 days to the year 46 BC to make up for the
seasonal drift and adjusted the lengths of the months similarly as we
know them to be today.  He introduced the leap year by adding one day
to February every four years.  For the present, the leap year
regulation was made in the way that all four years after the 23rd day in
February a leap day was laid in, so the 24th February occurred twice.
The use of the leap year was an improvement but not entirely accurate.

  But in the later years, the leap rule was used in the wrong way so
that the errors are corrected by emperor Augustus in the year 8 BC.  A
curious sequel happened on this occasion.  Because Augustus reacted
with great jealousy to all things previously made and propagated by
Julius Caesar, he did not like Caesar's name in the calendar, namely
the today's month of *July*.  Offhandedly he ordered to name another
month to himself and so the month name *August* arose.  Furthermore,
Augustus did not tolerate the fact that his month of birth (the August)
was shorter than Caesar's month in the sense of the periodical sequence
of months with 30 and 31 days.  Consequently, the month of August got
31 days, too.  Due to this modification, the number of days in February
were reduced to 28 and 29 days, respectively, so the 29th February was
designed to be the leap day now.

  This calendar is well known under the term "Julian calendar" and is
based on a plain solar year.  The nominal length of a solar year
(respectively a so-called tropical year) is 365 days, 5 hours, 48
minutes, and 46 seconds.  One 366-day year every four years equates to
an average Julian year of 365 days and 6 hours, consequently to 365.25
days.  This means, every four years, an error of 44 minutes, 56 seconds
was accumulated by this kind of calendar calculation.  Because of this
counting method, the length of the years becomes a bit too long, by
more than 11 minutes.

  By the 16th century, the vernal equinox occurred around March 11,
rather than March 21, by reason of an accumulated error of ten days.
The feast of Easter shifted away more and more from the habitual vernal
date, which must have always been celebrated on an earlier date.  So
Pope Gregory XIII introduced the new style calendar in 1582.  Thursday,
the 4th October 1582, was followed by Friday, the 15th October, by
suppressing the ten days between both dates.  Moreover, he ordained
that years ending in hundreds should not be leap years unless they are
divisible by 400.  Incidentally, the Gregorian reform compensates by 72
hours (3 days) every 400 years.  The actual excess accumulated is 74
hours, 53 minutes and 20 seconds.  The error of 2 hours, 53 minutes and
20 seconds every 400 years accumulates to one day in about 3300 years.
Thereby, the Gregorian year has an average length of 365.2425 days.

  But this "Gregorian calendar" was accepted very slowly by others.
Catholic countries adopted the Gregorian calendar almost immediately.
Most Protestant countries on the Continent adopted the new calendar
around 1700.  England and the American colonies changed in 1752, by act
of Parliament.  Orthodox Christian countries adopted the Gregorian
calendar later.  Russia was the last European country to do so, after
the communist revolution of 1917.  As a result, the former U.S.S.R.
celebrated the October Revolution (happened on October 25th, 1917) in
the old style calendar on November 7th.

  The era of a world wide uniform calendar is already part of history
today.  The Iran returned to the traditional Mohammedan lunar calendar
in 1979 after removal of the Shah reign.  There are some efforts to
improve our currently valid Gregorian calendar.  Its disadvantages are
the reason why an appointed day is not always on the same week day.
Besides, the month lengths are not equal and the holidays, which have
relations to the feast of Easter, are moved within the calendar from
one year to another.  A very sophisticated suggestion was proposed by
the United Nations, but the international establishment of this
suggestions has failed, since it was resisted by some countries as well
as the churches.


File: gcal.info,  Node: Gcal Utilities,  Next: Internationalization,  Prev: Todays Calendar,  Up: Top

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

* Menu:

* Invoking tcal::      How to run `tcal' and a summary of its options.
* Invoking txt2gcal::  How to run `txt2gcal' and a summary of its options.
* Invoking gcal2txt::  How to run `gcal2txt' and a summary of its options.

  Three small utility programs are part of the Gcal 3.01 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.


File: gcal.info,  Node: Invoking tcal,  Next: Invoking txt2gcal,  Prev: Gcal Utilities,  Up: Gcal Utilities

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

  The Tcal program runs the Gcal program with the date of tomorrow's
day(1) (*note Invoking tcal-Footnote-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 (*note Environment Variable
`GCALPROG': x-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 the Tcal program-- is used for calling the Gcal
program.  The `GCALPROG' environment variable must always be set if the
Gcal program is installed under another name than the standard name
`gcal', otherwise Tcal is unable to execute the Gcal program
automatically!  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.


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

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


File: gcal.info,  Node: Invoking txt2gcal,  Next: Invoking gcal2txt,  Prev: Invoking tcal,  Up: Gcal Utilities

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 a single `-' character, 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 us suppose there is a
text file by the name of `tdemo-1.txt' with the following contents:

     $ cat tdemo-1.txt
     -|         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
`tdemo-1.rc':

     $ txt2gcal tdemo-1.txt 0*d1#999 > tdemo-1.rc
     $ cat tdemo-1.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 `tdemo-1.rc'
from the text file `tdemo-1.txt'.  Let us finally see, how Gcal will
interpret this new resource file:

     $ gcal %19960101 -H no -Ax -f ./tdemo-1.rc
     -|
     -| Mon, Jan   1st 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'.
     -|


File: gcal.info,  Node: Invoking gcal2txt,  Prev: Invoking txt2gcal,  Up: Gcal Utilities

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 a single `-' character,
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 into the output by means of the Txt2gcal program.

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 us
use the resource file `tdemo-1.rc' of the previous section (*note
Invoking `txt2gcal': Invoking txt2gcal.), which was created by means of
the Txt2gcal program from a text file and which looks like this:

     $ txt2gcal tdemo-1.txt 0*d1#999 > tdemo-1.rc
     $ cat tdemo-1.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 us see, how this resource file will be processed by Gcal2txt:

     $ gcal2txt tdemo-1.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'.


File: gcal.info,  Node: Internationalization,  Next: Metasymbols,  Prev: Gcal Utilities,  Up: Top

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.  *Note Introduction: (gettext)Top, 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 3.01 supports the following
native languages:

*Native Language*        *Language Code*

English                  `en'
German                   `de'
French                   `fr'
Dutch                    `nl'
Polish                   `pl'
Russian                  `ru'
Swedish                  `sv'

It is only necessary to set one of the environment variables(1) (*note
Internationalization-Footnote-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.  *Note
The User's View: (gettext)Users, 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) (*note Internationalization-Footnote-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, the type of week number and the representation of calendar
sheets, these criteria are likewise bound to the language code(3)
(*note Internationalization-Footnote-3::).

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

   * U.S. American date format

   * Gregorian Reformation has occurred 1752

   * Week starts on Sunday

   * Standard week numbers

   * 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) (*note Internationalization-Footnote-4::)
causes the following internal defaults:

   * German date format

   * Gregorian Reformation has occurred 1582

   * Week starts on Monday

   * ISO-8601:1988 week numbers

   * 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',
`--iso-week-number' and `--type'.

  If no language code is detected, Gcal takes the internal defaults of
the `en' language code(5) (*note Internationalization-Footnote-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) (*note
Internationalization-Footnote-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é Europén de Normalisation):
          LANGUAGE[_TERRITORY][+AUDIENCE][+SPECIAL][,SPONSOR][_REVISION]

  Both syntaxes 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.


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

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


File: gcal.info,  Node: Metasymbols,  Next: Regular Expressions,  Prev: Internationalization,  Up: Top

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.


File: gcal.info,  Node: Regular Expressions,  Next: Regexp Summary,  Prev: Metasymbols,  Up: Top

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

* Menu:

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

  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!


File: gcal.info,  Node: Regexp Usage,  Next: Regexp Operators,  Prev: Regular Expressions,  Up: Regular Expressions

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.

  *Note Fixed date option `--filter-text=PATTERN': x-filter-text, 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) (*note Regexp
Usage-Footnote-1::).


File: gcal.info,  Node: Regexp Usage-Footnotes,  Up: Regexp Usage

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

