.TH xcal 1 "September 1990" "X Version 11 R4"
.SH NAME
xcal \-  calendar with alarms and a notebook for X11
.SH SYNTAX
.B xcal
[
.B \-debug
][
.B \-alarmscan
]
.SH DESCRIPTION
.I Xcal
is an interactive calendar program.
The user interface has several levels.
When started
.I xcal
displays today's date in a small command box on the screen.
The date changes at midnight.
The command box is intended to sit on the screen as a companion to the
.I xclock
program.
The format of the command box may be altered using the resource manager, so you
are not stuck with my preferred format.
A small button in the top level window can be pressed 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.
Finally, the memo panel displays and allows the edit of a memo file.
.LP
The calendar and notebook functions are accessed by clicking the mouse
buttons inside date portion of the command window.
.IP 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.
The command buttons in the header line allows the user to bring up a strip
for the previous or the next month.
.IP 2)
Pressing mouse button two in the date area will bring up a dialog 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.
.IP 3)
Pressing mouse button 3 in the command window causes the whole program to
exit, a dialog box is used to ask the user for confirmation.
.LP
Like
.IR xcalendar ,
daily events are stored in set of files, one for each day.
The file is created 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.
If the file exists
its data is displayed as the label in the command button.
This allows the user to use the first few lines of the file in an
intelligent manner since
X11R4 allows multiple lines of text to appear in a command button.
The strip width is sized by the length of the header, and users who
wish to display a wider strip to show more of the stored information
should widen the strip using the \fIminStripWidth\fP resource (see below).
.LP
Data files are stored in a directory usually called
.B 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 
.IR xcalendar ,
the user may specify that compatibility should be maintained.
.LP
.I Alarms
are supported by
.IR 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.
When the time is reached, or at some user specified time before that,
a dialogue box will be popped up onto the screen.
The dialogue box 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.
.LP
.I 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:
.br
.nf
	12:00 Lunch - Meet Joe at Burger King
	14.30 Meeting in the cafeteria
	2:30p Ring Mark
	7pm Pizza
.fi
.LP
.I 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:
.br
	4.30pm !xmessage -message 'ring home'
.LP
It is also possible to make 
.I xcal
execute a command whenever an alarm is triggered, see the \fIcmd\fP resource
below.
.LP
The Memo function of
.I Xcal
is accessed by pressing the non-date portion of the command window.
Currently 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 is back down again.
The top half of the panel displays the information held in the diary
for today; you cannot edit the data from here \- and must open the
diary strip to change the data.
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.
.LP
It is obviously possible to change
.IR Xcal 's
data files without using the inbuilt text widget editor.
In general,
.I 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.
.I 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.
.LP
You can make 
.I 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.
.SH OPTIONS
The
.I \-debug
switch causes contents of the initial date window to be incremented once
a second rather than once per day.
.LP
The
.I \-alarmscan
switch prints debugging information about the alarm system on standard output.
.SH "PANEL MAP"
.PP
.I 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.
.LP
.de EX		\"Begin example
.ne 5
.if n .sp 1
.if t .sp .5
.nf
.ta +8u*\w'\0'u +8u*\w'\0'u +8u*\w'\0'u +8u*\w'\0'u +8u*\w'\0'u +8u*\w'\0'u
..
.de EE
.fi
.if n .sp 1
.if t .sp .5
..
.EX
XCal				Toplevel application
	form			Form containing two buttons
		today		Memo Command button
		date		Strip Command button
.EE
.LP
Then we have various popups.
The Calendar Strip is:
.EX
"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
		"dd DDD"	form containing day button (lots of these)
			label	label containing dd DDD, day of the month
				and day of the week
			info	command containing the file data
.EE
.LP
The weekly popup strip is:
.EX
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
		shortday	form containing days
			label	label containing day of the week
			info	command containing the file data
.EE
.LP
The Edit Window is:
.EX
edit				the popup shell
	panel			the panel inside the shell
		title		the form containing the first line
			quit	the exit button
.EE	
.LP
The Help Window is:
.EX
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
.EE
.LP
The Alarm Window is:
.EX
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
.EE
.LP
The Memo Window is:
.EX
memo				the popup shell
	memoPanel		the panel inside the shell
		title		Top line form widget
			quit	the exit button
			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
2		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
.EE
.LP
The Middle button date selection popup is:
.EX
question				the popup shell
	newdate			the dialog widget
		ok		the OK button
		cancel		the cancel button
.EE
.LP
The Right button exit selection popup is:
.EX
question				the popup shell
	exit			the dialog widget
		yes		the yes button
		no		the no button
.EE
.LP
An error is shown when a multiple attempts are made to edit the same day file.
.EX
question				the popup shell
	noedit			the dialog widget
		ok		the OK button
.EE
.LP
A dialog box is popped up when an attempt is made to exit from an editing
box without saving the file.
.EX
check				the dialog widget
	yes			the yes button
	no			the no button
