1Toc(3)                User Contributed Perl Documentation               Toc(3)
2
3
4

NAME

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

DESCRIPTION

9       Generate, insert and update HTML Table of Contents (ToC).
10

Introduction

12       The HTML::Toc consists out of the following packages:
13
14           HTML::Toc
15           HTML::TocGenerator
16           HTML::TocInsertor
17           HTML::TocUpdator
18
19       HTML::Toc is the object which will eventually hold the Table of
20       Contents.  HTML::TocGenerator does the actual generation of the ToC.
21       HTML::TocInsertor handles the insertion of the ToC in the source.
22       HTML::TocUpdator takes care of updating previously inserted ToCs.
23
24       HTML::Parser is the base object of HTML::TocGenerator,
25       HTML::TocInsertor and HTML::TocUpdator.  Each of these objects uses its
26       predecessor as its ancestor, as shown in the UML diagram underneath:
27
28           +---------------------+
29           |    HTML::Parser     |
30           +---------------------+
31           +---------------------+
32           |    +parse()         |
33           |    +parse_file()    |
34           +----------+----------+
35                     /_\
36                      |
37           +----------+----------+  <<uses>>  +-----------+
38           | HTML::TocGenerator  + - - - - - -+ HTML::Toc |
39           +---------------------+            +-----------+
40           +---------------------+            +-----------+
41           | +extend()           |            | +clear()  |
42           | +extendFromFile()   |            | +format() |
43           | +generate()         |            +-----+-----+
44           | +generateFromFile() |                  :
45           +----------+----------+                  :
46                     /_\                            :
47                      |                             :
48           +----------+----------+     <<uses>>     :
49           |  HTML::TocInsertor  + - - - - - - - - -+
50           +---------------------+                  :
51           +---------------------+                  :
52           |  +insert()          |                  :
53           |  +insertIntoFile()  |                  :
54           +----------+----------+                  :
55                     /_\                            :
56                      |                             :
57           +----------+----------+     <<uses>>     :
58           |  HTML::TocUpdator   + - - - - - - - - -+
59           +---------------------+
60           +---------------------+
61           |  +insert()          |
62           |  +insertIntoFile()  |
63           |  +update()          |
64           |  +updateFile()      |
65           +---------------------+
66
67       When generating a ToC you'll have to decide which object you want to
68       use:
69
70           TocGenerator:
71               for generating a ToC without inserting the ToC into the source
72           TocInsertor:
73               for generating a ToC and inserting the ToC into the source
74           TocUpdator:
75               for generating and inserting a ToC, removing any previously
76               inserted ToC elements
77
78       Thus in tabular view, each object is capable of:
79
80                          generating   inserting   updating
81                          ---------------------------------
82           TocGenerator        X
83           TocInsertor         X           X
84           TocUpdator          X           X           X
85
86   Generating
87       The code underneath will generate a ToC of the HTML headings
88       "<h1">.."<h6"> from a file "index.htm":
89
90           use HTML::Toc;
91           use HTML::TocGenerator;
92
93           my $toc          = HTML::Toc->new();
94           my $tocGenerator = HTML::TocGenerator->new();
95
96           $tocGenerator->generateFromFile($toc, 'index.htm');
97           print $toc->format();
98
99       For example, with "index.htm" containing:
100
101           <html>
102           <body>
103              <h1>Chapter</h1>
104           </body>
105           </html>
106
107       the output will be:
108
109           <!-- Table of Contents generated by Perl - HTML::Toc -->
110           <ul>
111           <li><a href="#h-1">Chapter</a></li>
112           </ul>
113           <!-- End of generated Table of Contents -->
114
115   Inserting
116       This code will generate a ToC of HTML headings "<h1">.."<h6"> of file
117       "index.htm", and insert the ToC after the "<body"> tag at the same
118       time:
119
120           use HTML::Toc;
121           use HTML::TocInsertor;
122
123           my $toc         = HTML::Toc->new();
124           my $tocInsertor = HTML::TocInsertor->new();
125
126           $tocInsertor->insertIntoFile($toc, 'index.htm');
127
128       For example, with "index.htm" containing:
129
130           <html>
131           <body>
132              <h1>Chapter</h1>
133           </body>
134           </html>
135
136       the output will be:
137
138           <html>
139           <body>
140           <!-- Table of Contents generated by Perl - HTML::Toc -->
141           <ul>
142           <li><a href="#h-1">Chapter</a></li>
143           </ul>
144           <!-- End of generated Table of Contents -->
145
146           <h1><a name="h-1"></a>Chapter</h1>
147           </body>
148           </html>
149
150       Inserting into string
151
152       By default, "HTML::TocInsertor::insert()" prints both the string and
153       the generated ToC to standard output.  To actually insert the ToC in
154       the string, use the output option to specify a scalar reference to
155       insert the ToC into:
156
157           use HTML::Toc;
158           use HTML::TocInsertor;
159
160           my $toc         = HTML::Toc->new();
161           my $tocInsertor = HTML::TocInsertor->new();
162
163           $html =<<HTML;
164           <html>
165           <body>
166              <h1>Chapter</h1>
167           </body>
168           </html>
169           HTML
170           $tocInsertor->insert($toc, $html, {'output' => \$html});
171           print $html;
172
173       Now the output will be:
174
175           <html>
176           <body>
177           <!-- Table of Contents generated by Perl - HTML::Toc -->
178           <ul>
179              <li><a href="#h-1">Chapter</a></li>
180           </ul>
181           <!-- End of generated Table of Contents -->
182
183              <h1><a name="h-1"></a>Chapter</h1>
184           </body>
185           </html>
186
187       Inserting with update tokens
188
189       If you're planning to update the inserted ToC, you'd better use
190       "TocUpdator" to insert the ToC.  "TocUpdator" marks the inserted ToC
191       elements with update tokens.  These update tokens allow "TocUpdator" to
192       identify and remove the ToC elements during a future update session.
193       This code uses "TocUpdator" instead of "TocInsertor":
194
195           use HTML::Toc;
196           use HTML::TocUpdator;
197
198           my $toc        = HTML::Toc->new();
199           my $tocUpdator = HTML::TocUpdator->new();
200
201           $tocUpdator->insertIntoFile($toc, 'index.htm');
202
203       When applying the code above on 'index.htm':
204
205           <html>
206           <body>
207              <h1>
208              Chapter
209              </h1>
210           </body>
211           </html>
212
213       the output will contain additional update tokens:
214
215           <!-- #BeginToc -->
216           <!-- #EndToc -->
217           <!-- #BeginTocAnchorNameBegin -->
218           <!-- #EndTocAnchorNameBegin -->
219           <!-- #BeginTocAnchorNameEnd -->
220           <!-- #EndTocAnchorNameEnd -->
221
222       around the inserted ToC elements:
223
224           <html>
225           <body><!-- #BeginToc -->
226           <!-- Table of Contents generated by Perl - HTML::Toc -->
227           <ul>
228              <li><a href="#h-1"> Chapter </a></li>
229           </ul>
230           <!-- End of generated Table of Contents -->
231           <!-- #EndToc -->
232              <h1><!-- #BeginTocAnchorNameBegin --><a name="h-1"></a><!-- #EndTocAnchorNameBegin -->
233              Chapter
234              </h1>
235           </body>
236           </html>
237
238       Instead of "HTML::TocUpdator::insertIntoFile" you can also use
239       "HTML::TocUpdator::updateFile()".  "HTML::TocUpdator::updateFile()"
240       will also insert the ToC, whether there is a ToC already inserted or
241       not.
242
243   Updating
244       This code will generate a ToC of HTML headings "<h1">.."<h6"> of file
245       "indexToc.htm", and insert or update the ToC after the "<body"> tag at
246       the same time:
247
248           use HTML::Toc;
249           use HTML::TocUpdator;
250
251           my $toc        = HTML::Toc->new();
252           my $tocUpdator = HTML::TocUpdator->new();
253
254           $tocUpdator->updateFile($toc, 'indexToc.htm');
255
256       For example, with "indexToc.htm" containing:
257
258           <html>
259           <body><!-- #BeginToc -->
260           foo
261           <!-- #EndToc -->
262              <!-- #BeginTocAnchorNameBegin -->bar<!-- #EndTocAnchorNameBegin --><h1>
263              Chapter
264              </h1><!-- #BeginTocAnchorNameEnd -->foo<!-- #EndTocAnchorNameEnd -->
265           </body>h
266           </html>
267
268       the output will be:
269
270           <html>
271           <body><!-- #BeginToc -->
272           <!-- Table of Contents generated by Perl - HTML::Toc -->
273           <ul>
274              <li><a href="#h-1"> Chapter </a></li>
275           </ul>
276           <!-- End of generated Table of Contents -->
277           <!-- #EndToc -->
278              <h1><!-- #BeginTocAnchorNameBegin --><a name="h-1"></a><!-- #EndTocAnchorNameBegin -->
279              Chapter
280              </h1>
281           </body>
282           </html>
283
284       All text between the update tokens will be replaced.  So be warned: all
285       manual changes made to text between update tokens will be removed
286       unrecoverable after calling "HTML::TocUpdator::update()" or
287       "HTML::TocUpdator::updateFile()".
288
289   Formatting
290       The ToC isn't generated all at once.  There are two stages involved:
291       generating and formatting.  Generating the ToC actually means storing a
292       preliminary ToC in "HTML::Toc->{_toc}".  This preliminary, tokenized
293       ToC has to be turned into something useful by calling
294       "HTML::Toc->format()".  For an example, see paragraph 'Generating'.
295

