libvpx: Pull from upstream

source/libvpx/examples/includes/HTML-Toc-0.91/TocInsertor.pm

Index: source/libvpx/examples/includes/HTML-Toc-0.91/TocInsertor.pm
===================================================================
--- source/libvpx/examples/includes/HTML-Toc-0.91/TocInsertor.pm	(revision 247498)
+++ source/libvpx/examples/includes/HTML-Toc-0.91/TocInsertor.pm	(working copy)
@@ -1,1066 +0,0 @@
-#--- TocInsertor.pm -----------------------------------------------------------
-# function: Insert Table of Contents HTML::Toc, generated by 
-#           HTML::TocGenerator.
-# note:     - The term 'propagate' is used as a shortcut for the process of 
-#             both generating and inserting a ToC at the same time.
-#           - 'TIP' is an abbreviation of 'Toc Insertion Point'.
-
-
-package HTML::TocInsertor;
-
-
-use strict;
-use FileHandle;
-use HTML::TocGenerator;
-
-
-BEGIN {
-	use vars qw(@ISA $VERSION);
-
-	$VERSION = '0.91';
-
-	@ISA = qw(HTML::TocGenerator);
-}
-
-	# TocInsertionPoint (TIP) constants
-	
-use constant TIP_PREPOSITION_REPLACE => 'replace';
-use constant TIP_PREPOSITION_BEFORE  => 'before';
-use constant TIP_PREPOSITION_AFTER   => 'after';
-
-use constant TIP_TOKEN_ID           => 0;
-use constant TIP_PREPOSITION        => 1;
-use constant TIP_INCLUDE_ATTRIBUTES => 2;
-use constant TIP_EXCLUDE_ATTRIBUTES => 3;
-use constant TIP_TOC                => 4;
-
-use constant MODE_DO_NOTHING   => 0;	# 0b00
-use constant MODE_DO_INSERT    => 1;	# 0b01
-use constant MODE_DO_PROPAGATE => 3;	# 0b11
-
-END {}
-
-
-#--- HTML::TocInsertor::new() -------------------------------------------------
-# function: Constructor.
-
-sub new {
-		# Get arguments
-	my ($aType) = @_;
-	my $self = $aType->SUPER::new;
-		# TRUE if insertion point token must be output, FALSE if not
-	$self->{_doOutputInsertionPointToken} = 1;
-		# Reset batch variables
-	$self->_resetBatchVariables;
-		# Bias to not insert ToC
-	$self->{hti__Mode} = MODE_DO_NOTHING;
-
-		# TODO: Initialize output
-
-	return $self;
-}  # new()
-
-
-#--- HTML::TocInsertor::_deinitializeOutput() ---------------------------------
-# function: Deinitialize output.
-
-sub _deinitializeOutput {
-		# Get arguments
-	my ($self) = @_;
-		# Filehandle is defined?
-	if (defined($self->{_outputFileHandle})) {
-		# Yes, filehandle is defined;
-			# Restore selected filehandle
-		select($self->{_oldFileHandle});
-			# Undefine filehandle, closing it automatically
-		undef $self->{_outputFileHandle};
-	}
-}  # _deinitializeOutput()
-
-
-#--- HTML::TocInsertor::_initializeOutput() -----------------------------------
-# function: Initialize output.
-
-sub _initializeOutput {
-		# Get arguments
-	my ($self) = @_;
-		# Bias to write to outputfile
-	my $doOutputToFile = 1;
-
-		# Is output specified?
-	if (defined($self->{options}{'output'})) {
-		# Yes, output is specified;
-			# Indicate to not output to outputfile
-		$doOutputToFile = 0;
-			# Alias output reference
-		$self->{_output} = $self->{options}{'output'};
-			# Clear output
-		${$self->{_output}} = "";
-	}
-
-		# Is output file specified?
-	if (defined($self->{options}{'outputFile'})) {
-		# Yes, output file is specified;
-			# Indicate to output to outputfile
-		$doOutputToFile = 1;
-			# Open file
-		$self->{_outputFileHandle} = 
-			new FileHandle ">" . $self->{options}{'outputFile'};
-
-			# Backup currently selected filehandle
-		$self->{_oldFileHandle} = select;
-			# Set new default filehandle
-		select($self->{_outputFileHandle});
-	}
-
-		# Alias output-to-file indicator
-	$self->{_doOutputToFile} = $doOutputToFile;
-}  # _initializeOutput()
-
-
-#--- HTML::TocInsertor::_deinitializeInsertorBatch() --------------------------
-# function: Deinitialize insertor batch.
-
-sub _deinitializeInsertorBatch {
-		# Get arguments
-	my ($self) = @_;
-		# Indicate ToC insertion has finished
-	$self->{_isTocInsertionPointPassed} = 0;
-		# Write buffered output
-	$self->_writeBufferedOutput();
-		# Propagate?
-	if ($self->{hti__Mode} == MODE_DO_PROPAGATE) {
-		# Yes, propagate;
-			# Deinitialize generator batch
-		$self->_deinitializeGeneratorBatch();
-	}
-	else {
-		# No, insert only;
-			# Do general batch deinitialization
-		$self->_deinitializeBatch();
-	}
-		# Deinitialize output
-	$self->_deinitializeOutput();
-		# Indicate end of batch
-	$self->{hti__Mode} = MODE_DO_NOTHING;
-		# Reset batch variables
-	$self->_resetBatchVariables();
-}  # _deinitializeInsertorBatch()
-
-
-#--- HTML::TocInsertor::_initializeInsertorBatch() ----------------------------
-# function: Initialize insertor batch.
-# args:     - $aTocs: Reference to array of tocs.
-#           - $aOptions: optional options
-
-sub _initializeInsertorBatch {
-		# Get arguments
-	my ($self, $aTocs, $aOptions) = @_;
-		# Add invocation options
-	$self->setOptions($aOptions);
-		# Option 'doGenerateToc' specified?
-	if (!defined($self->{options}{'doGenerateToc'})) {
-		# No, options 'doGenerateToc' not specified;
-			# Default to 'doGenerateToc'
-		$self->{options}{'doGenerateToc'} = 1;
-	}
-		# Propagate?
-	if ($self->{options}{'doGenerateToc'}) {
-		# Yes, propagate;
-			# Indicate mode
-		$self->{hti__Mode} = MODE_DO_PROPAGATE;
-			# Initialize generator batch
-			# NOTE: This method takes care of calling '_initializeBatch()'
-		$self->_initializeGeneratorBatch($aTocs);
-	}
-	else {
-		# No, insert;
-			# Indicate mode
-		$self->{hti__Mode} = MODE_DO_INSERT;
-			# Do general batch initialization
-		$self->_initializeBatch($aTocs);
-	}
-		# Initialize output
-	$self->_initializeOutput();
-		# Parse ToC insertion points
-	$self->_parseTocInsertionPoints();
-}  # _initializeInsertorBatch()
-
-
-#--- HTML::TocInsertor::_insert() ---------------------------------------------
-# function: Insert ToC in string.
-# args:     - $aString: Reference to string to parse.
-# note:     Used internally.
-
-sub _insert {
-		# Get arguments
-	my ($self, $aString) = @_;
-		# Propagate?
-	if ($self->{options}{'doGenerateToc'}) {
-		# Yes, propagate;
-			# Generate & insert ToC
-		$self->_generate($aString);
-	}
-	else {
-		# No, just insert ToC
-			# Insert by parsing file
-		$self->parse($aString);
-			# Flush remaining buffered text
-		$self->eof();
-	}
-}  # _insert()
-
-
-#--- HTML::TocInsertor::_insertIntoFile() -------------------------------------
-# function: Do insert generated ToCs in file.
-# args:     - $aToc: (reference to array of) ToC object(s) to insert.
-#           - $aFile: (reference to array of) file(s) to parse for insertion
-#                points.
-#           - $aOptions: optional insertor options
-# note:     Used internally.
-
-sub _insertIntoFile {
-		# Get arguments
-	my ($self, $aFile) = @_;
-		# Local variables;
-	my ($file, @files);
-		# Dereference array reference or make array of file specification
-	@files = (ref($aFile) =~ m/ARRAY/) ? @$aFile : ($aFile);
-		# Loop through files
-	foreach $file (@files) {
-			# Propagate?
-		if ($self->{options}{'doGenerateToc'}) {
-			# Yes, propagate;
-				# Generate and insert ToC
-			$self->_generateFromFile($file);
-		}
-		else {
-			# No, just insert ToC
-				# Insert by parsing file
-			$self->parse_file($file);
-		}
-	}
-}  # _insertIntoFile()
-
-
-#--- HTML::TocInsertor::_parseTocInsertionPoints() ----------------------------
-# function: Parse ToC insertion point specifier.
-
-sub _parseTocInsertionPoints {
-		# Get arguments
-	my ($self) = @_;
-		# Local variables
-	my ($tipPreposition, $tipToken, $toc, $tokenTipParser);
-		# Create parser for TIP tokens
-	$tokenTipParser = HTML::_TokenTipParser->new(
-		$self->{_tokensTip}
-	);
-		# Loop through ToCs
-	foreach $toc (@{$self->{_tocs}}) {
-			# Split TIP in preposition and token
-		($tipPreposition, $tipToken) = split(
-			'\s+', $toc->{options}{'insertionPoint'}, 2
-		);
-			# Known preposition?
-		if (
-			($tipPreposition ne TIP_PREPOSITION_REPLACE) &&
-			($tipPreposition ne TIP_PREPOSITION_BEFORE) &&
-			($tipPreposition ne TIP_PREPOSITION_AFTER)
-		) {
-			# No, unknown preposition;
-				# Use default preposition
-			$tipPreposition = TIP_PREPOSITION_AFTER;
-				# Use entire 'insertionPoint' as token
-			$tipToken = $toc->{options}{'insertionPoint'};
-		}
-			# Indicate current ToC to parser
-		$tokenTipParser->setToc($toc);
-			# Indicate current preposition to parser
-		$tokenTipParser->setPreposition($tipPreposition);
-			# Parse ToC Insertion Point
-		$tokenTipParser->parse($tipToken);
-			# Flush remaining buffered text
-		$tokenTipParser->eof();
-	}
-}  # _parseTocInsertionPoints()
-
-
-#--- HTML::TocInsertor::_processTokenAsInsertionPoint() -----------------------
-# function: Check for token being a ToC insertion point (Tip) token and
-#           process it accordingly.
-# args:     - $aTokenType: type of token: start, end, comment or text.
-#           - $aTokenId: token id of currently parsed token
-#           - $aTokenAttributes: attributes of currently parsed token
-#           - $aOrigText: complete token
-# returns:  1 if successful -- token is processed as insertion point, 0
-#           if not.
-
-sub _processTokenAsInsertionPoint {
-		# Get arguments
-	my ($self, $aTokenType, $aTokenId, $aTokenAttributes, $aOrigText) = @_;
-		# Local variables
-	my ($i, $result, $tipToken, $tipTokenId, $tipTokens);
-		# Bias to token not functioning as a ToC insertion point (Tip) token
-	$result = 0;
-		# Alias ToC insertion point (Tip) array of right type
-	$tipTokens = $self->{_tokensTip}[$aTokenType];
-		# Loop through tipTokens
-	$i = 0;
-	while ($i < scalar @{$tipTokens}) {
-			# Aliases
-		$tipToken			         = $tipTokens->[$i];
-		$tipTokenId			         = $tipToken->[TIP_TOKEN_ID];
-			# Id & attributes match?
-		if (
-			($aTokenId =~ m/$tipTokenId/) && (
-				HTML::TocGenerator::_doesHashContainHash(
-					$aTokenAttributes, $tipToken->[TIP_INCLUDE_ATTRIBUTES], 0
-				) &&
-				HTML::TocGenerator::_doesHashContainHash(
-					$aTokenAttributes, $tipToken->[TIP_EXCLUDE_ATTRIBUTES], 1
-				)
-			)
-		) {
-			# Yes, id and attributes match;
-				# Process ToC insertion point
-			$self->_processTocInsertionPoint($tipToken);
-				# Indicate token functions as ToC insertion point
-			$result = 1;
-				# Remove Tip token, automatically advancing to next token
-			splice(@$tipTokens, $i, 1);
-		}
-		else {
-			# No, tag doesn't match ToC insertion point
-				# Advance to next start token
-			$i++;
-		}
-	}
-		# Token functions as ToC insertion point?
-	if ($result) {
-		# Yes, token functions as ToC insertion point;
-			# Process insertion point(s)
-		$self->_processTocInsertionPoints($aOrigText);
-	}
-		# Return value
-	return $result;
-}  # _processTokenAsInsertionPoint()
-
-
-#--- HTML::TocInsertor::toc() -------------------------------------------------
-# function: Toc processing method.  Add toc reference to scenario.
-# args:     - $aScenario: Scenario to add ToC reference to.
-#           - $aToc: Reference to ToC to insert.
-# note:     The ToC hasn't been build yet; only a reference to the ToC to be
-#           build is inserted.
-
-sub toc {
-		# Get arguments
-	my ($self, $aScenario, $aToc) = @_;
-		# Add toc to scenario
-	push(@$aScenario, $aToc);
-}  # toc()
-
-
-#--- HTML::TocInsertor::_processTocInsertionPoint() ----------------------------
-# function: Process ToC insertion point.
-# args:     - $aTipToken: Reference to token array item which matches the ToC 
-#                insertion point.
-
-sub _processTocInsertionPoint {
-		# Get arguments
-	my ($self, $aTipToken) = @_;
-		# Local variables
-	my ($tipToc, $tipPreposition); 
-	
-		# Aliases
-	$tipToc         = $aTipToken->[TIP_TOC];
-	$tipPreposition = $aTipToken->[TIP_PREPOSITION];
-
-	SWITCH: {
-			# Replace token with ToC?
-		if ($tipPreposition eq TIP_PREPOSITION_REPLACE) {
-			# Yes, replace token;
-				# Indicate ToC insertion point has been passed
-			$self->{_isTocInsertionPointPassed} = 1;
-				# Add ToC reference to scenario reference by calling 'toc' method
-			$self->toc($self->{_scenarioAfterToken}, $tipToc);
-			#push(@{$self->{_scenarioAfterToken}}, $tipTokenToc);
-				# Indicate token itself must not be output
-			$self->{_doOutputInsertionPointToken} = 0;
-			last SWITCH;
-		}
-			# Output ToC before token?
-		if ($tipPreposition eq TIP_PREPOSITION_BEFORE) {
-			# Yes, output ToC before token;
-				# Indicate ToC insertion point has been passed
-			$self->{_isTocInsertionPointPassed} = 1;
-				# Add ToC reference to scenario reference by calling 'toc' method
-			$self->toc($self->{_scenarioBeforeToken}, $tipToc);
-			#push(@{$self->{_scenarioBeforeToken}}, $tipTokenToc);
-			last SWITCH;
-		}
-			# Output ToC after token?
-		if ($tipPreposition eq TIP_PREPOSITION_AFTER) {
-			# Yes, output ToC after token;
-				# Indicate ToC insertion point has been passed
-			$self->{_isTocInsertionPointPassed} = 1;
-				# Add ToC reference to scenario reference by calling 'toc' method
-			$self->toc($self->{_scenarioAfterToken}, $tipToc);
-			#push(@{$self->{_scenarioAfterToken}}, $tipTokenToc);
-			last SWITCH;
-		}
-	}
-}  # _processTocInsertionPoint()
-
-
-#--- HTML::TocInsertor::_processTocInsertionPoints() --------------------------
-# function: Process ToC insertion points
-# args:     - $aTokenText: Text of token which acts as insertion point for one
-#                or multiple ToCs.
-
-sub _processTocInsertionPoints {
-		# Get arguments
-	my ($self, $aTokenText) = @_;
-		# Local variables
-	my ($outputPrefix, $outputSuffix);
-		# Extend scenario
-	push(@{$self->{_scenario}}, @{$self->{_scenarioBeforeToken}});
-
-	if ($outputPrefix = $self->{_outputPrefix}) {
-		push(@{$self->{_scenario}}, \$outputPrefix);
-		$self->{_outputPrefix} = "";
-	}
-
-		# Must insertion point token be output?
-	if ($self->{_doOutputInsertionPointToken}) {
-		# Yes, output insertion point token;
-		push(@{$self->{_scenario}}, \$aTokenText);
-	}
-
-	if ($outputSuffix = $self->{_outputSuffix}) {
-		push(@{$self->{_scenario}}, \$outputSuffix);
-		$self->{_outputSuffix} = "";
-	}
-
-	push(@{$self->{_scenario}}, @{$self->{_scenarioAfterToken}});
-		# Add new act to scenario for output to come
-	my $output = "";
-	push(@{$self->{_scenario}}, \$output);
-		# Write output, processing possible '_outputSuffix'
-	#$self->_writeOrBufferOutput("");
-		# Reset helper scenario's
-	$self->{_scenarioBeforeToken} = [];
-	$self->{_scenarioAfterToken}  = [];
-		# Reset bias value to output insertion point token
-	$self->{_doOutputInsertionPointToken} = 1;
-
-}  # _processTocInsertionPoints()
-
-
-#--- HTML::Toc::_resetBatchVariables() ----------------------------------------
-# function: Reset batch variables.
-
-sub _resetBatchVariables {
-	my ($self) = @_;
-		# Call ancestor
-	$self->SUPER::_resetBatchVariables();
-		# Array containing references to scalars.  This array depicts the order
-		# in which output must be performed after the first ToC Insertion Point
-		# has been passed.
-	$self->{_scenario}            = [];
-		# Helper scenario
-	$self->{_scenarioBeforeToken} = [];
-		# Helper scenario
-	$self->{_scenarioAfterToken}  = [];
-		# Arrays containing start, end, comment, text & declaration tokens which 
-		# must trigger the ToC insertion.  Each array element may contain a 
-		# reference to an array containing the following elements:
-	$self->{_tokensTip} = [
-		[],	# TT_TOKENTYPE_START
-		[],	# TT_TOKENTYPE_END
-		[],	# TT_TOKENTYPE_COMMENT
-		[],	# TT_TOKENTYPE_TEXT
-		[]		# TT_TOKENTYPE_DECLARATION
-	];
-		# 1 if ToC insertion point has been passed, 0 if not
-	$self->{_isTocInsertionPointPassed} = 0;
-		# Tokens after ToC
-	$self->{outputBuffer} = "";
-		# Trailing text after parsed token
-	$self->{_outputSuffix} = "";
-		# Preceding text before parsed token
-	$self->{_outputPrefix} = "";
-}  # _resetBatchVariables()
-
-
-#--- HTML::TocInsertor::_writeBufferedOutput() --------------------------------
-# function: Write buffered output to output device(s).
-
-sub _writeBufferedOutput {
-		# Get arguments
-	my ($self) = @_;
-		# Local variables
-	my ($scene);
-		# Must ToC be parsed?
-	if ($self->{options}{'parseToc'}) {
-		# Yes, ToC must be parsed;
-			# Parse ToC
-		#$self->parse($self->{toc});
-			# Output tokens after ToC
-		#$self->_writeOrBufferOutput($self->{outputBuffer});
-	}
-	else {
-		# No, ToC needn't be parsed;
-			# Output scenario
-		foreach $scene (@{$self->{_scenario}}) {
-				# Is scene a reference to a scalar?
-			if (ref($scene) eq "SCALAR") {
-				# Yes, scene is a reference to a scalar;
-					# Output scene
-				$self->_writeOutput($$scene);
-			}
-			else {
-				# No, scene must be reference to HTML::Toc;
-					# Output toc
-				$self->_writeOutput($scene->format());
-			}
-		}
-	}
-}  # _writeBufferedOutput()
-
-
-#--- HTML::TocInsertor::_writeOrBufferOutput() --------------------------------
-# function: Write processed HTML to output device(s).
-# args:     - aOutput: scalar to write
-# note:     If '_isTocInsertionPointPassed' text is buffered before being 
-#           output because the ToC has to be generated before it can be output.
-#           Only after the entire data has been parsed, the ToC and the 
-#           following text will be output.
-
-sub _writeOrBufferOutput {
-		# Get arguments
-	my ($self, $aOutput) = @_;
-
-		# Add possible output prefix and suffix
-	$aOutput = $self->{_outputPrefix} . $aOutput . $self->{_outputSuffix};
-		# Clear output prefix and suffix
-	$self->{_outputPrefix} = "";
-	$self->{_outputSuffix} = "";
-
-		# Has ToC insertion point been passed?
-	if ($self->{_isTocInsertionPointPassed}) {
-		# Yes, ToC insertion point has been passed;
-			# Buffer output; add output to last '_scenario' item
-		my $index = scalar(@{$self->{_scenario}}) - 1;
-		${$self->{_scenario}[$index]} .= $aOutput;
-	}
-	else {
-		# No, ToC insertion point hasn't been passed;
-			# Write output
-		$self->_writeOutput($aOutput);
-	}
-}  # _writeOrBufferOutput()
-
-
-#--- HTML::TocInsertor::_writeOutput() ----------------------------------------
-# function: Write processed HTML to output device(s).
-# args:     - aOutput: scalar to write
-
-sub _writeOutput {
-		# Get arguments
-	my ($self, $aOutput) = @_;
-		# Write output to scalar;
-	${$self->{_output}} .= $aOutput if (defined($self->{_output}));
-		# Write output to output file
-	print $aOutput if ($self->{_doOutputToFile})
-}  # _writeOutput()
-
-
-#--- HTML::TocGenerator::anchorId() -------------------------------------------
-# function: Anchor id processing method.
-# args:     - $aAnchorId
-
-sub anchorId {
-		# Get arguments
-	my ($self, $aAnchorId) = @_;
-		# Indicate id must be added to start tag
-	$self->{_doAddAnchorIdToStartTag} = 1;
-	$self->{_anchorId} = $aAnchorId;
-}  # anchorId()
-
-
-#--- HTML::TocInsertor::anchorNameBegin() -------------------------------------
-# function: Process anchor name begin, generated by HTML::TocGenerator.
-# args:     - $aAnchorNameBegin: Anchor name begin tag to output.
-#           - $aToc: Reference to ToC to which anchorname belongs.
-
-sub anchorNameBegin {
-		# Get arguments
-	my ($self, $aAnchorNameBegin, $aToc) = @_;
-		# Is another anchorName active?
-	if (defined($self->{_activeAnchorName})) {
-		# Yes, another anchorName is active;
-			# Show warning
-		print "Warn\n";
-		$self->_showWarning(
-			HTML::TocGenerator::WARNING_NESTED_ANCHOR_PS_WITHIN_PS,
-			[$aAnchorNameBegin, $self->{_activeAnchorName}]
-		);
-	}
-		# Store anchor name as output prefix
-	$self->{_outputPrefix} = $aAnchorNameBegin;
-		# Indicate active anchor name
-	$self->{_activeAnchorName} = $aAnchorNameBegin;
-		# Indicate anchor name end must be output
-	$self->{_doOutputAnchorNameEnd} = 1;
-}	# anchorNameBegin()
-
-
-#--- HTML::TocInsertor::anchorNameEnd() ---------------------------------------
-# function: Process anchor name end, generated by HTML::TocGenerator.
-# args:     - $aAnchorNameEnd: Anchor name end tag to output.
-#           - $aToc: Reference to ToC to which anchorname belongs.
-
-sub anchorNameEnd {
-		# Get arguments
-	my ($self, $aAnchorNameEnd) = @_;
-		# Store anchor name as output prefix
-	$self->{_outputSuffix} .= $aAnchorNameEnd;
-		# Indicate deactive anchor name
-	$self->{_activeAnchorName} = undef;
-}	# anchorNameEnd()
-
-
-#--- HTML::TocInsertor::comment() ---------------------------------------------
-# function: Process comment.
-# args:     - $aComment: comment text with '<!--' and '-->' tags stripped off.
-
-sub comment {
-		# Get arguments
-	my ($self, $aComment) = @_;
-		# Local variables
-	my ($tocInsertionPointToken, $doOutput, $origText);
-		# Allow ancestor to process the comment tag
-	$self->SUPER::comment($aComment);
-		# Assemble original comment
-	$origText = "<!--$aComment-->";
-		# Must ToCs be inserted?
-	if ($self->{hti__Mode} & MODE_DO_INSERT) {
-		# Yes, ToCs must be inserted;
-			# Processing comment as ToC insertion point is successful?
-		if (! $self->_processTokenAsInsertionPoint(
-			HTML::TocGenerator::TT_TOKENTYPE_COMMENT, $aComment, undef, $origText
-		)) {
-			# No, comment isn't a ToC insertion point;
-				# Output comment normally
-			$self->_writeOrBufferOutput($origText);
-		}
-	}
-}  # comment()
-
-
-#--- HTML::TocInsertor::declaration() -----------------------------------------
-# function: This function is called every time a declaration is encountered
-#           by HTML::Parser.
-
-sub declaration {
-		# Get arguments
-	my ($self, $aDeclaration) = @_;
-		# Allow ancestor to process the declaration tag
-	$self->SUPER::declaration($aDeclaration);
-		# Must ToCs be inserted?
-	if ($self->{hti__Mode} & MODE_DO_INSERT) {
-		# Yes, ToCs must be inserted;
-			# Processing declaration as ToC insertion point is successful?
-		if (! $self->_processTokenAsInsertionPoint(
-			HTML::TocGenerator::TT_TOKENTYPE_DECLARATION, $aDeclaration, undef, 
-			"<!$aDeclaration>"
-		)) {
-			# No, declaration isn't a ToC insertion point;
-				# Output declaration normally
-			$self->_writeOrBufferOutput("<!$aDeclaration>");
-		}
-	}
-}  # declaration()
-
-
-#--- HTML::TocInsertor::end() -------------------------------------------------
-# function: This function is called every time a closing tag is encountered
-#           by HTML::Parser.
-# args:     - $aTag: tag name (in lower case).
-
-sub end {
-		# Get arguments
-	my ($self, $aTag, $aOrigText) = @_;
-		# Allow ancestor to process the end tag
-	$self->SUPER::end($aTag, $aOrigText);
-		# Must ToCs be inserted?
-	if ($self->{hti__Mode} & MODE_DO_INSERT) {
-		# Yes, ToCs must be inserted;
-			# Processing end tag as ToC insertion point is successful?
-		if (! $self->_processTokenAsInsertionPoint(
-			HTML::TocGenerator::TT_TOKENTYPE_END, $aTag, undef, $aOrigText
-		)) {
-			# No, end tag isn't a ToC insertion point;
-				# Output end tag normally
-			$self->_writeOrBufferOutput($aOrigText);
-		}
-	}
-}  # end()
-
-
-#--- HTML::TocInsertor::insert() ----------------------------------------------
-# function: Insert ToC in string.
-# args:     - $aToc: (reference to array of) ToC object to insert
-#           - $aString: string to insert ToC in
-#           - $aOptions: hash reference with optional insertor options
-
-sub insert {
-		# Get arguments
-	my ($self, $aToc, $aString, $aOptions) = @_;
-		# Initialize TocInsertor batch
-	$self->_initializeInsertorBatch($aToc, $aOptions);
-		# Do insert Toc
-	$self->_insert($aString);
-		# Deinitialize TocInsertor batch
-	$self->_deinitializeInsertorBatch();
-}  # insert()
-
-
-#--- HTML::TocInsertor::insertIntoFile() --------------------------------------
-# function: Insert ToCs in file.
-# args:     - $aToc: (reference to array of) ToC object(s) to insert.
-#           - $aFile: (reference to array of) file(s) to parse for insertion
-#                points.
-#           - $aOptions: optional insertor options
-
-sub insertIntoFile {
-		# Get arguments
-	my ($self, $aToc, $aFile, $aOptions) = @_;
-		# Initialize TocInsertor batch
-	$self->_initializeInsertorBatch($aToc, $aOptions);
-		# Do insert ToCs into file
-	$self->_insertIntoFile($aFile);
-		# Deinitialize TocInsertor batch
-	$self->_deinitializeInsertorBatch();
-}  # insertIntoFile()
-
-
-#--- HTML::TocInsertor::number() ----------------------------------------------
-# function: Process heading number generated by HTML::Toc.
-# args:     - $aNumber
-
-sub number {
-		# Get arguments
-	my ($self, $aNumber) = @_;
-		# Store heading number as output suffix
-	$self->{_outputSuffix} .= $aNumber;
-}	# number()
-
-
-#--- HTML::TocInsertor::propagateFile() ---------------------------------------
-# function: Propagate ToC; generate & insert ToC, using file as input.
-# args:     - $aToc: (reference to array of) ToC object to insert
-#           - $aFile: (reference to array of) file to parse for insertion
-#                points.
-#           - $aOptions: optional insertor options
-
-sub propagateFile {
-		# Get arguments
-	my ($self, $aToc, $aFile, $aOptions) = @_;
-		# Local variables;
-	my ($file, @files);
-		# Initialize TocInsertor batch
-	$self->_initializeInsertorBatch($aToc, $aOptions);
-		# Dereference array reference or make array of file specification
-	@files = (ref($aFile) =~ m/ARRAY/) ? @$aFile : ($aFile);
-		# Loop through files
-	foreach $file (@files) {
-			# Generate and insert ToC
-		$self->_generateFromFile($file);
-	}
-		# Deinitialize TocInsertor batch
-	$self->_deinitializeInsertorBatch();
-}  # propagateFile()
-
-
-#--- HTML::TocInsertor::start() -----------------------------------------------
-# function: This function is called every time an opening tag is encountered.
-# args:     - $aTag: tag name (in lower case).
-#           - $aAttr: reference to hash containing all tag attributes (in lower
-#                case).
-#           - $aAttrSeq: reference to array containing all tag attributes (in 
-#                lower case) in the original order
-#           - $aOrigText: the original HTML text
-
-sub start {
-		# Get arguments
-	my ($self, $aTag, $aAttr, $aAttrSeq, $aOrigText) = @_;
-		# Local variables
-	my ($doOutput, $i, $tocToken, $tag, $anchorId);
-		# Let ancestor process the start tag
-	$self->SUPER::start($aTag, $aAttr, $aAttrSeq, $aOrigText);
-		# Must ToC be inserted?
-	if ($self->{hti__Mode} & MODE_DO_INSERT) {
-		# Yes, ToC must be inserted;
-			# Processing start tag as ToC insertion point is successful?
-		if (! $self->_processTokenAsInsertionPoint(
-			HTML::TocGenerator::TT_TOKENTYPE_START, $aTag, $aAttr, $aOrigText
-		)) {
-			# No, start tag isn't a ToC insertion point;
-				# Add anchor id?
-			if ($self->{_doAddAnchorIdToStartTag}) {
-				# Yes, anchor id must be added;
-					# Reset indicator;
-				$self->{_doAddAnchorIdToStartTag} = 0;
-					# Alias anchor id
-				$anchorId = $self->{_anchorId};
-					# Attribute 'id' already exists?
-				if (defined($aAttr->{id})) {
-					# Yes, attribute 'id' already exists;
-						# Show warning
-					print STDERR "WARNING: Overwriting existing id attribute '" .
-						$aAttr->{id} . "' of tag $aOrigText\n";
-					
-						# Add anchor id to start tag
-					$aOrigText =~ s/(id)=\S*([\s>])/$1=$anchorId$2/i;
-				}
-				else {
-					# No, attribute 'id' doesn't exist;
-						# Add anchor id to start tag
-					$aOrigText =~ s/>/ id=$anchorId>/;
-				}
-			}
-				# Output start tag normally
-			$self->_writeOrBufferOutput($aOrigText);
-		}
-	}
-}  # start()
-
-
-#--- HTML::TocInsertor::text() ------------------------------------------------
-# function: This function is called every time plain text is encountered.
-# args:     - @_: array containing data.
-
-sub text {
-		# Get arguments
-	my ($self, $aText) = @_;
-		# Let ancestor process the text
-	$self->SUPER::text($aText);
-		# Must ToC be inserted?
-	if ($self->{hti__Mode} & MODE_DO_INSERT) {
-		# Yes, ToC must be inserted;
-			# Processing text as ToC insertion point is successful?
-		if (! $self->_processTokenAsInsertionPoint(
-			HTML::TocGenerator::TT_TOKENTYPE_TEXT, $aText, undef, $aText
-		)) {
-			# No, text isn't a ToC insertion point;
-				# Output text normally
-			$self->_writeOrBufferOutput($aText);
-		}
-	}
-}  # text()
-
-
-
-
-#=== HTML::_TokenTipParser ====================================================
-# function: Parse 'TIP tokens'.  'TIP tokens' mark HTML code which is to be
-#           used as the ToC Insertion Point.
-# note:     Used internally.
-
-package HTML::_TokenTipParser;
-
-
-BEGIN {
-	use vars qw(@ISA);
-
-	@ISA = qw(HTML::_TokenTocParser);
-}
-
-
-END {}
-
-
-#--- HTML::_TokenTipParser::new() ---------------------------------------------
-# function: Constructor
-
-sub new {
-		# Get arguments
-	my ($aType, $aTokenArray) = @_;
-		# Create instance
-	my $self = $aType->SUPER::new;
-		# Reference token array
-	$self->{tokens} = $aTokenArray;
-		# Reference to last added token
-	$self->{_lastAddedToken}     = undef;
-	$self->{_lastAddedTokenType} = undef;
-		# Return instance
-	return $self;
-}  # new()
-
-
-#--- HTML::_TokenTipParser::_processAttributes() ------------------------------
-# function: Process attributes.
-# args:     - $aAttributes: Attributes to parse.
-
-sub _processAttributes {
-		# Get arguments
-	my ($self, $aAttributes) = @_;
-		# Local variables
-	my (%includeAttributes, %excludeAttributes);
-
-		# Parse attributes
-	$self->_parseAttributes(
-		$aAttributes, \%includeAttributes, \%excludeAttributes
-	);
-		# Include attributes are specified?
-	if (keys(%includeAttributes) > 0) {
-		# Yes, include attributes are specified;
-			# Store include attributes
-		@${$self->{_lastAddedToken}}[
-			HTML::TocInsertor::TIP_INCLUDE_ATTRIBUTES
-		] = \%includeAttributes;
-	}
-		# Exclude attributes are specified?
-	if (keys(%excludeAttributes) > 0) {
-		# Yes, exclude attributes are specified;
-			# Store exclude attributes
-		@${$self->{_lastAddedToken}}[
-			HTML::TocInsertor::TIP_EXCLUDE_ATTRIBUTES
-		] = \%excludeAttributes;
-	}
-}  # _processAttributes()
-
-
-#--- HTML::_TokenTipParser::_processToken() -----------------------------------
-# function: Process token.
-# args:     - $aTokenType: Type of token to process.
-#           - $aTag: Tag of token.
-
-sub _processToken {
-		# Get arguments
-	my ($self, $aTokenType, $aTag) = @_;
-		# Local variables
-	my ($tokenArray, $index);
-		# Push element on array of update tokens
-	$index = push(@{$self->{tokens}[$aTokenType]}, []) - 1;
-		# Alias token array to add element to
-	$tokenArray = $self->{tokens}[$aTokenType];
-		# Indicate last updated token array element
-	$self->{_lastAddedTokenType} = $aTokenType;
-	$self->{_lastAddedToken}     = \$$tokenArray[$index];
-		# Add fields
-	$$tokenArray[$index][HTML::TocInsertor::TIP_TOC]         = $self->{_toc};
-	$$tokenArray[$index][HTML::TocInsertor::TIP_TOKEN_ID] 	= $aTag;
-	$$tokenArray[$index][HTML::TocInsertor::TIP_PREPOSITION] =
-		$self->{_preposition};
-}  # _processToken()
-
-
-#--- HTML::_TokenTipParser::comment() -----------------------------------------
-# function: Process comment.
-# args:     - $aComment: comment text with '<!--' and '-->' tags stripped off.
-
-sub comment {
-		# Get arguments
-	my ($self, $aComment) = @_;
-		# Process token
-	$self->_processToken(HTML::TocGenerator::TT_TOKENTYPE_COMMENT, $aComment);
-}  # comment()
-
-
-#--- HTML::_TokenTipParser::declaration() --------------------------------
-# function: This function is called every time a markup declaration is
-#           encountered by HTML::Parser.
-# args:     - $aDeclaration: Markup declaration.
-
-sub declaration {
-		# Get arguments
-	my ($self, $aDeclaration) = @_;
-		# Process token
-	$self->_processToken(
-		HTML::TocGenerator::TT_TOKENTYPE_DECLARATION, $aDeclaration
-	);
-}  # declaration()
-
-	
-#--- HTML::_TokenTipParser::end() ----------------------------------------
-# function: This function is called every time a closing tag is encountered
-#           by HTML::Parser.
-# args:     - $aTag: tag name (in lower case).
-
-sub end {
-		# Get arguments
-	my ($self, $aTag, $aOrigText) = @_;
-		# Process token
-	$self->_processToken(HTML::TocGenerator::TT_TOKENTYPE_END, $aTag);
-}  # end()
-
-
-#--- HTML::_TokenTipParser->setPreposition() ----------------------------------
-# function: Set current preposition.
-
-sub setPreposition {
-		# Get arguments
-	my ($self, $aPreposition) = @_;
-		# Set current ToC
-	$self->{_preposition} = $aPreposition;
-}  # setPreposition()
-
-
-#--- HTML::_TokenTipParser->setToc() ------------------------------------------
-# function: Set current ToC.
-
-sub setToc {
-		# Get arguments
-	my ($self, $aToc) = @_;
-		# Set current ToC
-	$self->{_toc} = $aToc;
-}  # setToc()
-
-
-#--- HTML::_TokenTipParser::start() --------------------------------------
-# function: This function is called every time an opening tag is encountered.
-# args:     - $aTag: tag name (in lower case).
-#           - $aAttr: reference to hash containing all tag attributes (in lower
-#                case).
-#           - $aAttrSeq: reference to array containing all attribute keys (in 
-#                lower case) in the original order
-#           - $aOrigText: the original HTML text
-
-sub start {
-		# Get arguments
-	my ($self, $aTag, $aAttr, $aAttrSeq, $aOrigText) = @_;
-		# Process token
-	$self->_processToken(HTML::TocGenerator::TT_TOKENTYPE_START, $aTag);
-		# Process attributes
-	$self->_processAttributes($aAttr);
-}  # start()
-
-
-#--- HTML::_TokenTipParser::text() ---------------------------------------
-# function: This function is called every time plain text is encountered.
-# args:     - @_: array containing data.
-
-sub text {
-		# Get arguments
-	my ($self, $aText) = @_;
-		# Was token already created and is last added token of type 'text'?
-	if (
-		defined($self->{_lastAddedToken}) && 
-		$self->{_lastAddedTokenType} == HTML::TocGenerator::TT_TOKENTYPE_TEXT
-	) {
-		# Yes, token is already created;
-			# Add tag to existing token
-		@${$self->{_lastAddedToken}}[HTML::TocGenerator::TT_TAG_BEGIN] .= $aText;
-	}
-	else {
-		# No, token isn't created;
-			# Process token
-		$self->_processToken(HTML::TocGenerator::TT_TOKENTYPE_TEXT, $aText);
-	}
-}  # text()
-
-
-1;