The tocbibind package^{∗}

Peter Wilson Catholic University of America^{†}

             Now at peter.r.wilson@boeing.com

1999/01/17

Abstract

The tocbibind package can be used to add document elements like a bibliography or an index to the Table of Contents. The package is designed to work with the four standard book, report, article and proc classes, and to a limited extent with the ltxdoc class. Results with other classes may be problematical. The package has been tested with the tocloft package, but has not been tested with other packages that change the definitions of the

     \chapter* or \section* commands.

The package requres the stdclsdv package.

Contents

1 Introduction 1

2 The tocbibind package 2

3 The package code 3

1 Introduction

Questions about adding the bibliography to the Table of Contents seem to pop up fairly regularly on the comp.text.tex newsgroup.

The tocbibind package provides a solution for automatically inserting references to a bibliography or an index, or other headed document elements into the Table of Contents. (tocbibind is meant to be shorthand for ‘Table of Contents, Bibliography, Index, etc’). Portions of the package were developed as part of a class and package bundle for typesetting ISO standards [Wil96]. This manual is typeset according to the conventions of the L^{A}TEX docstrip utility which enables the automatic extraction of the L^{A}TEX macro source files [GMS94].

Section 2 describes the usage of the package. Commented source code for the package is in Section 3. The package requires the stdclsdv package to be available.

∗This file has version number v1.2, last revised 1999/01/17.

†This work was originally performed as a Guest Researcher at the National Institute of Standards and Technology.

2 The tocbibind package

The tocbibind package enables the titles of the Table of Contents, the List of Figures, the List of Tables, the Bibliography and the Index all to be added to the Table of Contents. By default, all of these document elements, if they exist, will be incorporated into the Table of Contents (ToC for short). Package options are available to switch off any of these inclusions.

• notbib Disables the inclusion of the Bibliography.

• notindex Disables the inclusion of the Index (inclusion of the Index of an ltxdoc class document is permanantly disabled).

• nottoc Disables the inclusion of the ToC.

• notlot Disables the inclusion of the List of Tables.

• notlof Disables the inclusion of the List of Figures.

• chapter Use chapter-level headings, if possible.

• section Use section-level headings, if possible.

• numbib Number the Bibliography heading (default is no number).

• numindex Number the Index heading (default is no number).

The package is designed to work with the standard L^{A}TEX document classes book, report, article, proc and ltxdoc class (which is based to a large extent on the article class). In the article, proc and ltxdoc classes L^{A}TEX uses the \section* heading style for the bibliography etc., while for the other two classes it uses the \chapter* heading style. tocbibind honours these conventions. However, if the package is used with another class (perhaps with a class for typesetting theses which has different conventions), then the chapter or section options can be used to select the appropriate style (but the class must define \chapter* and

\@makeschapterhead, or \section* respectively).

\tocextrahead In the standard L^{A}TEX classes the bibliography and index headings are either both defined in terms of the \chapter* command or in terms of the \section* command. The package assumes that any class, other than the standard classes already mentioned, will either use code from the standard classes for implementing the bibliography and other headings, or will use very similar code. Some classes (and maybe packages) change the names of the heading commands. One example that I am aware of uses \clause instead of \section, \sclause instead of \subsection and so on. If your document’s headings are defined like this and the same heading level is used for the bibliography, etc., then you can use the \tocextrahead{⟨headingname⟩} command to cater for this. If your document uses \clause then put \tocextrahead{clause} in the preamble after loading the package. The package then assumes that the bibliography heading is defined in

terms of \clause*.

If you use the \tocextrahead command, then it overrides any chapter or section option.

\tocbibname The package attempts to pick up the name for the Bibliography from the class definition. (Note that the article class and its derivatives stores the name text in the \refname whilst the book and report classes store the name in \bibname). This package uses \tocbibname to store the name of the bibliography.

\setindexname These commands set the heading texts for the index, ToC, list of tables and list

\settocname
\setlotname
\setlofname
\settocbibname

of figures. When used with the three standard classes, the heading text is picked up

from the \indexname, \contentsname, \listtablename and \listfigurename

commands respectively. The heading texts can be changed by changing the standard commands, or by using \tocindexname{⟨name⟩}, and similarly for the other headings. Thus, the following two lines of code have the same effect:

 \renewcommand{\listfigurename}{Figures}
 \toclofname{Figures}

Note that these commands replace the \toc...name commands that were in version 1.1.

Unlike the default theindex environment, provided the notindex option is used,

