=head1 NAME

HTML::Toc - Generate, insert and update HTML Table of Contents.

=head1 DESCRIPTION

Generate, insert and update HTML Table of Contents.

=head1 Introduction

The HTML::Toc consists out of the following packages:

    HTML::Toc
    HTML::TocGenerator
    HTML::TocInsertor
    HTML::TocUpdator

HTML::Toc is the object which will eventually hold the Table of Contents.  HTML::TocGenerator does the actual generation of the ToC.  HTML::TocInsertor handles the insertion of the ToC in the source.  HTML::TocUpdator takes care of updating previously inserted ToCs.

HTML::Parser is the base object of HTML::TocGenerator, HTML::TocInsertor and HTML::TocUpdator.  Each of these objects uses its predecessor as its ancestor, as shown in the UML diagram underneath:
    
    +---------------------+
    |    HTML::Parser     |
    +---------------------+
    +---------------------+
    |    +parse()         |
    |    +parse_file()    |
    +----------+----------+
              /_\
               |
    +----------+----------+  <<uses>>  +-----------+
    | HTML::TocGenerator  + - - - - - -+ HTML::Toc |
    +---------------------+            +-----------+
    +---------------------+            +-----------+
    | +extend()           |            | +clear()  |
    | +extendFromFile()   |            | +format() |
    | +generate()         |            +-----+-----+
    | +generateFromFile() |                  :
    +----------+----------+                  :
              /_\                            :
               |                             :
    +----------+----------+     <<uses>>     :
    |  HTML::TocInsertor  + - - - - - - - - -+
    +---------------------+                  :
    +---------------------+                  :
    |  +insert()          |                  :
    |  +insertIntoFile()  |                  :
    +----------+----------+                  :
              /_\                            :
               |                             :
    +----------+----------+     <<uses>>     :
    |  HTML::TocUpdator   + - - - - - - - - -+
    +---------------------+
    +---------------------+
    |  +insert()          |
    |  +insertIntoFile()  |
    |  +update()          |
    |  +updateFile()      |
    +---------------------+

When generating a ToC you'll have to decide which object you want to use:

    TocGenerator:
        for generating a ToC without inserting the ToC into the source
    TocInsertor:
        for generating a ToC and inserting the ToC into the source
    TocUpdator:
        for generating and inserting a ToC, removing any previously
        inserted ToC elements

Thus in tabular view, each object is capable of:

                   generating   inserting   updating
                   ---------------------------------
    TocGenerator        X
    TocInsertor         X           X
    TocUpdator          X           X           X

=head2 Generating

The code underneath will generate a ToC of the HTML headings C<<h1>>..C<<h6>> from a file C<index.htm>:

    use HTML::Toc;
    use HTML::TocGenerator;

    my $toc          = HTML::Toc->new();
    my $tocGenerator = HTML::TocGenerator->new();

    $tocGenerator->generateFromFile($toc, 'index.htm');
    print $toc->format();

For example, with C<index.htm> containing:

    <html>
    <body>
       <h1>Chapter</h1>
    </body>
    </html>

the output will be:

    
    <!-- Table of Contents generated by Perl - HTML::Toc -->
    <ul>
       <li><a href=#h-1>Chapter</a>
    </ul>
    <!-- End of generated Table of Contents -->

=head2 Inserting

This code will generate a ToC of HTML headings C<<h1>>..C<<h6>> of file C<index.htm>, and insert the ToC after the C<<body>> tag at the same time:

    use HTML::Toc;
    use HTML::TocInsertor;

    my $toc         = HTML::Toc->new();
    my $tocInsertor = HTML::TocInsertor->new();

    $tocInsertor->insertIntoFile($toc, 'index.htm');

For example, with C<index.htm> containing:

    <html>
    <body>
       <h1>Chapter</h1>
    </body>
    </html>

the output will be:

    <html>
    <body>
    <!-- Table of Contents generated by Perl - HTML::Toc -->
    <ul>
       <li><a href=#h-1>Chapter</a>
    </ul>
    <!-- End of generated Table of Contents -->

       <a name=h-1><h1>Chapter</h1></a>
    </body>
    </html>

If you're planning to update the inserted ToC, you'd better use C<TocUpdator> to insert the ToC.  C<TocUpdator> marks the inserted ToC elements with update tokens.  These update tokens allow C<TocUpdator> to identify and remove the ToC elements during a future update session.  This code uses C<TocUpdator> instead of C<TocInsertor>:

    use HTML::Toc;
    use HTML::TocUpdator;

    my $toc        = HTML::Toc->new();
    my $tocUpdator = HTML::TocUpdator->new();

    $tocUpdator->insertIntoFile($toc, 'index.htm');

When applying the code above on 'index.htm':

    <html>
    <body>
       <h1>
       Chapter
       </h1>
    </body>
    </html>

the output will contain additional update tokens:

    <!-- #BeginToc -->
    <!-- #EndToc -->
    <!-- #BeginTocAnchorNameBegin -->
    <!-- #EndTocAnchorNameBegin -->
    <!-- #BeginTocAnchorNameEnd -->
    <!-- #EndTocAnchorNameEnd -->

around the inserted ToC elements:

    <html>
    <body><!-- #BeginToc-->
    <!-- Table of Contents generated by Perl - HTML::Toc -->
    <ul>
       <li><a href=#h-1> Chapter </a>
    </ul>
    <!-- End of generated Table of Contents -->
    <!-- #EndToc -->
       <!-- #BeginTocAnchorNameBegin --><a name=h-1><!-- #EndTocAnchorNameBegin --><h1>
       Chapter
       </h1><!-- #BeginTocAnchorNameEnd --></a><!-- #EndTocAnchorNameEnd -->
    </body>
    </html>

Instead of C<HTML::TocUpdator::insertIntoFile> you can also use C<HTML::TocUpdator::updateFile()>.  C<HTML::TocUpdator::updateFile()> will also insert the ToC, whether there is a ToC already inserted or not.

=head2 Updating

This code will generate a ToC of HTML headings C<<h1>>..C<<h6>> of file C<indexToc.htm>, and insert or update the ToC after the C<<body>> tag at the same time:

    use HTML::Toc;
    use HTML::TocUpdator;

    my $toc        = HTML::Toc->new();
    my $tocUpdator = HTML::TocUpdator->new();

    $tocUpdator->updateFile($toc, 'indexToc.htm');

For example, with C<indexToc.htm> containing:

    <html>
    <body><!-- #BeginToc -->
    foo
    <!-- #EndToc -->
       <!-- #BeginTocAnchorNameBegin -->bar<!-- #EndTocAnchorNameBegin --><h1>
       Chapter
       </h1><!-- #BeginTocAnchorNameEnd -->foo<!-- #EndTocAnchorNameEnd -->
    </body>h
    </html>

the output will be:

    <html>
    <body><!-- #BeginToc -->
    <!-- Table of Contents generated by Perl - HTML::Toc -->
    <ul>
       <li><a href=#h-1> Chapter </a>
    </ul>
    <!-- End of generated Table of Contents -->
    <!-- #EndToc -->
       <!-- #BeginTocAnchorNameBegin --><a name=h-1><!-- #EndTocAnchorNameBegin --><h1>
       Chapter
       </h1><!-- #BeginTocAnchorNameEnd --></a><!-- #EndTocAnchorNameEnd -->
    </body>
    </html>