Advanced

297       The ToC generation can be modified in a variety of ways.  The following
298       paragraphs each explain a single modification.  An example of most of
299       the modifications can be found in the "manualTest.t" test file.  Within
300       this test, a manual containing:
301
302           preface
303           introduction
304           table of contents
305           table of figures
306           table of tables
307           parts
308           chapters
309           appendixes
310           bibliography
311
312       is formatted all at once.
313
314   Using attribute value as ToC text
315       Normally, the ToC will be made of text between specified ToC tokens.
316       It's also possible to use the attribute value of a token as a ToC text.
317       This can be done by specifying the attribute marked with an
318       attributeToTocToken within the tokenBegin token.  For example, suppose
319       you want to generate a ToC of the "alt" attributes of the following
320       image tokens:
321
322           <body>
323              <img src=test1.gif alt="First picture">
324              <img src=test2.gif alt="Second picture">
325           </body>
326
327       This would be the code:
328
329           use HTML::Toc;
330           use HTML::TocInsertor;
331
332           my $toc         = HTML::Toc->new();
333           my $tocInsertor = HTML::TocInsertor->new();
334
335           $toc->setOptions({
336              'tokenToToc'   => [{
337                 'groupId'    => 'image',
338                 'tokenBegin' => '<img alt=@>'
339              }],
340           });
341           $tocInsertor->insertIntoFile($toc, $filename);
342
343       and the output will be:
344
345           <body>
346           <!-- Table of Contents generated by Perl - HTML::Toc -->
347           <ul>
348              <li><a href="#image-1">First picture</a></li>
349              <li><a href="#image-2">Second picture</a></li>
350           </ul>
351           <!-- End of generated Table of Contents -->
352
353              <a name="image-1"></a><img src="test1.gif" alt="First picture">
354              <a name="image-2"></a><img src="test2.gif" alt="Second picture">
355           </body>
356
357   Generate single ToC of multiple files
358       Besides generating a ToC of a single file, it's also possible to
359       generate a single ToC of multiple files.  This can be done by
360       specifying either an array of files as the file argument and/or by
361       extending an existing ToC.
362
363       Specify an array of files
364
365       For example, suppose you want to generate a ToC of both "doc1.htm":
366
367           <body>
368              <h1>Chapter of document 1</h1>
369           </body>
370
371       and "doc2.htm":
372
373           <body>
374              <h1>Chapter of document 2</h1>
375           </body>
376
377       Here's the code to do so by specifying an array of files:
378
379           use HTML::Toc;
380           use HTML::TocGenerator;
381
382           my $toc          = HTML::Toc->new();
383           my $tocGenerator = HTML::TocGenerator->new();
384
385           $toc->setOptions({'doLinkToFile' => 1});
386           $tocGenerator->generateFromFile($toc, ['doc1.htm', 'doc2.htm']);
387           print $toc->format();
388
389       And the output will be:
390
391           <!-- Table of Contents generated by Perl - HTML::Toc -->
392           <ul>
393              <li><a href="doc1.htm#h-1">Chapter of document 1</a></li>
394              <li><a href="doc2.htm#h-2">Chapter of document 2</a></li>
395           </ul>
396           <!-- End of generated Table of Contents -->
397
398       Extend an existing ToC
399
400       It's also possible to extend an existing ToC.  For example, suppose we
401       want the generate a ToC of file "doc1.htm":
402
403           <body>
404              <h1>Chapter of document 1</h1>
405           </body>
406
407       and extend this ToC with text from "doc2.htm":
408
409           <body>
410              <h1>Chapter of document 2</h1>
411           </body>
412
413       Here's the code to do so:
414
415           use HTML::Toc;
416           use HTML::TocGenerator;
417
418           my $toc          = HTML::Toc->new();
419           my $tocGenerator = HTML::TocGenerator->new();
420
421           $toc->setOptions({'doLinkToFile' => 1});
422           $tocGenerator->generateFromFile($toc, 'doc1.htm');
423           $tocGenerator->extendFromFile($toc, 'doc2.htm');
424           print $toc->format();
425
426       And the output will be:
427
428           <!-- Table of Contents generated by Perl - HTML::Toc -->
429           <ul>
430              <li><a href="doc1.htm#h-1">Chapter of document 1</a></li>
431              <li><a href="doc2.htm#h-2">Chapter of document 2</a></li>
432           </ul>
433           <!-- End of generated Table of Contents -->
434
435   Generate multiple ToCs
436       It's possible to generate multiple ToCs at once by specifying a
437       "HTML::Toc" object array as the ToC argument.  For example, suppose you
438       want to generate a default ToC of HTML headings h1..h6 as well as a ToC
439       of the "alt" image attributes of the following text:
440
441           <body>
442              <h1>Header One</h1>
443              <img src="test1.gif" alt="First picture">
444              <h2>Paragraph One</h2>
445              <img src="test2.gif" alt="Second picture">
446           </body>
447
448       Here's how you would do so:
449
450           use HTML::Toc;
451           use HTML::TocInsertor;
452
453           my $toc1        = HTML::Toc->new();
454           my $toc2        = HTML::Toc->new();
455           my $tocInsertor = HTML::TocInsertor->new();
456
457           $toc2->setOptions({
458              'tokenToToc'   => [{
459                 'groupId'    => 'image',
460                 'tokenBegin' => '<img alt=@>'
461              }],
462           });
463           $tocInsertor->insertIntoFile([$toc1, $toc2], $filename);
464
465       And the output will be:
466
467           <body>
468           <!-- Table of Contents generated by Perl - HTML::Toc -->
469           <ul>
470              <li><a href="#h-1">Header One</a>
471                 <ul>
472                    <li><a href="#h-1.1">Paragraph One</a></li>
473                 </ul>
474              </li>
475           </ul>
476           <!-- End of generated Table of Contents -->
477
478           <!-- Table of Contents generated by Perl - HTML::Toc -->
479           <ul>
480              <li><a href="#image-1">First picture</a>
481              <li><a href="#image-2">Second picture</a>
482           </ul>
483           <!-- End of generated Table of Contents -->
484
485              <h1><a name="h-1"></a>Header One</h1>
486              <a name="image-1"></a><img src="test1.gif" alt="First picture"/>
487              <h2><a name="h-1.1"></a>Paragraph One</h2>
488              <a name="image-2"></a><img src="test2.gif" alt="Second picture"/>
489           </body>
490
491   Generate multiple groups in one ToC
492       You may want to generate a ToC consisting of multiple ToC groups.
493
494       Specify an additional 'Appendix' group
495
496       Suppose you want to generate a ToC with one group for the normal
497       headings, and one group for the appendix headings, using this source
498       file:
499
500           <body>
501              <h1>Chapter</h1>
502              <h2>Paragraph</h2>
503              <h3>Subparagraph</h3>
504              <h1>Chapter</h1>
505              <h1 class="appendix">Appendix Chapter</h1>
506              <h2 class="appendix">Appendix Paragraph</h2>
507           </body>
508
509       With the code underneath:
510
511           use HTML::Toc;
512           use HTML::TocInsertor;
513
514           my $toc         = HTML::Toc->new();
515           my $tocInsertor = HTML::TocInsertor->new();
516
517           $toc->setOptions({
518              'tokenToToc' => [{
519                    'tokenBegin' => '<h1 class="-appendix">'
520                 }, {
521                    'tokenBegin' => '<h2 class="-appendix">',
522                    'level'      => 2
523                 }, {
524                    'groupId'    => 'appendix',
525                    'tokenBegin' => '<h1 class="appendix">',
526                 }, {
527                    'groupId'    => 'appendix',
528                    'tokenBegin' => '<h2 class="appendix">',
529                    'level'      => 2
530                 }]
531           });
532           $tocInsertor->insertIntoFile($toc, $filename);
533
534       the output will be:
535
536           <body>
537           <!-- Table of Contents generated by Perl - HTML::Toc -->
538           <ul>
539              <li><a href="#h-1">Chapter</a>
540                 <ul>
541                    <li><a href="#h-1.1">Paragraph</a></li>
542                 </ul>
543              </li>
544              <li><a href="#h-2">Chapter</a></li>
545           </ul>
546           <ul>
547              <li><a href="#appendix-1">Appendix Chapter</a>
548                 <ul>
549                    <li><a href="#appendix-1.1">Appendix Paragraph</a></li>
550                 </ul>
551              </li>
552           </ul>
553           <!-- End of generated Table of Contents -->
554
555              <h1><a name="h-1"></a>Chapter</h1>
556              <h2><a name="h-1.1"></a>Paragraph</h2>
557              <h3>Subparagraph</h3>
558              <h1><a name="h-2"></a>Chapter</h1>
559              <h1 class="appendix"><a name="appendix-1"></a>Appendix Chapter</h1>
560              <h2 class="appendix"><a name="appendix-1.1"></a>Appendix Paragraph</h2>
561           </body>
562
563       Specify an additional 'Part' group
564
565       Suppose you want to generate a ToC of a document which is divided in
566       multiple parts like this file underneath:
567
568           <body>
569              <h1 class="part">First Part</h1>
570              <h1>Chapter</h1>
571              <h2>Paragraph</h2>
572              <h1 class="part">Second Part</h1>
573              <h1>Chapter</h1>
574              <h2>Paragraph</h2>
575           </body>
576
577       With the code underneath:
578
579           use HTML::Toc;
580           use HTML::TocInsertor;
581
582           my $toc         = HTML::Toc->new();
583           my $tocInsertor = HTML::TocInsertor->new();
584
585           $toc->setOptions({
586              'doNumberToken'    => 1,
587              'tokenToToc' => [{
588                    'tokenBegin' => '<h1 class="-part">'
589                 }, {
590                    'tokenBegin' => '<h2 class="-part">',
591                    'level'      => 2,
592                 }, {
593                    'groupId'        => 'part',
594                    'tokenBegin'     => '<h1 class="part">',
595                    'level'          => 1,
596                    'doNumberToken'  => 1,
597                    'numberingStyle' => 'upper-alpha'
598                 }]
599           });
600           $tocInsertor->insertIntoFile($toc, $filename);
601
602       the output will be:
603
604           <body>
605           <!-- Table of Contents generated by Perl - HTML::Toc -->
606           <ul>
607              <li><a href="#part-A">First Part</a></li>
608           </ul>
609           <ul>
610              <li><a href="#h-1">Chapter</a>
611                 <ul>
612                    <li><a href="#h-1.1">Paragraph</a></li>
613                 </ul>
614              </li>
615           </ul>
616           <ul>
617              <li><a href="#part-B">Second Part</a></li>
618           </ul>
619           <ul>
620              <li><a href="#h-2">Chapter</a>
621                 <ul>
622                    <li><a href="#h-2.1">Paragraph</a></li>
623                 </ul>
624              </li>
625           </ul>
626           <!-- End of generated Table of Contents -->
627
628              <h1 class="part"><a name="part-A"></a>A &nbsp;First Part</h1>
629              <h1><a name="h-1"></a>Chapter</h1>
630              <h2><a name="h-1.1"></a>Paragraph</h2>
631              <h1 class="part"><a name="part-B"></a>B &nbsp;Second Part</h1>
632              <h1><a name="h-2"></a>Chapter</h1>
633              <h2><a name="h-2.1"></a>Paragraph</h2>
634           </body>
635
636   Number ToC entries
637       By default, the generated ToC will list its entries unnumbered.  If you
638       want to number the ToC entries, two options are available.  Either you
639       can specify a numbered list by modifying templateLevelBegin and
640       templateLevelEnd.  Or when the ToC isn't a simple numbered list, you
641       can use the numbers generated by HTML::TocGenerator.
642
643       Specify numbered list
644
645       By modifying templateLevelBegin and templateLevelEnd you can specify a
646       numbered ToC:
647
648           use HTML::Toc;
649           use HTML::TocGenerator;
650
651           my $toc          = HTML::Toc->new();
652           my $tocGenerator = HTML::TocGenerator->new();
653
654           $toc->setOptions({
655               'templateLevelBegin' => '"<ol>\n"',
656               'templateLevelEnd'   => '"</ol>\n"',
657           });
658           $tocGenerator->generateFromFile($toc, 'index.htm');
659           print $toc->format();
660
661       For instance with the original file containing:
662
663           <body>
664               <h1>Chapter</h1>
665               <h2>Paragraph</h2>
666           </body>
667
668       The formatted ToC now will contain "ol" instead of "ul" tags:
669
670           <!-- Table of Contents generated by Perl - HTML::Toc -->
671           <ol>
672              <li><a href="#h-1">Chapter</a>
673                 <ol>
674                    <li><a href="#h-1.1">Paragraph</a></li>
675                 </ol>
676              </li>
677           </ol>
678           <!-- End of generated Table of Contents -->
679
680       See also: Using CSS for ToC formatting.
681
682       Use generated numbers
683
684       Instead of using the HTML ordered list (OL), it's also possible to use
685       the generated numbers to number to ToC nodes.  This can be done by
686       modifying templateLevel:
687
688           use HTML::Toc;
689           use HTML::TocGenerator;
690
691           my $toc          = HTML::Toc->new();
692           my $tocGenerator = HTML::TocGenerator->new();
693
694           $toc->setOptions({
695              'templateLevel' => '"<li>$node &nbsp;$text"',
696           });
697           $tocGenerator->generateFromFile($toc, 'index.htm');
698           print $toc->format();
699
700       For instance with the original file containing:
701
702           <body>
703               <h1>Chapter</h1>
704               <h2>Paragraph</h2>
705           </body>
706
707       The formatted ToC now will have the node numbers hard-coded:
708
709           <!-- Table of Contents generated by Perl - HTML::Toc -->
710           <ul>
711              <li>1 &nbsp;<a href=#h-1>Chapter</a>
712                 <ul>
713                    <li>1.1 &nbsp;<a href=#h-1.1>Paragraph</a></li>
714                 </ul>
715              </li>
716           </ul>
717           <!-- End of generated Table of Contents -->
718
719       See also: Using CSS for ToC formatting.
720
721   Using CSS for ToC formatting
722       Suppose you want to display a ToC with upper-alpha numbered appendix
723       headings.  To accomplish this, you can specify a CSS style within the
724       source document:
725
726           <html>
727           <head>
728              <style type="text/css">
729                 ol.toc_appendix1 { list-style-type: upper-alpha }
730              </style>
731           </head>
732           <body>
733              <h1>Appendix</h1>
734              <h2>Appendix Paragraph</h2>
735              <h1>Appendix</h1>
736              <h2>Appendix Paragraph</h2>
737           </body>
738           </html>
739
740       Here's the code:
741
742           my $toc          = new HTML::Toc;
743           my $tocInsertor  = new HTML::TocInsertor;
744
745           $toc->setOptions({
746              'templateLevelBegin'   => '"<ol class=toc_$groupId$level>\n"',
747              'templateLevelEnd'     => '"</ol>\n"',
748              'doNumberToken'        => 1,
749              'tokenToToc' => [{
750                    'groupId'        => 'appendix',
751                    'tokenBegin'     => '<h1>',
752                    'numberingStyle' => 'upper-alpha'
753                 }, {
754                    'groupId'        => 'appendix',
755                    'tokenBegin'     => '<h2>',
756                    'level'          => 2,
757                }]
758           });
759           $tocInsertor->insertIntoFile($toc, $filename);
760
761       Which whill result in the following output:
762
763           <html>
764           <head>
765              <style type="text/css">
766                 ol.toc_appendix1 { list-style-type: upper-alpha }
767              </style>
768           </head>
769           <body>
770           <!-- Table of Contents generated by Perl - HTML::Toc -->
771           <ol class="toc_appendix1">
772              <li><a href="#appendix-A">Appendix</a>
773                 <ol class="toc_appendix2">
774                    <li><a href="#appendix-A.1">Appendix Paragraph</a></li>
775                 </ol>
776              </li>
777              <li><a href="#appendix-B">Appendix</a>
778                 <ol class="toc_appendix2">
779                    <li><a href="#appendix-B.1">Appendix Paragraph</a></li>
780                 </ol>
781              </li>
782           </ol>
783           <!-- End of generated Table of Contents -->
784
785              <h1><a name="appendix-A"></a>A &nbsp;Appendix</h1>
786              <h2><a name="appendix-A.1"></a>A.1 &nbsp;Appendix Paragraph</h2>
787              <h1><a name="appendix-B"></a>B &nbsp;Appendix</h1>
788              <h2><a name="appendix-B.1"></a>B.1 &nbsp;Appendix Paragraph</h2>
789           </body>
790           </html>
791
792   Creating site map
793       Suppose you want to generate a table of contents of the <title> tags of
794       the files in the following directory structure:
795
796           path               file
797
798           .                  index.htm, <title>Main</title>
799           |- SubDir1         index.htm, <title>Sub1</title>
800           |  |- SubSubDir1   index.htm, <title>SubSub1</title>
801           |
802           |- SubDir2         index.htm, <title>Sub2</title>
803           |  |- SubSubDir1   index.htm, <title>SubSub1</title>
804           |  |- SubSubDir2   index.htm, <title>SubSub2</title>
805           |
806           |- SubDir3         index.htm, <title>Sub3</title>
807
808       By specifying 'fileSpec' which determine how many slashes (/) each file
809       may contain for a specific level:
810
811           use HTML::Toc;
812           use HTML::TocGenerator;
813           use File::Find;
814
815           my $toc          = HTML::Toc->new;
816           my $tocGenerator = HTML::TocGenerator->new;
817           my @fileList;
818
819           sub wanted {
820                 # Add file to 'fileList' if extension matches '.htm'
821              push (@fileList, $File::Find::name) if (m/\.htm$/);
822           }
823
824           $toc->setOptions({
825              'doLinkToFile'       => 1,
826              'templateAnchorName' => '""',
827              'templateAnchorHref' => '"<a href=$file"."#".$groupId.$level.">"',
828              'doLinkTocToToken'   => 1,
829              'tokenToToc'         => [{
830                 'groupId'         => 'dir',
831                 'level'           => 1,
832                 'tokenBegin'      => '<title>',
833                 'tokenEnd'        => '</title>',
834                 'fileSpec'        => '\./[^/]+$'
835              }, {
836                 'groupId'         => 'dir',
837                 'level'           => 2,
838                 'tokenBegin'      => '<title>',
839                 'tokenEnd'        => '</title>',
840                 'fileSpec'        => '\./[^/]+?/[^/]+$'
841              }, {
842                 'groupId'         => 'dir',
843                 'level'           => 3,
844                 'tokenBegin'      => '<title>',
845                 'tokenEnd'        => '</title>',
846                 'fileSpec'        => '\./[^/]+?/[^/]+?/[^/]+$'
847              }]
848           });
849
850              # Traverse directory structure
851           find({wanted => \&wanted, no_chdir => 1}, '.');
852              # Generate ToC of case-insensitively sorted file list
853           $tocGenerator->extendFromFile(
854              $toc, [sort {uc($a) cmp uc($b)} @fileList]
855           );
856           print $toc->format();
857
858       the following ToC will be generated:
859
860           <!-- Table of Contents generated by Perl - HTML::Toc -->
861           <ul>
862              <li><a href="./index.htm#">Main</a>
863                 <ul>
864                    <li><a href="./SubDir1/index.htm#">Sub1</a>
865                       <ul>
866                          <li><a href="./SubDir1/SubSubDir1/index.htm#">SubSub1</a></li>
867                       </ul>
868                    </li>
869                    <li><a href="./SubDir2/index.htm#">Sub2</a>
870                       <ul>
871                          <li><a href="./SubDir2/SubSubDir1/index.htm#">SubSub1</a></li>
872                          <li><a href="./SubDir2/SubSubDir2/index.htm#">SubSub2</a></li>
873                       </ul>
874                    </li>
875                    <li><a href="./SubDir3/index.htm#">Sub3</a></li>
876                 </ul>
877              </li>
878           </ul>
879           <!-- End of generated Table of Contents -->
880

