.\" @(#)cal.1 3.4.1 11/01/96
.TH CCAL 1 "28 January 2004"
.SH NAME
ccal \- display a colored calendar
.SH SYNOPSIS
.B ccal
[
options
]
[
[
.I num_month
]
.I year
]
.br
ccal
[
options
]
[
[
.I word_month
]
.I year
]
.SH DESCRIPTION
.IX  ccal  ""  "\fLcal\fP \(em display calendar"
.B ccal
is an enhanced version of the Unix
.B 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.
.LP
.B 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.
.SH 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.
.LP
The options are explained more fully in the ENHANCEMENTS sections below.
The available options are:
.LP
.TP
.B \-nod[ata]
Do not try to read any appointment data file.
.TP
.B \-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.
.TP
.B \-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.
.TP
.B \-t[oday]
If current month is displayed, then show only appointments for today from
the appointment file.
.TP
.B \-e[urope]
Use European format (first weekday is Monday).
.TP
.B \-a[merican]
Use North American format (first weekday is Sunday), this is the default.
.TP
.B \-m[axappts]
Maximum number of appointments to display.  Minimum is 8, maximum is 50,
default is 24.
.TP
.B \-p[ause]
Pause before exiting and prompt for a keystroke.
.TP
.B \-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
.TP
.B \-noc[olor]
Inhibit the use of colors.
.TP
.B \-c[olor-file]=filename
Read color definitions from `filename' (default color filename depends on
operating system).
.LP
.SH COMMAND EXAMPLES
.LP
.TP
.B ccal \-f \-d=my_dates
display the current month and future appointments defined in file `my_dates'
.TP
.B ccal 1996
display the entire year of 1996
.TP
.B ccal 9 1752
display the month of September 1752
.TP
.B ccal sep 1752
same as above
.TP
.B ccal January
display January of the current year
.TP
.B ccal help
help message displayed for unrecognized arguments
.SH ENHANCEMENTS OVER STANDARD `CAL' COMMAND
.LP
If displaying the single-month format,
.B ccal
will look for a date file
(the default file or whatever you specify with the -d option).
If found,
.B 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).
.LP
The special date descriptions specified
in the date file are single lines, formatted as follows:
.LP
 YYYY MM DD NW xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

where
.TP
.B YYYY
is the year,
.TP
.B MM
is the month (01 - 12),
.TP
.B DD
is the day (00 if the NW field is used),
.TP
.B NW
is the weekday-of-month code (00 if the DD field is used)
.TP
.B xxxx
is the description; it will be truncated as necessary to fit
.LP
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."
.LP
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.
.LP
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".
.LP
NOTE:  If
.B 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.
.LP
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.
.LP
If compiled with the
.B USE_REMINDER
(this is the default in Debian)
flag,
.B ccal
will also search for the
files
.I dates
and
.I .dates
in the same places as for the
.I caldat
equivalents.  The
.I dates
file is used by the
.BR 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.
.LP
The
.B reminder
format consists of text lines of length < screen width
in the following format:
.LP
  DDDDDDDD:N:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx:yyyyyy:S
.LP
where
.TP
.B DDDDDDDD
is the date in one of the following formats:
.TP
 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)
.TP
 M/D
an event occurring every year
.TP
 D
an event occurring every month
.TP
 DDD
an event occurring every week (day of the week is 'Sun', 'Mon', etc.)
.TP
.B N
is the number of days notice of the event to give the user
(ignored by
.BR ccal )
.TP
.B xxxxx
the event description
.TP
.B yyyyy
an optional receptor of the event (e.g. Mr. Jones)
.TP
.B S
status flag, either N for normal event or D for a deleted (not displayed)
event
.LP
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.
.LP
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.
.LP
There is an optional environment variable that can be used by
.B ccal
if found.  If CALOPT is set then 
.B 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).
.B Cal
will produce its usage screen when run if any invalid options are set
in this variable.
.LP
.SH ENHANCEMENTS SPECIFIC TO MS-DOS and OS/2
.LP
Under MS-DOS or OS/2, commandline arguments may begin with a '/' instead of
a '-' character.  It works either way.
.LP
The default name for the date file under MS-DOS and OS/2 is called
.IR 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.
.LP
.B ccal
modifies the display attributes behind its output in order to display
the calendar in attractive colors.  Display manipulation is not done if
.BR ccal 's
output is redirected to a file.  When
.B ccal
starts up, it looks for a
file called
.I cal.col
(or whatever you specify with the -c option), first
in
.BR ccal 's
originating directory, and then in the current directory.
The colors have their own defaults if the file is not found.
.SH "ENHANCEMENTS SPECIFIC TO UNIX"
.LP
Under Unix the default filenames and places that are searched for are
different.  For the calendar date file,
.B ccal
searches for the file
.I .caldat
in the users home directory.  If it is not found
.B ccal
will then
look for the file
.I caldat
in the current directory and then look for it
in
.BR /usr/lib .
.LP
For the default color file, it will look first in the user's home directory
for the file
.IR .calcol .
It then looks for
.I calcol
in the current directory
and then in
.BR /etc/ .
.SH "ENHANCEMENTS SPECIFIC TO DEBIAN"
.LP
Under Debian, 
.B 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.
.PP
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
.B ccal
or your libc definitions are to blame. If you think this is 
a bug, please report it.  Remember,
.B ccal
will not accept a default week day which is not Monday or Sunday. 
.SH COLOR ATTRIBUTES
.LP
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
.LP
FG BG
.LP
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.
.LP
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
.LP
Specifying a background color from 8 to 15 will result in a background
color of 0 to 7, with flashing text.
.LP
.SH FILES
.PD 0
.TP 20
.B cal.dat
DOS and OS/2 date file
.TP
.B cal.col
DOS and OS/2 color file
.TP
.B ~/.caldat
Unix local date file
.TP
.B ~/.calcol
Unix local color file
.TP
.B caldat
.TP
.B /usr/lib/caldat
Unix global date files
.TP
.B calcol
.TP
.B /etc/calcol
Unix global color files
.TP
.B ~/.dates
date file used with Unix reminder program and can be used with cal.
.PD
.SH 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.
.SH "SEE ALSO"
.BR date (1),
.BR reminder (1),
.BR rs (1),
.BR locale (1)