.* This file can be processed with Vprint to get a manual. Note that the file
.* docs.txt has already been processed and can be listed to a 66 line/page
.* printer.
.
.lf=c
.hd65=\twPage \\#p\tw
**** ** ****
** ** **** **
** ** ** **
** ** ** **
** ****** ** *
** ** ** ** ** **
**** ** ** *******
Calendar Generating Program
for
OS9/68000
Copyright 1995
Bob van der Poel Software
N O T I C E
-----------
.lf=l
This software is protected by copyright. It is offered on an "as is" basis. Under our shareware agreement you have no obligation to register the software. However, if you like it you should send in the requested contribution. If you do not wish to register the software, please delete the program from your system.
If you like this software we ask that you complete the enclosed registration form and mail it to us with a $20.00 fee. In return we will send you the latest version of CAL, our latest catalogue and a $10.00 certificate redeemable on any of our commercial products.
You are free to redistribute this software by any means. However, you can not change any of the files you received in the original package. You can not charge any fee for distributing the package.
.lf=c
Introduction
------------
.lf=l
CAL is a program which will print out calendars and remind you of holidays and appointments. It is easy to use and can be configured to printout in various formats and to the printer or screen. CAL will accept any date; however, you should be aware that because the current calendar has not always been in use, dates prior to 1753 will be mythical at best.
.pg
.lf=c
Command Line Options
--------------------
.lf=l
If you just type "cal" at an OS9 prompt you will get a printout of calendars for the last, current and next month. This is CAL's default operation. However, there are many ways to change the defaults. The changes are done via command line arguments. Each argument must be prefaced with a '-'. You can concatenate several options together, so long as none of the intermediate arguments do not need an argument. For example:
cal -m10
will display a calendar for November of the current year. And:
cal -gm1-12 -y1994
will display calendars for each month in 1994, with the graphics characters turned off. In both cases, the calendars will be displayed three wide. We assume that you have an 80 column display (don't worry...you can change that!). However, if you try this:
cal -m1y1995
the "y1995" will be ignored.
For each command option which needs a parameter, you can use an option "=". However, using the "=" or not, you must not have any spaces between the option name and the parameter. For example:
cal -m=12
cal -m12
Are identical. However:
cal -m 12
will not work.
Each of the various command options will now be explained:
.id=5
-b This flag enables printing in "big" format. This format is very nice to use on a printer (you'll never have to line up at the bank again in the new year). Rather than trying to explain the format here, just do a "cal -b" to see the results.
.id
-c[=]value This command can be used to set the number of calendars to print. For example, if you use the command line:
cal -m1 c4
you will get calendars for January, February, March and April. Of course, you could get the same results with the command:
cal -m1-4
.id
-g This flag will disable the use of 8 bit, IBM graphics characters when printing the calendar. Most terminals and printers now support this character set; however, some don't...so it is an option.
.id
-h[=][path] Normally, holidays are not printed. However, you can print them with this flag. The format of the holiday file is detailed later in this document. If you simply include the -h flag (without a filename) CAL will look for the holiday data file "/dd/sys/cal.holidays". If you wish to use a different filename, just place it after the -h. For example:
cal -h=/h1/woof/myholidays
will look for the file "myholidays" in the directory "woof" on the device "h1".
.id
-m[=]range This option lets you specify the months to print. You can specify the range in a number of ways...again, a few examples prove the rule:
cal -m=1-12 \idprints January to December
cal -m=4 \idprints April
cal -m-12 \idprints from the current month to December
If you specify a range and the second value is less than the first, the second will be used for the next year. For example:
cal -m12-1 -y1995
will display calendars for December 1995 and January 1996.
.id
-oe[=]str This option sets the codes which enable overstrike mode on your printer/terminal. It is used to print the dates of the month when doing a "big" calendar. The definitions for the "str" are detailed later in this document.
.id
-os[=]str This option set the codes with disable overstrike mode. It is used when printing the dates of the month when doing a "big" calendar.
.id
-p[=]path Normally, the printout is done to standard out (your terminal). You can change this by using the -p option. For example:
cal -p=/p
will print the calendar to the device "/p" (normally, a printer). Of course, you could do the same with a redirect command (such is the flexibility of OS9).
.id
-se[=]str When printing in "big" mode, this string is printed at the start of the calendar. See later in this document for the details on "str". Also, see the example "cal.init" file.
.id
-ss[=]str This string is sent at the end of "big" calendar. Useful to undo the effects of "-se".
.id
-u[-][path] You can use initialization files with CAL. Normally, they are not used (which leaves CAL in the default mode). However, an init file is very useful when doing printouts to the printer, etc. If you call CAL with:
cal -u
the file "/dd/sys/cal.init" will be read. The format of this file is quite simple: it is just a collection of command line options. Each line in an init file can:
- \idstart with a "#" or "*". These are comment lines and ignored.
- \idbe blank. These are ignored.
- \idstart with a "-" and have a legal command line option. These are interpreted just like a command line option.
Following is a copy of the init file we use on our system (the numbers have been added and MUST NOT appear in your file).
1 \id* cal.init
2 \id* This assumes a printout on a laser.
3
4 \id# Set the session start string for reset, landscape, 12 cpi
5 \id-ss=\x1bE\x1b&l1O\x1b(s12H
6 \id# Session end string = reset
7 \id-se=\x1bE
8 \id# printout width = 132 columns
9 \id-w=132
10 \id# use big format
11 \id-b
12 \id# printer name
13 \id-p=/p
14 \id# include holiday information
15 \id-h
16 \id# overstrike on/off strings for date number emphasis
17 \id-os=\x1b(s3B
18 \id-oe=\x1b(s0B
19 \id##### end of cal.init #####
Lines 1 to 4 are comments/blank and are ignored, lines 5 and 7 set the session start strings, line 11 enables "big" format, etc.
You can have many init files and specify the one to use with the -u option. For example:
cal -u=/h1/woof/myinit
will cause the file "/h1/woof/myinit" to be read.
It is important to note that options are read in the order read. For example, if you have "-p=/p" in your init file and use the following command line:
cal -u -p=/p1
the printout will go to "/p1"; not "/p". This behaviour can be exploited to override default setting in an init file. Just place the new settings after the -u flag.
.id
-w[=]value This option changes the width of the printout. By default, CAL assumes an 80 column device.
.id
-y[=]range This option set the range of years to print:
cal -m1 -y=1888 \idprints a calendar for January 1888
cal -m1 -y1995-1996 \idprints a calendar for Jan 1995 to Jan 1996
cal -y-1997 \idprints a calendar from the current month to
\idthe current month in the year 1997
.il=0 pg
The HOLIDAY File
----------------
.lf=l
If you wish holidays to be printed with a calendar, you must include the "holiday" file. This is automatically done, assuming that the file is "/dd/sys/cal.holidays". If you wish to use a different path you can specify the file (eg. -h=/dd/sys/cal.woof).
Each line in the holiday file can be a comment or specify a holiday. Blank lines are ignored.
Comment lines start with a "*" or a "#".
Holiday date entries start with a date, followed by a description. The description must be separated from the date by one or more spaces or TAB characters.
A date can be specified in a number of ways:
1. \idAs an absolute date. In this case just start the line with the month number and the day number separated with a "/". For example:
1/1 New Years
12/25 Christmas
2. \idAs a specified day in the month. For example, the first Monday of February or the Last Thursday in June. To specify a date in this manner you need the month, followed by the digit "1" to "4" or an "L" (or "l"), followed by enough of the letters of the day name to be unique. Again, examples prove the rule:
5/2Sunday Mother's Day
This specifies the second Monday in May.
6/3Sun Father's Day
This specifies the third Sunday in June.
9/1mo Labor Day
This specifies the first Monday in September.
3. \idAs a day of the week preceding a specific date. For example, Canadian Victoria day is the Monday before May 25. This is set with a full date as in (1), followed by a "-" and a day name. For example:
5/25-monday Victoria Day
In this example, "5/25-MO" would work just as well.
4. \idAs a day of the week following specific date. We are not aware of any holidays of this nature, but to specify the Sunday following the November 1, you would use:
11/1+SUN Special Day
5. \idAs an offset from Easter Sunday (or just Easter without an offset). This is needed for dates like Palm Sunday, Easter Monday, etc. The syntax for this is simply the word "Easter" followed by an optional "+" or "-" and a value. Examples:
easter-7 Palm Sunday
easter-2 Good Friday
Easter Easter Sunday
easter+1 Easter Monday
A final, useful, option in a holiday file is the include directive which includes another file. To include a file, use the word "include" at the start of the line followed by a valid pathname. For example,
INCLUDE /dd/sys/birthdays
Would include a birthday file. Note that the pathname is relative to the current data directory, not to the directory where the original file is located.
When the included file is finished, processing will continue in the original file. You can nest includes up to the limit imposed by the operating system (32).