Methods

882   HTML::Toc::clear()
883           syntax:  $toc->clear()
884           returns: --
885
886       Clear the ToC.
887
888   HTML::Toc::format()
889           syntax:  $scalar = $toc->format()
890           returns: Formatted ToC.
891
892       Format tokenized ToC.
893
894   HTML::TocGenerator::extend()
895           syntax:  $tocGenerator->extend($toc, $string [, $options])
896           args:    - $toc:     (reference to array of) HTML::Toc object(s) to extend
897                    - $string:  string to retrieve ToC from
898                    - $options: hash reference containing generator options.
899
900       Extend ToC from specified string.  For available options, see Parser
901       Options
902
903   HTML::TocGenerator::extendFromFile()
904           syntax:  $tocGenerator->extendFromFile($toc, $filename [, $options])
905           args:    - $toc:      (reference to array of) HTML::Toc object(s) to extend
906                    - $filename: (reference to array of) file(s) to extend ToC from
907                    - $options:  hash reference containing generator options.
908
909       Extend ToC from specified file.  For available options, see Parser
910       Options.  For an example, see "Extend an existing ToC".
911
912   HTML::TocGenerator::generate()
913           syntax:  $tocGenerator->generate($toc, $string [, $options])
914           args:    - $toc:     (reference to array of) HTML::Toc object(s) to generate
915                    - $string:  string to retrieve ToC from
916                    - $options: hash reference containing generator options.
917
918       Generate ToC from specified string.  Before generating, the ToC will be
919       cleared.  For extending an existing ToC, use the
920       HTML::TocGenerator::extend() method.  For available options, see Parser
921       Options.
922
923   HTML::TocGenerator::generateFromFile()
924           syntax:  $tocGenerator->generateFromFile($toc, $filename [, $options])
925           args:    - $toc:      (reference to array of) HTML::Toc object(s) to
926                                 generate
927                    - $filename: (reference to array of) file(s) to generate ToC from
928                    - $options:  hash reference containing generator options.
929
930       Generate ToC from specified file.  Before generating, the ToC will be
931       cleared.  For extending an extisting ToC, use the
932       HTML::TocGenerator::extendFromFile() method.  For available options,
933       see Parser Options.
934
935   HTML::TocInsertor::insert()
936           syntax:  $tocInsertor->insert($toc, $string [, $options])
937           args:    - $toc:     (reference to array of) HTML::Toc object(s) to insert
938                    - $string:  string to insert ToC in
939                    - $options: hash reference containing insertor options.
940
941       Generate ToC from specified string.  The string and the generated ToC
942       are printed to standard output.  For available options, see Parser
943       Options.
944
945       NOTE: To actually insert the ToC in the string, use the output option
946       to specify a scalar reference to insert the ToC into.  See Insert into
947       string for an example.
948
949   HTML::TocInsertor::insertIntoFile()
950           syntax:  $tocInsertor->insertIntoFile($toc, $filename [, $options])
951           args:    - $toc:      (reference to array of) HTML::Toc object(s) to insert
952                    - $filename: (reference to array of) file(s) to insert ToC in
953                    - $options:  hash reference containing insertor options.
954
955       Insert ToC into specified file.  For available options, see Parser
956       Options.
957
958   HTML::TocUpdator::insert()
959           syntax:  $tocUpdator->insert($toc, $string [, $options])
960           args:    - $toc:     (reference to array of) HTML::Toc object(s) to insert
961                    - $string:  string to insert ToC in
962                    - $options: hash reference containing updator options.
963
964       Insert ToC into specified string.  Differs from
965       HTML::TocInsertor::insert() in that inserted text will be surrounded
966       with update tokens in order for "HTML::TocUpdator" to be able to update
967       this text the next time an update is issued.  See also: Update options.
968
969   HTML::TocUpdator::insertIntoFile()
970           syntax:  $tocUpdator->insertIntoFile($toc, $filename [, $options])
971           args:    - $toc:      (reference to array of) HTML::Toc object(s) to insert
972                    - $filename: (reference to array of) file(s) to insert ToC in
973                    - $options:  hash reference containing updator options.
974
975       Insert ToC into specified file.  Differs from
976       HTML::TocInsertor::insert() in that inserted text will be surrounded
977       with update tokens in order for "HTML::TocUpdator" to be able to update
978       this text the next time an update is issued.  For updator options, see
979       Update options.
980
981   HTML::TocUpdator::update()
982           syntax:  $tocUpdator->update($toc, $string [, $options])
983           args:    - $toc:     (reference to array of) HTML::Toc object(s) to insert
984                    - $string:  string to update ToC in
985                    - $options: hash reference containing updator options.
986
987       Update ToC within specified string.  For updator options, see Update
988       options.
989
990   HTML::TocUpdator::updateFile()
991           syntax:  $tocUpdator->updateFile($toc, $filename [, $options])
992           args:    - $toc:      (reference to array of) HTML::Toc object(s) to insert
993                    - $filename: (reference to array of) file(s) to update ToC in
994                    - $options:  hash reference containing updator options.
995
996       Update ToC of specified file.  For updator options, see Update options.
997

