The multitoc package^{∗}

Martin Schröder

Crüsemannallee 3 D-28213 Bremen Martin.Schroeder@ACM.org

                           PGP-Key:  2048 bit / KeyID 292814E5
                        7E86 6EC8 97FA 2995  82C3 FEA5 2719 090E

1999/06/08

Abstract This package allows setting only the table of contents, list of figures and/or list of tables in two or more columns. The number of columns can be configured via commands; the multicolumn toc(s) can be selected via package options.

Contents

1 Introduction 1 1.1 The problem . . . . . 1 1.2 A solution . . . . . . . 2

2 Parameters 3

3 Options 3

4 Required packages 3 5 The Implementation 3 5.1 The parameters …. 3 5.2 Initial Code . . . . . . 3 5.3 The options . . . . . . 3 5.4 Executing options . . 4 5.5 Redefining \@starttoc 4 5.6 Code from Version 1.00 5

1 Introduction

1.1 The problem

When you want to set only the table of contents of a document in two (or more columns), there is one known way^{1}: Add an

     \addtocontents{toc}{\protect\begin{multicols}{2}}
before the \tableofcontents and an
     \addtocontents{toc}{\protect\end{multicols}}

∗The version number of this file is v2.01, last revised 1999/06/08.

The name multitoc is a tribute to the 8 + 3 file-naming convention of certain “operating systems”; strictly speaking it should be MulticolumnToc.

1This was first used in the doc package[4].

at the end of the document. This way your .toc will start with

\begin{multicols}{2} and end with \end{multicols}.
This can be automised by using \AtBeginDocument and \AtEndDocument

but this has the drawback that it may collide with other commands inserted using \AtEndDocument that try to write information to the auxilary file (like the count1to package[5]). This is because TEX has two ways to write information to files [3, p. 226–228]: immediately (when the \write is prefixed by \immediate) or deferred till the current page is finished and written out by TEX (at the next \shipout). \addtocontents does a deferred \write, count1to does an immediate.

Sidenote: \addtocontents writes a command to the .aux file to write its information to the .toc file. The .aux is read in and executed by \end{document} and at the next run by

\begin{document}. So the .toc is written by \end{document} and
at the next run by \begin{document}.

When you use the automised solution with count1to this may happen:

1. The \addtocontents{toc}{\protect\end{multicols}} is inserted

using \AtEndDocument somewhere in the preamble.

2. count1to inserts this code

     \clearpage
     \immediate\write\@auxout{\string\newlabel{TotalPages}{{\the\count1}{\the\count1}}}
