6.3 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 ok:

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

The following is not ok:

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

In addition to the elements obtained after parsing a Texinfo document, two elements are added, unit type elements that correspond to the normal document units (see Output Element Units), and special elements with type special_element that correspond to added special elements (see Output Element Units). These added elements, as well as nodes and sectioning elements hold information on the document structure in the structure element hash (see (texi2any_internals)Texinfo::Structuring METHODS).

Normal tree unit elements have a unit_command key in the extra hash that points to the associated @node or sectioning @-command depending on which of nodes or sectioning commands are the main components of elements. See Output Element Units.

The following keys of the structure hash can be interesting:

associated_unit

For sectioning and @node @-command elements. The associated tree unit element.

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.

unit_filename

For tree unit elements. The associated file name.

unit_next

For tree unit elements. The next unit element in document order.

unit_prev

For tree unit elements. The previous unit element in document order.

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).