summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/calendar/calguide.tex
blob: 5950f9fa804255256d5e5a5615615eccd6b6b899 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
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}