xenial (1) xcal.1.gz

Provided by: xcal_4.1-19_amd64 bug

NAME

       xcal -  calendar with alarms and a notebook for X11

SYNTAX

       xcal  [  -debug ][ -alarmscan ][ -format fmt ][ -editformat fmt ][ -stripformat fmt ][ -clocktick tick ][
       -u username ]

DESCRIPTION

       Xcal is an interactive calendar program.  The user interface has  several  levels.   When  started,  xcal
       displays  today's date in a small command box that is intended to sit on the screen as a companion to the
       xclock program.  The format of the command box may be altered using the resource manager, so you are  not
       stuck  with  my  preferred  layout.   You can set the time in the window too, if you wish (see the format
       resource).  Access to further levels in xcal is made by clicking a mouse button in the command box.   The
       command box is split into several areas and clicking on one of these will popup a window supporting a new
       function.

       Clicking with mouse button one on the question mark in the command box pops up a help window.  Xcal comes
       with many help buttons.  When you are convinced they are no longer any use to you, they can all be turned
       off using an X resource.

       A small button containing a `mouse' bitmap can be pressed with mouse button one to  inspect  appointments
       for  today.   This generates a panel showing information from the calendar file for today and information
       from a set of seven daily files holding regular commitments.  The panel also contains a text  scratchpad,
       `the memo panel'.  This allows the editing of a memo file.

       The  calendar  functions  are  accessed  by  clicking  a mouse buttons inside date portion of the command
       window.

       1)     Mouse button one pops up a calendar `strip' for the current month.   The  strip  has  some  header
              lines  and then one line per day of the month.  The `line per day' display contains the day in the
              month and the day of the week.  Today may be highlighted specially - the notion of Today alters at
              midnight.  The strip has a help button which displays a description of the panel.  Command buttons
              in the header line allows the user to bring up a strip for the previous or the next month.

       2)     Pressing mouse button two in the date area will bring up a dialogue box which allows the  user  to
              select  any month of any year (yes, September 1752 is supported).  The month may be input as month
              name or abbreviation, even though the prompt indicates a more restrictive format.

       3)     Pressing mouse button 3 in the date label causes the whole program to exit, a dialog box  is  used
              to ask the user for confirmation.

       Like  xcalendar,  daily events are stored in set of files, one for each day.  If the file exists when the
       strip is started, its data is displayed as the label in the command button on the right-hand side of  the
       month  strip.  The file is created and edited by entering a simple text editor (the standard text widget)
       which is started by pressing the right hand side of the appropriate day line in the strip.  You can  also
       add  data  to  the  file  by  selecting a string on the screen and clicking with the middle button on the
       right-hand side of the month strip.  The string is appended to the file for  the  day.   This  short-hand
       allows one entry to be loaded into several day files.

       The width of the month strip is computed from the width of the header.  Users who wish to display a wider
       strip to show more of the stored information should widen the strip using the minStripWidth resource (see
       below).

       The  colours  and  fonts  used in the strip is controllable by resources.  The widget that comprises each
       line in the strip is tagged with the short form name of the day, so it's easy to vary the  strip  display
       showing weekends differently from the weekdays.

       Data  files are stored in a directory usually called Calendar under the user's home directory.  Each file
       is stored in a subdirectory containing all the data for a particular year.   This  is  incompatible  with
       xcalendar, the user may specify that the compatibility should be maintained.

       Alarms  are  supported  by xcal.  When a line in the data file starts with a digit, it is assumed to be a
       time specification and a candidate for an alarm.  The line contains a string giving the alarm time and  a
       text  string  displayed  in a dialogue alarm box that pops up when the alarm fires.  You can also arrange
       for countdown alarms to fire, so that you can be told that something is about to happen.  These  dialogue
       boxes  will automatically go away after two minutes, unless the `Stick' button is pressed glueing the box
       onto the screen.  The box can be made to go away at any time by hitting the `Unpin' button.

       When  specifying  alarms,  Xcal  tries  to  be  liberal  about  the  times  that  it  understands.   Time
       specifications  are:  h, hh, hhmm, hmm, hh:mm, h:mm, hh.mm, h.mm; all of these may be optionally followed
       by an am/pm indicator - one of: A, a, AM, am, Am, aM, P, p,  PM,  pm,  Pm,  pM.   Times  must  always  be
       followed by at least one space or tab.  Some legal examples are:
            12:00 Lunch - Meet Joe at Burger King
            14.30 Meeting in the cafeteria
            2:30p Ring Mark
            7pm Pizza

       You  can  make  a time like 2:30 mean 14:30 by setting the resource AlarmWarp to be true.  If this is the
       case, an alarm hour will be promoted to a PM time if it is found to be between the range of zero and  the
       value of the resource minAlarmWarp.

       Xcal  also  supports  timed command execution from the data file.  To trigger a command, the data part of
       the line starts with an exclamation mark, eg:
            4.30pm !xmessage -message 'ring home'

       The exclamation mark can also be replaced by the string `%cron'.   It  is  also  possible  to  make  xcal
       execute a command whenever an alarm is triggered, see the Cmd resource below.

       The memo function of Xcal is accessed by pressing the non-date portion of the command window.  This shows
       a bitmap diagram of three mouse buttons.  Clicking the left mouse button in this area brings up a complex
       panel,  clicking on the button again will pop it back down again.  The top half of the panel displays the
       information held in the diary for today; pressing the Edit button here will start an edit box for  today.
       The  next  section  of  the  panel  displays  the information held in the weekly files.  Again you cannot
       directly change the text in this area, you must press on the Edit button to bring up a strip enabling you
       to  change  things.   The bottom portion of the panel is an edit window displaying the contents of a file
       usually called `memo' in the Calendar directory.  The idea of this panel is to allow you to  access  your
       current information in one button click.

       It  is  obviously  possible to change Xcal's data files without using the inbuilt text widget editor.  In
       general, Xcal will not notice this.  Editing random day files with a standard text editor will not change
       the contents of any displayed strips until the strips are popped down and up again.  Xcal knows what days
       have been altered when the text widget is used to edit  the  day  files,  and  will  reflect  any  change
       immediately into the displayed strips.

       You can make Xcal take notice of today's date file and the current memo file.  The `Update' resource sets
       a polling time in seconds.  When the clock fires and today's file has been altered,  the  alarm  list  is
       rebuilt  from  the current date file and the memo panel is updated.  The bottom part of the memo panel is
       also updated if the `memo' file has been altered on the clock tick.

OPTIONS

       Version 4 of Xcal permits one user to view another's calendar by giving the -u  option  followed  by  the
       user's  login  name.   The  user's calendar storage area is assumed to be called `Calendar' in their home
       directory.  The facilities are somewhat rudimentary.  First, the main date box will have the user's login
       name  appended  to  the date format string.  When a month strip is generated, you will be given read-only
       access to their calendar files, assuming that the file permissions allow  you  to  read  them.   This  is
       intended to be one step better than using cat on their calendar files.

       The  -debug  switch  causes  contents  of the initial date window to be incremented very frequently, this
       allows some testing of the program.

       The -alarmscan switch prints debugging information about the alarm system on standard output.

       The argument following the -format is a date format used to display dates in the top  level  window  (see
       below,  the  Format  resource).  Changing this to include a time format will make xcal display a clock in
       your top level window.

       The argument following the -stripfmt argument is a date format used to display month names and  years  in
       the monthly calendar strip.  (see the resource StripFmt).

       Similarly,  the  -editfmt  argument  is  the  format  for  dates  used in an edit window (see the Editfmt
       resource).

       The -clocktick argument is used to set the clock update time of the main date window, should  a  time  be
       displayed as well as the date.  See the Clocktick resource.