the \columnseprule and \columnsep lengths can be changed via \setlength to

alter the column seperation and the thickness of a rule between the two columns.

3 The package code

Announce the name and version of the package, which requires L^{A}TEX 2ε and the stdclsdv package.

1 ⟨∗usc⟩

 2 \NeedsTeXFormat{LaTeX2e}
 3 \ProvidesPackage{tocbibind}[1999/01/17 v1.2 extra ToC listings]
 4 \RequirePackage{stdclsdv}

Issue warning(s) if there are no recognized sectional divisions and then skip the rest of the package code.

 5 \ifSCDnodivs
 6 \PackageWarning{tocbibind}%
 7  {I don't recognize any sectional divisions so I'll do nothing}
 8 \renewcommand{\SCDquit}{\endinput}
 9 \fi
10 \SCDquit
11 \ifSCDknownclass\else
12 \PackageWarning{tocbibind}%
13  {| don't recognize the class but I'll do my best}
14 \ifSCDnodivs
15  \PackageWarning{tocbibind}%
16  {I don't recognize any sectional divisions so I'll do nothing}
17  \renewcommand{\SCDquit}{\endinput}
18 \fi
19 \fi
20 \SCDquit

\if@inltxdoc This is used as a flag for the ltxdoc class. This has a particular kind of index that I am not going to mess with.

21 \newif\if@inltxdoc
22 \@ifclassloaded{ltxdoc}{\@inltxdoctrue}{\@inltxdocfalse}

\if@bibchapter Used for knowing whether to use chapter or section style headings.

23 \newif\if@bibchapter\@bibchapterfalse
24 \ifSCDchapter
25 \@bibchaptertrue
26 \fi

\if@dotocbib \if@dotocind \if@dotoctoc \if@dotoclot \if@dotoclof A set of booleans for deciding what is to go into the ToC. By default add everything.

27 \newif\if@dotocbib\@dotocbibtrue
28 \newif\if@dotocind\@dotocindtrue
29 \newif\if@dotoctoc\@dotoctoctrue
30 \newif\if@dotoclot\@dotoclottrue
31 \newif\if@dotoclof\@dotocloftrue

\if@donumbib \if@donumindex A set of booleans for deciding whether or not to produce numbered headings (default is to do unnumbered headings).

32 \newif\if@donumbib\@donumbibfalse
33 \newif\if@donumindex\@donumindexfalse

Now we can do the options. Most of them are easy.

34 \DeclareOption{section}{\@bibchapterfalse}
35 \DeclareOption{notbib}{\@dotocbibfalse}
36 \DeclareOption{notindex}{\@dotocindfalse}
37 \DeclareOption{nottoc}{\@dotoctocfalse}
38 \DeclareOption{notlot}{\@dotoclotfalse}
39 \DeclareOption{notlof}{\@dotocloffalse}
40 \DeclareOption{numbib}{\@donumbibtrue}
41 \DeclareOption{numindex}{\@donumindextrue}

The chapter option needs to check whether or not the chapter heading commands are defined. If they are not, then go with the section level headings.

42 \DeclareOption{chapter}{%
43 \ifx\chapter\undefined
44  \@bibchapterfalse
45  \PackageWarning{tocbibind}%
46  {Chapters are undefined, using section instead}
47 \else
48  \ifx\@makeschapterhead\undefined
49  \@bibchapterfalse
50  \PackageWarning{tocbibind}%
51  {Makeschapterhead undefined, using section instead}
52  \else
53  \@bibchaptertrue
54  \fi
55 \fi}

Process the options now.

56 \ProcessOptions\relax

Issue a note about the heading style being used.

57 \if@bibchapter
58 \PackageWarning{tocbibind}{Using chapter style headings}
59 \else
60 \PackageWarning{tocbibind}{Using section or other style headings}
61 \fi

Ensure that the index is not processed if it is an ltxdoc class.

62 \if@inltxdoc \@dotocindfalse \fi

\@tocextra \tocextrahead \@tocextra is the internal command to store the heading command name. \tocextrahead{⟨name⟩} is the user command to set the heading command ⟨name⟩ (without the backslash). The default is section.

