This is Info file en/gcal.info, produced by Makeinfo-1.64 from the
input file en/gcal.texi.

START-INFO-DIR-ENTRY
* Gcal: (gcal).              The GNU calendar program.
END-INFO-DIR-ENTRY

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

  Copyright (C) 1994, 1995, 1996 Thomas Esken

  This is the first edition of the Gcal documentation.

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

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

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

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

                                \\\_''/'
-------------------------oOO    (/o-o\)    OOo-------------------------
Thomas Esken                o  (.  "  .)  o   Internet :
Im Hagenfeld 84              \___) ~ (___/      (esken@uni-muenster.de)
D-48147 M"unster; GERMANY                     Phone    : +49 251 232585


File: gcal.info,  Node: Lists of commands,  Next: Ranges of commands,  Prev: 3-Month mode commands,  Up: Commands

Lists of Commands
.................

`MM,...,MM'
     List of specified months in current year, e.g.:

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

`MM/YYYY,...,MM/YYYY'
     List of months in specified year, e.g.:

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

`MM,...,MM YYYY'
     List of specified months of selected year, e.g.:

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

`YYYY;...;YYYY'
     List of specified years, e.g.:

          gcal 1992;1777;1899

`MM:YYYY;...;MM:YYYY'
     List of specified fiscal years, e.g.:

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

*Other valid lists:*

`MM,MM/YYYY,...'
     Mixed list of months consisting of: `MM MM/YYYY'

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

`MM:;MM:YYYY;...'
     Mixed list of fiscal years of given / actual year consisting of:
     `MM: :YYYY MM:YYYY YYYY'

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

`MM:;MM:;...'
     List of fiscal years of actual year consisting of: `MM:'

          gcal 3:;august:;DEC:


File: gcal.info,  Node: Ranges of commands,  Prev: Lists of commands,  Up: Commands

Ranges of commands
..................

`MM-MM'
     Range of current months, e.g.:

          gcal 3-7
          gcal 11-8
          gcal MAY-dec
          gcal 12-aug

`MM/YYYY-MM/YYYY'
     Range of months of year, e.g.:

          gcal 3/1991-july/1992
          gcal dec/1994-3
          gcal sep-dec/2000

`MM-MM YYYY'
     Range of specified months of selected year, e.g.:

          gcal 3-7 1999
          gcal nov-3 1777
          gcal aug-dec 1992

`MM YYYY-YYYY'
`MM/YYYY-YYYY'
     Range of specified month of selected years, e.g.:

          gcal AUGUST 1494-1497
          gcal 3/1993-1999
          gcal nov/3-1777

`YYYY+YYYY'
     Range of specified years, e.g.:

          gcal 1992+1994

`MM:YYYY+MM:YYYY'
     Range of specified fiscal years, e.g.:

          gcal 7:1999+8:1992
          gcal aug:1992+july:1999


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

The `GCAL' environment variable
===============================

  The environment variable `GCAL' can hold a set of default options for
Gcal (*note GCAL: Environment variables.).  These options are
interpreted first at program start-up and some can be overwritten by
explicit command line arguments or values which are found in a response
file option `@FILE'.  *Note Command line arguments::, and *Note
Response file::.

For example:

   * for *sh*:
          GCAL="-i @colour -b 3"; export GCAL

   * for *csh*:
          setenv GCAL "-i @colour -b 3"

   * for *MS-DOS*:
          set GCAL=-i @colour -b 3

  On Vax/VMS, the name of the environment variable is `GCAL_OPT', to
avoid a conflict with the symbol `GCAL' set for invocation of the
program.

For example:

   * for *VMS*:
          define GCAL_OPT "-i @colour -b 3"


File: gcal.info,  Node: Eternal holidays,  Next: Fixed date warnings,  Prev: Invoking Gcal,  Up: Top

Eternal holidays
****************

The *eternal holiday list* is created only for dates after A.D.463.
It can be displayed in different ways:

  In case you start Gcal without an explicit (fiscal) date and the
*eternal holiday list* argument (*note `--holiday-list[=long|short]':
Calendar options.), e.g.:

     gcal --holiday-list
     gcal -n
     gcal -n :

Gcal displays all holidays of the eternal holiday list, that refer to
the actual / fiscal year without a leading calendar.

  In case you start Gcal with the *eternal holiday list* argument and a
month (plus an additional year), e.g.:

     gcal --holiday-list july
     gcal -n july
     gcal -n 7 1993
     gcal -n 7/1993

Gcal displays a month calendar of the specified month (of year) and
trailing those holidays of the eternal holiday list, that refer to the
given month (of given year).

  In case you start Gcal with the *eternal holiday list* argument and a
simple year or an explicit fiscal year, e.g.:

     gcal --holiday-list 1993
     gcal -n 1993
     gcal -n july:
     gcal -n :1993
     gcal -n 7:1993

Gcal displays a year calendar of the specified year or fiscal year and
trailing all holidays of the eternal holiday list, that refer to the
given year or fiscal year.

  In case you start Gcal with the *eternal holiday list* argument and a
