path: root/Master/texmf-dist/doc/latex/calendar/calguide.tex

%\iffalse
%
% file: calman.tex
% Copyright (C) 1996-1997 by Frank Bennett.  All rights reserved.
%
%\fi
\documentclass[a4paper]{article}
\usepackage{float}
\def\fileversion{3.1}
\def\filedate{1998/01/17 17:11:27}
\DeclareRobustCommand\cs[1]{\texttt{\char`\\#1}}
\begin{document}

\title{User's Guide to the \LaTeX{} Calendar 
   Bundle\thanks{This file is version number
   \fileversion{}.  It was last revised on
   \filedate{}.}}

\author{Frank G. Bennett, Jr.}

\maketitle
\thispagestyle{empty}

\tableofcontents
\newpage

\setcounter{page}{1}

\section*{Preface}

Welcome to the \LaTeX{} Calendar bundle.  This bundle will
produce calendars in a variety of formats, in any language
supported by \LaTeXe, simply, quickly, and with enough
flexibility to make the little ``personal calendars'' that ship
with Windows~95 and the like beg for mercy.  It just might be the 
only calendaring system you need.

This manual explains how to use it.

\section{System Preparation}

The first thing you must do is be sure that you have all of the
necessary tools to hand.  Before using the styles in the \LaTeX{}
calendar package, you should first check that your \LaTeX{}
installation includes all of the utilities in the
\texttt{graphics} subdirectory under \texttt{packages} in the
main \LaTeXe{} distribution directory on CTAN, and the
\texttt{longtable} and the \texttt{multicol} packages from the
\texttt{tools} subdirectory of \texttt{packages}.  You will also
need everything in the \texttt{calendar} package itself. With
these items in hand, the package should function smoothly in
accordance with the documentation given here and in the
individual \texttt{*.dtx} files.  If you have problems, please
contact me on \texttt{bennett@nomolog.nagoya-u.ac.jp}.

\section{Creating Calendars}

There are nine calendar styles in the bundle.  The simplest
possible document for each is shown in Figure~1.  It is worth
spending a little time studying these examples to see what the
essential elements are, and what can vary from one style to
another.  Some are packages, invoked through the \cs{usepackage}
tag.  Others are classes, invoked via the \cs{documentclass} tag
at the top of the document.  In either case, the calendar itself
takes the form of a \LaTeX{} environment.  The name of this
environment sometimes differs from the name given to
\cs{usepackage} or \cs{documentclass}, because the operating
system on which the largest software company in the world was
built cannot cope with more than eight characters in a file name.

\newlength\myboxAwidth
\newlength\myboxAheight
\def\myeg#1#2#3#4#5#6{%
\fbox{%
\vbox to\myboxAheight{%
\hbox to\myboxAwidth{\cs{documentclass\{#1\}}\hfill}
\hbox to\myboxAwidth{%
  \ifcat$#2$\else\cs{usepackage\{#2\}}\fi%
\hfill}
\hbox to\myboxAwidth{\cs{begin\{document\}}\hfill}
\hbox to\myboxAwidth{\cs{begin\{#3\}}\hfill}
\hbox to\myboxAwidth{\texttt{\{#4\}}\hfill}
\hbox to\myboxAwidth{\texttt{\{#5\}}\hfill}
\hbox to\myboxAwidth{\space\space \texttt{#6}\hfill}
\hbox to\myboxAwidth{\cs{end\{#3\}}\hfill}\vfill}}}

\floatstyle{plain}
\restylefloat{figure}

\begin{figure}[tbp]
\def\{{\char`\{}
\def\}{\char`\}}
\fboxsep=2pt
\fboxrule=0.4pt
\myboxAwidth=119.4pt
\myboxAheight=3cm
\small
\hbox to\textwidth{\hfill\myeg{article}{timesht}{timesheet}{}{}{Jan 1 1997}\hskip10pt%
      \myeg{weekly}{}{weekly}{}{}{Jan 1 1997}\hfill}
\vskip10pt
\hbox to\textwidth{\hfill\myeg{monthly}{}{monthly}{}{}{Jan 1 1997}\hskip10pt%
      \myeg{article}{yearly}{yearly}{}{}{Jan 1 1997}\hfill}
\vskip10pt
\hbox to\textwidth{\hfill\myeg{article}{evntlist}{eventlist}{}{}{Jan 1 1997}\hskip10pt%
      \myeg{timetabl}{}{timetable}{}{}{Jan 1 1997}\hfill}
\vskip10pt
\hbox to\textwidth{\hfill\myeg{article}{hmonth}{htmlmonth}{}{}{Jan 1 1997}\hskip10pt%
      \myeg{article}{hlist}{htmllist}{}{}{Jan 1 1997}\hfill}
\vskip10pt
\hbox to\textwidth{\hfill\myeg{article}{hml}{htmlmonthlist}{}{}{Jan 1 1997}\hskip10pt%
  \hskip\fboxsep\hskip\fboxsep\hskip\fboxrule\hskip\fboxrule
  \hskip\myboxAwidth\hfill}
\caption{Minimal documents for each calendar style}
\end{figure}

There are \textit{always} two extra arguments after the
\cs{begin} tag that opens the environment.  The first extra
argument contains formatting instructions and other options that
modify the behavior of the style.  We will refer to these as
\textit{calendar options}.  A few calendar options are common to
all calendar styles, while others are specific to a particular
style.  In the examples, the first extra argument is always empty
because (get ready for this one) calendar options are optional.
A full explanation of all calendar options for all styles is
given in section \ref{options} below.

The second extra argument gives names of data files containing
lists of events or appointments, together with the names of any
colors to be associated with the entries in each data file.  In
the examples, this second argument is blank because a calendar
can be created without including any events or appointments.  See
section \ref{lists} below for a discussion of how to manage data
lists and include them in calendars.

The only other component of a complete calendar is a
\textit{controlling date} or a \textit{controlling range} of
dates.  As you can see from the examples, this is the only thing
written inside the environment, and it is written in a
human-readable form.  The bundle is pretty forgiving in the way
it reads dates; the elements of a simple date can be written in
any order (that is to say, \texttt{Aug 1 1997}, \texttt{1 Aug
  1997} and \texttt{1997 Aug 1} will all work equally well).
Only the first three letters of the month are read, but any extra
characters are quietly ignored (so you can say \texttt{August 1
  1997} instead of \texttt{Aug 1 1997}).  And the first character
of the month can be either upper-case or lower-case (so \texttt{1
  aug 1997} is okay too).

The finished calendar will be composed so that it includes the
controlling date.  This may be expressed as a \textit{range}
rather than, as in the examples, a \textit{pinpoint date}.  A
range is simply two pinpoint dates separated by the word
\texttt{to}.  If a range is used (for example, \texttt{jan 1 1997 
  to 1 august 1997}), the finished calendar will be composed so
that it includes both the starting and the ending date of the
controlling range.

We have now completed an overview of how calendars are written.
All that remains is to examine (a) how data files are written and
included in documents (see section \ref{lists} below), and (b)
what options are available to modify the behavior of each of the
styles (see section \ref{options} below).

\section{Data Files}\label{lists}

\floatstyle{boxed}
\restylefloat{figure}

Most commercial calendars come with pre-printed notes of the
major holidays and other significant events.  Calendars created
with the \LaTeX{} Calendar Bundle can contain pre-printed notes
of any events or appontments that you like.  Events or
appointments are incorporated into a calendar from separate files
that have the extension \texttt{.cld}.  The names of the files,
less the extension, should be listed, separated by commas and
without spaces, in the second argument to the calendar
environment, as show in Figure~2.  In the next section, we will
examine the content of the data files themselves.

\begin{figure}[bh]
\begin{verbatim}
\documentclass{weekly}
\begin{document}
\begin{weekly}{}{firstlist,secondlist}
  Jan 1 1997
\end{weekly}
\end{document}
\end{verbatim}
\caption{Data file names}
\end{figure}

\subsection{Pinpoint Date Syntax}

The simplest type of \texttt{.cld} file is a list of dates, each
followed by a note in curly braces.  Such a file is shown in
Figure~3.  The month is specified as a word (the first three
letters of which will be recognized), the day as an integer
between \texttt{1} and \texttt{31}, and the year as a four-digit
integer.  The items may come in any order, and the first letter
of the word may be in upper or lower case.
  
\begin{figure}[bht]
\begin{verbatim}
  Jan 1 1997 {New Year's Day}
  Jan 1 1997 {The Day After New Year's Day}
\end{verbatim}
\caption{Simple pinpoint entries}
\end{figure}
  
The text given in curly braces should be a brief note describing
the event or appointment.  This can be followed by a longer note
in square braces.  Styles will use this longer text where
appropriate and physically possible.  An example is given in
Figure~4.

\begin{figure}[bht]
\begin{verbatim}
 jan 1 1997 10:00-11:30 {Smith}
   [Smith: \textit{Reflections on Principle in the work
    of Ambrose Bierce}]
\end{verbatim}
\caption{Verbose description in square braces}
\end{figure}

Finally, a time or a range of times may be added to pinpoint
entries.  In this manual, I refer to entries that do not specify
a time as ``events'', and to those that do specify a time as
``appointments'', but there is no other difference between the
two.  They may be intermixed within a single \texttt{.cld} file,
and in any order.  There should be no space in the time string.
See Figure~5 for an example of what appointment entries look like.

\begin{figure}[ht]
\begin{verbatim}
 jan 1 1997 8:00 {Happy New Year}
  [Take stock of New Year hangover and damage to home
   and hearth]
 jan 1 1997 10:00-16:00 {New Year cleaning}
\end{verbatim}
\caption{Appointment entries}
\end{figure}

\subsection{Recursive Date Syntax}

Some events happen repeatedly.  Birthdays happen every year.
Classes happen every week during school terms except on holidays.
Phases of the moon recur.  It is not very efficient to use
repeated pinpoint entries for such events, so the \LaTeX{}
Calendar Bundle allows you to write such dates descriptively.
This manual refers to dates defined in this way as
\textit{recursive} dates.

\begin{figure}[H]
\begin{verbatim}
% file: class.cld
% The schedule for my Spanish class
range curyear {Current year}
every thurs {Spanish class}
\end{verbatim}
\caption{\texttt{class.cld}}
\end{figure}

\begin{figure}[H]
\begin{verbatim}
% file: curyear.cld
% A range including all dates in the current year
January 1 1997 to December 31 1997 {The year}
\end{verbatim}
\caption{\texttt{curyear.cld}}
\end{figure}

Figures~6 and 7 show the content of two \texttt{.cld} files, which
together define a simple recursive date.  The file
\texttt{class.cld}, shown in Figure~6, will produce a note saying
``Spanish class'' for every Thursday within the range
given in the file \texttt{curyear.cld}.  It is worth pausing for
a few moments to study how these two files are constructed.

Note that the \texttt{range} declaration takes a filename (less
the \texttt{.cld} extension), followed by a comment in curly
braces.  The comment will not be printed in the calendar output,
so the braces can be left empty if desired.  The file called by
the \texttt{range} declaration should contain one or more ranges,
each of which is composed of a starting and an ending date
separated by the word \texttt{to}.  Each range should be ended
with a comment (possibly, as in the example, an empty comment) in
matched curly braces.\footnote{The starting date may also be
  followed by a comment in curly braces.  It is often useful to
  associate a comment with the starting and ending dates of a
  range.  See Figure~11 and the discussion at the end of this
  section.}

The recursive date itself always begins with the word
\texttt{every}, followed by a description of conditions to be
repeated throughout the range.  Figure~8 gives examples of all of 
the conditions that can be specified.  The only entry that is not 
self-explanatory, I think, is the \texttt{every third} (or
\texttt{first}, or \texttt{second}) \texttt{Tuesday} example.
This puts an entry on the \texttt{n}\textit{th} day of the
specified week of the month throughout the specified range.  Note 
also that times can be specified for all recursive entries (that
is to say, you can specify recursive appointments as well as
recursive events).

\begin{figure}[bht]
\begin{verbatim}
 every day          {Rejoice if you can}
 every day 8:00     {Wake up}
 every 20           {Payday}
 every 20  12:00    {Buy big lunch}
 every 1 April      {All Fools Day}
 every 1 april 8:00 {Practical joke time!}
 every third tuesday          {Village council}
 every third monday 2:00-3:00 {That appointment}
 every Tuesday 3:00-4:00 {Aerobics}
 every Tuesday           {Happy Tuesday!}
 every other week from 12 dec 1997       {Kite flying}
 every other week from 12 dec 1997 17:00 {Repair kite}
\end{verbatim}
\caption{Examples of all possible recursive entry types}
\end{figure}

There is one common situation with which the simple recursive
date illustrated in Figures~6 and 7 cannot cope.  Suppose I want
to define a recursive date that will put an entry in my diary for
classes that I teach on a regular basis.  I might try to do this
using an entry like that in Figure~9.

\begin{figure}[bht]
\begin{verbatim}
range schoolterms {Terms}
every Tuesday 10:00-12:00 {Jse Lec}
  [Japanese Law lecture]
every Tuesday 13:00-14:00 {Prop Tut}
  [Property Law tutorial]
\end{verbatim}
  \caption{First attempt to record my teaching dates}
\end{figure}

The problem is that the simple ranges recorded in
\texttt{schoolterms.cld} will not account for holidays, and I do
not plan to teach classes during holidays.  To cope with this
little difficulty, the \LaTeX{} Calendar Bundle provides the
\texttt{holiday} declaration.  As you can see in Figure~10, the
syntax of this declaration is the same as that of the
\texttt{range} declaration.  The separate file
\texttt{ukhols.cld} should contain a list of pinpoint dates which
are to be excluded when recursive dates are calculated.

\begin{figure}[bht]
\begin{verbatim}
range schoolterms {Terms}
holiday ukhols    {United Kingdom holidays}
every Tuesday 10:00-12:00 {Jse Lec}
  [Japanese Law lecture]
every Tuesday 13:00-14:00 {Prop Tut}
  [Property Law tutorial]
\end{verbatim}
  \caption{A better attempt to record my teaching dates}
\end{figure}

The text enclosed in curly braces that follows a \texttt{range}
or \texttt{holiday} declaration (see Figures~6, 9 and 10), and
the comments in curly braces inside the \texttt{.cld} files
called by these declarations (see Figure~7) will not appear in
the text of printed calendars.  Sometimes it is \textit{useful}
to print a note of the beginning and ending dates of a range, or
the dates of holidays.  In this case, the file containing the
relevant range (which should have notes associated with the
starting an ending dates) should be named in the second argument
to the calendar environment, as a normal input file.  Figure~11
gives an example of a fully-commented range file.

\begin{figure}[bht]
\begin{verbatim}
% file: ug-current.cld
17 sep 1997     {First SOAS term begins}
 to 12 dec 1997 {First SOAS term ends}
5 jan 1998      {Second SOAS term begins}
 to 20 mar 1998 {Second SOAS term ends}
20 apr 1998     {Third SOAS term begins}
to 5 jun 1998   {Third SOAS term ends}
\end{verbatim}
  \caption{Ranges with comments}
\end{figure}

\subsection{Color Support}

You can make calendars that are more informative and easier to
read by printing entries of different types in different colors.
To do this, you must first include color support by calling the
\texttt{color} package.  If the color package has not been
configured for your system, you may need to tell it about your
driver.  If you use \texttt{dvips}, it is handy to use named
colors and the pallette of colors provided by the
\texttt{dvipsnames} option.  See the documentation to the
\texttt{graphics} package for further details.

\begin{figure}[bht]
\begin{verbatim}
\documentclass{weekly}
\usepackage[dvips,usenames,dvipsnames]{color}
\begin{document}
\end{verbatim}
  \caption{A header that invokes color support}
\end{figure}

Once color support is in place (and you have a color printer to
hand), you can associate a color with the entries in a data file
by putting a colon after the name of the file, followed by the
name of the color in which you want its entries to appear.  See
the documentation to the \texttt{graphics} package for further
information on what color names are available.

\begin{figure}[bht]
\begin{verbatim}
\documentclass{weekly}
\begin{document}
\begin{weekly}{}{firstlist:red,secondlist:blue}
  Jan 1 1997
\end{weekly}
\end{document}
\end{verbatim}
\caption{Data file names}
\end{figure}

\subsection{Freezing Data}

A price must be paid for the very friendly syntax of the data
files used by the \LaTeX{} Calendar bundle; when large amounts of
data are involved, it can take a significant amount of time to
process a calendar.  The \texttt{freeze} declaration provides a
means of speeding things up.  To freeze the data in a file, put
the declaration \texttt{freeze} (without any following curly
braces) immediately after any range or holiday specifications.
All subsequent dates generated by the file will be captured in a
pre-processed form to a file with the same name, but with the
extension \texttt{.eve}.  The next time a style from the \LaTeX{}
Calendar bundle reads that file, the pre-processed \texttt{.eve}
file will be read instead of the \texttt{.cld} file.

\begin{figure}[bht]
\begin{verbatim}
 range year {Current year}
 freeze
 every second thursday {Working group}
\end{verbatim}
\caption{An example of the \texttt{freeze} declaration}
\end{figure}

\subsection{Composite Lists}

Large or complex data sets can be easier to manage if the data is
broken down into small chunks.  The \LaTeX{} Calendar bundle
facilitates this through the \texttt{list} declaration, which
allows one \texttt{.cld} file to incorporate another by
reference.  The file called by \texttt{list} may include either
pinpoint or recursive dates.  This can be used to create a file
representing an entire category of entries.  Figure~15 shows the
content of a file that I used to represent all of the
undergraduate lectures in a university law department in London.

\begin{figure}[bht]
\begin{verbatim}
list ug-cinl-lecture {}
list ug-cinl-lecture {}
list ug-conflicts-lecture {}
list ug-criminal-lecture {}
list ug-csel-lecture {}
list ug-eml-lecture {}
list ug-equity-lecture {}
list ug-essay-lecture {}
list ug-family-lecture {}
list ug-hr-lecture {}
list ug-iel-lecture {}
list ug-islam-lecture {}
list ug-jsel-lecture {}
list ug-ld-lecture {}
list ug-ld-lecture {}
list ug-lsaa-lecture {}
list ug-lssa-lecture {}
list ug-obs1-lecture {}
list ug-obs2-lecture {}
list ug-pil-lecture {}
list ug-property-lecture {}
list ug-public-lecture {}
\end{verbatim}
  \caption{\texttt{ug-lectures.cld}}
\end{figure}

A nice feature of the \texttt{list} declaration is that the color
associated with the ``top'' file is inherited by files called
from it using \texttt{list}.  When dealing with large or complex
data sets, this is a Really Nice Feature.  Note, however, that
the \texttt{freeze} declaration will \textit{not} export any data
contained in files referenced using \texttt{list}.  The
\texttt{freeze} declaration should therefore be used
\textit{only} in files that do \textit{not} contain any
\texttt{list} declarations.

If your operating system can cope with long filenames, see the
\texttt{tar} archive file \texttt{bigdemo.tgz} in the
\texttt{calendar} subdirectory on CTAN for a complete working
data set that relies on the \texttt{list} declaration to organize
things in this way.

\subsection{Language Support}

The \LaTeX{} Calendar bundle can be quickly configured to support
any language that \LaTeX{} is capable of handling.  By default,
calendars are produced using English names of the month and names
of days of the week.  It can also support \textit{multiple}
languages in each of the \texttt{*.cld} files on your system, and
produce the same calendar with month and day names \textit{and}
the entry texts in alternative languages.

The language configuration of the \LaTeX{} Calendar bundle is
contained in the file \texttt{dates.cfg}.  The sample file that
ships with the bundle has the following contents:

\bgroup\small
\begin{verbatim}
\DeclareCalendarLanguage{English}
 {{Sunday}{Monday}{Tuesday}{Wednesday}{Thursday}{Friday}{Saturday}}
 {{Sun}{Mon}{Tue}{Wed}{Thu}{Fri}{Sat}}
 {{January}{February}{March}{April}{May}{June}{July}{August}{September}
  {October}{November}{December}}
 {{Jan}{Feb}{Mar}{Apr}{May}{Jun}{Jul}{Aug}{Sep}{Oct}{Nov}{Dec}}

\DeclareCalendarLanguage{German}
  {{Sonntag}{Montag}{Dienstag}{Mittwoch}{Donnerstag}{Freitag}{Samstag}}
  {{So}{Mo}{Di}{Mi}{Do}{Fr}{Sa}}
  {{Januar}{Februar}{M\"arz}{April}{Mai}{Juni}{Juli}{August}{September}%
    {Oktober}{November}{Dezember}}
  {{Jan}{Feb}{M\"arz}{Apr}{Mai}{Juni}{Juli}{Aug}{Sep}{Okt}{Nov}{Dez}} 
\end{verbatim}
\egroup

These entries serve two purposes.  First, they define the texts
that should be use for long and short names of the days of the
week and the months for each of the language options that they
declare.  Second, the \textit{order} of options determines the
order of alternative language entries in your \texttt{*.cld}
files.  In the example above, \texttt{English} is the default
language, but \texttt{German} can be specified as an option in
your documents, by giving that as a class or package option to
the calendar style you are using.  You can declare as many
languages in your \texttt{dates.cfg} file as you like.

Once you have edited the \texttt{dates.cfg} file to your
satisfaction, and put the languages into the correct order for
your needs, you are ready to add multi-lingual \texttt{*.cld}
to your files.  The first thing to note is that alternative
languages are always \textit{optional}.  If we are using the
sample \texttt{dates.cfg} file above, and the \texttt{*.cld} file 
contains only default entries in English, the English entries
will be supplied.  Nothing will break as a result of specifying
an alternative language that has been declared; they are
perfectly safe.

Again following the example configuration file above, a German
entry can be added to a file by using angle braces instead of
curly braces for its short text.  Square braces (for a long text)
work exactly as they do after the default, curly-brace text:

\begin{verbatim}
jan 1 1998 {New Year}
           <Neue Yahr>
\end{verbatim}

\begin{verbatim}
jan 1 1998 21:00 {New Year's Party} [New Year's Party at Fred's house.]
                 <Neue Yahr>        []
\end{verbatim}

\subsection{Rotating Text}

Two of the style packages (\texttt{weekly} and \texttt{timetabl})
need to be able to twist text sideways before it is printed.
Internally, they use the special facilities of the
\texttt{graphics} bundle for this purpose.  You may want to turn
other calendars (such as the \texttt{monthly} calendar, for
example) sideways in order to make better use of the space on a
page.  To get full use out of this package, it is therefore
important that you have the the \texttt{graphics} bundle
installed on your system, and that your print driver be one that
is capable of rotating text.  I don't have access to most of the
devices supported by the \texttt{graphics} package, but from the
code in the package it looks as though only the following drivers
support rotation: \texttt{dvips}, \texttt{dvipsone},
\texttt{dvitops}, \texttt{pctex32}, \texttt{pctexps},
\texttt{pubps}, \texttt{textures}.

Note that the \texttt{graphics} bundle must also be
\textit{configured} properly for your system.  In essence, this
means that the files in the bundle must be told what driver you
are using, via a file called \texttt{graphics.cfg}.  If you have
problems, please see the documentation in the file
\texttt{grfguide.tex}, shipped with the \texttt{graphics} bundle.

To rotate an entire calendar (such as \texttt{monthly}), use the
\texttt{lscape} package, and enclose the calendar tags in
\texttt{landscape} tags:

\begin{verbatim}
\documentclass{article}
\usepackage{monthly}
\usepackage{lscape}
\begin{landscape}
\begin{monthly}{}{}
  january 1 1998
\end{monthly}
\end{landscape}
\end{verbatim}

\subsection{Arbitrary Formul\ae}

Finally, it is possible to specify recursive dates using an
arbitrary formula, using the \texttt{function} declaration in a
\texttt{.cld} file.  The use of the \texttt{function} declaration
is beyond the scope of this manual, but interested designers
might want to take a look at the documentation contained in
\texttt{dates.dtx} for a discussion of this declaration, and an
example that generates a note of the phases of the moon.

\section{Calendar, Class and Package Options}

\label{options}
In this section, all of the options to all of the styles are
explained.  ``Options'' come in two flavors.  One is accepted by
the calendar package or class that makes a given calendar
environment available.  Such options are fed to the
\cs{usepackage} or \cs{documentclass} commands in the
conventional way, through a square-braced argument.  These are
referred to here as \textit{class or package options}.  The
second type of option is given in the second argument to the
calendar environment itself, and are referred to here as
\textit{calendar options}.\footnote{Calendar options are
  processed using the \texttt{keyval} package.  See the
  documentation of that package if you would like more detailed
  information about how these work.} Calendar options are given
as a comma-delimited list.  \textit{Boolean} calendar options
take effect when they appear by themselves in the argument text.
\textit{Variable} calendar options must be followed by an equal
sign and some value, possibly in curly braces.  Figure~16 gives
examples of each type.  To conclude our explanatory tour, we will
examine the options recognized by each style in the bundle.  If
you would like to see samples of any of the styles, please
extract and print the appropriate demo file from the
distribution.

\begin{figure}[bht]
\begin{verbatim}
\documentclass{timetabl}
\begin{document}
\begin{timetable}
  {notimes,
   title={Law Department Timetable},
   labels={Monday,Tuesday,Wednesday,Thursday,Friday},
   start=9:00,
   end=21:00,
   blockminutes=60}
  {}
  Jan 5 1997 to Jan 9 1997
\end{timetable}
\end{document}
\end{verbatim}
  \caption{Examples of boolean and variable options}
\end{figure}

\subsection{Timesheets}

The timesheet style produces a timesheet for every date in the
controlling range.  Timesheets have a column of time blocks
marked out on the left side of the page, a list of appointments
(if any) to the right of that, and a blank area for recording
actions taken (or doodling pictures) on the far right of the
page.

\subsubsection{Package Options}

This style is provided as a package.  Its only options are
language options declared in \texttt{dates.cfg}.

\subsubsection{Calendar Options}

The following formatting options are supported by the
\texttt{timesheet} environment:

\begin{description}
\item[\texttt{title}] The string fed to this option will form the
  title of the timesheet.  Robust commands (like \cs{LaTeXe})
  should be safe here.  The default string is \texttt{Timesheet}.
\item[\texttt{leftright}] This option can be used to alter the
  proportion of space taken up by the right and left columns.
  The syntax is a pair of integers separated by a slash.  The
  default value is \texttt{1/1}, for evenly spaced columns.  The
  values express a ratio, so you do not need to make the values
  add up to anything in particular.
\item[\texttt{start}] This is the starting time of the timesheet.
  The format is colon-delimited 24-hour time (i.e.~\texttt{17:00}
  for five o'clock in the afternoon).  The default starting time
  is \texttt{8:00}.
\item[\texttt{end}] Like \texttt{start}, but specifies an ending
  time for the timesheet.  The default ending time is
  \texttt{17:00}.
\item[\texttt{blockminutes}] If you want the timesheet to be
  split into time blocks of equal duration, you can use this
  option to select the length of the blocks in minutes.  This
  must divide evenly (without a remainder) into the span of time
  specified by the start and end of the timesheet.  The default
  value of this option is \texttt{15}, for fifteen-minute blocks.
\item[\texttt{blockgroup}] A line will be drawn all the way
  across the timesheet at the end of every group of time blocks.
  The number of blocks in a group can be set using this option.
  The default is \texttt{4}, which puts a line at every hour
  boundary with the default value of \texttt{blockminutes}.
\item[\texttt{width}] If you don't want the timesheet to fill the
  whole width of the page, you can use this option to specify a
  smaller size.  The feedback given when the style is run gives
  you the size in points for that run of \LaTeX, which may be
  useful in making formatting adjustments.
\item[\texttt{leftspace}] This can be used to specify an explicit
  left-offset value.  The default is \cs{fill}.
\item[\texttt{rightspace}] Like \texttt{leftspace}, but for the
  right side of the timesheet.  The default is \cs{fill}, for a
  centred table.
\item[\texttt{titletype}] This sets the default typeface for the
 overall title of the timesheet.
\item[\texttt{labeltype}] This sets the default typeface for the
 labels (Plan and Action) at the top of the sheet.
\item[\texttt{timelabeltype}] This sets the default typeface for the
 time markings on the lefthand side of the page.
\item[\texttt{timeitemtype}] This sets the default typeface for the
 times associated with appointments.
\item[\texttt{itemtype}] This sets the default typeface for the
 item text itself.
\end{description}

\subsection{Weekly}

The \texttt{weekly} style prints weekly calendars for use with a
Filofax(tm) or other personal planner.  Pages are framed with
cut-lines, and punch-marks show where to cut holes at the edge of
the page.  For each date, the style initially attempts to set the
event and date text as a single column.  If the text overflows
the box for that date, the style will attempt to recover by
resetting the text as two columns.

\subsubsection{Class Options}

This style is provided as a \LaTeX{} class file.  It has the
following special features and limitations:

\begin{itemize}
\item The text of the calendar is always rotated, using the
  \texttt{lscape} package from the \texttt{graphics} bundle.  As
  a result, calendars generated using this package can only be
  printed using \texttt{dvips} or other PostScript(TM) print
  drivers supported by the \texttt{graphics} bundle.
\item If the \texttt{graphics} bundle has not been configured for
  your system, you can specify the driver and other options for
  its use by giving \LaTeX{} options to the class when it is
  loaded.
\item While the paper size can be specified using options like
  \texttt{a4paper}, this will have no effect; the actual paper
  size is governed by calendar options.
\item Documents created with this style should contain nothing
  other than a calendar environment.
\end{itemize}

\subsubsection{Calendar Options}

The following formatting options are supported by the
\texttt{weekly} environment:

\begin{description}
\item[\texttt{firstday}] This is the starting day of the
  calendar, expressed as an integer. Friday (the default) is
  ``\texttt{5}''.
\item[\texttt{punchcluster}] Most filofaxes have two or or more
  clusters or groups of punches to hold the pages in place.  This
  option sets the number of punches in each cluster.  The default
  is three.
\item[\texttt{intraspace}] This governs the space between
  punchouts within a group.  The default is 19.25mm.
\item[\texttt{punchgroups}] This option sets the number of groups
  of punches.  The default is two groups.
\item[\texttt{interspace}] This option sets the distance between
  the groups of punches.  The default is 51.25mm.
\item[\texttt{pageheight}] This fixes the height of a filofax
  page (not the physical paper on which it is printed).  The
  default is 172mm.
\item[\texttt{pagewidth}] This fixes the width of an individual
  page.  The physical printed area will be twice this figure.
  The default is 95mm, for a 190mm printed area.
\item[\texttt{grip}] This adjusts the distance from the edge of
  the page to the outer edge of the punchouts.  Default is 5mm.
\item[\texttt{punchmargin}] This adjusts the distance from the
  edge of the text to the inner edge of the punchouts.  Default
  is 2mm.
\item[\texttt{punchsize}] Size, in points, of punchouts.  Default
  is 15.
\item[\texttt{topspace}] Gap between top of filofax page and top
  of text page.
\item[\texttt{bottomspace}] Gap between bottom of filofax page
  and bottom of text page.
\item[\texttt{jawspread}] If set to a positive length, this
  places a set of rules the width of the punchmarks on either
  side of each punchhole, centered on its center and spread the
  distance specified.  This can be useful as a guide with some
  one-hole punches that are designed to be used ``blind''.
\item[\texttt{jawline}] Sets the width of the lines used to make
  jawmarks.  Default value is \texttt{0.4pt}.
\end{description}

\subsection{Monthly}

The \texttt{monthly} style produces a simple monthly calendar,
similar to the ones you can buy in shops.  The \LaTeX{} Calendar
version does not include cartoons by Gary Larson or pictures of
the latest fave rave teen band (at least by default), but you do
have access to all of the goodies available in the other packages
in the bundle (color coding, et cetera).  Ordinarily you will
want to print this using the \texttt{lscape} package and its
\texttt{landscape} environment.

\subsubsection{Package Options}

This style is provided as a package.  It only recognizes language
options declared in \texttt{dates.cfg}.

\subsubsection{Calendar Options}

\begin{description}
\item[\texttt{title}] The string fed to this option will form the
  title of the calendar.  Robust commands (like ``\LaTeXe'')
  should be safe here.  The default is the name of the month,
  followed by the year.
\item[\texttt{labels}] This is an optional comma-delimited,
  brace-enclosed string giving a list of seven labels to be used
  for days of the week.  This was once used to make calendars in
  languages other than English.
\item[\texttt{firstday}] This is the starting day of the
  calendar, expressed as an integer. Sunday (the default) is
  ``0''.
\item[\texttt{titletype}] This sets the typeface for the
title.  The default is \cs{large}\cs{bfseries}.
\item[\texttt{daynametype}] This sets the typeface for the
 day-name labels.  The default is \cs{bfseries}.
\item[\texttt{datetype}] This sets the default typeface for
 the day in each box.  The default is \cs{bfseries}.
\item[\texttt{texttype}] This sets the default typeface for
 the entry texts.  The default is \cs{tiny}.
\end{description}

\subsection{Yearly}

This produces a simple yearly calendar.  It was the first of the
Calendar style packages to be written, and in some ways it is the 
most unsatisfactory; I invite others to use this style as a model 
and improve on it.  But for workaday needs --- to produce a
simple one-year calendar on a single piece of paper --- it works
well enough.

\subsubsection{Class or Package Options}

This is distributed as a package.  

\subsubsection{Calendar Options}

The following options are recognized by the \texttt{yearly} style:

\begin{description}
\item[\texttt{title}] The string fed to this option will
 form the title of the calendar.  Robust commands (like
 ``\LaTeXe'') should be safe here.  The default is
 the number of the year.
\item[\texttt{labels}] This is an optional comma-delimited,
 brace-enclosed string giving a list of seven labels to
 be used for days of the week.  This can be used to
 make a calendar in a language other than English or German.
\item[\texttt{firstday}] This is the starting day of the
 calendar, expressed as an integer. Sunday (the
default) is ``0''.
\end{description}

\subsection{Timetable}

This package organizes date items in a format suitable for
conference schedules, itineraries, academic teaching timetables
and the like.  It is a versatile package, worth playing around
with if you want to use this bundle in an institutional context.

\subsubsection{Package Options}

This style is provided as a package.  Its only options are
language options declared in \texttt{dates.cfg}.

\subsubsection{Calendar Options}

The options valid for use with the \texttt{timetable} environment
are:

\begin{description}
\item[\texttt{leftspace}] Amount of space to the left of the
 table (default is \cs{hfill}, but with table sized to exactly
fit the margins).
\item[\texttt{rightspace}] Amount of space to the right of the
 table (default is \cs{hfill}, but with table sized to exactly
fit the margins).
\item[\texttt{width}] Width of the table.  The default is
\cs{textwidth}.
\item[\texttt{title}] The string fed to this option will
 form the title of the timetable.  Robust commands (like
 ``\LaTeXe'') should be safe here.  The default is
 ``Conference Schedule''.
\item[\texttt{notimes}] If this option is given, the
time of each item is not given in the body of the
timetable.  If all entries begin and end exactly on
the boundaries arrived at by applying \texttt{blockminutes}
to the range of the table, no information is lost, and the
table will have a cleaner appearance and be easier to read.
\item[\texttt{start}] Time from which schedule should
 begin, with hours and minutes separated by a colon.
 The default is \texttt{8:00}.
\item[\texttt{end}] Time at which the schedule should
 end.  The default is \texttt{17:00}.
\item[\texttt{blockminutes}] The number of minutes in
 each time block.  This should divide \textit{evenly}
 into the total number of minutes within the range specified
 by \texttt{start} and \texttt{end}.  The default is 60.
\item[\texttt{blocks}] As an alternative to
\texttt{blockminutes},
 you can specify the precise periods of time you want
included in each time block.  The format is a set of
comma-delimited time ranges, all
enclosed in a pair of matching braces.  For
example:
\begin{quote}
 \verb+blocks={8:00-9:00,9:00-10:00,4:00-5:00}+
\end{quote}
\item[\texttt{labels}] This is an optional comma-delimited,
 brace-enclosed string giving a list of labels to
 be used for the day headings.
\item[\texttt{titleface}] The typeface used for the title.
\item[\texttt{labelface}] The typeface used for the day labels.
\item[\texttt{timelabelface}] The typeface used for the time
labels on the left edge of the table.
\item[\texttt{timeitemface}] The typeface used for the
 time of each entry (suppressed altogether if the
 \texttt{notimes}
 option is given).
\item[\texttt{itemface}] The typeface used for the entry text.
\end{description}

\subsection{Event List}

This is a simple package that produces a list of events
in cronological order.  It is not particularly elegant,
and users are invited to improve on this model.

\subsubsection{Class or Package Options}

The only options recognized by this package are language options
declared via \texttt{dates.cfg}.

\subsubsection{Calendar Options}

This package does not recognize any calendar options at present.

\subsection{HTML Monthly Calendar}

This package produces a monthly calendar in HTML.  The
calendar does not take advantage of any table features of
HTML, and can be viewed on any browser, including the
Lynx browser for character terminals.

\subsubsection{Class or Package Options}

The only options recognized by this package are language options
declared via \texttt{dates.cfg}.

\subsubsection{Calendar Options}

This package recognizes he following calendar options:

\begin{description}
\item[\texttt{title}] The string fed to this option will form the
  title of the calendar.  The default is the name of the month,
  followed by the year.
\item[\texttt{firstday}] This is the starting day of the
  calendar, expressed as an integer. Sunday (the default) is
  ``0''.
\item[\texttt{outputfile}] This is the name of a file to
  which the HTML output should be written.
\end{description}

\subsection{HTML Event List}

This is a simple package that produces an HTML list of events
in cronological order.

\subsubsection{Class or Package Options}

The only options recognized by this package are language options
declared via \texttt{dates.cfg}.

\subsubsection{Calendar Options}

The only option recognized by this package is
\texttt{outputfile}, which sets the name of the file to which the 
HTML output should be written.

\subsection{HTML Month and Event List}

There are CGI scripts that do the same thing as this script ---
produce one or more monthly calendars, with jump-links on
appropriate days into a list of events.  The difference is that
this style offers multi-lingual support, and could be
made to work with color by a wizard.

\subsubsection{Class or Package Options}

The only options recognized by this package are language options
declared via \texttt{dates.cfg}.

\subsubsection{Calendar Options}

This package recognizes the same calendar options as the
HTML Monthly style.

\end{document}