All text between the update tokens will be replaced.  So be warned: all manual changes made to text between update tokens will be removed unrecoverable after calling C<HTML::TocUpdator::update()> or C<HTML::TocUpdator::updateFile()>.

=head2 Formatting

The ToC isn't generated all at once.  There are two stages involved: generating and formatting.  Generating the ToC actually means storing a preliminary ToC in C<HTML::Toc-E<gt>{_toc}>.  This preliminary, tokenized ToC has to be turned into something useful by calling C<HTML::Toc-E<gt>format()>.  For an example, see paragraph 'L<Generating|"generating">'.

=head1 Advanced

The ToC generation can be modified in a variety of ways.  The following paragraphs each explain a single modification.  An example of most of the modifications can be found in the C<manualTest.t> test file.  Within this test, a manual containing:

    preface
    introduction
    table of contents
    table of figures
    table of tables
    parts
    chapters
    appendixes
    bibliography

is formatted.

=head2 Using attribute value as ToC text

Normally, the ToC will be made of text between specified ToC tokens.  It's also possible to use the attribute value of a token as a ToC text.  This can be done by specifying the attribute marked with an L<attributeToTocToken|"attributeToTocToken"> within the L<tokenBegin|"tokenBegin"> token.  For example, suppose you want to generate a ToC of the C<alt> attributes of the following image tokens:

    <body>
       <img src=test1.gif alt="First picture">
       <img src=test2.gif alt="Second picture">
    </body>

This would be the code:

    use HTML::Toc;
    use HTML::TocInsertor;

    my $toc         = HTML::Toc->new();
    my $tocInsertor = HTML::TocInsertor->new();

    $toc->setOptions({
       'tokenToToc'   => [{
          'groupId'    => 'image',
          'tokenBegin' => '<img alt=@>'
       }],
    });
    $tocInsertor->insertIntoFile($toc, $filename);

and the output will be:

    <body>
    <!-- Table of Contents generated by Perl - HTML::Toc -->
    <ul>
       <li><a href=#image-1>First picture</a>
       <li><a href=#image-2>Second picture</a>
    </ul>
    <!-- End of generated Table of Contents -->

       <a name=image-1><img src=test1.gif alt="First picture"></a>
       <a name=image-2><img src=test2.gif alt="Second picture"></a>
    </body>

=head2 Generate single ToC of multiple files

Besides generating a ToC of a single file, it's also possible to generate a single ToC of multiple files.  This can be done by specifying either an array of files as the file argument and/or by extending an existing ToC.

=head3 Specify an array of files

For example, suppose you want to generate a ToC of both C<doc1.htm>:

    <body>
       <h1>Chapter of document 1</h1>
    </body>

and C<doc2.htm>:

    <body>
       <h1>Chapter of document 2</h1>
    </body>

Here's the code to do so by specifying an array of files:

    use HTML::Toc;
    use HTML::TocGenerator;

    my $toc          = HTML::Toc->new();
    my $tocGenerator = HTML::TocGenerator->new();

    $toc->setOptions({'doLinkToFile' => 1});
    $tocGenerator->generateFromFile($toc, ['doc1.htm', 'doc2.htm']);
    print $toc->format();

And the output will be:


    <!-- Table of Contents generated by Perl - HTML::Toc -->
    <ul>
       <li><a href=doc1.htm#h-1>Chapter of document 1</a>
       <li><a href=doc2.htm#h-2>Chapter of document 2</a>
    </ul>
    <!-- End of generated Table of Contents -->

=head3 Extend an existing ToC

It's also possible to extend an existing ToC.  For example, suppose we want the generate a ToC of file C<doc1.htm>:

    <body>
       <h1>Chapter of document 1</h1>
    </body>

and extend this ToC with text from C<doc2.htm>:

    <body>
       <h1>Chapter of document 2</h1>
    </body>

Here's the code to do so:

    use HTML::Toc;
    use HTML::TocGenerator;

    my $toc          = HTML::Toc->new();
    my $tocGenerator = HTML::TocGenerator->new();

    $toc->setOptions({'doLinkToFile' => 1});
    $tocGenerator->generateFromFile($toc, 'doc1.htm');
    $tocGenerator->extendFromFile($toc, 'doc2.htm');
    print $toc->format();

And the output will be:


    <!-- Table of Contents generated by Perl - HTML::Toc -->
    <ul>
       <li><a href=doc1.htm#h-1>Chapter of document 1</a>
       <li><a href=doc2.htm#h-2>Chapter of document 2</a>
    </ul>
    <!-- End of generated Table of Contents -->

=head2 Generate multiple ToCs

It's possible to generate multiple ToCs at once by specifying a C<HTML::Toc> object array as the ToC argument.  For example, suppose you want to generate a default ToC of HTML headings <h1>..<h6> as well as a ToC of the C<alt> image attributes of the following text:

    <body>
       <h1>Header One</h1>
       <img src=test1.gif alt="First picture" id=image_001>
       <h2>Paragraph One</h2>
       <img src=test2.gif alt="Second picture" id=image_002>
    </body>

Here's how you would do so:

    use HTML::Toc;
    use HTML::TocInsertor;

    my $toc1        = HTML::Toc->new();
    my $toc2        = HTML::Toc->new();
    my $tocInsertor = HTML::TocInsertor->new();

    $toc2->setOptions({
       'tokenToToc'   => [{
          'groupId'    => 'image',
          'tokenBegin' => '<img alt=@>'
       }],
    });
    $tocInsertor->insertIntoFile([$toc1, $toc2], $filename);

And the output will be:

    <body>
    <!-- Table of Contents generated by Perl - HTML::Toc -->
    <ul>
       <li><a href=#h-1>Header One</a>
       <ul>
          <li><a href=#h-1.1>Paragraph One</a>
       </ul>
    </ul>
    <!-- End of generated Table of Contents -->

    <!-- Table of Contents generated by Perl - HTML::Toc -->
    <ul>
       <li><a href=#image-1>First picture</a>
       <li><a href=#image-2>Second picture</a>
    </ul>
    <!-- End of generated Table of Contents -->

       <a name=h-1><h1>Header One</h1></a>
       <a name=image-1><img src=test1.gif alt="First picture"></a>
       <a name=h-1.1><h2>Paragraph One</h2></a>
       <a name=image-2><img src=test2.gif alt="Second picture"></a>
    </body>

=head2 Generate multiple groups in one ToC

You may want to generate a ToC consisting of multiple ToC groups.

=head3 Specify an additional 'Appendix' group

Suppose you want to generate a ToC with one group for the normal headings, and one group for the appendix headings, using this source file:

    <body>
       <h1>Chapter</h1>
       <h2>Paragraph</h2>
       <h3>Subparagraph</h3>
       <h1>Chapter</h1>
       <h1 class=appendix>Appendix Chapter</h1>
       <h2 class=appendix>Appendix Paragraph</h2>
    </body>

