home *** CD-ROM | disk | FTP | other *** search
/ rtsi.com / 2014.01.www.rtsi.com.tar / www.rtsi.com / OS9 / OSK / CMDS / cal.lzh / docs.txt next >
Text File  |  1995-02-26  |  14KB  |  463 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.                       ****            **            ****   
  8.                      **  **          ****            **    
  9.                     **              **  **           **    
  10.                     **              **  **           **    
  11.                     **              ******           **   *
  12.                      **  **         **  **           **  **
  13.                       ****          **  **          *******
  14.     
  15.     
  16.                           Calendar Generating Program
  17.                                       for
  18.                                    OS9/68000
  19.     
  20.                                  Copyright 1995
  21.                            Bob van der Poel Software
  22.     
  23.                                   N O T I C E
  24.                                   -----------
  25.     
  26.     This software is protected by copyright. It is offered on an "as is"
  27.     basis. Under our shareware agreement you have no obligation to register
  28.     the software. However, if you like it you should send in the requested
  29.     contribution. If you do not wish to register the software, please
  30.     delete the program from your system.
  31.     
  32.     If you like this software we ask that you complete the enclosed
  33.     registration form and mail it to us with a $20.00 fee. In return we
  34.     will send you the latest version of CAL, our latest catalogue and a
  35.     $10.00 certificate redeemable on any of our commercial products.
  36.     
  37.     You are free to redistribute this software by any means. However, you
  38.     can not change any of the files you received in the original package.
  39.     You can not charge any fee for distributing the package.
  40.     
  41.                                   Introduction
  42.                                   ------------
  43.     
  44.     CAL is a program which will print out calendars and remind you of
  45.     holidays and appointments. It is easy to use and can be configured to
  46.     printout in various formats and to the printer or screen. CAL will
  47.     accept any date; however, you should be aware that because the current
  48.     calendar has not always been in use, dates prior to 1753 will be
  49.     mythical at best.
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.                                      Page 1                                 
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72.  
  73.                               Command Line Options
  74.                               --------------------
  75.     
  76.     If you just type "cal" at an OS9 prompt you will get a printout of
  77.     calendars for the last, current and next month. This is CAL's default
  78.     operation. However, there are many ways to change the defaults. The
  79.     changes are done via command line arguments. Each argument must be
  80.     prefaced with a '-'. You can concatenate several options together, so
  81.     long as none of the intermediate arguments do not need an argument. For
  82.     example:
  83.     
  84.         cal -m10
  85.     
  86.     will display a calendar for November of the current year. And:
  87.     
  88.         cal -gm1-12 -y1994
  89.     
  90.     will display calendars for each month in 1994, with the graphics
  91.     characters turned off. In both cases, the calendars will be displayed
  92.     three wide. We assume that you have an 80 column display (don't
  93.     worry...you can change that!). However, if you try this:
  94.     
  95.         cal -m1y1995
  96.     
  97.     the "y1995" will be ignored.
  98.     
  99.     For each command option which needs a parameter, you can use an option
  100.     "=". However, using the "=" or not, you must not have any spaces
  101.     between the option name and the parameter. For example:
  102.     
  103.         cal -m=12
  104.         cal -m12
  105.     
  106.     Are identical. However:
  107.     
  108.         cal -m 12
  109.     
  110.     will not work.
  111.     
  112.     
  113.     Each of the various command options will now be explained:
  114.     
  115.     -b  This flag enables printing in "big" format. This format is very
  116.          nice to use on a printer (you'll never have to line up at the bank
  117.          again in the new year). Rather than trying to explain the format
  118.          here, just do a "cal -b" to see the results.
  119.          
  120.     -c[=]value  This command can be used to set the number of calendars to
  121.          print. For example, if you use the command line:
  122.          
  123.             cal -m1 c4
  124.          
  125.          you will get calendars for January, February, March and April. Of
  126.  
  127.  
  128.  
  129.  
  130.  
  131.                                      Page 2                                 
  132.  
  133.  
  134.  
  135.  
  136.  
  137.  
  138.  
  139.          course, you could get the same results with the command:
  140.          
  141.             cal -m1-4
  142.          
  143.          
  144.     -g  This flag will disable the use of 8 bit, IBM graphics characters
  145.          when printing the calendar. Most terminals and printers now
  146.          support this character set; however, some don't...so it is an
  147.          option.
  148.          
  149.     -h[=][path]  Normally, holidays are not printed. However, you can print
  150.          them with this flag. The format of the holiday file is detailed
  151.          later in this document. If you simply include the -h flag (without
  152.          a filename) CAL will look for the holiday data file
  153.          "/dd/sys/cal.holidays". If you wish to use a different filename,
  154.          just place it after the -h. For example:
  155.          
  156.             cal -h=/h1/woof/myholidays
  157.          
  158.          will look for the file "myholidays" in the directory "woof" on the
  159.          device "h1".
  160.          
  161.     -m[=]range  This option lets you specify the months to print. You can
  162.          specify the range in a number of ways...again, a few examples
  163.          prove the rule:
  164.          
  165.             cal -m=1-12     prints January to December
  166.             cal -m=4        prints April
  167.             cal -m-12       prints from the current month to December
  168.          
  169.          If you specify a range and the second value is less than the
  170.          first, the second will be used for the next year. For example:
  171.          
  172.             cal -m12-1 -y1995
  173.          
  174.          will display calendars for December 1995 and January 1996.
  175.          
  176.     -oe[=]str  This option sets the codes which enable overstrike mode on
  177.          your printer/terminal. It is used to print the dates of the month
  178.          when doing a "big" calendar. The definitions for the "str" are
  179.          detailed later in this document.
  180.          
  181.     -os[=]str  This option set the codes with disable overstrike mode. It
  182.          is used when printing the dates of the month when doing a "big"
  183.          calendar.
  184.          
  185.     -p[=]path  Normally, the printout is done to standard out (your
  186.          terminal). You can change this by using the -p option. For
  187.          example:
  188.          
  189.             cal -p=/p
  190.          
  191.          will print the calendar to the device "/p" (normally, a printer).
  192.  
  193.  
  194.  
  195.  
  196.  
  197.                                      Page 3                                 
  198.  
  199.  
  200.  
  201.  
  202.  
  203.  
  204.  
  205.          Of course, you could do the same with a redirect command (such is
  206.          the flexibility of OS9).
  207.          
  208.     -se[=]str  When printing in "big" mode, this string is printed at the
  209.          start of the calendar. See later in this document for the details
  210.          on "str". Also, see the example "cal.init" file.
  211.          
  212.     -ss[=]str  This string is sent at the end of "big" calendar. Useful to
  213.          undo the effects of "-se".
  214.          
  215.     -u[-][path]  You can use initialization files with CAL. Normally, they
  216.          are not used (which leaves CAL in the default mode). However, an
  217.          init file is very useful when doing printouts to the printer, etc.
  218.          If you call CAL with:
  219.          
  220.             cal -u
  221.          
  222.          the file "/dd/sys/cal.init" will be read. The format of this file
  223.          is quite simple: it is just a collection of command line options.
  224.          Each line in an init file can:
  225.          
  226.             - start with a "#" or "*". These are comment lines and ignored.
  227.             - be blank. These are ignored.
  228.             - start with a "-" and have a legal command line option. These
  229.               are interpreted just like a command line option.
  230.          
  231.          Following is a copy of the init file we use on our system (the
  232.          numbers have been added and MUST NOT appear in your file).
  233.          
  234.             1 * cal.init
  235.             2 * This assumes a printout on a laser.
  236.             3
  237.             4 # Set the session start string for reset, landscape, 12 cpi
  238.             5 -ss=1bE1b&l1O1b(s12H
  239.             6 # Session end string = reset
  240.             7 -se=1bE
  241.             8 # printout width = 132 columns
  242.             9 -w=132
  243.             10 # use big format
  244.             11 -b
  245.             12 # printer name
  246.             13 -p=/p
  247.             14 # include holiday information
  248.             15 -h
  249.             16 # overstrike on/off strings for date number emphasis
  250.             17 -os=1b(s3B
  251.             18 -oe=1b(s0B
  252.             19 ##### end of cal.init #####
  253.          
  254.          Lines 1 to 4 are comments/blank and are ignored, lines 5 and 7 set
  255.          the session start strings, line 11 enables "big" format, etc.
  256.          
  257.          You can have many init files and specify the one to use with the -
  258.  
  259.  
  260.  
  261.  
  262.  
  263.                                      Page 4                                 
  264.  
  265.  
  266.  
  267.  
  268.  
  269.  
  270.  
  271.          u option. For example:
  272.          
  273.             cal -u=/h1/woof/myinit
  274.          
  275.          will cause the file "/h1/woof/myinit" to be read.
  276.          
  277.          It is important to note that options are read in the order read.
  278.          For example, if you have "-p=/p" in your init file and use the
  279.          following command line:
  280.          
  281.             cal -u -p=/p1
  282.          
  283.          the printout will go to "/p1"; not "/p". This behaviour can be
  284.          exploited to override default setting in an init file. Just place
  285.          the new settings after the -u flag.
  286.          
  287.     -w[=]value  This option changes the width of the printout. By default,
  288.          CAL assumes an 80 column device.
  289.          
  290.     -y[=]range  This option set the range of years to print:
  291.          
  292.             cal -m1 -y=1888         prints a calendar for January 1888
  293.             cal -m1 -y1995-1996     prints a calendar for Jan 1995 to Jan
  294.                                     1996
  295.             cal -y-1997             prints a calendar from the current
  296.                                     month to
  297.                                     the current month in the year 1997
  298.          
  299.  
  300.  
  301.  
  302.  
  303.  
  304.  
  305.  
  306.  
  307.  
  308.  
  309.  
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327.  
  328.  
  329.                                      Page 5                                 
  330.  
  331.  
  332.  
  333.  
  334.  
  335.  
  336.  
  337.     The HOLIDAY File
  338.     ----------------
  339.     
  340.     If you wish holidays to be printed with a calendar, you must include
  341.     the "holiday" file. This is automatically done, assuming that the file
  342.     is "/dd/sys/cal.holidays". If you wish to use a different path you can
  343.     specify the file (eg. -h=/dd/sys/cal.woof).
  344.     
  345.     Each line in the holiday file can be a comment or specify a holiday.
  346.     Blank lines are ignored.
  347.     
  348.     Comment lines start with a "*" or a "#".
  349.     
  350.     Holiday date entries start with a date, followed by a description. The
  351.     description must be separated from the date by one or more spaces or
  352.     TAB characters.
  353.     
  354.     A date can be specified in a number of ways:
  355.     
  356.     1. As an absolute date. In this case just start the line with the month
  357.        number and the day number separated with a "/". For example:
  358.     
  359.         1/1     New Years
  360.         12/25   Christmas
  361.     
  362.     2. As a specified day in the month. For example, the first Monday of
  363.        February or the Last Thursday in June. To specify a date in this
  364.        manner you need the month, followed by the digit "1" to "4" or an
  365.        "L" (or "l"), followed by enough of the letters of the day name to
  366.        be unique. Again, examples prove the rule:
  367.     
  368.         5/2Sunday   Mother's Day
  369.     
  370.     This specifies the second Monday in May.
  371.     
  372.         6/3Sun      Father's Day
  373.     
  374.     This specifies the third Sunday in June.
  375.     
  376.         9/1mo       Labor Day
  377.     
  378.     This specifies the first Monday in September.
  379.     
  380.     3. As a day of the week preceding a specific date. For example,
  381.        Canadian Victoria day is the Monday before May 25. This is set with
  382.        a full date as in (1), followed by a "-" and a day name. For
  383.        example:
  384.     
  385.         5/25-monday     Victoria Day
  386.     
  387.     In this example, "5/25-MO" would work just as well.
  388.     
  389.     4. As a day of the week following specific date. We are not aware of
  390.  
  391.  
  392.  
  393.  
  394.  
  395.                                      Page 6                                 
  396.  
  397.  
  398.  
  399.  
  400.  
  401.  
  402.  
  403.        any holidays of this nature, but to specify the Sunday following the
  404.        November 1, you would use:
  405.     
  406.         11/1+SUN        Special Day
  407.     
  408.     5. As an offset from Easter Sunday (or just Easter without an offset).
  409.        This is needed for dates like Palm Sunday, Easter Monday, etc. The
  410.        syntax for this is simply the word "Easter" followed by an optional
  411.        "+" or "-" and a value. Examples:
  412.     
  413.         easter-7    Palm Sunday
  414.         easter-2    Good Friday
  415.         Easter      Easter Sunday
  416.         easter+1    Easter Monday
  417.     
  418.     A final, useful, option in a holiday file is the include directive
  419.     which includes another file. To include a file, use the word "include"
  420.     at the start of the line followed by a valid pathname. For example,
  421.     
  422.         INCLUDE /dd/sys/birthdays
  423.     
  424.     Would include a birthday file. Note that the pathname is relative to
  425.     the current data directory, not to the directory where the original
  426.     file is located.
  427.     
  428.     When the included file is finished, processing will continue in the
  429.     original file. You can nest includes up to the limit imposed by the
  430.     operating system (32).
  431.  
  432.  
  433.  
  434.  
  435.  
  436.  
  437.  
  438.  
  439.  
  440.  
  441.  
  442.  
  443.  
  444.  
  445.  
  446.  
  447.  
  448.  
  449.  
  450.  
  451.  
  452.  
  453.  
  454.  
  455.  
  456.  
  457.  
  458.  
  459.  
  460.  
  461.                                      Page 7                                 
  462.  
  463.