examples/includes/HTML-Toc-0.91/Toc.pod

   1 =head1 NAME
   2
   3 HTML::Toc - Generate, insert and update HTML Table of Contents.
   4
   5 =head1 DESCRIPTION
   6
   7 Generate, insert and update HTML Table of Contents.
   8
   9 =head1 Introduction
  10
  11 The HTML::Toc consists out of the following packages:
  12
  13     HTML::Toc
  14     HTML::TocGenerator
  15     HTML::TocInsertor
  16     HTML::TocUpdator
  17
  18 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.
  19
  20 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:
  21
  22     +---------------------+
  23     |    HTML::Parser     |
  24     +---------------------+
  25     +---------------------+
  26     |    +parse()         |
  27     |    +parse_file()    |
  28     +----------+----------+
  29               /_\
  30                |
  31     +----------+----------+  <<uses>>  +-----------+
  32     | HTML::TocGenerator  + - - - - - -+ HTML::Toc |
  33     +---------------------+            +-----------+
  34     +---------------------+            +-----------+
  35     | +extend()           |            | +clear()  |
  36     | +extendFromFile()   |            | +format() |
  37     | +generate()         |            +-----+-----+
  38     | +generateFromFile() |                  :
  39     +----------+----------+                  :
  40               /_\                            :
  41                |                             :
  42     +----------+----------+     <<uses>>     :
  43     |  HTML::TocInsertor  + - - - - - - - - -+
  44     +---------------------+                  :
  45     +---------------------+                  :
  46     |  +insert()          |                  :
  47     |  +insertIntoFile()  |                  :
  48     +----------+----------+                  :
  49               /_\                            :
  50                |                             :
  51     +----------+----------+     <<uses>>     :
  52     |  HTML::TocUpdator   + - - - - - - - - -+
  53     +---------------------+
  54     +---------------------+
  55     |  +insert()          |
  56     |  +insertIntoFile()  |
  57     |  +update()          |
  58     |  +updateFile()      |
  59     +---------------------+
  60
  61 When generating a ToC you'll have to decide which object you want to use:
  62
  63     TocGenerator:
  64         for generating a ToC without inserting the ToC into the source
  65     TocInsertor:
  66         for generating a ToC and inserting the ToC into the source
  67     TocUpdator:
  68         for generating and inserting a ToC, removing any previously
  69         inserted ToC elements
  70
  71 Thus in tabular view, each object is capable of:
  72
  73                    generating   inserting   updating
  74                    ---------------------------------
  75     TocGenerator        X
  76     TocInsertor         X           X
  77     TocUpdator          X           X           X
  78
  79 =head2 Generating
  80
  81 The code underneath will generate a ToC of the HTML headings C<<h1>>..C<<h6>> from a file C<index.htm>:
  82
  83     use HTML::Toc;
  84     use HTML::TocGenerator;
  85
  86     my $toc          = HTML::Toc->new();
  87     my $tocGenerator = HTML::TocGenerator->new();
  88
  89     $tocGenerator->generateFromFile($toc, 'index.htm');
  90     print $toc->format();
  91
  92 For example, with C<index.htm> containing:
  93
  94     <html>
  95     <body>
  96        <h1>Chapter</h1>
  97     </body>
  98     </html>
  99
 100 the output will be:
 101
 102
 103     <!-- Table of Contents generated by Perl - HTML::Toc -->
 104     <ul>
 105        <li><a href=#h-1>Chapter</a>
 106     </ul>
 107     <!-- End of generated Table of Contents -->
 108
 109 =head2 Inserting
 110
 111 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:
 112
 113     use HTML::Toc;
 114     use HTML::TocInsertor;
 115
 116     my $toc         = HTML::Toc->new();
 117     my $tocInsertor = HTML::TocInsertor->new();
 118
 119     $tocInsertor->insertIntoFile($toc, 'index.htm');
 120
 121 For example, with C<index.htm> containing:
 122
 123     <html>
 124     <body>
 125        <h1>Chapter</h1>
 126     </body>
 127     </html>
 128
 129 the output will be:
 130
 131     <html>
 132     <body>
 133     <!-- Table of Contents generated by Perl - HTML::Toc -->
 134     <ul>
 135        <li><a href=#h-1>Chapter</a>
 136     </ul>
 137     <!-- End of generated Table of Contents -->
 138
 139        <a name=h-1><h1>Chapter</h1></a>
 140     </body>
 141     </html>
 142
 143 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>:
 144
 145     use HTML::Toc;
 146     use HTML::TocUpdator;
 147
 148     my $toc        = HTML::Toc->new();
 149     my $tocUpdator = HTML::TocUpdator->new();
 150
 151     $tocUpdator->insertIntoFile($toc, 'index.htm');
 152
 153 When applying the code above on 'index.htm':
 154
 155     <html>
 156     <body>
 157        <h1>
 158        Chapter
 159        </h1>
 160     </body>
 161     </html>
 162
 163 the output will contain additional update tokens:
 164
 165     <!-- #BeginToc -->
 166     <!-- #EndToc -->
 167     <!-- #BeginTocAnchorNameBegin -->
 168     <!-- #EndTocAnchorNameBegin -->
 169     <!-- #BeginTocAnchorNameEnd -->
 170     <!-- #EndTocAnchorNameEnd -->
 171
 172 around the inserted ToC elements:
 173
 174     <html>
 175     <body><!-- #BeginToc-->
 176     <!-- Table of Contents generated by Perl - HTML::Toc -->
 177     <ul>
 178        <li><a href=#h-1> Chapter </a>
 179     </ul>
 180     <!-- End of generated Table of Contents -->
 181     <!-- #EndToc -->
 182        <!-- #BeginTocAnchorNameBegin --><a name=h-1><!-- #EndTocAnchorNameBegin --><h1>
 183        Chapter
 184        </h1><!-- #BeginTocAnchorNameEnd --></a><!-- #EndTocAnchorNameEnd -->
 185     </body>
 186     </html>
 187
 188 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.
 189
 190 =head2 Updating
 191
 192 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:
 193
 194     use HTML::Toc;
 195     use HTML::TocUpdator;
 196
 197     my $toc        = HTML::Toc->new();
 198     my $tocUpdator = HTML::TocUpdator->new();
 199
 200     $tocUpdator->updateFile($toc, 'indexToc.htm');
 201
 202 For example, with C<indexToc.htm> containing:
 203
 204     <html>
 205     <body><!-- #BeginToc -->
 206     foo
 207     <!-- #EndToc -->
 208        <!-- #BeginTocAnchorNameBegin -->bar<!-- #EndTocAnchorNameBegin --><h1>
 209        Chapter
 210        </h1><!-- #BeginTocAnchorNameEnd -->foo<!-- #EndTocAnchorNameEnd -->
 211     </body>h
 212     </html>
 213
 214 the output will be:
 215
 216     <html>
 217     <body><!-- #BeginToc -->
 218     <!-- Table of Contents generated by Perl - HTML::Toc -->
 219     <ul>
 220        <li><a href=#h-1> Chapter </a>
 221     </ul>
 222     <!-- End of generated Table of Contents -->
 223     <!-- #EndToc -->
 224        <!-- #BeginTocAnchorNameBegin --><a name=h-1><!-- #EndTocAnchorNameBegin --><h1>
 225        Chapter
 226        </h1><!-- #BeginTocAnchorNameEnd --></a><!-- #EndTocAnchorNameEnd -->
 227     </body>
 228     </html>
 229
 230 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()>.
 231
 232 =head2 Formatting
 233
 234 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">'.
 235
 236 =head1 Advanced
 237
 238 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:
 239
 240     preface
 241     introduction
 242     table of contents
 243     table of figures
 244     table of tables
 245     parts
 246     chapters
 247     appendixes
 248     bibliography
 249
 250 is formatted.
 251
 252 =head2 Using attribute value as ToC text
 253
 254 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:
 255
 256     <body>
 257        <img src=test1.gif alt="First picture">
 258        <img src=test2.gif alt="Second picture">
 259     </body>
 260
 261 This would be the code:
 262
 263     use HTML::Toc;
 264     use HTML::TocInsertor;
 265
 266     my $toc         = HTML::Toc->new();
 267     my $tocInsertor = HTML::TocInsertor->new();
 268
 269     $toc->setOptions({
 270        'tokenToToc'   => [{
 271           'groupId'    => 'image',
 272           'tokenBegin' => '<img alt=@>'
 273        }],
 274     });
 275     $tocInsertor->insertIntoFile($toc, $filename);
 276
 277 and the output will be:
 278
 279     <body>
 280     <!-- Table of Contents generated by Perl - HTML::Toc -->
 281     <ul>
 282        <li><a href=#image-1>First picture</a>
 283        <li><a href=#image-2>Second picture</a>
 284     </ul>
 285     <!-- End of generated Table of Contents -->
 286
 287        <a name=image-1><img src=test1.gif alt="First picture"></a>
 288        <a name=image-2><img src=test2.gif alt="Second picture"></a>
 289     </body>
 290
 291 =head2 Generate single ToC of multiple files
 292
 293 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.
 294
 295 =head3 Specify an array of files
 296
 297 For example, suppose you want to generate a ToC of both C<doc1.htm>:
 298
 299     <body>
 300        <h1>Chapter of document 1</h1>
 301     </body>
 302
 303 and C<doc2.htm>:
 304
 305     <body>
 306        <h1>Chapter of document 2</h1>
 307     </body>
 308
 309 Here's the code to do so by specifying an array of files:
 310
 311     use HTML::Toc;
 312     use HTML::TocGenerator;
 313
 314     my $toc          = HTML::Toc->new();
 315     my $tocGenerator = HTML::TocGenerator->new();
 316
 317     $toc->setOptions({'doLinkToFile' => 1});
 318     $tocGenerator->generateFromFile($toc, ['doc1.htm', 'doc2.htm']);
 319     print $toc->format();
 320
 321 And the output will be:
 322
 323
 324     <!-- Table of Contents generated by Perl - HTML::Toc -->
 325     <ul>
 326        <li><a href=doc1.htm#h-1>Chapter of document 1</a>
 327        <li><a href=doc2.htm#h-2>Chapter of document 2</a>
 328     </ul>
 329     <!-- End of generated Table of Contents -->
 330
 331 =head3 Extend an existing ToC
 332
 333 It's also possible to extend an existing ToC.  For example, suppose we want the generate a ToC of file C<doc1.htm>:
 334
 335     <body>
 336        <h1>Chapter of document 1</h1>
 337     </body>
 338
 339 and extend this ToC with text from C<doc2.htm>:
 340
 341     <body>
 342        <h1>Chapter of document 2</h1>
 343     </body>
 344
 345 Here's the code to do so:
 346
 347     use HTML::Toc;
 348     use HTML::TocGenerator;
 349
 350     my $toc          = HTML::Toc->new();
 351     my $tocGenerator = HTML::TocGenerator->new();
 352
 353     $toc->setOptions({'doLinkToFile' => 1});
 354     $tocGenerator->generateFromFile($toc, 'doc1.htm');
 355     $tocGenerator->extendFromFile($toc, 'doc2.htm');
 356     print $toc->format();
 357
 358 And the output will be:
 359
 360
 361     <!-- Table of Contents generated by Perl - HTML::Toc -->
 362     <ul>
 363        <li><a href=doc1.htm#h-1>Chapter of document 1</a>
 364        <li><a href=doc2.htm#h-2>Chapter of document 2</a>
 365     </ul>
 366     <!-- End of generated Table of Contents -->
 367
 368 =head2 Generate multiple ToCs
 369
 370 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:
 371
 372     <body>
 373        <h1>Header One</h1>
 374        <img src=test1.gif alt="First picture" id=image_001>
 375        <h2>Paragraph One</h2>
 376        <img src=test2.gif alt="Second picture" id=image_002>
 377     </body>
 378
 379 Here's how you would do so:
 380
 381     use HTML::Toc;
 382     use HTML::TocInsertor;
 383
 384     my $toc1        = HTML::Toc->new();
 385     my $toc2        = HTML::Toc->new();
 386     my $tocInsertor = HTML::TocInsertor->new();
 387
 388     $toc2->setOptions({
 389        'tokenToToc'   => [{
 390           'groupId'    => 'image',
 391           'tokenBegin' => '<img alt=@>'
 392        }],
 393     });
 394     $tocInsertor->insertIntoFile([$toc1, $toc2], $filename);
 395
 396 And the output will be:
 397
 398     <body>
 399     <!-- Table of Contents generated by Perl - HTML::Toc -->
 400     <ul>
 401        <li><a href=#h-1>Header One</a>
 402        <ul>
 403           <li><a href=#h-1.1>Paragraph One</a>
 404        </ul>
 405     </ul>
 406     <!-- End of generated Table of Contents -->
 407
 408     <!-- Table of Contents generated by Perl - HTML::Toc -->
 409     <ul>
 410        <li><a href=#image-1>First picture</a>
 411        <li><a href=#image-2>Second picture</a>
 412     </ul>
 413     <!-- End of generated Table of Contents -->
 414
 415        <a name=h-1><h1>Header One</h1></a>
 416        <a name=image-1><img src=test1.gif alt="First picture"></a>
 417        <a name=h-1.1><h2>Paragraph One</h2></a>
 418        <a name=image-2><img src=test2.gif alt="Second picture"></a>
 419     </body>
 420
 421 =head2 Generate multiple groups in one ToC
 422
 423 You may want to generate a ToC consisting of multiple ToC groups.
 424
 425 =head3 Specify an additional 'Appendix' group
 426
 427 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:
 428
 429     <body>
 430        <h1>Chapter</h1>
 431        <h2>Paragraph</h2>
 432        <h3>Subparagraph</h3>
 433        <h1>Chapter</h1>
 434        <h1 class=appendix>Appendix Chapter</h1>
 435        <h2 class=appendix>Appendix Paragraph</h2>
 436     </body>
 437
 438 With the code underneath:
 439
 440     use HTML::Toc;
 441     use HTML::TocInsertor;
 442
 443     my $toc         = HTML::Toc->new();
 444     my $tocInsertor = HTML::TocInsertor->new();
 445
 446     $toc->setOptions({
 447        'tokenToToc' => [{
 448              'tokenBegin' => '<h1 class=-appendix>'
 449           }, {
 450              'tokenBegin' => '<h2 class=-appendix>',
 451              'level'      => 2
 452           }, {
 453              'groupId'    => 'appendix',
 454              'tokenBegin' => '<h1 class=appendix>',
 455           }, {
 456              'groupId'    => 'appendix',
 457              'tokenBegin' => '<h2 class=appendix>',
 458              'level'      => 2
 459           }]
 460     });
 461     $tocInsertor->insertIntoFile($toc, $filename);
 462
 463 the output will be:
 464
 465     <body>
 466     <!-- Table of Contents generated by Perl - HTML::Toc -->
 467     <ul>
 468        <li><a href=#h-1>Chapter</a>
 469        <ul>
 470           <li><a href=#h-1.1>Paragraph</a>
 471        </ul>
 472        <li><a href=#h-2>Chapter</a>
 473     </ul>
 474     <ul>
 475        <li><a href=#appendix-1>Appendix Chapter</a>
 476        <ul>
 477           <li><a href=#appendix-1.1>Appendix Paragraph</a>
 478        </ul>
 479     </ul>
 480     <!-- End of generated Table of Contents -->
 481
 482        <a name=h-1><h1>Chapter</h1></a>
 483        <a name=h-1.1><h2>Paragraph</h2></a>
 484        <h3>Subparagraph</h3>
 485        <a name=h-2><h1>Chapter</h1></a>
 486        <a name=appendix-1><h1 class=appendix>Appendix Chapter</h1></a>
 487        <a name=appendix-1.1><h2 class=appendix>Appendix Paragraph</h2></a>
 488     </body>
 489
 490 =head3 Specify an additional 'Part' group
 491
 492 Suppose you want to generate a ToC of a document which is divided in multiple parts like this file underneath:
 493
 494     <body>
 495        <h1 class=part>First Part</h1>
 496        <h1>Chapter</h1>
 497        <h2>Paragraph</h2>
 498        <h1 class=part>Second Part</h1>
 499        <h1>Chapter</h1>
 500        <h2>Paragraph</h2>
 501     </body>
 502
 503 With the code underneath:
 504
 505     use HTML::Toc;
 506     use HTML::TocInsertor;
 507
 508     my $toc         = HTML::Toc->new();
 509     my $tocInsertor = HTML::TocInsertor->new();
 510
 511     $toc->setOptions({
 512        'doNumberToken'    => 1,
 513        'tokenToToc' => [{
 514              'tokenBegin' => '<h1 class=-part>'
 515           }, {
 516              'tokenBegin' => '<h2 class=-part>',
 517              'level'      => 2,
 518           }, {
 519              'groupId'        => 'part',
 520              'tokenBegin'     => '<h1 class=part>',
 521              'level'          => 1,
 522              'numberingStyle' => 'upper-alpha'
 523           }]
 524     });
 525     $tocInsertor->insertIntoFile($toc, $filename);
 526
 527 the output will be:
 528
 529     <body>
 530     <!-- Table of Contents generated by Perl - HTML::Toc -->
 531     <ul>
 532        <li><a href=#part-A>First Part</a>
 533     </ul>
 534     <ul>
 535        <li><a href=#h-1>Chapter</a>
 536        <ul>
 537           <li><a href=#h-1.1>Paragraph</a>
 538        </ul>
 539     </ul>
 540     <ul>
 541        <li><a href=#part-B>Second Part</a>
 542     </ul>
 543     <ul>
 544        <li><a href=#h-2>Chapter</a>
 545        <ul>
 546           <li><a href=#h-2.1>Paragraph</a>
 547        </ul>
 548     </ul>
 549     <!-- End of generated Table of Contents -->
 550
 551        <a name=part-A><h1 class=part>A &nbsp;First Part</h1></a>
 552        <a name=h-1><h1>1 &nbsp;Chapter</h1></a>
 553        <a name=h-1.1><h2>1.1 &nbsp;Paragraph</h2></a>
 554        <a name=part-B><h1 class=part>B &nbsp;Second Part</h1></a>
 555        <a name=h-2><h1>2 &nbsp;Chapter</h1></a>
 556        <a name=h-2.1><h2>2.1 &nbsp;Paragraph</h2></a>
 557     </body>
 558
 559 =head2 Number ToC entries
 560
 561 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.
 562
 563 =head3 Specify numbered list
 564
 565 By modifying L<templateLevelBegin|"templateLevelBegin"> and L<templateLevelEnd|"templateLevelEnd"> you can specify a numbered ToC:
 566
 567     use HTML::Toc;
 568     use HTML::TocGenerator;
 569
 570     my $toc          = HTML::Toc->new();
 571     my $tocGenerator = HTML::TocGenerator->new();
 572
 573     $toc->setOptions({
 574         'templateLevelBegin' => '"<ol>\n"',
 575         'templateLevelEnd'   => '"</ol>\n"',
 576     });
 577     $tocGenerator->generateFromFile($toc, 'index.htm');
 578     print $toc->format();
 579
 580 For instance with the original file containing:
 581
 582     <body>
 583         <h1>Chapter</h1>
 584         <h2>Paragraph</h2>
 585     </body>
 586
 587 The formatted ToC now will contain C<ol> instead of C<ul> tags:
 588
 589     <!-- Table of Contents generated by Perl - HTML::Toc -->
 590     <ol>
 591        <li><a href=#h-1>Chapter</a>
 592        <ol>
 593           <li><a href=#h-1.1>Paragraph</a>
 594        </ol>
 595     </ol>
 596     <!-- End of generated Table of Contents -->
 597
 598 See also: L<Using CSS for ToC formatting|"Using CSS for ToC formatting">.
 599
 600 =head3 Use generated numbers
 601
 602 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">:
 603
 604     use HTML::Toc;
 605     use HTML::TocGenerator;
 606
 607     my $toc          = HTML::Toc->new();
 608     my $tocGenerator = HTML::TocGenerator->new();
 609
 610     $toc->setOptions({
 611                 'templateLevel' => '"<li>$node &nbsp;$text\n"',
 612     });
 613     $tocGenerator->generateFromFile($toc, 'index.htm');
 614     print $toc->format();
 615
 616 For instance with the original file containing:
 617
 618     <body>
 619         <h1>Chapter</h1>
 620         <h2>Paragraph</h2>
 621     </body>
 622
 623 The formatted ToC now will have the node numbers hard-coded:
 624
 625     <!-- Table of Contents generated by Perl - HTML::Toc -->
 626     <ul>
 627        <li>1 &nbsp;<a href=#h-1>Chapter</a>
 628        <ul>
 629           <li>1.1 &nbsp;<a href=#h-1.1>Paragraph</a>
 630        </ul>
 631     </ul>
 632     <!-- End of generated Table of Contents -->
 633
 634 See also: L<Using CSS for ToC formatting|"Using CSS for ToC formatting">.
 635
 636 =head2 Using CSS for ToC formatting
 637
 638 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:
 639
 640     <html>
 641     <head>
 642        <style type="text/css">
 643           ol.toc_appendix1 { list-style-type: upper-alpha }
 644        </style>
 645     </head>
 646     <body>
 647        <h1 class=appendix>Appendix</h1>
 648        <h2 class=appendix>Appendix Paragraph</h2>
 649        <h1 class=appendix>Appendix</h1>
 650        <h2 class=appendix>Appendix Paragraph</h2>
 651     </body>
 652     </html>
 653
 654 Here's the code:
 655
 656     my $toc          = new HTML::Toc;
 657     my $tocInsertor  = new HTML::TocInsertor;
 658
 659     $toc->setOptions({
 660        'templateLevelBegin'   => '"<ol class=toc_$groupId$level>\n"',
 661        'templateLevelEnd'     => '"</ol>\n"',
 662        'doNumberToken'        => 1,
 663        'tokenToToc' => [{
 664              'groupId'        => 'appendix',
 665              'tokenBegin'     => '<h1>',
 666              'numberingStyle' => 'upper-alpha'
 667           }, {
 668              'groupId'        => 'appendix',
 669              'tokenBegin'     => '<h2>',
 670              'level'          => 2,
 671          }]
 672     });
 673     $tocInsertor->insertIntoFile($toc, $filename);
 674
 675 Which whill result in the following output:
 676
 677     <html>
 678     <head>
 679        <style type="text/css">
 680           ol.toc_appendix1 { list-style-type: upper-alpha }
 681        </style>
 682     </head>
 683     <body>
 684     <!-- Table of Contents generated by Perl - HTML::Toc -->
 685     <ol class=toc_appendix1>
 686        <li><a href=#appendix-A>Appendix</a>
 687        <ol class=toc_appendix2>
 688           <li><a href=#appendix-A.1>Appendix Paragraph</a>
 689        </ol>
 690        <li><a href=#appendix-B>Appendix</a>
 691        <ol class=toc_appendix2>
 692           <li><a href=#appendix-B.1>Appendix Paragraph</a>
 693        </ol>
 694     </ol>
 695     <!-- End of generated Table of Contents -->
 696
 697        <a name=appendix-A><h1>A &nbsp;Appendix</h1></a>
 698        <a name=appendix-A.1><h2>A.1 &nbsp;Appendix Paragraph</h2></a>
 699        <a name=appendix-B><h1>B &nbsp;Appendix</h1></a>
 700        <a name=appendix-B.1><h2>B.1 &nbsp;Appendix Paragraph</h2></a>
 701     </body>
 702     </html>
 703
 704 =head2 Creating site map
 705
 706 Suppose you want to generate a table of contents of the E<lt>titleE<gt> tags of the files in the following directory structure:
 707
 708     path               file
 709
 710     .                  index.htm, <title>Main</title>
 711     |- SubDir1         index.htm, <title>Sub1</title>
 712     |  |- SubSubDir1   index.htm, <title>SubSub1</title>
 713     |
 714     |- SubDir2         index.htm, <title>Sub2</title>
 715     |  |- SubSubDir1   index.htm, <title>SubSub1</title>
 716     |  |- SubSubDir2   index.htm, <title>SubSub2</title>
 717     |
 718     |- SubDir3         index.htm, <title>Sub3</title>
 719
 720 By specifying 'fileSpec' which determine how many slashes (/) each file may contain for a specific level:
 721
 722     use HTML::Toc;
 723     use HTML::TocGenerator;
 724     use File::Find;
 725
 726     my $toc          = HTML::Toc->new;
 727     my $tocGenerator = HTML::TocGenerator->new;
 728     my @fileList;
 729
 730     sub wanted {
 731           # Add file to 'fileList' if extension matches '.htm'
 732        push (@fileList, $File::Find::name) if (m/\.htm$/);
 733     }
 734
 735     $toc->setOptions({
 736        'doLinkToFile'       => 1,
 737        'templateAnchorName' => '""',
 738        'templateAnchorHref' => '"<a href=$file"."#".$groupId.$level.">"',
 739        'doLinkTocToToken'   => 1,
 740        'tokenToToc'         => [{
 741           'groupId'         => 'dir',
 742           'level'           => 1,
 743           'tokenBegin'      => '<title>',
 744           'tokenEnd'        => '</title>',
 745           'fileSpec'        => '\./[^/]+$'
 746        }, {
 747           'groupId'         => 'dir',
 748           'level'           => 2,
 749           'tokenBegin'      => '<title>',
 750           'tokenEnd'        => '</title>',
 751           'fileSpec'        => '\./[^/]+?/[^/]+$'
 752        }, {
 753           'groupId'         => 'dir',
 754           'level'           => 3,
 755           'tokenBegin'      => '<title>',
 756           'tokenEnd'        => '</title>',
 757           'fileSpec'        => '\./[^/]+?/[^/]+?/[^/]+$'
 758        }]
 759     });
 760
 761        # Traverse directory structure
 762     find({wanted => \&wanted, no_chdir => 1}, '.');
 763        # Generate ToC of case-insensitively sorted file list
 764     $tocGenerator->extendFromFile(
 765        $toc, [sort {uc($a) cmp uc($b)} @fileList]
 766     );
 767     print $toc->format();
 768
 769 the following ToC will be generated:
 770
 771     <!-- Table of Contents generated by Perl - HTML::Toc -->
 772     <ul>
 773        <li><a href=./index.htm#>Main</a>
 774        <ul>
 775           <li><a href=./SubDir1/index.htm#>Sub1</a>
 776           <ul>
 777              <li><a href=./SubDir1/SubSubDir1/index.htm#>SubSub1</a>
 778           </ul>
 779           <li><a href=./SubDir2/index.htm#>Sub2</a>
 780           <ul>
 781              <li><a href=./SubDir2/SubSubDir1/index.htm#>SubSub1</a>
 782              <li><a href=./SubDir2/SubSubDir2/index.htm#>SubSub2</a>
 783           </ul>
 784           <li><a href=./SubDir3/index.htm#>Sub3</a>
 785        </ul>
 786     </ul>
 787     <!-- End of generated Table of Contents -->
 788
 789 =head1 Methods
 790
 791 =head2 HTML::Toc::clear()
 792
 793     syntax:  $toc->clear()
 794     returns: --
 795
 796 Clear the ToC.
 797
 798 =head2 HTML::Toc::format()
 799
 800     syntax:  $scalar = $toc->format()
 801     returns: Formatted ToC.
 802
 803 Format tokenized ToC.
 804
 805 =head2 HTML::TocGenerator::extend()
 806
 807     syntax:  $tocGenerator->extend($toc, $string [, $options])
 808     args:    - $toc:     (reference to array of) HTML::Toc object(s) to extend
 809              - $string:  string to retrieve ToC from
 810              - $options: hash reference containing generator options.
 811
 812 Extend ToC from specified string.  For generator options, see L<HTML::TocGenerator Options|"HTML::TocGenerator Options">
 813
 814 =head2 HTML::TocGenerator::extendFromFile()
 815
 816     syntax:  $tocGenerator->extendFromFile($toc, $filename [, $options])
 817     args:    - $toc:      (reference to array of) HTML::Toc object(s) to extend
 818              - $filename: (reference to array of) file(s) to extend ToC from
 819              - $options:  hash reference containing generator options.
 820
 821 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>.
 822
 823 =head2 HTML::TocGenerator::generate()
 824
 825     syntax:  $tocGenerator->generate($toc, $string [, $options])
 826     args:    - $toc:     (reference to array of) HTML::Toc object(s) to generate
 827              - $string:  string to retrieve ToC from
 828              - $options: hash reference containing generator options.
 829
 830 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">.
 831
 832 =head2 HTML::TocGenerator::generateFromFile()
 833
 834     syntax:  $tocGenerator->generateFromFile($toc, $filename [, $options])
 835     args:    - $toc:      (reference to array of) HTML::Toc object(s) to
 836                           generate
 837              - $filename: (reference to array of) file(s) to generate ToC from
 838              - $options:  hash reference containing generator options.
 839
 840 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">.
 841
 842 =head2 HTML::TocInsertor::insert()
 843
 844     syntax:  $tocInsertor->insert($toc, $string [, $options])
 845     args:    - $toc:     (reference to array of) HTML::Toc object(s) to insert
 846              - $string:  string to insert ToC in
 847              - $options: hash reference containing insertor options.
 848
 849 Insert ToC into specified string.  For insertor options, see L<HTML::TocInsertor Options|"HTML::TocInsertor Options">.
 850
 851 =head2 HTML::TocInsertor::insertIntoFile()
 852
 853     syntax:  $tocInsertor->insertIntoFile($toc, $filename [, $options])
 854     args:    - $toc:      (reference to array of) HTML::Toc object(s) to insert
 855              - $filename: (reference to array of) file(s) to insert ToC in
 856              - $options:  hash reference containing insertor options.
 857
 858 Insert ToC into specified file.  For insertor options, see L<HTML::TocInsertor Options|"HTML::TocInsertor Options">.
 859
 860 =head2 HTML::TocUpdator::insert()
 861
 862     syntax:  $tocUpdator->insert($toc, $string [, $options])
 863     args:    - $toc:     (reference to array of) HTML::Toc object(s) to insert
 864              - $string:  string to insert ToC in
 865              - $options: hash reference containing updator options.
 866
 867 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">.
 868
 869 =head2 HTML::TocUpdator::insertIntoFile()
 870
 871     syntax:  $tocUpdator->insertIntoFile($toc, $filename [, $options])
 872     args:    - $toc:      (reference to array of) HTML::Toc object(s) to insert
 873              - $filename: (reference to array of) file(s) to insert ToC in
 874              - $options:  hash reference containing updator options.
 875
 876 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">.
 877
 878 =head2 HTML::TocUpdator::update()
 879
 880     syntax:  $tocUpdator->update($toc, $string [, $options])
 881     args:    - $toc:     (reference to array of) HTML::Toc object(s) to insert
 882              - $string:  string to update ToC in
 883              - $options: hash reference containing updator options.
 884
 885 Update ToC within specified string.  For updator options, see L<HTML::TocUpdator Options|"HTML::TocUpdator Options">.
 886
 887 =head2 HTML::TocUpdator::updateFile()
 888
 889     syntax:  $tocUpdator->updateFile($toc, $filename [, $options])
 890     args:    - $toc:      (reference to array of) HTML::Toc object(s) to insert
 891              - $filename: (reference to array of) file(s) to update ToC in
 892              - $options:  hash reference containing updator options.
 893
 894 Update ToC of specified file.  For updator options, see L<HTML::TocUpdator Options|"HTML::TocUpdator Options">.
 895
 896 =head1 Parser Options
 897
 898 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:
 899
 900     $tocGenerator->generateFromFile($toc, $filename, {doUseGroupsGlobal => 1});
 901
 902 Available options are:
 903
 904 =over 4
 905
 906 =item L<doGenerateToc|"doGenerateToc">
 907
 908 =item L<doUseGroupsGlobal|"doUseGroupsGlobal">
 909
 910 =item L<output|"output">
 911
 912 =item L<outputFile|"outputFile">
 913
 914 =back
 915
 916 =head2 doGenerateToc
 917
 918     syntax:         [0|1]
 919     default:        1
 920     applicable to:  TocInsertor, TocUpdator
 921
 922 True (1) if ToC must be generated.  False (0) if ToC must be inserted only.
 923
 924 =head2 doUseGroupsGlobal
 925
 926     syntax:         [0|1]
 927     default:        0
 928     applicable to:  TocGenerator, TocInsertor, TocUpdator
 929
 930 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':
 931
 932     <h1>Chapter</h1>
 933     <h2>Paragraph</h2>
 934
 935 Using the default setting of 'doUseGroupsGlobal' => 0:
 936
 937     use HTML::Toc;
 938     use HTML::TocGenerator;
 939
 940     my $toc1         = HTML::Toc->new();
 941     my $toc2         = HTML::Toc->new();
 942     my $tocGenerator = HTML::TocGenerator->new();
 943
 944     $toc1->setOptions({
 945        'header'     => '',
 946        'footer'     => '',
 947        'tokenToToc' => [{'tokenBegin' => '<h1>'}]
 948     });
 949     $toc2->setOptions({
 950        'header'     => '',
 951        'footer'     => '',
 952        'tokenToToc' => [{'tokenBegin' => '<h2>'}]
 953     });
 954     $tocGenerator->generateFromFile([$toc1, $toc2], 'index.htm');
 955     print $toc1->format() . "\n\n" . $toc2->format();
 956
 957 the output will be:
 958
 959     <ul>
 960        <li><a href=#h-1>Chapter</a>
 961     </ul>
 962
 963     <ul>
 964        <li><a href=#h-1>Paragraph</a>
 965     </ul>
 966
 967 Each ToC will use its own numbering scheme.  Now if 'C<doUseGroupsGlobal = 1>' is specified:
 968
 969     $tocGenerator->generateFromFile(
 970         [$toc1, $toc2], 'index.htm', {'doUseGroupsGlobal' => 1}
 971     );
 972
 973 the output will be:
 974
 975     <ul>
 976        <li><a href=#h-1>Chapter</a>
 977     </ul>
 978
 979     <ul>
 980        <li><a href=#h-2>Paragraph</a>
 981     </ul>
 982
 983 using a global numbering scheme for all ToCs.
 984
 985 =head2 output
 986
 987     syntax:         reference to scalar
 988     default:        none
 989     applicable to:  TocInsertor, TocUpdator
 990
 991 Reference to scalar where the output must be stored in.
 992
 993 =head2 outputFile
 994
 995     syntax:         scalar
 996     default:        none
 997     applicable to:  TocInsertor, TocUpdator
 998
 999 Filename to write output to.  If no filename is specified, output will be written to standard output.
