


CALENTOOL(1)                                         CALENTOOL(1)


NNAAMMEE
       calentool  -  day/week/month/year-at-a-glance calendar for
       XView/Open Look (the Hacker's Almanac)

SSYYNNOOPPSSIISS
       ccaalleennttooooll [ --bb ] [ --BB ] [ --dd _d_a_t_e ] [ --ff _a_p_p_t_s_f_i_l_e ] [  --hh
       [  _A|_a|_c|_i|_l|_j|_s ]] [ --HH [ _A|_a|_c|_i|_l|_j|_s ]] [ --II { _d|_w|_m|_y
       }] [ --ii ] [ --ll [ _0|_1 ]] [{ --mm | --MM } _u_s_e_r_i_d ] [ --oo ] [{ --pp
       |  --PP }{ _d|_w|_W|_m }] [ --rr ] [ --tt ] [ --uu _i_n_t ] [ --ww ] [ --zz ]
       [ --55 ] [ --66 ] [ [ --77 ] [ --1122 ] [ --2244 ] [ --DD _s_t_y_l_e ] [ --ee ]
       [  --EE ] [ --TT _p_r_i_n_t_d_e_v ] [ --ss _s_t_a_r_t_h_o_u_r ] [ --SS _s_t_o_p_h_o_u_r ] [
       --NN _i_n_t ] [ --xx _i_n_t ] [ _x_v_i_e_w _o_p_t_i_o_n_s ]

DDEESSCCRRIIPPTTIIOONN
       _C_a_l_e_n_t_o_o_l is a day/week/month/year-at-a-glance  tool.   It
       is  a window-based calendar; the only time you should have
       to type is when entering  the  text  for  an  appointment.
       _C_a_l_e_n_t_o_o_l   provides   for  both  one-time  and  recurring
       appointments, as well as notes (appointments or  reminders
       with no associated time).  A period of advance warning can
       be specified.  A visual  warning  (and  optional  auditory
       bell) are produced at the approach of a scheduled appoint-
       ment.

       By employing appropriate options, this tool can be used to
       send  reminders of appointments by _m_a_i_l(1), and to examine
       colleagues  appointment  schedules.   Daily,  weekly   and
       monthly  schedules can be sent to a POSTSCRIPT(R) printer.
       Outdated appointments can  be  sent  automatically  to  an
       archival  file.  An extensive set of files containing com-
       memorative dates is included, as well as a library of rou-
       tines  which  computes the dates of various holidays which
       do not fall  on  fixed  days  of  the  Gregorian  calendar
       (including  religious  holidays  and astronomical events).
       Lunar and solar almanacs are also included.

       Although to take full advantage of _c_a_l_e_n_t_o_o_l you should be
       operating within the X11 or XNeWs environment, the --mm, --MM,
       --pp, --PP, and --TT options allow the Hacker's  Almanac  to  be
       employed  even  from ordinary terminals.  The accompanying
       utilities _c_a_l_2_c_t(1L), _m_o_n_t_h_2_c_t(1L), and _m_t_2_c_t(1L),  trans-
       form appointment files in _c_a_l_e_n_d_a_r(1), _m_o_n_t_h(1L), and _m_o_n_-
       _t_h_t_o_o_l(1L) formats to _c_a_l_e_n_t_o_o_l format.

       Instructions appear in the section DETAILED  INSTRUCTIONS,
       which follows the OPTIONS section.

OOPPTTIIOONNSS
       _C_a_l_e_n_t_o_o_l  accepts  standard _x_v_i_e_w command line options at
       the end of the command line. As well as  the  X11  options
       -fg,  -bg,  and  -geometry.  In addition, most options are
       also settable in the .Xdefaults file.

       --bb             When an  appointment  is  pending,  a  bell



                          19 August 1994                        1





CALENTOOL(1)                                         CALENTOOL(1)


                      character  (along with the appointment mes-
                      sage) is sent  to  the  console;  only  one
                      reminder  is  sent  for  each  appointment.
                      Also, place a copy of the appointment  text
                      in  the  file  _$_H_O_M_E_/_._m_s_g_f_i_l_e.  The text in
                      this file is displayed by the  screen  lock
                      program _x_n_l_o_c_k(1L); notifying passers-by of
                      the user's current activity.

       --BB             Similar to --bb  except  that  the  _c_a_l_e_n_t_o_o_l
                      window  is opened instead of writing to the
                      console.  If  both  features  are  desired,
                      both options may be specified.

       --dd _d_a_t_e        Open  the  calendar  at the day _d_a_t_e, which
                      may take on several formats:

                      day of current week:
                             Tue, Th, fr, MONDAY

                      numeric dates:
                             DD (day DD  of  current  month,  for
                             example  27  for  the  27th  of this
                             month)
                             MO/DD (day DD of month MO, for exam-
                             ple 11/12 for November 12)
                             MO/DD/YY  (day  DD of month MO, year
                             YY, for example 9/1/88 for 1 Septem-
                             ber 1988).  (If the --ee or --EE options
                             are used, the date format  is  DD/MO
                             and  DD/MO/YY.  If the -D2 option is
                             used, the date format is  MO-DD  and
                             YY-MM-DD.)

                      relative dates:
                             +n  (n days from now, for example +1
                             for tomorrow)
                             -n (n days ago, for example  -1  for
                             yesterday)

       --DD _s_t_y_l_e       Set the date formatting style.  The default
                      (-D 0) specifys typical  U.S.  usage,  with
                      dates  formatted  as  MM/DD/YY.  Style 1 is
                      the typical (?) European usage, with  dates
                      formatted  as DD/MM/YY.  Style 2 is the ISO
                      standard (?) format, also used  in  Sweden,
                      with  dates  formatted  as  YY-MM-DD.  This
                      option overrides the -E option.

       --ee             Set  European  (ISO)  week  display  format
                      (Monday  through  Sunday).  When 7 day week
                      display is set, the display shows the  days
                      Monday  through  Sunday, rather than Sunday
                      through Saturday.  This  also  affects  the



                          19 August 1994                        2





CALENTOOL(1)                                         CALENTOOL(1)


                      month  and year displays.  With this option
                      the weeks are  numbered  according  to  ISO
                      standard.

       --EE             Set all European style options.  Currently,
                      this includes: --2244, --DD 22 and --ee.

       --ff _a_p_p_t_s_f_i_l_e   Use _a_p_p_t_s_f_i_l_e  as  the  appointments  file.
                      This  is  useful for seeing if other people
                      on the net are free to  attend  a  meeting.
                      If  everyone  exports his appointments file
                      (in a NFS environment) then people can plan
                      appointments more effectively.

                      File integrity can NOT be assured when this
                      option is in use;  if  two  people  try  to
                      write  to the same appointments file at the
                      same time,  the  result  could  be  tragic.
                      Only the person whose schedule is described
                      by a particular  appointments  file  should
                      have write permission for that file.

       --hh _c_h_a_r        Compute  and  display holidays which do not
                      fall on set dates of the  Gregorian  calen-
                      dar.  Notes appear in the day and week dis-
                      plays, and marks appear in  the  month  and
                      year  displays.  This option is followed by
                      a single character  which  indicates  which
                      set  of  holidays  is  to  be computed (the
                      option can be invoked multiple times on the
                      command  line).   The  character  codes for
                      supported date sets are:

                      AA      Use all available date  sets.   When
                             this  option  is  chosen,  the  time
                             required to produce  a  new  display
                             increases.   It becomes long for the
                             month display and extremely long for
                             the year display.

                      aa      Astronomical  events  (solstices and
                             equinoxes).

                      cc      Christian religious holidays.  These
                             dates  may  be  inaccurate for years
                             prior to the advent of the Gregorian
                             calendar in 1582.

                      ii      Islamic  religious  holidays.  There
                             are different  conventions  used  by
                             Muslim  countries  to  determine the
                             dates in the Islamic  calendar;  the
                             dates  computed  here  may differ by
                             1-2 days from the locally determined



                          19 August 1994                        3





CALENTOOL(1)                                         CALENTOOL(1)


                             date.

                      ll      Lunar   calendar  (Chinese/Oriental)
                             holidays (not yet implemented).

                      jj      Jewish  religious  holidays.   These
                             may  not be accurate for years after
                             2000.  Also note that  until  recent
                             centuries,  the  Jewish calendar was
                             regulated (like the  modern  Islamic
                             calendar)  by sightings of the cres-
                             cent Moon, so that dates for  previ-
                             ous  years  must be interpreted with
                             caution.

                      ss      US Secular holidays.

       --HH _c_h_a_r        Identical to the  --hh  option,  except  that
                      computed  dates  are  displayed only in the
                      day and week displays; the month  and  year
                      displays are not marked for these dates.

       --II _c_h_a_r        Set  the intial display state when the tool
                      is first started.  The _d_, _w_, _m_, _y modifiers
                      start  the tool displaying the current day,
                      week, month or year, respectively.

       --ii             Include  all  outdated  appointments  files
                      (files  named  _._a_p_p_o_i_n_t_m_e_n_t_s_._y_y,  where  _y_y
                      represents  the  last  two  digits  of  the
                      appointment's year).

       --ll _i_n_t         Set  limit  check for appointments.  If _i_n_t
                      is 0 or missing, then only the  appointment
                      time  slots  are  checked  when determining
                      whether to show a "no appointments" icon or
                      a  standard icon.  When _i_n_t is 1, the notes
                      are also included in the check.

       --mm _u_s_e_r_i_d
       --MM _u_s_e_r_i_d      Send mail listing  todays  appointments  to
                      the  user specified by _u_s_e_r_i_d and exit.  --mm
                      shows all notes, while  --MM  does  not  show
                      notes   not   marked  for  display  in  the
                      month/year displays.  This feature is  use-
                      ful  when calentool is run from _c_r_o_n(1), to
                      send yourself mail about  today's  appoint-
                      ments.   No  mail  is  sent  about  today's
                      appointments, if there are  none.   The  --pp
                      and  --PP  options  may  be  used  with these
                      options to  mail  yourself  a  whole  weeks
                      worth  of appointments, e.g.: _c_a_l_e_n_t_o_o_l _-_P_w
                      _-_m _b_i_l_l_r_.  By default, the output generated
                      by the -[mM] command is in ASCII.  By using



                          19 August 1994                        4





CALENTOOL(1)                                         CALENTOOL(1)


                      the --TT option, a  different  output  format
                      (e.g.  POSTSCRIPT(R)) may be chosen.  Month
                      output is in POSTSCRIPT(R) only.

       --NN _i_n_t         Set the number of  noteslots  displayed  to
                      _i_n_t  slots.  This is useful if you increase
                      the number of timeslots used  and  want  to
                      keep the overall display size down.

       --oo             Save  outdated  appointments to an outdated
                      appointments  file  (e.g.,  a  file   named
                      _._a_p_p_o_i_n_t_m_e_n_t_s_._y_y,  where  _y_y represents the
                      last two digits of the appointments  year).
                      An  appointment  is  considered outdated at
                      the beginning of the next year or,  if  the
                      --xx_n  option  is specified, _n days after the
                      appointment.

       --pp _c_h_a_r
       --PP _c_h_a_r        Print today's appointments and exit.   This
                      is  useful  for reviewing appointments from
                      an ordinary terminal or _s_h_e_l_l_t_o_o_l(1).   The
                      _d_,  _w_,  _W_, _m modifiers select a printout of
                      the  current  day,  week,  week  or  month,
                      respectively.   The _w option prints a weeks
                      worth starting at the beginning of the cur-
                      rent week.  _W prints a weeks worth starting
                      at the current day.  --pp  shows  all  notes,
                      while --PP does not show notes not marked for
                      display in  the  month/year  displays.   No
                      printout  is  provided of the current day's
                      appointments,  if  there  are   none.    By
                      default,  the output generated by the -[pP]
                      command  is  in  ASCII,  except  for  month
                      printouts     where    the    default    is
                      POSTSCRIPT(R).  By using the --TT  option,  a
                      different      output      format     (e.g.
                      POSTSCRIPT(R)) may be chosen.  Month output
                      is in POSTSCRIPT(R) only.

       --rr             Open  the  calendar tool in read-only mode.
                      Appointments can be edited, but no  changes
                      will  be  saved.   The  tool's banner strip
                      will  contain  the  string  "[Read  Only]".
                      This  is particularly useful for inspecting
                      other users' appointment files with the  --ff
                      option.

       --ss _s_t_a_r_t_h_o_u_r   Set  the  start  hour  for the day and week
                      displays to _s_t_a_r_t_h_o_u_r hour (0 to 23).

       --SS _s_t_o_p_h_o_u_r    Set the stop (end) hour  for  the  day  and
                      week  displays  to _s_t_o_p_h_o_u_r hour (1 to 24).
                      The end hour must be greater than the start



                          19 August 1994                        5





CALENTOOL(1)                                         CALENTOOL(1)


                      hour.  If the start stop span is large, you
                      should change the default font to a smaller
                      size  font.   This can be done with the --WWtt
                      SunView window  option  or  by  setting  it
                      explicity in the defaults file (see below).

       --tt             Display the current time below  the  _c_a_l_e_n_-
                      _t_o_o_l  icon  (no  further  need  for  _c_l_o_c_k_-
                      _t_o_o_l(1)).

       --TT _d_e_v_i_c_e      Use _d_e_v_i_c_e as the output format for  print-
                      ing  or  mailing appointments.  The default
                      is ASCII.   The  only  currently  supported
                      option for _d_e_v_i_c_e is ppss or ppsscc which speci-
                      fies POSTSCRIPT(R) output instead.

       --uu _i_n_t         Update the time at the interval of _i_n_t sec-
                      onds.

       --ww             Display  the "Working!" message in the con-
                      trol panel during lengthy operations.   The
                      cursor also changes to an hourglass.

       --xx _i_n_t         Expire (delete) appointment file entries if
                      they are older than _i_n_t days old.  If --oo is
                      set,  entries  are  moved from the appoint-
                      ments file  to  the  outdated  appointments
                      file.   Appointments  in #include files and
                      read only appointments are not expired.  To
                      expire   included  appointments,  _c_a_l_e_n_t_o_o_l
                      must be run on the included file  directly.

       --zz             Convert  appointments  file used by earlier
                      (pre 2.0) versions of _c_a_l_e_n_t_o_o_l to the for-
                      mat  used  by  the  current  version.  This
                      option should be  invoked  only  once,  the
                      first  time  an  old format file is read by
                      _c_a_l_e_n_t_o_o_l.

       --55             Display only five days (Monday through Fri-
                      day)  in  the week display.  This is useful
                      if the installer has set the  default  dis-
                      play format to 6 or 7 days.

       --66             Display  six days (Monday through Saturday)
                      in the week display.  This is useful if the
                      installer  has set the default display for-
                      mat to 5 or 7 days.

       --77             Display all seven days in the week display.
                      This is useful if the installer has set the
                      default value  to  5  or  6  days.   Sunday
                      through  Saturday  is  the standard format.
                      Using the  --ee  or  --EE  options  displays  a



                          19 August 1994                        6





CALENTOOL(1)                                         CALENTOOL(1)


                      Monday  through  Sunday  format.  The 7-day
                      display is wider than  the  5-day  display,
                      allowing longer messages to be displayed on
                      the day page.

       --1122            Display time  in  a  12-hour  AM/PM  format
                      whenever  practical.  This is useful if the
                      installer has set the default  time  format
                      to 24-hour time.

       --2244            Display  time in a 24-hour format.  This is
                      useful if the installer has set the default
                      time format to 12-hour time.


DDEETTAAIILLEEDD IINNSSTTRRUUCCTTIIOONNSS
       Help  is available for most buttons, message items, panels
       and the main window by moving the cursor over the  desired
       item  and  pushing  the HHeellpp button (or its mapped equiva-
       lent).

   EExxaammiinniinngg tthhee ccaalleennddaarr
       When first opened, the tool displays the appointments  for
       a  single  day  (today  if  the  --dd  option  has  not been
       employed).  The day page for  today  is  patterned.   Each
       appointment  or  reminder  is  shown  at its start time in
       reverse video.  If the appointment lasts  longer  than  30
       minutes  an  arrow  is drawn from the starting timeslot to
       the end of the appointment.  If advance warning of  future
       appointments  has been requested, a popup display appears.
       The day display containing a  future  appointment  may  be
       displayed  if  the future appointment is selected with the
       _m_o_u_s_e_-_L_B (SELECT).  The reminder popup may be removed per-
       manently  (during this _c_a_l_e_n_t_o_o_l session) by selecting the
       DDiissmmiissss option;  if  the  KKeeeepp  option  is  selected,  the
       reminder  window  will  reappear each time the current day
       page is displayed.

       If there are multiple appointments sharing a time slot,  a
       MMoorree  button  appears to the right of the time slot.  This
       may be toggled repeatedly  to  view  each  appointment  in
       turn.   Any  arrows  for  hidden appointments are drawn as
       _d_a_s_h_e_d lines to show all scheduled time at a  glance.   As
       the  MMoorree  button is toggled, the arrows change state such
       that the new active appointment has arrows drawn as  solid
       lines  and  the previous appointment's arrows (if any) are
       now dashed.  If appointment text is too wide for  the  day
       page,  scroll  buttons appear to the right of the text and
       may be used to view the text in its entirety.  When  first
       displayed, all text is left justified.

   TThhee ccoonnttrrooll ppaanneell
       The control subwindow contains various control buttons and
       todays date and time.  View the current  week,  month,  or



                          19 August 1994                        7





CALENTOOL(1)                                         CALENTOOL(1)


       year  by  employing  the  _m_o_u_s_e_-_L_B  (SELECT) to select the
       WWeeeekk, MMoonntthh, or YYeeaarr panel buttons.  Pushing the  _m_o_u_s_e_-_R_B
       (MENU)  in  the  DDaayy,  WWeeeekk,  MMoonntthh, or YYeeaarr panel buttons
       activates  pull-down  menus  with  appropriate  selections
       (certain  of  the selections may be inactivated due to the
       current display mode).  The TTooddaayy panel button  redisplays
       today's  day page.  In each of the four display modes, the
       PPrreevviioouuss and NNeexxtt panel buttons move backward  or  forward
       one  day, week, month or year, as appropriate (maintaining
       the current display mode).  There are also pull-down menus
       associated  with  these buttons, produced by selecting the
       _m_o_u_s_e_-_R_B (MENU) (again, certain options may be inactivated
       according  to the current display mode).  The CCuurrrreenntt but-
       ton displays the current day, week, month or year, depend-
       ing upon the current display mode.  A pull-down menu asso-
       ciated with the CCuurrrreenntt button  allows  selection  of  the
       current  day,  week,  month,  or  year displays, or direct
       entry of a specific date for which a day  page  is  to  be
       displayed.   The  DDoonnee button closes the frame to an icon.
       A pull-down menu associated with the  DDoonnee  button  allows
       selection of either closing the frame or exiting the tool.

   WWeeeekk,, mmoonntthh aanndd yyeeaarr ddiissppllaayyss
       In the week display, the initial part of each  appointment
       message  is  visible.   If  there are overlapping appoint-
       ments/notes, a MMoorree button appears at the  bottom  of  the
       day  column,  which prints a message reminding the user to
       select the day display to be  able  to  view  all  of  the
       appointments/notes.   The day strip for today, if present,
       is patterned.  Move the cursor over any day  of  the  week
       and select the _m_o_u_s_e_-_L_B (SELECT) to view the indicated day
       display.

       In the month display, a triangular hatch-mark in the upper
       right-hand  corner of a day indicates an appointment.  The
       day box for today, if present,  is  patterned.   Move  the
       cursor  over  any day of the month and select the _m_o_u_s_e_-_L_B
       (SELECT) to view the indicated day display.  Position  the
       cursor over the arrow to the left of a week and select the
       _m_o_u_s_e_-_L_B (SELECT) to view the indicated week.

       In the year display, a  reverse-video  date  indicates  an
       appointment.   Today's  date,  if  present,  is patterned.
       Move the cursor over a particular  month  and  select  the
       _m_o_u_s_e_-_L_B (SELECT) to select the indicated month display.

       The  pulldown  menu actuated within the top control bar of
       the window by selecting the  _m_o_u_s_e_-_R_B  (MENU)  allows  the
       tool to be closed, moved, terminated, etc.

   LLuunnaarr aanndd SSoollaarr ddaattaa
       Selection  of  the  Sun  or  Moon icons in the day display
       reveals information about rising and setting times,  lunar
       phases,  local  time,  sidereal time, etc.  An abbreviated



                          19 August 1994                        8





CALENTOOL(1)                                         CALENTOOL(1)


       solar data display is shown if  the  day  currently  being
       displayed is not today.

   IIccoonniicc wwaarrnniinngg ooff aann aappppooiinnttmmeenntt
       When  _c_a_l_e_n_t_o_o_l is in iconic form, the icon is inverted to
       a  reverse  video  representation  prior  to  a  scheduled
       appointment  and  remains inverted for the duration of the
       appointment.  The amount of advance warning given  is  set
       by  the  aappppooiinnttmmeenntt pprrooppeerrttiieess menu, with a default of 10
       minutes.

       When there are no appointments or notes remaining for  the
       current  day, an alternate icon with an empty page is dis-
       played instead of the standard  or  reverse  video  icons.
       For  all  icons,  today's  month and day of month are dis-
       played at the bottom of the icon's calendar page.

   EEnntteerriinngg aappppooiinnttmmeennttss
       Appointments can only be entered in the day display.   The
       day  display presents a number of labeled time slots (gen-
       erally 30 minute intervals) as well as a _n_o_t_e_s section  at
       the end of the day page, to enter reminders not associated
       with a specific time.  To enter an  appointment,  position
       the  cursor  over  the  required  time  slot and press the
       _m_o_u_s_e_-_L_B (SELECT).  The slot is toggled to reverse  video.
       Leaving  the  cursor  positioned  in the slot, type in the
       appropriate descriptive text.  If  the  text  exceeds  the
       size  of  the  window,  scroll  buttons will appear to the
       right.  Typing new text into the time  slot  automatically
       right-justifies  the text already present, so that the new
       text  is  appended.   To  indicate  the  duration  of  any
       appointment,  click  the  _m_o_u_s_e_-_M_B (ADJUST) in the initial
       time slot (any existing duration arrow will be deleted); a
       vertical  indicator  arrow appears and follows the cursor.
       Drag the cursor to the location of the final time slot and
       release  the  button.   The  SunView/XView  L6 and L8 keys
       (COPY/PASTE or PUT/GET) may also be used to paste the text
       from  the  shelf  to an active appointment slot or from an
       appointment slot to the shelf.  When inserting a string in
       calentool using PASTE, the slot must be active first (i.e.
       the _m_o_u_s_e_-_L_B (SELECT) must have been pressed first).

   CChhaannggiinngg aann aappppooiinnttmmeenntt
       Selecting the _m_o_u_s_e_-_R_B (MENU) in the highlighted time slot
       produces  a  popup  menu with the options pprrooppeerrttiieess, ccuutt,
       ppaassttee, ccooppyy, ddeelleettee, and uunnddeelleettee.  To delete the  current
       appointment,  storing it in a temporary buffer, select the
       ccuutt option.  To copy the text of an appointment  into  the
       buffer without deleting it, select ccooppyy, To place the text
       of a buffer-stored appointment into a time slot, click the
       _m_o_u_s_e_-_R_B  (MENU) in the new time slot, and then select the
       ppaassttee option.

       To delete  the  current  appointment,  select  the  ddeelleettee



                          19 August 1994                        9





CALENTOOL(1)                                         CALENTOOL(1)


       option.   If  the  appointment in question is recurring, a
       special subwindow appears which allows the user to  delete
       (or move) every occurrence or just today's occurrence.  If
       the latter is selected, the uunnddeelleettee option is  activated,
       which allows today's occurrence to be reinstated.

   AAppppooiinnttmmeenntt pprrooppeerrttiieess
       An  appointment  may  be further modified by selecting the
       pprrooppeerrttiieess option or pushing the Props key.  This causes a
       properties  subwindow  to  appear,  in  which the user may
       specify that the appointment is to be repeated every  day,
       for selected weeks of the month (first through fifth, last
       or every Monday thru Friday), every  month,  and/or  every
       year.  Alternatively, the appointment may be repeated at a
       specified interval of days.  The user can also  specify  a
       period  of  days  prior  to  the  appointment for which an
       advance warning will  be  printed;  how  many  times  this
       appointment  will  be repeated; and how many minutes ahead
       of the scheduled time the user should be reminded about an
       appointment  (default  is  10  minutes).  For example, one
       could specify that a meeting is to occur on the first  and
       third  Tuesday  of  the month, in perpetuity, by selecting
       the repeat options SSeelleecctteedd WWeeeekk, EEvveerryy MMoonntthh,  and  EEvveerryy
       YYeeaarr, as well as the selected week indicators 11sstt and 33rrdd.
       After selecting the  appointment  options,  the  user  can
       select  either AAppppllyy or RReesseett to close the options subwin-
       dow.

   EEnntteerriinngg nnootteess
       Entering notes is similar to entering appointments, except
       that  no  duration  arrows can be appended, and the modify
       panel allows the user to indicate whether or not the  note
       is  to  be used to mark the month and year displays, or to
       be printed (or mailed) when  the  --PP  (or  --MM)  option  is
       invoked.

   PPrriinnttiinngg aappppooiinnttmmeennttss
       The  PPrriinntt button prints a copy of the day, week, month or
       year display.  Pressing the _m_o_u_s_e_-_R_B (MENU) over this but-
       ton  produces  a  popup  menu which allows either a raster
       image or a POSTSCRIPT(R) version of the current display to
       be  printed.   A  third  option allows modification of the
       default print command.  The default print command is taken
       from  the  first  provided by the following sources: the X
       Resource data base, the _P_R_I_N_T_E_R environment variable,  and
       the  _P_R_I_N_T___C_M_D value provided by the system manager at the
       time of installation.  The printer output can also be sent
       to a file instead of directly to the printer.

   SSaavviinngg oouuttddaatteedd aappppooiinnttmmeennttss
       Appointments  are  recorded in a file named _._a_p_p_o_i_n_t_m_e_n_t_s.
       If the --oo option is in effect, at the end of  a  year  all
       appointments  for  the past year are copied into a special
       file with a name _<_a_p_p_t_s___f_i_l_e_>_._y_y (where  _y_y  contains  the



                          19 August 1994                       10





CALENTOOL(1)                                         CALENTOOL(1)


       final  two  digits  of the past year).  These appointments
       are then deleted from the current appointments  file.   If
       the  --xx and --oo options are in effect, expired appointments
       are also copied to the outdated file,  rather  than  being
       purged.

   EExxaammiinniinngg ootthheerr aappppooiinnttmmeenntt ffiilleess
       The  FFiillee  button  displays a window in which an alternate
       _._a_p_p_o_i_n_t_m_e_n_t_s file can be specified.  This is  useful  for
       maintaining  multiple  appointment  books or for examining
       colleagues' calendars.  The file can be made read-only  or
       read-write according to the toggle option, and a file name
       can be typed into the window.  The AAppppllyy button  initiates
       reading  of the currently displayed file, while the OOrriiggii--
       nnaall button restores the original file name that  calentool
       was  invoke  with.   The  RReesseett button undoes any filename
       changes that have been made prior to selecting AAppppllyy.  The
       SSaavvee button updates the current appointments file with any
       changes made that have not yet been logged.

FFIILLEE FFOORRMMAATT
       Using an included file (see below)  is  the  one  instance
       where  manual  editing  of the _._a_p_p_o_i_n_t_m_e_n_t_s file is still
       required (although one could use the window-based aids  of
       _c_a_l_e_n_t_o_o_l to build such a file, by means of the --ff option,
       the include command must still be edited into the  primary
       appointment  file).   The  appointments file contains four
       types of lines:
            ## CCaalleennTTooooll VV22..22 -- DDOO NNOOTT RREEMMOOVVEE TTHHIISS LLIINNEE
            ##iinncclluuddee ""ffiillee""
            ## <<ccoommmmeenntt ssttrriinngg>>
            YYYY MMOO DDDD HHHH MMII AAAA [[IIII]] <<WWWW>> ++RRRR %%AAAA ## _m_e_s_s_a_g_e

   HHeeaaddeerr lliinnee
       The first line in an _a_p_p_o_i_n_t_m_e_n_t_s file identifies the ver-
       sion  of  _c_a_l_e_n_t_o_o_l  in  use.   This  line should never be
       removed.

   IInncclluuddeedd aappppooiinnttmmeenntt ffiilleess
       A nnoonn--eeddiittaabbllee appointments file (for  example,  one  con-
       taining  site  specific  holidays) can be included.  Three
       formats are possbile for specifying such a file:
            #include "/pathname/file"
       or
            #include "file"
       or
            #include <file>
       In the second case, the file will be  prepended  with  the
       pathname  used  for  the  appointments  file.  In the last
       case, the included file is assumed to reside in a  system-
       wide  library directory specified at the time of installa-
       tion (see your system administrator).  The # mmuusstt start in
       column  1  of the appointments file.  The first line of an
       included file must also  have  a  header  line.   Included



                          19 August 1994                       11





CALENTOOL(1)                                         CALENTOOL(1)


       files may not include other files.

   CCoommmmeenntt lliinnee
       A  _#  in column one (not followed by the string "include")
       indicates a comment; the rest of the line is ignored.

   AAppppooiinnttmmeenntt//NNoottee eennttrriieess
       All fields are separated by at least one space  character.

   MMaannddaattoorryy eennttrriieess
       The  _Y_Y  field  is  the  year (00-99), the _M_O field is the
       month (1-12) and _D_D is the day (1-31).  The _D_D  field  can
       also  contain a two-character alphabetic string describing
       a day of the week: Su, Mo, Tu, We, Th, Fr, Sa or MF  (Mon-
       day  thru  Friday).   This  feature is used in conjunction
       with wildcards (see below), and the _[_I_I_] field, which must
       appear  within  square brackets, and which can contain the
       digits 1-5 and the letter L, separated by commas, to indi-
       cate  the first through fifth (or last) monthly occurrence
       of the specified day of the  week.   _H_H  and  _M_I  are  the
       starting  hour  (00-23)  and  minutes  (00 or 30).  The _A_A
       field is the number of arrow bars  (additional  30  minute
       time slots) required.

   NNootteess
       A _H_H value of 99 indicates a note, rather than an appoint-
       ment, with _M_I designating whether presence of the note  is
       to  be  shown  (marked)  in  the month and year panels (00
       indicates that it is to be marked, 99  indicates  that  it
       should not be marked).

   WWiillddccaarrddss ffoorr rreeccuurrrriinngg aappppooiinnttmmeennttss//nnootteess
       A  double  asterisk (**) can be used in place of the year,
       month and/or day fields to indicate every year,  month  or
       day.

   OOppttiioonnaall eennttrriieess
       The _[_I_I_] field appears within square brackets, and (if the
       DD field contains a numerical value) is  taken  to  be  an
       interval in days between recurring appointments.  The _<_W_W_>
       field appears within broken brackets,  and  indicates  the
       number of days of advance warning required.  The _+_R_R field
       is preceded by a plus sign, and indicates  the  repetition
       count  for a given appointment.  The _%_A_A field is preceded
       by a percent sign, and indicates the number of minutes  in
       advance of an appointment the user should be reminded.  If
       this field does not exist, the default value of 10 minutes
       is used.

   AAppppooiinnttmmeenntt tteexxtt
       If  a  #  character appears in front of the text, it indi-
       cates that a recurring appointment has been suppressed for
       that  day.  A leading '\' character is prepended to a text
       entry that starts with special characters to  prevent  the



                          19 August 1994                       12





CALENTOOL(1)                                         CALENTOOL(1)


       text from being misinterpreted as appointment options.

   EExxaammppllee eennttrriieess
       A meeting that occurs weekly at 0900 and lasts for 1 hour,
       starting on April 1st, would be represented as:
            8888 0044 0011 0099 0000 0011 [[77]]        WWeeeekkllyy ssttaattuuss mmeeeettiinngg
       Several other examples:
            **** 0044 0011 9999 9999 0000            AApprriill FFooooll''ss DDaayy
            **** **** TTuu 1100 3300 0000 [[11,,33]]      MMeeeettiinngg oonn 11sstt aanndd 33rrdd TTuueess.. ooff MMoonntthh
            **** **** 0011 9999 0000 0000 <<11>>        FFiirrsstt ddaayy ooff eevveerryy mmoonntthh,, oonnee ddaayy wwaarrnniinngg
            8888 0055 **** 9999 9999 0000            OOnn vvaaccaattiioonn ffoorr eennttiirree mmoonntthh ooff MMaayy 11998888
            8899 1111 0066 9999 0000 0000 ++44         SSiiggFFiisshhiinngg CCoonnffeerreennccee
            **** **** MMFF 1177 0000 0000            DDaaiillyy bbaacckkuuppss

SSUUPPPPLLIIEEDD SSPPEECCIIAALL DDAATTEESS FFIILLEESS
       _C_a_l_e_n_t_o_o_l is supplied with a number of system-wide special
       dates  files  which  may be included in a user's _._a_p_p_o_i_n_t_-
       _m_e_n_t_s file:

              ancient        Events celebrated in ancient times

              can_holiday    Major  Canadian  holidays  (holidays
                             from work)

              celtic         Holidays/events of interest to Celts

              computing      Events in the history of computing

              events         Historical events (major and minor)

              gdead          Dates  concerning  the  rock   group
                             Grateful Dead

              hawaii         Historical   events   pertaining  to
                             Hawaii

              literature     Historical events pertaining to lit-
                             erature, newspapers and comics

              lives          Biographical  dates of note (births,
                             deaths, weddings)

              lotr           Special dates for fans of  Tolkien's
                             _L_o_r_d _o_f _t_h_e _R_i_n_g_s

              movies         Historical   events   pertaining  to
                             motion pictures

              music          Historical events pertaining to  the
                             music world (both popular and tradi-
                             tional)

              radio          Historical  events   pertaining   to
                             radio



                          19 August 1994                       13





CALENTOOL(1)                                         CALENTOOL(1)


              sfo            Historical  events pertaining to San
                             Francisco, CA  and  the  surrounding
                             area

              space          Dates  of note in the history of the
                             exploration of outer space

              sports         Dates concerning sports.

              television     Dates concerning television programs
                             and history of tv.

              usa_holiday    Major  US  holidays  (holidays  from
                             work)

              usa_other      Minor US/Canadian holidays

              usa_states     US  holidays  specific  to  selected
                             states

              witchcraft     Dates  of  interest  to  witches and
                             warlocks

              world          Holidays from countries  other  than
                             the US/Canada

EENNVVIIRROONNMMEENNTT  VVAARRIIAABBLLEESS,,  IINNIITTIIAALLIIZZAATTIIOONN  FFIILLEESS,,  AANNDD  CCOOMMPPIILLAATTIIOONN
       OOPPTTIIOONNSS
       By default, the _._a_p_p_o_i_n_t_m_e_n_t_s file employed  by  _c_a_l_e_n_t_o_o_l
       resides  in the users' home directory.  Alternatively, the
       environment variable CALENTOOL_DIR can be set to the  full
       pathname  of  a  directory  where  the  _._a_p_p_o_i_n_t_m_e_n_t_s file
       resides.  _C_a_l_e_n_t_o_o_l must  have  write  permission  in  the
       directory to be used.

       Compile  time  options allow modification of the start and
       ending year for  the  year  pull-down  menu,  and  various
       parameters defining the display.

FFIILLEESS
       $HOME/.appointments           default appointments file

       $HOME/.Xdefaults              defaults initialization file

       /tmp/appts*                   default  temporary  appoint-
                                     ments file, while active

       $HOME/.msgfile                message   file   (containing
                                     current   appointment)   for
                                     _x_n_l_o_c_k(1L) program

       /usr/openwin/lib/calentool    default directory containing
                                     special date inclusion files




                          19 August 1994                       14





CALENTOOL(1)                                         CALENTOOL(1)


       /usr/tmp/calentool.ps         default   file   used   when
                                     POSTSCRIPT(R)  printer  File
                                     Only output is selected

       /usr/tmp/calentool.ras        file    used   when   raster
                                     printer File Only output  is
                                     selected

       Ct.Xdefaults                  example resource entries

SSEEEE AALLSSOO
       cal(1),  cal2ct(1L),  calencheck(1L),  calendar(1), clock-
       tool(1),  cron(8),  mail(1),   month(1L),   monthtool(1L),
       month2ct(1L), mt2ct(1L), xnlock(1L), xview(1)

RREEFFEERREENNCCEESS
       An  excellent compendium which describes basic terminology
       of time measurement, methods of astronomical  computation,
       and the convoluted history of calendars:

              The  Nautical Almanac Offices of the United Kingdom
              and the United States of America, _E_x_p_l_a_n_a_t_o_r_y  _S_u_p_-
              _p_l_e_m_e_n_t _t_o _t_h_e _A_s_t_r_o_n_o_m_i_c_a_l _E_p_h_e_m_e_r_i_s _a_n_d _t_h_e _A_m_e_r_-
              _i_c_a_n _E_p_h_e_m_e_r_i_s _a_n_d _N_a_u_t_i_c_a_l _A_l_m_a_n_a_c, Her  Majesty's
              Stationery  Office,  London,  1961  (reprinted with
              amendments, 1977).

       The best single source for practical computations of solar
       and lunar data:

              Jean  Meeus, _A_s_t_r_o_n_o_m_i_c_a_l _F_o_r_m_u_l_a_e _f_o_r _C_a_l_c_u_l_a_t_o_r_s,
              _M_o_n_o_g_r_a_f_i_e_e_n  _o_v_e_r   _A_s_t_r_o_n_o_m_i_e   _e_n   _A_s_t_r_o_f_y_s_i_c_a,
              Volkssterrenwacht Urania V.Z.W., Mattheessensstraat
              62, B 2540 Hove,  Belgium,  Vereniging  voor  Ster-
              renkunde  V.Z.W.,  Ringlaan 3, B 1180 Brussel, Bel-
              gium, Vol. 4, Derde Druk, October 1980.

       Other helpful references for astronomical computations:

              Eric Burgess,  _C_e_l_e_s_t_i_a_l  _B_A_S_I_C,  Revised  Edition,
              Sybex,  1985  (cookbook  oriented,  many algorithms
              hard to dig out of turgid BASIC).

              Pierre Bretagnon and  Jean-Louis  Simon,  _P_l_a_n_e_t_a_r_y
              _P_r_o_g_r_a_m_s  _a_n_d _T_a_b_l_e_s _f_r_o_m _-_4_0_0_0 _t_o _+_2_8_0_0, Willmann-
              Bell, 1986 (for utmost accuracy in planetary compu-
              tations).

       A  non-scholarly  work  with easily implemented algorithms
       for computation of Christian and Jewish holidays  and  (an
       approximation to) the Islamic New Year:

              Wolfgang  Alexander Schocken, _T_h_e _c_a_l_c_u_l_a_t_e_d _c_o_n_f_u_-
              _s_i_o_n _o_f _c_a_l_e_n_d_a_r_s_; _p_u_z_z_l_e_s _i_n _C_h_r_i_s_t_i_a_n_, _J_e_w_i_s_h _a_n_d



                          19 August 1994                       15





CALENTOOL(1)                                         CALENTOOL(1)


              _M_o_s_l_e_m _c_a_l_e_n_d_a_r_s, 1st Ed., Vantage Press, New York,
              1976.

       Useful tables and additional information about the Islamic
       calendar:

              G.  S.  P. Freeman-Grenville, _T_h_e _M_u_s_l_i_m _a_n_d _C_h_r_i_s_-
              _t_i_a_n _C_a_l_e_n_d_a_r_s, Oxford  University  Press,  London,
              1963.

              F.  R.  Unat,  _H_i_c_r_i  _T_a_r_i_h_l_e_r_i,  Turktarih  Kurumu
              Basimevi, Ankara, 1959 (Turkish).

              U. V. Tsybulsky, _C_a_l_e_n_d_a_r _o_f _M_i_d_d_l_e  _E_a_s_t_e_r_n  _C_o_u_n_-
              _t_r_i_e_s,   Nauka   Publishing   House,  Moscow,  1979
              (English).

       Information  (regrettably,  not  at  all  current)   about
       Japanese holidays:

              W. H. Erskine, _J_a_p_a_n_e_s_e _F_e_s_t_i_v_a_l _a_n_d _C_a_l_e_n_d_a_r _L_o_r_e,
              Kyo Bun Kwan, Tokyo, 1933.

CCAALLLLIINNGG AALLLL HHAACCKKEERRSS
       Please help extend the special dates files and date compu-
       tation  library  (only  carefully verified dates and algo-
       rithms, please!).  In particular, it would be splendid  if
       someone  would  expand  the range of astronomical computa-
       tions, which currently include only the equinoxes and sol-
       stices;  one  could  add  dates/times  of the major meteor
       showers, planetary risings and settings, etc.   Perhaps  a
       sailing  buff  could  build  in high/low tide estimations.
       The lunar calendar date computation library remains to  be
       completed.   There are many other historical and contempo-
       rary calendrical systems  we  have  overlooked  (Egyptian,
       Armenian,  Babylonian, Greek, Julian, Indian, and Russian,
       as well as ecclesiatical calendars  such  as  the  Alexan-
       drian).   The present dates library provides useful calen-
       drical computations not currently exploited by  _c_a_l_e_n_t_o_o_l,
       such  as  determining  the number of days, or weekdays, or
       Mondays between two dates.  Perhaps a third icon could  be
       placed  next  to  those  for the solar and lunar almanacs,
       which would open a  calendrical  computation  window.   It
       would  be  very useful if someone would write a _c_u_r_s_e_s(3X)
       based front-end for _c_a_l_e_n_t_o_o_l format date files for  those
       not  using  _s_u_n_t_o_o_l_s(1).   An  efficient way of doing this
       might be to merge _c_a_l_e_n_t_o_o_l with the  excellent  _D_a_t_e_s(1L)
       program of Dain Samples (samples@dougfir.berkeley.edu).

       An SunView version of _c_a_l_e_n_t_o_o_l is also available.

       Mail  suggestions,  corrections,  and  additions  for  the
       Hacker's Almanac to Bill Randle  (billr@saab.CNA.TEK.COM).




                          19 August 1994                       16





CALENTOOL(1)                                         CALENTOOL(1)


BBUUGGSS
       Without a doubt, but hopefully pretty minor.

CCAAUUTTIIOONNSS
       Note  that  the  dates computed here are for the Gregorian
       calendar, which was a modification of the Julian  calendar
       first  introduced  in  1582.   Countries have adapted this
       system as recently as 1927 (Turkey), and in some countries
       it is used as a civil calendar in co-existence with a sep-
       arate indigenous calendar system.  Apply caution in  using
       computed dates for non-recent years and non-European coun-
       tries.

AAUUTTHHOORRSS
       The original suntools version of _c_a_l_e_n_t_o_o_l was contributed
       to  the  Sun  User  Group  tape  (17 April 1987) by Philip
       Heller (Sun Microsystems,  heller%terrapin@sun.COM).   Sun
       Microsystems  owns  this  program,  but has no interest in
       maintaining it.

       Extensive corrections and additions have been executed  by
       Bill  Randle (Tektronix, Inc., billr@saab.CNA.TEK.COM); it
       is likely that Phil Heller would recognize little  of  the
       current      program!       R.      P.      C.     Rodgers
       (rodgers@maxwell.mmwb.ucsf.edu, School of  Pharmacy,  Uni-
       versity  of California, San Francisco) performed extensive
       beta testing, made numerous design suggestions,  and  con-
       tributed  the  holiday  computation library, icons, manual
       pages, and special dates files for later SunView versions.
       The  initial set of special dates files were modified from
       earlier  net  postings  contributed   by   Rich   Kulawiec
       (rsk@boulder.Colorado.EDU)  and  Dick  Wexelblat  (...dec-
       vax!ittvax!wxlvax!rlw), assisted by the following contrib-
       utors    known    only   by   their   network   addresses:
       (ittvax!decvax!harpo!eagle!mhuxl!ihnp4!ihuxw!pector),
       (ittvax!bunker!dick),                    (decvax!sii!mem),
       (ittvax!decvax!bellcore!yquem!psl),
       (seismo!rochester!rocksvax!sunybcs!colonel),   and   (dec-
       vax!seismo!rochester!ritcv!ccieng5!ccieng6!wla), in  addi-
       tion to others whose identifications have been lost (speak
       up!).  More dates were obtained from "Today in History" by
       Robert Heckendorn at Hewlett-Packard in Fort Collins, Col-
       orado  (robert@fc.hp.com)  for  which  the  conversion  to
       calentool   format   was   done   by   Larry   W.   Virden
       (lwv27%cas.BITNET@CUNYVM.CUNY.Edu).

       We thank Dr. Omar Afzal of Cornell University (Chairman of
       the  Committee  for  Crescent Observation) for his help in
       implementing the Islamic  date  computations.   The  lunar
       computations  were  adapted from a network posting of John
       Walker of Autodeck, Inc. (Sausalito, CA, sun!acad!kelvin),
       the solar computations were adapted from a network posting
       of  Marc  T.  Kaufman  (Los  Altos,  CA),  the  raster  to
       POSTSCRIPT(R)   conversion  was  adapted  from  a  network



                          19 August 1994                       17





CALENTOOL(1)                                         CALENTOOL(1)


       posting by Glenn Boysko of Case Western Reserve University
       and  the  pcal code for printing the pretty month calendar
       was adapted from a  network  posting  by  Ken  Keirnan  of
       Pacific Bell.

       Paul  Blumstein (Citicorp/TTI, paulb@harley.tti.COM), Mark
       Feblowitz (GTE Laboratories, mdf0%shemesh@gte.COM), Dennis
       Calkins  (Teradata  Corp., tdat!dc1@suntzu.sun.com), Hakan
       Kallberg (Simulina AB, hk@simulina.se),  Baron  O.A.  Grey
       (UCLA,  baron@lanai.cs.ucla.edu), Matt Landau (BBN Labora-
       tories, mlandau@bbn.COM), David St. Pierre (Pacific  Bell,
       david@pbsaint.PacBell.COM),  Casey Leedom (Lawrence Liver-
       more  Laboratories,  casey@lll-crg.llnl.GOV),  and  Alfred
       Correira  (UniSQL,  Inc. alfred@unisql.uucp) also provided
       useful  suggestions,  patches  and  feedback  on  previous
       releases, as did many others.

       Additional  special  thanks for the XView port go to Randy
       Thomas (rjt@sedist.cray.COM) who did the first XView  port
       of calentool 2.1 and has greatly assisted in debugging the
       current version,  Swen  Thuemmler  (swen@uni-paderborn.de)
       who  did  an  independent  port  of 2.1 from Randy's, Doug
       Eldred (eldred@hare.udev.cdc.COM) who helped me  out  with
       some X and XView questions along with valuable early test-
       ing, and many, many others who have assisted with valuable
       alpha and beta testing of the XView port.































                          19 August 1994                       18


