3.1.1.2 Global options

-R name

--response-file=name

Write the contents of the environment variable GCAL (see Environment Variable GCAL), and then the arguments of command line (in the given order) to file name, i.e. create response file name. See Response file, for more details.

-S name

--shell-script=name

Write the contents of the environment variable GCAL (see Environment Variable GCAL), and then the arguments of command line (in the given order) to file name, i.e. create shell script file name. An automatically created shell script file is executable and calls Gcal directly with the arguments stored in it. You may start the shell script with other command line arguments which are directed to Gcal, too.

--debug[=internal|handled|unhandled|all|abort]

Display some debug information.

--debug=internal

Display informational texts if program internal maxima are reached or other conditions occurred, respectively.

--debug=handled

Like --debug=internal, additionally display the file names which can be processed respectively handled.

--debug=unhandled

Like --debug=internal, additionally display file names which cannot be processed respectively handled.

--debug=all

Like --debug=handled and --debug=unhandled together.

--debug=abort

Like --debug=all and abort program with an error code if the file name cannot be handled or other unmanageable conditions occurred, respectively. See Error Codes.

-p

--pager

Enables either an external pager or a simple, internal pager. If an environment variable PAGER is set, its contents will be used for detecting the external pager program. See Environment Variable PAGER, for more information.

If no PAGER environment variable is set or if its contents is invalid, Gcal tries to use the less pager; if this program cannot be found during scanning the PATH environment variable, Gcal tries to use the more pager, if this program cannot be found, the pg pager in the same way¹. See Environment Variable PATH.

If all these actions fail, Gcal will use its simple, built-in pager. If the internal pager is used, Gcal detects the number of lines shown before it prompts and waits for user input by using these methods:

1. Gcal respects the values set in the environment variables GCAL_LINES and GCAL_COLUMNS. See Environment Variable GCAL_LINES, and Environment Variable GCAL_COLUMNS, for further information.
2. If above action fails, Gcal respects the values set in the environment variables LINES and COLUMNS. See Environment Variable LINES, and Environment Variable COLUMNS, for more details.
3. If above action fails, Gcal respects the values set in the termcap² file which refers to the terminal used (see Environment Variable TERM). This step is only done on systems which support the use of Termcap by default.

   On MS-DOS, OS/2 and some other operating systems, Gcal uses a system dependent low-level function and respects the reported values.

4. If all above actions have failed, Gcal uses default values³.

-H yes

--force-highlighting

--highlighting=yes

If the output of the program is redirected⁴ or piped⁵, the highlighting sequences are not automatically converted into the according marking characters, they remain unchanged. This option takes no effect if the output of the program is sent by means of electronic mail. See Global option --mail[=address].

-H no

--disable-highlighting

--highlighting=no

Disable highlighting sequence / marking character pairs of current day, holiday or text explicitly.

-H text

--highlighting=text

Set highlighting sequence / marking character pairs explicitly. In this sense, highlighting sequences are control character sequences which cause a color or intensity switch in output text. Typical control character sequences are the ANSI escape sequences which have a leading escape character, and trailing more characters that define the type of the ANSI escape sequence. In this sense, marking characters are single, printable characters which lead and trail the output text.

The text argument must be a (‘:’) colon-separated text which is structured in this way: seq1_start:seq1_end:seq2_start:seq2_end. The first sequence is used for highlighting/marking an actual day, the second for a holiday. The sequences must be given in form of a sequence pair; seq?_start enables the highlighting/marking, seq?_end disables it. Only two sequence pairs will be processed, others are ignored. Either highlighting sequence pairs or marking character pairs may be defined, i.e. using them both in a mixed couple is not permitted!

For example:

-H \x20:\x20:\x1:# respectively
--highlighting=\x20:\x20:\x1:#
marks the actual day like ‘\x20actual date\x20’⁶ and the holiday date like ‘\x1holiday date#’ using the given marking characters.

-H \x1b[34;42m:\x1b[0;40m or
-H \033[34;42m:\033[0;40m or
-H \E[34;42m:\E[0;40m
defines a starting ANSI escape highlighting sequence ‘\x1b[34;42m’ used for actual day and ending ANSI escape highlighting sequence ‘\x1b[0;40m’ with no given highlighting sequence for holidays, so default highlighting sequences for holidays are used (non-given entries are always skipped). Please note the last abstract of this text part which informs you more detailed of this context. See Environment Variable GCALANSI, too.

Control code definitions may contain any printable characters. Non-printable characters may be encoded in octal or hexadecimal notation. The abbreviation ‘\E’ directly encodes the escape character (octal \033 respectively hexadecimal \x1B).

A character can be encoded octal by typing ‘\nnn’ (backslash-octal digit(s)), where n must be a valid octal digit (0...7). Normally, three octal digits must be given. If the octal character code consists of one or two octal digits, leading zeroes must be added, except the case, where the encoded octal character is given at last in the single sequence.

A character can be encoded hexadecimal by typing ‘\xnn’ (backslash-x hexadecimal digit(s)), where n must be a valid hexadecimal digit (0...9A...Fa...f). Normally, two hexadecimal digits must be given. If the hexadecimal character code consists of one hexadecimal digit, a leading zero must be added, except the case, where the encoded hexadecimal character is given at last in the single sequence.

If the sequence separator character, thus the ‘:’ (colon) character itself, is used as a marking character, it must be encoded either octal by \072 or hexadecimal by \x3A.

If the C Preprocessor symbol USE_PAGER was defined and the output of the program is redirected or used in a pipeline, the highlighting sequences are automatically converted into the according marking characters; if USE_PAGER was not defined, they remain untouched.

Incomplete or non-given highlighting sequences will be replaced by internal default ANSI escape highlighting sequences if a GCALANSI environment variable is defined; otherwise completely replaced by their according marking characters. See Environment Variable GCALANSI.

--mail[=address]

Send Gcal's output via mail⁷ program to the given address, e.g.:

          --mail=esken@gmx.net

If no address is given, Gcal tries to send the eMail by using the following methods:

1. If an environment variable MAILTO is defined and set, the eMail is send to the address which is listed in this environment variable. See Environment Variable MAILTO, for more information.
2. If above action fails, and if an environment variable USER is defined and set, the eMail is send to the address which is listed in this environment variable. See Environment Variable USER, for more information.
3. If above action fails, and if an environment variable LOGNAME is defined and set, the eMail is send to the address which is listed in this environment variable. See Environment Variable LOGNAME, for more information.
4. If all above actions have failed, no eMail is send.

Generally, Gcal does not send electronic Mails whose message body is empty! An informational message will be shown on the standard error channel if this case occurs.

All highlighting sequences produced by Gcal itself are always disabled respectively automatically converted into the according marking characters if an eMail must be send; no matter if the --force-highlighting option was given or not. This behavior of Gcal is an imperative necessity, because it is possible that the mail program cannot perform the mailing correctly. Please pay attention in this context to the further explanations concerning the limitations of the text part of a resource file line (see Text part of a line).

If an environment variable MAILPROG is defined and set, its contents will be used as the program name of the mailer instead of the standard name mail. See Environment Variable MAILPROG, for more information.