With the code underneath:

    use HTML::Toc;
    use HTML::TocInsertor;

    my $toc         = HTML::Toc->new();
    my $tocInsertor = HTML::TocInsertor->new();

    $toc->setOptions({
       'tokenToToc' => [{
             'tokenBegin' => '<h1 class=-appendix>'
          }, {
             'tokenBegin' => '<h2 class=-appendix>',
             'level'      => 2
          }, {
             'groupId'    => 'appendix',
             'tokenBegin' => '<h1 class=appendix>',
          }, {
             'groupId'    => 'appendix',
             'tokenBegin' => '<h2 class=appendix>',
             'level'      => 2
          }]
    });
    $tocInsertor->insertIntoFile($toc, $filename);

the output will be:

    <body>
    <!-- Table of Contents generated by Perl - HTML::Toc -->
    <ul>
       <li><a href=#h-1>Chapter</a>
       <ul>
          <li><a href=#h-1.1>Paragraph</a>
       </ul>
       <li><a href=#h-2>Chapter</a>
    </ul>
    <ul>
       <li><a href=#appendix-1>Appendix Chapter</a>
       <ul>
          <li><a href=#appendix-1.1>Appendix Paragraph</a>
       </ul>
    </ul>
    <!-- End of generated Table of Contents -->

       <a name=h-1><h1>Chapter</h1></a>
       <a name=h-1.1><h2>Paragraph</h2></a>
       <h3>Subparagraph</h3>
       <a name=h-2><h1>Chapter</h1></a>
       <a name=appendix-1><h1 class=appendix>Appendix Chapter</h1></a>
       <a name=appendix-1.1><h2 class=appendix>Appendix Paragraph</h2></a>
    </body>

=head3 Specify an additional 'Part' group

Suppose you want to generate a ToC of a document which is divided in multiple parts like this file underneath:

    <body>
       <h1 class=part>First Part</h1>
       <h1>Chapter</h1>
       <h2>Paragraph</h2>
       <h1 class=part>Second Part</h1>
       <h1>Chapter</h1>
       <h2>Paragraph</h2>
    </body>

With the code underneath:

    use HTML::Toc;
    use HTML::TocInsertor;

    my $toc         = HTML::Toc->new();
    my $tocInsertor = HTML::TocInsertor->new();

    $toc->setOptions({
       'doNumberToken'    => 1,
       'tokenToToc' => [{
             'tokenBegin' => '<h1 class=-part>'
          }, {
             'tokenBegin' => '<h2 class=-part>',
             'level'      => 2,
          }, {
             'groupId'        => 'part',
             'tokenBegin'     => '<h1 class=part>',
             'level'          => 1,
             'numberingStyle' => 'upper-alpha'
          }]
    });
    $tocInsertor->insertIntoFile($toc, $filename);

the output will be:

    <body>
    <!-- Table of Contents generated by Perl - HTML::Toc -->
    <ul>
       <li><a href=#part-A>First Part</a>
    </ul>
    <ul>
       <li><a href=#h-1>Chapter</a>
       <ul>
          <li><a href=#h-1.1>Paragraph</a>
       </ul>
    </ul>
    <ul>
       <li><a href=#part-B>Second Part</a>
    </ul>
    <ul>
       <li><a href=#h-2>Chapter</a>
       <ul>
          <li><a href=#h-2.1>Paragraph</a>
       </ul>
    </ul>
    <!-- End of generated Table of Contents -->

       <a name=part-A><h1 class=part>A &nbsp;First Part</h1></a>
       <a name=h-1><h1>1 &nbsp;Chapter</h1></a>
       <a name=h-1.1><h2>1.1 &nbsp;Paragraph</h2></a>
       <a name=part-B><h1 class=part>B &nbsp;Second Part</h1></a>
       <a name=h-2><h1>2 &nbsp;Chapter</h1></a>
       <a name=h-2.1><h2>2.1 &nbsp;Paragraph</h2></a>
    </body>

=head2 Number ToC entries

By default, the generated ToC will list its entries unnumbered.  If you want to number the ToC entries, two options are available.  Either you can specify a numbered list by modifying L<templateLevelBegin|"templateLevelBegin"> and L<templateLevelEnd|"templateLevelEnd">.  Or when the ToC isn't a simple numbered list, you can use the numbers generated by HTML::TocGenerator.

=head3 Specify numbered list

By modifying L<templateLevelBegin|"templateLevelBegin"> and L<templateLevelEnd|"templateLevelEnd"> you can specify a numbered ToC:

    use HTML::Toc;
    use HTML::TocGenerator;

    my $toc          = HTML::Toc->new();
    my $tocGenerator = HTML::TocGenerator->new();

    $toc->setOptions({
        'templateLevelBegin' => '"<ol>\n"',
        'templateLevelEnd'   => '"</ol>\n"',
    });
    $tocGenerator->generateFromFile($toc, 'index.htm');
    print $toc->format();

For instance with the original file containing:

    <body>
        <h1>Chapter</h1>
        <h2>Paragraph</h2>
    </body>

The formatted ToC now will contain C<ol> instead of C<ul> tags:

    <!-- Table of Contents generated by Perl - HTML::Toc -->
    <ol>
       <li><a href=#h-1>Chapter</a>
       <ol>
          <li><a href=#h-1.1>Paragraph</a>
       </ol>
    </ol>
    <!-- End of generated Table of Contents -->

See also: L<Using CSS for ToC formatting|"Using CSS for ToC formatting">.

=head3 Use generated numbers

Instead of using the HTML ordered list (OL), it's also possible to use the generated numbers to number to ToC nodes.  This can be done by modifying L<templateLevel|"templateLevel">:

    use HTML::Toc;
    use HTML::TocGenerator;

    my $toc          = HTML::Toc->new();
    my $tocGenerator = HTML::TocGenerator->new();

    $toc->setOptions({
		'templateLevel' => '"<li>$node &nbsp;$text\n"',
    });
    $tocGenerator->generateFromFile($toc, 'index.htm');
    print $toc->format();

For instance with the original file containing:

    <body>
        <h1>Chapter</h1>
        <h2>Paragraph</h2>
    </body>

The formatted ToC now will have the node numbers hard-coded:

    <!-- Table of Contents generated by Perl - HTML::Toc -->
    <ul>
       <li>1 &nbsp;<a href=#h-1>Chapter</a>
       <ul>
          <li>1.1 &nbsp;<a href=#h-1.1>Paragraph</a>
       </ul>
    </ul>
    <!-- End of generated Table of Contents -->

See also: L<Using CSS for ToC formatting|"Using CSS for ToC formatting">.

=head2 Using CSS for ToC formatting

Suppose you want to display a ToC with upper-alpha numbered appendix headings.  To accomplish this, you can specify a CSS style within the source document:

    <html>
    <head>
       <style type="text/css">
          ol.toc_appendix1 { list-style-type: upper-alpha }
       </style>
    </head>
    <body>
       <h1 class=appendix>Appendix</h1>
       <h2 class=appendix>Appendix Paragraph</h2>
       <h1 class=appendix>Appendix</h1>
       <h2 class=appendix>Appendix Paragraph</h2>
    </body>
    </html>

