5.1 Resource file

• Structure of resource file: How to write a Resource file.
• Date part of a line: How to write the Date part.
• Further date part attributes: What are Further date part attributes?
• Text part of a line: How to write the Text part.
• Special Texts processed: What are %?... Special Texts?
• Comment line: What is a Comment line?
• Include directives: What are Include directives.
• Date variables: How Date variables can be used.
• Text variables: How Text variables can be used.

This section describes how to use a resource file that contains fixed dates and appointments. The name of the standard resource file is HOME/.gcalrc¹.

Gcal uses a special file searching mechanism:

1. The Gcal program scans the file directories which are referenced in the environment variable GCALPATH (see Environment Variable GCALPATH) to find the standard resource file. The GCALPATH environment variable contains a (‘:’) colon-separated² list of file directories. If no such environment variable is defined and set, Gcal omits this step.
2. If the above action fails, Gcal looks for the standard resource file in the file directory which is referenced in the environment variable HOME. If no HOME environment variable is defined and set, Gcal also omits this step. See Environment Variable HOME.
3. If the above action fails, Gcal inspects the user data file directory³ to find the standard resource file. This file directory is a file directory relative to the HOME file 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 this file directory instead of using the burned-in default name of this file directory (see Environment Variable GCAL_USR_DATADIR). If no HOME environment variable is defined and set, Gcal of course also omits this step.
4. If all above actions fail, Gcal inspects the system data file directory⁴ to find the standard resource file. This file directory is a file directory absolute to the root/$prefix file directory. If an environment variable GCAL_SYS_DATADIR is set, Gcal tries to use this file directory instead of using the burned-in default name of this file directory (see Environment Variable GCAL_SYS_DATADIR).

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

In case the --debug=abort option is given and no standard resource file is found during the steps 1...4 of the file searching mechanism, the Gcal program will be aborted with an error code. See Error Code 118, and Global option --debug=abort, for more information.

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. See Fixed date option --resource-file=name.

Annotation:

An extended file name contains one ore more ‘/’ (slash) characters⁵ and denotes a file, whose fixed access path either starts from the root file directory, like ‘/foo/bar/file’, or from the actual file 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 denotes a file, whose access-path either does not start from the root file directory or from the actual file directory, like ‘file’ or ‘bar/file’. If name is a simple file name:

• Gcal tries to find this file name by using the previously explained file searching mechanism.