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

NAME
====

Texinfo::Structuring - informations and transformations in Texinfo::Parser tree

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_by_letter sort_indices elements_directions
    elements_file_directions);
  # $tree is a Texinfo document tree.  $parser is a Texinfo::Parser object.
  my $sections_root = sectioning_structure ($parser, $tree);
  my $top_node = nodes_tree($parser);
  number_floats($parser->floats_information());
  associate_internal_references($parser);
  my $elements;
  if ($split_at_nodes) {
    $elements = split_by_node($tree);
  } else {
    $elements = split_by_section($tree);
  }
  split_pages($elements, $split);
  elements_directions($parser, $elements);
  elements_file_directions($parser, $elements);

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

DESCRIPTION
===========

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

It is also possible to group the top-level contents of the tree, which consist in nodes and sectioning commands into elements that group together a node and the next sectioning element.  With split_by_node nodes are considered to be the main sectionning 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 correspond 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 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 or sort_indices_by_letter to sort by letters.

Other miscellaneous methods include set_menus_to_simple_menu and menu_to_simple_menu to change the menu texinfo tree, as well as insert_nodes_for_sectioning_commands that adds nodes for sectioning commands without nodes and complete_tree_nodes_menus that completes the node menus based on the sectioning tree.

METHODS
=======

No method is exported in the default case.

Most of those function references takes a Texinfo::Parser object as argument, see Texinfo::Parser NAME.

$sections_root = sectioning_structure ($parser, $tree)

     This function goes through the tree and gather information on the document structure for sectioning commands.  It returns the root of the sectioning commands tree.

     For section elements, it sets:

     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.

     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.

my $top_node = nodes_tree($parser)

     Goes through menu and nodes and set directions.  Returns the top node.

     This functions sets:

     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.

     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 of the float tree elements.

associate_internal_references($parser)

     Verify that internal references (@ref and similar without fourth of fifth argument) have an associated node, anchor or float. Set the label key in the extra hash of the reference tree element to the associated labeled tree element.

$elements = split_by_node($tree)

     Returns a reference array of elements 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 elements.

     Elements are regular tree items with type element, the associated nodes and sectioning tree items are in the array associated with the contents key.  They have directions, namely element_next and element_prev pointing to the previous and the next element.

     In the extra hash they have

     no_node

          A special case, if there are no nodes in the document, the value is set.

     node

     element_command

          The node command associated with the element.

     section

          The sectioning command associated with the element node.

$elements = split_by_section($tree)

     Similarly with split_by_node, returns an array of elements.  This time, lone nodes are associated with the previous sections and lone sections makes up an element.

     The extra hash keys set are the same, except that element_command is the sectioning command associated with the element, and no_node is replaced by no_section.

$pages = split_pages($elements, $split)

     The elements from the array reference argument have an extra first_in_page value set to the first element on the unit, and based on the value of $split.  The possible values for $split are

     chapter

          The elements are split at chapter or other toplevel sectioning elements.

     node

          Each element has its own page.

     section

          The elements are split at sectioning commands below chapter.

     value evaluating to false

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

elements_directions($parser, $elements)

     Directions are set up for the elements in the array reference given in argument.  The corresponding hash reference is in {'extra'}->{'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.

     FastForward

          The next top level section element.

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

elements_file_directions($parser, $elements)

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

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

$merged_entries = merge_indices($index_names)

     Using informations 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.

$index_entries_sorted = sort_indices_by_letter($parser, $merged_index_entries, $index_names)

$index_entries_sorted = sort_indices($parser, $merged_index_entries, $index_names)

     These functions first sets a plain text key for each index entry, used for sorting.  In both cases, a hash reference with index names as keys 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 indes entries is associated with the index name.

($root_content, $added_sections) = fill_gaps_in_sectioning ($root)

     This function adds empty @unnumbered and similar commands in a tree to fill gaps in sectioning.  This may be used, for example, when converting from a format that can handle gaps in sectioning.  $root is the tree root.  An array reference is returned, containing the root contents with added sectioning commands, as well as an array reference containing the added sectioning commands.

     If the sectioning commands are lowered or raised (with @raisesections, @lowersection) the tree may be modified with @raisesections or @lowersection added to some tree elements.

menu_to_simple_menu ($menu)

set_menus_to_simple_menu ($parser)

     menu_to_simple_menu transforms the tree of a menu tree element. set_menus_to_simple_menu calls menu_to_simple_menu for all the menus of the document.

     A simple menu has no menu_comment, menu_entry or menu_entry_description container anymore, their content are merged directly in the menu in preformatted container.

($root_content, $added_nodes) = insert_nodes_for_sectioning_commands ($parser, $tree)

     Insert nodes for sectioning commands without node in $tree. An array reference is returned, containing the root contents with added nodes, as well as an array reference containing the added nodes.

complete_tree_nodes_menus ($parser, $tree)

     Add menu entries or whole menus for nodes associated with sections, based on the sectioning tree.  This function should therefore be called after sectioning_structure.

$detailmenu = new_master_menu ($parser)

     Returns a detailmenu tree element formatted as a master node.

regenerate_master_menu ($parser)

     Regenerate the Top node master menu, replacing the first detailmenu in Top node menus or appending at the end of the Top node menu.

SEE ALSO
========

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

AUTHOR
======

Patrice Dumas, <pertusus@free.fr>

COPYRIGHT AND LICENSE
=====================

Copyright 2010, 2011, 2012 Free Software Foundation, Inc.

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.