Debian Codegraph @

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

raw
1 %% \iffalse meta-comment
2 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3 %
4 % Copyright (C) Martin Schröder, 1998–1999
5 % Marei Peischl (peiTeX) <[email protected]>, 2024
6 %
7 % This work may be distributed and/or modified under the
8 % conditions of the LaTeX Project Public License, either version 1.3c
9 % of this license or (at your option) any later version.
10 % The latest version of this license is in
11 % http://www.latex-project.org/lppl.txt
12 % and version 1.3c or later is part of all distributions of LaTeX
13 % version 2005/12/01 or later.
14 %
15 % This work has the LPPL maintenance status `maintained'.
16 % This package is maintained but will not receive any additional features.
17 %
18 % The Current Maintainer of this work is
19 % Marei Peischl <[email protected]>.
20 %
21 %
22 % This work consists of the files
23 % README.md
24 % multitoc.dtx
25 % multitoc.ins
26 % and the derived file
27 % multitoc.sty.
28 %
29 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
30 %
31 % \fi
32 % \iffalse
33 \NeedsTeXFormat{LaTeX2e}[2015-09-18]
34 %<package>\ProvidesPackage{multitoc}
35 %<package> [2024/06/13 v2.02 MultiToc Package]
36 %
37 %<*driver>
38 \ProvidesFile{multitoc.drv}
39 [1999/06/08 v2.02 Driver for MultiToc Package]
40 \documentclass{ltxdoc}
41 \usepackage{url}
42 \usepackage{ragged2e}
43 \usepackage[toc]{multitoc}
44 \GetFileInfo{multitoc.sty}
45 \makeatletter
46 \IfFileExists{gitHeadInfo.gin}{
47 \newcommand*{\GI@githeadinfo@file}{gitHeadInfo.gin}
48 }{}
49 \makeatother
50 \usepackage{gitinfo2}
51 \setcounter{IndexColumns}{2}
52 \EnableCrossrefs
53 %%\DisableCrossrefs% Say \DisableCrossrefs if index is ready
54 \CodelineIndex % Index code by line number
55 \OnlyDescription % comment out for implementation details
56 %%\OldMakeIndex % use if your MakeIndex is pre-v2.9
57 \setcounter{IndexColumns}{2}
58 \setlength{\IndexMin}{30ex}
59 \setlength{\premulticols}{\IndexMin}
60 \RaggedRight
61 \begin{document}
62 \DocInput{multitoc.dtx}
63 \end{document}
64 %</driver>
65 % \fi
66 %
67 % \changes{v0.90}{1998/05/23}{New}
68 % \changes{v1.00}{1998/08/09}{Documentation improved}
69 % \changes{v2.00}{1998/08/23}{Redesign}
70 % \changes{v2.01}{1999/06/08}{Moved to LPPL}
71 %
72 % \newcommand*{\option}[1]{\textnormal{\sffamily#1}}
73 % \newcommand*{\package}[1]{\textnormal{\sffamily#1}}
74 % \newcommand*{\file}[1]{\textnormal{\texttt{.#1}}}
75 % \newcommand*{\env}[1]{\textnormal{\texttt{#1}}}
76 %
77 %
78 % ^^A -----------------------------
79 %
80 % \title{\unskip
81 % The \textsf{multitoc} package^^A
82 % \thanks{^^A
83 % The version number of this file is \fileversion,
84 % revision~\#\gitAbbrevHash, last revised \protect\gitAuthorIsoDate.\protect\newline
85 % The name \textsf{multitoc} is a tribute to the $8+3$
86 % file-naming convention of certain ``operating
87 % systems''; strictly speaking it should be
88 % \textsf{MulticolumnToc}.}
89 % }
90 % \author{Martin Schröder\\
91 % \url{https://gitlab.com/TeXhackse/multitoc}\thanks{maintained by Marei Peischl}}
92 % \date{\filedate}
93 % \maketitle
94 %
95 % ^^A -----------------------------
96 %
97 % \begingroup\renewcommand*{\abstractname}{Disclaimer/Warning}
98 % \begin{abstract}
99 % \changes{v2.02}{2024/06/13}{Add note, that there will not be any additional features.}
100 % This package is maintained to keep compatibility but will not receive any further feature extensions as there are a lot of packages providing by far more functionality.
101 %
102 % In case you are looking for methods to modify lists have a look at Markus Kohm's tocbasic Package \cite{package:tocbasic} or the corresponding CTAN Topic \url{https://ctan.org/topic/toc-etc}.
103 % \end{abstract}
104 % \endgroup
105 %
106 % \begin{abstract}
107 % This package allows setting only the table of contents, list of
108 % figures and/or list of tables in two or more columns.
109 % The number of columns can be configured via commands; the
110 % multicolumn toc(s) can be selected via package options.
111 % \end{abstract}
112 %
113 % \pagestyle{headings}
114 %
115 % ^^A -----------------------------
116 %
117 % \tableofcontents
118 %
119 % ^^A -----------------------------
120 %
121 % \section{Introduction}
122 %
123 %
124 % ^^A -----------------------------
125 %
126 % \subsection{The problem\label{sec:sec:problem}}
127 % ^^A
128 % When you want to set only the table of contents of a document in two
129 % (or more columns), there is one known way^^A
130 % \footnote{^^A
131 % This was first used in the \package{doc}
132 % package\protect\cite{package:doc}.
133 % }^^A
134 % : Add an
135 % \begin{quote}
136 % |\addtocontents{toc}{\protect\begin{multicols}{2}}|
137 % \end{quote}
138 % before the \cs{tableofcontents} and an
139 % \begin{quote}
140 % |\addtocontents{toc}{\protect\end{multicols}}|
141 % \end{quote}
142 % at the end of the document.
143 % This way your \file{toc} will start with |\begin{multicols}{2}|
144 % and end with |\end{multicols}|.
145 %
146 % This can be automised by using \cs{AtBeginDocument} and
147 % \cs{AtEndDocument} but this has the drawback that it may
148 % collide with other commands inserted using \cs{AtEndDocument} that
149 % try to write information to the auxilary file (like the
150 % \package{count1to} package\cite{package:count1to}).
151 % This is because \TeX{} has two ways to write information to files
152 % \cite[p.\ 226--228]{KnuthTeXa}: immediately (when the \cs{write} is
153 % prefixed by \cs{immediate}) or deferred till the current page is
154 % finished and written out by \TeX{} (at the next \cs{shipout}).
155 % \cs{addtocontents} does a deferred \cs{write}, \package{count1to}
156 % does an immediate.
157 %
158 % \begin{quote}
159 % \small
160 % Sidenote: \cs{addtocontents} writes a command to the \file{aux} file
161 % to write its information to the \file{toc} file.
162 % The \file{aux} is read in and executed by |\end{document}| and at
163 % the next run by |\begin{document}|.
164 % So the \file{toc} is written by |\end{document}| and at the
165 % next run by |\begin{document}|.
166 % \end{quote}
167 %
168 % When you use the automised solution with \package{count1to} this may
169 % happen:
170 % \begin{enumerate}
171 % \item The |\addtocontents{toc}{\protect\end{multicols}}| is inserted
172 % using \cs{AtEndDocument} somewhere in the preamble.
173 % \item \package{count1to} inserts this code
174 % \begin{quote}
175 % \hfuzz135pt
176 % \small
177 % |\clearpage|\\
178 % |\immediate\write\@auxout{\string\newlabel{TotalPages}{{\the\count1}{\the\count1}}}|
179 % \end{quote}
180 % via an |\AtBeginDocument{\AtEndDocument{| so it can be sure that
181 % this code is the \emph{last} code executed by \cs{AtEndDocument}.
182 % \item At the |\end{document}| first the code from step~1 is executed
183 % which adds the information to the current page to write the
184 % |\@writefile{toc}{\end{multicols}}| to the auxilary file
185 % \emph{when the current page is finished}.
186 %
187 % Then the code from step~2 is executed, which lets \LaTeX{} clear
188 % the page (to force all pending writes to be written) and
189 % \emph{immediately} after that write the information for the
190 % |TotalPages| to the auxilary file.
191 %
192 % Now suppose that the |\end{document}| is called \emph{just after}
193 % \LaTeX{} has finished the last page.
194 % The code from step~1 is never written to the file (since at the
195 % \cs{clearpage} \LaTeX{} has no page to finish and so the code
196 % waits for the \cs{shipout} which won't come), but the code from
197 % step~2 is.
198 % So you now have an \file{aux} which won't write the
199 % |\end{multicols}| to the \file{toc}.
200 % This of course produces an error at the next run.
201 % \end{enumerate}
202 %
203 %
204 % ^^A -----------------------------
205 %
206 % \subsection{A solution}
207 % ^^A
208 % \DescribeMacro{\@starttoc}
209 % An easy way around this is to simply redefine \cs{@starttoc} from
210 % \cite{package:ltsect} which reads in the \file{toc} to wrap a
211 % \env{multicol} around it.\footnote{^^A
212 % Thanks to Frank Mittelbach for reminding me of this.}^^A
213 % $^{,}$^^A
214 % \footnote{^^A
215 % \raggedright
216 % Version~1.00 of this package provided a more elaborate solution
217 % to this using \cs{immediateaddtocontents}; this is no longer needed.
218 % But the commands from version~1.00 are still provided (see
219 % section~\ref{sec:sec:version100}).}
220 %
221 %
222 % ^^A -----------------------------
223 %
224 % \section{Parameters}
225 % ^^A
226 % \DescribeMacro{\multicolumntoc}
227 % \DescribeMacro{\multicolumnlot}
228 % \DescribeMacro{\multicolumnlof}
229 % The number of columns for the table of contens, list of figures and
230 % list of tables can be set by redefining the commands
231 % \cs{multicolumntoc}, \cs{multicolumnlot} and \cs{multicolumnlof}.
232 % The default is two columns.
233 %
234 %
235 % ^^A -----------------------------
236 %
237 % \section{Options}
238 % ^^A
239 % The package has the following options:
240 % \nopagebreak
241 % \begin{description}
242 % \item[\normalfont\option{toc}]
243 % The table of contents is set in \cs{multicolumntoc} columns.
244 % \item[\normalfont\option{lof}]
245 % The list of figures is set in \cs{multicolumnlof} columns.
246 % \item[\normalfont\option{lot}]
247 % The list of tables is set in \cs{multicolumnlot} columns.
248 % \end{description}
249 %
250 %
251 % ^^A -----------------------------
252 %
253 % \section{Required packages}
254 % ^^A
255 % The package requires the \package{multicol} and the
256 % \package{ifthen} packages.
257 %
258 %
259 % ^^A -----------------------------
260 %
261 % \StopEventually{^^A
262 %
263 %
264 % ^^A -----------------------------
265 %
266 % \begin{thebibliography}{1}
267 % \raggedright
268 % \bibitem{package:ltfiles}
269 % Johannes Braams, David Carlisle, Alan Jeffrey, Leslie Lamport,
270 % Frank Mittelbach, Chris Rowley and Rainer Sch\"opf.
271 % \newblock \package{ltfiles.dtx}.
272 % \newblock \texttt{CTAN: tex-archive/macros/latex/base/ltfiles.dtx}.
273 % \newblock \LaTeXe{} kernel.
274 % \bibitem{package:ltsect}
275 % Johannes Braams, David Carlisle, Alan Jeffrey, Leslie Lamport,
276 % Frank Mittelbach, Chris Rowley, Tobias Oetiker and Rainer Sch\"opf.
277 % \newblock \package{ltsect.dtx}.
278 % \newblock \url{CTAN: tex-archive/macros/latex/base/ltsect.dtx}.
279 % \newblock \LaTeXe{} kernel.
280 % \bibitem{KnuthTeXa}
281 % Donald~E.\ Knuth.
282 % \newblock \emph{The {\TeX}Book}, volume~A of \emph{Computers
283 % and Typesetting}.
284 % \newblock Addison-Wes\-ley, 1986.
285 % \newblock Eleventh printing, revised, May 1991.
286 % \bibitem{package:doc}
287 % Frank Mittelbach.
288 % \newblock The \package{doc} and \package{shortvrb} package.
289 % \newblock \url{CTAN: tex-archive/macros/latex/base/doc.dtx}.
290 % \newblock \LaTeXe{} package.
291 % \bibitem{package:count1to}
292 % Martin Schr\"oder.
293 % \newblock The \package{count1to} package.
294 % \newblock \url{CTAN: tex-archive/macros/latex/contrib/supported/ms/count1to.dtx}.
295 % \newblock \LaTeXe{} package.
296 % \bibitem{package:tocbasic}
297 % Markus Kohm
298 % \newblock KOMA-Script
299 % \newblock \url{CTAN: tex-archive/macros/latex/contrib/koma-script/tocbasic.dtx}.
300 % \newblock \LaTeXe{} package.
301 % \end{thebibliography}
302 %
303 % }
304 %
305 %
306 % ^^A -----------------------------
307 %
308 % \section{The Implementation}
309 % ^^A
310 % \setlength{\parindent}{0pt}
311 % \begin{macrocode}
312 %<*package>
313 % \end{macrocode}
314 %
315 % We need the \package{multicol} and the \package{ifthen} packages.
316 % \begin{macrocode}
317 \RequirePackage{multicol}
318 \RequirePackage{ifthen}
319 % \end{macrocode}
320 %
321 %
322 % ^^A -----------------------------
323 %
324 % \subsection{The parameters}
325 % ^^A
326 % \begin{macro}{\multicolumntoc}
327 % \begin{macro}{\multicolumnlot}
328 % \begin{macro}{\multicolumnlof}
329 % \mbox{}
330 % \begin{macrocode}
331 \newcommand{\multicolumntoc}{2}
332 \newcommand{\multicolumnlot}{2}
333 \newcommand{\multicolumnlof}{2}
334 % \end{macrocode}
335 % \end{macro}
336 % \end{macro}
337 % \end{macro}
338 %
339 %
340 % ^^A -----------------------------
341 %
342 % \subsection{Initial Code}
343 % ^^A
344 % \begin{macro}{@multitoc@toc}
345 % \changes{v2.00}{1998/08/23}{new}
346 % \cs{if@multitoc@toc} is used to flag the use of the \option{toc}
347 % otion.
348 % \begin{macrocode}
349 \newboolean{@multitoc@toc}
350 % \end{macrocode}
351 % \end{macro}
352 %
353 % \begin{macro}{@multitoc@lot}
354 % \changes{v2.00}{1998/08/23}{new}
355 % \cs{if@multitoc@lot} is used to flag the use of the \option{lot}
356 % otion.
357 % \begin{macrocode}
358 \newboolean{@multitoc@lot}
359 % \end{macrocode}
360 % \end{macro}
361 %
362 % \begin{macro}{@multitoc@lof}
363 % \changes{v2.00}{1998/08/23}{new}
364 % \cs{if@multitoc@lof} is used to flag the use of the \option{lof}
365 % otion.
366 % \begin{macrocode}
367 \newboolean{@multitoc@lof}
368 % \end{macrocode}
369 % \end{macro}
370 %
371 %
372 % ^^A -----------------------------
373 %
374 % \subsection{The options}
375 % ^^A
376 % The options simply set the corresponding flags.
377 % \changes{v2.00}{1998/08/23}{Redesign}
378 % \changes{v1.00}{1998/08/09}{\cs{clearpage}}
379 % \begin{macrocode}
380 \DeclareOption{toc}{\setboolean{@multitoc@toc}{true}}
381 \DeclareOption{lot}{\setboolean{@multitoc@lot}{true}}
382 \DeclareOption{lof}{\setboolean{@multitoc@lof}{true}}
383 % \end{macrocode}
384 %
385 %
386 % ^^A -----------------------------
387 %
388 % \subsection{Executing options}
389 % ^^A
390 % There are no default options.
391 % \begin{macrocode}
392 \ProcessOptions\relax
393 % \end{macrocode}
394 %
395 %
396 % ^^A -----------------------------
397 %
398 % \subsection{Redefining \cs{@starttoc}}
399 % ^^A
400 % \begin{macro}{\@starttoc}
401 % From \cite{package:ltsect}:
402 % \begin{quote}
403 % The |\@starttoc|\marg{ext} command is used to define the commands:\\
404 % |\tableofcontents|, |\listoffigures|, etc.
405 %
406 % For example:
407 % |\@starttoc{lof}| is used in |\listoffigures|. This command
408 % reads the |.|\meta{ext} file and sets up to write the new
409 % |.|\meta{ext} file.
410 %
411 % \begin{oldcomments}
412 % \@starttoc{EXT} ==
413 % BEGIN
414 % \begingroup
415 % \makeatletter
416 % read file \jobname.EXT
417 % IF @filesw = true
418 % THEN open \jobname.EXT as file \tf@EXT
419 % FI
420 % @nobreak :=G FALSE %% added 24 May 89
421 % \endgroup
422 % END
423 % \end{oldcomments}
424 % \end{quote}
425 % We store the current definition in \cs{@multitoc@starttoc}
426 % and wrap it in a \env{multicol} environment if the right
427 % option has been selected.
428 % We also have to determine the number of columns to use.\footnote{^^A
429 % This could probably be coded more effeciently, but this code
430 % works\ldots}
431 % \changes{v2.02}{2024/06/13}{Fix bug breaking other lists but toc/lof/lot. Thanks to Markus Kohm for reporting.}
432 % \begin{macrocode}
433 \let\@multitoc@starttoc\@starttoc
434 \ExplSyntaxOn
435 \renewcommand*{\@starttoc}[1]{%
436 \clist_if_in:nnTF {toc,lof,lot} {#1} {
437 \ifthenelse{\boolean{@multitoc@#1}}{
438 \begin{multicols}{\use:c{multicolumn#1}}%
439 \@multitoc@starttoc{#1}%
440 \end{multicols}
441 }{
442 \@multitoc@starttoc{#1}
443 }
444 }{
445 \@multitoc@starttoc{#1}
446 }
447 }
448 \ExplSyntaxOff
449 % \end{macrocode}
450 % \end{macro}
451 %
452 %
453 % ^^A -----------------------------
454 %
455 % \subsection{Code from Version~1.00\label{sec:sec:version100}}
456 % ^^A
457 % The first version of this package took a different approach to
458 % solving the problem mentioned in section~\ref{sec:sec:problem} and
459 % provided the commands \cs{protected@write@immediate} and
460 % \cs{immediateaddtocontents}.
461 % Their code has been retained here for compatibilty reasons.
462 %
463 % \DescribeMacro{\immediateaddtocontents}
464 % \cs{immediateaddtocontents} is a version of \cs{addtocontents} which
465 % does just what the name implies: Write the information \cs{immediate}.
466 %
467 % \begin{macro}{\protected@write@immediate}
468 % This is a changed version of \cs{protected@write}
469 % from~\cite{package:ltfiles}.
470 % It takes three arguments: an output stream, some initialization
471 % code, and some text to write.
472 % It then writes this \emph{immediately}, with
473 % appropriate handling of |\protect| and |\thepage|.
474 % \changes{v2.00}{1998/09/06}{retained}
475 % \begin{macrocode}
476 \newcommand*{\protected@write@immediate}[3]{%
477 \begingroup
478 \let\thepage\relax
479 #2%
480 \let\protect\string
481 \edef\reserved@a{\immediate\write#1{#3}}%
482 \reserved@a
483 \endgroup
484 \if@nobreak\ifvmode\nobreak\fi\fi
485 }
486 % \end{macrocode}
487 % \end{macro}
488 %
489 % \begin{macro}{\immediateaddtocontents}
490 % This is a changed version of \cs{addtocontents}
491 % from~\cite{package:ltsect}.
492 % The |\immediateaddtocontents{|\meta{table}|}{|\meta{text}|}| command
493 % \emph{immediately} adds \meta{text} to the |.|\meta{table} file,
494 % with no page number.
495 % \changes{v2.00}{1998/09/06}{retained}
496 % \begin{macrocode}
497 \newcommand*{\immediateaddtocontents}[2]{%
498 \protected@write@immediate\@auxout
499 {\let\label\@gobble \let\index\@gobble \let\glossary\@gobble}%
500 {\string\@writefile{#1}{#2}}}
501 % \end{macrocode}
502 % \end{macro}
503 %
504 % \begin{macrocode}
505 %</package>
506 % \end{macrocode}
507 %
508 % ^^A -----------------------------
509 %
510 % \Finale
511 %
512 % \PrintIndex\PrintChanges
513 % ^^A Make sure that the index is not printed twice
514 % ^^A (ltxdoc.cfg might have a second \PrintIndex command)
515 % \let\PrintChanges\relax
516 % \let\PrintIndex\relax