Example of contentsline

Question

I would like to learn how to use the command contentsline; to do this I wrote the code:

\documentclass{article}
\usepackage[utf8]{inputenc}


\begin{document}

\maketitle

\tableofcontents
\clearpage

\section{Paragrafo 1}
Questo è il paragrafo 1

\subsection{Sottoparagrafo 1.1}
Questo è il sottoparagrafo 1.1

\contentsline{chapter}{Prefazione}{2}

\section{Paragrafo 2}
Questo è il paragrafo 2

\end{document}

The result is strange: contentsline has no effect on the table of contents. Can you show me an example of the use of contentsline please?

Answer 1

If you want to add a specific entry to your ToC at the chapter level, you should use \addcontentsline{toc}{chapter}{Prefazione} in your example. The page will be the current page (so the page this macro is executed on). You could add arbitrary stuff to your ToC with \addtocontents (mainly used for formatting instructions).

To add a specific entry with a forced page number, you could use \addtocontents{toc}{\string\contentsline{section}{Foobar}{100}}. Don't use chapter here, as article doesn't have this layer and it would result in errors.

The \contentsline macro is used internally to typeset each entry of the ToC. It is defined to call the macro \l@#1 (build with \csname l@#1\endcsname), so if \contentsline{chapter} is encountered, the \l@chapter macro will be called. This one grabs the other two arguments of \contentsline and typesets the chapter entry.

In article the macro \l@chapter wouldn't be defined though, so your \contentsline{chapter} would call \relax (as each undefined macro name build with \csname equals a \relax). For that reason the other two arguments you specify are just typeset, as they are never actually grabbed.

Answer 2

The \contentsline macro should never be used directly in a document. It's LaTeX's duty to write such macro with the appropriate arguments in the .toc file or other auxiliary files for the various lists.

The instruction for this is \addcontentsline, which is usually implicit in macros such as \chapter, \section, other sectional commands and \caption.

If you have \addcontentsline{<file>}{<level>}{<text>} in your document, LaTeX will write in the appropriate file a line of the form

\contentsline{<level>}{<text>}{<page>}

The <type> can be toc, lof or lot (table of contents, list of figures or list of tables) and corresponds to the extension for the auxiliary file. Note that the page number will be automatically supplied, because the write operation is performed when a page is being shipped out, when the page number is known precisely. Other <file> types might be available, depending on packages used or on definitions of new lists done in the document (the package of choice is newfloat).

There is also \addtocontents{<type>}{<text>}, which will write the raw <text> in the corresponding file, but this requires precise knowledge about how the file is subsequently used.

One should also remember that <text> is subject to expansion, so \protect should be used if some macro is not to be expanded prior to writing.

It's a duty of the document class (or of packages defining new lists) to define the working of \contentsline: by default, the line

\contentsline{<level>}{<text>}{<page>}

will be transformed into

\l@<level>{<text>}{<page>}

For instance, \contentsline{chapter}{Prefazione}{2} will become \l@chapter{Prefazione}{2} and the macro \l@chapter should be defined by the document class (it isn't in article).

Note that hyperref changes \addcontentsline and \contentsline to add more arguments for the purpose of hyperlinks.