special 3-Month mode command (*note `. YYYY': 3-Month mode commands.),
e.g.:

     gcal --holiday-list .
     gcal -n .
     gcal -n ..
     gcal -n .+
     gcal -n .-

Gcal displays the according three months using a fixed year calendar
style and trailing all holidays of the eternal holiday list, that refer
to the these months.

  In case you start Gcal with the *eternal holiday list* argument and a
*list* or *range* of commands, it produces the according series of
eternal holiday lists.  *Note `MM,...,MM': Lists of commands, and *Note
`MM-MM': Ranges of commands, for more details.


File: gcal.info,  Node: Fixed date warnings,  Next: Todays calendar,  Prev: Eternal holidays,  Up: Top

Fixed date warnings
*******************

* Menu:

* Resource file::           How to use a Resource file.
* Resource file examples::  Examples of Resource file entries.

  This chapter describes how to use the *fixed date warning* feature of
Gcal.  For that purpose, you may create a Gcal resource file for
showing fixed dates/appointments (*note Resource file::.).

  Each time you execute Gcal in simple single month mode, i.e. no
explicit month, year or fiscal year is given in the command line, but
the *fixed date warning* argument, e.g.:

     gcal --list-of-fixed-dates
     gcal -c

it checks the resource file for dates and processes those that refer to
the actual (==todays) date.  Then Gcal displays all fixed date warnings
found in the resource file, that refer to the actual day
(week/month/year) of the actual year without a leading calendar.

Some more examples:

     gcal -ce
     gcal -cw-
     gcal -c-m
     gcal -c-y-
     gcal -jcb -c-et
     gcal -cey-
     gcal -jc -cey

The fixed date warnings can be displayed in different ways:

  In case you start Gcal with the *fixed date warning* argument and/or
a month and/or an explicit year or fiscal year; respectively with the
special 3-Month mode command, e.g.:

     gcal -c july
     gcal -ce 7 1994
     gcal -c-y 7/1994
     gcal -c 7:1993
     gcal -c 1993
     gcal -c .
     gcal -c .+

Gcal displays a (three) month / year calendar of the specified
respectively actual month / year and trailing those fixed date warnings
found in the resource file, that refer to the given period; the warning
level is same as `-cy' option if the warning period refers to a year or
fiscal year or to a three month period respectively is same as `-cm'
option if the warning period refers to a month.

  In case you start Gcal without an explicit date and the *fixed date
warning* argument *in connection with* the *eternal holiday list*
argument, e.g.:

     gcal -c -n
     gcal -Cm -n
     gcal -Cl1224 -n
     gcal -cl3+ -n

then Gcal displays all fixed date warnings found in the resource file,
that refer to the requested period and trailing all holidays of the
eternal holiday list that refer to the whole actual year without a
leading calendar.  For more details how to use an *eternal holiday
list*, see *Note Eternal holidays::.

*Annotation to previous examples:*

  In case an additional *standard/special calendar format* argument or
an additional *starting day of week* argument (except the
`--starting-day=today' respectively the `--starting-day=0' option) is
found in the command line, e.g.:

     gcal -c -n -i
     gcal -c -i-
     gcal -n -i- :
     gcal -n -s Sunday

Gcal displays a leading month, year or fiscal year calendar before all
other lists.  *Note `--type=special|standard': Calendar options, and
*Note `--starting-day[=ARGUMENT]': Calendar options, for more
information.

  Each time you execute Gcal in simple single year mode, i.e. no
explicit month, year or fiscal year is given in the command line, but
the *fixed date warning* argument (with optional modifiers) and the
*number of blocks* argument (*note `--blocks=NUMBER': Calendar
options.), e.g.:

     gcal -c --blocks=3
     gcal -C-em -b 3
     gcal -c-t -b 6 -jc

it checks the resource file for dates and processes those that refer to
the actual (==todays) date!  Gcal displays a leading year calendar and
all fixed date warnings, found in the resource file, that refer to the
actual day (week/month/year) of the actual year.

  You can list fixed date warnings of past, present or future
month/years, too.  This can be done on the one hand, if you use the
`%DATE' option in the fashion you require (*note Actual date
modifier::.), and on the other hand, if a command respectively a *list*
or *range* of commands is used.

For example:

`gcal -c -n- 1993'
     Lists all fixed dates of entire 1993 in ascending order, and the
     eternal holiday list of entire 1993 in descending order; the
     warning level is same as `-cy' option.

`gcal -c- july:1993'
     Lists all fixed dates related to fiscal year - starting in July
     1993 and ending in June 1994 - in descending order; the warning
     level is same as `-cy' option.

`gcal -ce july 1993'
     Lists all fixed dates related to July 1993 inclusive all eternal
     holidays merged into this list in ascending order; the warning
     level is same as `-cm' option.

`gcal -c-e -n 1993+1996'
     Lists all fixed dates related to entire 1993, 1994, 1995 and 1996
     (series of years) inclusive all eternal holidays merged into this
     list in descending order, and the eternal holiday list related to
     all above years in ascending order; the warning level is same as
     `-cy' option.


File: gcal.info,  Node: Resource file,  Next: Resource file examples,  Prev: Fixed date warnings,  Up: Fixed date warnings

Resource file
=============

* Menu:

* Structure of resource file::    How to write a Resource file.
* Date part of a line::           How to write the Date part.
* Further date part attributes::  What are Further date part attributes?
* Text part of a line::           How to write the Text part.
* Comment line::                  What is a Comment line?
* Include directives::            What are Include directives.
* Special macro texts::           What is a Special macro text.
* Date variables::                How Date variables can be used.
* Text variables::                How Text variables can be used.

  This sections describes how to use a "resource file", which contains