.EE
.SH RESOURCES
As with all standard X applications, \fIxcal\fR may be customised through 
entries in the resource manager.
It is a serious mistake to install
.I Xcal
without putting the resource initialisation file 
.I Xcal
in 
.IR /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:
.LP
.TP "\w'ReverseVideoMarkNNN'u"
.B Debug
If True enables accelerated time.
Alarms will not function correctly.
Default: False.
.TP
.B AlarmScan
If True enables printing of alarm related debugging information
to the standard output.
Default: False.
.TP
.B ReverseVideo
If true display the output in reverse video.
.IP
.B Format
The \fIprintf\fP format used to create the contents of the top command button,
the title in an edit window and the title in the memo window.
The default is "%s %2d %s %d", the arguments to this command are presented
in a default order: day, month string and year.
The order is controlled by the Order resource, this contains the default
string "wdmy".
.TP
.B Order
This resource gives the order that various arguments are presented to the
printf using the format string defined above.
Legal combinations using day, month and year are: dmy, ymd, mdy, ydm.
The name of today can be inserted at the start of the string by
using one of the formats: wdmy, wymd, wmdy, wydm.
It can be entered at the end by using on of the formats: dmyw, ymdw, mdyw, ydmw.
In case you are wondering the `w' stands for `day' of the week.
Beware that altering this resource from
the default may force you to change the format string,
see the previous resource.
The default is wdmy.
.TP
.B DateYearIsTwoDigits
The display of the year in the date strip is controlled
the format above.
If this resource is true then the year will be displayed as a two
digit number; if false the whole four digits will be displayed.
Default: False.
.TP
.B EditYearIsTwoDigits
The display of the year in the edit boxes is controlled by
the format above.
If this resource is true then the year will be displayed as a two
digit number; if false the whole four digits will be displayed.
Default: False.
.TP
.B MemoYearIsTwoDigits
The display of the year in the memo box is controlled
the format above.
If this resource is true then the year will be displayed as a two
digit number; if false the whole four digits will be displayed.
Default: False.
.TP
.B MarkBackground
The background colour for highlighting entries.
Default Black.
.TP
.B MarkForeground
The foreground colour for highlighting entries.
Default White.
.TP
.B MarkToday
If True then highlight today.
Default True.
.TP
.B TodayBackground
the background colour when marking, default Black.
.TP
.B TodayForeground
the foreground colour when marking today, default White.
.TP
.B 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.
.TP
.B Directory
The name of the directory under the home directory
where the day files are stored.
Default: Calendar.
.TP
.B 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.
.TP
.B GiveHelp
If True than access to the help information is given.
If False, help buttons disappear and the initial message is not printed.
Default: True.
.TP
.B InitialCalendar
If True then the calendar for this month is automatically displayed on
startup.
If False, the calendar is not automatically displayed.
Default: False.
.TP
.B 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.
.TP
.B InitialMemo
If True then the memo window is automatically displayed on startup.
Default: False.
.TP
.B 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.
.TP
.B 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).
.TP
.B TextBufferSize
the maximum number of bytes which we are prepared to deal with in an
edit window.
Default: 2048 bytes.
.TP
.B Alarms
whether or not to enable the alarm system.
Default: True.
.TP
.B Update
When scanning for alarms in the current day file
.I 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 the todays file
.I xcal
will not see the new contents and new alarms will not be set.
Setting this resource to non-zero will force 
.I 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.
.TP
.B Nbeeps
When an alarm window is popped up, it is accompanied by `Nbeeps' beeps.
Default: 3.
.TP
.B Volume
Control the loudness of the beep. Default: 50.
.TP
.B 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.
.TP
.B 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.
.TP
.B 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.
.TP
.B Alarmleft
contains a \fIprintf\fP 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...''
.TP
.B Alarmnow
contains the fIprintf\fP string that is displayed in the label at the top
of an alarm box when the stated time is reached.
Default: ``Time is now...''.
.TP
.B UseMemo
enables the use of the memo feature.
This defaults to ``True'', but is present to allow users to make 
.I XCal
have as it used to.
.TP
.B 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.
.TP
.B MemoFile
gives the name of the memo file within the Calendar directory.
The default is `memo'.
.TP
.B 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.
.TP
.B January
.B February
and so on.
The names of the long form of the month name.
.TP
.B Jan
.B 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
.I xcalendar .
.TP
.B Sunday
.B Monday
and so on.
The \fIlong\fP 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.
.TP
.B Sun
.B Mon
and so on.
The short names of the days \- used in date strips.
.TP
.B Weekly
The word `Weekly' used in various places.
.SH FILES
.PP
 $HOME/Calendar/*
.LP
.TP "\w'xc<dd><Mon><Year>  'u"
xc<dd><Mon><Year>
A data file is day, Month in three letter format and the year.
.TP
xy<Year>
A year directory.
.TP
xw<Day>
A data file for the weekly code, one per day.
.TP
memo
The memo file.
.LP
The standard resource database can be found in /usr/lib/X11/app-defaults/Xcal.
Assuming that this is where the system admin installed it.
.PP
.SH SEE ALSO
xrdb(1), xcal_cal(1)
.PP
.SH BUGS
There should be some way of removing several edit windows from the screen
at once.
.LP
It would be nice to be able to cut from the date box on the screen.
.LP
Setting an alarm 1 minute in the future may not work.
.LP
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.
.LP
Alarms set at 0000 probably won't work.
.SH AUTHOR
.LP
Copyright 1989,1990 by Peter Collinson, Hillside Systems
All rights reserved.
Placed into the public domain.
.PP
Much of the
.B xcalendar
program was plundered to create
.B xcal ;
author is: Roman J. Budzianowski, MIT Project Athena
.PP
Thanks to Ed Gould, Mt Xinu for the support for the
.IR 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.