NAME
ccal - display a colored calendar
SYNOPSIS
ccal [ options ] [ [ num_month ] year ]
ccal [ options ] [ [ word_month ] year ]
DESCRIPTION
ccal is an enhanced version of the Unix cal command. It is compatible
to the Unix version in that it uses the same input arguments and its
output may be piped or redirected anywhere.
ccal displays a calendar for a specified year, a specified month and
year, or for the current date. By default, it displays a calendar for
the current system-date month, with the current day hilighted. It
correctly handles the transition from the Julian to Gregorian calendars
in September 1752.
ARGUMENTS
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. The command ‘cal 10’
refers to 10 AD, not October, and not 1910.
The options are explained more fully in the ENHANCEMENTS sections
below. The available options are:
-nod[ata]
Do not try to read any appointment data file.
-d[ata-file]=filename
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.
-f[uture]
If current month is displayed, then show only future
appointments from the appointment file, not appointments that
are past. NOTE: This switch was -d in previous versions.
-t[oday]
If current month is displayed, then show only appointments for
today from the appointment file.
-e[urope]
Use European format (first weekday is Monday).
-a[merican]
Use North American format (first weekday is Sunday), this is the
default.
-m[axappts]
Maximum number of appointments to display. Minimum is 8,
maximum is 50, default is 24.
-p[ause]
Pause before exiting and prompt for a keystroke.
-8[bit]
Allows the use 8 bit extended ASCII (code page 437) characters
in Unix version. It is always allowed in DOS and OS/2 versions
-noc[olor]
Inhibit the use of colors.
-c[olor-file]=filename
Read color definitions from ‘filename’ (default color filename
depends on operating system).
COMMAND EXAMPLES
ccal -f -d=my_dates
display the current month and future appointments defined in
file ‘my_dates’
ccal 1996
display the entire year of 1996
ccal 9 1752
display the month of September 1752
ccal sep 1752
same as above
ccal January
display January of the current year
ccal help
help message displayed for unrecognized arguments
ENHANCEMENTS OVER STANDARD ‘CAL’ COMMAND
If displaying the single-month format, ccal will look for a date file
(the default file or whatever you specify with the -d option). If
found, ccal 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 (number may be changed with -m) 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 (next
month’s dates having definitions like "2nd Thursday" will be skipped).
The special date descriptions specified in the date file are single
lines, formatted as follows:
YYYY MM DD NW xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
where
YYYY is the year,
MM is the month (01 - 12),
DD is the day (00 if the NW field is used),
NW is the weekday-of-month code (00 if the DD field is used)
xxxx is the description; it will be truncated as necessary to fit
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."
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.
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".
NOTE: If ccal is invoked with the -europe switch, then the W values
1-7 denote Monday(1) to Sunday(7) rather than Sunday(1) to Saturday(7).
If invoked with the -american switch, then the W values 1-7 denote
Sunday(1) to Monday(7). If none of those switches are used it will use
the locale definitions (LC_TIME), if available.
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.
If compiled with the USE_REMINDER (this is the default in Debian) flag,
ccal will also search for the files dates and .dates in the same places
as for the caldat 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.
The reminder format consists of text lines of length < screen width in
the following format:
DDDDDDDD:N:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx:yyyyyy:S
where
DDDDDDDD
is the date in one of the following formats:
M/D/Y an event occurring on a specific day (year can be two or four
digits, but must be two for backward compatibility with
reminder)
M/D an event occurring every year
D an event occurring every month
DDD an event occurring every week (day of the week is ’Sun’, ’Mon’,
etc.)
N is the number of days notice of the event to give the user
(ignored by ccal)
xxxxx the event description
yyyyy an optional receptor of the event (e.g. Mr. Jones)
S status flag, either N for normal event or D for a deleted (not
displayed) event
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.
The -f commandline switch causes any date description older than
today’s date to be ignored, thereby giving 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 -f
switch affects only the display for the current month, and not other
months.
There is an optional environment variable that can be used by ccal if
found. If CALOPT is set then ccal 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.
ENHANCEMENTS SPECIFIC TO MS-DOS and OS/2
Under MS-DOS or OS/2, commandline arguments may begin with a ’/’
instead of a ’-’ character. It works either way.
The default name for the date file under MS-DOS and OS/2 is called
cal.dat. It will first look for this file (or whatever you specify
with the -d option) in the current directory and if that fails it will
look in the directory that the cal program is located in.
ccal modifies the display attributes behind its output in order to
display the calendar in attractive colors. Display manipulation is not
done if ccal’s output is redirected to a file. When ccal starts up, it
looks for a file called cal.col (or whatever you specify with the -c
option), first in ccal’s originating directory, and then in the current
directory. The colors have their own defaults if the file is not
found.
ENHANCEMENTS SPECIFIC TO UNIX
Under Unix the default filenames and places that are searched for are
different. For the calendar date file, ccal searches for the file
.caldat in the users home directory. If it is not found ccal will then
look for the file caldat in the current directory and then look for it
in /usr/lib.
For the default color file, it will look first in the user’s home
directory for the file .calcol. It then looks for calcol in the
current directory and then in /etc/.
ENHANCEMENTS SPECIFIC TO DEBIAN
Under Debian, ccal will also use the user’s locale definitions to
determine which day to use as start week day. Currently, only Monday or
Sunday are used.
If you do not set the -europe or -american switch, your locale is
defined properly, and you see a different start week day different from
what you would expect, either ccal or your libc definitions are to
blame. If you think this is a bug, please report it. Remember, ccal
will not accept a default week day which is not Monday or Sunday.
COLOR ATTRIBUTES
Example of a color definition file:
15 02 video colors for month name
01 03 video colors for weekday header
07 01 video colors for normal calendar days
13 01 video colors for sundays
14 02 video colors for current day
07 06 bkgd for yearly calendar (space between months)
11 00 video colors for special day descriptions
12 08 video colors for * indicating descr.=today
FG BG
Color definitions must appear as above, as a two-character field for
the foreground color, followed by a space, followed 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.
Possible colors:
black 0
blue 1
green 2
cyan 3
red 4
violet 5
orange 6
light gray 7
dark gray 8
bright blue 9
bright green 10
bright cyan 11
bright red 12
bright violet 13
yellow 14
white 15
Specifying a background color from 8 to 15 will result in a background
color of 0 to 7, with flashing text.
FILES
cal.dat DOS and OS/2 date file
cal.col DOS and OS/2 color file
~/.caldat Unix local date file
~/.calcol Unix local color file
caldat
/usr/lib/caldat Unix global date files
calcol
/etc/calcol Unix global color files
~/.dates date file used with Unix reminder program and can
be used with cal.
AUTHOR
Alex Matulich - matulich_a@seaa.navsea.navy.mil
...with enhancements and modifications by other
contributors.
(c) 1995 by Unicorn Research Corporation. All rights
reserved. Inspired by an Amiga program by
Gary L. Brant.
SEE ALSO
date(1), reminder(1), rs(1), locale(1)
28 January 2004