fixed dates and appointments.  The name of the standard resource file is
`~/.gcalrc' (1).

Gcal uses a special file searching mechanism:

  1. The Gcal program expects the standard resource file that
     directory, which is referenced in the environment variable `HOME'.
     If no `HOME' environment variable is defined and set, Gcal omits
     this step.  *Note HOME: Environment variables.

  2. If the above action fails, Gcal scans the directories, which are
     referenced in the environment variable `GCALPATH' (*note GCALPATH:
     Environment variables.) for the standard resource file.  The
     `GCALPATH' environment variable contains a (`:') (2)
     colon-separated list of directories.  If no such environment
     variable is defined and set, Gcal omits this step.

  3. If the above action fails, Gcal inspects the *user data* directory
     (normally `$HOME/share/gcal') to find the standard resource file.
     This directory is a directory relative to the `HOME' directory.
     If an environment variable `GCAL_USR_DATADIR' is set, Gcal appends
     the contents of this environment variable to the contents of the
     `HOME' environment variable and tries to use that directory first
     instead of using the burned-in default name of that directory
     (*note GCAL_USR_DATADIR: Environment variables.).  If no `HOME'
     environment variable is defined and set, Gcal omits this step.

  4. If all above actions fail, Gcal inspects the *system data*
     directory (normally `/usr/local/share/gcal' or
     `$(prefix)/share/gcal') to find the standard resource file.  This
     directory is a directory absolute the *root*/*$(prefix)*
     directory.  If an environment variable `GCAL_SYS_DATADIR' is set,
     Gcal tries to use that directory first instead of using the
     burned-in default name of that directory (*note GCAL_SYS_DATADIR:
     Environment variables.).

  If the standard resource file is not found during steps 1...4 of the
file searching mechanism, no fixed date warnings will be created!

  If a `-f|F NAME[+...]' respectively `--resource-file=NAME' command
line argument is given, a file NAME will be used for the resource file
instead of the standard resource file.  *Note `--resource-file=NAME':
Date warning options.

  An "extended file name" contains one ore more `/' (3) (slash)
characters and denotes a file, which fixed access path either starts
from the root directory, like `/foo/bar/file', or from the actual
directory, like `./bar/file' or `../bar/file'.  If NAME is an extended
file name:

     In case file NAME is found, Gcal will use it.
     In case file NAME is not found, Gcal will not use it.

  A "simple file name" does denote a file, which access path doesn't
either starts from the root directory or from the actual directory, like
`file' or `bar/file'.  If NAME is a simple file name:

     Gcal tries to find this file NAME using the previously explained
     file searching mechanism.

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

  (1)  On MS-DOS, OS/2 and some other operating systems, the name of
the *standard* resource file is `~/gcalrc'.

  (2)  On MS-DOS, OS/2 and some other operating systems, another
character will be used, e.g. `;' on MS-DOS and OS/2.

  (3)  Operating systems like MS-DOS or OS/2 use the `\' (Backslash)
character for separating a directory from a file name.


File: gcal.info,  Node: Structure of resource file,  Next: Date part of a line,  Prev: Resource file,  Up: Resource file

Structure of resource file
--------------------------

  First of all, a Gcal resource file is a plain ASCII text file.  This
text file may be created by any text editor or by redirecting the
*standard output channel* to a file, e.g.:

     $ echo '19930217 Text'>> resource-file RET

  A special but simple line structure is required so Gcal is able to
interpret its contents.  Each fixed date warning entry in a resource
file must be splitted into two parts, namely a *date part* and an
optional *text part*, which *must* be separated by *one* "whitespace"
character (Tab, Space, Form-Feed ...) minimum.  It's not necessary to
give a whitespace separator character if no *text part* is specified.

  A line must always end with a `\n' (newline) character, except it's
the last line of a resource file.  The maximum length of a line is
limited to INT_MAX (1) characters.  A newline character is
automatically appended to the line if the *standard output channel* is
directed to a file.  A newline character is appended to the typed line
in a text editor window if it is completed by pressing the RET key.  In
case the used text editor doesn't generate the newline character in
this way, it should be set to this mode of operation, otherwise this
text editor is useless for creating Gcal resource files.

The line structure of fixed date warning entries is:

     DATE PART [ *whitespace* TEXT PART ] *newline*

or more concrete, e.g.:

     YYYY[MM[DD|WWW[N]]] [ *whitespace* TEXT ] *newline*

or much more concrete, e.g.:

     19940217 Hi, I'm the text!

Besides fixed date warning entries, a resource file may contain further
entries like:

Include directives...

     #include <FILE NAME>
     #include "FILE NAME"

Date variable assignments respectively operations...

     DVAR=NOTHING
     DVAR=MMDD
     DVAR=MMWWWN
     DVAR=*dN[WWW]
     DVAR=*wN[WWW]
     DVAR=DVAR[[+|-]N[WWW]]
     DVAR++
     DVAR--
     DVAR+=N[WWW]
     DVAR-=N[WWW]

Text variable assignments...

     TVAR=[TEXT]

Text variable references...

     TVAR

  Text variable references in the beginning of a Gcal resource file line
may only be used if it is ensured that they are expanded to a valid Gcal
resource file line.

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

  (1)  Normally, this is for example equivalent to a value of 32,767 ==
(2^15)-1 on a 16-Bit machine architecture; to a value of 2,147,483,648
== (2^31)-1 on a 32-Bit machine architecture etc.


File: gcal.info,  Node: Date part of a line,  Next: Further date part attributes,  Prev: Structure of resource file,  Up: Resource file

Date part of a line
-------------------

  The structure of a "date part" - which gives Gcal the information at
which date a fixed date happens - of a line in the resource file is

*Either*: `YYYY[MM[DD|WWW[N]]]'

    `YYYY'
          (4 digits), is the year including the century (range
          0000...9999).  Leading zeroes are required in case given year
          is less than 1000 and other components of the date part are
          trailing the year.

    `MM'
          (2 digits or 3 characters), is the month (range 00...12 or
          99, respectively Jan, Feb...).  A given 99 for the month
          means the last month of the year (== December).  Leading
          zeroes are required in case given month is less than 10 and
          other components of the date part are trailing the month.

    `DD'
          (2 digits), is the day (range 00...31 or 99).  A given 99 for
          the day means the last day of the month.  Leading zeroes are
          required in case given day is less than 10 and other
          components of the date part are trailing the day.

    `WWW'
          (2...3 characters), is a short weekday name (range Mon...Sun).

    `N'
          (1 digit), is the N'th weekday WWW of month (range 1...5 or
          9).

             * N == 1...5
               N'th weekday WWW of month.

             * N == 9
               Last weekday WWW of month.

