****            **            ****   
                     **  **          ****            **    
                    **              **  **           **    
                    **              **  **           **    
                    **              ******           **   *
                     **  **         **  **           **  **
                      ****          **  **          *******
    
    
                          Calendar Generating Program
                                      for
                                   OS9/68000
    
                                 Copyright 1995
                           Bob van der Poel Software
    
                                  N O T I C E
                                  -----------
    
    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.
    
                                  Introduction
                                  ------------
    
    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.















                                     Page 1                                 







                              Command Line Options
                              --------------------
    
    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:
    
    -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.
         
    -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





                                     Page 2                                 







         course, you could get the same results with the command:
         
            cal -m1-4
         
         
    -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.
         
    -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".
         
    -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     prints January to December
            cal -m=4        prints April
            cal -m-12       prints 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.
         
    -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.
         
    -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.
         
    -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).





                                     Page 3                                 







         Of course, you could do the same with a redirect command (such is
         the flexibility of OS9).
         
    -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.
         
    -ss[=]str  This string is sent at the end of "big" calendar. Useful to
         undo the effects of "-se".
         
    -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:
         
            - start with a "#" or "*". These are comment lines and ignored.
            - be blank. These are ignored.
            - start 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 * cal.init
            2 * This assumes a printout on a laser.
            3
            4 # Set the session start string for reset, landscape, 12 cpi
            5 -ss=1bE1b&l1O1b(s12H
            6 # Session end string = reset
            7 -se=1bE
            8 # printout width = 132 columns
            9 -w=132
            10 # use big format
            11 -b
            12 # printer name
            13 -p=/p
            14 # include holiday information
            15 -h
            16 # overstrike on/off strings for date number emphasis
            17 -os=1b(s3B
            18 -oe=1b(s0B
            19 ##### 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 -





                                     Page 4                                 







         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.
         
    -w[=]value  This option changes the width of the printout. By default,
         CAL assumes an 80 column device.
         
    -y[=]range  This option set the range of years to print:
         
            cal -m1 -y=1888         prints a calendar for January 1888
            cal -m1 -y1995-1996     prints a calendar for Jan 1995 to Jan
                                    1996
            cal -y-1997             prints a calendar from the current
                                    month to
                                    the current month in the year 1997
         






























                                     Page 5                                 







    The HOLIDAY File
    ----------------
    
    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. As 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. As 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. As 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. As a day of the week following specific date. We are not aware of





                                     Page 6                                 







       any holidays of this nature, but to specify the Sunday following the
       November 1, you would use:
    
        11/1+SUN        Special Day
    
    5. As 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).






























                                     Page 7