| 1 |
<HTML> |
| 2 |
<HEAD><TITLE>CAL</TITLE> |
| 3 |
</HEAD> |
| 4 |
|
| 5 |
<BODY> |
| 6 |
<H1 ALIGN=CENTER>CAL - display a calendar<BR> |
| 7 |
<SMALL>(substitute unix "cal" command)</SMALL></H1> |
| 8 |
<P ALIGN=CENTER> |
| 9 |
by <A HREF="mailto:alex@unicorn.us.com">Alex Matulich</A>, |
| 10 |
<A HREF="http://unicorn.us.com">Unicorn Research Corporation</A><BR> |
| 11 |
Version 4.0</P> |
| 12 |
|
| 13 |
<HR> |
| 14 |
|
| 15 |
<H3>Contents:</H3> |
| 16 |
<UL> |
| 17 |
<LI><A HREF="#syno">Synopsis</A> |
| 18 |
<LI><A HREF="#desc">Description</A> |
| 19 |
<LI><A HREF="#args">Arguments</A> |
| 20 |
<LI><A HREF="#exam">Examples</A> |
| 21 |
<LI><A HREF="#enha">Enhancements over standard cal command</A><UL> |
| 22 |
<LI><A HREF="#caldat">Date files (appointments and reminders)</A> |
| 23 |
<LI><A HREF="#color">Color attributes</A></UL> |
| 24 |
<LI><A HREF="#files">Files in the archive, bugs</A><BR> |
| 25 |
|
| 26 |
<LI><A HREF="#gimme">Where to get cal</A> |
| 27 |
<LI><A HREF="http://unicorn.us.com/pub/cal40/cal.dat">Download a |
| 28 |
sample cal.dat file</A> for you to modify (local shell account holders |
| 29 |
only). Rename to .cal.dat in your home directory. |
| 30 |
</UL> |
| 31 |
|
| 32 |
<BR><HR> |
| 33 |
<H2><A NAME="syno">NAME</A></H2> |
| 34 |
<DL><DT>cal - displays a calendar</DL> |
| 35 |
|
| 36 |
<H2>SYNOPSIS</H2> |
| 37 |
<DL> |
| 38 |
<DT> |
| 39 |
<DD><TT>cal [options] [[num_month] year]</TT> |
| 40 |
<DT> |
| 41 |
<DD><TT>cal [options] [word_month] [year]</TT> |
| 42 |
</DL> |
| 43 |
|
| 44 |
<H2><A NAME="desc">DESCRIPTION</A></H2> |
| 45 |
|
| 46 |
<p>By default, cal will display a calendar for the current month |
| 47 |
with the current day marked. By specifing certain arguments, cal |
| 48 |
will display a calendar for a whole year or a specified month and |
| 49 |
year.</p> |
| 50 |
|
| 51 |
<p>The transition from the Julian to Gregorian calendar is assumed |
| 52 |
to have occured in 1752 on the 3rd of September. Ten days following |
| 53 |
that date were eliminated by the reformation, so the calendar for |
| 54 |
that month is a bit unusual.</p> |
| 55 |
|
| 56 |
<p>If displaying a calendar in the single-month format, cal will |
| 57 |
look for a date file. If found, cal will read the file, looking for |
| 58 |
special date descriptions for that month which will be displayed to |
| 59 |
the right of the calendar. By default, up to 24 appointments may be |
| 60 |
displayed per month. If the current date happens to fall on one of |
| 61 |
these special dates, it will be flagged by an asterisk. If there |
| 62 |
is room, appointments for the next month may also be displayed with |
| 63 |
some limitations (currently, special dates such as the 3rd Thursday |
| 64 |
of will not be calculated for next month).</p> |
| 65 |
|
| 66 |
<p>cal can also optionally use colors when displaying the calendar. |
| 67 |
It will not display colors any time the calendar is not directly |
| 68 |
displaying on the console. This is generally the desired behavior |
| 69 |
when your redirecting cal's output to another program or a file.</p> |
| 70 |
|
| 71 |
<H2><A NAME="args">ARGUMENTS</A></H2> |
| 72 |
|
| 73 |
<P>A verbally-specified month may be entered without specifying a year |
| 74 |
in the argument list; however, a single numerical argument will be |
| 75 |
interpreted as a year. Only the first 3 characters of the month name are |
| 76 |
significant for a verbally-specified month. <I><B>NOTE:</B> The command |
| 77 |
"<B><TT>cal 10</TT></B>" refers to <B>10 AD</B>, not October, and |
| 78 |
not 1910.</I></P> |
| 79 |
|
| 80 |
<P>The available options are:</P> |
| 81 |
|
| 82 |
<dl> |
| 83 |
<dt><tt><b>--3</b>[months]</tt> |
| 84 |
<dd>Display previous/current/next month together. This |
| 85 |
option will be ignored when displaying a full year. |
| 86 |
|
| 87 |
<dt><tt><b>--a</b>[ppts]</tt> |
| 88 |
<dd>Maximum number of appointments to display. Minimum |
| 89 |
is 8, maximum is 50, default is 24. |
| 90 |
|
| 91 |
<dt><tt><b>--col</b>[or-file]=filename</tt> |
| 92 |
<dd>Read color definitions from `filename' (default |
| 93 |
color filename depends on operating system). |
| 94 |
|
| 95 |
<dt><tt><b>--con</b>[tinue]=n</tt> |
| 96 |
<dd>Display the next n successive months starting with |
| 97 |
the month specified. |
| 98 |
|
| 99 |
<dt><tt><b>--d</b>[ata-file]=filename</tt> |
| 100 |
<dd>Read appointments from `filename' (default appointment data |
| 101 |
filename depends on operating system). You may use -d up to 8 times |
| 102 |
in a commandline to specify multiple data file names. |
| 103 |
|
| 104 |
<dt><tt><b>--e</b>[urope]</tt> |
| 105 |
<dd>Use European format (first weekday is Monday). |
| 106 |
|
| 107 |
<dt><tt><b>--f</b>[uture]</tt> |
| 108 |
|
| 109 |
<dd>If current month is displayed, then show only future |
| 110 |
appointments from the date file, not appointments that are past. |
| 111 |
This allows room for other descriptions with future dates to be |
| 112 |
displayed. As time progresses through the month, old descriptions |
| 113 |
are discarded and newer ones are used. The --future switch affects |
| 114 |
only the display for the current month, and not other months. |
| 115 |
|
| 116 |
<dt><tt><b>--j</b>[ulian]</tt> |
| 117 |
<dd>Display Julian dates (days one-based, numbered from January 1. |
| 118 |
|
| 119 |
<dt><tt><b>--m</b>[onday]</tt> |
| 120 |
<dd>Display Monday as the first day of the week (same as --europe) |
| 121 |
|
| 122 |
<dt><tt><b>--noc</b>[olor]</tt> |
| 123 |
<dd>Inhibit the use of colors. |
| 124 |
|
| 125 |
<dt><tt><b>--nod</b>[ata]</tt> |
| 126 |
<dd>Do not try to read any appointment data file. |
| 127 |
|
| 128 |
<dt><tt><b>--p</b>[ause]</tt> |
| 129 |
<dd>Pause before exiting and prompt for a keystroke. |
| 130 |
|
| 131 |
<dt><tt><b>--th</b>[ismonth]</tt> |
| 132 |
<dd>Disable display of next month appointments; show only current month's. |
| 133 |
|
| 134 |
<dt><tt><b>--to</b>[day]</tt> |
| 135 |
<dd>Show only today's appointments. |
| 136 |
|
| 137 |
<dt><tt><b>--u</b>[se-color]</tt> |
| 138 |
<dd>Allow the use of colors. |
| 139 |
|
| 140 |
<dt><tt><b>--y</b>[ear]</tt> |
| 141 |
<dd>Display a calendar for the current year. |
| 142 |
</dl> |
| 143 |
|
| 144 |
<p>There is an optional environment variable that can be used by cal |
| 145 |
if found. If CALOPT is set then cal will read it and use any valid |
| 146 |
command line options found. This allows any commonly used switches |
| 147 |
to be set in your environment and always used (e.g. --europe). Cal |
| 148 |
will produce its usage screen when run if any invalid options are |
| 149 |
set in this variable.</p> |
| 150 |
|
| 151 |
<H2><A NAME="exam">COMMAND EXAMPLES</A></H2> |
| 152 |
<DL> |
| 153 |
<DT><TT>cal -f -d=my_dates</TT> |
| 154 |
<DD>display the current month and future appointments defined in file |
| 155 |
'my_dates' |
| 156 |
<DT><TT>cal 1996</TT> |
| 157 |
<DD>display the entire year of 1996 |
| 158 |
<DT><TT>cal 9 1752</TT> |
| 159 |
<DD>display the month of September 1752 |
| 160 |
<DT><TT>cal sep 1752</TT> |
| 161 |
<DD>same as above |
| 162 |
<DT><TT>cal January</TT> |
| 163 |
<DD>display January of the current year |
| 164 |
<DT><TT>cal help</TT> |
| 165 |
<DD>help message displayed for unrecognized arguments |
| 166 |
</DL><BR> |
| 167 |
|
| 168 |
<A NAME="enha"> </A> |
| 169 |
|
| 170 |
<H2><A NAME="caldat">DATE FILES</A></H2> |
| 171 |
|
| 172 |
<p>cal will search for a date file called cal.dat in the directory |
| 173 |
it was executed from. If not found it will search in the users |
| 174 |
$HOME directory for a file called .cal.dat. If still not found, it |
| 175 |
will look for a global cal.dat in a system wide directory. To find |
| 176 |
out where this location is you can run cal --help which will display |
| 177 |
the location.</p> |
| 178 |
|
| 179 |
<p>The special date descriptions specified in the date file are |
| 180 |
single lines, formatted as follows:</p> |
| 181 |
|
| 182 |
<p><tt>YYYY MM DD NW xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx</tt></p> |
| 183 |
|
| 184 |
<p>where</p> |
| 185 |
<dl> |
| 186 |
<dt><tt>YYYY</tt> is the year, |
| 187 |
<dt><tt>MM</tt> is the month (01 - 12), |
| 188 |
<dt><tt>DD</tt> is the day (00 if the NW field is used), |
| 189 |
<dt><tt>NW</tt> is the weekday-of-month code (00 if the DD field is used) |
| 190 |
<dt><tt>xxxx</tt> is the description; it will be truncated as necessary to fit |
| 191 |
</dl> |
| 192 |
|
| 193 |
<p>The data MUST occupy the character fields as shown. If YYYY is |
| 194 |
specified as -999, the month and day are assumed to be annual events |
| 195 |
such as holidays, and the description will be displayed for any |
| 196 |
year. If MM is specified as -9, the day is assumed to be a monthly |
| 197 |
event for the specified year. In the weekday-of-month code NW, N |
| 198 |
signifies on which weekday W the special date occurs. For example, |
| 199 |
31 indicates the third sunday. Values of W range from 1 to 7, for |
| 200 |
Sunday to Saturday, respectively. A value of 9 for N indicates |
| 201 |
"last" as in 95 for "last thursday."</p> |
| 202 |
|
| 203 |
<p>If ALL of the fields contain a positive number and the year is |
| 204 |
at least 1970, then the description is assumed to be periodic, |
| 205 |
starting at the given date, with the period in days specified in NW |
| 206 |
(e.g. 1995 01 06 14 will display the description every 2nd Friday |
| 207 |
using 6 January 1995 as the base date). The base date does not get |
| 208 |
displayed.</p> |
| 209 |
|
| 210 |
<p>You can display birthdays and anniversaries by putting the year |
| 211 |
of birth (or other special event) inside brackets or braces, in |
| 212 |
the description. This number is converted to the number of years |
| 213 |
since the year you indicate and the brackets or braces are removed |
| 214 |
from the output. If braces {} are used the number will have an |
| 215 |
ordinal suffix, as in 21st, 32nd, 43rd, 54th, etc. If the number |
| 216 |
in brackets or braces is greater than the current year, the number |
| 217 |
will be displayed unchanged. Example: "Alex's {1961} birthday" will |
| 218 |
display as "Alex's 34th birthday" (if the current year is 1995). If |
| 219 |
you need to include brackets or braces in your output then you can |
| 220 |
escape them by prefixing it with a '\'. Example: "Alex's \{1961\} |
| 221 |
birthday" will be displayed as "Alex's {1961} birthday".</p> |
| 222 |
|
| 223 |
<p>NOTE: If cal is invoked with the --europe or --monday switch, |
| 224 |
then the W values 1-7 denote Monday(1) to Sunday(7) rather than |
| 225 |
Sunday(1) to Saturday(7).</p> |
| 226 |
|
| 227 |
<p>A line in cal.dat must start with -999 or a 4-digit number to be |
| 228 |
considered as data. The data lines may be in any order. All these |
| 229 |
appointments will be displayed in chronological order, regardless of |
| 230 |
the ordering in the appointment data file.</p> |
| 231 |
|
| 232 |
<p>If cal was compiled with the reminder support then call will also |
| 233 |
search for the files dates and .dates in the same places as for |
| 234 |
the cal.dat equivalents. The dates file is used by the reminder(1) |
| 235 |
program and is an alternate, less-powerful format for specifying |
| 236 |
descriptions. A file in this format cannot be specified with the |
| 237 |
--data-file= option.</p> |
| 238 |
|
| 239 |
<p>The reminder format consists of text lines of length < screen |
| 240 |
width in the following format:</p> |
| 241 |
|
| 242 |
<p><tt>DDDDDDDD:N:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx:yyyyyy:S</tt></p> |
| 243 |
|
| 244 |
<p>where</p> |
| 245 |
<dl> |
| 246 |
<dt><tt>DDDDDDDD</tt> |
| 247 |
<dd>is the date in one of the following formats: |
| 248 |
|
| 249 |
<dt><tt>M/D/Y</tt> |
| 250 |
<dd>an event occurring on a specific day (year can be two or four |
| 251 |
digits, but must be two for backward compatibility with reminder) |
| 252 |
|
| 253 |
<dt><tt>M/D</tt> |
| 254 |
<dd>an event occurring every year |
| 255 |
|
| 256 |
<dt><tt>D</tt> |
| 257 |
<dd>an event occurring every month |
| 258 |
|
| 259 |
<dt><tt>DDD</tt> |
| 260 |
<dd>an event occurring every week (day of the week is 'Sun', 'Mon', etc.) |
| 261 |
|
| 262 |
<dt><tt>N</tt> |
| 263 |
<dd>is the number of days notice of the event to give |
| 264 |
the user (ignored by cal) |
| 265 |
|
| 266 |
<dt><tt>xxxxx</tt> |
| 267 |
<dd>the event description |
| 268 |
|
| 269 |
<dt><tt>yyyyy</tt> |
| 270 |
<dd>an optional receptor of the event (e.g. Mr. Jones) |
| 271 |
|
| 272 |
<dt><tt>S</tt> |
| 273 |
<dd>status flag, either N for normal event or D for a deleted (not |
| 274 |
displayed) event |
| 275 |
</dl> |
| 276 |
|
| 277 |
<p>Blank lines are ignored. A line otherwise not in the above |
| 278 |
format is assume to specify a file name from which to read more |
| 279 |
events. The file is searched for in the usual places.</p> |
| 280 |
|
| 281 |
<H2><a name="#color">COLOR ATTRIBUTES</a></h2> |
| 282 |
|
| 283 |
<p>cal will search for a color definition file called cal.col in |
| 284 |
the directory it was executed from. If not found it will search in |
| 285 |
the users $HOME directory for a file called .cal.col. If still not |
| 286 |
found, it will look for a global cal.col in a system wide directory. |
| 287 |
To find out where this location is you can run cal --help which will |
| 288 |
display the location.</p> |
| 289 |
|
| 290 |
<p>Users may override the default colors used when displaying |
| 291 |
calendars. This may be done by creating a color definition |
| 292 |
file.</p> |
| 293 |
|
| 294 |
<p>Example of a color definition file:</p> |
| 295 |
|
| 296 |
<dl><dt> |
| 297 |
<dd><tt>15 02</tt> video colors for month name |
| 298 |
<dd><tt>01 03</tt> video colors for weekday header |
| 299 |
<dd><tt>07 01</tt> video colors for normal calendar days |
| 300 |
<dd><tt>13 01</tt> video colors for sundays |
| 301 |
<dd><tt>14 02</tt> video colors for current day |
| 302 |
<dd><tt>07 06</tt> bkgd for yearly calendar (space between months) |
| 303 |
<dd><tt>11 00</tt> video colors for special day descriptions |
| 304 |
<dd><tt>12 08</tt> video colors for * indicating descr.=today |
| 305 |
</dl> |
| 306 |
|
| 307 |
<P>Color definitions must appear as above, as a two-character field for |
| 308 |
the foreground color, followed by a space, folowed by a two-character |
| 309 |
field for the background color. The color definitions must start on the |
| 310 |
first line, and must not contain blank lines. Comments may appear after |
| 311 |
the second field, provided that the total line length does not exceed 80 |
| 312 |
characters. </P> |
| 313 |
|
| 314 |
<DL> |
| 315 |
<DT>Possible colors: |
| 316 |
<DD>0 black |
| 317 |
<DD>1 blue |
| 318 |
<DD>2 green |
| 319 |
<DD>3 cyan |
| 320 |
<DD>4 red |
| 321 |
<DD>5 violet |
| 322 |
<DD>6 orange |
| 323 |
<DD>7 light gray |
| 324 |
<DD> |
| 325 |
<DD>8 dark gray |
| 326 |
<DD>9 bright blue |
| 327 |
<DD>10 bright green |
| 328 |
<DD>11 bright cyan |
| 329 |
<DD>12 bright red |
| 330 |
<DD>13 bright violet |
| 331 |
<DD>14 yellow |
| 332 |
<DD>15 white |
| 333 |
</DL> |
| 334 |
|
| 335 |
<P>Specifying a background color from 8 to 15 will result in a |
| 336 |
background color of 0 to 7, with flashing text.</P> |
| 337 |
|
| 338 |
<H2><A NAME="files">FILES</A></H2> |
| 339 |
<DL> |
| 340 |
<DT>cal.dat |
| 341 |
<DD> Date file. Can be located in the current |
| 342 |
directory or the directory in which cal is run from. |
| 343 |
<DT>cal.col |
| 344 |
<DD> Color definition file. Can be located in the current |
| 345 |
directory or the directory in which cal is run from. |
| 346 |
<DT>$HOME/.cal.dat |
| 347 |
<DD> unix local date file. |
| 348 |
<DT>$HOME/.cal.col |
| 349 |
<DD> unix local color file. |
| 350 |
<DT>$HOME/.dates |
| 351 |
<DD> Date file used with unix reminder program and can be used |
| 352 |
with cal. |
| 353 |
</DL> |
| 354 |
|
| 355 |
<H2>BUGS</H2> |
| 356 |
|
| 357 |
<P>Cal 4.0 had a bug where the line in cal.dat<br> |
| 358 |
<tt>-999 06 00 16 National Donut Day {1938}</tt><br> |
| 359 |
would not display on the correct day. Fixed in 4.1.</P> |
| 360 |
|
| 361 |
<H2><A NAME="gimme">WHERE TO GET CAL</A></H2> |
| 362 |
|
| 363 |
<P>The latest version of cal is available from |
| 364 |
<A HREF="http://unicorn.us.com/pub/cal40.zip"> |
| 365 |
http://unicorn.us.com/pub/cal40.zip</A></P> |
| 366 |
|
| 367 |
<H2>AUTHOR</H2> |
| 368 |
|
| 369 |
<P>Alex Matulich - <A HREF="mailto:alex@unicorn.us.com"> |
| 370 |
alex@unicorn.us.com</A></P> |
| 371 |
|
| 372 |
<P>...with enhancements and modifications by other contributors.</p> |
| 373 |
|
| 374 |
<IMG SRC="/images/unicrn32.gif" ALIGN=LEFT ALT="-"> |
| 375 |
© 1993-2002 by <A HREF="http://unicorn.us.com"> |
| 376 |
Unicorn Research Corporation</A><br> |
| 377 |
Inspired by an Amiga program by Gary L. Brant.</P><br clear=all> |
| 378 |
|
| 379 |
<H2>SEE ALSO</H2> |
| 380 |
<p>date(1), reminder(1), rs(1)</p> |
| 381 |
|
| 382 |
</BODY> |
| 383 |
</HTML> |
| 384 |
|