1000
1001 =head1 HTML::Toc Options
1002
1003 The C<HTML::Toc> options can be grouped in the following categories:
1004
1005 =over 4
1006
1007 =item L<Generate options|"Generate options">
1008
1009 =item L<Insert options|"Insert options">
1010
1011 =item L<Update options|"Update options">
1012
1013 =item L<Format options|"Format options">
1014
1015 =back
1016
1017 The ToC options must be specified using the 'setOptions' method.  For example:
1018
1019     my $toc = new HTML::Toc;
1020
1021     $toc->setOptions({
1022        'doNumberToken' => 1,
1023        'footer'        => '<!-- End Of ToC -->'
1024        'tokenToToc'    => [{
1025           'level'          => 1,
1026           'tokenBegin'     => '<h1>',
1027           'numberingStyle' => 'lower-alpha'
1028        }]
1029     });
1030
1031 =head2 Generate options
1032
1033 =over 4
1034
1035 =item Token groups
1036
1037 =over 4
1038
1039 =item L<tokenToToc|"tokenToToc">
1040
1041 =over 4
1042
1043 =item L<doNumberToken|"doNumberToken">
1044
1045 =item L<fileSpec|"fileSpec">
1046
1047 =item L<groupId|"groupId">
1048
1049 =item L<level|"level">
1050
1051 =item L<tokenBegin|"tokenBegin">
1052
1053 =item L<tokenEnd|"tokenEnd">
1054
1055 =item L<numberingStyle|"numberingStyle">
1056
1057 =back
1058
1059 =item L<groupToToc|"groupToToc">
1060
1061 =item L<levelToToc|"levelToToc">
1062
1063 =back
1064
1065 =item Numbering tokens
1066
1067 =over 4
1068
1069 =item L<doNumberToken|"doNumberToken">
1070
1071 =item L<numberingStyle|"numberingStyle">
1072
1073 =item L<templateTokenNumber|"templateTokenNumber">
1074
1075 =back
1076
1077 =item Miscellaneous
1078
1079 =over 4
1080
1081 =item L<attributeToExcludeToken|"attributeToExcludeToken">
1082
1083 =item L<attributeToTocToken|"attributeToTocToken">
1084
1085 =item L<groupToToc|"groupToToc">
1086
1087 =item L<levelToToc|"levelToToc">
1088
1089 =back
1090
1091 =item Linking ToC to tokens
1092
1093 =over 4
1094
1095 =item L<doLinkToToken|"doLinkToToken">
1096
1097 =item L<doLinkToFile|"doLinkToFile">
1098
1099 =item L<doLinkToId|"doLinkToId">
1100
1101 =item L<templateAnchorName|"templateAnchorName">
1102
1103 =item L<templateAnchorHrefBegin|"templateAnchorHrefBegin">
1104
1105 =item L<templateAnchorHrefEnd|"templateAnchorHrefEnd">
1106
1107 =item L<templateAnchorNameBegin|"templateAnchorNameBegin">
1108
1109 =item L<templateAnchorNameEnd|"templateAnchorNameEnd">
1110
1111 =back
1112
1113 =back
1114
1115 =head2 Insert options
1116
1117 =over 4
1118
1119 =item L<insertionPoint|"insertionPoint">
1120
1121 =back
1122
1123 =head2 Update options
1124
1125 =over 4
1126
1127 =item L<tokenUpdateBeginAnchorName|"tokenUpdateBeginAnchorName">
1128
1129 =item L<tokenUpdateEndAnchorName|"tokenUpdateEndAnchorName">
1130
1131 =item L<tokenUpdateBeginToc|"tokenUpdateBeginToc">
1132
1133 =item L<tokenUpdateEndToc|"tokenUpdateEndToc">
1134
1135 =item L<tokenUpdateBeginNumber|"tokenUpdateBeginNumber">
1136
1137 =item L<tokenUpdateEndNumber|"tokenUpdateEndNumber">
1138
1139 =back
1140
1141 =head2 Format options
1142
1143 =over 4
1144
1145 =item L<doSingleStepLevel|"doSingleStepLevel">
1146
1147 =item L<doNestGroup|"doNestGroup">
1148
1149 =item L<footer|"footer">
1150
1151 =item L<groupToToc|"groupToToc">
1152
1153 =item L<header|"header">
1154
1155 =item L<levelIndent|"levelIndent">
1156
1157 =item L<levelToToc|"levelToToc">
1158
1159 =item L<templateLevelBegin|"templateLevelBegin">
1160
1161 =item L<templateLevelEnd|"templateLevelEnd">
1162
1163 =back
1164
1165 =head1 HTML::Toc Options Reference
1166
1167 =head2 attributeToExcludeToken
1168
1169     syntax:  $scalar
1170     default: '-'
1171
1172 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">.
1173
1174 =head2 attributeToTocToken
1175
1176     syntax:  $scalar
1177     default: '@'
1178
1179 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">.
1180
1181 =head2 doLinkToToken
1182
1183     syntax:  [0|1]
1184     default: 1
1185
1186 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.
1187
1188 =head2 doLinkToFile
1189
1190     syntax:  [0|1]
1191     default: 0
1192
1193 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.
1194
1195 =head2 doLinkToId
1196
1197     syntax:  [0|1]
1198     default: 0
1199
1200 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.
1201
1202 =head2 doNestGroup
1203
1204     syntax:  [0|1]
1205     default: 0
1206
1207 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">.
1208
1209 =head2 doNumberToken
1210
1211     syntax:  [0|1]
1212     default: 0
1213
1214 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">.
1215
1216 =head2 doSingleStepLevel
1217
1218     syntax:  [0|1]
1219     default: 1
1220
1221 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>':
1222
1223     <h1>Chapter</h1>
1224     <h3>Paragraph</h3>
1225
1226 By default, an empty indentation level will be inserted in the ToC:
1227
1228     <!-- Table of Contents generated by Perl - HTML::Toc -->
1229     <ul>
1230        <li><a href=#h-1>Header 1</a>
1231        <ul>
1232           <ul>
1233              <li><a href=#h-1.0.1>Header 3</a>
1234           </ul>
1235        </ul>
1236     </ul>
1237     <!-- End of generated Table of Contents -->
1238
1239 After specifying:
1240
1241     $toc->setOptions({'doSingleStepLevel' => 0});
1242
1243 the ToC will not have an indentation level inserted for level 2:
1244
1245     <!-- Table of Contents generated by Perl - HTML::Toc -->
1246     <ul>
1247        <li><a href=#h-1>Header 1</a>
1248        <ul>
1249              <li><a href=#h-1.0.1>Header 3</a>
1250        </ul>
1251     </ul>
1252     <!-- End of generated Table of Contents -->
1253
1254 =head2 fileSpec
1255
1256     syntax:  <regexp>
1257     default: undef
1258
1259 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">.
1260
1261 =head2 footer
1262
1263     syntax:  $scalar
1264     default: "\n<!-- End of generated Table of Contents -->\n"
1265
1266 String to output at end of ToC.
1267
1268 =head2 groupId
1269
1270     syntax:  $scalar
1271     default: 'h'
1272
1273 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:
1274
1275     $toc->setOptions({
1276        'tokenToToc' => [{
1277               'tokenBegin' => '<h1 class=-appendix>'
1278            }, {
1279               'groupId' => 'appendix',
1280               'tokenBegin' => '<h1 class=appendix>'
1281        }]
1282     });
1283
1284 =head2 groupToToc
1285
1286     syntax:  <regexp>
1287     default: '.*'
1288
1289 Determines which groups to use for generating the ToC.  For example, to create a ToC for groups [a-b] only, specify:
1290
1291     'groupToToc => '[a-b]'
1292
1293 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:
1294
1295     $toc->setOptions({'groupToToc' => '.*'});
1296     $tocGenerator->generateToc($toc, ...);
1297         # Get ToC of all groups
1298     $fullToc = $toc->format();
1299         # Get ToC of 'appendix' group only
1300     $toc->setOptions({'groupToToc' => 'appendix'});
1301     $appendixToc = $toc->format();
1302
1303 =head2 header
1304
1305     syntax:  $scalar
1306     default: "\n<!-- Table of Contents generated by Perl - HTML::Toc -->\n"
1307
1308 String to output at begin of ToC.
1309
1310
1311 =head2 insertionPoint
1312
1313     syntax:  [<before|after|replace>] <token>
1314     default: 'after <body>'
1315     token:   <[/]tag{ attribute=[-|@]<regexp>}> |
1316              <text regexp> |
1317              <declaration regexp> |
1318              <comment regexp>
1319
1320 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:
1321
1322     '<h1 class=^header$>'
1323
1324 Examples of valid 'insertionPoint' tokens are:
1325
1326     '<h1>'
1327     '</h1>'
1328     '<!-- ToC -->'
1329     '<!ToC>'
1330     'ToC will be placed here'
1331
1332 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:
1333
1334     '<h1 class=-^header$>'
1335
1336 See also L<tokenBegin|"tokenBegin">.
1337
1338 =head2 level
1339
1340     syntax:  number
1341     default: 1
1342
1343 Number which identifies at which level the tokengroup should be incorporated into the ToC.  See also: L<tokenToToc|"tokenToToc">.
1344
1345 =head2 levelIndent
1346
1347     syntax:  number
1348     default: 3
1349
1350 Sets the number of spaces each level will be indented, when formatting the ToC.
1351
1352 =head2 levelToToc
1353
1354     syntax:  <regexp>
1355     default: '.*'
1356
1357 Determines which group levels to use for generating the ToC.  For example, to create a ToC for levels 1-2 only, specify:
1358
1359     'levelToToc => '[1-2]'
1360
1361 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:
1362
1363     $toc->setOptions({'levelToToc' => '.*'});
1364     $tocGenerator->generateToc($toc, ...);
1365         # Get ToC of all levels
1366     $fullToc = $toc->getToc();
1367         # Get ToC of level 1 only
1368     $toc->setOptions({'levelToToc' => '1'});
1369     $level1Toc = $toc->getToc();
1370
1371 =head2 numberingStyle
1372
1373     syntax:  [decimal|lower-alpha|upper-alpha|lower-roman|upper-roman]}
1374     default: decimal
1375
1376 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.:
1377
1378     $toc->setOptions({
1379        'doNumberToken' => 1,
1380        'tokenToToc' => [{
1381           'level'          => 1,
1382           'tokenBegin'     => '<h1>',
1383           'numberingStyle' => 'lower-alpha'
1384        }]
1385     });
1386
1387 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>.
1388
1389 =head2 templateAnchorName
1390
1391     syntax:  <expression|function reference>
1392     default: '$groupId."-".$node'
1393
1394 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:
1395
1396     $file
1397     $groupId
1398     $level
1399     $node
1400
1401 If C<templateAnchorHrefBegin> is a function reference to a function returning the anchor, like in:
1402
1403     $toc->setOptions({'templateAnchorName' => \&assembleAnchorName});
1404
1405 the function will be called with the following arguments:
1406
1407     $anchorName = assembleAnchorName($file, $groupId, $level, $node);
1408
1409 =head2 templateAnchorHrefBegin
1410
1411     syntax:  <expression|function reference>
1412     default: '"<a href=#$anchorName>"' or
1413              '"<a href=$file#$anchorName>"',
1414              depending on 'doLinkToFile' being 0 or 1 respectively.
1415
1416 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:
1417
1418     $file
1419     $groupId
1420     $level
1421     $node
1422     $anchorName
1423
1424 If C<templateAnchorHrefBegin> is a function reference to a function returning the anchor, like in:
1425
1426     $toc->setOptions({'templateAnchorHrefBegin' => \&assembleAnchorHrefBegin});
1427
1428 the function will be called with the following arguments:
1429
1430     $anchorHrefBegin = &assembleAnchorHrefBegin(
1431        $file, $groupId, $level, $node, $anchorName
1432     );
1433
1434 See also: L<templateAnchorName|"templateAnchorName">, L<templateAnchorHrefEnd|"templateAnchorHrefEnd">.
1435
1436 =head2 templateAnchorHrefEnd
1437
1438     syntax:  <expression|function reference>
1439     default: '"</a>"'
1440
1441 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:
1442
1443     $toc->setOptions({'templateAnchorHrefEnd' => \&assembleAnchorHrefEnd});
1444
1445 the function will be called without arguments:
1446
1447     $anchorHrefEnd = &assembleAnchorHrefEnd;
1448
1449 See also: L<templateAnchorHrefBegin|"templateAnchorHrefBegin">.
1450
1451 =head2 templateAnchorNameBegin
1452
1453     syntax:  <expression|function reference>
1454     default: '"<a name=$anchorName>"'
1455
1456 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:
1457
1458     $file
1459     $groupId
1460     $level
1461     $node
1462     $anchorName
1463
1464 If C<templateAnchorNameBegin> is a function reference to a function returning the anchor name, like in:
1465
1466     $toc->setOptions({'templateAnchorNameBegin' => \&assembleAnchorNameBegin});
1467
1468 the function will be called with the following arguments:
1469
1470     $anchorNameBegin = assembleAnchorNameBegin(
1471         $file, $groupId, $level, $node, $anchorName
1472     );
1473
1474 See also: L<templateAnchorName|"templateAnchorName">, L<templateAnchorNameEnd|"templateAnchorNameEnd">.
1475
1476 =head2 templateAnchorNameEnd
1477
1478     syntax:  <expression|function reference>
1479     default: '"</a>"'
1480
1481 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:
1482
1483     $toc->setOptions({'templateAnchorNameEnd' => \&assembleAnchorNameEnd});
1484
1485 the function will be called without arguments:
1486
1487     $anchorNameEnd = &assembleAnchorNameEnd;
1488
1489 See also: L<templateAnchorNameBegin|"templateAnchorNameBegin">.
1490
1491 =head2 templateLevel
1492
1493     syntax:  <expression|function reference>
1494     default: '"<li>$text\n"'
1495
1496 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:
1497
1498     $level
1499     $groupId
1500     $node
1501     $sequenceNr
1502     $text
1503
1504 If C<templateLevel> is a function reference to a function returning the ToC node, like in:
1505
1506     $toc->setOptions({'templateLevel' => \&AssembleTocNode});
1507
1508 the function will be called with the following arguments:
1509
1510     $tocNode = &AssembleTocNode(
1511         $level, $groupId, $node, $sequenceNr, $text
1512     );
1513
1514 =head2 templateLevelBegin
1515
1516     syntax:  <expression>
1517     default: '"<ul>\n"'
1518
1519 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:
1520
1521     '"<ul class=toc_$groupId$level>\n"'
1522
1523 which will result in each ToC group being given a class name:
1524
1525     <ul class=toc_h1>
1526        <li>Header
1527     </ul>
1528
1529 For an example, see L<Using CSS for ToC formatting|"Using CSS for ToC formatting">.
1530
1531 =head2 templateLevelEnd
1532
1533     syntax:  <expression>
1534     default: '"<ul>\n"'
1535
1536 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:
1537
1538     '"</ul>\n"'
1539
1540 For an example, see L<Using CSS for ToC formatting|"Using CSS for ToC formatting">.
1541
1542 =head2 templateTokenNumber
1543
1544     syntax:  <expression|function reference>
1545     default: '"$node &nbsp;"'
1546
1547 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:
1548
1549     $file
1550     $groupId
1551     $groupLevel
1552     $level
1553     $node
1554     $toc
1555
1556 If C<templateTokenNumber> is a function reference to a function returning the token number, like in:
1557
1558     $toc->setOptions({'templateTokenNumber' => \&assembleTokenNumber});
1559
1560 the function will be called with the following arguments:
1561
1562     $number = &assembleTokenNumber(
1563         $node, $groupId, $file, $groupLevel, $level, $toc
1564     );
1565
1566 =head2 tokenBegin
1567
1568     syntax:  <token>
1569     default: '<h1>'
1570     token:   <[/]tag{ attribute=[-|@]<regexp>}> |
1571              <text regexp> |
1572              <declaration regexp> |
1573              <comment regexp>
1574
1575 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:
1576
1577     '<h1>'
1578     '</end>'
1579     '<!-- Start ToC entry -->'
1580     '<!Start ToC entry>'
1581     'ToC entry'
1582
1583 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:
1584
1585     '<h1 class=^header$>'
1586
1587 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:
1588
1589     '<h1 class=-^header$>'
1590
1591 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:
1592
1593     '<h1 class=@>'
1594
1595 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.
1596
1597 See also: L<tokenEnd|"tokenEnd">, L<tokenToToc|"tokenToToc">.
1598
1599 =head2 tokenEnd
1600
1601     syntax:  $scalar
1602     default: empty string ('') or end tag counterpart of 'tokenBegin' if
1603              'tokenBegin' is a start tag
1604
1605 The 'tokenEnd' definition applies to the same rules as L<tokenBegin|"tokenBegin">.
1606
1607 See also: L<tokenBegin|"tokenBegin">, L<tokenToToc|"tokenToToc">.
1608
1609 =head2 tokenToToc
1610
1611     syntax:  [{array of hashrefs}]
1612     default: [{
1613                 'level'      => 1,
1614                 'tokenBegin' => '<h1>'
1615              }, {
1616                 'level'      => 2,
1617                 'tokenBegin' => '<h2>'
1618              }, {
1619                 'level'      => 3,
1620                 'tokenBegin' => '<h3>'
1621              }, {
1622                 'level'      => 4,
1623                 'tokenBegin' => '<h4>'
1624              }, {
1625                 'level'      => 5,
1626                 'tokenBegin' => '<h5>'
1627              }, {
1628                 'level'      => 6,
1629                 'tokenBegin' => '<h6>'
1630              }]
1631
1632 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.
1633
1634 =head2 tokenUpdateBeginAnchorName
1635
1636     syntax:  <string>
1637     default: '<!-- #BeginTocAnchorNameBegin -->';
1638
1639 This token marks the begin of an anchor name, inserted by C<HTML::TocInsertor>.  This option is used by C<HTML::TocUpdator>.
1640
1641 =head2 tokenUpdateEndAnchorName
1642
1643     syntax:  <string>
1644     default: '<!-- #EndTocAnchorName -->';
1645
1646 This option is used by C<HTML::TocUpdator>, to mark the end of an inserted anchor name.
1647
1648 =head2 tokenUpdateBeginNumber
1649
1650     syntax:  <string>
1651     default: '<!-- #BeginTocNumber -->';
1652
1653 This option is used by C<HTML::TocUpdator>, to mark the begin of an inserted number.
1654
1655 =head2 tokenUpdateEndNumber
1656
1657     syntax:  <string>
1658     default: '<!-- #EndTocAnchorName -->';
1659
1660 This option is used by C<HTML::TocUpdator>, to mark the end of an inserted number.
1661
1662 =head2 tokenUpdateBeginToc
1663
1664     syntax:  <string>
1665     default: '<!-- #BeginToc -->';
1666
1667 This option is used by C<HTML::TocUpdator>, to mark the begin of an inserted ToC.
1668
1669 =head2 tokenUpdateEndToc
1670
1671     syntax:  <string>
1672     default: '<!-- #EndToc -->';
1673
1674 This option is used by C<HTML::TocUpdator>, to mark the end of an inserted ToC.
1675
1676 =head1 Known issues
1677
1678 =head2 Cygwin
1679
1680 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.
1681 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.
1682
1683 =head2 Nested anchors
1684
1685 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:
1686
1687     <a name=foo><h1>Header</h1></a>
1688
1689 will go all right, whereas:
1690
1691     <h1><a name=foo>Header</a></h1>
1692
1693 will yield the warning:
1694
1695     warning (1): Nested anchor '<a name=foo>' within anchor '<a name=h-1>'.
1696
1697 since anchor names aren't allowed to be nested according to the HTML 4.01 specification.
1698
1699 =head1 AUTHOR
1700
1701 Freddy Vulto E<lt>L<"fvu@fvu.myweb.nl">E<gt>
1702
1703 =head1 COPYRIGHT
1704
1705 Copyright (c) 2001 Freddy Vulto.  All rights reserved.
1706
1707 This library is free software; you can redistribute it and/or
1708 modify it under the same terms as Perl itself.
1709
1710 =cut