diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex/calendar/calguide.tex')
-rw-r--r-- | Master/texmf-dist/doc/latex/calendar/calguide.tex | 1037 |
1 files changed, 1037 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/calendar/calguide.tex b/Master/texmf-dist/doc/latex/calendar/calguide.tex new file mode 100644 index 00000000000..5950f9fa804 --- /dev/null +++ b/Master/texmf-dist/doc/latex/calendar/calguide.tex @@ -0,0 +1,1037 @@ +%\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} + + + + |