Texinfo::Structuring
********************

Texinfo::Structuring NAME
=========================

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

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);
  number_floats($parser->floats_information());
  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);
  elements_file_directions($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,
                             'by_letter');
  } else {
    $index_entries_sorted = sort_indices($registrar, $config,
                                         $merged_index_entries,
                                         $indices_information);
  }

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.

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.

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 (Texinfo::Convert::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:

     This

          The element itself.

     Forward

          Element next.

     Back

          Previous element.

     NodeForward

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

     NodeBack

          Preceding node element.

     NodeUp

     NodeNext

     NodePrev

          The up, next and previous node elements.

     Up

     Next

     Prev

          The up, next and previous section elements.

     FastBack

          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.

     FastForward

          The next top level section element.

elements_file_directions($tree_units)

     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:

     node_up

     node_prev

     node_next

          Up, next and previous directions for the node.

number_floats($float_information)

     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:

     section_level

          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.

     section_number

          The sectioning element number.

     section_childs

          An array holding sectioning elements children of the element.

     section_up

     section_prev

     section_next

          The up, previous and next sectioning elements.

     toplevel_next

     toplevel_prev

     toplevel_up

          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:

     menu_child

          The first child in the menu of the node.

     menu_up

     menu_next

     menu_prev

          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:

     unit_command

          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

     chapter

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

     node

          Each element has its own page.

     section

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

Texinfo::Structuring SEE ALSO
=============================

Texinfo manual (http://www.gnu.org/s/texinfo/manual/texinfo/), Texinfo::Parser.

Texinfo::Structuring AUTHOR
===========================

Patrice Dumas, <pertusus@free.fr>

Texinfo::Structuring COPYRIGHT AND LICENSE
==========================================

Copyright 2010- Free Software Foundation, Inc.  See the source file for all copyright years.

This library is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.