*Or*: `YYYY*d|wN[WWW]'

    `YYYY'
          (4 digits), is the year including the century (range
          0000...9999).  Leading zeroes are required in case given year
          is less than 1000 and other components of the date part are
          trailing the year.

    `*d'
          (2 characters), is the reference to an ordinary date.

    `*w'
          (2 characters), is the reference to a date of an
          ISO-8601:1988 week.

    `N'
          (1...3 digits), is the value in days or in weeks, the fixed
          date occurs.  A given 99 in connection with a short weekday
          name means the last weekday WWW of the year.  A given 999 in
          connection with `*d' means the last day of a year, i.e. the
          31st December.  If the computed date doesn't occur in year,
          i.e. exceeds the year bounds, the fixed date warning message
          is suppressed.

    `WWW'
          (2...3 characters), is a short weekday name (range Mon...Sun).

*Or*: `YYYY@e|DVAR[[+|-]N]'

    `YYYY'
          (4 digits), is the year including the century (range
          0000...9999).  Leading zeroes are required in case given year
          is less than 1000 and other components of the date part are
          trailing the year.

    `@e'
          (2 characters), is the reference to the Easter Sunday's date.

    `@DVAR'
          (2 characters), is the reference to a date variable.

    `[+|-]N'
          (1...4 alphanumeric characters), is the optional displacement
          value in days, the fixed date occurs relative to the Easter
          Sunday's date or date variables date.  A given -999 means the
          first day of a year, i.e. the 1st January.  A given +999 or
          999 means the last day of a year, i.e. the 31st December.  If
          the computed date doesn't occur in year, i.e. exceeds the year
          bounds, the fixed date warning message is suppressed.

*Or*: `YYYY@e|DVAR[+|-]NWWW'

    `YYYY'
          (4 digits), is the year including the century (range
          0000...9999).  Leading zeroes are required in case given year
          is less than 1000 and other components of the date part are
          trailing the year.

    `@e'
          (2 characters), is the reference to the Easter Sunday's date.

    `@DVAR'
          (2 characters), is the reference to a date variable.

    `[+|-]NWWW'
          (3...7 alphanumeric characters), is the optional displacement
          value in weekdays, the fixed date occurs relative to the
          Easter Sunday's date or date variables date.  A given -99
          means the first weekday WWW of the year.  A given +99 or 99
          means the last weekday WWW of the year.  If the computed date
          doesn't occur in year, i.e. exceeds the year bounds, the
          fixed date warning message is suppressed.

*Please note:*

   * If YYYY is specified as 0000:
     The month and day are assumed to be annual events and the *text
     part* will be displayed for any year.

   * If MM is not given or specified as 00:
     The day is assumed to be a monthly event for the specified year
     and the *text part* will be displayed for any month.

   * If DD is not given or specified as 00:
     Each day is assumed to be a daily event for the specified year and
     month and the *text part* will be displayed for any day.

   * If WWW is specified as a short (2...3 characters) weekday name,
     e.g. `Mon, Tue...':
     The given weekday name is assumed to be a weekly event for the
     specified year and month and the *text part* will be displayed for
     any week.


File: gcal.info,  Node: Further date part attributes,  Next: Text part of a line,  Prev: Date part of a line,  Up: Resource file

Further date part attributes
----------------------------

* Menu:

* Lists of days::              How Lists of days can be used.
* Ranges of days::             How Ranges of days can be used.
* Repetition factor of days::  How to use such a factor.
* Appearance factor of days::  How to use such a factor.

  The date part of a Gcal resource file may be provided with further
attributes, which are either specifications of lists of days or ranges
of days, which provide the information at which date a fixed date
happens.  More further attributes are the repetition factor as well as
the appearance factor.

All date parts of a Gcal resource file, which are structured as
follows, may be provided generally with further attributes:

   * `YYYYMM...'

   * `YYYY*d|w...'

   * `YYYY@e|DVAR...'

*Attention:*
If the date part is supplied with further attributes and the year of
the fixed date is not given in a concrete manner, i.e. the year `YYYY'
is set to zero, such kinds of fixed dates are *only* computed correctly
in simple year bounds, which means during a current year, not in fixed
dates shown after the current year has changed, e.g. in *fiscal years*.


File: gcal.info,  Node: Lists of days,  Next: Ranges of days,  Prev: Further date part attributes,  Up: Further date part attributes

Lists of days
.............

  A list of days is specified by a `,' separator character; it must
contain two elements minimum and may have any number of elements.  A
single element of the list may not be set to a zero value and be
unconcrete therefore, which wouldn't make any sense in this coherence.

  A list of days is used to define recurrent fixed dates and to use
only one line in the resource file for them, instead of using several
lines in a resource file needed for defining these recurrent fixed
dates separately.  Assuming a fixed date shall always occur on the 1st
and the 15th day in every month of the year 1996, e.g. `Tax returns',
one solution would be on the one hand a fixed date entry in the
resource file for the 1st of the month and another entry for the 15th
of the month, which would be a total of two entries in the resource
file for such a fixed date.

  On the other hand, this expense can be reduced to a total of only one
