home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: InfoMgt / InfoMgt.zip / cal29a.zip / cal.doc < prev    next >
Text File  |  1993-07-17  |  7KB  |  164 lines
  1. CAL     display a calendar      version 2.9
  2.  
  3. SYNOPSIS
  4.  
  5.         cal [options] [[num_month] year]     (numerical arguments)
  6.         cal [options] [word_month] [year]    (verbal month argument)
  7.  
  8. DESCRIPTION
  9.  
  10. Cal is an enhanced version of the unix cal command.  It is compatible to
  11. the unix version in that it uses the same input arguments and its output
  12. may be piped or redirected anywhere.
  13.  
  14. Cal displays a calendar for a specified year, a specified month and year,
  15. or for the current date.  By default, it displays a calendar for the current
  16. system-date month, with the current day hilighted.  It correctly handles the
  17. transition from the Julian to Gregorian calendars in September 1752.
  18.  
  19. ARGUMENTS
  20.  
  21. A verbally-specified month may be entered without specifying a year in the
  22. argument list; however, a single numerical argument will be interpreted as
  23. a year.  Only the first 3 characters of the month name are significant for
  24. a verbally-specified month.  The command `cal 10' refers to 10 AD, not
  25. October, and not 1910.
  26.  
  27. The options are explained more fully in the ENHANCEMENTS sections below.
  28. The available options are:
  29.  
  30. --nod[ata]              - Do not try to read any appointment data file.
  31. --d[ata-file]=filename  - Read appointments from `filename'
  32.                           (default appointment data filename is cal.dat).
  33.                           You may use --d to 8 times, in a commandline,
  34.                           to specify multiple data file names.
  35. --f[uture]              - If current month is displayed, then show only
  36.                           future appointments from the appointment file,
  37.                           not appointments that are past.
  38.                           NOTE:  This switch was -d in previous versions.
  39. --e[urope]              - Use European format (1st weekday is Monday)
  40. --m[axappts]            - Maximum number of appointments to display.
  41.                           Minimum is 8, maximum is 50, default is 24.
  42. --noc[olor]             - Inhibit the use of colors.
  43. --c[olor-file]=filename - Read color definitions from `filename'
  44.                           (default color filename is cal.col)
  45.  
  46. COMMAND EXAMPLES
  47.  
  48.         cal --f --d=my_dates  display the current month and future
  49.                               appointments defined in file `my_dates'
  50.         cal 1996        display the entire year of 1996
  51.         cal 9 1752      display the month of September 1752
  52.         cal sep 1752    same as above
  53.         cal January     display January of the current year
  54.         cal help        help message displayed for unrecognized arguments
  55.  
  56. ENHANCEMENTS OVER STANDARD `CAL' COMMAND
  57.  
  58. If displaying the single-month format, cal will look for a file called
  59. cal.dat (or whatever you specify with the --d option) in the current
  60. directory and then in cal's directory of origin.  If found, cal will read
  61. the file, looking for special date descriptions for that month which will
  62. be displayed to the right of the calendar.  24 (adjustable default)
  63. appointments may be displayed per month.  If the current date happens to
  64. fall on one of these special dates, it will be flagged by an asterisk.  If
  65. there is room, appointments for the next month may also be displayed (next
  66. month's dates having definitions like "2nd Thursday" will be skipped).
  67. The special date descriptions specified in cal.dat are single lines,
  68. formatted as follows:
  69.  
  70. YYYY MM DD NW xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
  71.  
  72. Where
  73.   YYYY is the year,
  74.   MM is the month (01 - 12),
  75.   DD is the day (00 if the NW field is used),
  76.   NW is the weekday-of-month code (00 if the DD field is used)
  77.   xxxx... is the message, if longer than 50 characters it will be truncated.
  78.  
  79. The data MUST occupy the character fields as shown.  If YYYY is specified
  80. as -999, the month and day are assumed to be annual events such as holidays,
  81. and the description will be displayed for any year.  If MM is specified as
  82. -9, the day is assumed to be a monthly event for the specified year.  In the
  83. weekday-of-month code NW, N signifies on which weekday W the special date
  84. occurs.  For example, 31 indicates the third sunday.  Values of W range from
  85. 1 to 7, for Sunday to Saturday, respectively.  A value of 9 for N indicates
  86. "last" as in 95 for "last thursday."
  87.  
  88. NOTE:  If cal is invoked with the --europe switch, then the W values 1-7
  89. denote Monday(1) to Sunday(7) rather than Sunday(1) to Saturday(7).
  90.  
  91. A line in cal.dat must start with -999 or a 4-digit number to be considered
  92. as data.  The data lines may be in any order.  All these appointments will
  93. be displayed in chronological order, regardless of the ordering in the
  94. appointment data file.
  95.  
  96. The --f commandline switch causes any date description older than today's
  97. date to be ignored, thereby giving room for other descriptions with future
  98. dates to be displayed.  As time progresses through the month, old
  99. descriptions are discarded and newer ones are used.  The --f switch affects
  100. only the display for the current month, and not other months.
  101.  
  102. ENHANCEMENTS SPECIFIC TO MS-DOS and OS/2
  103.  
  104. Cal modifies the display attributes behind its output in order to display
  105. the calendar in attractive colors.  Display manipulation is not done if
  106. cal's output is redirected somewhere else.  When cal starts up, it looks
  107. for a file called cal.col (or whatever you specify with the --c option),
  108. first in the current directory, and then in cal's originating directory.
  109. The colors have defaults if the file is not found.
  110.  
  111. Example of a color definition file:
  112.  
  113. 15 02   video colors for month name
  114. 01 03   video colors for weekday header
  115. 07 01   video colors for normal calendar days
  116. 13 01   video colors for sundays
  117. 14 02   video colors for current day
  118. 07 06   background color for yearly calendar (the space between months)
  119. 11 00   video colors for special day descriptions
  120. 12 08   video colors for asterisk indicating that a description=today
  121.  
  122. FG BG
  123.  
  124. Color definitions must appear as above, as a two-character field for the
  125. foreground color, followed by a space, folowed by a two-character field for
  126. the background color.  The color definitions must start on the first line,
  127. and must not contain blank lines.  Comments may appear after the second
  128. field, provided that the total line length does not exceed 80 characters.
  129.  
  130. Possible colors:
  131.  
  132.         black           0
  133.         blue            1
  134.         green           2
  135.         cyan            3
  136.         red             4
  137.         violet          5
  138.         orange          6
  139.         light gray      7
  140.  
  141.         dark gray       8
  142.         bright blue     9
  143.         bright green    10
  144.         bright cyan     11
  145.         bright red      12
  146.         bright violet   13
  147.         yellow          14
  148.         white           15
  149.  
  150. Specifying a background color from 8 to 15 will result in a background
  151. color of 0 to 7, with flashing text.
  152.  
  153. AUTHOR
  154.  
  155.         Alex Matulich  -  uucp:     alex@bilver.uucp
  156.                           internet: alex%bilver@peora.sdc.ccur.com
  157.                                     alex@bilver.oau.org
  158.                           fidonet:  1:363/140, Alex Matulich
  159.  
  160.         ...with enhancements and modifications by other contributors.
  161.  
  162.         (c) 1992 by Unicorn Research Corporation.  All rights reserved.
  163.         Inspired by an Amiga program by Gary L. Brant.
  164.