8

I'm trying to understand, in some detail, how a toc is generated. But now I'm thoroughly confused and perplexed after examining the .toc file before and after making a ``slight'' modification. I hope someone can get me past this bottleneck. [The final goal is to design a ToC where where I can place the chapter title (not chaptername or chapternum), author, and page number all on one line, sometimes two. For a particular book or report, the title, author, or page should appear in the user preferred order. The title should appear in one header, the author in the other: a later question, I suspect]

I started with a simple file, nothing fancy, just 2 chapters.

\documentclass{book}
\usepackage{lipsum}
%\newcommand\autsection[2]{%
%  \chapter[#1~/ {\normalfont\small\itshape#2}] %
%  {#1 \\ {\normalfont\large\itshape#2}}} % 
\begin{document}
\tableofcontents
\chapter{Title without slash Author}
%\autsection{Title with slash Author}{Paul Isamber}
\lipsum[20-30]
\chapter{Very long title name without slash author or any other text in the title}
%\autsection{Very long title name with slash author following}{Joseph Wright and Timothy Hall}
\end{document}

They generated this .toc file. Straight forward it seems.

\contentsline {chapter}{\numberline {1}Title without slash Author}{3}
\contentsline {chapter}{\numberline {2}Very long title name without slash author or any other text in the title}{7}

Then I added a small modification, based on an answer by G.Medina (Add author's name automatically while building ToC on Mar 10, 2012 by Gonzalo Medina)

\newcommand\autsection[2]{% alternative
    \section[#1~/ {\normalfont\small\itshape#2}] % optional part of \section
    {#1 \\ {\normalfont\large\itshape#2}}} % main part of \section

And I substituted these two macros for the \chapter commands.

\autsection{Title with slash Author}{Paul Isamber}
\autsection{Very long title name with slash author following}{Joseph Wright and Timothy Hall}

The contents of the .toc file is what confused me. Note that I've reformatted the file to make it easier to read, and only include the code that refers to the first chapter

\contentsline {chapter}{\numberline {1}Title with slash Author
    \nobreakspace {}/ 
    {\normalfont \relax
        \fontsize {9}{11}\selectfont 
        \abovedisplayskip 8.5\p@ plus3\p@ minus4\p@ 
        \abovedisplayshortskip \z@ plus2\p@ 
        \belowdisplayshortskip 4\p@ plus2\p@ minus2\p@ 
        \def \leftmargin \leftmargini 
        \parsep 4\p@ plus2\p@ minus\p@ 
        \topsep 8\p@ plus2\p@ minus4\p@ 
        \itemsep 4\p@ plus2\p@ minus\p@ {%
            \leftmargin \leftmargini 
            \topsep 4\p@ plus2\p@ minus2\p@ 
            \parsep 2\p@ plus\p@ minus\p@ 
            \itemsep \parsep 
        }%
        \belowdisplayskip 
        \abovedisplayskip 
        \itshape Paul Isamber}
}%
{3}

Where did all this ``stuff'' come from? What macros are responsible? I recognize that several default values are reset, but I don't understand what is doing it. I Tried to retrace possible steps through the relevant commands, beginning with \chapter, \tableofcontents, \l@chapter, \addcontentsline, \contentsline, \@dottedtocline, \@chapter, and the elusive \@starttoc. But I just simply ran into blind alleys!

  • 4
    That's the expansion of the \small command, it is not robust (in the sense that it gets expanded when wandering in the toc). Use \protect\small if you want to get \small in the toc. – Ulrike Fischer Mar 5 '15 at 11:25
  • Ulrike Fischer I had read the warning to use \protect on "fragile" commands. I'm beginning to get some idea now what it means practically – zun Mar 5 '15 at 14:14
7

Writing into the .toc file happens in two stages:

  1. The entry is written in the .aux file; you'll indeed find

    \@writefile{toc}{\contentsline {chapter}{\numberline {1}Title without slash Author}{3}}
    

    in it

  2. When the .aux file is input as part of the end game routine, those command write the entry in a fresh .toc file that can so be used anywhere during the next run.

One has to remember that these instructions are passed through \protected@write that does full expansion, unless it finds \protect in front of a token (explicit or resulting from expansion).

For instance, book.cls has

\addcontentsline{toc}{chapter}{\protect\numberline{\thechapter}#1}

as part of the \@chapter macro; so \numberline is protected and will not be unduly expanded during the write operations.

The command \normalfont is robust, which means that it expands to

\protect\normalfont•

(the bullet denotes a space in the command name). So what's eventually written out is the string \normalfont•• (one space because there's one in the command name, one, as always, following a control word). When the file is read back in, those two spaces will be ignored because the file is \input.

Also \itshape is robust in the same sense, but \large and \small aren't.

You should precede them with \protect; if you do, the .toc file will contain

\contentsline {chapter}{\numberline {2}Title with slash Author\nobreakspace {}/ {\normalfont \small \itshape Paul Isamber}}{5}

Note that ~ is converted to \nobreakspace{}, which is completely equivalent and such a conversion is innocuous (\nobreakspace is robust).

  • egreg I'm getting a better idea of what it means to \protect "fragile" commands. Indeed, I did see the difference in the .toc file. I'm still a bit hazy on when the \@write occurs and where in the chain of calls it occurs. Having looked at source2e along with several other refs, I'm also still a bit fuzzy on the full sequence of calls to generate a toc. – zun Mar 5 '15 at 14:27
  • @zun The \write operation is part of \chapter (precisely of \@chapter, via \addcontentsline. TeX always does complete expansion when writing to external files, unless this expansion is inhibited (and \protect serves this purpose). So \normalfont is written as such because it has been protected in advance by the LaTeX kernel, but \small isn't because the developers didn't expect it to sneak in the .aux file. – egreg Mar 5 '15 at 17:28

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.