63 \newcommand{\@tocextra}{section}
64 \newcommand{\tocextrahead}[1]{\renewcommand{\@tocextra}{#1}}

\prw@mkboth \toc@section \toc@chapter \toc@headstar Utility macros, as the code that they represent gets used several times over. They deal with marking for page headers (code taken from classes.dtx), and adding starred sectional headings to the ToC.

\prw@mkboth{⟨text⟩} is shorthand for \@mkboth{⟨left⟩}{⟨right⟩} as called by sectional headings.

65 \providecommand{\prw@mkboth}[1]{\@mkboth{%
66 \MakeUppercase{#1}}{\MakeUppercase{#1}}}

\toc@section{⟨sec⟩}{⟨text⟩} is a generalised version of \sec*{⟨text⟩} which also makes an entry of ⟨text⟩ into the ToC, where ⟨sec⟩ is the name of a sectional division (with no backslash). \toc@headstar{⟨sec⟩}{⟨text⟩} is similar except that it makes no entry into the ToC.

67 \newcommand{\toc@section}[2]{%
68 \@nameuse{#1}*{#2\prw@mkboth{#2}}
69 \addcontentsline{toc}{#1}{#2}}
70 \newcommand{\toc@headstar}[2]{%
71 \@nameuse{#1}*{{#2}}}

\toc@chapter{⟨text⟩} is equivalent to \chapter*{⟨text⟩} except that it makes an entry into the ToC.

72 \newcommand{\toc@chapter}[1]{%
73 \chapter*{#1\prw@mkboth{#1}}
74 \addcontentsline{toc}{chapter}{#1}}

\tocbibname This holds the text for the Bibliography heading. We try and get the text from the class (either \bibname or \refname).

75 \ifx\bibname\undefined
76 \ifx\refname\undefined
77  \newcommand{\tocbibname}{References}
78 \else
79  \newcommand{\tocbibname}{\refname}
80 \fi
81 \else
82 \newcommand{\tocbibname}{\bibname}
83 \fi

\setindexname \settocname \setlotname \setlofname \settocbibname The remaining heading texts are simpler as we only need to check if their respective names are defined in the class. Note that these commands in version 1.2 have been changed from version 1.1 in order to integrate with the tocloft package (which operates with the \contentsname etc commands).

84 \providecommand{\indexname}{Index}
85 \newcommand{\setindexname}[1]{\renewcommand{\indexname}{#1}}
86 \providecommand{\contentsname}{Contents}
87 \newcommand{\settocname}[1]{\renewcommand{\contentsname}{#1}}

 88 \providecommand{\listtablename}{List of Tables}
 89 \newcommand{\setlotname}[1]{\renewcommand{\listtablename}{#1}}
 90 \providecommand{\listfigurename}{List of Figures}
 91 \newcommand{\setlofname}[1]{\renewcommand{\listfigurename}{#1}}
 92 \newcommand{\settocbibname}[1]{\renewcommand{\tocbibname}{#1}}

The rest is just hacking the various environments and commands from

 classes.dtx.
thebibliography Redefine thebibliography, but only if requested.
 93 \if@dotocbib
 94 \renewenvironment{thebibliography}[1]
 95  {\if@bibchapter
 96  \if@donumbib
 97  \chapter{\tocbibname}
 98  \else
 99  \toc@chapter{\tocbibname}
100  \fi
101  \else
102  \if@donumbib
103  \@nameuse{\@tocextra}{\tocbibname}
104  \else
105  \toc@section{\@tocextra}{\tocbibname}
106  \fi
107  \fi
108  \begin{thebibitemlist}{#1}}{\end{thebibitemlist}}

thebibitemlist Just as a matter of style, I have extracted the list making code from the definition of the thebibliography. It might also make it easier for someone to change the list environment. The code is a straight copy from classes.dtx.

109 \newenvironment{thebibitemlist}[1]{
110  \list{\@biblabel{\@arabic\c@enumiv}}%
111  {\settowidth\labelwidth{\@biblabel{#1}}%
112  \leftmargin\labelwidth
113  \advance\leftmargin\labelsep
114  \@openbib@code
115  \usecounter{enumiv}%
116  \let\p@enumiv\@empty
117  \renewcommand\theenumiv{\@arabic\c@enumiv}}%
118  \sloppy
119  \clubpenalty4000
120  \@clubpenalty \clubpenalty
121  \widowpenalty4000%
122  \sfcode`\.\@m}
123 {\def\@noitemerr
124  {\@latex@warning{Empty `thebibliography' environment}}%
125  \endlist}
126 \fi

theindex We redefine the theindex if asked for. The first bit of code is a copy from

 classes.dtx.
127 \if@dotocind
128 \renewenvironment{theindex}
129  {\if@twocolumn

130  \@restonecolfalse
131  \else
132  \@restonecoltrue
133  \fi

This next bit is where we make the package changes. Note that in the default definition the values for \columnseprule and \columnsep were set at this point to be 0pt and 35pt respectively. They are not set in this definition so that they can be adjusted by the user, if necessary, before starting the environment.

134  \if@bibchapter
135  \if@donumindex
136  \twocolumn[\@makechapterhead{\indexname}]%
137  \addcontentsline{toc}{chapter}{\protect\numberline{\thechapter}\indexname}
138  \else
139  \twocolumn[\@makeschapterhead{\indexname}]%
140  \prw@mkboth{\indexname}
141  \addcontentsline{toc}{chapter}{\indexname}
142  \fi
143  \else
144  \if@donumindex
145  \twocolumn[\@nameuse{\@tocextra}{\indexname}]%
146  \else
147  \twocolumn[\toc@headstar{\@tocextra}{\indexname}]%
148  \prw@mkboth{\indexname}
149  \addcontentsline{toc}{\@tocextra}{\indexname}
150  \fi
151  \fi

Now we are back to the original code.

152 \thispagestyle{plain}\parindent\z@
153 \parskip\z@ \@plus .3\p@\relax
154 \let\item\@idxitem}
155 {\if@restonecol\onecolumn\else\clearpage\fi}
156 \fi

\toc@start \toc@finish These two macros deal with the start and finish of the \tableofcontents and friends by adjusting the column settings if need be.

157 \newcommand{\toc@start}{%
158 \ifSCDchapter
159  \if@twocolumn
160  \@restonecoltrue\onecolumn
161  \else
162  \@restonecolfalse
163  \fi
164 \fi}
165 \newcommand{\toc@finish}{%
166 \ifSCDchapter
167  \if@restonecol\twocolumn\fi
168 \fi}
\toc@file The code for \tableofcontents, \listoftables and \listoffigures is virtu-

ally identical in each case, except for the heading text. \toc@file embodies the common code. This is virtually a parameterized copy from classes.dtx, except that it handles the differences between the article class and the other two, and incorporates the code for additions to the ToC. It is a useful hook if any other package wants to extend tocbibind for other kinds of listings.

The command is \toc@file{⟨head-text⟩}{⟨file-extension⟩}, where ⟨head-text⟩ is the heading (e.g., List of Figures) and ⟨file-extension⟩ is the file extension (e.g.,

lof).
169 \newcommand{\toc@file}[2]{%
170 \toc@start

The next bit is for the heading changes.

171 \if@bibchapter
172  \toc@chapter{#1}
173 \else
174  \toc@section{\@tocextra}{#1}
175 \fi

And finish up with a parameterized call to start the listing and tidy up.

176 \@starttoc{#2}
177 \toc@finish}

\tableofcontents If requested, we redefine this command, using \toc@file to do all the work for us.

178 \if@dotoctoc
179 \renewcommand{\tableofcontents}{%
180  \toc@file{\contentsname}{toc}

181 }

182 \fi

\listoftables This is almost identical to the code for \tableofcontents

183 \if@dotoclot
184 \renewcommand{\listoftables}{%
185  \toc@file{\listtablename}{lot}

186 }

187 \fi

\listoffigures This is almost identical to the code for \tableofcontents

188 \if@dotoclof
189 \renewcommand{\listoffigures}{%
190  \toc@file{\listfigurename}{lof}

191 }

192 \fi

The end of this package.

193 ⟨/usc⟩

References

[GMS94] Michel Goossens, Frank Mittelbach, and Alexander Samarin. The LaTeX Companion. Addison-Wesley Publishing Company, 1994.

[Wil96] Peter R. Wilson. LaTeX for standards: The LaTeX package files user manual. NIST Report NISTIR, June 1996.

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

\@bibchapterfalse .

…. 23, 34, 44, 49

\@bibchaptertrue 25, 53
\@biblabel . . . 110, 111
\@clubpenalty . . . . . 120
\@donumbibfalse . . . 32
\@donumbibtrue . . . . 40
\@donumindexfalse . 33
\@donumindextrue . . 41
\@dotocbibfalse . . . 35
\@dotocbibtrue . . . . 27
\@dotocindfalse . 36, 62
\@dotocindtrue . . . . 28
\@dotocloffalse . . . 39
\@dotocloftrue . . . . 31
\@dotoclotfalse . . . 38
\@dotoclottrue . . . . 30
\@dotoctocfalse . . . 37
\@dotoctoctrue . . . . 29

\@idxitem . . . . . . . . 154

\@ifclassloaded . . . 22
\@inltxdocfalse . . . 22
\@inltxdoctrue . . . . 22
\@latex@warning . . . 124
\@makechapterhead . 136
\@makeschapterhead .

. . . . . . . . 48, 139 \@nameuse 68, 71, 103, 145

\@noitemerr . . . . . . . 123
\@openbib@code . . . . 114
\@restonecolfalse .

. . . . . . . . 130, 162

\@restonecoltrue . .

. . . . . . . . 132, 160

\@starttoc . . . . . . . 176
\@tocextra . . . . . . .

. . \underline{63}, 103, 105, 145, 147, 149, 174

A

\addcontentsline . .

69, 74, 137, 141, 149

B

\bibname . . . . . . . 75, 82

C \c@enumiv …. 110, 117 \chapter …. 43, 73, 97

                          \clearpage . . . . . . . 155
                          \clubpenalty . . 119, 120
                          \contentsname 86, 87, 180

E \endinput . . . . . . . 8, 17 environments:

                             thebibitemlist . . \underline{6}
                             thebibliography . \underline{6}
                             theindex . . . . . . . \underline{6}

I

                          \if@bibchapter . . . .

\underline{23}, 57, 95, 134, 171

                          \if@donumbib  \underline{32}, 96, 102
                          \if@donumindex . . . .

. . . . . \underline{32}, 135, 144

                          \if@dotocbib . . . . \underline{27}, 93
                          \if@dotocind . . . \underline{27}, 127
                          \if@dotoclof . . . \underline{27}, 188
                          \if@dotoclot . . . \underline{27}, 183
                          \if@dotoctoc . . . \underline{27}, 178
                          \if@inltxdoc . . . . \underline{21}, 62
                          \if@restonecol 155, 167
                          \if@twocolumn . 129, 159
                          \ifSCDchapter . . . . .

. . . . . 24, 158, 166

                          \ifSCDknownclass . . 11
                          \ifSCDnodivs . . . . . 5, 14
                          \indexname . . 84, 85,

136, 137, 139– 141, 145, 147–149

\item . . . . . . . . . . . . 154

L \labelsep . . . . . . . . 113

                          \labelwidth . . . 111, 112
                          \leftmargin . . . 112, 113
                          \listfigurename . . .

. . . . . . 90, 91, 190

                          \listoffigures . . . . \underline{188}
                          \listoftables . . . . . \underline{183}
                          \listtablename . . . .

. . . . . . 88, 89, 185

M

                                                   \MakeUppercase . . . . 66

N \newif …. 21, 23, 27–33

O

                                                   \onecolumn . . . 155, 160

P \p@enumiv . . . . . . . . 116

                                                   \PackageWarning 6, 12,

15, 45, 50, 58, 60

                                                   \parindent . . . . . . . 152

\parskip . . . . . . . . . 153

                                                   \providecommand . . .

. 65, 84, 86, 88, 90

                                                   \ProvidesPackage . . . 3
                                                   \prw@mkboth  \underline{65}, 140, 148

R \refname . . . . . . . 76, 79

                                                   \renewenvironment .

. . . . . . . . 94, 128

                                                   \RequirePackage . . . . 4

S \SCDquit . . 8, 10, 17, 20

                                                   \setindexname . . . . 2, \underline{84}
                                                   \setlofname . . . . . . 2, \underline{84}
                                                   \setlotname . . . . . . 2, \underline{84}
                                                   \settocbibname . . . 2, \underline{84}
                                                   \settocname . . . . . . 2, \underline{84}

T

                                                   \tableofcontents . . \underline{178}
                                                   thebibitemlist (envi-

ronment) … \underline{109}

                                                   thebibliography (envi-

ronment) …. \underline{93}

                                                   \thechapter . . . . . . . 137
                                                   \theenumiv . . . . . . . 117

theindex (environ-

ment) . . . . . . \underline{127}

                                                   \thispagestyle . . . . 152
                                                   \toc@chapter  \underline{65}, 99, 172
                                                   \toc@file . . . . . . . .

. \underline{169}, 180, 185, 190

\toc@finish . . . \underline{157}, 177
\toc@headstar . . \underline{65}, 147
\toc@section \underline{65}, 105, 174
\toc@start . . . \underline{157}, 170

                          \tocbibname . . 2, \underline{75},

92, 97, 99, 103, 105

                          \tocextrahead . . . . 2, \underline{63}
                          \twocolumn . . . 136,

139, 145, 147, 167

W

                                                   \widowpenalty . . . . . 121