Provided by: ccal_4.0-3_amd64 bug

NAME

       ccal - displays a calendar

SYNOPSIS

       ccal [ options ] [ [ num_month ] year ]
       ccal [ options ] [ word_month ] [ year ]

DESCRIPTION

       By  default,  ccal  will  display  a  calendar  for the current month with the current day
       marked.  By specifing certain arguments, ccal will display a calendar for a whole year  or
       a specified month and year.

       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.

       If  displaying  a  calendar in the single-month format, ccal will look for a date file. 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 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).

       ccal  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.

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 available options are:

       --3[months]
              Display previous/current/next month together.  This option  will  be  ignored  when
              displaying a full year.

       --a[ppts]
              Maximum number of appointments to display.  Minimum is 8, maximum is 50, default is
              24.

       --col[or-file]=filename
              Read color definitions from `filename' (default color filename depends on operating
              system).

       --con[tinue]=n
              Display the next n successive months starting with the month specified.

       --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.

       --e[urope]
              Use European format (first weekday is Monday).

       --a[merican]
              Use North American format (first weekday is Sunday), this is the default.

       --f[uture]
              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.

       --j[ulian]
              Display Julian dates (days one-based, numbered from January 1).

       --m[onday]
              Display Monday as the first day of the week (same as --europe)

       --noc[olor]
              Inhibit the use of colors.

       --nod[ata]
              Do not try to read any appointment data file.

       --p[ause]
              Pause before exiting and prompt for a keystroke.

       --th[ismonth]
              Disable display of next month appointments; show only current month's.

       --to[day]
              Show only today's appointments.

       --u[se-color]
              Allow the use of colors.

       --y[ear]
              Display a calendar for the current year.

       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).
       Ccal will produce its usage screen when run  if  any  invalid  options  are  set  in  this
       variable.

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

DATE FILES

       ccal 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 ccal --help which will display the location.

       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 or --monday switch,  then  the  W  values  1-7
       denote Monday(1) to Sunday(7) rather than Sunday(1) to Saturday(7).

       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  ccal  was  compiled with the reminder support then 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.

LOCALISATION

       ccal  will  also  use  the  user's locale definitions to determine which day to use as the
       starting weekday. This is overriden if the -europe or the -american command line  switches
       are used.

       If  you  do  not set the -europe or -american switch, your locale is properly defined, and
       you see a different start weekday different from what you would  expect,  either  ccal  or
       your libc definitions are to blame. If you think this is a bug in ccal please report it.

COLOR ATTRIBUTES

       ccal  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 system-wide /etc/cal.col You can
       confirm the location for the system-wide definition by  running  ccal  --help  which  will
       display it.

       Users may override the default colors used when displaying calendars.  This may be done by
       creating a color definition file in their home directory.

       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             Date file
       cal.col             Color definition file
       $HOME/.cal.dat      User's local date file
       $HOME/.cal.col      User's local color file
       /etc/cal.dat        System wide definition for dates
       /etc/cal.dat        System wide definition for colors
       ~/.dates            Date file used with UNIX reminder program and can be used with cal.

AUTHOR

            Alex Matulich  -  alex@unicorn.us.com

            ...with enhancements and modifications by other
            contributors.

            (c) 1993-2001 by Unicorn Research Corporation http://unicorn.us.com.
            Inspired by an Amiga program by Gary L. Brant.

SEE ALSO

       date(1), reminder(1), rs(1)

                                         28 January 2004                                   CAL(1)