Here's the code:

    my $toc          = new HTML::Toc;
    my $tocInsertor  = new HTML::TocInsertor;

    $toc->setOptions({
       'templateLevelBegin'   => '"<ol class=toc_$groupId$level>\n"',
       'templateLevelEnd'     => '"</ol>\n"',
       'doNumberToken'        => 1,
       'tokenToToc' => [{
             'groupId'        => 'appendix',
             'tokenBegin'     => '<h1>',
             'numberingStyle' => 'upper-alpha'
          }, {
             'groupId'        => 'appendix',
             'tokenBegin'     => '<h2>',
             'level'          => 2,
         }]
    });
    $tocInsertor->insertIntoFile($toc, $filename);

Which whill result in the following output:

    <html>
    <head>
       <style type="text/css">
          ol.toc_appendix1 { list-style-type: upper-alpha }
       </style>
    </head>
    <body>
    <!-- Table of Contents generated by Perl - HTML::Toc -->
    <ol class=toc_appendix1>
       <li><a href=#appendix-A>Appendix</a>
       <ol class=toc_appendix2>
          <li><a href=#appendix-A.1>Appendix Paragraph</a>
       </ol>
       <li><a href=#appendix-B>Appendix</a>
       <ol class=toc_appendix2>
          <li><a href=#appendix-B.1>Appendix Paragraph</a>
       </ol>
    </ol>
    <!-- End of generated Table of Contents -->

       <a name=appendix-A><h1>A &nbsp;Appendix</h1></a>
       <a name=appendix-A.1><h2>A.1 &nbsp;Appendix Paragraph</h2></a>
       <a name=appendix-B><h1>B &nbsp;Appendix</h1></a>
       <a name=appendix-B.1><h2>B.1 &nbsp;Appendix Paragraph</h2></a>
    </body>
    </html>

=head2 Creating site map

Suppose you want to generate a table of contents of the E<lt>titleE<gt> tags of the files in the following directory structure:

    path               file

    .                  index.htm, <title>Main</title>
    |- SubDir1         index.htm, <title>Sub1</title>
    |  |- SubSubDir1   index.htm, <title>SubSub1</title>
    |
    |- SubDir2         index.htm, <title>Sub2</title>
    |  |- SubSubDir1   index.htm, <title>SubSub1</title>
    |  |- SubSubDir2   index.htm, <title>SubSub2</title>
    |
    |- SubDir3         index.htm, <title>Sub3</title>

By specifying 'fileSpec' which determine how many slashes (/) each file may contain for a specific level:

    use HTML::Toc;
    use HTML::TocGenerator;
    use File::Find;

    my $toc          = HTML::Toc->new;
    my $tocGenerator = HTML::TocGenerator->new;
    my @fileList;

    sub wanted {
          # Add file to 'fileList' if extension matches '.htm'
       push (@fileList, $File::Find::name) if (m/\.htm$/);
    }

    $toc->setOptions({
       'doLinkToFile'       => 1,
       'templateAnchorName' => '""',
       'templateAnchorHref' => '"<a href=$file"."#".$groupId.$level.">"',
       'doLinkTocToToken'   => 1,
       'tokenToToc'         => [{
          'groupId'         => 'dir',
          'level'           => 1,
          'tokenBegin'      => '<title>',
          'tokenEnd'        => '</title>',
          'fileSpec'        => '\./[^/]+$'
       }, {
          'groupId'         => 'dir',
          'level'           => 2,
          'tokenBegin'      => '<title>',
          'tokenEnd'        => '</title>',
          'fileSpec'        => '\./[^/]+?/[^/]+$'
       }, {
          'groupId'         => 'dir',
          'level'           => 3,
          'tokenBegin'      => '<title>',
          'tokenEnd'        => '</title>',
          'fileSpec'        => '\./[^/]+?/[^/]+?/[^/]+$'
       }]
    });

       # Traverse directory structure
    find({wanted => \&wanted, no_chdir => 1}, '.');
       # Generate ToC of case-insensitively sorted file list
    $tocGenerator->extendFromFile(
       $toc, [sort {uc($a) cmp uc($b)} @fileList]
    );
    print $toc->format();

the following ToC will be generated:

    <!-- Table of Contents generated by Perl - HTML::Toc -->
    <ul>
       <li><a href=./index.htm#>Main</a>
       <ul>
          <li><a href=./SubDir1/index.htm#>Sub1</a>
          <ul>
             <li><a href=./SubDir1/SubSubDir1/index.htm#>SubSub1</a>
          </ul>
          <li><a href=./SubDir2/index.htm#>Sub2</a>
          <ul>
             <li><a href=./SubDir2/SubSubDir1/index.htm#>SubSub1</a>
             <li><a href=./SubDir2/SubSubDir2/index.htm#>SubSub2</a>
          </ul>
          <li><a href=./SubDir3/index.htm#>Sub3</a>
       </ul>
    </ul>
    <!-- End of generated Table of Contents -->

=head1 Methods

=head2 HTML::Toc::clear()

    syntax:  $toc->clear()
    returns: --

Clear the ToC.

=head2 HTML::Toc::format()

    syntax:  $scalar = $toc->format()
    returns: Formatted ToC.

Format tokenized ToC.

=head2 HTML::TocGenerator::extend()

    syntax:  $tocGenerator->extend($toc, $string [, $options])
    args:    - $toc:     (reference to array of) HTML::Toc object(s) to extend
             - $string:  string to retrieve ToC from
             - $options: hash reference containing generator options.

Extend ToC from specified string.  For generator options, see L<HTML::TocGenerator Options|"HTML::TocGenerator Options">

=head2 HTML::TocGenerator::extendFromFile()

    syntax:  $tocGenerator->extendFromFile($toc, $filename [, $options])
    args:    - $toc:      (reference to array of) HTML::Toc object(s) to extend
             - $filename: (reference to array of) file(s) to extend ToC from
             - $options:  hash reference containing generator options.

Extend ToC from specified file.  For generator options, see L<HTML::TocGenerator Options|"HTML::TocGenerator Options">.  For an example, see L<Extend an existing ToC>.

=head2 HTML::TocGenerator::generate()

    syntax:  $tocGenerator->generate($toc, $string [, $options])
    args:    - $toc:     (reference to array of) HTML::Toc object(s) to generate
             - $string:  string to retrieve ToC from
             - $options: hash reference containing generator options.

Generate ToC from specified string.  Before generating, the ToC will be cleared.  For extending an existing ToC, use the L<HTML::TocGenerator::extend()|"HTML::TocGenerator::extend()"> method.  For generator options, see L<HTML::TocGenerator Options|"HTML::TocGenerator Options">.

=head2 HTML::TocGenerator::generateFromFile()

    syntax:  $tocGenerator->generateFromFile($toc, $filename [, $options])
    args:    - $toc:      (reference to array of) HTML::Toc object(s) to 
                          generate
             - $filename: (reference to array of) file(s) to generate ToC from
             - $options:  hash reference containing generator options.