via an \AtBeginDocument{\AtEndDocument{ so it can be sure that

this code is the last code executed by \AtEndDocument.

3. At the \end{document} first the code from step 1 is executed which adds the information to the current page to write the

\@writefile{toc}{\end{multicols}} to the auxilary file when

the current page is finished.

Then the code from step 2 is executed, which lets L^{A}TEX clear the page (to force all pending writes to be written) and immediately after that write the information for the TotalPages to the auxilary file.

Now suppose that the \end{document} is called just after L^{A}TEX has finished the last page. The code from step 1 is never written to the file (since at the \clearpage L^{A}TEX has no page to finish and so the code waits for the \shipout which won’t come), but the code from step 2 is. So you now have an .aux which won’t write the \end{multicols} to the .toc. This of course produces an error at the next run.

1.2 A solution

\@starttoc An easy way around this is to simply redefine \@starttoc from [2] which reads in the .toc to wrap a multicol around it.^{2}^{,}^{3}

2Thanks to Frank Mittelbach for reminding me of this.

3Version 1.00 of this package provided a more elaborate solution to this using \immediateaddtocontents; this is no longer needed. But the commands from version 1.00 are still provided (see section 5.6).

2 Parameters

\multicolumntoc The number of columns for the table of contens, list of figures and list

\multicolumnlot
\multicolumnlof

of tables can be set by redefining the commands \multicolumntoc,

\multicolumnlot and \multicolumnlof. The default is two columns.

3 Options

The package has the following options:

toc The table of contents is set in \multicolumntoc columns.

lof The list of figures is set in \multicolumnlof columns.

lot The list of tables is set in \multicolumnlot columns.

4 Required packages

The package requires the multicol and the ifthen packages.

5 The Implementation

1 ⟨∗package⟩

We need the multicol and the ifthen packages.

 2 \RequirePackage{multicol}
 3 \RequirePackage{ifthen}

5.1 The parameters

\multicolumntoc
\multicolumnlot
\multicolumnlof

 4 \newcommand{\multicolumntoc}{2}
 5 \newcommand{\multicolumnlot}{2}
 6 \newcommand{\multicolumnlof}{2}

5.2 Initial Code

@multitoc@toc \if@multitoc@toc is used to flag the use of the toc otion.

 7 \newboolean{@multitoc@toc}

@multitoc@lot \if@multitoc@lot is used to flag the use of the lot otion.

 8 \newboolean{@multitoc@lot}

@multitoc@lof \if@multitoc@lof is used to flag the use of the lof otion.

 9 \newboolean{@multitoc@lof}

5.3 The options

The options simply set the corresponding flags.

10 \DeclareOption{toc}{\setboolean{@multitoc@toc}{true}}
11 \DeclareOption{lot}{\setboolean{@multitoc@lot}{true}}
12 \DeclareOption{lof}{\setboolean{@multitoc@lof}{true}}

5.4 Executing options

There are no default options.

13 \ProcessOptions\relax

5.5 Redefining \@starttoc

\@starttoc From [2]:

The \@starttoc{⟨ext⟩} command is used to define the commands:

\tableofcontents, \listoffigures, etc.
For example: \@starttoc{lof} is used in \listoffigures.

This command reads the .⟨ext⟩ file and sets up to write the new .⟨ext⟩ file.

 \@starttoc{EXT} ==

BEGIN

   \begingroup
     \makeatletter

read file \jobname.EXT

IF @filesw = true

      THEN open \jobname.EXT as file \tf@EXT

FI

@nobreak :=G FALSE %% added 24 May 89

   \endgroup

END

We store the current definition in \@multitoc@starttoc and wrap it in a multicol environment if the right option has been selected. We also have to determine the number of columns to use.^{4}

14 \let\@multitoc@starttoc\@starttoc
15 \renewcommand*{\@starttoc}[1]{%
16 \ifthenelse{\boolean{@multitoc@toc}\and\equal{#1}{toc}}{%
17  \begin{multicols}{\multicolumntoc}%
18  \@multitoc@starttoc{#1}%
19  \end{multicols}%
20  }{}%
21 \ifthenelse{\boolean{@multitoc@lot}\and\equal{#1}{lot}}{%
22  \begin{multicols}{\multicolumnlot}%
23  \@multitoc@starttoc{#1}%
24  \end{multicols}%
25  }{}%
26 \ifthenelse{\boolean{@multitoc@lof}\and\equal{#1}{lof}}{%
27  \begin{multicols}{\multicolumnlof}%
28  \@multitoc@starttoc{#1}%
29  \end{multicols}%
30  }{}%

31 }

4This could probably be coded more effeciently, but this code works…

5.6 Code from Version 1.00

The first version of this package took a different approach to solving the problem mentioned in section 1.1 and provided the commands

\protected@write@immediate and \immediateaddtocontents. Their

code has been retained here for compatibilty reasons.

\immediateaddtocontents  \immediateaddtocontents is a version of \addtocontents which does

just what the name implies: Write the information \immediate.

\protected@write@immediate This is a changed version of \protected@write from [1]. It takes three arguments: an output stream, some initialization code, and some text to write. It then writes this immediately, with appropriate handling of

\protect and \thepage.
32 \newcommand*{\protected@write@immediate}[3]{%
33  \begingroup
34  \let\thepage\relax
35  #2%
36  \let\protect\string
37  \edef\reserved@a{\immediate\write#1{#3}}%
38  \reserved@a
39  \endgroup
40  \if@nobreak\ifvmode\nobreak\fi\fi

41 }

\immediateaddtocontents This is a changed version of \addtocontents from [2]. The

\immediateaddtocontents{⟨table⟩}{⟨text⟩} command immediately adds ⟨text⟩ to the .⟨table⟩ file, with no page number.

42 \newcommand*{\immediateaddtocontents}[2]{%
43 \protected@write@immediate\@auxout
44  {\let\label\@gobble \let\index\@gobble \let\glossary\@gobble}%
45  {\string\@writefile{#1}{#2}}}

46 ⟨/package⟩

References

[1] Johannes Braams, David Carlisle, Alan Jeffrey, Leslie Lamport, Frank Mittelbach, Chris Rowley and Rainer Schöpf. ltfiles.dtx. CTAN:

   tex-archive/macros/latex/base/ltfiles.dtx. L^{A}TEX 2ε kernel.

[2] Johannes Braams, David Carlisle, Alan Jeffrey, Leslie Lamport, Frank Mittelbach, Chris Rowley, Tobias Oetiker and Rainer Schöpf.

   ltsect.dtx. CTAN:tex-archive/macros/latex/base/ltsect.dtx.

L^{A}TEX 2ε kernel.

[3] Donald E. Knuth. The TEXBook, volume A of Computers and Typesetting. Addison-Wesley, 1986. Eleventh printing, revised, May 1991.

[4] Frank Mittelbach. The doc and shortvrb package.

   CTAN:tex-archive/macros/latex/base/doc.dtx. L^{A}TEX 2ε package.

Index 6

[5] Martin Schröder. The count1to package. CTAN:

   tex-archive/macros/latex/contrib/supported/ms/count1to.dtx.

L^{A}TEX 2ε package.

Index

Numbers written in italic refer to the page where the corresponding entry is described, the ones underlined to the code line of the definition, the rest to the code lines where the entry is used.

Symbols

\@auxout . . . . . . . . . . . . . . . . . . 43 \@gobble . . . . . . . . . . . . . . . . . . 44 \@multitoc@lof . . . . . . . . . . . . . . \underline{9} \@multitoc@lot . . . . . . . . . . . . . . \underline{8}

\@multitoc@starttoc . 14, 18, 23, 28

\@multitoc@toc . . . . . . . . . . . . . . \underline{7} \@starttoc . . . . . . . . . . . . . . 2, \underline{14} \@writefile . . . . . . . . . . . . . . . . 45

A

\and . . . . . . . . . . . . . . . 16, 21, 26

B

\begin . . . . . . . . . . . . . . 17, 22, 27 \begingroup . . . . . . . . . . . . . . . . 33 \boolean . . . . . . . . . . . . 16, 21, 26

D

\DeclareOption . . . . . . . . . . 10–12

E

\edef . . . . . . . . . . . . . . . . . . . . . 37 \end . . . . . . . . . . . . . . . 19, 24, 29 \endgroup . . . . . . . . . . . . . . . . . 39 \equal . . . . . . . . . . . . . . 16, 21, 26

F

\fi . . . . . . . . . . . . . . . . . . . . . . 40

G

\glossary . . . . . . . . . . . . . . . . . 44

I

\if@nobreak . . . . . . . . . . . . . . . . 40 \ifthenelse . . . . . . . . . . 16, 21, 26 \ifvmode . . . . . . . . . . . . . . . . . . 40 \immediate . . . . . . . . . . . . . . . . 37

                                    \immediateaddtocontents . . . 5, \underline{42}

\index . . . . . . . . . . . . . . . . . . . . 44

L \label . . . . . . . . . . . . . . . . . . . . 44 \let . . . . . . . . . . . . . 14, 34, 36, 44

M

                                    \multicolumnlof . . . . . . . . 3, \underline{4}, 27
                                    \multicolumnlot . . . . . . . . 3, \underline{4}, 22
                                    \multicolumntoc . . . . . . . . 3, \underline{4}, 17

N \newboolean . . . . . . . . . . . . . . . 7–9 \newcommand . . . . . . . . . 4–6, 32, 42 \nobreak . . . . . . . . . . . . . . . . . . 40

P

                                    \ProcessOptions . . . . . . . . . . . . 13

\protect . . . . . . . . . . . . . . . . . . 36

                                    \protected@write@immediate  \underline{32}, 43

R \relax . . . . . . . . . . . . . . . . . 13, 34 \renewcommand . . . . . . . . . . . . . . 15

                                    \RequirePackage . . . . . . . . . . . 2, 3

\reserved@a . . . . . . . . . . . . . 37, 38

S \setboolean . . . . . . . . . . . . . 10–12 \string . . . . . . . . . . . . . . . . 36, 45

T \thepage . . . . . . . . . . . . . . . . . . 34

W \write . . . . . . . . . . . . . . . . . . . . 37

Change History 7

Change History

v0.90

General: New . . . . . . . . . . . . . 1 v1.00

General: \clearpage . . . . . . . . 3

Documentation improved … 1 v2.00

General: Redesign . . . . . . . . 1, 3

\immediateaddtocontents: re-

tained . . . . . . . . . . . . . . . 5

@multitoc@lof: new . . . . . . . . 3
@multitoc@lot: new . . . . . . . . 3
@multitoc@toc: new . . . . . . . . 3
\protected@write@immediate:

retained . . . . . . . . . . . . . . 5 v2.01

General: Moved to LPPL . . . . . 1