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