Debian Codegraph @

texmf-dist/doc/generic/pgf/pgfmanual-en-pgfcalendar.tex

raw
1 % Copyright 2019 by Till Tantau
2 %
3 % This file may be distributed and/or modified
4 %
5 % 1. under the LaTeX Project Public License and/or
6 % 2. under the GNU Free Documentation License.
7 %
8 % See the file doc/generic/pgf/licenses/LICENSE for more details.
9
10
11 \section{Date and Calendar Utility Macros}
12 \label{section-calendar}
13
14 This section describes the package |pgfcalendar|.
15
16 \begin{package}{pgfcalendar}
17 This package can be used independently of \pgfname. It has two purposes:
18 %
19 \begin{enumerate}
20 \item It provides functions for working with dates. Most noticeably, it
21 can convert a date in ISO-standard format (like 1975-12-26) to a
22 so-called Julian day number, which is defined in Wikipedia as
23 follows: ``The Julian day or Julian day number is the (integer)
24 number of days that have elapsed since the initial epoch at noon
25 Universal Time (UT) Monday, January 1, 4713 BC in the proleptic
26 Julian calendar''. The package also provides a function for
27 converting a Julian day number to an ISO-format date.
28
29 Julian day numbers make it very easy to work with days. For
30 example, the date ten days in the future of 2008-02-20 can be
31 computed by converting this date to a Julian day number, adding 10,
32 and then converting it back. Also, the day of week of a given date
33 can be computed by taking the Julian day number modulo~7.
34 \item It provides a macro for typesetting a calendar. This macro is
35 highly configurable and flexible (for example, it can produce both
36 plain text calendars and also complicated \tikzname-based
37 calendars), but most users will not use the macro directly. It is
38 the job of a frontend to provide useful configurations for
39 typesetting calendars based on this command.
40 \end{enumerate}
41 \end{package}
42
43
44 \subsection{Handling Dates}
45
46 \subsubsection{Conversions Between Date Types}
47
48 \begin{command}{\pgfcalendardatetojulian\marg{date}\marg{counter}}
49 This macro converts a date in a format to be described in a moment to the
50 Julian day number in the Gregorian calendar. The \meta{date} should expand
51 to a string of the following form:
52 %
53 \begin{enumerate}
54 \label{calendar-date-format}
55 \item It should start with a number representing the year. Use |\year|
56 for the current year, that is, the year the file is being typeset.
57 \item The year must be followed by a hyphen.
58 \item Next should come a number representing the month. Use |\month|
59 for the current month. You can, but need not, use leading zeros.
60 For example, |02| represents February, just like |2|.
61 \item The month must also be followed by a hyphen.
62 \item Next you must either provide a day of month (again, a number and,
63 again, |\day| yields the current day of month) or the keyword
64 |last|. This keyword refers to the last day of the month, which is
65 automatically computed (and which is a bit tricky to compute,
66 especially for February).
67 \item Optionally, you can next provide a plus sign followed by positive
68 or negative number. This number of days will be added to the
69 computed date.
70 \end{enumerate}
71
72 Here are some examples:
73 %
74 \begin{itemize}
75 \item |2006-01-01| refers to the first day of 2006.
76 \item |2006-02-last| refers to February 28, 2006.
77 \item |\year-\month-\day| refers to today.
78 \item |2006-01-01+2| refers to January 3, 2006.
79 \item |\year-\month-\day+1| refers to tomorrow.
80 \item |\year-\month-\day+-1| refers to yesterday.
81 \end{itemize}
82
83 The conversion method is taken from the English Wikipedia entry on Julian
84 days.
85
86 \newcount\mycount
87 \example |\pgfcalendardatetojulian{2007-01-14}{\mycount}| sets
88 |\mycount| to
89 \pgfcalendardatetojulian{2007-01-14}{\mycount}\the\mycount.
90 \end{command}
91
92 \begin{command}{\pgfcalendarjuliantodate\marg{Julian day}\marg{year macro}\marg{month macro}\marg{day macro}}
93 This command converts a Julian day number to an ISO-date. The \meta{Julian
94 day} must be a number or \TeX\ counter, the \meta{year macro}, \meta{month
95 macro} and \meta{day macro} must be \TeX\ macro names. They will be set to
96 numbers representing the year, month, and day of the given Julian day in
97 the Gregorian calendar.
98
99 The \meta{year macro} will be assigned the year without leading zeros. Note
100 that this macro will produce year 0 (as opposed to other calendars, where
101 year 0 does not exist). However, if you really need calendars for before
102 the year 1, it is expected that you know what you are doing anyway.
103
104 The \meta{month macro} gets assigned a two-digit number representing the
105 month (with a leading zero, if necessary). Thus, the macro is set to |01|
106 for January.
107
108 The \meta{day macro} gets assigned a two-digit number representing the day
109 of the month (again, possibly with a leading zero).
110
111 To convert a Julian day number to an ISO-date you use code like the
112 following:
113 %
114 \begin{verbatim}
115 \pgfcalendarjuliantodate{2454115}{\myyear}{\mymonth}{\myday}
116 \edef\isodate{\myyear-\mymonth-\myday}
117 \end{verbatim}
118 %
119 The above code sets |\isodate| to
120 \pgfcalendarjuliantodate{2454115}{\myyear}{\mymonth}{\myday}%
121 \edef\isodate{\myyear-\mymonth-\myday}\texttt{\isodate}.
122 \end{command}
123
124 \begin{command}{\pgfcalendarjuliantoweekday\marg{Julian day}\marg{week day counter}}
125 This command converts a Julian day to a week day by computing the day
126 modulo 7. The \meta{week day counter} must be a \TeX\ counter. It will be
127 set to 0 for a Monday, to 1 for a Tuesday, and so on.
128
129 \example |\pgfcalendarjuliantoweekday{2454115}{\mycount}| sets
130 |\mycount| to
131 \pgfcalendarjuliantoweekday{2454115}{\mycount}\the\mycount\ (it was a Sunday).
132 \end{command}
133
134 \begin{command}{\pgfcalendareastersunday\marg{year}\marg{counter}}
135 This command computes the date of Easter Sunday as a Julian date and stores
136 it in \meta{counter}.
137
138 \example |\pgfcalendareastersunday{2019}{\mycount}| sets
139 |\mycount| to
140 \pgfcalendareastersunday{2019}{\mycount}\the\mycount, which corresponds to
141 \pgfcalendarjuliantodate{\mycount}{\myyear}{\mymonth}{\myday}%
142 \edef\isodate{\myyear-\mymonth-\myday}\texttt{\isodate}.
143 \end{command}
144
145 \subsubsection{Checking Dates}
146
147 \begin{command}{\pgfcalendarifdate\marg{date}\marg{tests}\marg{code}\marg{else code}}
148 \label{pgfcalendarifdate}
149 This command is used to execute code based on properties of \meta{date}.
150 The \meta{date} must be a date in ISO-format. For this date, the
151 \meta{tests} are checked (to be detailed later) and if one of the tests
152 succeeds, the \meta{code} is executed. If none of the tests succeeds, the
153 \meta{else code} is executed.
154
155 \example |\pgfcalendarifdate{2007-02-07}{Wednesday}{Is a Wednesday}{Is not a Wednesday}|
156 yields \texttt{\pgfcalendarifdate{2007-02-07}{Wednesday}{Is a Wednesday}{Is
157 not a Wednesday}}.
158
159 The \meta{tests} is a comma-separated list of key--value pairs. The
160 following are defined by default:
161 %
162 \begin{itemize}
163 \itemcalendaroption{all} This test is passed by all dates.
164 \itemcalendaroption{Monday} This test is passed by all dates that are
165 Mondays.
166 \itemcalendaroption{Tuesday} as above.
167 \itemcalendaroption{Wednesday} as above.
168 \itemcalendaroption{Thursday} as above.
169 \itemcalendaroption{Friday} as above.
170 \itemcalendaroption{Saturday} as above.
171 \itemcalendaroption{Sunday} as above.
172 \itemcalendaroption{workday} Passed by Mondays, Tuesdays, Wednesdays,
173 Thursdays, and Fridays. \itemcalendaroption{weekend} Passed by
174 Saturdays and Sundays.
175 \itemcalendaroption{equals}|=|\meta{reference} The \meta{reference}
176 can be in one of two forms: Either, it is a full ISO format date
177 like |2007-01-01| or the year may be missing as in |12-31|. In the
178 first case, the test is passed if \meta{date} is the same as
179 \meta{reference}. In the second case, the test is passed if the
180 month and day part of \meta{date} is the same as \meta{reference}.
181
182 For example, the test |equals=2007-01-10| will only be passed by
183 this particular date. The test |equals=05-01| will be passed by
184 every first of May on any year.
185 \itemcalendaroption{at least}|=|\meta{reference} This test works
186 similarly to the |equals| test, only it is checked whether
187 \meta{date} is equal to \meta{reference} or to any later date.
188 Again, the \meta{reference} can be a full date like |2007-01-01| or
189 a short version like |07-01|. For example, |at least=07-01| is true
190 for every day in the second half of any year.
191 \itemcalendaroption{at most}|=|\meta{reference} as above.
192 \itemcalendaroption{between}|=|\meta{start reference}| and |\meta{end
193 reference} This test checks whether the current date lies between
194 the two given reference dates. Both full and short version may be
195 given.
196
197 For example |between=2007-01-01 and 2007-02-28| is true for the
198 days in January and February of 2007.
199
200 For another example, |between=05-01 and 05-07| is true for the days
201 of the first week of May of any year.
202 \itemcalendaroption{day of month}|=|\meta{number} Passed by the day of
203 month of the \meta{date} that is \meta{number}. For example, the
204 test |day of month=1| is passed by every first of every month.
205 \itemcalendaroption{end of month}\opt{|=|\meta{number}} Passed by the
206 day of month of the \meta{date} that is \meta{number} from the end
207 of the month. For example, the test |end of month=1| is passed by
208 the last day of every month, the test |end of month=2| is passed by
209 the second last day of every month. If \meta{number} is omitted, it
210 is assumed to be |1|.
211 \itemcalendaroption{Easter}\opt{|=|\meta{number}} This test checks
212 whether the given date is Easter Sunday. The optional number can
213 be used for offsets from Easter Sunday, e.g.\ |Easter=-3| for
214 Maundy Thursday, |Easter=-2| for Good Friday, |Easter=1| for Easter
215 Monday. Since the dates of other Christian holidays are determined
216 by the date of Easter, these can be accessed as well, e.g.\
217 |Easter=39| for Feast of the Ascension, |Easter=49| for Pentecost,
218 and |Easter=50| for Whit Monday.
219 \end{itemize}
220
221 In addition to the above checks, you can also define new checks. To do so,
222 you must add a new key to the path |/pgf/calendar/| using the |\pgfkeys|
223 command. The job of the code of this new key is to possibly set the \TeX-if
224 |\ifpgfcalendarmatches| to true (if it is already true, no action should be
225 taken) to indicate that the \meta{date} passes the test setup by this new
226 key.
227
228 In order to perform the test, the key code needs to know the date that
229 should be checked. The date is available through a macro, but a whole bunch
230 of additional information about this date is also available through the
231 following macros:
232 %
233 \begin{itemize}
234 \item |\pgfcalendarifdatejulian| is the Julian day number of the
235 \meta{date} to be checked.
236 \item |\pgfcalendarifdateweekday| is the weekday of the \meta{date} to
237 be checked.
238 \item |\pgfcalendarifdateyear| is the year of the \meta{date} to be
239 checked.
240 \item |\pgfcalendarifdatemonth| is the month of the \meta{date} to be
241 checked.
242 \item |\pgfcalendarifdateday| is the day of month of the \meta{date} to
243 be checked.
244 \end{itemize}
245
246 For example, let us define a new key that checks whether the \meta{date} is
247 a Workers day (May 1st). This can be done as follows:
248 %
249 \begin{verbatim}
250 \pgfkeys{/pgf/calendar/workers day/.code=%
251 {
252 \ifnum\pgfcalendarifdatemonth=5\relax
253 \ifnum\pgfcalendarifdateday=1\relax
254 \pgfcalendarmatchestrue
255 \fi
256 \fi
257 }}
258 \end{verbatim}
259 %
260 \end{command}
261
262
263 \subsubsection{Typesetting Dates}
264
265 \begin{command}{\pgfcalendarweekdayname\marg{week day number}}
266 This command expands to a textual representation of the day of week, given
267 by the \meta{week day number}. Thus, |\pgfcalendarweekdayname{0}| expands
268 to |Monday| if the current language is English and to |Montag| if the
269 current language is German, and so on. See
270 Section~\ref{section-calendar-locale} for more details on translations.
271
272 \example |\pgfcalendarweekdayname{2}| yields
273 \texttt{\pgfcalendarweekdayname{2}}.
274 \end{command}
275
276 \begin{command}{\pgfcalendarweekdayshortname\marg{week day number}}
277 This command works similarly to the previous command, only an abbreviated
278 version of the week day is produced.
279
280 \example |\pgfcalendarweekdayshortname{2}| yields
281 \texttt{\pgfcalendarweekdayshortname{2}}.
282 \end{command}
283
284 \begin{command}{\pgfcalendarmonthname\marg{month number}}
285 This command expands to a textual representation of the month, which is
286 given by the \meta{month number}.
287
288 \example |\pgfcalendarmonthname{12}| yields
289 \texttt{\pgfcalendarmonthname{12}}.
290 \end{command}
291
292 \begin{command}{\pgfcalendarmonthshortname\marg{month number}}
293 As above, only an abbreviated version is produced.
294
295 \example |\pgfcalendarmonthshortname{12}| yields
296 \texttt{\pgfcalendarmonthshortname{12}}.
297 \end{command}
298
299
300 \subsubsection{Localization}
301 \label{section-calendar-locale}
302
303 All textual representations of week days or months (like ``Monday'' or
304 ``February'') are wrapped with |\translate| commands from the |translator|
305 package (it this package is not loaded, no translation takes place).
306 Furthermore, the |pgfcalendar| package will try to load the
307 |translator-months-dictionary|, if the |translator| package is loaded.
308
309 If you want to use the |translator| package, it has to be loaded before the
310 |pgfcalendar| package or, when you are using the |calendar| \tikzname\ library,
311 before |tikz|. Otherwise it will not be properly detected.
312
313 The net effect of all this is that all dates will be translated to the current
314 language setup in the |translator| package. See the documentation of this
315 package for more details.
316
317
318 \subsection{Typesetting Calendars}
319
320 \begin{command}{\pgfcalendar\marg{prefix}\marg{start date}\marg{end date}\marg{rendering code}}
321 This command can be used to typeset a calendar. It is a very general
322 command, the actual work has to be done by giving clever implementations of
323 \meta{rendering code}. Note that this macro need \emph{not} be called
324 inside a |{pgfpicture}| environment (even though it typically will be) and
325 you can use it to typeset calendars in normal \TeX\ or using packages other
326 than \pgfname.
327
328
329 \medskip
330 \textbf{Basic typesetting process.}
331 A calendar is typeset as follows: The \meta{start date} and \meta{end date}
332 specify a range of dates. For each date in this range the \meta{rendering
333 code} is executed with certain macros setup to yield information about the
334 \emph{current date} (the current date in the enumeration of dates of the
335 range). Typically, the \meta{rendering code} places nodes inside a picture,
336 but it can do other things as well. Note that it is also the job of the
337 \meta{rendering code} to position the calendar correctly.
338
339 The different calls of the \meta{rending code} are not surrounded by \TeX\
340 groups (though you can do so yourself, of course). This means that settings
341 can accumulate between different calls, which is often desirable and
342 useful.
343
344
345 \medskip
346 \textbf{Information about the current date.}
347 Inside the \meta{rendering code}, different macros can be access:
348 %
349 \begin{itemize}
350 \item |\pgfcalendarprefix| The \meta{prefix} parameter. This prefix is
351 recommended for nodes inside the calendar, but you have to use it
352 yourself explicitly.
353 \item |\pgfcalendarbeginiso| The \meta{start date} of range being
354 typeset in ISO format (like 2006-01-10).
355 \item |\pgfcalendarbeginjulian| Julian day number of \meta{start date}.
356 \item |\pgfcalendarendiso| The \meta{end date} of range being typeset
357 in ISO format.
358 \item |\pgfcalendarendjulian| Julian day number of \meta{end date}.
359 \item |\pgfcalendarcurrentjulian| This \TeX\ count holds the Julian day
360 number of the day currently being rendered.
361 \item |\pgfcalendarcurrentweekday| The weekday (a number with zero
362 representing Monday) of the current date.
363 \item |\pgfcalendarcurrentyear| The year of the current date.
364 \item |\pgfcalendarcurrentmonth| The month of the current date (always
365 two digits with a leading zero, if necessary).
366 \item |\pgfcalendarcurrentday| The day of month of the current date
367 (always two digits).
368 \end{itemize}
369
370
371 \medskip
372 {\bfseries The |\ifdate| command.}
373 Inside the |\pgfcalendar| the macro |\ifdate| is available locally:
374 %
375 \begin{command}{\ifdate\marg{tests}\marg{code}\marg{else code}}
376 \label{ifdate}%
377 This command has the same effect as calling |\pgfcalendarifdate|
378 for the current date.
379 \end{command}
380
381
382 \medskip
383 \textbf{Examples.}
384 In a first example, let us create a very simple calendar: It just lists the
385 dates in a certain range.
386 %
387 \begin{codeexample}[vbox,ignorespaces,preamble={\usepackage{pgfcalendar}}]
388 \pgfcalendar{cal}{2007-01-20}{2007-02-10}{\pgfcalendarcurrentday\ }
389 \end{codeexample}
390 %
391 Let us now make this a little more interesting: Let us add a line break
392 after each Sunday.
393 %
394 \begin{codeexample}[vbox,ignorespaces,preamble={\usepackage{pgfcalendar}}]
395 \pgfcalendar{cal}{2007-01-20}{2007-02-10}
396 {
397 \pgfcalendarcurrentday\
398 \ifdate{Sunday}{\par}{}
399 }
400 \end{codeexample}
401 %
402 We now want to have all Mondays to be aligned on a column. For this,
403 different approaches work. Here is one based positioning each day
404 horizontally using a skip.
405 %
406 \begin{codeexample}[vbox,ignorespaces,preamble={\usepackage{pgfcalendar}}]
407 \pgfcalendar{cal}{2007-01-20}{2007-02-10}
408 {%
409 \leavevmode%
410 \hbox to0pt{\hskip\pgfcalendarcurrentweekday cm\pgfcalendarcurrentday\hss}%
411 \ifdate{Sunday}{\par}{}%
412 }
413 \end{codeexample}
414 %
415 Let us now typeset two complete months.
416 %
417 \begin{codeexample}[vbox,ignorespaces,preamble={\usepackage{pgfcalendar}}]
418 \pgfcalendar{cal}{2007-01-01}{2007-02-28}{%
419 \ifdate{day of month=1}{
420 \par\bigskip\hbox to7.5cm{\itshape\hss\pgfcalendarshorthand mt\hss}\par
421 }{}%
422 \leavevmode%
423 {%
424 \ifdate{weekend}{\color{black!50}}{\color{black}}%
425 \hbox to0pt{%
426 \hskip\pgfcalendarcurrentweekday cm%
427 \hbox to1cm{\hss\pgfcalendarshorthand d-}\hss%
428 }%
429 }%
430 \ifdate{Sunday}{\par}{}%
431 }
432 \end{codeexample}
433 %
434 For our final example, we use a |{tikzpicture}|.
435 %
436 \begin{codeexample}[vbox,ignorespaces,preamble={\usepackage{pgfcalendar}}]
437 \begin{tikzpicture}
438 \pgfcalendar{cal}{2007-01-20}{2007-02-10}{%
439 \ifdate{workday}
440 {\tikzset{filling/.style={fill=blue!20}}}
441 {\tikzset{filling/.style={fill=red!20}}}
442 \node (\pgfcalendarsuggestedname) at (\pgfcalendarcurrentweekday,0)
443 [anchor=base,circle,filling] {\pgfcalendarcurrentday};
444 \ifdate{Sunday}{\pgftransformyshift{-3em}}{}%
445 }
446 \draw (cal-2007-01-21) -- (cal-2007-02-03);
447 \end{tikzpicture}
448 \end{codeexample}
449 %
450 \end{command}
451
452 \begin{command}{\pgfcalendarshorthand\marg{kind}\marg{representation}}
453 \label{pgfcalendarshorthand}
454 This command can be used inside a |\pgfcalendar|, where it will expand to a
455 representation of the current day, month, year or day of week, depending on
456 whether \meta{kind} is |d|, |m|, |y| or |w|. The \meta{representation} can
457 be one of the following: |-|, |=|, |0|, |.|, and |t|. They have the
458 following meanings:
459 %
460 \begin{itemize}
461 \item The minus sign selects the shortest numerical representation
462 possible (no leading zeros).
463 \item The equal sign also selects the shortest numerical
464 representation, but a space is added to single digit days and
465 months (thereby ensuring that they have the same length as other
466 days).
467 \item The zero digit selects a two-digit numerical representation for
468 days and months. For years it is allowed, but has no effect.
469 \item The letter |t| selects a textual representation.
470 \item The dot selects an abbreviated textual representation.
471 \end{itemize}
472 %
473 Normally, you should say |\let\%=\pgfcalendarshorthand| locally, so that
474 you can write |\%wt| instead of the much more cumbersome
475 |\pgfcalendarshorthand{w}{t}|.
476 %
477 \begin{codeexample}[leave comments,preamble={\usepackage{pgfcalendar}}]
478 \let\%=\pgfcalendarshorthand
479 \pgfcalendar{cal}{2007-01-20}{2007-01-20}
480 { ISO form: \%y0-\%m0-\%d0, long form: \%wt, \%mt \%d-, \%y0}
481 \end{codeexample}
482 %
483 \end{command}
484
485 \begin{command}{\pgfcalendarsuggestedname}
486 This macro expands to a suggested name for nodes representing days in a
487 calendar. If the \meta{prefix} is empty, it expands to the empty string,
488 otherwise it expands to the \meta{prefix} of the calendar, followed by a
489 hyphen, followed by the ISO format version of the date. Thus, when the date
490 |2007-01-01| is typeset in a calendar for the prefix |mycal|, the macro
491 expands to |mycal-2007-01-01|.
492 \end{command}