This is Info file gcal.info, produced by Makeinfo-1.64 from the input file ./doc/tex/gcal-us.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: Fixed date warnings, Next: Todays calendar, Prev: Eternal holidays, Up: Top Fixed date warnings ******************* 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 (*note `--type=special|standard': Calendar options.) or an additional *starting day of week* argument (*note `--starting-day[=ARG]': Calendar options.) (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. 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=ARG': 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 1993' List all date entries related to entire 1993 and all eternal date entries related to entire 1993 in ascending order; the warning level is same as `-cy' option. `gcal -c- july:1993' List all date entries related to fiscal year - starting in July 1993 and ending in June 1994 - and all eternal date entries 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' List all date entries related to July 1993 and all eternal date entries related to July 1993 and all eternal holiday entries related to July 1993 in ascending order; the warning level is same as `-cm' option. `gcal -c-e 1993' List all date entries related to entire 1993 and all eternal date entries related to entire 1993 and all eternal holiday entries related to entire 1993 in descending order; the warning level is same as `-cy' option. * Menu: * Resource file:: How to use a Resource file. * Resource file examples:: Examples of Resource file entries.  File: gcal.info, Node: Resource file, Next: Resource file examples, Prev: Fixed date warnings, Up: Fixed date warnings Resource file ============= 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 in the actual directory and looks in this directory first. 2. If the above action fails, Gcal inspects 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. 3. If the above action fails, Gcal scans the directories, which are referenced in the environment variable `GCALPATH' (2) (*note GCALPATH: Environment variables.), for the standard resource file. The `GCALPATH' environment variable contains a (`:') colon-separated list of directories. If no such environment variable is defined and set, Gcal omits this step. 4. If the above action fails, Gcal inspects the *user library* directory (normally `$HOME/lib/gcal-lib') to find the standard resource file. This directory is a directory relative to the `HOME' directory. If an environment variable `GCAL_USR_LIBDIR' 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_LIBDIR: Environment variables.). If no `HOME' environment variable is defined and set, Gcal omits this step. 5. If all above actions fail, Gcal inspects the *system library* directory (normally `/usr/lib/gcal-lib' or `$(prefix)/lib/gcal-lib') to find the standard resource file. This directory is a directory absolute the *root*/*$(prefix)* directory. If an environment variable `GCAL_SYS_LIBDIR' is set, Gcal tries to use that directory first instead of using the burned-in default name of that directory (*note GCAL_SYS_LIBDIR: Environment variables.). If the standard resource file is not found during steps 1...5 of the file searching mechanism, no fixed date warnings will be created! If a `-f|F NAME[+...]' respectively `--resource-file=ARG' command line argument is given, a file NAME will be used for the resource file instead of the standard resource file. *Note `--resource-file=ARG': 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. * 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 statements:: What are Include statements. * Special macro texts:: What is a Special macro text. * Date variables:: How Date variables can be used. ---------- Footnotes ---------- (1) On MS-DOS, OS/2 and some other operating systems, the name of the *standard* resource file is `./gcalrc'. (2) The environment variable `PATH' is used on MS-DOS for this, and the environment variable `DPATH' is used on OS/2 for this. (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 -------------------------- 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 (except of *local date variable* assignments/operations). 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. 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 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! The maximum length of a line is limited to INT_MAX (1) characters. ---------- 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. 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. 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. If the computed date doesn't occur in year, i.e. exceeds the year bounds, the fixed date warning message is suppressed. *Or*: Any of these date variable assignments respectively operations... DVAR=MMDD DVAR=MMWWWN DVAR=*dN[WWW] DVAR=*wN[WWW] DVAR=DVAR DVAR++ DVAR-- DVAR+=N DVAR-=N *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 ---------------------------- 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'. * 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.  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 1'st and the 15'th 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 1'st of the month and another entry for the 15'th 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 1'st and the 15'th day in every month, namely 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 3'rd Friday, on the 12'th, on the last day of the month and on every Monday. And in every year: on the 14'th April, on the 3'rd December, on the 3'rd 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 12'th. `0*d1,1fr,999,17mo' In every year: on the first day of the year, on the 1'st Friday of the year, on the last day of the year and on the 17'th Monday of the year. `1996*w1fr,1,17mo,99fr' In the year 1996: on Friday of the 1'st ISO-week, on Monday of the first ISO-week, on Monday of the 17'th 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 1'st and the 15'th 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 1'st of the month, another one for the 2'nd of the month until the 15'th 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 1'st until the 15'th day in every month, namely 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 3'rd Friday of the month until the 12'th of the month. `00000112#fr3' In every year in January: every day that appears within the period of the 12'th of the month until the 3'rd Friday of the month. `00000112#augfri3' In every year: every day that appears within the period of the 12'th January until the 3'rd Friday of August. `0000sep13#99fr9' In every year: every day that appears within the period of the 13'th September until the last Friday of December. `0*d1#1fr' In every year: every day that appears within the period of the 1'st day of the year until the 1'rd 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 333'rd day of the year. `1996*w1fr#17mo' In the year 1996: every day that appears within the period of the Friday of the 1'st ISO-week until the Monday of the 17'th 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 4'th 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 9'th 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 15'th day in every month of the year 1996 and covers a period of four days (inclusive the 15'th itself), e.g. `Co-workers training', one solution would be on the one hand a fixed date entry in the resource file for the 15'th 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 15'th and the three days, which succeed the 15'th 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 3'rd 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 12'th 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 12'th of the month and the succeeding two days, and that appears within the period of the 3'rd Friday of the month and the succeeding four days. `0*d1:1' In every year: every day that appears within the period of the 1'st day of the year and no succeeding day. `0*d1:2' In every year: every day that appears within the period of the 1'st 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 1'st 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 15'th day in every month of the year 1996 and covers a period of seven days (inclusive the 15'th 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 15'th of the month, for the 18'th and for the 21'st 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 15'th, the 18'th and the 21'st 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 3'rd Friday of the month and the succeeding ten days, but only every 3'rd 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 12'th of the month and the succeeding two days, but only every 2'nd 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 12'th of the month and the succeeding two days, but only every 2'nd day within this period (skip one day at a time), and that appears within the period of the 3'rd Friday of the month and the succeeding four days, but only every 3'rd 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 1'st 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 1'st day of the year and the succeeding day, but only every 5'th day within this period (skip four days at a time). Well, the succeeding days (only one in this example) of the starting day (1'st 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 61'st 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 1'st ISO-week and the succeeding 16 days, but only every 8'th 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 3'rd 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 4'th day within this period (skip three days at a time).. `1996@e3#-20so.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 20'th Sunday before the Easter Sunday's date, but only every 15'th 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 14'th 1994: Am I another short text? Dunno... => Wed, Sep 14'th 1994: I hope I'm long enough => here, a line break up => and again => and now for the last time... => Wed, Sep 14'th 1994: I know I'm a short text  File: gcal.info, Node: Comment line, Next: Include statements, 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: Resource file.  File: gcal.info, Node: Include statements, Next: Special macro texts, Prev: Comment line, Up: Resource file Include statements ------------------ You may add "#include" statements in a resource file (a mechanism similar the method, which is used by the C Preprocessor) for searching and loading further resource files, e.g.: 1. #include "foo/bar" 2. #include The first *#include* statement tells Gcal to load the file `bar' from the directory `foo' using steps 1...5 of the previously explained mechanism, which is used for searching files (*note File searching mechanism: Resource file.). The second *#include* statement tells Gcal to load the file `bar' from the user respectively system library directory using steps 4...5 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 a *#include* statement like `#include ' or `#include '; 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 library directory name) wouldn't be a valid file name anymore. 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! ---------- 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 statements, Up: Resource file Special macro texts ------------------- The text part of a resource file line may contain 14 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. `\%'. *Please note:* The optional date after the `%b...', `%y...', `%s...' and `%e...' 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. * 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. * %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.  File: gcal.info, Node: %s macro text, Next: %e macro text, Prev: Special macro texts, Up: Special macro texts %s macro text ............. `%s[YYYY[MM[DD|WWWN]]]' references the "starting date" of the fixed date, i.e. the first date the fixed date may occur. If the date, which is encoded in the `%s...' macro text, is later the current respectively queried date, so the complete warning text will be suppressed. If the warning text must be shown, the text of this macro is always suppressed in output. This macro text *must* have a trailing *whitespace* character. * If YYYY... is not given (==*no* date encoded), the 01 January of current year is assumed for the date. * If YYYY is set to 0000, the current year is assumed for the year. * If MM is not given, then 01 (==January) is assumed for the month. * If MM is set to 00, the current month is assumed for the month. * If DD|WWW is not given, then 01 is assumed for the day. * If DD is set to 00, the current day is assumed for the day. * If the N field is given (range 1...5 or 9), a WWW field must be given then.  File: gcal.info, Node: %e macro text, Next: %b macro text, Prev: %s macro text, Up: Special macro texts %e macro text ............. `%e[YYYY[MM[DD|WWWN]]]' references the "ending date" of the fixed date, i.e. the last date the fixed date may occur. If the date, which is encoded in the `%e...' macro text, is earlier the current respectively queried date, so the complete warning text will be suppressed. If the warning text must be shown, the text of this macro is always suppressed in output. This macro text *must* have a trailing *whitespace* character. * If YYYY... is not given (==*no* date encoded), the 31 December of current year is assumed for the date. * If YYYY is set to 0000, the current year is assumed for the year. * If MM is not given, then 12 (==December) is assumed for the month. * If MM is set to 00, the current month is assumed for the month. * If DD|WWW is not given, then the last day of month MM is assumed for the day. * If DD is set to 00, the current day is assumed for the day. * If the N field is given (range 1...5 or 9), a WWW field must be given then.  File: gcal.info, Node: %b macro text, Next: %y macro text, Prev: %e macro text, Up: Special macro texts %b macro text ............. `%b[YYYY[MM[DD|WWWN]]]' references a "year of birth" and is converted to an *age value*, e.g.: The text `My %b1962 birthday%s1952 %e2062' will be expanded to ==> `My 32'nd birthday', in case the current year is 1994. Those age values are evaluated/respected only, if the computation of an age value is greater zero. The fixed date warning in preceding example is displayed only in case the current year is greater than 1952 and less than 2062. If the warning text must be shown, the text of this macro is always suppressed in output. This macro text *must* have a trailing *whitespace* character. * If YYYY... ist not given (==*no* date encoded), the current date is assumed for the date. * If YYYY is set to 0000, the current year is assumed for the year. * If MM is not given or set to 00, the current month is assumed for the month. * If DD is not given or set to 00, the current day is assumed for the day. * If the N field is given (range 1...5 or 9), a WWW field must be given then.  File: gcal.info, Node: %y macro text, Next: %m macro text, Prev: %b macro text, Up: Special macro texts %y macro text ............. `%y[YYYY[MM[DD|WWWN]]]' references any year and is converted to a "year difference value", e.g.: The text `Sylvester 1912 is %y1912 years ago' will be expanded to ==> `Sylvester 1912 is -82 years ago', in case the current year is 1994. If the warning text must be shown, the text of this macro is always suppressed in output. This macro text *must* have a trailing *whitespace* character. * If YYYY... is not given (==*no* date encoded), the current date is assumed for the date. * If YYYY is set to 0000, the current year is assumed for the year. * If MM is not given or set to 00, the current month is assumed for the month. * If DD is not given or set to 00, the current day is assumed for the day. * If the N field is given (range 1...5 or 9), a WWW field must be given then.  File: gcal.info, Node: %m macro text, Next: %w macro text, Prev: %y macro text, Up: Special macro texts %m macro text ............. `%m' references the current respectively queried "month number" relative to the actual (==todays) date.  File: gcal.info, Node: %w macro text, Next: %d macro text, Prev: %m macro text, Up: Special macro texts %w macro text ............. `%w' references the current respectively queried "week number" relative to the actual (==todays) date.  File: gcal.info, Node: %d macro text, Next: %j macro text, Prev: %w macro text, Up: Special macro texts %d macro text ............. `%d' references the current respectively queried "day number" relative to the actual (==todays) date, e.g.: A resource file line like `0 %d days gone' will be expanded to ==> `-10 days gone', in case you call Gcal with the `-c10-' option and no command.  File: gcal.info, Node: %j macro text, Next: %n macro text, Prev: %d macro text, Up: Special macro texts %j macro text ............. `%j[[-]N]' references the current respectively queried "Julian Day number" relative to the actual (==todays) date. This day number is tied with the date 1'st January 4713 BCE, which is the starting day zero of a consecutive day counting used in astronomical computations and is known as the Julian Date (J.D.). The real zero of this date is at 12 o'clock universal time; the day doesn't change at midnight, but at noon universal time. Actually, Gcal does not evalute the time zone, which is returned by the systems date function. For that reason, this day number is represented without a time fraction on the supposition that the day has already changed at noon. If you don't like the feature that the day has already changed at noon, you can decrease the resulting Julian Day number of that macro text always by one, e.g. `%j-1'. For example: The line `0 Julian Day %j since 01-Jan-4713 BCE' will be expanded to ==> `Julian Day 2437929 since 01-Jan-4713 BCE', in case you call Gcal with the `-c %19620921' option and no command. If the `%j' text is directly trailed by a number, this number is always subtracted from the real Julian Day number (a negative sign can be given to increase the readability of this expression), so you are able to work with any reference values, e.g.: The line `0 Julian Day %j-2415021 since 01-Jan-1900' will be expanded to ==> `Julian Day 4 since 01-Jan-1900', in case you call Gcal with the `-c %19000105' option and no command.  File: gcal.info, Node: %n macro text, Next: %t macro text, Prev: %j macro text, Up: Special macro texts %n macro text ............. `%n[[+|-]N]' references the current respectively queried "day number" relative to the current date `+/-' N days and is converted to an effective "date text", e.g.: A resource file line like `1962Sep21 10000 days old: %n+10000' will be expanded to ==> `10000 days old: Feb-06-1990', in case you call Gcal with the simple `-c' option and the command `sep 1962' (*note `MM YYYY': Single commands.).  File: gcal.info, Node: %t macro text, Next: %1 macro text, Prev: %n macro text, Up: Special macro texts %t macro text ............. `%t[12|24]' references the "actual system time", e.g.: The text `Time: %t --> Dentist at 10:00' will be expanded to ==> `Time: 07:32 --> Dentist at 10:00', in case the actual system time value is 07:32 (hh:mm). A system time value is always displayed in the *24-hour* format by default. For displaying in the *12-hour* format, add `12' behind `%t', e.g. `%t12'.  File: gcal.info, Node: %1 macro text, Next: %2 macro text, Prev: %t macro text, Up: Special macro texts %1 macro text ............. `%1' is replaced by the starting highlighting sequence respectively the starting marking character, which is used for highlighting the actual day, (*note `--highlighting=ARG': Global options.). This attains that all succeeding text of the line after this macro text is displayed in the same way as the highlighted respectively marked actual day. `%1' is used together with the `%2' macro text, which turns off this enabled highlighting sequence respectively produces the ending marking character. If a `%1' text is not succeeded by a `%2' text on the line, Gcal automatically inserts such a `%2' text at the end of the line. For example: Only %1THIS%2 word is highlighted in this line. %1This text is highlighted up to%2 here. All from %1here up to the end of the line is highlighted.