ICAL(1)

NAME
ical - X based calendar program

DESCRIPTION
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 particular 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 edited and deleted easily.
    * Items can be cut, copied and pasted.
    * Items can be made to repeat in various ways.
    * Ical will post reminders for upcoming appointments.
    * Ical can print and list item occurrences.
    * An ical calendar can include other calendars.
    * Ical calendars can be shared by different users.

CALENDAR FILE
A calendar is stored in a calendar file. The default calendar 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 - "ical -calendar file-name". Ical periodically saves any modifications made to a calendar to the corresponding calendar file. Changes can be explicitly saved to the calendar file by selecting the Save entry from the Calendar menu. You can discard any un-saved changes made to the calendar by selecting the Re-Read entry from the Calendar menu. The Re-Read entry is also useful for incorporating changes made to a shared calendar by other users. The Exit entry in the Calendar menu saves any changes and then kills the calendar program.

WINDOWS
The main calendar window displays the appointments and notices for a particular date. The top left portion of the window contains a date selector. You can click on the various 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. The bottom left portion of the window contains the notices for the selected date. You can scroll this region by using the scroll bar. 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. A menubar runs along the top of the calendar window. The r menu allows you to create and destroy application windows.

New Window
    Opens a new calendar window. This new window can be used to view the items for a different date than the original window.

Close Window
    Closes the selected window.

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.

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. You can change the length allocated to a notice by dragging with the right mouse button held down.

APPOINTMENTS
You can enter appointments by left-clicking in the background 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 dragging 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 appointment window while it is selected. Ical generates reminders for appointments. By default, the first reminder is generated fifteen minutes before the appointment is supposed to start and successive reminders are generated every five minutes until the appointment actually starts.

REPEATING ITEMS
Items can be made to repeat in various ways. Item repetition can be controlled by using the entries in the Repeat menu. These entries make the item repeat in certain frequently used ways. For example, the Monthly entry makes the selected item repeat once per month. 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 Make First Date or the Make Last Date entry from the Repeat menu. Normally, a modication 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 Edit menu. The selected occurrence can now be modified independently of the repeating item.

CLIPBOARD
The application 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. An item in the clipboard can be inserted into the current day by selecting Paste from the Edit menu. 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 options in the List menu. The command line "ical -list" can be used to generate a similar listing from the shell without opening a window. This is most useful in .login files and on non-X terminals. Alternatively, you can use the command line "ical -show +n" to generate a listing for the next n days without opening a window. "ical -list" has behavior identical to "ical -show +1". An item is included in a listing for a particular date if it occurs either on that date, or on the very next day. Sometimes, you 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 the Ten Days Early entry from the Remind menu. The A Day Early entry restores the default behavior. The On Occurence entry marks the item so that it is only included in the listing for a particular date if it occurs on that date.

PRINTING
All items in a given range can be printed to a postscript printer by selecting one of the entries in the Print menu. The Month entry prints all items for the current month on a single sheet of paper. The other menu entries print all items that occur on the currently selected date, or within the next n - 1 days. For example, if the selected date is April 17, then the Eight Days entry can be used to print all items in the range April 17 to April 24. The postscript code for printing the items is fed to a user-specified filter. The default filter is lpr.

INCLUDING CALENDARS
You can include other calendars into your private calendar. 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. You can include a calendar by selecting the Include Calendar entry from the Calendar menu. You can remove an included calendar by selecting the Remove Calendar entry from the Calendar menu. An item can be moved between calendars by selecting the Move Item To ... entry from the Edit menu. You can list all items in a particular calendar by selecting the From Calendar ... entry from the List menu.

CUSTOMIZATION
You can specify several X resources to customize the appearance and behavior of ical.

  BEHAVIOR

Ical.alarms
    List of minutes before an appointment that alarms should go off. The default is alarms: 0 5 10 15. This default means that alarms go off when the appointment starts, and also 5, 10, and 15 minutes before the appointment starts.

  DIMENSIONS

Ical.apptStartTime
    The time that initially appears at the top of the appointment listing. The format for the time specification is hh:mm. The default value for this resource is 8:00.

Ical.apptLines
    The number of lines that appear in the appointment listing. The default is 20. Each line represents 30 minutes and therefore by default the appointment listing is high enough to display ten hours at a time.

Ical.noteLines
    The height of the notice window in lines. The default is 8.

Ical.itemWidth
    The width of item windows. The width is specified as a floating point number followed by an optional unit specification. If the unit specification is left off, then the units default to screen pixels. Legal unit specifications are c for centimeters, i for inches, m for millimeters, and p for printer points. The default item window width is 3.5i (three and a half inches).

Ical.Dayview.geometry
    X geometry specification for main calendar window. Usually, you will just specify the window position here. The size of the window is easier to specify via Ical.apptLines, Ical.noteLines, and Ical.itemWidth.

Ical.Reminder.geometry
    X geometry specification for item reminders. Usually, you will just specify the window position here. The window size will be calculated automatically.

Ical.Listing.geometry
    X geometry specification for item listings. Usually, you will just specify the window position here. The window size will be calculated automatically.

Ical.vertical
    If this boolean option has the value "1", then the various components of the ical window will be laid out vertically as opposed to the default layout where the appointments are laid out on the right side of the window. The default value for this option is "0".

  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
    Set the colors used for most of the ical windows.

Ical.itemFg

Ical.itemBg
    The foreground and background colors for unselected items. The default foreground is black and the default background is gray.

Ical.itemSelectFg

Ical.itemSelectBg
    The foreground and background colors for selected items. The default foreground is yellow and the default background is blue.

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.

  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.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", "Button", "Label", "Menubutton", "Menu", "Listbox", and "Reminder".

AUTHOR
Sanjay Ghemawat (sanjay@lcs.mit.edu)

COPYRIGHT
Copyright (c) 1991 1992 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.