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