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 the
153       generated ToC to standard output.  To actually insert the ToC in the
154       string, use the output option to specify a scalar reference to insert
155       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() will
240       also insert the ToC, whether there is a ToC already inserted or not.
241
242   Updating
243       This code will generate a ToC of HTML headings "<h1">.."<h6"> of file
244       "indexToc.htm", and insert or update the ToC after the "<body"> tag at
245       the same time:
246
247           use HTML::Toc;
248           use HTML::TocUpdator;
249
250           my $toc        = HTML::Toc->new();
251           my $tocUpdator = HTML::TocUpdator->new();
252
253           $tocUpdator->updateFile($toc, 'indexToc.htm');
254
255       For example, with "indexToc.htm" containing:
256
257           <html>
258           <body><!-- #BeginToc -->
259           foo
260           <!-- #EndToc -->
261              <!-- #BeginTocAnchorNameBegin -->bar<!-- #EndTocAnchorNameBegin --><h1>
262              Chapter
263              </h1><!-- #BeginTocAnchorNameEnd -->foo<!-- #EndTocAnchorNameEnd -->
264           </body>h
265           </html>
266
267       the output will be:
268
269           <html>
270           <body><!-- #BeginToc -->
271           <!-- Table of Contents generated by Perl - HTML::Toc -->
272           <ul>
273              <li><a href="#h-1"> Chapter </a></li>
274           </ul>
275           <!-- End of generated Table of Contents -->
276           <!-- #EndToc -->
277              <h1><!-- #BeginTocAnchorNameBegin --><a name="h-1"></a><!-- #EndTocAnchorNameBegin -->
278              Chapter
279              </h1>
280           </body>
281           </html>
282
283       All text between the update tokens will be replaced.  So be warned: all
284       manual changes made to text between update tokens will be removed
285       unrecoverable after calling HTML::TocUpdator::update() or
286       HTML::TocUpdator::updateFile().
287
288   Formatting
289       The ToC isn't generated all at once.  There are two stages involved:
290       generating and formatting.  Generating the ToC actually means storing a
291       preliminary ToC in "HTML::Toc->{_toc}".  This preliminary, tokenized
292       ToC has to be turned into something useful by calling
293       "HTML::Toc->format()".  For an example, see paragraph 'Generating'.
294

Advanced

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

Methods

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

Parser Options

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

HTML::Toc Options

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

HTML::Toc Options Reference

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

Known issues

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

AUTHOR

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