Example of contentsline
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.
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.