Debian Codegraph @

cal.html

raw
1 <HTML>
2 <HEAD><TITLE>CAL</TITLE>
3 </HEAD>
4
5 <BODY>
6 <H1 ALIGN=CENTER>CAL &nbsp;-&nbsp; display a calendar<BR>
7 <SMALL>(substitute unix "cal" command)</SMALL></H1>
8 <P ALIGN=CENTER>
9 by <A HREF="mailto:alex&#64;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>&nbsp;
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&nbsp;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 &lt; 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> &nbsp; video colors for month name
298 <dd><tt>01 03</tt> &nbsp; video colors for weekday header
299 <dd><tt>07 01</tt> &nbsp; video colors for normal calendar days
300 <dd><tt>13 01</tt> &nbsp; video colors for sundays
301 <dd><tt>14 02</tt> &nbsp; video colors for current day
302 <dd><tt>07 06</tt> &nbsp; bkgd for yearly calendar (space between months)
303 <dd><tt>11 00</tt> &nbsp; video colors for special day descriptions
304 <dd><tt>12 08</tt> &nbsp; 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 &nbsp; black
317 <DD>1 &nbsp; blue
318 <DD>2 &nbsp; green
319 <DD>3 &nbsp; cyan
320 <DD>4 &nbsp; red
321 <DD>5 &nbsp; violet
322 <DD>6 &nbsp; orange
323 <DD>7 &nbsp; light gray
324 <DD>&nbsp;
325 <DD>8 &nbsp; dark gray
326 <DD>9 &nbsp; bright blue
327 <DD>10 &nbsp; bright green
328 <DD>11 &nbsp; bright cyan
329 <DD>12 &nbsp; bright red
330 <DD>13 &nbsp; bright violet
331 <DD>14 &nbsp; yellow
332 <DD>15 &nbsp; 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&#64;unicorn.us.com">
370 alex&#64;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 &copy; 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