# Example of contentsline

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?

• \contentsline doesn't setup a line in the content, but is used by the table of content to typeset its contents. To add something to your ToC you should use \addcontentsline or \addtocontents (the former being easier to use if you want to add an entry, the latter being for arbitrary stuff). – Skillmon Aug 17 '18 at 18:55
• What exactly are you after? What do you want to achieve with your use of \contentsline? Write something to the ToC? – Werner Aug 17 '18 at 19:13
• Hello @Werner, my goal is to learn what is the genral use of contentsline through an example. – Gennaro Arguzzi Aug 17 '18 at 19:22
• @GennaroArguzzi The general use of \contentsline is don't use \contentsline yourself. It is only defined as \contentsline=macro: #1->\csname l@#1\endcsname in all the standard classes. It gets used by the ToC, LoT and LoF. – Skillmon Aug 17 '18 at 20:13

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.

• sorry for the delay. Your answer is very clear. – Gennaro Arguzzi Sep 5 '18 at 16:12

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.

• Hello @egreg, sorry for the delay. Thank you very much for your good explanation. – Gennaro Arguzzi Sep 5 '18 at 16:13