Tables of Contents

There are two types of TOCs in PerlPoint. One type is a list of subchapters, inserted by the \LOCALTOC tag. (See the end of this chapter for the second type.)

    \LOCALTOC

When the document will be processed, this line will be replaced by a table of contents for all subchapters of the current section.

Why is this tag called LOCALTOC? The "local" shows that you can use it anywhere, not just at the documents beginning, to show a partial TOC and not the whole tree. A local TOC lists all subchapters of the current chapter level.

    =The ons and outs
  
    ==Three ways to switch the light on
  
    \LOCALTOC
  
    ===Use a shout and a noice sensor
  
    ===Switch it by a MagLight
  
    ===Traditionalists prefer a fix installation
  
    ==Switch it out
  
    ...

The TOC built in this example includes the three subchapters of "Three ways ...". If we would have placed it a level above, "Three ways ..." and "Switch it out", would have become part of the TOC as well.

    =The ons and outs
  
    \LOCALTOC
  
    ==Three ways to switch the light on
  
    ===Use a shout and a noice sensor
  
    ===Switch it by a MagLight
  
    ===Traditionals prefer a ...
  
    ==Switch it out
  
    ...

By the way, it is no error to have local TOCs on nested levels.

    =The ons and outs
  
    \LOCALTOC
  
    ==Three ways to switch the light on
  
    \LOCALTOC
  
    ===Use a shout and a noice sensor
  
    ===Switch it by a MagLight
  
    ===Traditionals prefer a ...
  
    ==Switch it out
  
    \LOCALTOC
  
    ...

In this example, each of the chapters on level 1 has its local TOC, while the subchapters on level 2 have some as well.

A local TOC is often useful to fill an "empty page", in cases like this:

    =Useful Perl modules to catch options
  
    ==Getopt::Long
  
    ... ...
  
    ==Getopt::Std
  
    ... ...
  
    ==Getopt::ArgvFile
  
    ... ...

Structures like this use a container chapter to form a theme, but often there is no text provided in the container itself. With a page oriented PerlPoint converter like pp2html, this ends up with an empty slide (or page) for the container chapter. Using a local TOC, it is easy to fill the space:

    =Useful Perl modules to catch options
  
    \LOCALTOC
  
    ==Getopt::Long
  
    ... ...
  
    ==Getopt::Std
  
    ... ...
  
    ==Getopt::ArgvFile
  
    ... ...

This gives readers an impression of what will follow, and simplifies navigation. Well ... it could, if only the TOC was built of links. Till now, all we produced was raw text. But this changes if we use the type option:

    \LOCALTOC{type=linked}

which instantly converts all subchapter entries into links, given that the output format supports this.

Besides local TOCs, TOCs for the whole document are required. These are not inserted by a tag but by a template function, see below.