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

1998/09/06

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 2 3 Options 3

4 Required packages 3

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}}

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.

∗The version umber of this file is v2.00, last revised 1998/09/06.

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].

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}

2 Parameters

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

\multicolumnlot
\multicolumnlof

can be set by redefining the commands \multicolumntoc, \multicolumnlot and \multicolumnlof. The default is two columns.

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 ??).

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.

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.

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

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

L^{A}TEX 2ε package.