=head1 NAME HTML::Toc - Generate, insert and update HTML Table of Contents. =head1 DESCRIPTION Generate, insert and update HTML Table of Contents (ToC). =head1 Introduction The HTML::Toc consists out of the following packages: HTML::Toc HTML::TocGenerator HTML::TocInsertor HTML::TocUpdator 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. HTML::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: +---------------------+ | HTML::Parser | +---------------------+ +---------------------+ | +parse() | | +parse_file() | +----------+----------+ /_\ | +----------+----------+ <> +-----------+ | HTML::TocGenerator + - - - - - -+ HTML::Toc | +---------------------+ +-----------+ +---------------------+ +-----------+ | +extend() | | +clear() | | +extendFromFile() | | +format() | | +generate() | +-----+-----+ | +generateFromFile() | : +----------+----------+ : /_\ : | : +----------+----------+ <> : | HTML::TocInsertor + - - - - - - - - -+ +---------------------+ : +---------------------+ : | +insert() | : | +insertIntoFile() | : +----------+----------+ : /_\ : | : +----------+----------+ <> : | HTML::TocUpdator + - - - - - - - - -+ +---------------------+ +---------------------+ | +insert() | | +insertIntoFile() | | +update() | | +updateFile() | +---------------------+ When generating a ToC you'll have to decide which object you want to use: TocGenerator: for generating a ToC without inserting the ToC into the source TocInsertor: for generating a ToC and inserting the ToC into the source TocUpdator: for generating and inserting a ToC, removing any previously inserted ToC elements Thus in tabular view, each object is capable of: generating inserting updating --------------------------------- TocGenerator X TocInsertor X X TocUpdator X X X =head2 Generating The code underneath will generate a ToC of the HTML headings C<

>..C<

> from a file C: use HTML::Toc; use HTML::TocGenerator; my $toc = HTML::Toc->new(); my $tocGenerator = HTML::TocGenerator->new(); $tocGenerator->generateFromFile($toc, 'index.htm'); print $toc->format(); For example, with C containing:

Chapter

the output will be: =head2 Inserting This code will generate a ToC of HTML headings C<

>..C<

> of file C, and insert the ToC after the C<> tag at the same time: use HTML::Toc; use HTML::TocInsertor; my $toc = HTML::Toc->new(); my $tocInsertor = HTML::TocInsertor->new(); $tocInsertor->insertIntoFile($toc, 'index.htm'); For example, with C containing:

Chapter

the output will be:

Chapter

=head3 Inserting into string By default, C prints both the string and the generated ToC to standard output. To actually insert the ToC in the string, use the L option to specify a scalar reference to insert the ToC into: use HTML::Toc; use HTML::TocInsertor; my $toc = HTML::Toc->new(); my $tocInsertor = HTML::TocInsertor->new(); $html =<

Chapter

HTML $tocInsertor->insert($toc, $html, {'output' => \$html}); print $html; Now the output will be:

Chapter

=head3 Inserting with update tokens If you're planning to update the inserted ToC, you'd better use C to insert the ToC. C marks the inserted ToC elements with update tokens. These update tokens allow C to identify and remove the ToC elements during a future update session. This code uses C instead of C: use HTML::Toc; use HTML::TocUpdator; my $toc = HTML::Toc->new(); my $tocUpdator = HTML::TocUpdator->new(); $tocUpdator->insertIntoFile($toc, 'index.htm'); When applying the code above on 'index.htm':

Chapter

the output will contain additional update tokens: around the inserted ToC elements:

Chapter

Instead of C you can also use C. C will also insert the ToC, whether there is a ToC already inserted or not. =head2 Updating This code will generate a ToC of HTML headings C<

>..C<

> of file C, and insert or update the ToC after the C<> tag at the same time: use HTML::Toc; use HTML::TocUpdator; my $toc = HTML::Toc->new(); my $tocUpdator = HTML::TocUpdator->new(); $tocUpdator->updateFile($toc, 'indexToc.htm'); For example, with C containing: foo bar

Chapter

foo h the output will be:

Chapter