Generate ToC from specified file.  Before generating, the ToC will be cleared.  For extending an extisting ToC, use the L<HTML::TocGenerator::extendFromFile()|"HTML::TocGenerator::extendFromFile()"> method.  For generator options, see L<HTML::TocGenerator Options|"HTML::TocGenerator Options">.

=head2 HTML::TocInsertor::insert()

    syntax:  $tocInsertor->insert($toc, $string [, $options])
    args:    - $toc:     (reference to array of) HTML::Toc object(s) to insert
             - $string:  string to insert ToC in
             - $options: hash reference containing insertor options.

Insert ToC into specified string.  For insertor options, see L<HTML::TocInsertor Options|"HTML::TocInsertor Options">.

=head2 HTML::TocInsertor::insertIntoFile()

    syntax:  $tocInsertor->insertIntoFile($toc, $filename [, $options])
    args:    - $toc:      (reference to array of) HTML::Toc object(s) to insert
             - $filename: (reference to array of) file(s) to insert ToC in
             - $options:  hash reference containing insertor options.

Insert ToC into specified file.  For insertor options, see L<HTML::TocInsertor Options|"HTML::TocInsertor Options">.

=head2 HTML::TocUpdator::insert()

    syntax:  $tocUpdator->insert($toc, $string [, $options])
    args:    - $toc:     (reference to array of) HTML::Toc object(s) to insert
             - $string:  string to insert ToC in
             - $options: hash reference containing updator options.

Insert ToC into specified string.  Differs from L<HTML::TocInsertor::insert()|"HTML::TocInsertor::insert()"> in that inserted text will be surrounded with update tokens in order for C<HTML::TocUpdator> to be able to update this text the next time an update is issued.  For updator options, see L<HTML::TocUpdator Options|"HTML::TocUpdator Options">.

=head2 HTML::TocUpdator::insertIntoFile()

    syntax:  $tocUpdator->insertIntoFile($toc, $filename [, $options])
    args:    - $toc:      (reference to array of) HTML::Toc object(s) to insert
             - $filename: (reference to array of) file(s) to insert ToC in
             - $options:  hash reference containing updator options.

Insert ToC into specified file.  Differs from L<HTML::TocInsertor::insert()|"HTML::TocInsertor::insert()"> in that inserted text will be surrounded with update tokens in order for C<HTML::TocUpdator> to be able to update this text the next time an update is issued.  For updator options, see L<HTML::TocUpdator Options|"HTML::TocUpdator Options">.

=head2 HTML::TocUpdator::update()

    syntax:  $tocUpdator->update($toc, $string [, $options])
    args:    - $toc:     (reference to array of) HTML::Toc object(s) to insert
             - $string:  string to update ToC in
             - $options: hash reference containing updator options.

Update ToC within specified string.  For updator options, see L<HTML::TocUpdator Options|"HTML::TocUpdator Options">.

=head2 HTML::TocUpdator::updateFile()

    syntax:  $tocUpdator->updateFile($toc, $filename [, $options])
    args:    - $toc:      (reference to array of) HTML::Toc object(s) to insert
             - $filename: (reference to array of) file(s) to update ToC in
             - $options:  hash reference containing updator options.

Update ToC of specified file.  For updator options, see L<HTML::TocUpdator Options|"HTML::TocUpdator Options">.

=head1 Parser Options

When generating a ToC, additional options may be specified which influence the way the ToCs are generated using either C<TocGenerator>, C<TocInsertor> or C<TocUpdator>.  The options must be specified as a hash reference.  For example:

    $tocGenerator->generateFromFile($toc, $filename, {doUseGroupsGlobal => 1});

Available options are:

=over 4

=item L<doGenerateToc|"doGenerateToc">

=item L<doUseGroupsGlobal|"doUseGroupsGlobal">

=item L<output|"output">

=item L<outputFile|"outputFile">

=back

=head2 doGenerateToc

    syntax:         [0|1]
    default:        1
    applicable to:  TocInsertor, TocUpdator

True (1) if ToC must be generated.  False (0) if ToC must be inserted only.

=head2 doUseGroupsGlobal

    syntax:         [0|1]
    default:        0
    applicable to:  TocGenerator, TocInsertor, TocUpdator

True (1) if group levels must be used globally accross ToCs.  False (0) if not.  This option only makes sense when an array of ToCs is specified.  For example, suppose you want to generate two ToCs, one ToC for '<h1>' tokens and one ToC for '<h2>' tokens, of the file 'index.htm':

    <h1>Chapter</h1>
    <h2>Paragraph</h2>

Using the default setting of 'doUseGroupsGlobal' => 0:

    use HTML::Toc;
    use HTML::TocGenerator;

    my $toc1         = HTML::Toc->new();
    my $toc2         = HTML::Toc->new();
    my $tocGenerator = HTML::TocGenerator->new();

    $toc1->setOptions({
       'header'     => '',
       'footer'     => '',
       'tokenToToc' => [{'tokenBegin' => '<h1>'}]
    });
    $toc2->setOptions({
       'header'     => '',
       'footer'     => '',
       'tokenToToc' => [{'tokenBegin' => '<h2>'}]
    });
    $tocGenerator->generateFromFile([$toc1, $toc2], 'index.htm');
    print $toc1->format() . "\n\n" . $toc2->format();

the output will be:

    <ul>
       <li><a href=#h-1>Chapter</a>
    </ul>

    <ul>
       <li><a href=#h-1>Paragraph</a>
    </ul>

Each ToC will use its own numbering scheme.  Now if 'C<doUseGroupsGlobal = 1>' is specified:

    $tocGenerator->generateFromFile(
    	[$toc1, $toc2], 'index.htm', {'doUseGroupsGlobal' => 1}
    );

the output will be:

    <ul>
       <li><a href=#h-1>Chapter</a>
    </ul>

    <ul>
       <li><a href=#h-2>Paragraph</a>
    </ul>

using a global numbering scheme for all ToCs.

=head2 output

    syntax:         reference to scalar
    default:        none
    applicable to:  TocInsertor, TocUpdator

Reference to scalar where the output must be stored in.

=head2 outputFile

    syntax:         scalar
    default:        none
    applicable to:  TocInsertor, TocUpdator

Filename to write output to.  If no filename is specified, output will be written to standard output.

=head1 HTML::Toc Options

The C<HTML::Toc> options can be grouped in the following categories:

=over 4

=item L<Generate options|"Generate options">

=item L<Insert options|"Insert options">

=item L<Update options|"Update options">

=item L<Format options|"Format options">

=back

The ToC options must be specified using the 'setOptions' method.  For example:

    my $toc = new HTML::Toc;

    $toc->setOptions({
       'doNumberToken' => 1,
       'footer'        => '<!-- End Of ToC -->'
       'tokenToToc'    => [{
          'level'          => 1,
          'tokenBegin'     => '<h1>',
          'numberingStyle' => 'lower-alpha'
       }]
    });

=head2 Generate options

=over 4

=item Token groups

=over 4

=item L<tokenToToc|"tokenToToc">

=over 4

=item L<doNumberToken|"doNumberToken">

=item L<fileSpec|"fileSpec">

=item L<groupId|"groupId">

=item L<level|"level">

=item L<tokenBegin|"tokenBegin">

=item L<tokenEnd|"tokenEnd">

=item L<numberingStyle|"numberingStyle">

=back

=item L<groupToToc|"groupToToc">

=item L<levelToToc|"levelToToc">

=back

=item Numbering tokens

=over 4

=item L<doNumberToken|"doNumberToken">

=item L<numberingStyle|"numberingStyle">

=item L<templateTokenNumber|"templateTokenNumber">

=back

=item Miscellaneous

=over 4

=item L<attributeToExcludeToken|"attributeToExcludeToken">

=item L<attributeToTocToken|"attributeToTocToken">

=item L<groupToToc|"groupToToc">

=item L<levelToToc|"levelToToc">

=back

=item Linking ToC to tokens

=over 4

=item L<doLinkToToken|"doLinkToToken">

=item L<doLinkToFile|"doLinkToFile">

=item L<doLinkToId|"doLinkToId">

=item L<templateAnchorName|"templateAnchorName">

=item L<templateAnchorHrefBegin|"templateAnchorHrefBegin">

=item L<templateAnchorHrefEnd|"templateAnchorHrefEnd">

=item L<templateAnchorNameBegin|"templateAnchorNameBegin">

=item L<templateAnchorNameEnd|"templateAnchorNameEnd">

=back

=back

=head2 Insert options

=over 4

=item L<insertionPoint|"insertionPoint">

=back

=head2 Update options

=over 4

=item L<tokenUpdateBeginAnchorName|"tokenUpdateBeginAnchorName">

=item L<tokenUpdateEndAnchorName|"tokenUpdateEndAnchorName">

=item L<tokenUpdateBeginToc|"tokenUpdateBeginToc">

=item L<tokenUpdateEndToc|"tokenUpdateEndToc">

=item L<tokenUpdateBeginNumber|"tokenUpdateBeginNumber">

=item L<tokenUpdateEndNumber|"tokenUpdateEndNumber">

=back

=head2 Format options

=over 4

=item L<doSingleStepLevel|"doSingleStepLevel">

=item L<doNestGroup|"doNestGroup">

=item L<footer|"footer">

=item L<groupToToc|"groupToToc">

=item L<header|"header">

=item L<levelIndent|"levelIndent">

=item L<levelToToc|"levelToToc">

=item L<templateLevelBegin|"templateLevelBegin">

=item L<templateLevelEnd|"templateLevelEnd">

=back

=head1 HTML::Toc Options Reference

=head2 attributeToExcludeToken

    syntax:  $scalar
    default: '-'

Token which marks an attribute value in a L<tokenBegin|"tokenBegin"> or L<insertionPoint|"insertionPoint"> token as an attribute value a token should not have to be marked as a ToC token.  See also: L<Using attribute value as ToC entry|"Using attribute value as ToC text">.

=head2 attributeToTocToken

    syntax:  $scalar
    default: '@'

Token which marks an attribute in a L<tokenBegin|"tokenBegin"> token as an attribute which must be used as ToC text.  See also: L<Using attribute value as ToC entry|"Using attribute value as ToC text">.

=head2 doLinkToToken

    syntax:  [0|1]
    default: 1

True (1) if ToC must be linked to tokens, False (0) if not.  Note that 'HTML::TocInsertor' must be used to do the actual insertion of the anchor name within the source data.

=head2 doLinkToFile

    syntax:  [0|1]
    default: 0

True (1) if ToC must be linked to file, False (0) if not.  In effect only when L<doLinkToToken|"doLinkToToken"> equals True (1) and L<templateAnchorHrefBegin|"templateAnchorHrefBegin"> isn't specified.

=head2 doLinkToId

    syntax:  [0|1]
    default: 0

True (1) if ToC must be linked to tokens by using token ids.  False (0) if ToC must be linked to tokens by using anchor names.

=head2 doNestGroup

    syntax:  [0|1]
    default: 0

True (1) if groups must be nested in the formatted ToC, False (0) if not.  In effect only when multiple groups are specified within the L<tokenToToc|"tokenToToc"> setting.  For an example, see L<Generate multiple groups in one ToC|"Generate multiple groups in one ToC">.

=head2 doNumberToken

    syntax:  [0|1]
    default: 0

True (1) if tokens which are used for the ToC generation must be numbered.  This option may be specified both as a global ToC option or within a L<tokenToToc|"tokenToToc"> group.  When specified within a C<tokenToToc> option, the C<doNumberToken> applies to that group only.  For an example, see L<Specify an additional 'Part' group|"Specify an additional 'Part' group">.

=head2 doSingleStepLevel

    syntax:  [0|1]
    default: 1

True (1) if levels of a formatted ToC must advance one level at a time.  For example, when generating a ToC of a file with a missing '<h2>':

    <h1>Chapter</h1>
    <h3>Paragraph</h3>

By default, an empty indentation level will be inserted in the ToC:

    <!-- Table of Contents generated by Perl - HTML::Toc -->
    <ul>
       <li><a href=#h-1>Header 1</a>
       <ul>
          <ul>
             <li><a href=#h-1.0.1>Header 3</a>
          </ul>
       </ul>
    </ul>
    <!-- End of generated Table of Contents -->

After specifying:

    $toc->setOptions({'doSingleStepLevel' => 0});

the ToC will not have an indentation level inserted for level 2:

    <!-- Table of Contents generated by Perl - HTML::Toc -->
    <ul>
       <li><a href=#h-1>Header 1</a>
       <ul>
             <li><a href=#h-1.0.1>Header 3</a>
       </ul>
    </ul>
    <!-- End of generated Table of Contents -->

=head2 fileSpec

    syntax:  <regexp>
    default: undef

Specifies which files should match the current level.  Valid only if L<doLinkToFile|"doLinkToFile"> equals 1.  For an example, see L<Site map|"Site map">.

=head2 footer

    syntax:  $scalar
    default: "\n<!-- End of generated Table of Contents -->\n"

String to output at end of ToC.

=head2 groupId

    syntax:  $scalar
    default: 'h'

Sets the group id attribute of a tokenGroup.  With this attribute it's possible to divide the ToC into multiple groups.  Each group has its own numbering scheme.  For example, to generate a ToC of both normal headings and 'appendix' headings, specify the following ToC settings:

    $toc->setOptions({
       'tokenToToc' => [{
              'tokenBegin' => '<h1 class=-appendix>'
           }, {
              'groupId' => 'appendix',
              'tokenBegin' => '<h1 class=appendix>'
       }]
    });

=head2 groupToToc

    syntax:  <regexp>
    default: '.*'

Determines which groups to use for generating the ToC.  For example, to create a ToC for groups [a-b] only, specify:

    'groupToToc => '[a-b]'

This option is evaluated during both ToC generation and ToC formatting.  This enables you to generate a ToC of all groups, but - after generating - format only specified groups:

    $toc->setOptions({'groupToToc' => '.*'});
    $tocGenerator->generateToc($toc, ...);
        # Get ToC of all groups
    $fullToc = $toc->format();
        # Get ToC of 'appendix' group only
    $toc->setOptions({'groupToToc' => 'appendix'});
    $appendixToc = $toc->format();

