Designer’s Guide to the Calendar package^{∗}

Frank G. Bennett, Jr.

January 24, 1998

Abstract

This package provides tools for creating customized calendars using L^{A}TEX 2ε.

1 Overview and Exhortation

Think of this package as the Music Minus One of the scheduling trade. It provides a standard interface for drafting calendars, but leaves you in control of the style and content of the finished product. The calendar style generator included in this package can be used to create simple lists of events, as well as daily, weekly, monthly and yearly calendars in a variety of formats. Calendars can be ground into DVI, or can be exported in an arbitrary list or table formatting language such as HTML, or delimited ASCII text. While the format of calendars is pretty much up to you, all calendars created using the Calendar package inherit a number of useful features, among which are:

• Access to external lists of events and appointments written in a user-friendly syntax.

• Selective printing of long or short descriptions of events and appointments according to the list from which they originate or, in the case of appointments, according to their starting time.

• Built-in recursive entries such as everymonday or EverysecondWednesday, governed by a range.

• An extensible interface within list files for defining calculable dates within a range by reference to a mathematical formula.

• “Stopping” of recursive entries by reference to a list of holidays.

• Colour-coding of lists and groups of lists for the readable presentation of complex schedules. Colours may be associated with individual lists, or with entire groups of lists.

∗This file is version number 3.1.1.1. It was last revised on 1998/01/17 18:14:52.

On top of this, all calendar styles have a uniform user interface. For examples, please see the files included in the styles subdirectory in or near the filespace from which you retrieved this file.

Finally, the Calendar package has the virtue of being chilled, if not yet completely frozen. While there will doubtless be minor bug fixes and enhancements in future releases, this package is intended to be a finished and stable platform on which to build calendar styles. It will not move out from underneath your work. And if you draft a calendar style and publish it on CTAN, others will be able to put it straight to work on their own local lists of events.

************ The documentation to this package explains how to define your own calendar formats. There are many possibilities, but here are a few ideas:

• Web maintainers can provide a current view of upcoming events formatted with a tabular calendar at the top, the dates of which are linked to events for that day.

• Filofax calendars can be produced which contain institutional data and personal appointments on a per-user basis.

• Scheduling conflicts or common free times can be identified by producing concordance calendars that lay the daily schedules of several members of staff alongside one another.

• Timesheets with pre-printed diary entries can be produced.

• Consolidated academic timetables can be produced.

• To simplify the maintenance of lists, a Web site may want to produce a forms interface for the distributed creation and management of lists. This task is greatly simplified by the fact that the syntax for entries is flexible and human-readable.

• Users at a Web site can be given direct control over calendar content, by running L^{A}TEX and dvips from a CGI behind a click-box and radio-button interface.

All of these applications can be supported directly by the package as it stands. All that is required is to define appropriate calendar formats. Classes and packages that define new calendar formats contain only the essential commands which define their structure.

The source of the Calendar package and related files is located in the CTAN archives under:

     macros/latex/contrib/supported/calendar

If you design a new calendar format, please upload it to the CTAN /incoming directory at ftp.tex.ac.uk and send the site maintainers a note (see the file README.uploads for their contact details) asking them to place it in the styles subdirectory of the Calendar package filespace. It is best to send your calendar format as a *.dtx file, with documentation on how to use it (see the existing packages for model documentation). If you design a CGI or other front-end that calls on a style or manages database entries, please send that as well, for placement in the tools subdirectory. That way, anyone interested in using Calendar will find everything that is available in one place, and the utility of the package will be greatly enhanced.

I do not have time at present to write a readable and well-presented guide to the style drafting process. If you want to draft your own style, your best bet is to read through the commentary and code of an existing calendar style, and modify it to suit your needs. Feel free to write me on fb@soas.ac.uk if you have any questions or comments.