All 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 or C. =head2 Formatting 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{_toc}>. This preliminary, tokenized ToC has to be turned into something useful by calling Cformat()>. For an example, see paragraph 'L'. =head1 Advanced 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 test file. Within this test, a manual containing: preface introduction table of contents table of figures table of tables parts chapters appendixes bibliography is formatted all at once. =head2 Using attribute value as ToC text 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 within the L token. For example, suppose you want to generate a ToC of the C attributes of the following image tokens: First picture Second picture This would be the code: use HTML::Toc; use HTML::TocInsertor; my $toc = HTML::Toc->new(); my $tocInsertor = HTML::TocInsertor->new(); $toc->setOptions({ 'tokenToToc' => [{ 'groupId' => 'image', 'tokenBegin' => '@' }], }); $tocInsertor->insertIntoFile($toc, $filename); and the output will be: First picture Second picture =head2 Generate single ToC of multiple files 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. =head3 Specify an array of files For example, suppose you want to generate a ToC of both C:

Chapter of document 1

and C:

Chapter of document 2

Here's the code to do so by specifying an array of files: use HTML::Toc; use HTML::TocGenerator; my $toc = HTML::Toc->new(); my $tocGenerator = HTML::TocGenerator->new(); $toc->setOptions({'doLinkToFile' => 1}); $tocGenerator->generateFromFile($toc, ['doc1.htm', 'doc2.htm']); print $toc->format(); And the output will be: =head3 Extend an existing ToC It's also possible to extend an existing ToC. For example, suppose we want the generate a ToC of file C:

Chapter of document 1

and extend this ToC with text from C:

Chapter of document 2

Here's the code to do so: use HTML::Toc; use HTML::TocGenerator; my $toc = HTML::Toc->new(); my $tocGenerator = HTML::TocGenerator->new(); $toc->setOptions({'doLinkToFile' => 1}); $tocGenerator->generateFromFile($toc, 'doc1.htm'); $tocGenerator->extendFromFile($toc, 'doc2.htm'); print $toc->format(); And the output will be: =head2 Generate multiple ToCs It's possible to generate multiple ToCs at once by specifying a C 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 image attributes of the following text:

Header One

First picture

Paragraph One

Second picture Here's how you would do so: use HTML::Toc; use HTML::TocInsertor; my $toc1 = HTML::Toc->new(); my $toc2 = HTML::Toc->new(); my $tocInsertor = HTML::TocInsertor->new(); $toc2->setOptions({ 'tokenToToc' => [{ 'groupId' => 'image', 'tokenBegin' => '@' }], }); $tocInsertor->insertIntoFile([$toc1, $toc2], $filename); And the output will be:

Header One

First picture

Paragraph One

Second picture =head2 Generate multiple groups in one ToC You may want to generate a ToC consisting of multiple ToC groups. =head3 Specify an additional 'Appendix' group 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:

Chapter

Paragraph

Subparagraph

Chapter

Appendix Chapter

Appendix Paragraph