entry in the resource file by using a list of days, which is likewise
valid for the 1st and the 15th day in every month, that is

     19960001,15 Tax returns

  The use of lists of days in the date part is permitted as follows:

   * `YYYYMMDD|WWW|WWWN,[MM]DD|[MM]WWW|[MM]WWWN ...'

   * `YYYY*d|wN|NWWW,N|NWWW ...'

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

  Some examples to this:

`000001fr3,12,99,mon,apr14,993,julfri3,08fr'
     In every year in January: on the 3rd Friday, on the 12th, on the
     last day of the month and on every Monday.  And in every year: on
     the 14th April, on the 3rd December, on the 3rd Friday in July and
     on every Friday in August.

`199600mon,fr,12'
     In the year 1996 in every month: on every Monday, on every Friday
     and on the 12th.

`0*d1,1fr,999,17mo'
     In every year: on the first day of the year, on the 1st Friday of
     the year, on the last day of the year and on the 17th Monday of
     the year.

`1996*w1fr,1,17mo,99fr'
     In the year 1996: on Friday of the 1st ISO-week, on Monday of the
     first ISO-week, on Monday of the 17th ISO-week and on Friday of
     the last ISO-week.

`0@a,+1,-3,5,+4fr,2fr,-10sa'
     In every year: on the date of the date variable A, one day after
     the date of A, three days before the date of A, five days after the
     date of A, four Fridays after the date of A, two Fridays after the
     date of A and ten Saturdays before the date of A.

`1996@e+1,-3,5,+4fr,2fr,-10sa'
     In the year 1996: one day after the Easter Sunday's date, three
     days before the Easter Sunday's date, five days after the Easter
     Sunday's date, four Fridays after the Easter Sunday's date, two
     Fridays after the Easter Sunday's date and ten Saturdays before
     the Easter Sunday's date.


File: gcal.info,  Node: Ranges of days,  Next: Repetition factor of days,  Prev: Lists of days,  Up: Further date part attributes

Ranges of days
..............

  A range of days is specified by a `#' separator character and must
consist of two elements, namely the starting day and the final day.
The starting day and likewise the final day of the range may not be set
to a zero value and be unconcrete therefore, which wouldn't make any
sense in this coherence.

  A range of days just as a list of days is used to define recurrent
fixed dates and to use only one line in the resource file for them,
instead of using several lines in a resource file needed for defining
these recurrent fixed dates separately.  Assuming a fixed date shall
always occur during the 1st and the 15th day (inclusive) in every month
of the year 1996, e.g.  `Inside work', one solution would be on the one
hand a fixed date entry in the resource file for the 1st of the month,
another one for the 2nd of the month until the 15th of the month, which
would be a total of 15 entries in the resource file for such a fixed
date (apart from the possibility, that a list of days can be used in
such a case).

  On the other hand, this expense can be reduced to a total of only one
entry in the resource file by using a range of days, which is likewise
valid for the 1st until the 15th day in every month, that is

     19960001#15 Inside work

  The use of ranges of days in the date part is permitted as follows:

   * `YYYYMMWWW#WWW'

   * `YYYYMMDD|WWWN#[MM]DD|[MM]WWWN'

   * `YYYY*d|wN[WWW]#N[WWW]'

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

  Some examples to this:

`199600mon#fr'
     In the year 1996 in every month: every day that appears within the
     day sequence `mon, tue, wed, thu, fri'.

`000000fr#mon'
     In every year in every month: every day that appears within the day
     sequence `fri, sat, sun, mon'.

`000001fr3#12'
     In every year in January: every day that appears within the period
     of the 3rd Friday of the month until the 12th of the month.

`00000112#fr3'
     In every year in January: every day that appears within the period
     of the 12th of the month until the 3rd Friday of the month.

`00000112#augfri3'
     In every year: every day that appears within the period of the
     12th January until the 3rd Friday of August.

`0000sep13#99fr9'
     In every year: every day that appears within the period of the
     13th September until the last Friday of December.

`0*d1#1fr'
     In every year: every day that appears within the period of the 1st
     day of the year until the 1rd Friday of the year.

`0*d99fr#333'
     In every year: every day that appears within the period of the
     last Friday of the year until the 333rd day of the year.

`1996*w1fr#17mo'
     In the year 1996: every day that appears within the period of the
     Friday of the 1st ISO-week until the Monday of the 17th ISO-week.

`0@a#+4fr'
     In every year: every day that appears within the period of the
     date of the date variable A until the 4th Friday after the date of
     the date variable A.

`1996@e-3#+9fr'
     In the year 1996: every day that appears within the period of the
     date three days before the Easter Sunday's date until the 9th
     Friday after the date of the Easter Sunday's date.


File: gcal.info,  Node: Repetition factor of days,  Next: Appearance factor of days,  Prev: Ranges of days,  Up: Further date part attributes

Repetition factor of days
.........................

  A repetition factor of days (`:N') is specified by a `:' character
and must trail the day field, which must have a concrete value in a
date part of a Gcal resource file and has not been set to a zero value,
respectively either lead or trail an appearance factor of days.  Except
ranges of days or fixed dates, which occur only on a definite weekday
like `199600mon Every Monday 1996', such a repetition factor may be
specified in all possible codings of date parts of a Gcal resource file.

  This factor may have values in range `1'...`999'.  Values greater
than the real difference between the date of the first occurrence of
the fixed date und the last day of the year are always reduced to this
real difference.  In this sense, any value greater `365' (or `366' in
leap years) means a repetition factor until the last day of the year.

  A repetition factor of days is used to define recurrent fixed dates
