4 Texinfo::Structuring

4.1 Texinfo::Structuring NAME

Texinfo::Structuring - information on Texinfo::Parser tree

4.2 Texinfo::Structuring SYNOPSIS

  use Texinfo::Structuring qw(sectioning_structure nodes_tree number_floats
    associate_internal_references split_by_node split_by_section split_pages
    merge_indices sort_indices elements_directions elements_file_directions);

  # $tree is a Texinfo document tree.  $parser is a Texinfo::Parser object.
  # $config is an object implementing the get_conf() method.
  my $registrar = $parser->registered_errors();
  my $sections_root = sectioning_structure ($registrar, $config, $tree);
  my ($labels, $targets_list, $nodes_list) = $parser->labels_information();
  my $parser_information = $parser->global_information();
  my $global_commands = $parser->global_commands_information();
  set_menus_node_directions($registrar, $config, $parser_information,
                            $global_commands, $nodes_list, $labels);
  my $top_node = nodes_tree($registrar, $config, $parser_information,
                            $nodes_list, $labels);
  complete_node_tree_with_menus($registrar, $config, $nodes_list, $top_node);
  my $refs = $parser->internal_references_information();
  check_nodes_are_referenced($registrar, $config, $nodes_list, $top_node,
                             $labels, $refs);
  associate_internal_references($registrar, $parser, $parser_information,
                                $labels, $refs);
  my $tree_units;
  if ($split_at_nodes) {
    $tree_units = split_by_node($tree);
  } else {
    $tree_units = split_by_section($tree);
  split_pages($tree_units, $split);
  elements_directions($config, $labels, $tree_units);

  my $indices_information = $parser->indices_information();
  my $merged_index_entries
     = merge_indices($indices_information);
  my $index_entries_sorted;
  if ($sort_by_letter) {
    $index_entries_sorted = sort_indices($registrar, $config,
                             $merged_index_entries, $indices_information,
  } else {
    $index_entries_sorted = sort_indices($registrar, $config,

4.3 Texinfo::Structuring NOTES

The Texinfo Perl module main purpose is to be used in texi2any to convert Texinfo to other formats. There is no promise of API stability.

4.4 Texinfo::Structuring DESCRIPTION

Texinfo::Structuring first allows to collect information on a Texinfo tree. In most case, it also requires information from a parser object to do that job. Thanks to sectioning_structure the hierarchy of sectioning commands is determined. The directions implied by menus are determined with set_menus_node_directions. The node tree is analysed with nodes_tree. Nodes directions are completed with menu directions with complete_node_tree_with_menus. Floats get their standard numbering with number_floats and internal references are matched up with nodes, floats or anchors with associate_internal_references.

The following methods depend on the output format, so are usually called from converters.

It is also possible to associate top-level contents of the tree, which consist in nodes and sectioning commands with tree unit elements that group together a node and the next sectioning element. With split_by_node nodes are considered to be the main sectioning elements, while with split_by_section the sectioning command elements are the main elements. The first mode is typical of Info format, while the second corresponds to a traditional book. The elements may be further split in pages, which are not pages as in book pages, but more like web pages, and hold series of tree unit elements.

The elements may have directions to other elements prepared by elements_directions. elements_file_directions should also set direction related to files, provided files are associated with elements by the user.

merge_indices may be used to merge indices, which may be sorted with sort_indices.

4.5 Texinfo::Structuring METHODS

No method is exported in the default case.

Most methods takes a Texinfo::Report $registrar as argument for error reporting. Most also require Texinfo customization variables information, which means an object implementing the get_conf method, in practice the main program configuration or a converter (Getting and setting customization variables). Other common input arguments such as parser information, labels or refs are obtained from a parser, see Texinfo::Parser.

associate_internal_references($registrar, $customization_information, $parser_information, $labels, $refs)

Verify that internal references (@ref and similar without fourth of fifth argument and menu entries) have an associated node, anchor or float. Set the normalized key in the extra hash menu_entry_node hash for menu entries and in the first argument extra hash for internal references @ref and similar @-commands. Register errors in $registrar.

check_nodes_are_referenced($registrar, $customization_information, $nodes_list, $top_node, $labels, $refs)

Check that all the nodes are referenced (in menu, @*ref or node direction). Register errors in $registrar.

Should be called after complete_node_tree_with_menus in order to have the autogenerated menus available.

complete_node_tree_with_menus($registrar, $customization_information, $nodes_list, $top_node)

Complete nodes directions with menu directions. Check consistency of menus, sectionning and nodes direction structures. Register errors in $registrar.

elements_directions($customization_information, $labels, $tree_units)

Directions are set up for the tree unit elements in the array reference $tree_units given in argument. The corresponding hash is in {'structure'}->{'directions'} and keys correspond to directions while values are elements.

The following directions are set up:


The element itself.


Element next.


Previous element.


Following node element in reading order. It is the next node, or the first in menu or the next of the up node.


Preceding node element.


The up, next and previous node elements.


The up, next and previous section elements.


For top level elements, the previous top level element. For other elements the up top level element. For example, for a chapter element it is the previous chapter, for a subsection element it is the chapter element that contains the subsection.


The next top level section element.


In the directions reference described above for elements_directions, sets the PrevFile and NextFile directions to the elements in previous and following files.

It also sets FirstInFile* directions for all the elements by using the directions of the first element in file. So, for example, FirstInFileNodeNext is the next node of the first element in the file of each element.

The API for association of pages/elements to files is not defined yet.

@nodes_list = get_node_node_childs_from_sectioning($node)

$node is a node tree element. Find the node $node children based on the sectioning structure. For the node associated with @top sectioning command, the sections associated with parts are considered.

$entry_key = index_entry_sort_string($main_entry, $entry_tree_element, $sortas, $options)

Return a string suitable as a sort string, for index entries. The index entry processed is $entry_tree_element, and can be a @subentry. $main_entry is the main index entry tree element that can be used to gather information. $sortas can be given to override the sort string (typically obtained from @sortas). The $options are options used for Texinfo to text conversion for the generation of the sort string, typically obtained from setup_index_entry_keys_formatting.

$merged_entries = merge_indices($indices_information)

Using information returned by Texinfo::Parser::indices_information, a structure holding all the index entries by index name is returned, with all the entries of merged indices merged with those of the indice merged into.

The $merged_entries returned is a hash reference whose keys are the index names and values arrays of index entry structures described in details in Texinfo::Parser index_entries.

$new_block = new_block_command($content, $parent, $command_name)

Returns the texinfo tree corresponding to a block command named $command_name with contents $content and parent in tree $parent.

$new_menu = new_complete_node_menu($node, $use_sections)

Returns a texinfo tree menu for node $node, pointing to the children of the node obtained with the sectioning structure. If $use_sections is set, use section names for the menu entry names.

$detailmenu = new_master_menu($translations, $labels, $menus)

Returns a detailmenu tree element formatted as a master node. $translations, if defined, should be a Texinfo::Translations object and should also hold customization information. $menus is an array reference containing the regular menus of the Top node.

$entry = new_node_menu_entry($node, $use_sections)

Returns the texinfo tree corresponding to a single menu entry pointing to $node. If $use_sections is set, use the section name for the menu entry name. Returns undef if the node argument is missing.

$top_node = nodes_tree($registrar, $customization_information, $parser_information, $nodes_list, $labels)

Goes through nodes and set directions. Returns the top node. Register errors in $registrar.

This functions sets, in the structure node element hash:


Up, next and previous directions for the node.


Number the floats as described in the Texinfo manual. Sets the number key in the structure hash of the float tree elements.

$command_name = section_level_adjusted_command_name($element)

Return the sectioning command name corresponding to the sectioning element $element, adjusted in order to take into account raised and lowered sections, when needed.

$sections_root, $sections_list = sectioning_structure($registrar, $customization_information, $tree)

This function goes through the tree and gather information on the document structure for sectioning commands. It returns $sections_root the root of the sectioning commands tree and a reference on the sections elements list. Errors are registered in $registrar.

It sets section elements structure hash values:


The level in the sectioning tree hierarchy. 0 is for @top or @part, 1 for @chapter, @appendix... This level is corrected by @raisesections and @lowersections.


The sectioning element number.


An array holding sectioning elements children of the element.


The up, previous and next sectioning elements.


The next and previous and up sectioning elements of toplevel sectioning elements (like @top, @chapter, @appendix), not taking into account @part elements.

set_menus_node_directions($registrar, $customization_information, $parser_information, $global_commands, $nodes_list, $labels);

Goes through menu and set directions. Register errors in $registrar.

This functions sets, in the structure node element hash reference:


The first child in the menu of the node.


Up, next and previous directions as set in menus.

$option = setup_index_entry_keys_formatting($customization_information)

Return options for conversion of Texinfo to text relevant for index keys sorting.

($index_entries_sorted, $index_entries_sort_strings) = sort_indices($registrar, $customization_information, $merged_index_entries, $indices_information, $sort_by_letter)

If $sort_by_letter is set, sort by letter, otherwise sort all entries together. In both cases, a hash reference with index names as keys $index_entries_sorted is returned.

When sorting by letter, an array reference of letter hash references is associated with each index name. Each letter hash reference has two keys, a letter key with the letter, and an entries key with an array reference of sorted index entries beginning with the letter.

When simply sorting, the array of the sorted index entries is associated with the index name.

$index_entries_sort_strings is a hash reference associating the index entries with the strings that were used to sort them.

Register errors in $registrar.

$tree_units = split_by_node($tree)

Returns a reference array of tree units where a node is associated to the following sectioning commands. Sectioning commands without nodes are also with the previous node, while nodes without sectioning commands are alone in their tree units.

Tree units are regular tree elements with type unit, the associated nodes and sectioning tree elements are in the array associated with the contents key. The associated elements have a associated_unit key set in the structure hash that points to the associated tree unit.

Tree units have directions in the structure hash reference, namely unit_next and unit_prev pointing to the previous and the next tree unit.

In the extra hash reference, tree units have:


The node command associated with the element.

$tree_units = split_by_section($tree)

Similarly with split_by_node, returns an array of tree units. This time, lone nodes are associated with the previous sections and lone sections makes up a tree unit.

The structure and extra hash keys set are the same, except that unit_command is the sectioning command associated with the element.

$pages = split_pages($tree_units, $split)

The tree units from the array reference argument have an extra first_in_page value set in the structure hash reference to the first tree unit in the group, and based on the value of $split. The possible values for $split are


The tree units are split at chapter or other toplevel sectioning tree units.


Each element has its own page.


The tree units are split at sectioning commands below chapter.

value evaluating to false

No splitting, only one page is returned, holding all the tree units.

warn_non_empty_parts($registrar, $customization_information, $global_commands)

Register a warning in $registrar for each @part that is not empty in $global_commands information (typically obtained by calling global_commands_information() on a parser).

4.6 Texinfo::Structuring SEE ALSO

Texinfo manual, Texinfo::Parser.

4.7 Texinfo::Structuring AUTHOR

Patrice Dumas, <pertusus@free.fr>