With the code underneath: use HTML::Toc; use HTML::TocInsertor; my $toc = HTML::Toc->new(); my $tocInsertor = HTML::TocInsertor->new(); $toc->setOptions({ 'tokenToToc' => [{ 'tokenBegin' => '

' }, { 'tokenBegin' => '

', 'level' => 2 }, { 'groupId' => 'appendix', 'tokenBegin' => '

', }, { 'groupId' => 'appendix', 'tokenBegin' => '

', 'level' => 2 }] }); $tocInsertor->insertIntoFile($toc, $filename); the output will be:

Chapter

Paragraph

Subparagraph

Chapter

Appendix Chapter

Appendix Paragraph

=head3 Specify an additional 'Part' group Suppose you want to generate a ToC of a document which is divided in multiple parts like this file underneath:

First Part

Chapter

Paragraph

Second Part

Chapter

Paragraph

With the code underneath: use HTML::Toc; use HTML::TocInsertor; my $toc = HTML::Toc->new(); my $tocInsertor = HTML::TocInsertor->new(); $toc->setOptions({ 'doNumberToken' => 1, 'tokenToToc' => [{ 'tokenBegin' => '

' }, { 'tokenBegin' => '

', 'level' => 2, }, { 'groupId' => 'part', 'tokenBegin' => '

', 'level' => 1, 'doNumberToken' => 1, 'numberingStyle' => 'upper-alpha' }] }); $tocInsertor->insertIntoFile($toc, $filename); the output will be:

A  First Part

Chapter

Paragraph

B  Second Part

Chapter

Paragraph

=head2 Number ToC entries 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 and L. Or when the ToC isn't a simple numbered list, you can use the numbers generated by HTML::TocGenerator. =head3 Specify numbered list By modifying L and L you can specify a numbered ToC: use HTML::Toc; use HTML::TocGenerator; my $toc = HTML::Toc->new(); my $tocGenerator = HTML::TocGenerator->new(); $toc->setOptions({ 'templateLevelBegin' => '"
    \n"', 'templateLevelEnd' => '"
\n"', }); $tocGenerator->generateFromFile($toc, 'index.htm'); print $toc->format(); For instance with the original file containing:

Chapter

Paragraph

The formatted ToC now will contain C
    instead of C
      tags:
      1. Chapter
        1. Paragraph
      See also: L. =head3 Use generated numbers 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: use HTML::Toc; use HTML::TocGenerator; my $toc = HTML::Toc->new(); my $tocGenerator = HTML::TocGenerator->new(); $toc->setOptions({ 'templateLevel' => '"
    • $node  $text"', }); $tocGenerator->generateFromFile($toc, 'index.htm'); print $toc->format(); For instance with the original file containing:

      Chapter

      Paragraph

      The formatted ToC now will have the node numbers hard-coded: See also: L. =head2 Using CSS for ToC formatting 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:

      Appendix

      Appendix Paragraph

      Appendix

      Appendix Paragraph

      Here's the code: my $toc = new HTML::Toc; my $tocInsertor = new HTML::TocInsertor; $toc->setOptions({ 'templateLevelBegin' => '"
        \n"', 'templateLevelEnd' => '"
      \n"', 'doNumberToken' => 1, 'tokenToToc' => [{ 'groupId' => 'appendix', 'tokenBegin' => '

      ', 'numberingStyle' => 'upper-alpha' }, { 'groupId' => 'appendix', 'tokenBegin' => '

      ', 'level' => 2, }] }); $tocInsertor->insertIntoFile($toc, $filename); Which whill result in the following output:
      1. Appendix
        1. Appendix Paragraph
      2. Appendix
        1. Appendix Paragraph

      A  Appendix

      A.1  Appendix Paragraph

      B  Appendix

      B.1  Appendix Paragraph

      =head2 Creating site map Suppose you want to generate a table of contents of the EtitleE tags of the files in the following directory structure: path file . index.htm, Main |- SubDir1 index.htm, Sub1 | |- SubSubDir1 index.htm, SubSub1 | |- SubDir2 index.htm, Sub2 | |- SubSubDir1 index.htm, SubSub1 | |- SubSubDir2 index.htm, SubSub2 | |- SubDir3 index.htm, Sub3 By specifying 'fileSpec' which determine how many slashes (/) each file may contain for a specific level: use HTML::Toc; use HTML::TocGenerator; use File::Find; my $toc = HTML::Toc->new; my $tocGenerator = HTML::TocGenerator->new; my @fileList; sub wanted { # Add file to 'fileList' if extension matches '.htm' push (@fileList, $File::Find::name) if (m/\.htm$/); } $toc->setOptions({ 'doLinkToFile' => 1, 'templateAnchorName' => '""', 'templateAnchorHref' => '""', 'doLinkTocToToken' => 1, 'tokenToToc' => [{ 'groupId' => 'dir', 'level' => 1, 'tokenBegin' => '', 'tokenEnd' => '', 'fileSpec' => '\./[^/]+$' }, { 'groupId' => 'dir', 'level' => 2, 'tokenBegin' => '', 'tokenEnd' => '', 'fileSpec' => '\./[^/]+?/[^/]+$' }, { 'groupId' => 'dir', 'level' => 3, 'tokenBegin' => '', 'tokenEnd' => '', 'fileSpec' => '\./[^/]+?/[^/]+?/[^/]+$' }] }); # Traverse directory structure find({wanted => \&wanted, no_chdir => 1}, '.'); # Generate ToC of case-insensitively sorted file list $tocGenerator->extendFromFile( $toc, [sort {uc($a) cmp uc($b)} @fileList] ); print $toc->format(); the following ToC will be generated: =head1 Methods =head2 HTML::Toc::clear() syntax: $toc->clear() returns: -- Clear the ToC. =head2 HTML::Toc::format() syntax: $scalar = $toc->format() returns: Formatted ToC. Format tokenized ToC. =head2 HTML::TocGenerator::extend() syntax: $tocGenerator->extend($toc, $string [, $options]) args: - $toc: (reference to array of) HTML::Toc object(s) to extend - $string: string to retrieve ToC from - $options: hash reference containing generator options. Extend ToC from specified string. For available options, see L =head2 HTML::TocGenerator::extendFromFile() syntax: $tocGenerator->extendFromFile($toc, $filename [, $options]) args: - $toc: (reference to array of) HTML::Toc object(s) to extend - $filename: (reference to array of) file(s) to extend ToC from - $options: hash reference containing generator options. Extend ToC from specified file. For available options, see L. For an example, see L. =head2 HTML::TocGenerator::generate() syntax: $tocGenerator->generate($toc, $string [, $options]) args: - $toc: (reference to array of) HTML::Toc object(s) to generate - $string: string to retrieve ToC from - $options: hash reference containing generator options. Generate ToC from specified string. Before generating, the ToC will be cleared. For extending an existing ToC, use the L method. For available options, see L. =head2 HTML::TocGenerator::generateFromFile() syntax: $tocGenerator->generateFromFile($toc, $filename [, $options]) args: - $toc: (reference to array of) HTML::Toc object(s) to generate - $filename: (reference to array of) file(s) to generate ToC from - $options: hash reference containing generator options. Generate ToC from specified file. Before generating, the ToC will be cleared. For extending an extisting ToC, use the L method. For available options, see L. =head2 HTML::TocInsertor::insert() syntax: $tocInsertor->insert($toc, $string [, $options]) args: - $toc: (reference to array of) HTML::Toc object(s) to insert - $string: string to insert ToC in - $options: hash reference containing insertor options. Generate ToC from specified string. The string and the generated ToC are printed to standard output. For available options, see L. NOTE: To actually insert the ToC in the string, use the L option to specify a scalar reference to insert the ToC into. See L for an example. =head2 HTML::TocInsertor::insertIntoFile() syntax: $tocInsertor->insertIntoFile($toc, $filename [, $options]) args: - $toc: (reference to array of) HTML::Toc object(s) to insert - $filename: (reference to array of) file(s) to insert ToC in - $options: hash reference containing insertor options. Insert ToC into specified file. For available options, see L. =head2 HTML::TocUpdator::insert() syntax: $tocUpdator->insert($toc, $string [, $options]) args: - $toc: (reference to array of) HTML::Toc object(s) to insert - $string: string to insert ToC in - $options: hash reference containing updator options. Insert ToC into specified string. Differs from L in that inserted text will be surrounded with update tokens in order for C to be able to update this text the next time an update is issued. See also: L. =head2 HTML::TocUpdator::insertIntoFile() syntax: $tocUpdator->insertIntoFile($toc, $filename [, $options]) args: - $toc: (reference to array of) HTML::Toc object(s) to insert - $filename: (reference to array of) file(s) to insert ToC in - $options: hash reference containing updator options. Insert ToC into specified file. Differs from L in that inserted text will be surrounded with update tokens in order for C to be able to update this text the next time an update is issued. For updator options, see L. =head2 HTML::TocUpdator::update() syntax: $tocUpdator->update($toc, $string [, $options]) args: - $toc: (reference to array of) HTML::Toc object(s) to insert - $string: string to update ToC in - $options: hash reference containing updator options. Update ToC within specified string. For updator options, see L. =head2 HTML::TocUpdator::updateFile() syntax: $tocUpdator->updateFile($toc, $filename [, $options]) args: - $toc: (reference to array of) HTML::Toc object(s) to insert - $filename: (reference to array of) file(s) to update ToC in - $options: hash reference containing updator options. Update ToC of specified file. For updator options, see L. =head1 Parser Options When generating a ToC, additional options may be specified which influence the way the ToCs are generated using either C, C or C. The options must be specified as a hash reference. For example: $tocGenerator->generateFromFile($toc, $filename, {doUseGroupsGlobal => 1}); Available options are: =over 4 =item * L =item * L =item * L =item * L =back =head2 doGenerateToc syntax: [0|1] default: 1 applicable to: TocInsertor, TocUpdator True (1) if ToC must be generated. False (0) if ToC must be inserted only. =head2 doUseGroupsGlobal syntax: [0|1] default: 0 applicable to: TocGenerator, TocInsertor, TocUpdator 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':

      Chapter

      Paragraph

      Using the default setting of 'doUseGroupsGlobal' => 0: use HTML::Toc; use HTML::TocGenerator; my $toc1 = HTML::Toc->new(); my $toc2 = HTML::Toc->new(); my $tocGenerator = HTML::TocGenerator->new(); $toc1->setOptions({ 'header' => '', 'footer' => '', 'tokenToToc' => [{'tokenBegin' => '

      '}] }); $toc2->setOptions({ 'header' => '', 'footer' => '', 'tokenToToc' => [{'tokenBegin' => '

      '}] }); $tocGenerator->generateFromFile([$toc1, $toc2], 'index.htm'); print $toc1->format() . "\n\n" . $toc2->format(); the output will be: Each ToC will use its own numbering scheme. Now if 'C' is specified: $tocGenerator->generateFromFile( [$toc1, $toc2], 'index.htm', {'doUseGroupsGlobal' => 1} ); the output will be: using a global numbering scheme for all ToCs. =head2 output syntax: reference to scalar default: none applicable to: TocInsertor, TocUpdator Reference to scalar where the output must be stored in. =head2 outputFile syntax: scalar default: none applicable to: TocInsertor, TocUpdator Filename to write output to. If no filename is specified, output will be written to standard output. =head1 HTML::Toc Options The C options can be grouped in the following categories: =over 4 =item * L =item * L =item * L =item * L =back The ToC options must be specified using the 'setOptions' method. For example: my $toc = new HTML::Toc; $toc->setOptions({ 'doNumberToken' => 1, 'footer' => '' 'tokenToToc' => [{ 'level' => 1, 'tokenBegin' => '

      ', 'numberingStyle' => 'lower-alpha' }] }); =head2 Generate options =over 4 =item * Token groups =over 4 =item * L =over 4 =item * L =item * L =item * L =item * L =item * L =item * L =item * L =back =item * L =item * L =back =item * Numbering tokens =over 4 =item * L =item * L =item * L =back =item * Miscellaneous =over 4 =item * L =item * L =item * L =item * L =back =item * Linking ToC to tokens =over 4 =item * L =item * L =item * L =item * L =item * L =item * L =item * L =item * L =back =back =head2 Insert options =over 4 =item * L =back =head2 Update options =over 4 =item * L =item * L =item * L =item * L =item * L =item * L =back =head2 Format options =over 4 =item * L =item * L =item * L =item * L =item * L =item * L =item * L =item * L =item * L =item * L =item * L =back =head1 HTML::Toc Options Reference =head2 attributeToExcludeToken syntax: $scalar default: '-' Token which marks an attribute value in a L or L token as an attribute value a token should not have to be marked as a ToC token. See also: L. =head2 attributeToTocToken syntax: $scalar default: '@' Token which marks an attribute in a L token as an attribute which must be used as ToC text. See also: L. =head2 doLinkToToken syntax: [0|1] default: 1 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. =head2 doLinkToFile syntax: [0|1] default: 0 True (1) if ToC must be linked to file, False (0) if not. In effect only when L equals True (1) and L isn't specified. =head2 doLinkToId syntax: [0|1] default: 0 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. =head2 doNestGroup syntax: [0|1] default: 0 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 setting. For an example, see L. =head2 doNumberToken syntax: [0|1] default: 0 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 group. When specified within a C option, the C applies to that group only. For an example, see L. =head2 doSingleStepLevel syntax: [0|1] default: 1 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':

      Chapter

      Paragraph

      By default, an empty indentation level will be inserted in the ToC: After specifying: $toc->setOptions({'doSingleStepLevel' => 0}); the ToC will not have an indentation level inserted for level 2: =head2 fileSpec syntax: default: undef Specifies which files should match the current level. Valid only if L equals 1. For an example, see L. =head2 footer syntax: $scalar default: "\n\n" String to output at end of ToC. =head2 groupId syntax: $scalar default: 'h' 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: $toc->setOptions({ 'tokenToToc' => [{ 'tokenBegin' => '

      ' }, { 'groupId' => 'appendix', 'tokenBegin' => '

      ' }] }); =head2 groupToToc syntax: default: '.*' Determines which groups to use for generating the ToC. For example, to create a ToC for groups [a-b] only, specify: 'groupToToc => '[a-b]' 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: $toc->setOptions({'groupToToc' => '.*'}); $tocGenerator->generateToc($toc, ...); # Get ToC of all groups $fullToc = $toc->format(); # Get ToC of 'appendix' group only $toc->setOptions({'groupToToc' => 'appendix'}); $appendixToc = $toc->format(); =head2 header syntax: $scalar default: "\n\n" String to output at begin of ToC. =head2 insertionPoint syntax: [] default: 'after ' token: <[/]tag{ attribute=[-|@]}> | | | 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<

      > tag as insertion point: '

      ' Examples of valid 'insertionPoint' tokens are: '

      ' '

      ' '' '' 'ToC will be placed here' It is also possible to specify attributes to exclude, by prefixing the value with an L, default a minus sign (-). For example, to specify the C<

      > tag as insertion point, excluding all C<

      > tags: '

      ' See also L. =head2 level syntax: number default: 1 Number which identifies at which level the tokengroup should be incorporated into the ToC. See also: L. =head2 levelIndent syntax: number default: 3 Sets the number of spaces each level will be indented, when formatting the ToC. =head2 levelToToc syntax: default: '.*' Determines which group levels to use for generating the ToC. For example, to create a ToC for levels 1-2 only, specify: 'levelToToc => '[1-2]' 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: $toc->setOptions({'levelToToc' => '.*'}); $tocGenerator->generateToc($toc, ...); # Get ToC of all levels $fullToc = $toc->getToc(); # Get ToC of level 1 only $toc->setOptions({'levelToToc' => '1'}); $level1Toc = $toc->getToc(); =head2 numberingStyle syntax: [decimal|lower-alpha|upper-alpha|lower-roman|upper-roman]} default: decimal Determines which numbering style to use for a token group when L 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.: $toc->setOptions({ 'doNumberToken' => 1, 'tokenToToc' => [{ 'level' => 1, 'tokenBegin' => '

      ', 'numberingStyle' => 'lower-alpha' }] }); If C style is specified, be sure to have the Roman module installed, available from L. =head2 templateAnchorName syntax: default: '$groupId."-".$node' Anchor name to use when L is set to True (1). The anchor name is passed to both L and L. The template may be specified as either an expression or a function reference. The expression may contain the following variables: $file $groupId $level $node $text E.g. with "

      Intro

      ", $text = "Intro" $children Text, including HTML child elements. E.g. with "

      Intro

      ", $children = "Intro" If C is a function reference to a function returning the anchor, like in: $toc->setOptions({'templateAnchorName' => \&assembleAnchorName}); the function will be called with the following arguments: $anchorName = assembleAnchorName($file, $groupId, $level, $node, $text, $children); =head2 templateAnchorHrefBegin syntax: default: '""' or '""', depending on 'doLinkToFile' being 0 or 1 respectively. Anchor reference begin token to use when L 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: $file $groupId $level $node $anchorName If C is a function reference to a function returning the anchor, like in: $toc->setOptions({'templateAnchorHrefBegin' => \&assembleAnchorHrefBegin}); the function will be called with the following arguments: $anchorHrefBegin = &assembleAnchorHrefBegin( $file, $groupId, $level, $node, $anchorName ); See also: L, L. =head2 templateAnchorHrefEnd syntax: default: '""' Anchor reference end token to use when L is set to True (1). The template may be specified as either an expression or a function reference. If L is a function reference to a function returning the anchor end, like in: $toc->setOptions({'templateAnchorHrefEnd' => \&assembleAnchorHrefEnd}); the function will be called without arguments: $anchorHrefEnd = &assembleAnchorHrefEnd; See also: L. =head2 templateAnchorNameBegin syntax: default: '""' Anchor name begin token to use when L 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: $file $groupId $level $node $anchorName If C is a function reference to a function returning the anchor name, like in: $toc->setOptions({'templateAnchorNameBegin' => \&assembleAnchorNameBegin}); the function will be called with the following arguments: $anchorNameBegin = assembleAnchorNameBegin( $file, $groupId, $level, $node, $anchorName ); See also: L, L. =head2 templateAnchorNameEnd syntax: default: '""' Anchor name end token to use when L is set to True (1). The template may be specified as either an expression or a function reference. If L is a function reference to a function returning the anchor end, like in: $toc->setOptions({'templateAnchorNameEnd' => \&assembleAnchorNameEnd}); the function will be called without arguments: $anchorNameEnd = &assembleAnchorNameEnd; See also: L. =head2 templateLevel syntax: default: '"
    • $text"' 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: $level $groupId $node $sequenceNr $text If C is a function reference to a function returning the ToC node, like in: $toc->setOptions({'templateLevel' => \&AssembleTocNode}); the function will be called with the following arguments: $tocNode = &AssembleTocNode( $level, $groupId, $node, $sequenceNr, $text ); =head2 templateLevelClose syntax: default: '"
    • \n"' Expression to use when formatting a ToC node. The template may be specified as either an expression or a function reference. =head2 templateLevelBegin syntax: default: '"
        \n"' Expression to use when formatting begin of ToC level. See L 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: '"
          \n"' which will result in each ToC group given a class name:
          • Header
          For an example, see L. =head2 templateLevelEnd syntax: default: '"
        \n"' Expression to use when formatting end of ToC level. See L for a list of available variables to use within the expression. The default expression is: '"
      \n"' For an example, see L. =head2 templateTokenNumber syntax: default: '"$node  "' Token number to use when L equals True (1). The template may be specified as either an expression or a function reference. The expression has access to the following variables: $file $groupId $groupLevel $level $node $toc If C is a function reference to a function returning the token number, like in: $toc->setOptions({'templateTokenNumber' => \&assembleTokenNumber}); the function will be called with the following arguments: $number = &assembleTokenNumber( $node, $groupId, $file, $groupLevel, $level, $toc ); =head2 tokenBegin syntax: default: '

      ' token: <[/]tag{ attribute=[-|@]}> | | | 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: '

      ' '' '' '' 'ToC entry' When 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<

      > tag as tokenBegin: '

      ' It is also possible to specify attributes to exclude, by prefixing the value with an L, default a minus sign (-). For example, to specify the C<

      > tag as tokenBegin, excluding all C<

      > tags: '

      ' Also, you can specify here an attribute value which has to be used as ToC text, by prefixing the value with an L, default an at sign (@). For example, to use the class value as ToC text: '

      ' See L for an elaborated example using the C to generate a ToC of image C attribute values. See also: L, L. =head2 tokenEnd syntax: $scalar default: empty string ('') or end tag counterpart of 'tokenBegin' if 'tokenBegin' is a start tag The 'tokenEnd' definition applies to the same rules as L. See also: L, L. =head2 tokenToToc syntax: [{array of hashrefs}] default: [{ 'level' => 1, 'tokenBegin' => '

      ' }, { 'level' => 2, 'tokenBegin' => '

      ' }, { 'level' => 3, 'tokenBegin' => '

      ' }, { 'level' => 4, 'tokenBegin' => '

      ' }, { 'level' => 5, 'tokenBegin' => '

      ' }, { 'level' => 6, 'tokenBegin' => '
      ' }] This hash defines the tokens that must act as ToC entries. Each tokengroup may contain a L, L, L, L and L identifier. =head2 tokenUpdateBeginAnchorName syntax: default: ''; This token marks the begin of an anchor name, inserted by C. This option is used by C. =head2 tokenUpdateEndAnchorName syntax: default: ''; This option is used by C, to mark the end of an inserted anchor name. =head2 tokenUpdateBeginNumber syntax: default: ''; This option is used by C, to mark the begin of an inserted number. =head2 tokenUpdateEndNumber syntax: default: ''; This option is used by C, to mark the end of an inserted number. =head2 tokenUpdateBeginToc syntax: default: ''; This option is used by C, to mark the begin of an inserted ToC. =head2 tokenUpdateEndToc syntax: default: ''; This option is used by C, to mark the end of an inserted ToC. =head1 Known issues =head2 Cygwin In 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. 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. =head1 AUTHOR Freddy Vulto EL<"fvulto@gmail.com">E =head1 COPYRIGHT Copyright (c) 2009 Freddy Vulto. All rights reserved. This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =cut