and to use only one line in the resource file for them, instead of
using several lines in a resource file needed for defining these
recurrent fixed dates separately.  Assuming a fixed date shall always
occur on the 15th day in every month of the year 1996 and covers a
period of four days (inclusive the 15th itself), e.g. `Co-workers
training', one solution would be on the one hand a fixed date entry in
the resource file for the 15th of the month and the succeeding three
days, which would be a total of four entries in the resource file for
such a fixed date (apart from the possibility, that a list or a range
of days can be used in such a case).

  On the other hand, this expense can be reduced to a total of only one
entry in the resource file by using a repetition factor of days, which
is likewise valid for the 15th and the three days, which succeed the
15th in every month, namely

     19960015:4 Co-workers training

  The use of repetition factors of days in the date part is permitted
as follows:

   * `YYYYMMDD:N|WWWN:N'

   * `YYYY*d|wN:N|NWWW:N'

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

   * `YYYYMMDD:N|WWWN:N,[MM]DD:N|[MM]WWWN:N ...'

   * `YYYY*d|wN:N|NWWW:N,N:N|NWWW:N ...'

   * `YYYY@e|DVAR:N,|[+|-]N[WWW]:N,[+|-]N[WWW]:N ...'

  Some examples to this:

`000001fr3:11'
     In every year in January: every day that appears within the period
     of the 3rd Friday of the month and the succeeding ten days.

`00000112:3'
     In every year in January: every day that appears within the period
     of the 12th of the month and the succeeding two days.

`00000112:3,fr3:5'
     In every year in January: every day that appears within the period
     of the 12th of the month and the succeeding two days, and that
     appears within the period of the 3rd Friday of the month and the
     succeeding four days.

`0*d1:1'
     In every year: every day that appears within the period of the 1st
     day of the year and no succeeding day.

`0*d1:2'
     In every year: every day that appears within the period of the 1st
     day of the year and the succeeding day.

`0*d99fr:333'
     In every year: every day that appears within the period of the
     last Friday of the year and the succeeding 332 days.  Well, in
     cases a fixed date exceeds the year bounds, it will only be
     produced until the last day of the year.

`1996*w1fr:17'
     In the year 1996: every day that appears within the period of the
     Friday of the 1st ISO-week and the succeeding 16 days.

`0@a:4'
     In every year: every day that appears within the period of the
     date of the date variable A and the succeeding three days.

`1996@e-3:9'
     In the year 1996: every day that appears within the period of the
     date three days before the Easter Sunday's date and the succeeding
     eight days.


File: gcal.info,  Node: Appearance factor of days,  Prev: Repetition factor of days,  Up: Further date part attributes

Appearance factor of days
.........................

  An appearance factor of days (`.N') is specified by a `.' character
and must trail the day field, which must have a concrete value in a
date part of a Gcal resource file and has not been set to a zero value,
respectively either lead or trail a repetition factor of days.  Except
fixed dates, which occur only on a definite weekday and are not
specified by using a range of days, like `199600mon Every Monday 1996',
such an appearance factor may be specified in all possible codings of
date parts of a Gcal resource file.  This factor may be specified with
each single element of lists of days, but in a range of days, this
factor may trail *only* the final day of the range.  Well, the use of
such an appearance factor is only helpful if it is either given in a
range of days, or if it is given together with a repetition factor.

  This factor may have values in range `1'...`999'.  Fixed dates will
be ignored if the factor takes values, which are greater than the real
difference between the date of the occurrence of the fixed date und the
last day of the year, respectively the end of the period, for which the
fixed dates shall either be produced or respected.

  An appearance factor of days is used to define a concrete
displacement of recurrent fixed dates.  Assuming a fixed date shall
always occur on the 15th day in every month of the year 1996 and covers
a period of seven days (inclusive the 15th itself), but shall only be
respected every third day (i.e. two days have to be skipped at a time)
within this period, e.g. `Training-college', one solution would be on
the one hand a fixed date entry in the resource file for the 15th of
the month, for the 18th and for the 21st of the month, which would be a
total of three entries in the resource file for such a fixed date
(apart from the possibility, that a list of days can be used in such a
case).

  On the other hand, this expense can be reduced to a total of only one
entry in the resource file by using an appearance factor of days, which
is likewise valid for the 15th, the 18th and the 21st in every month,
namely on the one hand by the use of a repetition factor

     19960015:7.3 Training-college

  or on the other hand by the use of a range of days

     19960015#21.3 Training-college

  The use of appearance factors of days in the date part is permitted
as follows:

   * `YYYYMMDD:N.N|DD.N:N'

   * `YYYYMMWWWN:N.N|WWWN.N:N'

   * `YYYY*d|wN:N.N|N.N:N'

   * `YYYY*d|wNWWW:N.N|NWWW.N:N'

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

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

   * `YYYYMMDD:N.N|WWWN:N.N,[MM]DD:N.N|[MM]WWWN:N.N ...'

   * `YYYYMMDD.N:N|WWWN.N:N,[MM]DD:N.N|[MM]WWWN.N:N ...'

   * `YYYY*d|wN:N.N|NWWW:N.N,N:N.N|NWWW:N.N ...'

   * `YYYY*d|wN.N:N|NWWW.N:N,N.N:N|NWWW.N:N ...'

   * `YYYY@e|DVAR:N.N,|[+|-]N[WWW]:N.N,[+|-]N[WWW]:N.N ...'

   * `YYYY@e|DVAR.N:N,|[+|.]N[WWW].N:N,[+|.]N[WWW].N:N ...'

   * `YYYYMMWWW#WWW.N'

   * `YYYYMMDD|WWWN#[MM]DD|[MM]WWWN.N'

   * `YYYY*d|wN[WWW]#N[WWW].N'

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

  Some examples to this:

`000001fr3:11.3'
     In every year in January: every day that appears within the period
     of the 3rd Friday of the month and the succeeding ten days, but
     only every 3rd day within this period (skip two days at a time).

`00000112:3.2'
     In every year in January: every day that appears within the period
     of the 12th of the month and the succeeding two days, but only
     every 2nd day within this period (skip one day at a time).