=head2 header

    syntax:  $scalar
    default: "\n<!-- Table of Contents generated by Perl - HTML::Toc -->\n"

String to output at begin of ToC.


=head2 insertionPoint

    syntax:  [<before|after|replace>] <token>
    default: 'after <body>'
    token:   <[/]tag{ attribute=[-|@]<regexp>}> |
             <text regexp> |
             <declaration regexp> |
             <comment regexp>

Determines the point within the source, where the ToC should be inserted.  When specifying a start tag as the insertion point token, attributes to be included may be specified as well.  Note that the attribute value must be specified as a regular expression.  For example, to specify the C<<h1 class=header>> tag as insertion point:

    '<h1 class=^header$>'

Examples of valid 'insertionPoint' tokens are:

    '<h1>'
    '</h1>'
    '<!-- ToC -->'
    '<!ToC>'
    'ToC will be placed here'

It is also possible to specify attributes to exclude, by prefixing the value with an L<attributeToExcludeToken|"attributeToExcludeToken">, default a minus sign (-).  For example, to specify the C<<h1>> tag as insertion point, excluding all C<<h1 class=header>> tags:

    '<h1 class=-^header$>'

See also L<tokenBegin|"tokenBegin">.

=head2 level

    syntax:  number
    default: 1

Number which identifies at which level the tokengroup should be incorporated into the ToC.  See also: L<tokenToToc|"tokenToToc">.

=head2 levelIndent

    syntax:  number
    default: 3

Sets the number of spaces each level will be indented, when formatting the ToC.

=head2 levelToToc

    syntax:  <regexp>
    default: '.*'

Determines which group levels to use for generating the ToC.  For example, to create a ToC for levels 1-2 only, specify:

    'levelToToc => '[1-2]'

This option is evaluated during both ToC generation and ToC formatting.  This enables you to generate a ToC of all levels, but - after generating - retrieve only specified levels:

    $toc->setOptions({'levelToToc' => '.*'});
    $tocGenerator->generateToc($toc, ...);
        # Get ToC of all levels
    $fullToc = $toc->getToc();
        # Get ToC of level 1 only
    $toc->setOptions({'levelToToc' => '1'});
    $level1Toc = $toc->getToc();

=head2 numberingStyle

    syntax:  [decimal|lower-alpha|upper-alpha|lower-roman|upper-roman]}
    default: decimal

Determines which numbering style to use for a token group when L<doLinkToToken|"doLinkToToken"> is set to True (1).  When specified as a main ToC option, the setting will be the default for all groups.  When specified within a tokengroup, this setting will override any default for that particular tokengroup, e.g.:

    $toc->setOptions({
       'doNumberToken' => 1,
       'tokenToToc' => [{
          'level'          => 1,
          'tokenBegin'     => '<h1>',
          'numberingStyle' => 'lower-alpha'
       }]
    });

If C<roman> style is specified, be sure to have the Roman module installed, available from L<http://www.perl.com/CPAN/modules/by-module/Roman>.

=head2 templateAnchorName

    syntax:  <expression|function reference>
    default: '$groupId."-".$node'

Anchor name to use when L<doLinkToToken|"doLinkToToken"> is set to True (1).  The anchor name is passed to both L<templateAnchorHrefBegin|"templateAnchorHrefBegin"> and L<templateAnchorNameBegin|"templateAnchorNameBegin">.  The template may be specified as either an expression or a function reference.  The expression may contain the following variables:

    $file
    $groupId
    $level
    $node

If C<templateAnchorHrefBegin> is a function reference to a function returning the anchor, like in:

    $toc->setOptions({'templateAnchorName' => \&assembleAnchorName});

the function will be called with the following arguments:

    $anchorName = assembleAnchorName($file, $groupId, $level, $node);

=head2 templateAnchorHrefBegin

    syntax:  <expression|function reference>
    default: '"<a href=#$anchorName>"' or
             '"<a href=$file#$anchorName>"',
             depending on 'doLinkToFile' being 0 or 1 respectively.

Anchor reference begin token to use when L<doLinkToToken|"doLinkToToken"> is set to True (1).  The template may be specified as either an expression or a function reference.  The expression may contain the following variables:

    $file
    $groupId
    $level
    $node
    $anchorName

If C<templateAnchorHrefBegin> is a function reference to a function returning the anchor, like in:

    $toc->setOptions({'templateAnchorHrefBegin' => \&assembleAnchorHrefBegin});

the function will be called with the following arguments:

    $anchorHrefBegin = &assembleAnchorHrefBegin(
       $file, $groupId, $level, $node, $anchorName
    );

See also: L<templateAnchorName|"templateAnchorName">, L<templateAnchorHrefEnd|"templateAnchorHrefEnd">.

=head2 templateAnchorHrefEnd

    syntax:  <expression|function reference>
    default: '"</a>"'

Anchor reference end token to use when L<doLinkToToken|"doLinkToToken"> is set to True (1).  The template may be specified as either an expression or a function reference.  If L<templateAnchorHrefEnd|"templateAnchorHrefEnd"> is a function reference to a function returning the anchor end, like in:

    $toc->setOptions({'templateAnchorHrefEnd' => \&assembleAnchorHrefEnd});

the function will be called without arguments:

    $anchorHrefEnd = &assembleAnchorHrefEnd;

See also: L<templateAnchorHrefBegin|"templateAnchorHrefBegin">.

=head2 templateAnchorNameBegin

    syntax:  <expression|function reference>
    default: '"<a name=$anchorName>"'

Anchor name begin token to use when L<doLinkToToken|"doLinkToToken"> is set to True (1).  The template may be specified as either an expression or a function reference.  The expression may contain the following variables:

    $file
    $groupId
    $level
    $node
    $anchorName

If C<templateAnchorNameBegin> is a function reference to a function returning the anchor name, like in:

    $toc->setOptions({'templateAnchorNameBegin' => \&assembleAnchorNameBegin});

the function will be called with the following arguments:

    $anchorNameBegin = assembleAnchorNameBegin(
        $file, $groupId, $level, $node, $anchorName
    );

See also: L<templateAnchorName|"templateAnchorName">, L<templateAnchorNameEnd|"templateAnchorNameEnd">.

=head2 templateAnchorNameEnd

    syntax:  <expression|function reference>
    default: '"</a>"'

Anchor name end token to use when L<doLinkToToken|"doLinkToToken"> is set to True (1).  The template may be specified as either an expression or a function reference.  If L<templateAnchorNameEnd|"templateAnchorNameEnd"> is a function reference to a function returning the anchor end, like in:

    $toc->setOptions({'templateAnchorNameEnd' => \&assembleAnchorNameEnd});

the function will be called without arguments:

    $anchorNameEnd = &assembleAnchorNameEnd;

See also: L<templateAnchorNameBegin|"templateAnchorNameBegin">.

=head2 templateLevel

    syntax:  <expression|function reference>
    default: '"<li>$text\n"'

Expression to use when formatting a ToC node.  The template may be specified as either an expression or a function reference.  The expression may contain the following variables:

    $level
    $groupId
    $node
    $sequenceNr
    $text