Parser Options

999       When generating a ToC, additional options may be specified which
1000       influence the way the ToCs are generated using either "TocGenerator",
1001       "TocInsertor" or "TocUpdator".  The options must be specified as a hash
1002       reference.  For example:
1003
1004           $tocGenerator->generateFromFile($toc, $filename, {doUseGroupsGlobal => 1});
1005
1006       Available options are:
1007
1008       ·   doGenerateToc
1009
1010       ·   doUseGroupsGlobal
1011
1012       ·   output
1013
1014       ·   outputFile
1015
1016   doGenerateToc
1017           syntax:         [0|1]
1018           default:        1
1019           applicable to:  TocInsertor, TocUpdator
1020
1021       True (1) if ToC must be generated.  False (0) if ToC must be inserted
1022       only.
1023
1024   doUseGroupsGlobal
1025           syntax:         [0|1]
1026           default:        0
1027           applicable to:  TocGenerator, TocInsertor, TocUpdator
1028
1029       True (1) if group levels must be used globally accross ToCs.  False (0)
1030       if not.  This option only makes sense when an array of ToCs is
1031       specified.  For example, suppose you want to generate two ToCs, one ToC
1032       for 'h1' tokens and one ToC for 'h2' tokens, of the file 'index.htm':
1033
1034           <h1>Chapter</h1>
1035           <h2>Paragraph</h2>
1036
1037       Using the default setting of 'doUseGroupsGlobal' => 0:
1038
1039           use HTML::Toc;
1040           use HTML::TocGenerator;
1041
1042           my $toc1         = HTML::Toc->new();
1043           my $toc2         = HTML::Toc->new();
1044           my $tocGenerator = HTML::TocGenerator->new();
1045
1046           $toc1->setOptions({
1047              'header'     => '',
1048              'footer'     => '',
1049              'tokenToToc' => [{'tokenBegin' => '<h1>'}]
1050           });
1051           $toc2->setOptions({
1052              'header'     => '',
1053              'footer'     => '',
1054              'tokenToToc' => [{'tokenBegin' => '<h2>'}]
1055           });
1056           $tocGenerator->generateFromFile([$toc1, $toc2], 'index.htm');
1057           print $toc1->format() . "\n\n" . $toc2->format();
1058
1059       the output will be:
1060
1061           <ul>
1062              <li><a href=#h-1>Chapter</a>
1063           </ul>
1064
1065           <ul>
1066              <li><a href=#h-1>Paragraph</a>
1067           </ul>
1068
1069       Each ToC will use its own numbering scheme.  Now if '"doUseGroupsGlobal
1070       = 1"' is specified:
1071
1072           $tocGenerator->generateFromFile(
1073              [$toc1, $toc2], 'index.htm', {'doUseGroupsGlobal' => 1}
1074           );
1075
1076       the output will be:
1077
1078           <ul>
1079              <li><a href=#h-1>Chapter</a>
1080           </ul>
1081
1082           <ul>
1083              <li><a href=#h-2>Paragraph</a>
1084           </ul>
1085
1086       using a global numbering scheme for all ToCs.
1087
1088   output
1089           syntax:         reference to scalar
1090           default:        none
1091           applicable to:  TocInsertor, TocUpdator
1092
1093       Reference to scalar where the output must be stored in.
1094
1095   outputFile
1096           syntax:         scalar
1097           default:        none
1098           applicable to:  TocInsertor, TocUpdator
1099
1100       Filename to write output to.  If no filename is specified, output will
1101       be written to standard output.
1102