RESOURCES

       As  with all standard X applications, xcal may be customised through entries in the resource manager.  It
       is a serious  mistake  to  install  Xcal  without  putting  the  resource  initialisation  file  Xcal  in
       /usr/lib/X11/app-defaults.  Resource class names are listed below; resource instance names are identical,
       except the first letter is in lower case.  The following resource manager entries are defined:

       Debug              If True enables accelerated time.   Alarms  will  not  function  correctly.   Default:
                          False.

       OtherUser          the  name  of the user whose calendar files will be inspected.  This is usually set by
                          the -u option.

       AlarmScan          If True enables printing of  alarm  related  debugging  information  to  the  standard
                          output.  Default: False.

       ReverseVideo       If true display the output in reverse video.  Default: False.

       Format             This  is a format string used to create the contents of the top command button and the
                          memo box.  The format is aimed at the system routine: strftime.  I have chosen to  use
                          the  system  routine  because  it  makes  it  easier for non-english language sites to
                          generate their own formats.  However, this means that the names used  for  months  and
                          days  may  not be compatible with the ones set in the resources below.  Any characters
                          in the format string are passed to the output unchanged unless they specify a  format.
                          Format  letters  are preceded by a `%' character and can be found in the documentation
                          for strftime on your system.  The SunOS 4.1.3 routine supports:

                          %%      same as %
                          %a      day of week using abbreviated name
                          %A      day of week using full weekday names
                          %b      (%h) month, using locale's abbreviated names
                          %B      month, using locale's full names
                          %c      date and time as %x %X
                          %C      date and time, in local long-format date and
                                  time representation
                          %d      day of month (01-31)
                          %D      date as %m/%d/%y
                          %e      day of month (1-31; single digits are preceded  by a blank)
                          %H      hour (00-23)
                          %I      hour (00-12)
                          %j      day number of year (001-366)
                          %k      hour (0-23; single digits are preceded by a blank)
                          %l      hour (1-12; single digits are preceded by a blank)
                          %m      month number (01-12)
                          %M      minute (00-59)
                          %n      same as \n
                          %p      local equivalent of AM or PM
                          %r      time as %I:%M:%S %p
                          %R      time as %H:%M
                          %S      seconds (00-59)
                          %t      same as \t
                          %U      week number of year (01-52), Sunday is the first day of the week
                          %W      week number of year (01-52), Monday is the first day of the week
                          %x      date, using locale's date format
                          %X      time, using locale's time format
                          %y      year within century (00-99)
                          %Y      year, including century (fore example, 1988)
                          %Z      time zone abbreviation

                          The default is "%A %d %B %Y", printing the day, the date, the month and the full year.
                          I  prefer  to  use  "%A  %e %B %Y", but this does not seem to be portable to different
                          systems.  The format string is scanned to  determine  the  update  frequency  that  is
                          needed  to  maintain a correct date image.  The default needs updating every 24 hours,
                          if you insert an AM/PM format then the strip will be updated every 12  hours.   Adding
                          an  hour  specification  will  cause  an  update  every hour and specifying minutes or
                          seconds will cause appropriate behaviour.

       ClockTick          If you specify a second hand in the main date string and only want it updated every 30
                          seconds  (say) then setting the ClockTick resource to 30 will force an update for that
                          period.  Default: 0 (derived from the Format string).

       StripFmt           is used to format the date line at the top of  each  strip.   This  uses  an  internal
                          version  of  the  strftime  routine  that  only supports format characters relating to
                          months, years and days.  The supported format characters are: %A, %a, %B, %b, %h,  %D,
                          %d,  %e, %m, %n, %t, %x, %y and %%.  Long/short day and month names are taken from the
                          resources.  Default: "%B %y".

       EditFmt            provides the format string for any edit window.  This uses the same code as  StripFmt.
                          Default: "%A %d %B %Y".  Again, I prefer to use "%A %e %B %Y".

       MarkToday          If True then highlight today.  Default True.

       TodayBackground    the background colour when marking, default Black.

       TodayForeground    the foreground colour when marking today, default White.

       FontToday          Today  may  be marked by using a special font, if this is desired the font is given by
                          this resource.  Default is to use the default font.

       Directory          The name of the directory under the home directory where the  day  files  are  stored.
                          Default: Calendar.

       XcalendarCompat    If  true  then subdirectories are not created in the Calendar directory.  This flag is
                          not relevant when files are being read, so users can use both programs  with  existing
                          data files.  Default: False.

       GiveHelp           If  True  than  access  to  the  help  information  is  given.  If False, help buttons
                          disappear returning screen real-estate to the user.  You should resist setting this to
                          False in the default resources file.  Default: True.

       HelpFromFile       The  Xcal  program  will  usually  have  help  strings compiled into it.  These are in
                          English and it may be desirable to use help data in other languages.  If this resource
                          is true, it forces Xcal to look in a data file for the help strings.  Default: False.

       HelpFile           gives  the  name  of  the  file  used as a database for the help system, accessed when
                          HelpFromFile is True.  Default: /usr/lib/X11/XCal.help.

       InitialCalendar    If True then the calendar for this month is automatically displayed  on  startup.   If
                          False, the calendar is not automatically displayed.  Default: False.

       InitialEdit        If  True then an edit window for today is automatically displayed on startup if a file
                          exists for today's date.  If False, the edit window is  not  automatically  displayed.
                          Default: False.

       InitialMemo        If True then the memo window is automatically displayed on startup.  Default: False.

       UseWmTitle         If True display the month and the year at the head of each strip.  This information is
                          duplicated if your window manager uses titles so it is nice to be able to turn it off.
                          Default: True.

       TextBufferSize     the  maximum  number  of  bytes  which we are prepared to deal with in an edit window.
                          Default: 2048 bytes.

       Alarms             whether or not to enable the alarm system.  Default: True.

       ExecAlarms         if the alarm system is active, whether or  not  to  invoke  timed-execution  commands.
                          Default: True.

       Update             When  scanning  for alarms in the current day file Xcal inspects it at program startup
                          time and also when it is edited using the normal built-in editing mechanism.  However,
                          if  some  external  program  changes t file xcal will not see the new contents and new
                          alarms will not be set.  Setting this resource to non-zero will force xcal to scan the
                          file  every  `update'  seconds  looking for alterations in size and modification date.
                          When it detects that the file is altered, then it  will  rebuild  the  internal  alarm
                          list.  Default: zero.

       Nbeeps             When an alarm window is popped up, it is accompanied by `Nbeeps' beeps.  Default: 3.

       Volume             Control the loudness of the beep. Default: 50.

       Cmd                This  resource  contains  a  command  that is executed by calling the shell when every
                          alarm is triggered.  The command is passed the  contents  of  the  data  line  as  one
                          argument.

       Countdown          contains  a comma separated string of numbers; for example: 10,5,0.  The string allows
                          the user to customise warning alarms: so in the example, alarm boxes will be displayed
                          10 minutes before the stated time, 5 minutes before the stated time and exactly on the
                          stated time.  Commands lines in the data prefaced by a `!' will  always  be  triggered
                          exactly at the stated time.  Default: 10,0.

       Autoquit           Each  dialogue box containing an alarm message contains an `Unpin' button allowing the
                          user to remove the message from the screen by using mouse button  one.   Additionally,
                          the  message  box  can  remove  itself  from the screen after a specified period, this
                          resource gives that timeout in seconds.  If the resource is set to zero, then the user
                          is always forced to take explicit action to remove the box.  Default: 120, alarm boxes
                          disappear after 2 mins.

       Alarmleft          contains a printf string that is displayed in the label at the top  of  an  alarm  box
                          when  countdown  is  in  operation and there is some time before the stated time.  The
                          time before the stated time is supplied as the second argument  to  printf.   Default:
                          ``%d minutes before...''

       Alarmnow           contains  the  printf string that is displayed in the label at the top of an alarm box
                          when the stated time is reached.  Default: ``Time is now...''.

       UseMemo            enables the use of the memo feature.  This defaults to ``True'',  but  is  present  to
                          allow users to make XCal have as it used to.

       MemoLeft           affects  the  placing of the memo button in the top level date window.  The default is
                          `True' meaning that the button box is placed on the left of the date portion.  Setting
                          this to `False' will place the button box to the right of the date portions.

       MemoFile           gives the name of the memo file within the Calendar directory.  The default is `memo'.

       MaxDisplayLines    controls  the maximum number of text lines that can placed in the top half of the memo
                          panel.  The top hald will normally size to the number of lines in the diary  file  for
                          the  day,  unless the number of lines exceed the value in this resource.  This ensures
                          that today's events do not dominate the memo panel.  Default: 5 lines.

       MaxStripHeight     controls the maximum height of a strip.  A scroll bar will be added into the date part
                          of  the scrip of the contents are larger than this number.  If unset, this defaults to
                          the height of the screen.  Default: unset.

       MinStripWidth      The width of month strips are set by the top line, which usually  displays  the  month
                          and  year.   The  whole  strip  can be widened from this default value by setting this
                          resource to be non-zero.  Default: zero (i.e. off).

       January            February and so on.  The names of the long form of the month name.

       Jan                Feb and so on.  A short form of the month name - done this way because  I  doubt  that
                          writing  with  %3s works in all languages.  Changing this resource means that the data
                          file will no longer be compatible with xcalendar .

       Sunday             Monday and so on.  The long names of the days: Sunday, Monday etc.  These are used  in
                          titles: the top level widget, the title of an edit window and the memo frame.

       Sun                Mon and so on.  The short names of the days - used in date strips.

       Private            Contains  the  string  `Private  calendar  entry' and is used when the -u option is in
                          force. It is displayed when a calendar file entry is unreadable by the caller.

       Alarmleft          Contains the string `%d minutes before'.

       Alarmnow           Contains the string `Time is now...'.

       Already            Contains the string `Already editing %d %B %Y' I prefer to use `Already editing %e  %B
                          %Y'.

       AlreadyWeekly      Contains the string `Already editing %A'.

PANEL MAP

       Xcal makes extensive use of the resource manager.  The user needs to know the names of the various panels
       and widgets which comprise the application.

       XCal                            Toplevel application
               form                    Form containing two buttons
                       today           Memo Command button
                       date            Strip Command button
                       mainHelp                Optional main help button

       Then we have various popups.  The Calendar Strip is:

       "Mon Year"                      the popup shell
               Month                   panel containing the strip
                       header          label containing month and year
                       action          form containing < quit > buttons
                               back    command containing < - last month
                               quit    command containing exit button
                               next    command containing > - next month
                       help            command generating help
               viewport                        viewport permitting scrolling of the
               data                    data widget
                       "DDD"           form containing day button (lots of these)
                                       these are named for the short days of the week
                               label   label containing dd DDD, day of the month
                                       and day of the week
                               info    command containing the file data

       Note that each day button is named for the day of the week, so that weekends can be highlighted specially
       using the standard resources.

       The weekly popup strip is:

       weekly                          the popup shell
               weekly                  panel containing the strip
                       header          label containing the title
                       action          form containing quit and help
                               quit    command containing exit button
                               help    command generating help
               viewport                viewport permitting scrolling of the
               data                    data widget
                       shortday        form containing days
                               label   label containing day of the week
                               info    command containing the file data

       The Edit Window is:

       edit                            the popup shell
               panel                   the panel inside the shell
                       title           the form containing the first line
                               quit    the exit button
                               save    the save button
                               help    the help button
                               date    the date string
                       text            the text widget for editing

       The Help Window is:

       help                            the popup shell
               helpPanel                       the panel inside the shell
                       helpForm                the form containing the title line
                               quit    the exit button
                       helpText                the text widget showing the information

       The Alarm Window is:

       alarm                           the popup shell
               alarmPanel              the panel inside the shell
                       alarmForm       form for top line
                               alarmQuit       the exit button
                               alarmHold       the hold button
                               alarmTitle      the title on the alarm window
                       alarmText       the text widget for displaying

       The Memo Window is:

       memo                            the popup shell
               memoPanel               the panel inside the shell
                       title           Top line form widget
                               quit    the exit button
                               edit    edit button - edit today's info
                               help    the help button
                               date    display today's date
                       display         text from today's date file
                       weeklyMemo      form for the Memo title line
                               weeklyEdit      Edit button
                               weeklyTitle     Title area
                       display         text from today's weekly file
                       memoMiddle      Middle line form widget
                               save    Save button
                               memoTitle       text title of middle line
                       memoText        Text widget showing memo file

       The Middle button date selection popup is:

       question                                the popup shell
               newdate                 the dialog widget
                       ok              the OK button
                       cancel          the cancel button

       The Right button exit selection popup is:

       question                                the popup shell
               exit                    the dialog widget
                       yes             the yes button
                       no              the no button

       An error is shown when a multiple attempts are made to edit the same day file.

       question                                the popup shell
               noedit                  the dialog widget
                       ok              the OK button

       A dialog box is popped up when an attempt is made to exit from an editing box without saving the file.

       check                           the dialog widget
               yes                     the yes button
               no                      the no button

FILES

       $HOME/Calendar/∗

       xc<dd><Mon><Year>  A data file is day, Month in three letter format and the year.

       xy<Year>           A year directory.

       xw<Day>            A data file for the weekly code, one per day.

       memo               The memo file.

       The  standard  resource  database  can be found in /usr/lib/X11/app-defaults/Xcal.  Assuming that this is
       where the system admin installed it.

SEE ALSO

       xrdb(1), xcalev(1), xcalpr(1), xcal_cal(1)

BUGS

       There should be some way of removing several edit windows from the screen at once.

       Setting an alarm 1 minute in the future may not work.

       Countdown does not work in the early hours of the morning, if you have a  ten  minute  countdown  and  an
       alarm set at 0005 - then you will not get warning at 2325.

       Alarms set at 0000 probably won't work.

AUTHOR

       Copyright 1989,1990,1993 by Peter Collinson, Hillside Systems All rights reserved.

       This product includes software developed by the University of California, Berkeley and its contributors.

       At  one  time,  much  of  the  xcalendar  program  was  plundered  to  create  xcal ; author is: Roman J.
       Budzianowski, MIT Project Athena

       Thanks to Ed Gould, Mt Xinu for the support for the calendar(1) program.  Thanks to Mark Majhor,  Sequent
       for  the basis of the alarm code.  Thanks to Rod Whitby, Austek Microsystems Pty. Ltd., Australia for the
       ideas of the Stick/Unpin code for alarms and for prompting me to add the  memo  code.   Thanks  to  Miles
       O'Neal from Pencom for revising the help code to be a little more `X', although this was later revised to
       use files.

       There are a number of other people who have sent in revisions, some I have used, some I have not.  Thanks
       anyway.