1Toc(3) User Contributed Perl Documentation Toc(3)
2
6 HTML::Toc - Generate, insert and update HTML Table of Contents.
7
9 Generate, insert and update HTML Table of Contents (ToC).
10
12 The HTML::Toc consists out of the following packages:
13 HTML::Toc
15 HTML::TocGenerator
16 HTML::TocInsertor
17 HTML::TocUpdator
18 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 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 +---------------------+
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 When generating a ToC you'll have to decide which object you want to
68 use:
69 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 Thus in tabular view, each object is capable of:
79 generating inserting updating
81 ---------------------------------
82 TocGenerator X
83 TocInsertor X X
84 TocUpdator X X X
85 Generating
87 The code underneath will generate a ToC of the HTML headings
88 "<h1">.."<h6"> from a file "index.htm":
89 use HTML::Toc;
91 use HTML::TocGenerator;
92 my $toc = HTML::Toc->new();
94 my $tocGenerator = HTML::TocGenerator->new();
95 $tocGenerator->generateFromFile($toc, 'index.htm');
97 print $toc->format();
98 For example, with "index.htm" containing:
100 <html>
102 <body>
103 <h1>Chapter</h1>
104 </body>
105 </html>
106 the output will be:
108 <!-- 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 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 use HTML::Toc;
121 use HTML::TocInsertor;
122 my $toc = HTML::Toc->new();
124 my $tocInsertor = HTML::TocInsertor->new();
125 $tocInsertor->insertIntoFile($toc, 'index.htm');
127 For example, with "index.htm" containing:
129 <html>
131 <body>
132 <h1>Chapter</h1>
133 </body>
134 </html>
135 the output will be:
137 <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 <h1><a name="h-1"></a>Chapter</h1>
147 </body>
148 </html>
149 Inserting into string
151 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 use HTML::Toc;
158 use HTML::TocInsertor;
159 my $toc = HTML::Toc->new();
161 my $tocInsertor = HTML::TocInsertor->new();
162 $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 Now the output will be:
174 <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 <h1><a name="h-1"></a>Chapter</h1>
184 </body>
185 </html>
186 Inserting with update tokens
188 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 use HTML::Toc;
196 use HTML::TocUpdator;
197 my $toc = HTML::Toc->new();
199 my $tocUpdator = HTML::TocUpdator->new();
200 $tocUpdator->insertIntoFile($toc, 'index.htm');
202 When applying the code above on 'index.htm':
204 <html>
206 <body>
207 <h1>
208 Chapter
209 </h1>
210 </body>
211 </html>
212 the output will contain additional update tokens:
214 <!-- #BeginToc -->
216 <!-- #EndToc -->
217 <!-- #BeginTocAnchorNameBegin -->
218 <!-- #EndTocAnchorNameBegin -->
219 <!-- #BeginTocAnchorNameEnd -->
220 <!-- #EndTocAnchorNameEnd -->
221 around the inserted ToC elements:
223 <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 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 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 use HTML::Toc;
249 use HTML::TocUpdator;
250 my $toc = HTML::Toc->new();
252 my $tocUpdator = HTML::TocUpdator->new();
253 $tocUpdator->updateFile($toc, 'indexToc.htm');
255 For example, with "indexToc.htm" containing:
257 <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 the output will be:
269 <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 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 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
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 preface
303 introduction
304 table of contents
305 table of figures
306 table of tables
307 parts
308 chapters
309 appendixes
310 bibliography
311 is formatted all at once.
313 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 <body>
323 <img src=test1.gif alt="First picture">
324 <img src=test2.gif alt="Second picture">
325 </body>
326 This would be the code:
328 use HTML::Toc;
330 use HTML::TocInsertor;
331 my $toc = HTML::Toc->new();
333 my $tocInsertor = HTML::TocInsertor->new();
334 $toc->setOptions({
336 'tokenToToc' => [{
337 'groupId' => 'image',
338 'tokenBegin' => '<img alt=@>'
339 }],
340 });
341 $tocInsertor->insertIntoFile($toc, $filename);
342 and the output will be:
344 <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 <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 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 Specify an array of files
364 For example, suppose you want to generate a ToC of both "doc1.htm":
366 <body>
368 <h1>Chapter of document 1</h1>
369 </body>
370 and "doc2.htm":
372 <body>
374 <h1>Chapter of document 2</h1>
375 </body>
376 Here's the code to do so by specifying an array of files:
378 use HTML::Toc;
380 use HTML::TocGenerator;
381 my $toc = HTML::Toc->new();
383 my $tocGenerator = HTML::TocGenerator->new();
384 $toc->setOptions({'doLinkToFile' => 1});
386 $tocGenerator->generateFromFile($toc, ['doc1.htm', 'doc2.htm']);
387 print $toc->format();
388 And the output will be:
390 <!-- 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 Extend an existing ToC
399 It's also possible to extend an existing ToC. For example, suppose we
401 want the generate a ToC of file "doc1.htm":
402 <body>
404 <h1>Chapter of document 1</h1>
405 </body>
406 and extend this ToC with text from "doc2.htm":
408 <body>
410 <h1>Chapter of document 2</h1>
411 </body>
412 Here's the code to do so:
414 use HTML::Toc;
416 use HTML::TocGenerator;
417 my $toc = HTML::Toc->new();
419 my $tocGenerator = HTML::TocGenerator->new();
420 $toc->setOptions({'doLinkToFile' => 1});
422 $tocGenerator->generateFromFile($toc, 'doc1.htm');
423 $tocGenerator->extendFromFile($toc, 'doc2.htm');
424 print $toc->format();
425 And the output will be:
427 <!-- 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 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 <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 Here's how you would do so:
449 use HTML::Toc;
451 use HTML::TocInsertor;
452 my $toc1 = HTML::Toc->new();
454 my $toc2 = HTML::Toc->new();
455 my $tocInsertor = HTML::TocInsertor->new();
456 $toc2->setOptions({
458 'tokenToToc' => [{
459 'groupId' => 'image',
460 'tokenBegin' => '<img alt=@>'
461 }],
462 });
463 $tocInsertor->insertIntoFile([$toc1, $toc2], $filename);
464 And the output will be:
466 <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 <!-- 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 <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 Generate multiple groups in one ToC
492 You may want to generate a ToC consisting of multiple ToC groups.
493 Specify an additional 'Appendix' group
495 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 <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 With the code underneath:
510 use HTML::Toc;
512 use HTML::TocInsertor;
513 my $toc = HTML::Toc->new();
515 my $tocInsertor = HTML::TocInsertor->new();
516 $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 the output will be:
535 <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 <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 Specify an additional 'Part' group
564 Suppose you want to generate a ToC of a document which is divided in
566 multiple parts like this file underneath:
567 <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 With the code underneath:
578 use HTML::Toc;
580 use HTML::TocInsertor;
581 my $toc = HTML::Toc->new();
583 my $tocInsertor = HTML::TocInsertor->new();
584 $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 the output will be:
603 <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 <h1 class="part"><a name="part-A"></a>A 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 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 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 Specify numbered list
644 By modifying templateLevelBegin and templateLevelEnd you can specify a
646 numbered ToC:
647 use HTML::Toc;
649 use HTML::TocGenerator;
650 my $toc = HTML::Toc->new();
652 my $tocGenerator = HTML::TocGenerator->new();
653 $toc->setOptions({
655 'templateLevelBegin' => '"<ol>\n"',
656 'templateLevelEnd' => '"</ol>\n"',
657 });
658 $tocGenerator->generateFromFile($toc, 'index.htm');
659 print $toc->format();
660 For instance with the original file containing:
662 <body>
664 <h1>Chapter</h1>
665 <h2>Paragraph</h2>
666 </body>
667 The formatted ToC now will contain "ol" instead of "ul" tags:
669 <!-- 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 See also: Using CSS for ToC formatting.
681 Use generated numbers
683 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 use HTML::Toc;
689 use HTML::TocGenerator;
690 my $toc = HTML::Toc->new();
692 my $tocGenerator = HTML::TocGenerator->new();
693 $toc->setOptions({
695 'templateLevel' => '"<li>$node $text"',
696 });
697 $tocGenerator->generateFromFile($toc, 'index.htm');
698 print $toc->format();
699 For instance with the original file containing:
701 <body>
703 <h1>Chapter</h1>
704 <h2>Paragraph</h2>
705 </body>
706 The formatted ToC now will have the node numbers hard-coded:
708 <!-- Table of Contents generated by Perl - HTML::Toc -->
710 <ul>
711 <li>1 <a href=#h-1>Chapter</a>
712 <ul>
713 <li>1.1 <a href=#h-1.1>Paragraph</a></li>
714 </ul>
715 </li>
716 </ul>
717 <!-- End of generated Table of Contents -->
718 See also: Using CSS for ToC formatting.
720 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 <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 Here's the code:
741 my $toc = new HTML::Toc;
743 my $tocInsertor = new HTML::TocInsertor;
744 $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 Which whill result in the following output:
762 <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 <h1><a name="appendix-A"></a>A Appendix</h1>
786 <h2><a name="appendix-A.1"></a>A.1 Appendix Paragraph</h2>
787 <h1><a name="appendix-B"></a>B Appendix</h1>
788 <h2><a name="appendix-B.1"></a>B.1 Appendix Paragraph</h2>
789 </body>
790 </html>
791 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 path file
797 . 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 By specifying 'fileSpec' which determine how many slashes (/) each file
809 may contain for a specific level:
810 use HTML::Toc;
812 use HTML::TocGenerator;
813 use File::Find;
814 my $toc = HTML::Toc->new;
816 my $tocGenerator = HTML::TocGenerator->new;
817 my @fileList;
818 sub wanted {
820 # Add file to 'fileList' if extension matches '.htm'
821 push (@fileList, $File::Find::name) if (m/\.htm$/);
822 }
823 $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 # 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 the following ToC will be generated:
859 <!-- 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
882 HTML::Toc::clear()
883 syntax: $toc->clear()
884 returns: --
885 Clear the ToC.
887 HTML::Toc::format()
889 syntax: $scalar = $toc->format()
890 returns: Formatted ToC.
891 Format tokenized ToC.
893 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 Extend ToC from specified string. For available options, see Parser
901 Options
902 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 Extend ToC from specified file. For available options, see Parser
910 Options. For an example, see "Extend an existing ToC".
911 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 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 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 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 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 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 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 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 Insert ToC into specified file. For available options, see Parser
956 Options.
957 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 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 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 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 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 Update ToC within specified string. For updator options, see Update
988 options.
989 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 Update ToC of specified file. For updator options, see Update options.
997
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 $tocGenerator->generateFromFile($toc, $filename, {doUseGroupsGlobal => 1});
1005 Available options are:
1007 • doGenerateToc
1009 • doUseGroupsGlobal
1011 • output
1013 • outputFile
1015 doGenerateToc
1017 syntax: [0|1]
1018 default: 1
1019 applicable to: TocInsertor, TocUpdator
1020 True (1) if ToC must be generated. False (0) if ToC must be inserted
1022 only.
1023 doUseGroupsGlobal
1025 syntax: [0|1]
1026 default: 0
1027 applicable to: TocGenerator, TocInsertor, TocUpdator
1028 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 <h1>Chapter</h1>
1035 <h2>Paragraph</h2>
1036 Using the default setting of 'doUseGroupsGlobal' => 0:
1038 use HTML::Toc;
1040 use HTML::TocGenerator;
1041 my $toc1 = HTML::Toc->new();
1043 my $toc2 = HTML::Toc->new();
1044 my $tocGenerator = HTML::TocGenerator->new();
1045 $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 the output will be:
1060 <ul>
1062 <li><a href=#h-1>Chapter</a>
1063 </ul>
1064 <ul>
1066 <li><a href=#h-1>Paragraph</a>
1067 </ul>
1068 Each ToC will use its own numbering scheme. Now if '"doUseGroupsGlobal
1070 = 1"' is specified:
1071 $tocGenerator->generateFromFile(
1073 [$toc1, $toc2], 'index.htm', {'doUseGroupsGlobal' => 1}
1074 );
1075 the output will be:
1077 <ul>
1079 <li><a href=#h-1>Chapter</a>
1080 </ul>
1081 <ul>
1083 <li><a href=#h-2>Paragraph</a>
1084 </ul>
1085 using a global numbering scheme for all ToCs.
1087 output
1089 syntax: reference to scalar
1090 default: none
1091 applicable to: TocInsertor, TocUpdator
1092 Reference to scalar where the output must be stored in.
1094 outputFile
1096 syntax: scalar
1097 default: none
1098 applicable to: TocInsertor, TocUpdator
1099 Filename to write output to. If no filename is specified, output will
1101 be written to standard output.
1102
1104 The "HTML::Toc" options can be grouped in the following categories:
1105 • Generate options
1107 • Insert options
1109 • Update options
1111 • Format options
1113 The ToC options must be specified using the 'setOptions' method. For
1115 example:
1116 my $toc = new HTML::Toc;
1118 $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 Generate options
1130 • Token groups
1131 • tokenToToc
1133 • doNumberToken
1135 • fileSpec
1137 • groupId
1139 • level
1141 • tokenBegin
1143 • tokenEnd
1145 • numberingStyle
1147 • groupToToc
1149 • levelToToc
1151 • Numbering tokens
1153 • doNumberToken
1155 • numberingStyle
1157 • templateTokenNumber
1159 • Miscellaneous
1161 • attributeToExcludeToken
1163 • attributeToTocToken
1165 • groupToToc
1167 • levelToToc
1169 • Linking ToC to tokens
1171 • doLinkToToken
1173 • doLinkToFile
1175 • doLinkToId
1177 • templateAnchorName
1179 • templateAnchorHrefBegin
1181 • templateAnchorHrefEnd
1183 • templateAnchorNameBegin
1185 • templateAnchorNameEnd
1187 Insert options
1189 • insertionPoint
1190 Update options
1192 • tokenUpdateBeginAnchorName
1193 • tokenUpdateEndAnchorName
1195 • tokenUpdateBeginToc
1197 • tokenUpdateEndToc
1199 • tokenUpdateBeginNumber
1201 • tokenUpdateEndNumber
1203 Format options
1205 • doSingleStepLevel
1206 • doNestGroup
1208 • footer
1210 • groupToToc
1212 • header
1214 • levelIndent
1216 • levelToToc
1218 • templateLevel
1220 • templateLevelClose
1222 • templateLevelBegin
1224 • templateLevelEnd
1226
1228 attributeToExcludeToken
1229 syntax: $scalar
1230 default: '-'
1231 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 attributeToTocToken
1237 syntax: $scalar
1238 default: '@'
1239 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 doLinkToToken
1245 syntax: [0|1]
1246 default: 1
1247 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 doLinkToFile
1253 syntax: [0|1]
1254 default: 0
1255 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 doLinkToId
1261 syntax: [0|1]
1262 default: 0
1263 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 doNestGroup
1268 syntax: [0|1]
1269 default: 0
1270 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 doNumberToken
1277 syntax: [0|1]
1278 default: 0
1279 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 doSingleStepLevel
1287 syntax: [0|1]
1288 default: 1
1289 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 <h1>Chapter</h1>
1294 <h3>Paragraph</h3>
1295 By default, an empty indentation level will be inserted in the ToC:
1297 <!-- 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 After specifying:
1310 $toc->setOptions({'doSingleStepLevel' => 0});
1312 the ToC will not have an indentation level inserted for level 2:
1314 <!-- 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 fileSpec
1325 syntax: <regexp>
1326 default: undef
1327 Specifies which files should match the current level. Valid only if
1329 doLinkToFile equals 1. For an example, see Site map.
1330 footer
1332 syntax: $scalar
1333 default: "\n<!-- End of generated Table of Contents -->\n"
1334 String to output at end of ToC.
1336 groupId
1338 syntax: $scalar
1339 default: 'h'
1340 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 $toc->setOptions({
1347 'tokenToToc' => [{
1348 'tokenBegin' => '<h1 class=-appendix>'
1349 }, {
1350 'groupId' => 'appendix',
1351 'tokenBegin' => '<h1 class=appendix>'
1352 }]
1353 });
1354 groupToToc
1356 syntax: <regexp>
1357 default: '.*'
1358 Determines which groups to use for generating the ToC. For example, to
1360 create a ToC for groups [a-b] only, specify:
1361 'groupToToc => '[a-b]'
1363 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 $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 header
1377 syntax: $scalar
1378 default: "\n<!-- Table of Contents generated by Perl - HTML::Toc -->\n"
1379 String to output at begin of ToC.
1381 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 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 '<h1 class=^header$>'
1397 Examples of valid 'insertionPoint' tokens are:
1399 '<h1>'
1401 '</h1>'
1402 '<!-- ToC -->'
1403 '<!ToC>'
1404 'ToC will be placed here'
1405 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 '<h1 class=-^header$>'
1412 See also tokenBegin.
1414 level
1416 syntax: number
1417 default: 1
1418 Number which identifies at which level the tokengroup should be
1420 incorporated into the ToC. See also: tokenToToc.
1421 levelIndent
1423 syntax: number
1424 default: 3
1425 Sets the number of spaces each level will be indented, when formatting
1427 the ToC.
1428 levelToToc
1430 syntax: <regexp>
1431 default: '.*'
1432 Determines which group levels to use for generating the ToC. For
1434 example, to create a ToC for levels 1-2 only, specify:
1435 'levelToToc => '[1-2]'
1437 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 $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 numberingStyle
1451 syntax: [decimal|lower-alpha|upper-alpha|lower-roman|upper-roman]}
1452 default: decimal
1453 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 $toc->setOptions({
1461 'doNumberToken' => 1,
1462 'tokenToToc' => [{
1463 'level' => 1,
1464 'tokenBegin' => '<h1>',
1465 'numberingStyle' => 'lower-alpha'
1466 }]
1467 });
1468 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 templateAnchorName
1474 syntax: <expression|function reference>
1475 default: '$groupId."-".$node'
1476 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 $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 If "templateAnchorName" is a function reference to a function returning
1492 the anchor, like in:
1493 $toc->setOptions({'templateAnchorName' => \&assembleAnchorName});
1495 the function will be called with the following arguments:
1497 $anchorName = assembleAnchorName($file, $groupId, $level, $node, $text, $children);
1499 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 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 $file
1512 $groupId
1513 $level
1514 $node
1515 $anchorName
1516 If "templateAnchorHrefBegin" is a function reference to a function
1518 returning the anchor, like in:
1519 $toc->setOptions({'templateAnchorHrefBegin' => \&assembleAnchorHrefBegin});
1521 the function will be called with the following arguments:
1523 $anchorHrefBegin = &assembleAnchorHrefBegin(
1525 $file, $groupId, $level, $node, $anchorName
1526 );
1527 See also: templateAnchorName, templateAnchorHrefEnd.
1529 templateAnchorHrefEnd
1531 syntax: <expression|function reference>
1532 default: '"</a>"'
1533 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 $toc->setOptions({'templateAnchorHrefEnd' => \&assembleAnchorHrefEnd});
1540 the function will be called without arguments:
1542 $anchorHrefEnd = &assembleAnchorHrefEnd;
1544 See also: templateAnchorHrefBegin.
1546 templateAnchorNameBegin
1548 syntax: <expression|function reference>
1549 default: '"<a name=$anchorName>"'
1550 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 $file
1556 $groupId
1557 $level
1558 $node
1559 $anchorName
1560 If "templateAnchorNameBegin" is a function reference to a function
1562 returning the anchor name, like in:
1563 $toc->setOptions({'templateAnchorNameBegin' => \&assembleAnchorNameBegin});
1565 the function will be called with the following arguments:
1567 $anchorNameBegin = assembleAnchorNameBegin(
1569 $file, $groupId, $level, $node, $anchorName
1570 );
1571 See also: templateAnchorName, templateAnchorNameEnd.
1573 templateAnchorNameEnd
1575 syntax: <expression|function reference>
1576 default: '"</a>"'
1577 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 $toc->setOptions({'templateAnchorNameEnd' => \&assembleAnchorNameEnd});
1584 the function will be called without arguments:
1586 $anchorNameEnd = &assembleAnchorNameEnd;
1588 See also: templateAnchorNameBegin.
1590 templateLevel
1592 syntax: <expression|function reference>
1593 default: '"<li>$text"'
1594 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 $level
1600 $groupId
1601 $node
1602 $sequenceNr
1603 $text
1604 If "templateLevel" is a function reference to a function returning the
1606 ToC node, like in:
1607 $toc->setOptions({'templateLevel' => \&AssembleTocNode});
1609 the function will be called with the following arguments:
1611 $tocNode = &AssembleTocNode(
1613 $level, $groupId, $node, $sequenceNr, $text
1614 );
1615 templateLevelClose
1617 syntax: <expression|function reference>
1618 default: '"</li>\n"'
1619 Expression to use when formatting a ToC node. The template may be
1621 specified as either an expression or a function reference.
1622 templateLevelBegin
1624 syntax: <expression>
1625 default: '"<ul>\n"'
1626 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 '"<ul class=\"toc_$groupId$level\">\n"'
1633 which will result in each ToC group given a class name:
1635 <ul class="toc_h1">
1637 <li>Header
1638 </ul>
1639 For an example, see Using CSS for ToC formatting.
1641 templateLevelEnd
1643 syntax: <expression>
1644 default: '"</ul>\n"'
1645 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 '"</ul>\n"'
1651 For an example, see Using CSS for ToC formatting.
1653 templateTokenNumber
1655 syntax: <expression|function reference>
1656 default: '"$node "'
1657 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 $file
1663 $groupId
1664 $groupLevel
1665 $level
1666 $node
1667 $toc
1668 If "templateTokenNumber" is a function reference to a function
1670 returning the token number, like in:
1671 $toc->setOptions({'templateTokenNumber' => \&assembleTokenNumber});
1673 the function will be called with the following arguments:
1675 $number = &assembleTokenNumber(
1677 $node, $groupId, $file, $groupLevel, $level, $toc
1678 );
1679 tokenBegin
1681 syntax: <token>
1682 default: '<h1>'
1683 token: <[/]tag{ attribute=[-|@]<regexp>}> |
1684 <text regexp> |
1685 <declaration regexp> |
1686 <comment regexp>
1687 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 '<h1>'
1693 '</end>'
1694 '<!-- Start ToC entry -->'
1695 '<!Start ToC entry>'
1696 'ToC entry'
1697 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 '<h1 class=^header$>'
1704 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 '<h1 class=-^header$>'
1711 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 '<h1 class=@>'
1717 See Generate multiple ToCs for an elaborated example using the
1719 "attributeToTocToken" to generate a ToC of image "alt" attribute
1720 values.
1721 See also: tokenEnd, tokenToToc.
1723 tokenEnd
1725 syntax: $scalar
1726 default: empty string ('') or end tag counterpart of 'tokenBegin' if
1727 'tokenBegin' is a start tag
1728 The 'tokenEnd' definition applies to the same rules as tokenBegin.
1730 See also: tokenBegin, tokenToToc.
1732 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 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 tokenUpdateBeginAnchorName
1760 syntax: <string>
1761 default: '<!-- #BeginTocAnchorNameBegin -->';
1762 This token marks the begin of an anchor name, inserted by
1764 "HTML::TocInsertor". This option is used by "HTML::TocUpdator".
1765 tokenUpdateEndAnchorName
1767 syntax: <string>
1768 default: '<!-- #EndTocAnchorName -->';
1769 This option is used by "HTML::TocUpdator", to mark the end of an
1771 inserted anchor name.
1772 tokenUpdateBeginNumber
1774 syntax: <string>
1775 default: '<!-- #BeginTocNumber -->';
1776 This option is used by "HTML::TocUpdator", to mark the begin of an
1778 inserted number.
1779 tokenUpdateEndNumber
1781 syntax: <string>
1782 default: '<!-- #EndTocAnchorName -->';
1783 This option is used by "HTML::TocUpdator", to mark the end of an
1785 inserted number.
1786 tokenUpdateBeginToc
1788 syntax: <string>
1789 default: '<!-- #BeginToc -->';
1790 This option is used by "HTML::TocUpdator", to mark the begin of an
1792 inserted ToC.
1793 tokenUpdateEndToc
1795 syntax: <string>
1796 default: '<!-- #EndToc -->';
1797 This option is used by "HTML::TocUpdator", to mark the end of an
1799 inserted ToC.
1800
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
1811 Freddy Vulto <"fvulto@gmail.com">
1812
1814 Copyright (c) 2009 Freddy Vulto. All rights reserved.
1815 This library is free software; you can redistribute it and/or modify it
1817 under the same terms as Perl itself.
1818perl v5.34.0 2021-07-22 Toc(3)