`00000112:3.2,fr3:5.3'
     In every year in January: every day that appears within the period
     of the 12th of the month and the succeeding two days, but only
     every 2nd day within this period (skip one day at a time), and that
     appears within the period of the 3rd Friday of the month and the
     succeeding four days, but only every 3rd day within this period
     (skip two days at a time).

`0*d1:10.1'
     In every year: every day that appears within the period of the 1st
     day of the year and the succeeding nine days, and this for any day
     within this period (skip zero days at a time).

`0*d1:2.5'
     In every year: every day that appears within the period of the 1st
     day of the year and the succeeding day, but only every 5th day
     within this period (skip four days at a time).  Well, the
     succeeding days (only one in this example) of the starting day
     (1st day of year) are not respected, because the next day resulted
     by the appearance factor exceeds the final day (resulted by the
     repetition factor) of the period.

`0*d99fr:333.61'
     In every year: every day that appears within the period of the
     last Friday of the year and the succeeding 332 days, but only
     every 61st day within this period (skip 60 days at a time). Well,
     in cases a fixed date exceeds the year bounds, it will only be
     produced until the last day of the year.  No succeeding day (332
     in this example) of the starting day (last Friday of the year) is
     respected by reason of the displacement value of 60 days, because
     the next day resulted by the appearance factor exceeds the final
     day (resulted by the repetition factor) of the period (the last
     day of the year).

`1996*w1fr:17.8'
     In the year 1996: every day that appears within the period of the
     Friday of the 1st ISO-week and the succeeding 16 days, but only
     every 8th day within this period (skip seven days at a time).

`0@a:4.3'
     In every year: every day that appears within the period of the
     date of the date variable A and the succeeding three days, but
     only every 3rd day within this period (skip two days at a time).

`1996@e-3:9.4'
     In the year 1996: every day that appears within the period of the
     date three days before the Easter Sunday's date and the succeeding
     eight days, but only every 4th day within this period (skip three
     days at a time).

`1996@e3#-20sun.15'
     In the year 1996: every day that appears within the period of the
     date three days after the Easter Sunday's date until the 20th
     Sunday before the Easter Sunday's date, but only every 15th day
     within this period (skip 14 days at a time).


File: gcal.info,  Node: Text part of a line,  Next: Comment line,  Prev: Further date part attributes,  Up: Resource file

Text part of a line
-------------------

  The "text part" of a line in a resource file can be any text you like.
If the text part contains characters, which are used for highlighting
the text or format it for a printer, or characters with decimal values
above 127 in the code table of the used character set (these are
potentially non-printable), which are not produced by Gcal itself, such
characters respectively sequences are displayed by Gcal in an
*uninterpreted* manner!  For that very reason it can happen that the
output of such characters can potentially create problems with the used
screen device driver software and/or the external pager program,
likewise mailing of such texts by means of electronic mail.

  So-called `NUL' characters (that's the character with the value zero
in the code table of the used character set) may occur too in the text
part, but their effect is only the suppression of all succeeding
characters of the line.  In my opinion it makes no perceptible sense to
output these `NUL' characters uninterpreted so they are used for
remarking purposes only; besides the `NUL' characters would cause the
same problems already mentioned above.

  A line of the resource file is continued on the next line if a `\-\n'
(backslash-newline) character sequence is found, e.g.:

the line:
     000000Mo Every Monday

and the lines:
     000000Mo \
     Every \
     Monday

produce the same output and are essentially equivalent.

  Furthermore you can break up the text of a *long* resource file line
at any place your like.  The term *long* means in this context, that the
text displayed by Gcal would override the right text margin of the
screen respectively break up at that margin.  Each time a `~' (tilde)
character is found in the text part, this character is replaced by a
real `\n' (newline) character.  Such texts will be displayed by Gcal in
a formatted manner at a left margin.

  You may quote the `~' (tilde) character - in case this character
itself is needed - by placing a `\' (backslash) character before it,
e.g. `\~'.

  If you need the characters `\~' itself, you have to quote the `\'
(backslash) character by itself, e.g. `\\~'.

The resource file `example.rc'

     ;
     ; Hi, I'm `example.rc' and alive now
     ;
     0 I know I'm a short text
     0 I hope I'm long enough~here, a line break up\
     ~and again~and now for the last time...
     0 Am I another short text? Dunno...

is displayed as follows:

     $ gcal --resource-file=example.rc --disable-highlighting
     -|
     -| Fixed date list:
     -|
     -| Wed, Sep  14th 1994: Am I another short text? Dunno...
     -| Wed, Sep  14th 1994: I hope I'm long enough
     -|                      here, a line break up
     -|                      and again
     -|                      and now for the last time...
     -| Wed, Sep  14th 1994: I know I'm a short text

  Because *whitespace* characters are used to separate the date part
