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 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 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() will
240 also insert the ToC, whether there is a ToC already inserted or not.
241 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 use HTML::Toc;
248 use HTML::TocUpdator;
249 my $toc = HTML::Toc->new();
251 my $tocUpdator = HTML::TocUpdator->new();
252 $tocUpdator->updateFile($toc, 'indexToc.htm');
254 For example, with "indexToc.htm" containing:
256 <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 the output will be:
268 <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 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 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
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 preface
302 introduction
303 table of contents
304 table of figures
305 table of tables
306 parts
307 chapters
308 appendixes
309 bibliography
310 is formatted all at once.
312 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 <body>
322 <img src=test1.gif alt="First picture">
323 <img src=test2.gif alt="Second picture">
324 </body>
325 This would be the code:
327 use HTML::Toc;
329 use HTML::TocInsertor;
330 my $toc = HTML::Toc->new();
332 my $tocInsertor = HTML::TocInsertor->new();
333 $toc->setOptions({
335 'tokenToToc' => [{
336 'groupId' => 'image',
337 'tokenBegin' => '<img alt=@>'
338 }],
339 });
340 $tocInsertor->insertIntoFile($toc, $filename);
341 and the output will be:
343 <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 <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 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 Specify an array of files
363 For example, suppose you want to generate a ToC of both "doc1.htm":
365 <body>
367 <h1>Chapter of document 1</h1>
368 </body>
369 and "doc2.htm":
371 <body>
373 <h1>Chapter of document 2</h1>
374 </body>
375 Here's the code to do so by specifying an array of files:
377 use HTML::Toc;
379 use HTML::TocGenerator;
380 my $toc = HTML::Toc->new();
382 my $tocGenerator = HTML::TocGenerator->new();
383 $toc->setOptions({'doLinkToFile' => 1});
385 $tocGenerator->generateFromFile($toc, ['doc1.htm', 'doc2.htm']);
386 print $toc->format();
387 And the output will be:
389 <!-- 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 Extend an existing ToC
398 It's also possible to extend an existing ToC. For example, suppose we
400 want the generate a ToC of file "doc1.htm":
401 <body>
403 <h1>Chapter of document 1</h1>
404 </body>
405 and extend this ToC with text from "doc2.htm":
407 <body>
409 <h1>Chapter of document 2</h1>
410 </body>
411 Here's the code to do so:
413 use HTML::Toc;
415 use HTML::TocGenerator;
416 my $toc = HTML::Toc->new();
418 my $tocGenerator = HTML::TocGenerator->new();
419 $toc->setOptions({'doLinkToFile' => 1});
421 $tocGenerator->generateFromFile($toc, 'doc1.htm');
422 $tocGenerator->extendFromFile($toc, 'doc2.htm');
423 print $toc->format();
424 And the output will be:
426 <!-- 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 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 <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 Here's how you would do so:
448 use HTML::Toc;
450 use HTML::TocInsertor;
451 my $toc1 = HTML::Toc->new();
453 my $toc2 = HTML::Toc->new();
454 my $tocInsertor = HTML::TocInsertor->new();
455 $toc2->setOptions({
457 'tokenToToc' => [{
458 'groupId' => 'image',
459 'tokenBegin' => '<img alt=@>'
460 }],
461 });
462 $tocInsertor->insertIntoFile([$toc1, $toc2], $filename);
463 And the output will be:
465 <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 <!-- 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 <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 Generate multiple groups in one ToC
491 You may want to generate a ToC consisting of multiple ToC groups.
492 Specify an additional 'Appendix' group
494 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 <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 With the code underneath:
509 use HTML::Toc;
511 use HTML::TocInsertor;
512 my $toc = HTML::Toc->new();
514 my $tocInsertor = HTML::TocInsertor->new();
515 $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 the output will be:
534 <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 <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 Specify an additional 'Part' group
563 Suppose you want to generate a ToC of a document which is divided in
565 multiple parts like this file underneath:
566 <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 With the code underneath:
577 use HTML::Toc;
579 use HTML::TocInsertor;
580 my $toc = HTML::Toc->new();
582 my $tocInsertor = HTML::TocInsertor->new();
583 $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 the output will be:
602 <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 <h1 class="part"><a name="part-A"></a>A 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 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 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 Specify numbered list
643 By modifying templateLevelBegin and templateLevelEnd you can specify a
645 numbered ToC:
646 use HTML::Toc;
648 use HTML::TocGenerator;
649 my $toc = HTML::Toc->new();
651 my $tocGenerator = HTML::TocGenerator->new();
652 $toc->setOptions({
654 'templateLevelBegin' => '"<ol>\n"',
655 'templateLevelEnd' => '"</ol>\n"',
656 });
657 $tocGenerator->generateFromFile($toc, 'index.htm');
658 print $toc->format();
659 For instance with the original file containing:
661 <body>
663 <h1>Chapter</h1>
664 <h2>Paragraph</h2>
665 </body>
666 The formatted ToC now will contain "ol" instead of "ul" tags:
668 <!-- 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 See also: Using CSS for ToC formatting.
680 Use generated numbers
682 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 use HTML::Toc;
688 use HTML::TocGenerator;
689 my $toc = HTML::Toc->new();
691 my $tocGenerator = HTML::TocGenerator->new();
692 $toc->setOptions({
694 'templateLevel' => '"<li>$node $text"',
695 });
696 $tocGenerator->generateFromFile($toc, 'index.htm');
697 print $toc->format();
698 For instance with the original file containing:
700 <body>
702 <h1>Chapter</h1>
703 <h2>Paragraph</h2>
704 </body>
705 The formatted ToC now will have the node numbers hard-coded:
707 <!-- Table of Contents generated by Perl - HTML::Toc -->
709 <ul>
710 <li>1 <a href=#h-1>Chapter</a>
711 <ul>
712 <li>1.1 <a href=#h-1.1>Paragraph</a></li>
713 </ul>
714 </li>
715 </ul>
716 <!-- End of generated Table of Contents -->
717 See also: Using CSS for ToC formatting.
719 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 <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 Here's the code:
740 my $toc = new HTML::Toc;
742 my $tocInsertor = new HTML::TocInsertor;
743 $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 Which whill result in the following output:
761 <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 <h1><a name="appendix-A"></a>A Appendix</h1>
785 <h2><a name="appendix-A.1"></a>A.1 Appendix Paragraph</h2>
786 <h1><a name="appendix-B"></a>B Appendix</h1>
787 <h2><a name="appendix-B.1"></a>B.1 Appendix Paragraph</h2>
788 </body>
789 </html>
790 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 path file
796 . 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 By specifying 'fileSpec' which determine how many slashes (/) each file
808 may contain for a specific level:
809 use HTML::Toc;
811 use HTML::TocGenerator;
812 use File::Find;
813 my $toc = HTML::Toc->new;
815 my $tocGenerator = HTML::TocGenerator->new;
816 my @fileList;
817 sub wanted {
819 # Add file to 'fileList' if extension matches '.htm'
820 push (@fileList, $File::Find::name) if (m/\.htm$/);
821 }
822 $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 # 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 the following ToC will be generated:
858 <!-- 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
881 HTML::Toc::clear()
882 syntax: $toc->clear()
883 returns: --
884 Clear the ToC.
886 HTML::Toc::format()
888 syntax: $scalar = $toc->format()
889 returns: Formatted ToC.
890 Format tokenized ToC.
892 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 Extend ToC from specified string. For available options, see Parser
900 Options
901 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 Extend ToC from specified file. For available options, see Parser
909 Options. For an example, see "Extend an existing ToC".
910 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 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 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 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 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 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 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 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 Insert ToC into specified file. For available options, see Parser
955 Options.
956 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 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 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 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 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 Update ToC within specified string. For updator options, see Update
987 options.
988 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 Update ToC of specified file. For updator options, see Update options.
996
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 $tocGenerator->generateFromFile($toc, $filename, {doUseGroupsGlobal => 1});
1004 Available options are:
1006 • doGenerateToc
1008 • doUseGroupsGlobal
1010 • output
1012 • outputFile
1014 doGenerateToc
1016 syntax: [0|1]
1017 default: 1
1018 applicable to: TocInsertor, TocUpdator
1019 True (1) if ToC must be generated. False (0) if ToC must be inserted
1021 only.
1022 doUseGroupsGlobal
1024 syntax: [0|1]
1025 default: 0
1026 applicable to: TocGenerator, TocInsertor, TocUpdator
1027 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 <h1>Chapter</h1>
1034 <h2>Paragraph</h2>
1035 Using the default setting of 'doUseGroupsGlobal' => 0:
1037 use HTML::Toc;
1039 use HTML::TocGenerator;
1040 my $toc1 = HTML::Toc->new();
1042 my $toc2 = HTML::Toc->new();
1043 my $tocGenerator = HTML::TocGenerator->new();
1044 $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 the output will be:
1059 <ul>
1061 <li><a href=#h-1>Chapter</a>
1062 </ul>
1063 <ul>
1065 <li><a href=#h-1>Paragraph</a>
1066 </ul>
1067 Each ToC will use its own numbering scheme. Now if '"doUseGroupsGlobal
1069 = 1"' is specified:
1070 $tocGenerator->generateFromFile(
1072 [$toc1, $toc2], 'index.htm', {'doUseGroupsGlobal' => 1}
1073 );
1074 the output will be:
1076 <ul>
1078 <li><a href=#h-1>Chapter</a>
1079 </ul>
1080 <ul>
1082 <li><a href=#h-2>Paragraph</a>
1083 </ul>
1084 using a global numbering scheme for all ToCs.
1086 output
1088 syntax: reference to scalar
1089 default: none
1090 applicable to: TocInsertor, TocUpdator
1091 Reference to scalar where the output must be stored in.
1093 outputFile
1095 syntax: scalar
1096 default: none
1097 applicable to: TocInsertor, TocUpdator
1098 Filename to write output to. If no filename is specified, output will
1100 be written to standard output.
1101
1103 The "HTML::Toc" options can be grouped in the following categories:
1104 • Generate options
1106 • Insert options
1108 • Update options
1110 • Format options
1112 The ToC options must be specified using the 'setOptions' method. For
1114 example:
1115 my $toc = new HTML::Toc;
1117 $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 Generate options
1129 • Token groups
1130 • tokenToToc
1132 • doNumberToken
1134 • fileSpec
1136 • groupId
1138 • level
1140 • tokenBegin
1142 • tokenEnd
1144 • numberingStyle
1146 • groupToToc
1148 • levelToToc
1150 • Numbering tokens
1152 • doNumberToken
1154 • numberingStyle
1156 • templateTokenNumber
1158 • Miscellaneous
1160 • attributeToExcludeToken
1162 • attributeToTocToken
1164 • groupToToc
1166 • levelToToc
1168 • Linking ToC to tokens
1170 • doLinkToToken
1172 • doLinkToFile
1174 • doLinkToId
1176 • templateAnchorName
1178 • templateAnchorHrefBegin
1180 • templateAnchorHrefEnd
1182 • templateAnchorNameBegin
1184 • templateAnchorNameEnd
1186 Insert options
1188 • insertionPoint
1189 Update options
1191 • tokenUpdateBeginAnchorName
1192 • tokenUpdateEndAnchorName
1194 • tokenUpdateBeginToc
1196 • tokenUpdateEndToc
1198 • tokenUpdateBeginNumber
1200 • tokenUpdateEndNumber
1202 Format options
1204 • doSingleStepLevel
1205 • doNestGroup
1207 • footer
1209 • groupToToc
1211 • header
1213 • levelIndent
1215 • levelToToc
1217 • templateLevel
1219 • templateLevelClose
1221 • templateLevelBegin
1223 • templateLevelEnd
1225
1227 attributeToExcludeToken
1228 syntax: $scalar
1229 default: '-'
1230 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 attributeToTocToken
1236 syntax: $scalar
1237 default: '@'
1238 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 doLinkToToken
1244 syntax: [0|1]
1245 default: 1
1246 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 doLinkToFile
1252 syntax: [0|1]
1253 default: 0
1254 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 doLinkToId
1260 syntax: [0|1]
1261 default: 0
1262 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 doNestGroup
1267 syntax: [0|1]
1268 default: 0
1269 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 doNumberToken
1276 syntax: [0|1]
1277 default: 0
1278 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 doSingleStepLevel
1286 syntax: [0|1]
1287 default: 1
1288 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 <h1>Chapter</h1>
1293 <h3>Paragraph</h3>
1294 By default, an empty indentation level will be inserted in the ToC:
1296 <!-- 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 After specifying:
1309 $toc->setOptions({'doSingleStepLevel' => 0});
1311 the ToC will not have an indentation level inserted for level 2:
1313 <!-- 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 fileSpec
1324 syntax: <regexp>
1325 default: undef
1326 Specifies which files should match the current level. Valid only if
1328 doLinkToFile equals 1. For an example, see Site map.
1329 footer
1331 syntax: $scalar
1332 default: "\n<!-- End of generated Table of Contents -->\n"
1333 String to output at end of ToC.
1335 groupId
1337 syntax: $scalar
1338 default: 'h'
1339 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 $toc->setOptions({
1346 'tokenToToc' => [{
1347 'tokenBegin' => '<h1 class=-appendix>'
1348 }, {
1349 'groupId' => 'appendix',
1350 'tokenBegin' => '<h1 class=appendix>'
1351 }]
1352 });
1353 groupToToc
1355 syntax: <regexp>
1356 default: '.*'
1357 Determines which groups to use for generating the ToC. For example, to
1359 create a ToC for groups [a-b] only, specify:
1360 'groupToToc => '[a-b]'
1362 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 $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 header
1376 syntax: $scalar
1377 default: "\n<!-- Table of Contents generated by Perl - HTML::Toc -->\n"
1378 String to output at begin of ToC.
1380 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 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 '<h1 class=^header$>'
1396 Examples of valid 'insertionPoint' tokens are:
1398 '<h1>'
1400 '</h1>'
1401 '<!-- ToC -->'
1402 '<!ToC>'
1403 'ToC will be placed here'
1404 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 '<h1 class=-^header$>'
1411 See also tokenBegin.
1413 level
1415 syntax: number
1416 default: 1
1417 Number which identifies at which level the tokengroup should be
1419 incorporated into the ToC. See also: tokenToToc.
1420 levelIndent
1422 syntax: number
1423 default: 3
1424 Sets the number of spaces each level will be indented, when formatting
1426 the ToC.
1427 levelToToc
1429 syntax: <regexp>
1430 default: '.*'
1431 Determines which group levels to use for generating the ToC. For
1433 example, to create a ToC for levels 1-2 only, specify:
1434 'levelToToc => '[1-2]'
1436 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 $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 numberingStyle
1450 syntax: [decimal|lower-alpha|upper-alpha|lower-roman|upper-roman]}
1451 default: decimal
1452 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 $toc->setOptions({
1460 'doNumberToken' => 1,
1461 'tokenToToc' => [{
1462 'level' => 1,
1463 'tokenBegin' => '<h1>',
1464 'numberingStyle' => 'lower-alpha'
1465 }]
1466 });
1467 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 templateAnchorName
1473 syntax: <expression|function reference>
1474 default: '$groupId."-".$node'
1475 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 $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 If "templateAnchorName" is a function reference to a function returning
1491 the anchor, like in:
1492 $toc->setOptions({'templateAnchorName' => \&assembleAnchorName});
1494 the function will be called with the following arguments:
1496 $anchorName = assembleAnchorName($file, $groupId, $level, $node, $text, $children);
1498 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 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 $file
1511 $groupId
1512 $level
1513 $node
1514 $anchorName
1515 If "templateAnchorHrefBegin" is a function reference to a function
1517 returning the anchor, like in:
1518 $toc->setOptions({'templateAnchorHrefBegin' => \&assembleAnchorHrefBegin});
1520 the function will be called with the following arguments:
1522 $anchorHrefBegin = &assembleAnchorHrefBegin(
1524 $file, $groupId, $level, $node, $anchorName
1525 );
1526 See also: templateAnchorName, templateAnchorHrefEnd.
1528 templateAnchorHrefEnd
1530 syntax: <expression|function reference>
1531 default: '"</a>"'
1532 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 $toc->setOptions({'templateAnchorHrefEnd' => \&assembleAnchorHrefEnd});
1539 the function will be called without arguments:
1541 $anchorHrefEnd = &assembleAnchorHrefEnd;
1543 See also: templateAnchorHrefBegin.
1545 templateAnchorNameBegin
1547 syntax: <expression|function reference>
1548 default: '"<a name=$anchorName>"'
1549 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 $file
1555 $groupId
1556 $level
1557 $node
1558 $anchorName
1559 If "templateAnchorNameBegin" is a function reference to a function
1561 returning the anchor name, like in:
1562 $toc->setOptions({'templateAnchorNameBegin' => \&assembleAnchorNameBegin});
1564 the function will be called with the following arguments:
1566 $anchorNameBegin = assembleAnchorNameBegin(
1568 $file, $groupId, $level, $node, $anchorName
1569 );
1570 See also: templateAnchorName, templateAnchorNameEnd.
1572 templateAnchorNameEnd
1574 syntax: <expression|function reference>
1575 default: '"</a>"'
1576 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 $toc->setOptions({'templateAnchorNameEnd' => \&assembleAnchorNameEnd});
1583 the function will be called without arguments:
1585 $anchorNameEnd = &assembleAnchorNameEnd;
1587 See also: templateAnchorNameBegin.
1589 templateLevel
1591 syntax: <expression|function reference>
1592 default: '"<li>$text"'
1593 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 $level
1599 $groupId
1600 $node
1601 $sequenceNr
1602 $text
1603 If "templateLevel" is a function reference to a function returning the
1605 ToC node, like in:
1606 $toc->setOptions({'templateLevel' => \&AssembleTocNode});
1608 the function will be called with the following arguments:
1610 $tocNode = &AssembleTocNode(
1612 $level, $groupId, $node, $sequenceNr, $text
1613 );
1614 templateLevelClose
1616 syntax: <expression|function reference>
1617 default: '"</li>\n"'
1618 Expression to use when formatting a ToC node. The template may be
1620 specified as either an expression or a function reference.
1621 templateLevelBegin
1623 syntax: <expression>
1624 default: '"<ul>\n"'
1625 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 '"<ul class=\"toc_$groupId$level\">\n"'
1632 which will result in each ToC group given a class name:
1634 <ul class="toc_h1">
1636 <li>Header
1637 </ul>
1638 For an example, see Using CSS for ToC formatting.
1640 templateLevelEnd
1642 syntax: <expression>
1643 default: '"</ul>\n"'
1644 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 '"</ul>\n"'
1650 For an example, see Using CSS for ToC formatting.
1652 templateTokenNumber
1654 syntax: <expression|function reference>
1655 default: '"$node "'
1656 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 $file
1662 $groupId
1663 $groupLevel
1664 $level
1665 $node
1666 $toc
1667 If "templateTokenNumber" is a function reference to a function
1669 returning the token number, like in:
1670 $toc->setOptions({'templateTokenNumber' => \&assembleTokenNumber});
1672 the function will be called with the following arguments:
1674 $number = &assembleTokenNumber(
1676 $node, $groupId, $file, $groupLevel, $level, $toc
1677 );
1678 tokenBegin
1680 syntax: <token>
1681 default: '<h1>'
1682 token: <[/]tag{ attribute=[-|@]<regexp>}> |
1683 <text regexp> |
1684 <declaration regexp> |
1685 <comment regexp>
1686 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 '<h1>'
1692 '</end>'
1693 '<!-- Start ToC entry -->'
1694 '<!Start ToC entry>'
1695 'ToC entry'
1696 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 '<h1 class=^header$>'
1703 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 '<h1 class=-^header$>'
1710 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 '<h1 class=@>'
1716 See Generate multiple ToCs for an elaborated example using the
1718 "attributeToTocToken" to generate a ToC of image "alt" attribute
1719 values.
1720 See also: tokenEnd, tokenToToc.
1722 tokenEnd
1724 syntax: $scalar
1725 default: empty string ('') or end tag counterpart of 'tokenBegin' if
1726 'tokenBegin' is a start tag
1727 The 'tokenEnd' definition applies to the same rules as tokenBegin.
1729 See also: tokenBegin, tokenToToc.
1731 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 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 tokenUpdateBeginAnchorName
1759 syntax: <string>
1760 default: '<!-- #BeginTocAnchorNameBegin -->';
1761 This token marks the begin of an anchor name, inserted by
1763 "HTML::TocInsertor". This option is used by "HTML::TocUpdator".
1764 tokenUpdateEndAnchorName
1766 syntax: <string>
1767 default: '<!-- #EndTocAnchorName -->';
1768 This option is used by "HTML::TocUpdator", to mark the end of an
1770 inserted anchor name.
1771 tokenUpdateBeginNumber
1773 syntax: <string>
1774 default: '<!-- #BeginTocNumber -->';
1775 This option is used by "HTML::TocUpdator", to mark the begin of an
1777 inserted number.
1778 tokenUpdateEndNumber
1780 syntax: <string>
1781 default: '<!-- #EndTocAnchorName -->';
1782 This option is used by "HTML::TocUpdator", to mark the end of an
1784 inserted number.
1785 tokenUpdateBeginToc
1787 syntax: <string>
1788 default: '<!-- #BeginToc -->';
1789 This option is used by "HTML::TocUpdator", to mark the begin of an
1791 inserted ToC.
1792 tokenUpdateEndToc
1794 syntax: <string>
1795 default: '<!-- #EndToc -->';
1796 This option is used by "HTML::TocUpdator", to mark the end of an
1798 inserted ToC.
1799
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
1810 Freddy Vulto <"fvulto@gmail.com">
1811
1813 Copyright (c) 2009 Freddy Vulto. All rights reserved.
1814 This library is free software; you can redistribute it and/or modify it
1816 under the same terms as Perl itself.
1817perl v5.36.0 2023-01-20 Toc(3)