10.4.4 Texinfo Tree Elements in User Defined Functions ¶

Many user defined functions used for formatting have Texinfo tree elements as arguments. The user defined code should never modify the tree elements. It is possible to reuse Texinfo tree elements information, but with a copy. For example, the following is correct:

my @contents = @{$element->{'contents'}};
push @contents, {'text' => ' my added text'};
my $result = $converter->convert_tree({'cmdname' => 'strong',
                                  'contents' => \@contents });

The following is incorrect:

push @{$element->{'contents'}}, {'text' => ' my added text'};

Nodes and sectioning elements hold information on the document structure (see (texi2any_internals)Texinfo::Structuring METHODS). For example, the following keys of the extra sectioning elements hash can be interesting in several user-defined formatting and conversion functions:

section_childs

For sectioning commands elements. The children of the sectioning element in the sectioning tree.

section_level

The level of the section, taking into account @raisesections and @lowersections. Level 0 corresponds to @top or @part and level 1 to @chapter level sectioning commands. See Raise/lower sections in Texinfo.

Detailed information on the tree elements is available in the Texinfo Parser documentation, in particular a list of types and of information in the elements extra hash (see (texi2any_internals)Texinfo::Parser TEXINFO TREE).