from the text part (these are internally skipped and remain undisplayed
therefore), it's not possible to supply the text part with leading
*whitespace* characters without further ado.  If one or more
*whitespace* characters shall lead the text part, this can be arranged
by quoting the *first* of these *whitespace* characters (and that by
placing a `\' (backslash) character before it), e.g. `\ ' if it is a
space character.  By means of such a character sequence, Gcal notices
that the text trailing the `\' character is no longer used for
separating purposes, but is member of the text part.  Gcal skips this
specific marking backslash character (avoids its output) and processes
the rest of the line as usual.

The following example should be enough to elucidate the above facts.
The resource file `whitespc.rc'

     0 BANG BANG
     0 bogus
     0         bogomips
     0    \hello world
     0    \ main(){for(;;)fork();}
     0 \     sh $0 & $0 &
     0    \  a  \  b  \\  c  \\\  d
     0    What happens now?\
     ~0  \  This!
     0    What happens now?\\
     ~0  \  That!

is displayed as follows:

     $ gcal --resource-file=whitespc.rc --disable-highlighting
     -|
     -| Fixed date list:
     -|
     -| Wed, Sep  14th 1994:      sh $0 & $0 &
     -| Wed, Sep  14th 1994:   a  \  b  \\  c  \\\  d
     -| Wed, Sep  14th 1994:  main(){for(;;)fork();}
     -| Wed, Sep  14th 1994: BANG BANG
     -| Wed, Sep  14th 1994: What happens now?~0  \  That!
     -| Wed, Sep  14th 1994: What happens now?
     -|                      0  \  This!
     -| Wed, Sep  14th 1994: \hello world
     -| Wed, Sep  14th 1994: bogomips
     -| Wed, Sep  14th 1994: bogus


File: gcal.info,  Node: Comment line,  Next: Include directives,  Prev: Text part of a line,  Up: Resource file

Comment line
------------

  A line beginning with a `;' (semicolon) character in the resource file
is treated as a remark and will not be used by Gcal!  Any *whitespace*
characters may lead the remark character.  For information for how a
`NUL' character can be used for remarking in a text part, see *Note
Text part of a line::.


File: gcal.info,  Node: Include directives,  Next: Special macro texts,  Prev: Comment line,  Up: Resource file

Include directives
------------------

  You may add `#include' directives in a resource file (a mechanism
similar the method, which is used by the C Preprocessor) for searching
and loading further resource files.  An `#include' directive tells Gcal
to suspend reading the current resource file and read one other
resource file before continuing.  The directive is a line in the
resource file that looks like this template:

     #include *whitespace* ARGUMENT [*whitespace*] *newline*

The ARGUMENT can either be

     "FILE NAME"

or

     <FILE NAME>

(thus a file name, which is embraced by `""' or `<>').

  A *whitespace* character minimum is required between `#include' and
the ARGUMENT.  The ARGUMENT may be trailed by extra *whitespace*
characters and the line must always end with a `\n' (newline)
character, except it's the last line of a resource file.

Let's inspect a bit more concrete example:

  1. #include "foo/bar"

  2. #include <bar>

  The first `#include' directive tells Gcal to load the file `bar' in
the directory `foo' from the actual directory.  If this fails, Gcal
tries to load this file using steps 1...4 of the previously explained
mechanism, which is used for searching files (*note File searching
mechanism: Resource file.).

  The second `#include' directive tells Gcal to load the file `bar'
from the user respectively system data directory using steps 3...4 of
the previously explained mechanism, which is used for searching files.
It is not allowed to include files, which have a fixed access path
starting from the root directory by such an `#include' directive like
`#include </file>' or `#include </foo/bar/file>'; just as the
specification of a single or an extended file name containing a
disk/drive specifier (even if operating systems like MS-DOS or OS/2
would permit such a disk/drive specification on principle), because the
resulting path name (lead by the user respectively system data
directory name) wouldn't be a valid file name any longer.

  Included files may include other files again.  But the nesting level
of included files is limited on the one hand by the amount of useable
working storage of the computer, and on the other hand by the value,
which is given by the operating system respectively the compiler for
the number of files which can be opened simultaneously.  Recursive
includes (1) or cyclic includes (2) are not permitted, because such
backward references would produce an infinite loop in the program
internally!  Gcal recognizes such situations and terminates immediately
with a fatal error.

  If an included resource file cannot be found and no `--debug=abort'
option is given, processing of the resource file containing the
`#include' continues.

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

  (1)  The included file tries to include itself again.

  (2)  The included file is included again by another file, which
occurs at a deeper place of such a chain.


File: gcal.info,  Node: Special macro texts,  Next: Date variables,  Prev: Include directives,  Up: Resource file

Special macro texts
-------------------

* Menu:

* %s macro text::  How to use the Start of event macro text.
* %e macro text::  How to use the End of event macro text.
* %o macro text::  How to use the Weekday name macro text.
* %k macro text::  How to use the Week number macro text.
* %b macro text::  How to use the Birthday macro text.
* %y macro text::  How to use the Year number macro text.
* %m macro text::  How to use the Month number macro text.
* %w macro text::  How to use the Week number macro text.
* %d macro text::  How to use the Day number macro text.
* %j macro text::  How to use the Julian Day number macro text.
* %n macro text::  How to use the Textual date macro text.
* %t macro text::  How to use the Actual time macro text.
* %1 macro text::  How to use the Start of highlighting sequence 1 macro text.
* %2 macro text::  How to use the End of highlighting sequence 1 macro text.
* %3 macro text::  How to use the Start of highlighting sequence 2 macro text.
* %4 macro text::  How to use the End of highlighting sequence 2 macro text.

  The text part of a resource file line may contain 16 different,
special macro texts, which may occur in any (senseful) number and
order.  These texts start with a `%' (percent) character, which may be
quoted by a leading `\' (backslash) character if the `%' (percent)
character itself is wanted to be used in the text part, e.g. `\%'.  The
`%' character is trailed by a distinguishing mark, which defines the
kind of the macro text to be used and if it is a letter, Gcal accepts
it case-insentive.

     *Please note:*
     The optional date after the `%s...', `%e...', `%o...', `%k...',
     `%b...' and `%y...' macro texts may be denoted either using the
     date format `YYYY[MM[DD|WWWN]]', `YYYY*d|wN[WWW]' or
     `YYYY@e|DVAR[[+|-]N[WWW]]' date format.

