Lines Matching full:toc
3 HTML::Toc - Generate, insert and update HTML Table of Contents.
11 The HTML::Toc consists out of the following packages:
13 HTML::Toc
18 HTML::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.
32 | HTML::TocGenerator + - - - - - -+ HTML::Toc |
61 When generating a ToC you'll have to decide which object you want to use:
64 for generating a ToC without inserting the ToC into the source
66 for generating a ToC and inserting the ToC into the source
68 for generating and inserting a ToC, removing any previously
69 inserted ToC elements
81 The code underneath will generate a ToC of the HTML headings C<<h1>>..C<<h6>> from a file C<index.htm>:
83 use HTML::Toc;
86 my $toc = HTML::Toc->new();
89 $tocGenerator->generateFromFile($toc, 'index.htm');
90 print $toc->format();
103 <!-- Table of Contents generated by Perl - HTML::Toc -->
111 This 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:
113 use HTML::Toc;
116 my $toc = HTML::Toc->new();
119 $tocInsertor->insertIntoFile($toc, 'index.htm');
133 <!-- Table of Contents generated by Perl - HTML::Toc -->
143 If 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>:
145 use HTML::Toc;
148 my $toc = HTML::Toc->new();
151 $tocUpdator->insertIntoFile($toc, 'index.htm');
172 around the inserted ToC elements:
176 <!-- Table of Contents generated by Perl - HTML::Toc -->
188 Instead 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.
192 This 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:
194 use HTML::Toc;
197 my $toc = HTML::Toc->new();
200 $tocUpdator->updateFile($toc, 'indexToc.htm');
218 <!-- Table of Contents generated by Perl - HTML::Toc -->
234 The 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">'.
238 The 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:
252 =head2 Using attribute value as ToC text
254 Normally, 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:
263 use HTML::Toc;
266 my $toc = HTML::Toc->new();
269 $toc->setOptions({
275 $tocInsertor->insertIntoFile($toc, $filename);
280 <!-- Table of Contents generated by Perl - HTML::Toc -->
291 =head2 Generate single ToC of multiple files
293 Besides 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.
297 For example, suppose you want to generate a ToC of both C<doc1.htm>:
311 use HTML::Toc;
314 my $toc = HTML::Toc->new();
317 $toc->setOptions({'doLinkToFile' => 1});
318 $tocGenerator->generateFromFile($toc, ['doc1.htm', 'doc2.htm']);
319 print $toc->format();
324 <!-- Table of Contents generated by Perl - HTML::Toc -->
331 =head3 Extend an existing ToC
333 It's also possible to extend an existing ToC. For example, suppose we want the generate a ToC of file C<doc1.htm>:
339 and extend this ToC with text from C<doc2.htm>:
347 use HTML::Toc;
350 my $toc = HTML::Toc->new();
353 $toc->setOptions({'doLinkToFile' => 1});
354 $tocGenerator->generateFromFile($toc, 'doc1.htm');
355 $tocGenerator->extendFromFile($toc, 'doc2.htm');
356 print $toc->format();
361 <!-- Table of Contents generated by Perl - HTML::Toc -->
370 It'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:
381 use HTML::Toc;
384 my $toc1 = HTML::Toc->new();
385 my $toc2 = HTML::Toc->new();
399 <!-- Table of Contents generated by Perl - HTML::Toc -->
408 <!-- Table of Contents generated by Perl - HTML::Toc -->
421 =head2 Generate multiple groups in one ToC
423 You may want to generate a ToC consisting of multiple ToC groups.
427 Suppose you want to generate a ToC with one group for the normal headings, and one group for the appendix headings, using this source file:
440 use HTML::Toc;
443 my $toc = HTML::Toc->new();
446 $toc->setOptions({
461 $tocInsertor->insertIntoFile($toc, $filename);
466 <!-- Table of Contents generated by Perl - HTML::Toc -->
492 Suppose you want to generate a ToC of a document which is divided in multiple parts like this file underneath:
505 use HTML::Toc;
508 my $toc = HTML::Toc->new();
511 $toc->setOptions({
525 $tocInsertor->insertIntoFile($toc, $filename);
530 <!-- Table of Contents generated by Perl - HTML::Toc -->
559 =head2 Number ToC entries
561 By 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.
565 By modifying L<templateLevelBegin|"templateLevelBegin"> and L<templateLevelEnd|"templateLevelEnd"> you can specify a numbered ToC:
567 use HTML::Toc;
570 my $toc = HTML::Toc->new();
573 $toc->setOptions({
577 $tocGenerator->generateFromFile($toc, 'index.htm');
578 print $toc->format();
587 The formatted ToC now will contain C<ol> instead of C<ul> tags:
589 <!-- Table of Contents generated by Perl - HTML::Toc -->
598 See also: L<Using CSS for ToC formatting|"Using CSS for ToC formatting">.
602 Instead 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">:
604 use HTML::Toc;
607 my $toc = HTML::Toc->new();
610 $toc->setOptions({
613 $tocGenerator->generateFromFile($toc, 'index.htm');
614 print $toc->format();
623 The formatted ToC now will have the node numbers hard-coded:
625 <!-- Table of Contents generated by Perl - HTML::Toc -->
634 See also: L<Using CSS for ToC formatting|"Using CSS for ToC formatting">.
636 =head2 Using CSS for ToC formatting
638 Suppose 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:
656 my $toc = new HTML::Toc;
659 $toc->setOptions({
673 $tocInsertor->insertIntoFile($toc, $filename);
684 <!-- Table of Contents generated by Perl - HTML::Toc -->
722 use HTML::Toc;
726 my $toc = HTML::Toc->new;
735 $toc->setOptions({
763 # Generate ToC of case-insensitively sorted file list
765 $toc, [sort {uc($a) cmp uc($b)} @fileList]
767 print $toc->format();
769 the following ToC will be generated:
771 <!-- Table of Contents generated by Perl - HTML::Toc -->
791 =head2 HTML::Toc::clear()
793 syntax: $toc->clear()
796 Clear the ToC.
798 =head2 HTML::Toc::format()
800 syntax: $scalar = $toc->format()
801 returns: Formatted ToC.
803 Format tokenized ToC.
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
812 Extend ToC from specified string. For generator options, see L<HTML::TocGenerator Options|"HTML::TocGenerator Options">
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
821 Extend ToC from specified file. For generator options, see L<HTML::TocGenerator Options|"HTML::TocGenerator Options">. For an example, see L<Extend an existing ToC>.
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
830 Generate 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">.
834 syntax: $tocGenerator->generateFromFile($toc, $filename [, $options])
835 args: - $toc: (reference to array of) HTML::Toc object(s) to
837 - $filename: (reference to array of) file(s) to generate ToC from
840 Generate 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">.
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
849 Insert ToC into specified string. For insertor options, see L<HTML::TocInsertor Options|"HTML::TocInsertor Options">.
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
858 Insert ToC into specified file. For insertor options, see L<HTML::TocInsertor Options|"HTML::TocInsertor Options">.
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
867 Insert 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">.
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
876 Insert 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">.
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
885 Update ToC within specified string. For updator options, see L<HTML::TocUpdator Options|"HTML::TocUpdator Options">.
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
894 Update ToC of specified file. For updator options, see L<HTML::TocUpdator Options|"HTML::TocUpdator Options">.
898 When 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:
900 $tocGenerator->generateFromFile($toc, $filename, {doUseGroupsGlobal => 1});
922 True (1) if ToC must be generated. False (0) if ToC must be inserted only.
930 True (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':
937 use HTML::Toc;
940 my $toc1 = HTML::Toc->new();
941 my $toc2 = HTML::Toc->new();
967 Each ToC will use its own numbering scheme. Now if 'C<doUseGroupsGlobal = 1>' is specified:
1001 =head1 HTML::Toc Options
1003 The C<HTML::Toc> options can be grouped in the following categories:
1017 The ToC options must be specified using the 'setOptions' method. For example:
1019 my $toc = new HTML::Toc;
1021 $toc->setOptions({
1023 'footer' => '<!-- End Of ToC -->'
1091 =item Linking ToC to tokens
1165 =head1 HTML::Toc Options Reference
1172 Token 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">.
1179 Token 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">.
1186 True (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.
1193 True (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.
1200 True (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.
1207 True (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">.
1214 True (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">.
1221 True (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>':
1226 By default, an empty indentation level will be inserted in the ToC:
1228 <!-- Table of Contents generated by Perl - HTML::Toc -->
1241 $toc->setOptions({'doSingleStepLevel' => 0});
1243 the ToC will not have an indentation level inserted for level 2:
1245 <!-- Table of Contents generated by Perl - HTML::Toc -->
1266 String to output at end of ToC.
1273 Sets 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:
1275 $toc->setOptions({
1289 Determines which groups to use for generating the ToC. For example, to create a ToC for groups [a-b] only, specify:
1293 This 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:
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();
1306 default: "\n<!-- Table of Contents generated by Perl - HTML::Toc -->\n"
1308 String to output at begin of ToC.
1320 Determines 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:
1328 '<!-- ToC -->'
1329 '<!ToC>'
1330 'ToC will be placed here'
1343 Number which identifies at which level the tokengroup should be incorporated into the ToC. See also: L<tokenToToc|"tokenToToc">.
1350 Sets the number of spaces each level will be indented, when formatting the ToC.
1357 Determines which group levels to use for generating the ToC. For example, to create a ToC for levels 1-2 only, specify:
1361 This 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:
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();
1376 Determines 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.:
1378 $toc->setOptions({
1403 $toc->setOptions({'templateAnchorName' => \&assembleAnchorName});
1426 $toc->setOptions({'templateAnchorHrefBegin' => \&assembleAnchorHrefBegin});
1443 $toc->setOptions({'templateAnchorHrefEnd' => \&assembleAnchorHrefEnd});
1466 $toc->setOptions({'templateAnchorNameBegin' => \&assembleAnchorNameBegin});
1483 $toc->setOptions({'templateAnchorNameEnd' => \&assembleAnchorNameEnd});
1496 Expression 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:
1504 If C<templateLevel> is a function reference to a function returning the ToC node, like in:
1506 $toc->setOptions({'templateLevel' => \&AssembleTocNode});
1519 Expression 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:
1523 which will result in each ToC group being given a class name:
1529 For an example, see L<Using CSS for ToC formatting|"Using CSS for ToC formatting">.
1536 Expression 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:
1540 For an example, see L<Using CSS for ToC formatting|"Using CSS for ToC formatting">.
1554 $toc
1558 $toc->setOptions({'templateTokenNumber' => \&assembleTokenNumber});
1563 $node, $groupId, $file, $groupLevel, $level, $toc
1575 This 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:
1579 '<!-- Start ToC entry -->'
1580 '<!Start ToC entry>'
1581 'ToC entry'
1591 Also, 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:
1595 See 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.
1632 This 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.
1667 This option is used by C<HTML::TocUpdator>, to mark the begin of an inserted ToC.
1674 This option is used by C<HTML::TocUpdator>, to mark the end of an inserted ToC.
1681 When 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.
1685 HTML::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:
