ical(1)
NAME
ical - An X based Calendar Program
SYNOPSIS
Ical provides an X interface for maintaining a calendar.
A calendar is basically just a set of items. An item is
either an appointment, or a notice. An appointment starts
at a particular time of the day, and finishes at a partic-
ular time of the day. A notice does not have any starting
or ending time. Notices are useful for marking certain
days as special. For example, a calendar may contain a
notice for April 15th indicating that taxes are due. When
the documentation below refers to an item, it applies both
to notices and appointments. The main features of ical
are:
* Items can be created and edited easily.
* Items can be cut, copied and pasted.
* Items can be made to repeat in various ways.
* Ical will generate alarms for upcoming appoint-
ments.
* Users can view many calendars at a time.
* Calendars can be shared by many users.
* Related items can be grouped in their own calen-
dar.
INVOCATION
You can specify various command line options to control
ical.
General Options
The following options can be used even when you are not
logged in on an X display.
-calendar file-name
The calendar is read from the specified
file. See the description of calendar files
for more information.
-date date
Set the starting date for item listings or
window display to the specified date. For
example: ical -date 1/aug/1997
-list Print a listing of the starting date's items
and exit immediately. See the description
of listing items for details on the actual
items printed by this option. The starting
date is usually today, but may be changed
with the -date option.
-show +days
Print a listing for items in the range
[starting date...(starting date + days - 1)]
and exit immediately. See the description
of listing items for details on the actual
items printed by this option. The starting
date is usually today, but may be changed
with the -date option.
-print 1|2|4|8|10|month
Generate postscript on standard output for
range of days and exit. The starting date
is usually today, but may be changed with
the -date option.
X Options
The following options are valid only if you are logged in
on an X display.
-iconic
Start up with the main window iconified.
-iconposition x,y
Icon is placed at the specified position.
-popup
Popup a window containing a listing of the
starting date's items and exit as soon as
the window is dismissed. See the descrip-
tion of listing items for details on the
actual items printed by this option. The
starting date is usually today, but may be
changed with the -date option.
-geometry geometry
Use geometry as the geometry for the main
window.
-fg color
Use color as the foreground for all windows.
-bg color
Use color as the background for all windows.
-display display
Run ical on the specified X display.
WINDOWS
The main calendar window displays the appointments and
notices for a particular date.
Date Selector
The top left portion of the window contains
a date selector. You can click on the vari-
ous arrows to change the month or the year.
The day of the month can be selected by
clicking on the appropriate day in the month
display. The date selector contains various
other buttons for convenient date selection.
Notice Window
The bottom left portion of the window con-
tains the notices for the selected date. A
scroll bar is provided if all of the notices
for the selected date do not fit into the
notice window.
Appointment Window
The right portion of the window contains the
appointments for the selected day. You can
scroll this region by using the scroll bar,
or by dragging with the middle mouse button
in the background.
Menubar
A menubar runs along the top of the calendar
window. The File menu allows you to create
and destroy application windows.
Status Line
The bottom portion of the window contains a
status line. This status line indicates the
calendar from which the selected item comes
and whether or not the selected item
repeats.
CALENDAR FILES
A calendar is stored in a calendar file. The default cal-
endar file is named .calendar and is kept in the user's
home directory. If the CALENDAR environment variable is
set, its value is used as the name of the calendar file.
The CALENDAR environment variable and the default can both
be overridden by specifying a file name on the command
line as follows -- ical -calendar file-name. Ical period-
ically saves any modifications made to a calendar to the
corresponding calendar file. It also periodically incorpo-
rates changes made to a shared calendar file by other
instances of ical. You can explicitly trigger these peri-
odic saves and reads by using the File menu.
Including and Sharing Calendars
You can include other calendars into your private calen-
dar. This facility is mainly useful for allowing a group
of people to share a common set of items. For example,
members of a particular group might have a calendar that
contains the birthdays for each member of the group. This
calendar can be included in each group member's private
calendar. Use the File menu to include and exclude shared
calendars. Use the Move Item To ... entry from the Item
menu to move items between calendars. Use the From Calen-
dar ... entry in the List menu to list all items a partic-
ular calendar.
ITEMS
Notices
You can enter notices by clicking in the background in the
bottom-left portion of the main calendar window. This
click will create a new notice for the selected date. You
can enter text into the notice by typing into it while it
is selected (selected notices are highlighted by being
displayed in different colors). A notice can be selected
for editing by clicking with left button.
Appointments
You can enter appointments by left-clicking in the back-
ground in the right portion of the main calendar window.
This click will create a new appointment for the selected
date. The start time for this appointment is determined by
the click location. You can move the appointment by drag-
ging it with the middle mouse button held down. The
appointment can be resized by dragging with the right
mouse button held down.
Appointment text can be edited by typing into the appoint-
ment window while it is selected. If the appointment text
you are typing in does not fit into the appointment area,
then it will overflow out of the appointment area, but
will be editable normally. If you do not like overflowing
text, you should turn off the Allow Text Overflow option
in the Options menu . With this option turned off, if the
current text completely fills the area allocated to the
appointment, then any attempts to add to the appointment
text will be ignored until the appointment is enlarged
with the right mouse button. Likewise, the right mouse
button will refuse to shrink an appointment window if the
appointment text completely fills the appointment window.
Alarms
Ical generates alarms for appointments. By default, the
first alarm is generated fifteen minutes before the
appointment is supposed to start and successive alarms are
generated every five minutes until the appointment actu-
ally starts. You can change this default behavior by
selecting the Default Alarms entry from the Options menu.
You can also change the timings of these alarms on an
appointment-by-appointment basis by double-clicking on the
appointment, or by selecting the appointment and then
chosing the Properties entry in the Item menu.
Repeating Items
Items can be made to repeat in various ways. Item repeti-
tion can be controlled by using the entries in the Repeat
menu. These entries make the item repeat in certain fre-
quently used ways. For example, the Monthly entry makes
the selected item repeat once per month and the Weekly
entry makes the selected item repeat once per week. The
Edit Monthly... and Edit Weekly... entries can be used to
make items that repeat in more complex ways: for example,
an item that occurs on the last Friday of each month, or
an item that occurs on Monday, Wednesday, and Friday every
week.
In addition to making an item repeat in one of the pre-
defined ways, you can also restrict an item's starting and
finishing date by selecting the Set Range... entry from
the Repeat menu.
Normally, a modification to a repeating item applies to
all occurrences of that item. A single occurrence of a
repeating item can be modified by selecting the occurrence
and then choosing the Make Unique entry from the Repeat
menu. The selected occurrence can now be modified inde-
pendently of the repeating item.
Todo Items
Items can be marked as todo items by selecting the Todo
entry in the Item menu. A todo item is automatically
moved forward to today's date every day until the item is
deleted or marked as done. An item can be marked as done
by clicking in the little check-box right next to the dis-
played item.
Highlighting
By default, if any item occurs on a date, then the date is
highlighted in the date selector located in the top-left
corner of the calendar window. You can use the Highlight
entries in the Item menu to control this highlighting
behavior on an item-by-item basis.
KEY BINDINGS
This section is currently incomplete.
EDITING
Dragging with the left mouse button in a selected appoint-
ment or notice sets the X selection. The Edit menu pro-
vides commands for dealing with the X selection.
Ical also has a clipboard that can store a single item.
The Copy entry in the Edit menu copies the selected item
into the clipboard. The Cut entry does the same, but it
also deletes the item from the calendar. If the selected
item repeats, then the Cut command allows the user to
delete all occurrences of the item, or just the selected
occurrence. However, if the selected item does not belong
to you, then Cut just hides the item from you. Other peo-
ple will still see the item. An item in the clipboard can
be inserted into the current day by selecting Paste entry.
The newly pasted item loses all repetition information,
and occurs just on the day in which it was pasted.
LISTING ITEMS
You can generate listings of imminent items by selecting
one of the listing options in the List menu. You can also
use the command line options -list, -show, or -popup to
generate item listings. The command line options are most
useful in .login files.
By default an item is included in a listing for a particu-
lar date if it occurs either on that date, or on the very
next day. You can control this feature of item listings
with the List item entry in the Item menu.
PRINTING
Calendar contents can be printed by selecting the Print
option from the File menu.
CUSTOMIZATION
Some of ical's behavior can be customized via the Options
menu. Other aspects of ical's behavior can be controlled
via X Resources.
X Resources
Behavior
The following X resources can be used to control various
aspects of ical's behavior.
Ical.pollSeconds
Shared calendars are checked for changes
made by other people once every pollSeconds
seconds. The default value is 120. If ical
appears sluggish, or if it is using too much
CPU time, increase this value.
Ical.saveSeconds
Calendar files are saved once every saveSec-
onds seconds. The default value is 30. If
ical appears sluggish, or if it is using too
much CPU time, increase this value.
Dimensions
The following X resources can be used to control various
dimensions of ical's appearance.
Ical.itemSelectWidth
The border width of selected items is set to
the value of this option to display the
selected status of the item to to the user.
On color displays, the default value of this
option is 1 because on color displays selec-
tion is indicated by changing the color of
the selected item. On monochrome displays,
the default value of itemSelectWidth is 4.
Ical.Dayview.geometry
X geometry specification for main calendar
window. Usually, you will just specify the
window position here. The size of the win-
dow is easier to control via the Options
menu.
Ical.Reminder.geometry
X geometry specification for alarms. Usu-
ally, you will just specify the window posi-
tion here. The window size will be calcu-
lated automatically.
Ical.Listing.geometry
X geometry specification for item listings.
Usually, you will just specify the window
position here. The window size will be cal-
culated automatically.
Colors
The following X resources can be used to customize ical's
use of colors. If ical windows show up with illegible
colors (not enough distinction between background and
foreground), it may be because your X resources contain
definitions for *foreground or *background that conflict
with ical colors. In general, it is a bad idea to define
*foreground and *background in your resources because it
will break a number of programs. You will be better off
defining resources on an application by application basis.
Ical*Foreground/Ical*Background
Foreground and background colors for most of
ical's windows.
Ical*disabledForeground
Foreground color assigned to disabled but-
tons and menu entries.
Ical.itemFg/Ical.itemBg
Foreground and background colors for unse-
lected items. The default foreground is
black and the default background is gray.
Ical.itemSelectFg/Ical.itemSelectBg
Foreground and background colors for
selected items. The default foreground is
black and the default background is Slate-
Blue1.
Ical.itemOverflowColor/Ical.itemOverflowStipple
Background color and stippling used for
appointment text that overflows out of the
appointment area. On color displays, the
default overflow background is SlateBlue3
and no stippling is done (specified by an
empty stipple option). On monochrome dis-
plays, the default overflow background is
black, and the default overflow stippling is
gray50.
Ical.apptLineColor
The color for the background lines and times
displayed in the appointment window.
Ical.weekdayColor
The color used to display days of the week.
The default is black.
Ical.weekendColor
The color used to display weekends. The
default is red.
Ical.interestColor
The color used to highlight interesting
dates. The default is blue.
Ical.weekendInterestColor
The color used to highlight interesting
dates on weekends and holidays. The default
is purple.
Fonts
The following resources can be used to customize ical's
use of fonts.
Ical.fontFamily
Preferred font family. Fonts for various
purposes are obtained from this family
unless overridden with one of the specifica-
tions below. The default font family is
times. Some other font families you can
specify here are charter, new century
schoolbook, and helvetica. My personal
favorite is new century schoolbook.
Ical.fixedFontFamily
Preferred font family for fixed-width fonts.
Fixed-width fonts for various purposes are
obtained from this family unless overridden
with one of the specifications below. The
default font family is courier. Some other
font families you can specify here are fixed
and terminal.
Ical.fontSize
Font sizes used for ical. Use the value
small to use small font sizes everywhere.
Any other value for this option defaults to
the normal fonts.
Ical*itemFont
Font used to display item contents.
Ical.weekdayFont
Font used for displaying days of the week.
Ical.weekendFont
Font used for displaying weekends.
Ical.interestFont
Font used to highlight interesting dates.
Ical.weekendInterestFont
Font used to highlight interesting dates on
weekends and holidays.
Ical.smallHeadingFont
Font used for small headings.
Ical.largeHeadingFont
Font used for large headings.
Ical*<class>*font:
Font used for windows of a certain class.
Possible values for <class> are Dialog, But-
ton, Label, Menubutton, Menu, Listbox, and
Reminder.
Tcl Code
Users can also customize ical by writing tcl code and
storing it in the file ~/.tk/ical/user.tcl. The code
stored in this file is executed when ical starts up.
Ical also looks for site-specific customizations at
startup. These customizations can be placed in the file
site.tcl in either the ical library directory, or its par-
ent directory. (By default, ical looks for site.tcl in
/usr/local/lib/ical/v[version]/, and /usr/local/lib/ical/,
but these directories may be located elsewhere on your
system.) The site specific files will be loaded in before
any user specific customization file is loaded in.
See the "Tcl Interface to Ical" document available via the
Ical help menu.
Ical can run even when X is not available, therefore cus-
tomization files should be written so that they will func-
tion even when Tk commands are not available.
MENUS
File Menu
Save Save any modifications to the appropriate
calendar files.
Re-Read
Read any changes made to a shared calendar
by another user or another instance of ical.
Ical will automatically invoke this function
periodically. It is provided as a menu
entry only so for people who do not want to
wait for ical's periodic checks.
Print Print calendar contents. The user has the
option of saving the print-out to a file,
pre viewing the print-out by specifying a
PostScript displaying program, or sending
the print-out directly to a PostScript
printer by specifying a printing command.
Include Calendar
Select a calendar to include into your pri-
vate calendar. Included calendars are nor-
mally used to share calendars between dif-
ferent users.
Remove Include
Remove a previously included calendar from
your private calendar.
New Window
Open a new calendar window. This new window
can be used to view the items for a differ-
ent date than the original window.
Close Window
Close the selected window.
Exit Save any changes and kill ical.
Edit Menu
Cut Item
Delete the currently selected item and store
it in the clipboard.
Copy Item
Copy selected item to the clipboard.
Paste Item
Paste item from clipboard into calendar.
Delete Text
Delete the currently selected text from the
selected item.
Insert Text
Insert the current X selection into the
selected item.
Import Text
Import the current X selection as a new item
into the calendar. The date and time of
this new item are parsed from the X selec-
tion if possible.
Item Menu
Todo Toggle the item between being a todo item
and not being a todo item.
Always Highlight
The item always causes the corresponding
date to be highlighted. This is the default
behavior.
Never Highlight
The item never causes the corresponding date
to be highlighted.
Highlight Future
The item causes the corresponding date to be
highlighted if and only if the date is not
in the past.
Holiday
The item causes the corresponding date to be
highlighted as a holiday.
Change Alarms
This item pops up a dialog box that allows
you to edit the alarm times for an appoint-
ment.
Note that this will only change the alarm times for
the selected appointments. You can make this
change for all appointments that do not have spe-
cial alarm times by using the Default Alarms entry
in the Options menu.
Early Warning
By default an item is included in a listing
for a particular date if it occurs either on
that date, or on the very next day. Some-
times, you may want to include an item in
listings for earlier dates. For example, if
you have an item reminding you of a birthday
on March 17th, you might want this item to
be included in all listings from March 7th
to March 17th so that you will have enough
time to go out and buy a present. You can
achieve this effect by selecting this menu
entry and then entering "10 days" into the
resulting dialog.
Note that this will only change the listing behav-
ior for the selected item. You can make this
change for all items you create from now on by
using the Default Listings entry in the Options
menu.
Properties ...
Edit various item properties, including the
calendar to which the item belongs, high-
lighting information, early warning options,
alarm times, and starting and ending times
for appointments. You can also double-click
on an item to pop up the property editing
dialog.
Search Forward
Search forward looking for an item that con-
tains a user specified string.
Search Backward
Search backward looking for an item that
contains a user specified string.
Repeat Menu
Don't Repeat
Make the selected item a non-repeating item.
Daily Make the item repeat every day.
Weekly
Make the item repeat once every week.
Monthly
Make the item repeat once every month.
Annually
Make the item repeat once every year.
Edit Weekly
Make the item repeat on a weekly basis in a
complicated fashion. For example, on Tues-
day and Thursday every week.
Edit Monthly
Make the item repeat on a monthly basis in a
complicated fashion. For example, on the
third Sunday in June, or the last working
day of each month.
Set Range...
Restrict the range for a repeating item.
Last Occurrence
Make the current occurrence the last occur-
rence of the selected item. I.e., remove
any occurrences after the current date.
Make Unique
If you want to modify just a single occur-
rence of a repeating item, select the item
occurrence you want to modify and then acti-
vate this menu entry. Now all modifications
to this item occurrence will only affect
this particular occurrence.
List Menu
One Day
List the item occurrences for one day.
Seven Days
List the item occurrences for the next seven
days.
Ten Days
List the item occurrences for the next ten
days.
Thirty Days
List the item occurrences for the next
thirty days.
Week List the item occurrences for this week.
Month List the item occurrences for this month.
Year List the item occurrences for this year.
From Calendar ...
List all item occurrences from a selected
calendar.
Option Menu
Appointment Range
Controls the subset of a day displayed by
default in the appointment listing. The
factory settings display 8:00am to 6:00pm.
Notice Window Height
This entry can be used to change the height
of the notice window.
Item Width
This entry can be used to change the width
of displayed appointments and notices.
Allow Text Overflow
If this option is selected, then you can
type in any amount of text into an appoint-
ment. The part of the text that does not
fit into the appointment will be allowed to
overflow out of the appointment. If you do
not like text overflowing out of an appoint-
ment, then you should turn off this option.
Display Am/Pm
If this option is selected, time will be
printed in twelve hour mode with am or pm
indicators. Otherwise, time will be printed
in twenty-four hour mode.
Start Week on Monday
If this option is selected, month displays
will start each week off on a Monday. Oth-
erwise, each week will start on a Sunday.
Default Alarms
Use this menu entry to change the time
intervals at which alarms go off. The fac-
tory settings cause alarms to be triggered
fifteen minutes before each appointment, and
then once every five minutes until the
appointment actually starts. This menu
entry changes the default alarm behavior for
all appointments. You can override this
default behavior on an appointment-by-
appointment basis by selecting an appoint-
ment and then selecting the Change Alarms
entry in the item menu.
Default Listings
This menu can be used to select the default
listing behavior for newly created items.
If the On Occurrence entry is selected, then
a newly created item will only be shown in
the listing of the day on which the item
occurs. If the A Day Early entry is
selected, then a new item will be shown in
listings starting a day before the item
occurrence. Similarly, the other menu
entries can be selected to make new items
show up in listings a number of days before
their actual occurrence. This menu selects
the default behavior for new items. Indi-
vidual item behavior can be controlled by
similar entries in the Item menu.
Help Menu
About Ical
Displays ical version number and author
information.
User Guide
Displays this document.
AUTHOR
Sanjay Ghemawat sanjay@pa.dec.com
http://www.research.digital.com/SRC/personal/Sanjay_Ghe-
mawat/home.html
COPYRIGHT
Copyright (c) 1993 by Sanjay Ghemawat. Permission is
granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission
notice are preserved on all copies.
SEE ALSO
Ical http://www.research.digital.com/SRC/personal/San-
jay_Ghemawat/ical/home.html