Debian Codegraph @

texmf-dist/source/latex/sesstime/sesstime.dtx

raw
1 %
2 % \iffalse meta-comment
3 %
4 % sesstime.dtx Copyright (C) 2016-2026 Niklas Beisert
5 %
6 % This work may be distributed and/or modified under the
7 % conditions of the LaTeX Project Public License, either version 1.3
8 % of this license or (at your option) any later version.
9 % The latest version of this license is in
10 % https://www.latex-project.org/lppl.txt
11 % and version 1.3c or later is part of all distributions of LaTeX
12 % version 2008 or later.
13 %
14 % This work has the LPPL maintenance status `maintained'.
15 %
16 % The Current Maintainer of this work is Niklas Beisert.
17 %
18 % This work consists of the files sesstime.dtx and sesstime.ins
19 % and the derived files sesstime.sty and sesstime-samp.tex
20 % with sesstime-samp-3.tex and sesstime-samp-4.tex.
21 %
22 %<package|sample>\NeedsTeXFormat{LaTeX2e}[1996-12-01]
23 %<package>\ProvidesPackage{sesstime}[2026-03-23 v1.1.4 session timing marks]
24 %<sample>\ProvidesFile{sesstime-samp.tex}[2026-03-23 v1.1.4 sample for sesstime]
25 %<source>\ProvidesFile{sesstime-src.tex}[2026-03-23 v1.1.4 sesstime source code documentation]
26 %<manual>\ProvidesFile{sesstime.tex}[2026-03-23 v1.1.4 sesstime reference manual]
27 %<*main|manual|source>
28 \def\thepkg/{sesstime}\def\thedate/{2026-03-23}\def\theversion/{v1.1.4}
29 \def\thecopyright/{2016\texorpdfstring{--}{-}2026 Niklas Beisert}
30 %<*main>
31 \ProvidesFile{\thepkg/.dtx}[\thedate/ \theversion/ \thepkg/ package main file]
32 %</main>
33 \PassOptionsToClass{10pt,a4paper}{article}
34 \documentclass{ltxdoc}
35
36 \usepackage[margin=35mm]{geometry}
37 \usepackage[hyperindex=false]{hyperref}
38 \usepackage{hyperxmp}
39 \usepackage[usenames]{color}
40 \usepackage{longtable}
41
42 %<*main>
43 \title{The \markpkg{\thepkg/} Package}
44 \hypersetup{pdftitle={The \thepkg/ Package}}
45 \hypersetup{pdfsubject={Documentation for the LaTeX2e Package \thepkg/}}
46 %</main>
47 %<manual>\title{The \markpkg{\thepkg/} Package\\Reference Manual}
48 %<manual>\hypersetup{pdftitle={The \thepkg/ Package -- Reference Manual}}
49 %<manual>\hypersetup{pdfsubject={Reference Manual for the LaTeX2e Package \thepkg/}}
50 %<source>\title{The \markpkg{\thepkg/} Package\\Source Code Documentation}
51 %<source>\hypersetup{pdftitle={The \thepkg/ Package -- Source Code Documentation}}
52 %<source>\hypersetup{pdfsubject={Documented Source for the LaTeX2e Package \thepkg/}}
53 \author{Niklas Beisert\\[2ex]
54 Institut f\"ur Theoretische Physik\\
55 Eidgen\"ossische Technische Hochschule Z\"urich\\
56 Wolfgang-Pauli-Strasse 27, 8093 Z\"urich, Switzerland\\[1ex]
57 \href{mailto:[email protected]}
58 {\texttt{[email protected]}}}
59 \hypersetup{pdfauthor={Niklas Beisert}}
60 \date{\theversion/: \markdate{\thedate/}\\[1ex]
61 \url{https://ctan.org/pkg/\thepkg/}\\[0.5ex]
62 \url{https://github.com/nbeisert/latex-pkg-nb}}
63
64 \hypersetup{pdflang={en-UK}}
65 \hypersetup{pdfurl={https://ctan.org/pkg/\thepkg/}}
66 \hypersetup{pdfcopyright={Copyright \thecopyright/.
67 This work may be distributed and/or modified under the
68 conditions of the LaTeX Project Public License, either version 1.3
69 of this license or (at your option) any later version.}}
70 \hypersetup{pdflicenseurl={https://www.latex-project.org/lppl.txt}}
71 \hypersetup{pdfcontactaddress={ETH Zurich, ITP, HIT K,
72 Wolfgang-Pauli-Strasse 27}}
73 \hypersetup{pdfcontactpostcode={8093}}
74 \hypersetup{pdfcontactcity={Zurich}}
75 \hypersetup{pdfcontactcountry={Switzerland}}
76 \hypersetup{pdfcontactemail={[email protected]}}
77 \hypersetup{pdfcontacturl={https://people.phys.ethz.ch/\xmptilde nbeisert/}}
78
79 \hypersetup{keeppdfinfo=true}
80 \hypersetup{pdfsource={}}
81 \AddToHook{begindocument/before}{\hypersetup{colorlinks=false}}
82 \hypersetup{urlbordercolor={.5 1 1}}
83 \hypersetup{linkbordercolor={1 .7 .7}}
84 \AddToHook{begindocument/before}{\hypersetup{pdfstartview=FitH}}
85
86 \parskip1ex
87 \parindent0pt
88 \edef\itemize{\unexpanded\expandafter{\itemize}\parskip0pt}
89
90 \newcommand{\markpkg}[1]{\textsf{#1}}
91 \newcommand{\markdate}[1]{\textsf{#1}}
92 \newcommand{\secref}[1]{\hyperref[#1]{section \ref*{#1}}}
93 \newcommand{\ctanref}[2]{\href{https://ctan.org/#1}{#2}}
94 \newcommand{\ctanpkg}[1]{\ctanref{pkg/#1}{\markpkg{#1}}}
95
96 \def\verbbar{\texttt{\char"7C}}
97 \def\verbpkg{\texttt{\thepkg/}}
98 \def\thepkgctan/{\ctanpkg{\thepkg/}}
99
100 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
101
102 \makeatletter
103 \newcommand{\timingprint}[2][l]{%
104 \ifhmode\par\fi
105 \ifvmode
106 \@bsphack
107 \dimen@\prevdepth
108 \nointerlineskip
109 \if r#1%
110 \hbox{\smash{\rlap{\hspace{\textwidth}\parbox[t]{1cm}%
111 {\raggedright\renewcommand{\bfdefault}{b}#2}}}}%
112 \else
113 \hbox{\smash{\llap{\parbox[t]{1cm}%
114 {\raggedleft\renewcommand{\bfdefault}{b}#2}}}}%
115 \fi
116 \prevdepth\dimen@
117 \@esphack
118 \fi}
119 \newcommand{\printmark}[1]{\timingprint{\footnotesize#1}}
120 \newcommand{\printremark}[1]{%
121 \timingprint[r]{\tiny\sffamily\hrule#1\hrule}}
122 \makeatother
123
124 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
125 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
126 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
127 \begin{document}
128
129 \maketitle
130
131 \begin{abstract}\noindent
132 \markpkg{sesstime} is a \LaTeXe{} package
133 to add timing marks to lecture notes
134 in order to help managing the time available
135 for presenting a given section of the document.
136 It also provides tools to record and
137 estimate the progress throughout the course.
138 \end{abstract}
139
140 \begingroup
141 \parskip0ex
142 \tableofcontents
143 \endgroup
144
145
146 %<*main|manual>
147 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
148 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
149 \section{Introduction}
150
151 A crucial step in designing a lecture course is to estimate
152 the time needed for presenting the individual topics and to
153 arrange them such that the overall teaching goals can be achieved
154 within a predetermined amount of time.
155 This step requires a lot of experience and the information is typically lost
156 when (parts of) the lecture notes are recycled by different lecturer.
157 While it is very useful to have timing information available
158 for a number of purposes,
159 it also takes patience and dedication to
160 set it up and to keep it up to date when
161 the presented material is changed (added, removed or shuffled).
162
163 This package offers an interface to store such timing information
164 in the \LaTeX{} source. It also offers some tools
165 to process the raw data and display them in compiled form.
166 The goals and features of this package include the following:
167 \begin{itemize}
168 \item
169 Store timing information in the \LaTeX{} source
170 (as absolute or relative times).
171 \item
172 Show small timing marks in the margin of the text.
173 \item
174 Indicate where sessions begin and end in the \LaTeX{} source
175 and display session information in the text margin.
176 \item
177 Show the total time needed to present a given block, chapter or session
178 at its start.
179 \item
180 Generate a table of sessions to track and estimate the progress
181 throughout the course.
182 \item
183 Show brief comments regarding presentation,
184 e.g.\ to skip certain parts or to pay particular attention.
185 \item
186 Maintain timing information in updates as conveniently as possible.
187 \item
188 Automatically generate the subdivision of sessions
189 (based on the timing information provided).
190 \end{itemize}
191
192 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
193 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
194 \section{Usage}
195
196 This section describes the structures, markup and mechanisms
197 provided by the package and some hints how to structure and maintain
198 the information within the document.
199 A complete reference of commands
200 and configuration options in given in \secref{sec:commands}.
201
202 To use the package \ctanpkg{sesstime} add the command
203 \begin{center}
204 |\usepackage{sesstime}|
205 \end{center}
206 to the preamble of your \LaTeX{} document.
207
208 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
209 \subsection{Blocks}
210
211 The basic timing information is entered in a unit called \emph{block}.
212 It has the following generic structure:
213 %
214 \begin{center}
215 \begin{tabular}{l}
216 |\timingstart{15}|\\
217 |abc|\\
218 |def|\\
219 |\timingsplit{30}|\\
220 |ghi|\\
221 |jkl|\\
222 |\timingsplit{40}|\\
223 |mno|\\
224 |pqr|\\
225 |\timingstop{1:00}|\\
226 \end{tabular}
227 \end{center}
228 %
229 The above timing information is provided as absolute times
230 (in [hours:]minutes),
231 such that the block begins at 15 minutes and ends at 1 hour.
232 It thus takes 45 minutes in total to present this block.
233 Furthermore, two intermediate times are specified at 15 minutes
234 and 25 minutes into the block
235 (albeit in the form of absolute times).
236 The timing information for the block will be displayed as:
237 \vspace{2ex}
238 \begin{center}
239 \vrule\begin{minipage}{3em}
240 \printmark{\textbf{90}\rlap{\vphantom{$\Updownarrow$}}\kern1.2em%
241 \hrule 45\rlap{\kern0.4em$\Downarrow$\vphantom{$\Updownarrow$}}\kern1.2em}
242 abc\\
243 def\par
244 \printmark{\raisebox{-1ex}{15\rlap{\kern0.4em$\Updownarrow$}}\kern1.2em}
245 ghi\\
246 jkl\par
247 \printmark{\raisebox{-1ex}{25\rlap{\kern0.4em$\Updownarrow$}}\kern1.2em}
248 mno\\
249 pqr\par
250 \printmark{45\rlap{\kern0.4em$\Uparrow$\vphantom{$\Updownarrow$}}%
251 \kern1.2em\hrule%
252 \textbf{135}\rlap{\vphantom{$\Updownarrow$}}\kern1.2em}
253 \end{minipage}
254 \end{center}
255 \vspace{2ex}
256 Note that the displayed times are always relative to the block beginning.
257 The bold numbers show the overall time outside the block
258 (assuming that this block starts at 90 minutes).
259 Furthermore, note that two \LaTeX{} passes are
260 needed to display all data correctly
261 (as for labels).
262
263 Alternatively, the information can be entered as
264 relative times with respect to the previous timing command:
265 %
266 \begin{center}
267 \begin{tabular}{l}
268 |\timingstart*{0}|\\
269 |...|\\
270 |\timingsplit*{15}|\\
271 |...|\\
272 |\timingsplit*{10}|\\
273 |...|\\
274 |\timingstop*{20}|
275 \end{tabular}
276 \end{center}
277 %
278 This markup has the same effect as the above timing commands
279 using absolute times.
280 There are some benefits and shortcomings to the two modes
281 of entering the information,
282 and the choice is left to the user.
283 Note that relative and absolute times can be mixed
284 (one absolute reference point should be specified previously).
285
286 Some remarks and considerations are in order
287 for setting up timing blocks
288 and maintaining them when changing the presented material:
289 \begin{itemize}
290 \item
291 If the duration of some presented material is estimated,
292 it makes sense to specify relative times.
293 \item
294 If the duration is determined by periodically
295 noting the present time displayed on a clock,
296 it makes sense to specify these absolute times directly.
297 \item
298 When absolute times are specified, the duration of a block
299 is determined by the final |\timingstop| (only).
300 Split times given by |\timingsplit|[|*|] do not change
301 the overall length.
302 In order to change the duration of a block
303 when some presented material is added or removed,
304 all subsequent absolute times have to be adjusted.
305 Alternatively, additional time can be specified by:
306 %
307 \begin{center}
308 |\timinglapse{5}|
309 \end{center}
310 %
311 This command conveniently adds 5 minutes to the block
312 without modifying the current absolute time.
313 When using relative times throughout the block,
314 this has the same effect as |\timingsplit*{5}|.
315 \end{itemize}
316
317 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
318 \subsection{Chapters}
319
320 The package provides an additional layer
321 of structure called \emph{chapters}.
322 A chapter combines several blocks in order to display
323 the overall required time as well as relative times within the chapter.
324
325 A chapter is enclosed by two commands
326 %
327 \begin{center}
328 \begin{tabular}{l}
329 |\timingchapter|\\
330 |abc|\\
331 |def|\\
332 |ghi|\\
333 |\timingchapterend|
334 \end{tabular}
335 \end{center}
336 %
337 Closing a chapter is optional,
338 it will be closed automatically by starting any subsequent chapter.
339
340 There are three uses to declaring chapters.
341 The total time for presenting the chapter is computed and
342 it is displayed at the start:
343 %
344 \vspace{2ex}
345 \begin{center}
346 \vrule\begin{minipage}{3em}
347 \printmark{\textbf{180}\rlap{\kern0.4em$\star$}\kern1.2em}
348 abc\\
349 def\\
350 ghi
351 \end{minipage}
352 \end{center}
353 %
354 Furthermore, the bold numbers shown in the above examples
355 for blocks indicate the present time relative to the beginning of the chapter.
356 Finally, one can also show the total time needed for any chapter
357 anywhere within the document,
358 e.g.\ for a customised table of contents
359 or next to the chapter title in a customised form.
360
361 It will be useful to match the chapters and blocks
362 to certain structures in the document.
363 For example, chapters could correspond to chapters or sections
364 depending on which documentclass is used.
365 If the |\include| mechanism of \LaTeX{} is used to structure the document
366 into several files,
367 it makes sense to use these units as chapters for timing purposes.
368 Blocks would typically correspond to the next level of structure
369 (sections or subsections, respectively)
370 and split times could be inserted naturally
371 at any finer levels of structure (subsubsections, paragraphs).
372
373 Establishing some guidelines how to entering timing information
374 will be useful because the package will then compute the total durations
375 of these structures and display the times at their beginnings.
376
377 For maintenance purposes, a typical block could last
378 around 30 minutes to an hour and be split at no more than a handful instances;
379 more split times will take more efforts in maintaining across updates.
380 There is no practical limitation to the length of individual chapters
381 as times are computed automatically;
382 typically it would consist of a couple of blocks.
383
384 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
385 \subsection{Sessions}
386
387 Chapters will normally not map one-to-one to the units of presentation
388 (individual lectures) which we shall call \emph{sessions}.
389 It may be useful to keep track or estimate
390 where each session will start (or end).
391 There are two mechanisms to specify sessions.
392 The manual declaration takes the form:
393 %
394 \begin{center}
395 \begin{tabular}{l}
396 |\timingsession|\\
397 |abc|\\
398 |def|\\
399 |ghi|\\
400 |\timingsessionend|
401 \end{tabular}
402 \end{center}
403 %
404 Again, closing a session is optional,
405 it will be closed automatically by starting any subsequent session.
406 Alternatively, the subdivision of sessions can be automatically
407 estimated by the command:
408 %
409 \begin{center}
410 |\timingconfigure{autosession=|\textit{duration}|}|
411 \end{center}
412 %
413 This declares the duration of a session to be \textit{duration} minutes.
414 New sessions will be started automatically when the available time for the
415 previous session has elapsed
416 (as far as possible with the timing information provided).
417
418 Sessions have two uses.
419 The start of a session is indicated in the margin
420 together with its duration:
421 %
422 \begin{center}
423 \begin{minipage}{3em}
424 \printremark{session 4\\(35 min)}
425 abc\\
426 def\\
427 ghi
428 \end{minipage}\vrule
429 \end{center}
430 %
431 Furthermore, a list of sessions can be displayed by the command:
432 %
433 \begin{center}
434 |\timinglistofsessions|
435 \end{center}
436 %
437 The list of sessions can serve two purposes in planning a lecture course.
438 First, it outlines the (approximate) overall schedule and
439 allows one to find out conveniently whether
440 there will be sufficiently many sessions to cover the intended material.
441 Second, the preview can help coordinating the
442 topics for exercises to accompany the course.
443
444 Note that the automatic assignment of sessions
445 relies on the timing information provided in the blocks.
446 On the one hand, the latter should be sufficiently fine-grained
447 so that the session breaks can be located accurately.
448 On the other hand, it will not be worth the effort
449 to establish too detailed information.
450 Providing one timing mark for around
451 one third of the duration of a session
452 will produce reasonable results.
453 In the case of coarse-grained information,
454 new sessions will be triggered such that
455 the overall schedule remains approximately valid.
456 The session marks will then be displayed some time
457 after the session is expected is start, and the
458 time difference is displayed.
459
460 Note also that the list of sessions
461 and total times rely on information stored in the |.aux| files.
462 In order to update the information, it may be necessary
463 to compile the complete document (without |\includeonly| statements) twice.
464
465 Finally, it may be useful to emphasise that
466 session marks can also be displayed without providing timing information.
467 In that case, the subdivision of session evidently
468 cannot be generated automatically, but must be stored manually.
469
470 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
471 \subsection{Comments}
472
473 Occasionally it is useful to write some brief comments or instructions
474 in the margin of lecture notes.
475 While there are native \LaTeX{} tools to do so,
476 the package provides an integrated mechanism:
477 %
478 \begin{center}
479 |\timingcomment{|\textit{comment}|}|
480 \end{center}
481 %
482 Such comments can serve many purposes, such as:
483 %
484 \begin{itemize}
485 \textwidth0.9\textwidth
486 \printremark{skipped}
487 \item
488 `skipped': The following part is skipped in the presentation.\par
489 \printremark{brief!}
490 \item
491 `brief!': Be brief! Do not waste time!\par
492 \printremark{explain!}
493 \item
494 `explain!': Explain well! Take your time!\par
495 \printremark{exercise}
496 \item
497 `exercise': Hint at an accompanying exercise.
498 \item
499 \ldots
500 \end{itemize}
501
502 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
503 \subsection{Flags}
504 \label{sec:flags}
505
506 The package allows to specify flags to distinguish
507 different versions of the document
508 or to set it up for different purposes
509 (e.g.\ a particular iteration of the lecture course
510 or lecture notes vs.\ textbook):
511 %
512 \begin{center}
513 |\timingconfigure{flags={|\textit{flags}|}}|
514 \end{center}
515 %
516 Here \textit{flags} is a comma-separated list of user-defined flags.
517 Please avoid special characters and spaces (spaces next to
518 comma separators are presently not ignored).
519
520 Most timing commands provided by the package
521 accept an optional argument which can be
522 |[if=|\textit{flag}|]| or |[not=|\textit{flag}|]|
523 (or combinations of these separated by comma).
524 These commands will be processed only if the specified condition(s) hold.
525 For example, the commands
526 \begin{center}
527 \begin{tabular}{l}
528 |\timingcomment[if=2017]{skip}|\\
529 |\timinglapse[if=2017]{-10}|
530 \end{tabular}
531 \end{center}
532 can be used to indicate that the following part of the text is skipped
533 in the 2017 iteration of the lecture course,
534 and 10 minutes are saved by this omission.
535
536 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
537 \subsection{Printing}
538
539 Detailed timing information or comments may be intended for
540 private purposes only,
541 while these marks should be stripped in a public version of the document.
542 The package supplies some global options to enable and disable
543 the printing of timing marks.
544 To turn off all marks, use the package option:
545 %
546 \begin{center}
547 |\timingconfigure{print=false}|
548 \end{center}
549 %
550 Also individual types of timing marks can be suppressed
551 by similar package options,
552 see \secref{sec:packageoptions}.
553 For a finer selection or suppression of comments,
554 one could use an optional argument such as
555 |[if=private]| (only in the private version)
556 or |[not=public]| (only in the public version),
557 see \secref{sec:flags}.
558
559 Please note that the package uses a simple
560 mechanism to place timing marks and comments in the margin
561 next to the current location. This mechanism
562 requires \TeX{} to be in so-called vertical mode
563 (loosely speaking the space between paragraphs);
564 marks cannot be set in horizontal mode
565 (text within the paragraphs).
566 As timing marks are naturally placed between the paragraphs
567 and to avoid complications, a paragraph is automatically broken
568 when a timing mark is placed in horizontal mode.
569 This has the effect of splitting the current paragraph in two
570 or occasionally inserting some extra vertical space between paragraphs.
571 Note that this applies only if timing marks are actually printed,
572 otherwise the structure of paragraphs is left untouched.
573
574 Relatedly, it makes no sense to place timing marks \emph{after}
575 a (sub)paragraph command which enforces horizontal mode
576 to stay on the same line as the (sub)paragraph title;
577 place any marks before the (sub)paragraph command.
578 Also place timing marks at your own risk
579 within manually designed boxes or minipages
580 and avoid using them in mathematical mode.
581
582 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
583 \subsection{Customisation}
584
585 The package provides some default layout for the various
586 pieces of information to be displayed. However, it makes
587 sense to customise some of these.
588
589 For example, one could provide a list of session dates
590 and customise the session display
591 by changing the commands |\timingprintsession|
592 and/or |\timingsessionline|
593 to show the time instead of the session number.
594 See appendix \ref{sec:sample} for a sample implementation.
595
596 Please refer to the command reference in \secref{sec:commands}
597 as well as the implementation in appendix \ref{sec:implementation}
598 to find out about commands to be customised:
599 Commands suitable for customisation are among
600 the public ones (prefix |timing|)
601 and they should not make reference
602 to internal commands (prefix |sti@|).
603
604 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
605 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
606 \section{Command Reference}
607 \label{sec:commands}
608
609 This section describes the commands provided by the package \textit{sesstime}.
610
611 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
612 \subsection{Blocks}
613 \label{sec:blocks}
614
615 \DescribeMacro{\timingstart}
616 \DescribeMacro{\timingsplit}
617 \DescribeMacro{\timingstop}
618 \DescribeMacro{\timingnext}
619 Timing information is entered using the block commands:
620 \begin{center}
621 \begin{tabular}{l}
622 |\timingstart[|\textit{cond}|]{|\textit{abstime}|}|\\
623 |\timingsplit[|\textit{cond}|]{|\textit{abstime}|}|\\
624 |\timingstop[|\textit{cond}|]{|\textit{abstime}|}|\\
625 |\timingnext[|\textit{cond}|]{|\textit{abstime}|}|
626 \end{tabular}
627 \end{center}
628 The optional argument \textit{cond}
629 is a comma-separated list of options described in
630 \secref{sec:flagsref}.
631 The argument \textit{abstime} represents the absolute time at this instant;
632 it can be specified in minutes
633 or in the format \textit{hour}|:|\textit{minutes}.
634 The first three of the above commands
635 start, split or stop a block, respectively.
636 The last command stops a block and starts the next one at the same time.
637
638 Each of these commands has an alternative form:
639 \begin{center}
640 \begin{tabular}{l}
641 |\timingstart*[|\textit{cond}|]{|\textit{reltime}|}|\\
642 |\timingsplit*[|\textit{cond}|]{|\textit{reltime}|}|\\
643 |\timingstop*[|\textit{cond}|]{|\textit{reltime}|}|\\
644 |\timingnext*[|\textit{cond}|]{|\textit{reltime}|}|
645 \end{tabular}
646 \end{center}
647 Here the argument \textit{reltime} is a relative time (in minutes)
648 based on the previous block command.
649
650 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
651 \medskip
652 \noindent
653 \DescribeMacro{\timinglapse}
654 \DescribeMacro{\timinggauge}
655 There are two further commands to tweak the timers in useful ways:
656 %
657 \begin{center}
658 |\timinglapse[|\textit{cond}|]{|\textit{reltime}|}|
659 \end{center}
660 %
661 This command lets all timers evolve by \textit{reltime} minutes
662 while keeping the absolute time fixed.
663 It can be used to add or remove time from a block
664 which is otherwise specified by absolute times.
665 Instead of adjusting all later times by the lapse,
666 it suffices to insert this command between two
667 absolute time commands.
668
669 The other command implements the opposite effect:
670 %
671 \begin{center}
672 |\timinggauge[|\textit{cond}|]{|\textit{abstime}|}|
673 \end{center}
674 %
675 This command adjusts the current reference time to \textit{abstime}
676 (specified as minutes or in the format \textit{hour}|:|\textit{minutes})
677 without evolving any of the timers.
678 This can be used if a block stretches over several sessions
679 where the absolute time changes between sessions.
680 Gauging the time allows one to enter absolute times
681 as read off from a clock.
682
683 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
684 \medskip
685 \noindent
686 \DescribeMacro{\timingblocktotal}
687 The total time of the current block (in minutes) can be obtained
688 by the command:
689 \begin{center}
690 |\timingblocktotal|[|*|]|[|\textit{error}|]|
691 \end{center}
692 The duration is saved into the macro |\timingreturn|.
693 The starred form returns the duration of the subsequent block
694 instead of the current block.
695 If the time cannot be determined the optional argument \textit{error}
696 (default value `??') is returned.
697
698 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
699 \subsection{Chapters}
700 \label{sec:chapters}
701
702 \DescribeMacro{\timingchapter}
703 \DescribeMacro{\timingchapterend}
704 Chapters are started and ended by the commands:
705 \begin{center}
706 \begin{tabular}{l}
707 |\timingchapter[|\textit{cond}|]|\\
708 |\timingchapterend[|\textit{cond}|]|
709 \end{tabular}
710 \end{center}
711
712 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
713 \medskip
714 \noindent
715 \DescribeMacro{\timingchapterlabel}
716 \DescribeMacro{\timingchaptertotal}
717 The total duration of a chapter is determined by the commands:
718 \begin{center}
719 \begin{tabular}{l}
720 |\timingchapterlabel{|\textit{label}|}|\\
721 |\timingchaptertotal[|\textit{error}|]{|\textit{label}|}|\\
722 |\timingchaptertotal*[|\textit{error}|]{|\textit{chapter}|}|
723 \end{tabular}
724 \end{center}
725 The first one must be invoked within
726 a chapter to assign the label \textit{label}.
727 The second one saves the duration
728 for the chapter labelled by \textit{label}
729 into the macro |\timingreturn|.
730 The third (starred) form selects the chapter by the number \textit{chapter}.
731 If undetermined, the optional argument \textit{error} (default value `??')
732 is returned.
733
734 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
735 \subsection{Sessions}
736 \label{sec:sessions}
737
738 \DescribeMacro{\timingsession}
739 \DescribeMacro{\timingsessionend}
740 Sessions are started and ended by the commands:
741 %
742 \begin{center}
743 \begin{tabular}{l}
744 |\timingsession[|\textit{cond}|]|\\
745 |\timingsessionend[|\textit{cond}|]|
746 \end{tabular}
747 \end{center}
748
749 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
750 \medskip
751 \noindent
752 \DescribeMacro{\timinglistofsessions}
753 The list of sessions is printed by the command:
754 \begin{center}
755 |\timinglistofsessions|
756 \end{center}
757
758 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
759 \subsection{Comments}
760 \label{sec:comments}
761
762 \DescribeMacro{\timingcomment}
763 A comment is displayed by the command:
764 %
765 \begin{center}
766 |\timingsession[|\textit{cond}|]{|\textit{comment}|}|
767 \end{center}
768 %
769 As space in the margin is typically very limited,
770 it makes sense to be as concise as possible,
771 e.g.\ use just a single word or two.
772
773 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
774 \subsection{Flags}
775 \label{sec:flagsref}
776
777 The optional argument \textit{cond} for most of the above commands
778 is a comma-separated list to specify the conditions
779 under which the command is to be processed:
780 %
781 \begin{itemize}
782 \item |if=|\textit{flag} --
783 Process command only if \textit{flag} is among the currently declared flags.
784 \item |not=|\textit{flag} --
785 Process command unless \textit{flag} is among the currently declared flags.
786 \end{itemize}
787 %
788 Note that the conditionals are processed in the same order as specified.
789 After the first one is evaluated, all subsequent ones
790 change the status only if
791 \textit{flag} is among the currently declared flags.
792
793 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
794 \medskip
795 \noindent
796 \DescribeMacro{\timingif}
797 A command for optional processing is:
798 %
799 \begin{center}
800 |\timingif[|\textit{cond}|]{|\textit{code}|}|
801 \end{center}
802 %
803 The code \textit{code} is processed
804 only if the conditions \textit{cond} are met.
805
806 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
807 \subsection{Package Options}
808 \label{sec:packageoptions}
809
810 \DescribeMacro{\timingconfigure}
811 Options can be passed to the package by the commands:
812 \begin{center}
813 \begin{tabular}{rl}
814 &|\usepackage[|\textit{opts}|]{sesstime}|
815 \\
816 or&|\PassOptionsToPackage{|\textit{opts}|}{sesstime}|
817 \\
818 or&|\timingconfigure[|\textit{cond}|]{|\textit{opts}|}|
819 \end{tabular}
820 \end{center}
821 %
822 |\PassOptionsToPackage| must be used before |\usepackage|;
823 |\timingconfigure| must be used afterwards (for selected options).
824 \textit{opts} is a comma-separated list of options.
825 Below we provide a complete list of available options:
826 %
827 \begin{itemize}
828 \item |print|[|=true|\textbar|false|]
829 (no value implies |true|, initially set to |true|) --
830 Enable/disable printing all timing marks.
831
832 \item |block|[|=true|\textbar|false|]
833 (no value implies |true|, initially set to |true|) --
834 Enable/disable printing block marks.
835
836 \item |chapter|[|=true|\textbar|false|]
837 (no value implies |true|, initially set to |true|) --
838 Enable/disable printing chapter marks.
839
840 \item |session|[|=true|\textbar|false|]
841 (no value implies |true|, initially set to |true|) --
842 Enable/disable printing session marks.
843
844 \item |comment|[|=true|\textbar|false|]
845 (no value implies |true|, initially set to |true|) --
846 Enable/disable printing comments.
847
848 \item |warning|[|=true|\textbar|false|]
849 (no value implies |true|, initially set to |true|) --
850 Enable/disable printing warnings.
851
852 \item |width=|\textit{dimen}
853 (initially set to |1cm|) --
854 Specify width of timing marks in both margins.
855
856 \item |widthl=|\textit{dimen}
857 (initially set to |1cm|) --
858 Specify width of timing marks in the left margin
859 which are typically related to blocks and chapters.
860
861 \item |widthr=|\textit{dimen}
862 (initially set to |1cm|) --
863 Specify width of timing marks in the right margin
864 which are typically related to sessions and comments.
865
866 \item |autosession=|\textit{duration}
867 (initially set to |0|) --
868 Set duration of automatically determined sessions;
869 |0| disables automatic determination.
870
871 \item |depthsec=|\textit{depth}
872 (initially set to |3|) --
873 Set maximum sectioning depth to be displayed
874 along with their number in the list of sessions;
875 deeper sections are considered as paragraphs
876 and are displayed differently.
877 Values |0| through |5| correspond to
878 |\chapter|, |\section|, |\subsection|,
879 |\subsubsection|, |\paragraph| and |\subparagraph|.
880
881 \item |depthpar=|\textit{depth}
882 (initially set to |5|) --
883 Set maximum sectioning depth to be displayed
884 in list of sessions
885 (similar to the standard \LaTeX{} counter |secnumdepth|).
886
887 \item |flags=|\textit{flags}
888 --
889 Specify a comma-separated list of flags.
890 Avoid spaces between flags.
891 \end{itemize}
892 %
893 Note that one can specify conditional evaluation for
894 the command |\timingconfigure| to, e.g.,
895 conditionally turn on automatic determination of sessions.
896
897 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
898 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
899 \section{Information}
900
901 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
902 \subsection{Copyright}
903
904 Copyright \copyright{} \thecopyright/
905
906 This work may be distributed and/or modified under the
907 conditions of the \LaTeX{} Project Public License, either version 1.3
908 of this license or (at your option) any later version.
909 The latest version of this license is in
910 \url{https://www.latex-project.org/lppl.txt}
911 and version 1.3c or later is part of all distributions of \LaTeX{}
912 version 2008 or later.
913
914 This work has the LPPL maintenance status `maintained'.
915
916 The Current Maintainer of this work is Niklas Beisert.
917
918 This work consists of the files
919 |README.txt|, \verbpkg|.ins| and \verbpkg|.dtx|
920 as well as the derived files listed below.
921
922 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
923 \subsection{Files and Installation}
924
925 The package consists of the files:
926 %
927 \begin{longtable}{ll}
928 |README.txt| & readme file \\
929 \verbpkg|.ins| & installation file \\
930 \verbpkg|.dtx| & source file \\
931 \verbpkg|.sty| & package file \\
932 \verbpkg|-samp.tex| & sample file \\
933 \verbpkg|-samp-3.tex| & sample include file \\
934 \verbpkg|-samp-4.tex| & sample include file \\
935 \verbpkg|.pdf| & documentation \\
936 \end{longtable}
937 %
938 The distribution consists of the files
939 |README.txt|, \verbpkg|.ins| and \verbpkg|.dtx|.
940 %
941 \begin{itemize}
942 \item
943 Run \LaTeX{} on \verbpkg|.ins| to create the package \verbpkg|.sty|
944 and further documentation files.
945 \item
946 Copy the file \verbpkg|.sty| to an appropriate directory of your \LaTeX{}
947 distribution, e.g.\ \textit{texmf-root}|/tex/latex/|\verbpkg.
948 \item
949 Alternatively, you may copy \verbpkg|.sty| to your project directory.
950 \item
951 Run (pdf)\LaTeX{} on \verbpkg|.dtx|
952 to compile the documentation \verbpkg|.pdf| (this file).
953 \end{itemize}
954
955 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
956 \subsection{Interaction with CTAN Packages}
957
958 The package relies on other packages:
959 \begin{itemize}
960 \item
961 This package uses the package \ctanpkg{keyval}
962 from the \ctanpkg{graphics} bundle
963 to process the options for the package, environments and macros.
964 Compatibility with the \ctanpkg{keyval} package
965 has been tested with v1.15 (\markdate{2014-10-28}).
966 \end{itemize}
967
968 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
969 \subsection{Feature Suggestions}
970 \label{sec:suggestions}
971
972 The following is a list of features which may be useful for future
973 versions of this package:
974 %
975 \begin{itemize}
976 \item
977 Option to display times as \textit{hh}|:|\textit{mm}.
978 % (or sessions:mm?!)
979 %\item
980 %start new block within block behaviour: ignore or next?
981 %\item
982 %flexible storage of section / paragraph titles
983 %in list of sessions? depending on numbering depth?
984 \item
985 Warnings for unknown or multiply defined labels or times.
986 %note that aux is read again at enddocument in order to
987 %compare the labels for changes.
988 %different signs for these two in the text?
989 \item
990 Display position of timing marks in two-sided documents.
991 \item
992 Ignore leading and trailing spaces in the list of flags.
993 \end{itemize}
994
995 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
996 \subsection{Revision History}
997
998 \iffalse
999
1000 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1001 \paragraph{vN.N.N+:} \markdate{20YY-MM-DD}
1002
1003 \begin{itemize}
1004 \item
1005 \ldots
1006 \end{itemize}
1007
1008 \fi
1009
1010 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1011 \paragraph{v1.1.4:} \markdate{2026-03-23}
1012
1013 \begin{itemize}
1014 \item
1015 use elementary register manipulations
1016 \item
1017 package maintenance
1018 \end{itemize}
1019
1020 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1021 \paragraph{v1.1.3:} \markdate{2025-03-25}
1022
1023 \begin{itemize}
1024 \item
1025 maintenance and manual update
1026 \end{itemize}
1027
1028 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1029 \paragraph{v1.12:} \markdate{2019-01-17}
1030
1031 \begin{itemize}
1032 \item
1033 bugfix for changed behaviour of |\smash| in \LaTeXe{} \markdate{2018-12-01}
1034 %https://github.com/latex3/latex2e/issues/108
1035 \end{itemize}
1036
1037 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1038 \paragraph{v1.11:} \markdate{2018-01-17}
1039
1040 \begin{itemize}
1041 \item
1042 bugfix for section titles including |\texorpdfstring|
1043 \end{itemize}
1044
1045 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1046 \paragraph{v1.1:} \markdate{2018-01-06}
1047
1048 \begin{itemize}
1049 \item
1050 grabbing of section titles improved
1051 \item
1052 options |depthsec| and |depthpar| to
1053 adjust depth in list of sessions
1054 \end{itemize}
1055
1056 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1057 \paragraph{v1.0:} \markdate{2017-05-01}
1058
1059 \begin{itemize}
1060 \item
1061 first version published on CTAN
1062 \item
1063 manual and install package
1064 \item
1065 bugfix chapter total
1066 \item
1067 minor display changes
1068 \item
1069 specify absolute times as \textit{hour}|:|\textit{minutes}
1070 \item
1071 block gauge
1072 \item
1073 conditional depending on flags
1074 \end{itemize}
1075
1076 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1077 \paragraph{v0.7:} \markdate{2017-04-17}
1078
1079 \begin{itemize}
1080 \item
1081 multiple flags
1082 \item
1083 chapter labels to access total times
1084 \item
1085 bugfix for open chapters and sessions at end of document (write immediately)
1086 \item
1087 display tuned, deactivate selected marks
1088 \item
1089 public interface streamlined
1090 \end{itemize}
1091
1092 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1093 \paragraph{v0.55 / v0.6:} \markdate{2017-04-01}
1094
1095 \begin{itemize}
1096 \item
1097 block display and preview
1098 \item
1099 made flags mechanism more flexible
1100 \item
1101 block start/split/stop/next uniformised; lapse added
1102 \end{itemize}
1103
1104 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1105 \paragraph{v0.5:} \markdate{2016-11-03}
1106
1107 \begin{itemize}
1108 \item
1109 basic functionality
1110 \end{itemize}
1111
1112 %</main|manual>
1113 %<*main>
1114 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1115 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1116 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1117
1118 \appendix
1119 %</main>
1120 %<*main|source>
1121 \raggedright
1122 \settowidth\MacroIndent{\rmfamily\scriptsize 000\ }
1123
1124 \DocInput{\thepkg/.dtx}
1125 %</main|source>
1126
1127 \end{document}
1128 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1129 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1130 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1131 %</main|manual|source>
1132 % \fi
1133 %
1134 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1135 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1136 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1137 %
1138 %
1139 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1140 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1141 % \section{Sample}
1142 % \label{sec:sample}
1143 % \iffalse
1144 %<*sample>
1145 % \fi
1146 %
1147 % In this section we provide an example of how to use
1148 % some of the \ctanpkg{sesstime} features.
1149 % We also test the behaviour in some special cases.
1150 %
1151 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1152 % \paragraph{Preamble.}
1153 %
1154 % Standard document class:
1155 % \begin{macrocode}
1156 \documentclass[12pt]{article}
1157 % \end{macrocode}
1158
1159 % Use package \ctanpkg{geometry} to adjust the page layout,
1160 % adjust the paragraph shape:
1161 % \begin{macrocode}
1162 \usepackage{geometry}
1163 \geometry{layout=a4paper}
1164 \geometry{paper=a4paper}
1165 \geometry{margin=3cm}
1166 \parindent0pt
1167 % \end{macrocode}
1168
1169 % Include the \ctanpkg{sesstime} package:
1170 % \begin{macrocode}
1171 \RequirePackage{sesstime}
1172 % \end{macrocode}
1173
1174 % Enable automatic assignment of sessions at 30 minutes each.
1175 % Optionally turn off all timing marks:
1176 % \begin{macrocode}
1177 \timingconfigure{autosession=30}
1178 %%\timingconfigure{print=false}
1179 % \end{macrocode}
1180
1181 % Declare schedule of lectures for a customised display:
1182 % \begin{macrocode}
1183 \newcommand{\sessiondate}[1]{\ifcase#1\\
1184 \or Mon 09:00%
1185 \or Mon 10:00%
1186 \or Tue 09:00%
1187 \or Fri 11:00%
1188 \or Fri 12:00%
1189 \else END%
1190 \fi}
1191 % \end{macrocode}
1192
1193 % Overwrite display of session marks:
1194 % \begin{macrocode}
1195 \renewcommand{\timingprintsession}[2]{\timingprintremark{%
1196 lecture #1\\
1197 \sessiondate{#1}%
1198 \timingsessiontotal[0]{#1}\ifnum\timingreturn>0%
1199 \\(\timingreturn\ min)%
1200 \ifnum #2>0\\at #2 min\fi\fi\vphantom{g}}}
1201 % \end{macrocode}
1202
1203 % Overwrite depth of sections in session list:
1204 % \begin{macrocode}
1205 \timingconfigure{depthsec=3,depthpar=4}
1206 % \end{macrocode}
1207
1208 % Overwrite display of sessions list:
1209 % \begin{macrocode}
1210 \renewcommand{\timingsessionline}[5]{\ \\%
1211 \makebox[2em][r]{#1. }%
1212 \makebox[5em][l]{\sessiondate{#1}:}%
1213 \makebox[2.5em][r]{#3. }%
1214 \makebox[10em][l]{\def\tmp{#5}\def\empty{}%
1215 \ifx\tmp\empty #4\else\S\ #5\fi}%
1216 \timingsessiontotal[0]{#1}\ifnum\timingreturn>0%
1217 \ [\timingreturn\ min\ifnum #2>0; #2 min into\fi]\fi}
1218 % \end{macrocode}
1219
1220 % Define a macro |\lorem| to write out some paragraph of text:
1221 % \begin{macrocode}
1222 \def\lorem{Lorem ipsum dolor sit amet, consectetur adipisici elit,
1223 sed eiusmod tempor incidunt ut labore et dolore magna aliqua.
1224 Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris
1225 nisi ut aliquid ex ea commodi consequat.
1226 Quis aute iure reprehenderit in voluptate velit esse
1227 cillum dolore eu fugiat nulla pariatur.
1228 Excepteur sint obcaecat cupiditat non proident,
1229 sunt in culpa qui officia deserunt mollit anim id est laborum.\par}
1230 % \end{macrocode}
1231
1232 % Start document body:
1233 % \begin{macrocode}
1234 \begin{document}
1235 % \end{macrocode}
1236
1237 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1238 % \paragraph{Chapter 1.}
1239 %
1240 % Basic test of functionality:
1241 % First block before subsections provides several intermediate times.
1242 % Both subsections are in individual blocks
1243 % separated by |\timingnext|.
1244 % Most times are specified in absolute terms,
1245 % merely last block is stopped after a relative time.
1246 % Manual display of total time in chapter:
1247 % \begin{macrocode}
1248 \section{one}
1249 \timingchapter
1250 \timingchapterlabel{one}
1251 \timingstart{0}
1252 total chapter duration: \timingchaptertotal{one}\timingreturn\ min\par
1253 \lorem
1254 \lorem
1255 \timingsplit{10}
1256 \lorem
1257 \timingsplit{15}
1258 \lorem
1259 \lorem
1260 \timingstop{25}
1261 \subsection{one.one}
1262 \timingstart{0}
1263 \lorem
1264 \subsection{one.two}
1265 \timingnext{15}
1266 \lorem
1267 \timingstop*{10}
1268 \timingchapterend
1269 % \end{macrocode}
1270
1271 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1272 % \paragraph{Chapter 2.}
1273 %
1274 % Test of some special cases.
1275 % Block started without previous block closed.
1276 % Specified absolute time leads to negative time evolved.
1277 % Absolute time specified as \textit{hour}:\textit{minutes}.
1278 % Manual display of time in block (before or after start).
1279 % Behaviour within paragraph (display active/disabled):
1280 % \begin{macrocode}
1281 \section{two}
1282 \timingchapter
1283 total following block: \timingblocktotal*\timingreturn\ min\par
1284 \timingstart{0:15}
1285 total current block: \timingblocktotal\timingreturn\ min\par
1286 \lorem
1287 \subsection{two.one}
1288 \timingsplit*{10}
1289 \lorem
1290 \timingstart{0}
1291 \subsection{two.two}
1292 \timingsplit{40}
1293 \lorem
1294 \timingsplit{30}
1295 \lorem
1296 \timingstop{1:00}
1297 \subsection{two.three}
1298 \timingstart{0}
1299 \lorem
1300 some text broken
1301 \timingsplit{10}
1302 by active timing mark\par
1303 \lorem
1304 some text broken
1305 {\timingconfigure{print=false}\timingsplit{15}}%
1306 by inactive timing mark\par
1307 \lorem
1308 \timingstop{30}
1309 % \end{macrocode}
1310
1311 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1312 % \paragraph{Included Chapters 3 and 4.}
1313 %
1314 % Test of interoperability with |\include| mechanism:
1315 % \begin{macrocode}
1316 \include{\jobname-3}
1317 \include{\jobname-4}
1318 % \end{macrocode}
1319
1320 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1321 % \paragraph{Chapter 5.}
1322 %
1323 % Just another chapter with paragraphs:
1324 % \begin{macrocode}
1325 \section{five}
1326 \timingchapter
1327 \paragraph{five.paragraph.}
1328 \lorem
1329 \timingstart{0}
1330 \lorem
1331 \timingsplit*{15}
1332 \lorem
1333 \timingsplit*{15}
1334 \subsection{five.one}
1335 \lorem
1336 \timingsplit*{15}
1337 \paragraph{five.one.paragraph.}
1338 \lorem
1339 \timingsplit*{15}
1340 \subsection{five.two}
1341 \paragraph{five.two.paragraph.}
1342 \timingsession
1343 \lorem
1344 \timingsplit*{15}
1345 \subparagraph{five.two.subparagraph.}
1346 \timingsession
1347 \lorem
1348 \timingsplit*{15}
1349 \lorem
1350 \timingstop*{15}
1351 \timingchapterend
1352 % \end{macrocode}
1353
1354 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1355 % \paragraph{Chapter 6.}
1356 %
1357 % Test of |\timinglapse| and |\timinggauge|:
1358 % \begin{macrocode}
1359 \section{six}
1360 \timingchapter
1361 \timinglapse{5}
1362 \timingstart{10}
1363 \lorem
1364 \timinglapse{-5}
1365 \lorem
1366 \timingstop{20}
1367 \lorem
1368 \timinglapse{5}
1369 \timingstart{20}
1370 \lorem
1371 \timingsplit{30}
1372 \timinggauge{10}
1373 \lorem
1374 \timingstop{20}
1375 \timingchapterend
1376 % \end{macrocode}
1377
1378 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1379 % \paragraph{Comments and Flags.}
1380 %
1381 % Test comments and flags/conditionals:
1382 % \begin{macrocode}
1383 \section{flags}
1384 \timingcomment{test comments}
1385 set flags `two' and `three':\timingconfigure{flags={two,three}}\par
1386 one? \timingif[if=one]{yes}\par
1387 two? \timingif[if=two]{yes}\par
1388 one or two? \timingif[if=one,if=two]{yes}\par
1389 not one? \timingif[not=one]{yes}\par
1390 not two? \timingif[not=two]{yes}\par
1391 not one or not two? \timingif[not=one,not=two]{yes}\par
1392 % \end{macrocode}
1393
1394 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1395 % \paragraph{List of Sessions.}
1396 %
1397 % Test the List of Sessions.
1398 % \begin{macrocode}
1399 \appendix
1400 \section{list of sessions}
1401 the list of sessions
1402 \timinglistofsessions
1403 % \end{macrocode}
1404
1405 % End of document body:
1406 % \begin{macrocode}
1407 \end{document}
1408 % \end{macrocode}
1409 % \iffalse
1410 %</sample>
1411 % \fi
1412 %
1413 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1414 % \paragraph{Chapters 3 and 4 Include Files.}
1415 %
1416 % A standard chapter in an included file \verbpkg|-samp-3.tex|:
1417 % \iffalse
1418 %<*sample3>
1419 % \fi
1420 % \begin{macrocode}
1421 \section{three}
1422 \timingchapter
1423 \timingstart{30}
1424 \lorem
1425 \subsection{three.one}
1426 \timingsplit{35}
1427 \lorem
1428 \subsection{three.two}
1429 \timingsplit{40}
1430 \lorem
1431 \timingsplit{50}
1432 \lorem
1433 \timingstop{60}
1434 \timingchapterend
1435 % \end{macrocode}
1436 % \iffalse
1437 %</sample3>
1438 % \fi
1439 %
1440 % Another chapter in an included file \verbpkg|-samp-4.tex|.
1441 % Test a very long interval to let automatic session generation overflow:
1442 % \iffalse
1443 %<*sample4>
1444 % \fi
1445 % \begin{macrocode}
1446 \section{four}
1447 \timingchapter
1448 \timingstart{0}
1449 \lorem
1450 \subsection{four.one}
1451 \timingstop{25}
1452 \lorem
1453 \timingstart{-20}
1454 \subsection{four.two}
1455 \timingsplit{40}
1456 \lorem
1457 \timingsplit{50}
1458 \lorem
1459 \timingstop{60}
1460 \timingchapterend
1461 % \end{macrocode}
1462 % \iffalse
1463 %</sample4>
1464 % \fi
1465 %
1466 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1467 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1468 % \section{Implementation}
1469 % \label{sec:implementation}
1470 % \iffalse
1471 %<*package>
1472 % \fi
1473 %
1474 % In this section we describe the package \verbpkg|.sty|.
1475 %
1476 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1477 % \paragraph{Required Packages.}
1478 %
1479 % The package loads the package
1480 % \ctanpkg{keyval}
1481 % if not yet present.
1482 % \ctanpkg{keyval} is used for extended options processing:
1483 % \begin{macrocode}
1484 \RequirePackage{keyval}
1485 % \end{macrocode}
1486
1487 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1488 % \paragraph{Flags.}
1489 %
1490 % The following code compares flags for a command
1491 % against a global list of flags for optional processing of the command.
1492 %
1493 % \macro{\sti@processflags}
1494 % \macro{\ifsti@flag}
1495 % Declare variables for processing.
1496 % |\sti@flags| stores the list of selected flags.
1497 % |\ifsti@flag| is set by |\sti@processflags|.
1498 % |\ifsti@flaginit| is used to detect the first specified key:
1499 % \begin{macrocode}
1500 \def\sti@flags{}
1501 \newif\ifsti@flag
1502 \newif\ifsti@flaginit
1503 % \end{macrocode}
1504 % Compare given flag to list of flags stored in |\sti@flags|;
1505 % set |\ifsti@flag| accordingly.
1506 % First key sets default to opposite of specified condition:
1507 % \begin{macrocode}
1508 \define@key{sti@flag}{if}{%
1509 \ifsti@flaginit\else\sti@flagfalse\fi\sti@flaginittrue
1510 \def\sti@tmpa{#1}%
1511 \@for\sti@tmpb:=\sti@flags\do{\ifx\sti@tmpb\sti@tmpa\sti@flagtrue\fi}}
1512 \define@key{sti@flag}{not}{%
1513 \ifsti@flaginit\else\sti@flagtrue\fi\sti@flaginittrue
1514 \def\sti@tmpa{#1}%
1515 \@for\sti@tmpb:=\sti@flags\do{\ifx\sti@tmpb\sti@tmpa\sti@flagfalse\fi}}
1516 % \end{macrocode}
1517 % Initialise and process keys:
1518 % \begin{macrocode}
1519 \newcommand{\sti@processflags}[1]{\sti@flagtrue\sti@flaginitfalse
1520 \setkeys{sti@flag}{#1}}
1521 % \end{macrocode}
1522
1523 % \macro{\timingif}
1524 % Conditional processing:
1525 % \begin{macrocode}
1526 \newcommand{\timingif}[2][]{\sti@processflags{#1}\ifsti@flag#2\fi}
1527 % \end{macrocode}
1528
1529 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1530 % \paragraph{Internal Definitions.}
1531 %
1532 % The following definitions store package options.
1533 % The conditional |\ifsti@print|[|...|]
1534 % indicates whether timing marks (of particular kind) should be printed.
1535 % The dimensions |\sti@widthl| and |\sti@widthr| store
1536 % the width of timing marks on the left and right, respectively.
1537 % |sti@autosession| stores the duration of automatically generated sessions.
1538 % |\sti@depthsec| and |\sti@depthpar| store the depth of sections
1539 % to be included in the list of sessions:
1540 % \begin{macrocode}
1541 \newif\ifsti@print\sti@printtrue
1542 \newif\ifsti@printblock\sti@printblocktrue
1543 \newif\ifsti@printsession\sti@printsessiontrue
1544 \newif\ifsti@printchapter\sti@printchaptertrue
1545 \newif\ifsti@printwarning\sti@printwarningtrue
1546 \newif\ifsti@printcomment\sti@printcommenttrue
1547 \newdimen\sti@widthl\sti@widthl1cm\relax
1548 \newdimen\sti@widthr\sti@widthr1cm\relax
1549 \newcounter{sti@autosession}
1550 \def\sti@depthsec{3}
1551 \def\sti@depthpar{5}
1552 % \end{macrocode}
1553
1554 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1555 % \paragraph{Package Options.}
1556 %
1557 % Declare package options:
1558 % \begin{macrocode}
1559 \define@key{sti@}{print}[true]{\csname sti@print#1\endcsname}
1560 \define@key{sti@}{block}[true]{\csname sti@printblock#1\endcsname}
1561 \define@key{sti@}{chapter}[true]{\csname sti@printchapter#1\endcsname}
1562 \define@key{sti@}{session}[true]{\csname sti@printsession#1\endcsname}
1563 \define@key{sti@}{warning}[true]{\csname sti@printwarning#1\endcsname}
1564 \define@key{sti@}{comment}[true]{\csname sti@printcomment#1\endcsname}
1565 \define@key{sti@}{width}{\sti@widthl\dimexpr#1\relax\sti@widthl\sti@widthr}
1566 \define@key{sti@}{widthl}{\sti@widthl\dimexpr#1\relax}
1567 \define@key{sti@}{widthr}{\sti@widthr\dimexpr#1\relax}
1568 \define@key{sti@}{autosession}{\c@sti@autosession\numexpr#1\relax}
1569 \define@key{sti@}{flags}{\def\sti@flags{#1}}
1570 \define@key{sti@}{depthsec}{\def\sti@depthsec{#1}}
1571 \define@key{sti@}{depthpar}{\def\sti@depthpar{#1}}
1572 % \end{macrocode}
1573
1574 % \macro{\timingconfigure}
1575 % Configure package options:
1576 % \begin{macrocode}
1577 \newcommand{\timingconfigure}[2][]{%
1578 \sti@processflags{#1}%
1579 \ifsti@flag
1580 \setkeys{sti@}{#2}%
1581 \fi}
1582 % \end{macrocode}
1583
1584 % Pass undeclared options on to \ctanpkg{keyval} processing:
1585 % \begin{macrocode}
1586 \DeclareOption*{\expandafter\timingconfigure\expandafter{\CurrentOption}}
1587 % \end{macrocode}
1588 %
1589 % Process package options:
1590 % \begin{macrocode}
1591 \ProcessOptions
1592 % \end{macrocode}
1593
1594 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1595 % \paragraph{Internal Variables.}
1596 %
1597 % Declare internal variables and counters.
1598 % As they describe the status which may change
1599 % in include files, they are declared as counters
1600 % which are automatically stored in |.aux| files.
1601 % Status variables for sessions (counter, within session, time elapsed):
1602 % \begin{macrocode}
1603 \newcounter{sti@session}
1604 \newcounter{sti@insession}
1605 \newcounter{sti@sessiontime}
1606 % \end{macrocode}
1607 % Status variables for chapters (counter, within session, time elapsed):
1608 % \begin{macrocode}
1609 \newcounter{sti@chapter}
1610 \newcounter{sti@inchapter}
1611 \newcounter{sti@chaptertime}
1612 % \end{macrocode}
1613 % Status variables for blocks (counter, within session,
1614 % reference time, time elapsed):
1615 % \begin{macrocode}
1616 \newcounter{sti@block}[sti@chapter]
1617 \newcounter{sti@inblock}
1618 \newcounter{sti@blockgauge}
1619 \newcounter{sti@blocktime}
1620 % \end{macrocode}
1621 % Temporary counter:
1622 % \begin{macrocode}
1623 \newcount\sti@delta
1624 % \end{macrocode}
1625
1626 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1627 % \paragraph{Print Marks.}
1628 %
1629 % \macro{\timingprint}
1630 % Print a timing mark into left or right margin.
1631 % Leave horizontal mode and print only in vertical mode:
1632 % \begin{macrocode}
1633 \newcommand{\timingprint}[2][l]{%
1634 \ifsti@print
1635 \ifhmode\par\fi
1636 \ifvmode
1637 \@bsphack
1638 \dimen@\prevdepth
1639 \nointerlineskip
1640 \if r#1%
1641 \hbox{\smash{\rlap{\hspace{\textwidth}\parbox[t]{\sti@widthr}%
1642 {\raggedright\renewcommand{\bfdefault}{b}#2}}}}%
1643 \else
1644 \hbox{\smash{\llap{\parbox[t]{\sti@widthl}%
1645 {\raggedleft\renewcommand{\bfdefault}{b}#2}}}}%
1646 \fi
1647 \prevdepth\dimen@
1648 \@esphack
1649 \fi
1650 \else
1651 \ignorespaces
1652 \fi}
1653 % \end{macrocode}
1654
1655 % \macro{\timingprintmark}
1656 % \macro{\timingprintremark}
1657 % Print a timing mark or a remark:
1658 % \begin{macrocode}
1659 \providecommand{\timingprintmark}[1]{%
1660 \timingprint{\footnotesize#1}}
1661 \providecommand{\timingprintremark}[1]{%
1662 \timingprint[r]{\tiny\sffamily\hrule#1\hrule}}
1663 % \end{macrocode}
1664
1665 % \macro{\sti@warn}
1666 % Print a warning message:
1667 % \begin{macrocode}
1668 \newcommand{\sti@warn}[2][l]{\ifsti@printwarning
1669 \timingprint[#1]{\scriptsize\textbf{warn}\\#2}\fi}
1670 % \end{macrocode}
1671
1672 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1673 % \paragraph{Comments.}
1674 %
1675 % \macro{\timingprintcomment}
1676 % Print a comment:
1677 % \begin{macrocode}
1678 \newcommand{\timingcomment}[2][]{%
1679 \sti@processflags{#1}%
1680 \ifsti@flag
1681 \ifsti@printcomment\timingprintremark{#2}\fi
1682 \fi}
1683 % \end{macrocode}
1684
1685 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1686 % \paragraph{Sessions.}
1687 %
1688 % \macro{\sti@notesessiontotal}
1689 % \macro{\sti@writesessiontotal}
1690 % The following code remembers the duration of sessions.
1691 % The duration is stored in the macro |\sti@sessiontotal@|\textit{session}:
1692 % \begin{macrocode}
1693 \newcommand{\sti@notesessiontotal}[2]{%
1694 \expandafter\gdef\csname sti@sessiontotal@#1\endcsname{#2}}
1695 % \end{macrocode}
1696 % A blank definition of the above macro is written
1697 % to the |.aux| file to avoid compile errors
1698 % in case the package is removed:
1699 % \begin{macrocode}
1700 \AtBeginDocument{\immediate\write\@auxout{%
1701 \string\providecommand{\string\sti@notesessiontotal}[2]{}}}
1702 % \end{macrocode}
1703 % Writes the duration of the current session to the |.aux| file:
1704 % \begin{macrocode}
1705 \newcommand{\sti@writesessiontotal}[1]
1706 {\immediate\write\@auxout{\string\sti@notesessiontotal
1707 {\thesti@session}{#1}}}
1708 % \end{macrocode}
1709
1710 % \macro{\timingsessiontotal}
1711 % Save the duration of session number in the argument into |\timingreturn|.
1712 % Return the optional argument if the duration is unavailable:
1713 % \begin{macrocode}
1714 \newcommand{\timingsessiontotal}[2][??]{%
1715 \expandafter\let\expandafter\timingreturn
1716 \csname sti@sessiontotal@#2\endcsname
1717 \ifx\timingreturn\relax\def\timingreturn{#1}\fi}
1718 % \end{macrocode}
1719
1720 % \macro{\sti@recordtitle}
1721 % \macro{\sti@secnum}
1722 % \macro{\sti@sectitle}
1723 % \macro{\sti@partitle}
1724 % Record the present sectioning title and number
1725 % for usage in the list of sessions.
1726 % The depth in the first parameter in comparison to
1727 % |\sti@depthsec| and |\sti@depthpar| determines
1728 % whether the information is stored as section or paragraph:
1729 % \begin{macrocode}
1730 \newcommand{\sti@recordtitle}[4]{\ifnum#2>\sti@depthpar\else
1731 \ifnum#2>\sti@depthsec
1732 \gdef\sti@partitle{#4}%
1733 \else
1734 \xdef\sti@secnum{#3}%
1735 \gdef\sti@sectitle{#4}%
1736 \gdef\sti@partitle{}%
1737 \fi\fi}
1738 % \end{macrocode}
1739
1740 % \macro{\@startsection}
1741 % The following code hooks into the definition
1742 % of |\@startsection| to record titles and numbers:
1743 % \begin{macrocode}
1744 \let\sti@old@startsection\@startsection
1745 \def\@startsection#1#2#3#4#5#6{\@ifstar
1746 {\sti@ssect{#1}{#2}{#3}{#4}{#5}{#6}}%
1747 {\@dblarg{\sti@sect{#1}{#2}{#3}{#4}{#5}{#6}}}}
1748 \def\sti@ssect#1#2#3#4#5#6#7{\sti@recordtitle{#1}{#2}{}{#7}%
1749 \sti@old@startsection{#1}{#2}{#3}{#4}{#5}{#6}*{#7}}
1750 \def\sti@sect#1#2#3#4#5#6[#7]#8{{\advance\csname c@#1\endcsname1%
1751 \sti@recordtitle{#1}{#2}{\csname the#1\endcsname}{#7}}%
1752 \sti@old@startsection{#1}{#2}{#3}{#4}{#5}{#6}[#7]{#8}}
1753 % \end{macrocode}
1754
1755 % \macro{\chapter}
1756 % The following code similarly hooks into the definitions
1757 % of |\chapter| (if defined):
1758 % \begin{macrocode}
1759 \ifdefined\chapter
1760 \let\sti@old@chapter\chapter
1761 \def\chapter{\@ifstar\sti@schapter{\@dblarg{\sti@chapter}}}
1762 \def\sti@schapter#1{\sti@recordtitle{chapter}{0}{}{#1}\sti@old@chapter*{#1}}
1763 \def\sti@chapter[#1]#2{{\advance\c@chapter1%
1764 \sti@recordtitle{chapter}{0}{\thechapter}{#1}}\sti@old@chapter[#1]{#2}}
1765 \fi
1766 % \end{macrocode}
1767
1768 % \macro{\timingprintsession}
1769 % Print the mark for the current session.
1770 % Indicate the number and duration of the session as well as
1771 % the time into the session at which the label is printed (if applicable).
1772 % The arguments are
1773 % |#1| session number,
1774 % |#2| time into session:
1775 % \begin{macrocode}
1776 \providecommand{\timingprintsession}[2]{\timingprintremark{%
1777 session #1%
1778 \timingsessiontotal[0]{#1}\ifnum\timingreturn>\z@
1779 \\(\timingreturn\ min)%
1780 \ifnum #2>\z@\\at #2 min\fi\fi\vphantom{g}}}
1781 % \end{macrocode}
1782
1783 % \macro{\sti@startsession}
1784 % Initialise a new session:
1785 % \begin{macrocode}
1786 \newcommand{\sti@startsession}{%
1787 \c@sti@insession\@ne
1788 \advance\c@sti@session\@ne
1789 \ifsti@printsession
1790 \timingprintsession\thesti@session\thesti@sessiontime
1791 \fi
1792 \sti@addsessionline}
1793 % \end{macrocode}
1794
1795 % \macro{\sti@endsession}
1796 % Close a session:
1797 % \begin{macrocode}
1798 \newcommand{\sti@endsession}[1]{%
1799 \sti@writesessiontotal{#1}%
1800 \c@sti@insession\z@
1801 }
1802 % \end{macrocode}
1803
1804 % \macro{\sti@checksession}
1805 % Check whether a new session should be started in autosession mode
1806 % based on the time elapsed since the start of the present session.
1807 % Assumes that the session has a fixed duration so that the
1808 % total number of sessions approximates well the total duration.
1809 % In case of coarse graining of timing information,
1810 % the actual start of a session may be earlier.
1811 % Recurse if necessary:
1812 % \begin{macrocode}
1813 \newcommand{\sti@checksession}{%
1814 \ifnum\c@sti@autosession>\z@
1815 \ifodd\c@sti@insession
1816 \ifnum\c@sti@sessiontime<\c@sti@autosession\else
1817 \sti@endsession\thesti@autosession
1818 \advance\c@sti@sessiontime-\c@sti@autosession
1819 \sti@startsession
1820 \sti@checksession
1821 \fi
1822 \else
1823 \c@sti@sessiontime\z@
1824 \sti@startsession
1825 \fi
1826 \fi}
1827 % \end{macrocode}
1828
1829 % \macro{\timingsession}
1830 % Start a new session. End old session if necessary:
1831 % \begin{macrocode}
1832 \newcommand{\timingsession}[1][]{%
1833 \sti@processflags{#1}%
1834 \ifsti@flag
1835 \ifodd\c@sti@insession
1836 \sti@endsession\thesti@sessiontime
1837 \fi
1838 \c@sti@sessiontime\z@
1839 \sti@startsession
1840 \fi\ignorespaces}
1841 % \end{macrocode}
1842
1843 % \macro{\timingsessionend}
1844 % End the session (if started).
1845 % Remember session duration:
1846 % \begin{macrocode}
1847 \newcommand{\timingsessionend}[1][]{%
1848 \sti@processflags{#1}%
1849 \ifsti@flag
1850 \ifodd\c@sti@insession
1851 \sti@endsession\thesti@sessiontime
1852 \c@sti@sessiontime\z@
1853 \fi
1854 \fi\ignorespaces}
1855 % \end{macrocode}
1856 % End the session at the end of the document:
1857 % \begin{macrocode}
1858 \AtEndDocument{\timingsessionend}
1859 % \end{macrocode}
1860
1861 % \macro{\timinglistofsessions}
1862 % \macro{\timingsessionline}
1863 % \macro{\sti@addsessionline}
1864 % Display the list of sessions (without a section title):
1865 % \begin{macrocode}
1866 \newcommand{\timinglistofsessions}{\@starttoc{los}}
1867 % \end{macrocode}
1868 % Display one line within the list of session.
1869 % The arguments are
1870 % |#1| session number,
1871 % |#2| time into session,
1872 % |#3| section identifier,
1873 % |#4| section title,
1874 % |#5| paragraph title:
1875 % \begin{macrocode}
1876 \providecommand{\timingsessionline}[5]{\ \\%
1877 \makebox[3em][r]{#1: }\makebox[2.5em][r]{#3. }%
1878 \def\sti@tmp{#5}\ifx\sti@tmp\@empty #4\else\S\ #5\fi
1879 \timingsessiontotal[0]{#1}\ifnum\timingreturn>\z@
1880 \ [\timingreturn\ min\ifnum #2>\z@; #2 min into\fi]\fi}
1881 % \end{macrocode}
1882 % Add a line to the list of sessions:
1883 % \begin{macrocode}
1884 \newcommand{\sti@addsessionline}{%
1885 \addtocontents{los}{\protect\timingsessionline
1886 {\thesti@session}{\thesti@sessiontime}%
1887 {\sti@secnum}{\sti@sectitle}{\sti@partitle}}}%
1888 % \end{macrocode}
1889
1890 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1891 % \paragraph{Chapters.}
1892 %
1893 % \macro{\sti@notechaptertotal}
1894 % \macro{\sti@writechaptertotal}
1895 % The following code remembers the duration of chapters.
1896 % Store the duration in the macro
1897 % |\sti@chaptertotal@|\textit{chapter}:
1898 % \begin{macrocode}
1899 \newcommand{\sti@notechaptertotal}[2]{%
1900 \expandafter\gdef\csname sti@chaptertotal@#1\endcsname{#2}}
1901 % \end{macrocode}
1902 % A blank definition of the above macro is written
1903 % to the |.aux| file to avoid compile errors
1904 % in case the package is removed:
1905 % \begin{macrocode}
1906 \AtBeginDocument{\immediate\write\@auxout{%
1907 \string\providecommand{\string\sti@notechaptertotal}[2]{}}}
1908 % \end{macrocode}
1909 % Write the duration of the current chapter to the |.aux| file:
1910 % \begin{macrocode}
1911 \newcommand{\sti@writechaptertotal}{%
1912 \immediate\write\@auxout{\string\sti@notechaptertotal
1913 {\thesti@chapter}{\thesti@chaptertime}}}
1914 % \end{macrocode}
1915
1916 % \macro{\timingchapterlabel}
1917 % \macro{\sti@notechapterlabel}
1918 % The following code remembers labels for chapters.
1919 % Store the chapter number in the macro
1920 % |\sti@chapterlabel@|\textit{label}:
1921 % \begin{macrocode}
1922 \newcommand{\sti@notechapterlabel}[2]{%
1923 \expandafter\gdef\csname sti@chapterlabel@#1\endcsname{#2}}
1924 % \end{macrocode}
1925 % A blank definition of the above macro is written
1926 % to the |.aux| file to avoid compile errors
1927 % in case the package is removed:
1928 % \begin{macrocode}
1929 \AtBeginDocument{\immediate\write\@auxout{%
1930 \string\providecommand{\string\sti@notechapterlabel}[2]{}}}
1931 % \end{macrocode}
1932 % Write a label for the current chapter to the |.aux| file:
1933 % \begin{macrocode}
1934 \newcommand{\timingchapterlabel}[1]{%
1935 \immediate\write\@auxout{\string\sti@notechapterlabel
1936 {#1}{\thesti@chapter}}}
1937 % \end{macrocode}
1938
1939 % \macro{\timingchaptertotal}
1940 % Save the total duration of a chapter into the macro |\timingreturn|.
1941 % Return the optional argument if unavailable.
1942 % Version specifying the chapter by its number:
1943 % \begin{macrocode}
1944 \newcommand{\sti@chaptertotalnumber}[2][??]{%
1945 \expandafter\let\expandafter\timingreturn
1946 \csname sti@chaptertotal@#2\endcsname
1947 \ifx\timingreturn\relax\def\timingreturn{#1}\fi}
1948 % \end{macrocode}
1949 % Version specifying the chapter by its label:
1950 % \begin{macrocode}
1951 \newcommand{\sti@chaptertotallabel}[2][??]{%
1952 \expandafter\let\expandafter\timingreturn
1953 \csname sti@chapterlabel@#2\endcsname
1954 \ifx\timingreturn\relax\else
1955 \expandafter\let\expandafter\timingreturn
1956 \csname sti@chaptertotal@\timingreturn\endcsname\fi
1957 \ifx\timingreturn\relax\def\timingreturn{#1}\fi}
1958 % \end{macrocode}
1959 % Version selection:
1960 % \begin{macrocode}
1961 \newcommand{\timingchaptertotal}{%
1962 \@ifstar\sti@chaptertotalnumber\sti@chaptertotallabel}
1963 % \end{macrocode}
1964
1965 % \macro{\timingprintchapter}
1966 % Print the mark for the present chapter:
1967 % \begin{macrocode}
1968 \providecommand\timingprintchapter[1]{\timingprintmark{\raisebox{2.8ex}{%
1969 \textbf{\timingchaptertotal*{#1}\timingreturn}%
1970 \rlap{\kern0.4em$\star$}\kern1.2em}}}
1971 % \end{macrocode}
1972
1973 % \macro{\timingchapter}
1974 % Start a new chapter. End old chapter if necessary:
1975 % \begin{macrocode}
1976 \newcommand{\timingchapter}[1][]{%
1977 \sti@processflags{#1}%
1978 \ifsti@flag
1979 \ifodd\c@sti@inblock
1980 \PackageWarning{sesstime}{chapter: still in block; stopped}%
1981 \sti@warn{chap}%
1982 \sti@blockstop{}{}{0}%
1983 \fi
1984 \timingchapterend
1985 \c@sti@inchapter\@ne
1986 \c@sti@chaptertime\z@
1987 \advance\c@sti@chapter\@ne
1988 \c@sti@block\z@
1989 \ifsti@printchapter\timingprintchapter\thesti@chapter\fi
1990 \fi\ignorespaces}
1991 % \end{macrocode}
1992
1993 % \macro{\timingchapterend}
1994 % End the chapter (if started).
1995 % Remember chapter duration:
1996 % \begin{macrocode}
1997 \newcommand{\timingchapterend}[1][]{%
1998 \sti@processflags{#1}%
1999 \ifsti@flag
2000 \ifodd\c@sti@inblock
2001 \PackageWarning{sesstime}{chapterend: still in block; stopped}%
2002 \sti@warn{chap}%
2003 \sti@blockstop{}{}{0}%
2004 \fi
2005 \ifodd\c@sti@inchapter
2006 \sti@writechaptertotal
2007 \c@sti@inchapter\z@
2008 \c@sti@chaptertime\z@
2009 \fi
2010 \fi\ignorespaces}
2011 % \end{macrocode}
2012 % End the chapter at the end of document:
2013 % \begin{macrocode}
2014 \AtEndDocument{\timingchapterend}
2015 % \end{macrocode}
2016
2017 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2018 % \paragraph{Blocks.}
2019 %
2020 % \macro{\sti@writeblocktotal}
2021 % \macro{\sti@noteblocktotal}
2022 % The following code remembers the duration of blocks.
2023 % Store the duration in the macro
2024 % |\sti@blocktotal@|\textit{chapter}|@|\textit{block}:
2025 % \begin{macrocode}
2026 \newcommand{\sti@noteblocktotal}[3]{%
2027 \expandafter\gdef\csname sti@blocktotal@#1@#2\endcsname{#3}}
2028 % \end{macrocode}
2029 % A blank definition of the above macro is written
2030 % to the |.aux| file to avoid compile errors
2031 % in case the package is removed:
2032 % \begin{macrocode}
2033 \AtBeginDocument{\immediate\write\@auxout
2034 {\string\providecommand{\string\sti@noteblocktotal}[3]{}}}
2035 % \end{macrocode}
2036 % Write the duration of the current block to the |.aux| file:
2037 % \begin{macrocode}
2038 \newcommand{\sti@writeblocktotal}{%
2039 \immediate\write\@auxout{\string\sti@noteblocktotal
2040 {\thesti@chapter}{\thesti@block}{\thesti@blocktime}}}
2041 % \end{macrocode}
2042
2043 % \macro{\timingblocktotal}
2044 % Save the duration of the current block
2045 % (in starred form: subsequent block) into the macro |\timingreturn|.
2046 % Return optional argument if the duration is unavailable.
2047 % Version for current block:
2048 % \begin{macrocode}
2049 \newcommand{\sti@blocktotalcurrent}[1][??]{%
2050 \expandafter\let\expandafter\timingreturn
2051 \csname sti@blocktotal@\thesti@chapter @\thesti@block\endcsname
2052 \ifx\timingreturn\relax\def\timingreturn{#1}\fi}
2053 % \end{macrocode}
2054 % Version for subsequent block:
2055 % \begin{macrocode}
2056 \newcommand{\sti@blocktotalnext}[1][??]{%
2057 \expandafter\let\expandafter\timingreturn
2058 \csname sti@blocktotal@\thesti@chapter
2059 @\the\numexpr\c@sti@block+1\relax\endcsname
2060 \ifx\timingreturn\relax\def\timingreturn{#1}\fi}
2061 % \end{macrocode}
2062 % Version selection:
2063 % \begin{macrocode}
2064 \newcommand{\timingblocktotal}{%
2065 \@ifstar\sti@blocktotalnext\sti@blocktotalcurrent}
2066 % \end{macrocode}
2067
2068 % \macro{\timingprintblock}
2069 % Print block timing mark:
2070 % \begin{macrocode}
2071 \newcommand{\timingprintblock}[3]{\timingprintmark{%
2072 \def\sti@tmp{#2}\ifx\sti@tmp\@empty
2073 \raisebox{-1ex}{#1\rlap{\kern0.4em$\Updownarrow$}}\kern1.2em%
2074 \else
2075 \def\sti@tmp{#1}\ifx\sti@tmp\@empty\else
2076 #1\rlap{\kern0.4em$\Uparrow$%
2077 \vphantom{$\Updownarrow$}}\kern1.2em\hrule\fi
2078 \textbf{#2}\rlap{\vphantom{$\Updownarrow$}}\kern1.2em%
2079 \def\sti@tmp{#3}\ifx\sti@tmp\@empty\else
2080 \hrule#3\rlap{\kern0.4em$\Downarrow$%
2081 \vphantom{$\Updownarrow$}}\kern1.2em\fi
2082 \fi}}
2083 % \end{macrocode}
2084
2085 % \macro{\sti@advance}
2086 % Advance all running clocks by some amount of time:
2087 % \begin{macrocode}
2088 \newcommand{\sti@advance}{%
2089 \ifodd\c@sti@inblock\advance\c@sti@blocktime\sti@delta\fi
2090 \ifodd\c@sti@inchapter\advance\c@sti@chaptertime\sti@delta\fi
2091 \ifodd\c@sti@insession\advance\c@sti@sessiontime\sti@delta\fi}
2092 % \end{macrocode}
2093
2094 % \macro{\sti@hoursminutes}
2095 % Convert hours:minutes format to minutes:
2096 % \begin{macrocode}
2097 \def\sti@hoursminutes#1:#2:#3!{%
2098 \sti@delta\numexpr#1\relax
2099 \if!#3!\else
2100 \sti@delta\numexpr60*\sti@delta+#2\relax
2101 \fi}
2102 % \end{macrocode}
2103
2104 % \macro{\sti@computedelta}
2105 % Convert an absolute time to a relative time:
2106 % \begin{macrocode}
2107 \newcommand{\sti@computedelta}{%
2108 \advance\sti@delta\numexpr-\c@sti@blockgauge-\c@sti@blocktime\relax}
2109 % \end{macrocode}
2110
2111 % \macro{\sti@warnneg}
2112 % Warn if negative time elapsed:
2113 % \begin{macrocode}
2114 \newcommand{\sti@warnneg}{%
2115 \ifnum\sti@delta<\z@
2116 \PackageWarning{sesstime}{block: negative time elapsed}%
2117 \sti@warn{neg}%
2118 \fi}
2119 % \end{macrocode}
2120
2121 % \macro{\timingstart}
2122 % Start new block:
2123 % \begin{macrocode}
2124 \newcommand{\sti@blockstart}[3]{%
2125 \sti@processflags{#1}%
2126 \ifsti@flag
2127 \ifodd\c@sti@inblock
2128 \PackageWarning{sesstime}{already in block}%
2129 \sti@warn{block}
2130 \else
2131 \sti@hoursminutes#3::!%
2132 #2%
2133 \c@sti@inblock\@ne
2134 \advance\c@sti@blockgauge\numexpr\c@sti@blocktime+\sti@delta\relax
2135 \c@sti@blocktime\z@
2136 \advance\c@sti@block\@ne
2137 \sti@checksession
2138 \ifsti@printblock
2139 \sti@blocktotalcurrent
2140 \timingprintblock{}\thesti@chaptertime\timingreturn
2141 \fi
2142 \fi
2143 \fi\nopagebreak}
2144 % \end{macrocode}
2145 % Version selection:
2146 % \begin{macrocode}
2147 \newcommand{\sti@blockstartat}[1][]{\sti@blockstart{#1}\sti@computedelta}
2148 \newcommand{\sti@blockstartby}[1][]{\sti@blockstart{#1}{}}
2149 \newcommand{\timingstart}{\@ifstar\sti@blockstartby\sti@blockstartat}
2150 % \end{macrocode}
2151
2152 % \macro{\timingsplit}
2153 % Split current block:
2154 % \begin{macrocode}
2155 \newcommand{\sti@blocksplit}[3]{%
2156 \sti@processflags{#1}%
2157 \ifsti@flag
2158 \ifodd\c@sti@inblock
2159 \sti@hoursminutes#3::!%
2160 #2%
2161 \sti@warnneg
2162 \sti@advance
2163 \sti@checksession
2164 \ifsti@printblock
2165 \timingprintblock\thesti@blocktime{}{}%
2166 \fi
2167 \else
2168 \PackageWarning{sesstime}{not in block}%
2169 \sti@warn{block}%
2170 \fi
2171 \fi}
2172 % \end{macrocode}
2173 % Version selection:
2174 % \begin{macrocode}
2175 \newcommand{\sti@blocksplitat}[1][]{\sti@blocksplit{#1}\sti@computedelta}
2176 \newcommand{\sti@blocksplitby}[1][]{\sti@blocksplit{#1}{}}
2177 \newcommand{\timingsplit}{\@ifstar\sti@blocksplitby\sti@blocksplitat}
2178 % \end{macrocode}
2179
2180 % \macro{\timingstop}
2181 % Stop current block:
2182 % \begin{macrocode}
2183 \newcommand{\sti@blockstop}[3]{%
2184 \sti@processflags{#1}%
2185 \ifsti@flag
2186 \ifodd\c@sti@inblock
2187 \sti@hoursminutes#3::!%
2188 #2%
2189 \sti@warnneg
2190 \sti@advance
2191 \sti@writeblocktotal
2192 \ifsti@printblock
2193 \timingprintblock\thesti@blocktime\thesti@chaptertime{}%
2194 \fi
2195 \c@sti@inblock\z@
2196 \c@sti@blocktime\z@
2197 \else
2198 \PackageWarning{sesstime}{not in block}%
2199 \sti@warn{block}%
2200 \fi
2201 \fi}
2202 % \end{macrocode}
2203 % Version selection:
2204 % \begin{macrocode}
2205 \newcommand{\sti@blockstopat}[1][]{\sti@blockstop{#1}\sti@computedelta}
2206 \newcommand{\sti@blockstopby}[1][]{\sti@blockstop{#1}{}}
2207 \newcommand{\timingstop}{\@ifstar\sti@blockstopby\sti@blockstopat}
2208 % \end{macrocode}
2209
2210 % \macro{\timingnext}
2211 % Stop current block and start next block:
2212 % \begin{macrocode}
2213 \newcommand{\sti@blocknext}[3]{%
2214 \sti@processflags{#1}%
2215 \ifsti@flag
2216 \ifodd\c@sti@inblock
2217 \sti@hoursminutes#3::!%
2218 #2%
2219 \sti@warnneg
2220 \sti@advance
2221 \sti@writeblocktotal
2222 \advance\c@sti@block\@ne
2223 \ifsti@printblock
2224 \sti@blocktotalcurrent
2225 \timingprintblock\thesti@blocktime\thesti@chaptertime\timingreturn
2226 \fi
2227 \advance\c@sti@blockgauge\c@sti@blocktime
2228 \c@sti@blocktime\z@
2229 \sti@checksession
2230 \else
2231 \PackageWarning{sesstime}{not in block}%
2232 \sti@warn{block}%
2233 \fi
2234 \fi}
2235 % \end{macrocode}
2236 % Version selection:
2237 % \begin{macrocode}
2238 \newcommand{\sti@blocknextat}[1][]{\sti@blocknext{#1}\sti@computedelta}
2239 \newcommand{\sti@blocknextby}[1][]{\sti@blocknext{#1}{}}
2240 \newcommand{\timingnext}{\@ifstar\sti@blocknextby\sti@blocknextat}
2241 % \end{macrocode}
2242
2243 % \macro{\timinglapse}
2244 % Insert some time to the current block
2245 % without changing the current absolute time:
2246 % \begin{macrocode}
2247 \newcommand{\timinglapse}[2][]{%
2248 \sti@processflags{#1}%
2249 \ifsti@flag
2250 \sti@hoursminutes#2::!%
2251 \ifodd\c@sti@inblock
2252 \advance\c@sti@blockgauge-\sti@delta
2253 \fi
2254 \sti@advance
2255 \fi}
2256 % \end{macrocode}
2257
2258 % \macro{\timinggauge}
2259 % Change the current absolute time
2260 % without advancing any timers:
2261 % \begin{macrocode}
2262 \newcommand{\timinggauge}[2][]{%
2263 \sti@processflags{#1}%
2264 \ifsti@flag
2265 \sti@hoursminutes#2::!%
2266 \sti@computedelta
2267 \advance\c@sti@blockgauge\sti@delta
2268 \fi}
2269 % \end{macrocode}
2270
2271 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2272 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2273 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2274 % \iffalse
2275 %</package>
2276 % \fi
2277 %
2278 \endinput