4.8.1 Writing the .toc file

To write an entry for the table of contents, you say \writetocentry{part}{text}, where part is the type of part this entry is, e.g., `chapter', and text is the text of the title. \writetocentry puts an entry into the .toc file that looks like \tocpartentry{text}{page number} (unless part is an integer, see below). The text is written unexpanded.

A related command, \writenumberedtocentry, takes one additional argument, the first token of which is expanded at the point of the \writenumberedtocentry, but the rest of the argument is not expanded. The usual application is when the parts of the document are numbered. On the other hand, the one-level expansion allows you to use the argument for other things as well (author's names in a proceedings, say), and not have accents or other control sequences expanded. The downside is that if you want full expansion of the third argument, you don't get it—you must expand it yourself, before you call \writenumberedtocentry.

For example:

     \writenumberedtocentry{chapter}{A $\sin$ wave}{\the\chapno}
     \writetocentry{section}{A section title}

Supposing \the\chapno expanded to `3' and that the \write's occurred on pages eight and nine, respectively, the above writes the following to the .toc file:

     \tocchapterentry{A $\sin$ wave}{3}{8}
     \tocsectionentry{A section title}{9}

A variation on \writenumberedtocentry is \writenumberedtocline, differing only in the order of the parameters it takes and writes for the \tocpartentry control sequences. To continue the previous example:

     \writenumberedtocline{chapter}{\the\chapno}{A $\sin$ wave}

writes the following to the .toc file:

     \tocchapterentry{3}{A $\sin$ wave}{8}

Such ordering of the parameters allows the \tocpartentry macros to typeset the text of the entry without actually reading it as an argument. This is required for entries which need to change character catcodes, e.g., to produce verbatim text (see Verbatim listing).

Each of \writetocentry, \writenumberedtocentry and \writenumberedtocline processes a numeric part argument specially. If you pass part expanding to an integer, these macros write into the .toc file an entry that starts with \tocentry{part}. Thus, you can define a single \tocentry macro which formats all entries for a table of contents. To continue the previous examples:

     \writenumberedtocentry{1}{A $\sin$ wave}{\the\chapno}
     \writenumberedtocline{1}{\the\chapno}{A $\sin$ wave}
     \writetocentry{2}{A section title}

writes the following to the .toc file:

     \tocentry{1}{A $\sin$ wave}{3}{8}
     \tocentry{1}{3}{A $\sin$ wave}{8}
     \tocentry{2}{A section title}{9}