\startcomponent ma-cb-en-tablesofcontent

\product ma-cb-en

\chapter{Table of contents (lists)}

\index{table of contents}
\index{list}

\Command{\tex{completecontent}}
\Command{\tex{placecontent}}
\Command{\tex{definelist}}
\Command{\tex{setuplist}}
\Command{\tex{writetolist}}
\Command{\tex{writebetweenlist}}
\Command{\tex{definecombinedlist}}
\Command{\tex{setupcombinedlist}}

A table of contents contains chapter numbers, chapter titles
and page numbers and can be extended with sections,
sub sections, etc. A table of contents is generated
automatically by typing:

\starttyping
\placecontent
\stoptyping

Which table of contents is produced depends on the location
of this command in your document. At the start of the
document it will generate a list of chapters, sections etc.
But at the top of a chapter:

\startbuffer
\chapter{Hasselt in Summer}

\placecontent

\section{Hasselt in July}

\section{Hasselt in August}

\stopbuffer

\typebuffer

it will only produce a list of (sub) section titles with the
corresponding section numbers and page numbers.

The command \type{\placecontent} is available after
definition with:

\shortsetup{definecombinedlist}

This command and \type{\definelist} allows you to define
your own lists necessary for structuring your documents.

The use of this command and its related commands is
illustrated for the table of contents.

\startbuffer
\definelist[chapter]
\setuplist
   [chapter]
   [before=\blank,
    after=\blank,
    style=bold]

\definelist[section]
\setuplist
   [section]
   [alternative=d]
\stopbuffer

\typebuffer

Now there are two lists of chapters and sections and these
will be combined in a table of contents with the command
\type{\definecombinedlist}.

\startbuffer
\definecombinedlist
   [content]
   [chapter,section]
   [level=subsection]
\stopbuffer

\typebuffer

Now two commands are available: \type{\placecontent} and
\type{\completecontent}. With the second command the title
of the table of contents will be added to the table of
contents.

The layout of lists can be varied with the parameter
\type{alternative}.

\placetable
  [here,force]
  [tab:alternatives]
  {Alternatives for displaying lists.}
\starttable[|c|l|]
\HL
\NC \bf Alternative \NC \bf Display \NC\SR
\HL
\NC \type{a} \NC number -- title -- page number              \NC\FR
\NC \type{b} \NC number -- title -- spaces -- page number    \NC\MR
\NC \type{c} \NC number -- title -- dots -- page number      \NC\MR
\NC \type{d} \NC number -- title -- page number (continuing) \NC\MR
\NC \type{e} \NC reserved for interactive purposes           \NC\MR
\NC \type{f} \NC reserved for interactive purposes           \NC\LR
\HL
\stoptable

Lists are set up with:

\shortsetup{setuplist}
\shortsetup{setupcombinedlist}

If you want to change the layout of the generated table of
contents you'll have to remember that it is a list.

\startbuffer
\setupcombinedlist
  [content]
  [alternative=c,
   aligntitle=no,
   width=2.5cm]
\stopbuffer

\typebuffer

This will result in a somewhat different layout than the
default one.

Lists are called up and placed with:

\shortsetup{placelist}

So if you want a table of content you type:

\starttyping
\placecontent[level=section]
\stoptyping

or

\starttyping
\completecontent[level=section]
\stoptyping

only the sections will be displayed. You may need this
option when you have a well structured document that has sub
sub sub sub sub sections and you don't want those in the
table of contents.

A long list or a long table of contents will use up more
than one page. To be able to force page breaking you can
type:

\starttyping
\completecontent[2.2,8.5,12.3.3]
\stoptyping

A page break will occur after section 2.2 and 8.5 and
sub section~12.3.3.

In some cases you want to be able to write your own text in
an automatically generated list. This is done with:

\shortsetup{writetolist}
\shortsetup{writebetweenlist}

For example if you want to make a remark in your table of
contents after a section titled {\em Hotels in Hasselt}
you can type:

\startbuffer
\section{Hotels in Hasselt}
\writebetweenlist[section]{\blank}
\writetolist[section]{}{---under construction---}
\writebetweenlist[section]{\blank}
\stopbuffer

\typebuffer

\stopcomponent