HTML::Toc Options

1104       The "HTML::Toc" options can be grouped in the following categories:
1105
1106       ·   Generate options
1107
1108       ·   Insert options
1109
1110       ·   Update options
1111
1112       ·   Format options
1113
1114       The ToC options must be specified using the 'setOptions' method.  For
1115       example:
1116
1117           my $toc = new HTML::Toc;
1118
1119           $toc->setOptions({
1120              'doNumberToken' => 1,
1121              'footer'        => '<!-- End Of ToC -->'
1122              'tokenToToc'    => [{
1123                 'level'          => 1,
1124                 'tokenBegin'     => '<h1>',
1125                 'numberingStyle' => 'lower-alpha'
1126              }]
1127           });
1128
1129   Generate options
1130       ·   Token groups
1131
1132           ·   tokenToToc
1133
1134               ·   doNumberToken
1135
1136               ·   fileSpec
1137
1138               ·   groupId
1139
1140               ·   level
1141
1142               ·   tokenBegin
1143
1144               ·   tokenEnd
1145
1146               ·   numberingStyle
1147
1148           ·   groupToToc
1149
1150           ·   levelToToc
1151
1152       ·   Numbering tokens
1153
1154           ·   doNumberToken
1155
1156           ·   numberingStyle
1157
1158           ·   templateTokenNumber
1159
1160       ·   Miscellaneous
1161
1162           ·   attributeToExcludeToken
1163
1164           ·   attributeToTocToken
1165
1166           ·   groupToToc
1167
1168           ·   levelToToc
1169
1170       ·   Linking ToC to tokens
1171
1172           ·   doLinkToToken
1173
1174           ·   doLinkToFile
1175
1176           ·   doLinkToId
1177
1178           ·   templateAnchorName
1179
1180           ·   templateAnchorHrefBegin
1181
1182           ·   templateAnchorHrefEnd
1183
1184           ·   templateAnchorNameBegin
1185
1186           ·   templateAnchorNameEnd
1187
1188   Insert options
1189       ·   insertionPoint
1190
1191   Update options
1192       ·   tokenUpdateBeginAnchorName
1193
1194       ·   tokenUpdateEndAnchorName
1195
1196       ·   tokenUpdateBeginToc
1197
1198       ·   tokenUpdateEndToc
1199
1200       ·   tokenUpdateBeginNumber
1201
1202       ·   tokenUpdateEndNumber
1203
1204   Format options
1205       ·   doSingleStepLevel
1206
1207       ·   doNestGroup
1208
1209       ·   footer
1210
1211       ·   groupToToc
1212
1213       ·   header
1214
1215       ·   levelIndent
1216
1217       ·   levelToToc
1218
1219       ·   templateLevel
1220
1221       ·   templateLevelClose
1222
1223       ·   templateLevelBegin
1224
1225       ·   templateLevelEnd
1226