If C<templateLevel> is a function reference to a function returning the ToC node, like in:

    $toc->setOptions({'templateLevel' => \&AssembleTocNode});

the function will be called with the following arguments:

    $tocNode = &AssembleTocNode(
        $level, $groupId, $node, $sequenceNr, $text
    );

=head2 templateLevelBegin

    syntax:  <expression>
    default: '"<ul>\n"'

Expression to use when formatting begin of ToC level.  See L<templateLevel|"templateLevel"> for list of available variables to use within the expression.  For example, to give each ToC level a class name to use with Cascading Style Sheets (CSS), use the expression:

    '"<ul class=toc_$groupId$level>\n"'

which will result in each ToC group being given a class name:

    <ul class=toc_h1>
       <li>Header
    </ul>

For an example, see L<Using CSS for ToC formatting|"Using CSS for ToC formatting">.

=head2 templateLevelEnd

    syntax:  <expression>
    default: '"<ul>\n"'

Expression to use when formatting end of ToC level.  See L<templateLevel|"templateLevel"> for a list of available variables to use within the expression.  The default expression is:

    '"</ul>\n"'

For an example, see L<Using CSS for ToC formatting|"Using CSS for ToC formatting">.

=head2 templateTokenNumber

    syntax:  <expression|function reference>
    default: '"$node &nbsp;"'

Token number to use when L<doNumberToken|"doNumberToken"> equals True (1).  The template may be specified as either an expression or a function reference.  The expression has access to the following variables:

    $file
    $groupId
    $groupLevel
    $level
    $node
    $toc

If C<templateTokenNumber> is a function reference to a function returning the token number, like in:

    $toc->setOptions({'templateTokenNumber' => \&assembleTokenNumber});

the function will be called with the following arguments:

    $number = &assembleTokenNumber(
        $node, $groupId, $file, $groupLevel, $level, $toc
    );

=head2 tokenBegin

    syntax:  <token>
    default: '<h1>'
    token:   <[/]tag{ attribute=[-|@]<regexp>}> |
             <text regexp> |
             <declaration regexp> |
             <comment regexp>

This scalar defines the token that will trigger text to be put into the ToC.  Any start tag, end tag, comment, declaration or text string can be specified.  Examples of valid 'tokenBegin' tokens are:

    '<h1>'
    '</end>'
    '<!-- Start ToC entry -->'
    '<!Start ToC entry>'
    'ToC entry'

When specifying a start tag, attributes to be included may be specified as well.  Note that the attribute value is used as a regular expression.  For example, to specify the C<<h1 class=header>> tag as tokenBegin:

    '<h1 class=^header$>'

It is also possible to specify attributes to exclude, by prefixing the value with an L<attributeToExcludeToken|"attributeToExcludeToken">, default a minus sign (-).  For example, to specify the C<<h1>> tag as tokenBegin, excluding all C<<h1 class=header>> tags:

    '<h1 class=-^header$>'

Also, you can specify here an attribute value which has to be used as ToC text, by prefixing the value with an L<attributeToTocToken|"">, default an at sign (@).  For example, to use the class value as ToC text:

    '<h1 class=@>'

See L<Generate multiple ToCs|"Generate multiple ToCs"> for an elaborated example using the C<attributeToTocToken> to generate a ToC of image C<alt> attribute values.

See also: L<tokenEnd|"tokenEnd">, L<tokenToToc|"tokenToToc">.

=head2 tokenEnd

    syntax:  $scalar
    default: empty string ('') or end tag counterpart of 'tokenBegin' if 
             'tokenBegin' is a start tag

The 'tokenEnd' definition applies to the same rules as L<tokenBegin|"tokenBegin">.

See also: L<tokenBegin|"tokenBegin">, L<tokenToToc|"tokenToToc">.

=head2 tokenToToc

    syntax:  [{array of hashrefs}]
    default: [{
                'level'      => 1,
                'tokenBegin' => '<h1>'
             }, {
                'level'      => 2,
                'tokenBegin' => '<h2>'
             }, {
                'level'      => 3,
                'tokenBegin' => '<h3>'
             }, {
                'level'      => 4,
                'tokenBegin' => '<h4>'
             }, {
                'level'      => 5,
                'tokenBegin' => '<h5>'
             }, {
                'level'      => 6,
                'tokenBegin' => '<h6>'
             }]

This hash define the tokens that must act as ToC entries.  Each tokengroup may contain a L<groupId|"groupId">, L<level|"level">, L<numberingStyle|"numberingStyle">, L<tokenBegin|"tokenBegin"> and L<tokenEnd|"tokenEnd"> identifier.

=head2 tokenUpdateBeginAnchorName

    syntax:  <string>
    default: '<!-- #BeginTocAnchorNameBegin -->';

This token marks the begin of an anchor name, inserted by C<HTML::TocInsertor>.  This option is used by C<HTML::TocUpdator>.

=head2 tokenUpdateEndAnchorName

    syntax:  <string>
    default: '<!-- #EndTocAnchorName -->';

This option is used by C<HTML::TocUpdator>, to mark the end of an inserted anchor name.

=head2 tokenUpdateBeginNumber

    syntax:  <string>
    default: '<!-- #BeginTocNumber -->';

This option is used by C<HTML::TocUpdator>, to mark the begin of an inserted number.

=head2 tokenUpdateEndNumber

    syntax:  <string>
    default: '<!-- #EndTocAnchorName -->';

This option is used by C<HTML::TocUpdator>, to mark the end of an inserted number.

=head2 tokenUpdateBeginToc

    syntax:  <string>
    default: '<!-- #BeginToc -->';

This option is used by C<HTML::TocUpdator>, to mark the begin of an inserted ToC.

=head2 tokenUpdateEndToc

    syntax:  <string>
    default: '<!-- #EndToc -->';

This option is used by C<HTML::TocUpdator>, to mark the end of an inserted ToC.

=head1 Known issues

=head2 Cygwin

In order for the test files to run on Cygwin without errors, the 'UNIX' default text file type has to be selected during the Cygwin setup.
When extracting the tar.gz file with WinZip the 'TAR file smart CR/LF conversion' has to be turned off via {Options|Configuration...|Miscellaneous} in order for the files 'toc.pod' and './manualTest/manualTest1.htm' to be left in UNIX format.

=head2 Nested anchors

HTML::Toc can only link to existing anchors if these anchors are placed outside of the ToC tokens.  Otherwise a warning will be given.  For example, generating a L<linked|"doLinkToToken"> ToC of C<E<lt>h1E<gt>> tokens of the following text:

    <a name=foo><h1>Header</h1></a>

will go all right, whereas:

    <h1><a name=foo>Header</a></h1>

will yield the warning:

    warning (1): Nested anchor '<a name=foo>' within anchor '<a name=h-1>'.

since anchor names aren't allowed to be nested according to the HTML 4.01 specification.

=head1 AUTHOR

Freddy Vulto E<lt>L<"fvu@fvu.myweb.nl">E<gt>

=head1 COPYRIGHT

Copyright (c) 2001 Freddy Vulto.  All rights reserved.

This library is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.

=cut