HTML::Toc Options Reference

1228   attributeToExcludeToken
1229           syntax:  $scalar
1230           default: '-'
1231
1232       Token which marks an attribute value in a tokenBegin or insertionPoint
1233       token as an attribute value a token should not have to be marked as a
1234       ToC token.  See also: Using attribute value as ToC entry.
1235
1236   attributeToTocToken
1237           syntax:  $scalar
1238           default: '@'
1239
1240       Token which marks an attribute in a tokenBegin token as an attribute
1241       which must be used as ToC text.  See also: Using attribute value as ToC
1242       entry.
1243
1244   doLinkToToken
1245           syntax:  [0|1]
1246           default: 1
1247
1248       True (1) if ToC must be linked to tokens, False (0) if not.  Note that
1249       'HTML::TocInsertor' must be used to do the actual insertion of the
1250       anchor name within the source data.
1251
1252   doLinkToFile
1253           syntax:  [0|1]
1254           default: 0
1255
1256       True (1) if ToC must be linked to file, False (0) if not.  In effect
1257       only when doLinkToToken equals True (1) and templateAnchorHrefBegin
1258       isn't specified.
1259
1260   doLinkToId
1261           syntax:  [0|1]
1262           default: 0
1263
1264       True (1) if ToC must be linked to tokens by using token ids.  False (0)
1265       if ToC must be linked to tokens by using anchor names.
1266
1267   doNestGroup
1268           syntax:  [0|1]
1269           default: 0
1270
1271       True (1) if groups must be nested in the formatted ToC, False (0) if
1272       not.  In effect only when multiple groups are specified within the
1273       tokenToToc setting.  For an example, see Generate multiple groups in
1274       one ToC.
1275
1276   doNumberToken
1277           syntax:  [0|1]
1278           default: 0
1279
1280       True (1) if tokens which are used for the ToC generation must be
1281       numbered.  This option may be specified both as a global ToC option or
1282       within a tokenToToc group.  When specified within a "tokenToToc"
1283       option, the "doNumberToken" applies to that group only.  For an
1284       example, see Specify an additional 'Part' group.
1285
1286   doSingleStepLevel
1287           syntax:  [0|1]
1288           default: 1
1289
1290       True (1) if levels of a formatted ToC must advance one level at a time.
1291       For example, when generating a ToC of a file with a missing 'h2':
1292
1293           <h1>Chapter</h1>
1294           <h3>Paragraph</h3>
1295
1296       By default, an empty indentation level will be inserted in the ToC:
1297
1298           <!-- Table of Contents generated by Perl - HTML::Toc -->
1299           <ul>
1300              <li><a href=#h-1>Header 1</a>
1301              <ul>
1302                 <ul>
1303                    <li><a href=#h-1.0.1>Header 3</a>
1304                 </ul>
1305              </ul>
1306           </ul>
1307           <!-- End of generated Table of Contents -->
1308
1309       After specifying:
1310
1311           $toc->setOptions({'doSingleStepLevel' => 0});
1312
1313       the ToC will not have an indentation level inserted for level 2:
1314
1315           <!-- Table of Contents generated by Perl - HTML::Toc -->
1316           <ul>
1317              <li><a href=#h-1>Header 1</a>
1318              <ul>
1319                    <li><a href=#h-1.0.1>Header 3</a>
1320              </ul>
1321           </ul>
1322           <!-- End of generated Table of Contents -->
1323
1324   fileSpec
1325           syntax:  <regexp>
1326           default: undef
1327
1328       Specifies which files should match the current level.  Valid only if
1329       doLinkToFile equals 1.  For an example, see Site map.
1330
1331   footer
1332           syntax:  $scalar
1333           default: "\n<!-- End of generated Table of Contents -->\n"
1334
1335       String to output at end of ToC.
1336
1337   groupId
1338           syntax:  $scalar
1339           default: 'h'
1340
1341       Sets the group id attribute of a tokenGroup.  With this attribute it's
1342       possible to divide the ToC into multiple groups.  Each group has its
1343       own numbering scheme.  For example, to generate a ToC of both normal
1344       headings and 'appendix' headings, specify the following ToC settings:
1345
1346           $toc->setOptions({
1347              'tokenToToc' => [{
1348                     'tokenBegin' => '<h1 class=-appendix>'
1349                  }, {
1350                     'groupId' => 'appendix',
1351                     'tokenBegin' => '<h1 class=appendix>'
1352              }]
1353           });
1354
1355   groupToToc
1356           syntax:  <regexp>
1357           default: '.*'
1358
1359       Determines which groups to use for generating the ToC.  For example, to
1360       create a ToC for groups [a-b] only, specify:
1361
1362           'groupToToc => '[a-b]'
1363
1364       This option is evaluated during both ToC generation and ToC formatting.
1365       This enables you to generate a ToC of all groups, but - after
1366       generating - format only specified groups:
1367
1368           $toc->setOptions({'groupToToc' => '.*'});
1369           $tocGenerator->generateToc($toc, ...);
1370               # Get ToC of all groups
1371           $fullToc = $toc->format();
1372               # Get ToC of 'appendix' group only
1373           $toc->setOptions({'groupToToc' => 'appendix'});
1374           $appendixToc = $toc->format();
1375
1376   header
1377           syntax:  $scalar
1378           default: "\n<!-- Table of Contents generated by Perl - HTML::Toc -->\n"
1379
1380       String to output at begin of ToC.
1381
1382   insertionPoint
1383           syntax:  [<before|after|replace>] <token>
1384           default: 'after <body>'
1385           token:   <[/]tag{ attribute=[-|@]<regexp>}> |
1386                    <text regexp> |
1387                    <declaration regexp> |
1388                    <comment regexp>
1389
1390       Determines the point within the source, where the ToC should be
1391       inserted.  When specifying a start tag as the insertion point token,
1392       attributes to be included may be specified as well.  Note that the
1393       attribute value must be specified as a regular expression.  For
1394       example, to specify the "<h1 class=header"> tag as insertion point:
1395
1396           '<h1 class=^header$>'
1397
1398       Examples of valid 'insertionPoint' tokens are:
1399
1400           '<h1>'
1401           '</h1>'
1402           '<!-- ToC -->'
1403           '<!ToC>'
1404           'ToC will be placed here'
1405
1406       It is also possible to specify attributes to exclude, by prefixing the
1407       value with an attributeToExcludeToken, default a minus sign (-).  For
1408       example, to specify the "<h1"> tag as insertion point, excluding all
1409       "<h1 class=header"> tags:
1410
1411           '<h1 class=-^header$>'
1412
1413       See also tokenBegin.
1414
1415   level
1416           syntax:  number
1417           default: 1
1418
1419       Number which identifies at which level the tokengroup should be
1420       incorporated into the ToC.  See also: tokenToToc.
1421
1422   levelIndent
1423           syntax:  number
1424           default: 3
1425
1426       Sets the number of spaces each level will be indented, when formatting
1427       the ToC.
1428
1429   levelToToc
1430           syntax:  <regexp>
1431           default: '.*'
1432
1433       Determines which group levels to use for generating the ToC.  For
1434       example, to create a ToC for levels 1-2 only, specify:
1435
1436           'levelToToc => '[1-2]'
1437
1438       This option is evaluated during both ToC generation and ToC formatting.
1439       This enables you to generate a ToC of all levels, but - after
1440       generating - retrieve only specified levels:
1441
1442           $toc->setOptions({'levelToToc' => '.*'});
1443           $tocGenerator->generateToc($toc, ...);
1444               # Get ToC of all levels
1445           $fullToc = $toc->getToc();
1446               # Get ToC of level 1 only
1447           $toc->setOptions({'levelToToc' => '1'});
1448           $level1Toc = $toc->getToc();
1449
1450   numberingStyle
1451           syntax:  [decimal|lower-alpha|upper-alpha|lower-roman|upper-roman]}
1452           default: decimal
1453
1454       Determines which numbering style to use for a token group when
1455       doLinkToToken is set to True (1).  When specified as a main ToC option,
1456       the setting will be the default for all groups.  When specified within
1457       a tokengroup, this setting will override any default for that
1458       particular tokengroup, e.g.:
1459
1460           $toc->setOptions({
1461              'doNumberToken' => 1,
1462              'tokenToToc' => [{
1463                 'level'          => 1,
1464                 'tokenBegin'     => '<h1>',
1465                 'numberingStyle' => 'lower-alpha'
1466              }]
1467           });
1468
1469       If "roman" style is specified, be sure to have the Roman module
1470       installed, available from
1471       <http://www.perl.com/CPAN/modules/by-module/Roman>.
1472
1473   templateAnchorName
1474           syntax:  <expression|function reference>
1475           default: '$groupId."-".$node'
1476
1477       Anchor name to use when doLinkToToken is set to True (1).  The anchor
1478       name is passed to both templateAnchorHrefBegin and
1479       templateAnchorNameBegin.  The template may be specified as either an
1480       expression or a function reference.  The expression may contain the
1481       following variables:
1482
1483           $file
1484           $groupId
1485           $level
1486           $node
1487           $text      E.g. with "<h1><b>Intro</b></h1>", $text = "Intro"
1488           $children  Text, including HTML child elements.
1489               E.g. with "<h1><b>Intro</b></h1>", $children = "<b>Intro</b>"
1490
1491       If "templateAnchorName" is a function reference to a function returning
1492       the anchor, like in:
1493
1494           $toc->setOptions({'templateAnchorName' => \&assembleAnchorName});
1495
1496       the function will be called with the following arguments:
1497
1498           $anchorName = assembleAnchorName($file, $groupId, $level, $node, $text, $children);
1499
1500   templateAnchorHrefBegin
1501           syntax:  <expression|function reference>
1502           default: '"<a href=#$anchorName>"' or
1503                    '"<a href=$file#$anchorName>"',
1504                    depending on 'doLinkToFile' being 0 or 1 respectively.
1505
1506       Anchor reference begin token to use when doLinkToToken is set to True
1507       (1).  The template may be specified as either an expression or a
1508       function reference.  The expression may contain the following
1509       variables:
1510
1511           $file
1512           $groupId
1513           $level
1514           $node
1515           $anchorName
1516
1517       If "templateAnchorHrefBegin" is a function reference to a function
1518       returning the anchor, like in:
1519
1520           $toc->setOptions({'templateAnchorHrefBegin' => \&assembleAnchorHrefBegin});
1521
1522       the function will be called with the following arguments:
1523
1524           $anchorHrefBegin = &assembleAnchorHrefBegin(
1525              $file, $groupId, $level, $node, $anchorName
1526           );
1527
1528       See also: templateAnchorName, templateAnchorHrefEnd.
1529
1530   templateAnchorHrefEnd
1531           syntax:  <expression|function reference>
1532           default: '"</a>"'
1533
1534       Anchor reference end token to use when doLinkToToken is set to True
1535       (1).  The template may be specified as either an expression or a
1536       function reference.  If templateAnchorHrefEnd is a function reference
1537       to a function returning the anchor end, like in:
1538
1539           $toc->setOptions({'templateAnchorHrefEnd' => \&assembleAnchorHrefEnd});
1540
1541       the function will be called without arguments:
1542
1543           $anchorHrefEnd = &assembleAnchorHrefEnd;
1544
1545       See also: templateAnchorHrefBegin.
1546
1547   templateAnchorNameBegin
1548           syntax:  <expression|function reference>
1549           default: '"<a name=$anchorName>"'
1550
1551       Anchor name begin token to use when doLinkToToken is set to True (1).
1552       The template may be specified as either an expression or a function
1553       reference.  The expression may contain the following variables:
1554
1555           $file
1556           $groupId
1557           $level
1558           $node
1559           $anchorName
1560
1561       If "templateAnchorNameBegin" is a function reference to a function
1562       returning the anchor name, like in:
1563
1564           $toc->setOptions({'templateAnchorNameBegin' => \&assembleAnchorNameBegin});
1565
1566       the function will be called with the following arguments:
1567
1568           $anchorNameBegin = assembleAnchorNameBegin(
1569               $file, $groupId, $level, $node, $anchorName
1570           );
1571
1572       See also: templateAnchorName, templateAnchorNameEnd.
1573
1574   templateAnchorNameEnd
1575           syntax:  <expression|function reference>
1576           default: '"</a>"'
1577
1578       Anchor name end token to use when doLinkToToken is set to True (1).
1579       The template may be specified as either an expression or a function
1580       reference.  If templateAnchorNameEnd is a function reference to a
1581       function returning the anchor end, like in:
1582
1583           $toc->setOptions({'templateAnchorNameEnd' => \&assembleAnchorNameEnd});
1584
1585       the function will be called without arguments:
1586
1587           $anchorNameEnd = &assembleAnchorNameEnd;
1588
1589       See also: templateAnchorNameBegin.
1590
1591   templateLevel
1592           syntax:  <expression|function reference>
1593           default: '"<li>$text"'
1594
1595       Expression to use when formatting a ToC node.  The template may be
1596       specified as either an expression or a function reference.  The
1597       expression may contain the following variables:
1598
1599           $level
1600           $groupId
1601           $node
1602           $sequenceNr
1603           $text
1604
1605       If "templateLevel" is a function reference to a function returning the
1606       ToC node, like in:
1607
1608           $toc->setOptions({'templateLevel' => \&AssembleTocNode});
1609
1610       the function will be called with the following arguments:
1611
1612           $tocNode = &AssembleTocNode(
1613               $level, $groupId, $node, $sequenceNr, $text
1614           );
1615
1616   templateLevelClose
1617           syntax:  <expression|function reference>
1618           default: '"</li>\n"'
1619
1620       Expression to use when formatting a ToC node.  The template may be
1621       specified as either an expression or a function reference.
1622
1623   templateLevelBegin
1624           syntax:  <expression>
1625           default: '"<ul>\n"'
1626
1627       Expression to use when formatting begin of ToC level.  See
1628       templateLevel for list of available variables to use within the
1629       expression.  For example, to give each ToC level a class name to use
1630       with Cascading Style Sheets (CSS), use the expression:
1631
1632           '"<ul class=\"toc_$groupId$level\">\n"'
1633
1634       which will result in each ToC group given a class name:
1635
1636           <ul class="toc_h1">
1637              <li>Header
1638           </ul>
1639
1640       For an example, see Using CSS for ToC formatting.
1641
1642   templateLevelEnd
1643           syntax:  <expression>
1644           default: '"</ul>\n"'
1645
1646       Expression to use when formatting end of ToC level.  See templateLevel
1647       for a list of available variables to use within the expression.  The
1648       default expression is:
1649
1650           '"</ul>\n"'
1651
1652       For an example, see Using CSS for ToC formatting.
1653
1654   templateTokenNumber
1655           syntax:  <expression|function reference>
1656           default: '"$node &nbsp;"'
1657
1658       Token number to use when doNumberToken equals True (1).  The template
1659       may be specified as either an expression or a function reference.  The
1660       expression has access to the following variables:
1661
1662           $file
1663           $groupId
1664           $groupLevel
1665           $level
1666           $node
1667           $toc
1668
1669       If "templateTokenNumber" is a function reference to a function
1670       returning the token number, like in:
1671
1672           $toc->setOptions({'templateTokenNumber' => \&assembleTokenNumber});
1673
1674       the function will be called with the following arguments:
1675
1676           $number = &assembleTokenNumber(
1677               $node, $groupId, $file, $groupLevel, $level, $toc
1678           );
1679
1680   tokenBegin
1681           syntax:  <token>
1682           default: '<h1>'
1683           token:   <[/]tag{ attribute=[-|@]<regexp>}> |
1684                    <text regexp> |
1685                    <declaration regexp> |
1686                    <comment regexp>
1687
1688       This scalar defines the token that will trigger text to be put into the
1689       ToC.  Any start tag, end tag, comment, declaration or text string can
1690       be specified.  Examples of valid 'tokenBegin' tokens are:
1691
1692           '<h1>'
1693           '</end>'
1694           '<!-- Start ToC entry -->'
1695           '<!Start ToC entry>'
1696           'ToC entry'
1697
1698       When specifying a start tag, attributes to be included may be specified
1699       as well.  Note that the attribute value is used as a regular
1700       expression.  For example, to specify the "<h1 class=header"> tag as
1701       tokenBegin:
1702
1703           '<h1 class=^header$>'
1704
1705       It is also possible to specify attributes to exclude, by prefixing the
1706       value with an attributeToExcludeToken, default a minus sign (-).  For
1707       example, to specify the "<h1"> tag as tokenBegin, excluding all "<h1
1708       class=header"> tags:
1709
1710           '<h1 class=-^header$>'
1711
1712       Also, you can specify here an attribute value which has to be used as
1713       ToC text, by prefixing the value with an attributeToTocToken, default
1714       an at sign (@).  For example, to use the class value as ToC text:
1715
1716           '<h1 class=@>'
1717
1718       See Generate multiple ToCs for an elaborated example using the
1719       "attributeToTocToken" to generate a ToC of image "alt" attribute
1720       values.
1721
1722       See also: tokenEnd, tokenToToc.
1723
1724   tokenEnd
1725           syntax:  $scalar
1726           default: empty string ('') or end tag counterpart of 'tokenBegin' if
1727                    'tokenBegin' is a start tag
1728
1729       The 'tokenEnd' definition applies to the same rules as tokenBegin.
1730
1731       See also: tokenBegin, tokenToToc.
1732
1733   tokenToToc
1734           syntax:  [{array of hashrefs}]
1735           default: [{
1736                       'level'      => 1,
1737                       'tokenBegin' => '<h1>'
1738                    }, {
1739                       'level'      => 2,
1740                       'tokenBegin' => '<h2>'
1741                    }, {
1742                       'level'      => 3,
1743                       'tokenBegin' => '<h3>'
1744                    }, {
1745                       'level'      => 4,
1746                       'tokenBegin' => '<h4>'
1747                    }, {
1748                       'level'      => 5,
1749                       'tokenBegin' => '<h5>'
1750                    }, {
1751                       'level'      => 6,
1752                       'tokenBegin' => '<h6>'
1753                    }]
1754
1755       This hash defines the tokens that must act as ToC entries.  Each
1756       tokengroup may contain a groupId, level, numberingStyle, tokenBegin and
1757       tokenEnd identifier.
1758
1759   tokenUpdateBeginAnchorName
1760           syntax:  <string>
1761           default: '<!-- #BeginTocAnchorNameBegin -->';
1762
1763       This token marks the begin of an anchor name, inserted by
1764       "HTML::TocInsertor".  This option is used by "HTML::TocUpdator".
1765
1766   tokenUpdateEndAnchorName
1767           syntax:  <string>
1768           default: '<!-- #EndTocAnchorName -->';
1769
1770       This option is used by "HTML::TocUpdator", to mark the end of an
1771       inserted anchor name.
1772
1773   tokenUpdateBeginNumber
1774           syntax:  <string>
1775           default: '<!-- #BeginTocNumber -->';
1776
1777       This option is used by "HTML::TocUpdator", to mark the begin of an
1778       inserted number.
1779
1780   tokenUpdateEndNumber
1781           syntax:  <string>
1782           default: '<!-- #EndTocAnchorName -->';
1783
1784       This option is used by "HTML::TocUpdator", to mark the end of an
1785       inserted number.
1786
1787   tokenUpdateBeginToc
1788           syntax:  <string>
1789           default: '<!-- #BeginToc -->';
1790
1791       This option is used by "HTML::TocUpdator", to mark the begin of an
1792       inserted ToC.
1793
1794   tokenUpdateEndToc
1795           syntax:  <string>
1796           default: '<!-- #EndToc -->';
1797
1798       This option is used by "HTML::TocUpdator", to mark the end of an
1799       inserted ToC.
1800

Known issues

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

AUTHOR

1811       Freddy Vulto <"fvulto@gmail.com">
1812
1814       Copyright (c) 2009 Freddy Vulto.  All rights reserved.
1815
1816       This library is free software; you can redistribute it and/or modify it
1817       under the same terms as Perl itself.
1818
1819
1820
1821perl v5.32.0                      2020-07-28                            Toc(3)
Impressum