branch master updated: tp/Texinfo/Structuring.pm: update documentation.

[Patrice Dumas]

This is an automated email from the git hooks/post-receive script.

pertusus pushed a commit to branch master
in repository texinfo.

The following commit(s) were added to refs/heads/master by this push:
     new 9014f4f889 tp/Texinfo/Structuring.pm: update documentation.
9014f4f889 is described below

commit 9014f4f88945a03cf7722f59cf2e73b56266d7b2
Author: Patrice Dumas <pertusus@free.fr>
AuthorDate: Sat Jan 1 15:42:41 2022 +0100

    tp/Texinfo/Structuring.pm: update documentation.
---
 tp/Texinfo/Structuring.pm | 132 +++++++++++++++++++++++-----------------------
 1 file changed, 66 insertions(+), 66 deletions(-)

diff --git a/tp/Texinfo/Structuring.pm b/tp/Texinfo/Structuring.pm
index 8ced6e670c..404547f601 100644
--- a/tp/Texinfo/Structuring.pm
+++ b/tp/Texinfo/Structuring.pm
@@ -1775,18 +1775,18 @@ anchors with C<associate_internal_references>.
 The following methods depend on the output format, so are usually called
 from converters.
 
-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 C<split_by_node> nodes are considered
+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 C<split_by_node> nodes are 
considered
 to be the main sectioning elements, while with C<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.
+of Info format, while the second corresponds to a traditional book.
 The elements may be further split in I<pages>, which are not pages as
-in book pages, but more like web pages, and hold series of elements.
+in book pages, but more like web pages, and hold series of tree unit elements.
 
-The elements may have directions to other elements prepared 
+The elements may have directions to other elements prepared
 by C<elements_directions>.  C<elements_file_directions> should also
-set direction related to files, provided files are associated with 
+set direction related to files, provided files are associated with
 elements by the user.
 
 C<merge_indices> may be used to merge indices, which may be sorted
@@ -1797,7 +1797,7 @@ with C<sort_indices>.
 
 No method is exported in the default case.
 
-Most methods takes a Texinfo::Report I<$registrar> as argument
+Most methods takes a Texinfo::Report C<$registrar> as argument
 for error reporting, see L<Texinfo::Report>.  Most also require
 configuration information, which means an object implementing
 the get_conf() method, in practice the main program configuration
@@ -1810,14 +1810,14 @@ labels or refs are obtained from a parser, see 
L<Texinfo::Parser>.
 
 Verify that internal references (C<@ref> and similar without
 fourth of fifth argument) have an associated node, anchor or float.
-Set the I<label> key in the I<extra> hash of the reference tree
+Set the C<label> key in the C<extra> hash of the reference tree
 element to the associated labeled tree element.  Register errors
-in C<$registrar>.
+in I<$registrar>.
 
 =item check_nodes_are_referenced($registrar, $configuration_informations, 
$nodes_list, $top_node, $labels, $refs)
 
 Check that all the nodes are referenced (in menu, @*ref or node direction).
-Register errors in C<$registrar>.
+Register errors in I<$registrar>.
 
 Should be called after C<complete_node_tree_with_menus> in order to
 have the autogenerated menus available.
@@ -1826,12 +1826,12 @@ have the autogenerated menus available.
 
 Complete nodes directions with menu directions.  Check consistency
 of menus, sectionning and nodes direction structures.
-Register errors in C<$registrar>.
+Register errors in I<$registrar>.
 
 =item elements_directions($parser, $configuration_informations, $tree_units)
 
-Directions are set up for the elements in the array reference given in 
-argument.  The corresponding hash reference is in 
+Directions are set up for the tree unit elements in the array reference given 
in
+argument.  The corresponding hash is in
 C<< {'structure'}->{'directions'} >>
 and keys correspond to directions while values are elements.
 
@@ -1853,7 +1853,7 @@ Previous element.
 
 =item NodeForward
 
-Following node element in reading order.  It is the next node, or the 
+Following node element in reading order.  It is the next node, or the
 first in menu or the next of the up node.
 
 =item NodeBack
@@ -1883,8 +1883,8 @@ The next top level section element.
 =item 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 
+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.
 
 =item FastForward
@@ -1896,19 +1896,19 @@ The next top level element.
 =item elements_file_directions($tree_units)
 
 In the directions reference described above for C<elements_directions>, sets
-the I<PrevFile> and C<NextFile> directions to the elements in previous and
-following files.  
+the I<PrevFile> and I<NextFile> directions to the elements in previous and
+following files.
 
-It also sets C<FirstInFile*> directions for all the elements by using
-the directions of the first element in file.  So, for example, 
-C<FirstInFileNodeNext> is the next node of the first element in
+It also sets I<FirstInFile*> directions for all the elements by using
+the directions of the first element in file.  So, for example,
+I<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.
 
 =item @nodes_list = get_node_node_childs_from_sectioning($node)
 
-C<$node> is a node tree element.  Find the node C<$node> children based
+I<$node> is a node tree element.  Find the node I<$node> children based
 on the sectioning structure.  For the node associated with C<@top>
 sectioning command, the sections associated with parts are considered.
 
@@ -1919,8 +1919,8 @@ TODO
 =item $merged_entries = merge_indices($index_names)
 
 Using informations returned by L<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 
+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 I<$merged_entries> returned is a hash reference whose
@@ -1930,25 +1930,25 @@ described in details in 
L<Texinfo::Parser/index_entries>.
 =item $new_block = new_block_command($content, $parent, $command_name)
 
 Returns the texinfo tree corresponding to a block command named
-C<$command_name> with contents C<$content> and parent in tree C<$parent>.
+I<$command_name> with contents I<$content> and parent in tree I<$parent>.
 
 =item $new_menu = new_complete_node_menu($node, $use_sections)
 
-Returns a texinfo tree menu for node C<$node>, pointing to the children
-of the node obtained with the sectioning structure.  If C<$use_sections>
+Returns a texinfo tree menu for node I<$node>, pointing to the children
+of the node obtained with the sectioning structure.  If I<$use_sections>
 is set, use section names instead of node names in menu.
 
 =item $entry = new_node_menu_entry($node, $use_sections)
 
 Returns the texinfo tree corresponding to a single menu entry pointing to
-C<$node>.  If C<$use_section> is set, use the section name instead of node 
name.
+I<$node>.  If I<$use_section> is set, use the section name instead of node 
name.
 
-=item my $top_node = nodes_tree($registrar, $configuration_informations, 
$parser_informations, $nodes_list, $labels)
+=item $top_node = nodes_tree($registrar, $configuration_informations, 
$parser_informations, $nodes_list, $labels)
 
 Goes through nodes and set directions.  Returns the top
-node.  Register errors in C<$registrar>.
+node.  Register errors in I<$registrar>.
 
-This functions sets:
+This functions sets, in the C<structure> node element hash:
 
 =over
 
@@ -1965,11 +1965,12 @@ Up, next and previous directions for the node.
 =item number_floats($float_information)
 
 Number the floats as described in the Texinfo manual.  Sets
-the I<number> key of the float tree elements.
+the I<number> key in the C<structure> hash of the float
+tree elements.
 
 =item $level = section_level($section)
 
-Return numbered level of the tree sectioning C<$section>, as modified by
+Return numbered level of the tree sectioning I<$section>, as modified by
 raise/lowersections.
 
 =item $command_name = section_level_adjusted_command_name($element)
@@ -1978,20 +1979,20 @@ Return the sectioning command name corresponding to the 
sectioning
 element I<$element>, adjusted in order to take into account raised
 and lowered sections, when needed.
 
-=item $sections_root, $sections_list = sectioning_structure ($registrar, 
$configuration_informations, $tree)
+=item $sections_root, $sections_list = sectioning_structure($registrar, 
$configuration_informations, $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 and a reference on the sections
+the document structure for sectioning commands.  It returns I<$sections_root>
+the root of the sectioning commands tree and a reference on the sections
 elements list.  Errors are registered in I<$registrar>.
 
-For section elements, it sets:
+It sets section elements C<structure> hash values:
 
 =over
 
 =item level
 
-The level in the sectioning tree hierarchy.  0 is for C<@top> or 
+The level in the sectioning tree hierarchy.  0 is for C<@top> or
 C<@part>, 1 for C<@chapter>, C<@appendix>...  This level is corrected
 by C<@raisesections> and C<@lowersections>.
 
@@ -2018,14 +2019,16 @@ The up, previous and next sectioning elements.
 =item toplevel_up
 
 The next and previous and up sectioning elements of toplevel sectioning
-elements (like C<@top>, C<@chapter>, C<@appendix>), not taking into 
+elements (like C<@top>, C<@chapter>, C<@appendix>), not taking into
 account C<@part> elements.
 
 =back
 
 =item set_menus_node_directions($registrar, $configuration_informations, 
$parser_informations, $global_commands, $nodes_list, $labels);
 
-Goes through menu and set directions.  Register errors in C<$registrar>.
+Goes through menu and set directions.  Register errors in I<$registrar>.
+
+This functions sets, in the C<structure> node element hash reference:
 
 =over
 
@@ -2041,8 +2044,6 @@ The first child in the menu of the node.
 
 Up, next and previous directions as set in menus.
 
-=item node_up
-
 =back
 
 =item setup_index_entry_keys_formatting($self, $configuration_informations)
@@ -2051,22 +2052,22 @@ TODO
 
 =item ($index_entries_sorted, $index_entries_sort_strings) = 
sort_indices($parser, $registrar, $configuration_informations, 
$merged_index_entries, $sort_by_letter)
 
-If C<$sort_by_letter> is set, sort by letter, otherwise sort all
+If I<$sort_by_letter> is set, sort by letter, otherwise sort all
 entries together.  In both cases, a hash reference with index names
-as keys C<$index_entries_sorted> is returned.
+as keys I<$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 
+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 I<letter> key with the letter, and an I<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.
 
-C<$index_entries_sort_strings> is a hash reference associating the index
+I<$index_entries_sort_strings> is a hash reference associating the index
 entries with the strings that were used to sort them.
 
-Register errors in C<$registrar>.
+Register errors in I<$registrar>.
 
 =item $tree_units = split_by_node($tree)
 
@@ -2075,25 +2076,23 @@ 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.
 
-Elements are regular tree items with type I<unit>, the
-associated nodes and sectioning tree items are in the array associated
-with the I<contents> key.  They have directions, namely I<unit_next>
-and I<unit_prev> pointing to the previous and the next tree unit.
+Tree units are regular tree elements with type I<unit>, the
+associated nodes and sectioning tree elements are in the array associated
+with the C<contents> key.  The associated elements have a I<associated_unit>
+key set in the C<structure> hash that points to the associated tree unit.
 
-In the I<extra> hash they have
+Tree units have directions in the C<structure>
+hash reference, namely I<unit_next> and I<unit_prev> pointing to the
+previous and the next tree unit.
 
-=over
+In the C<extra> hash reference, tree units have:
 
-=item node
+=over
 
 =item unit_command
 
 The node command associated with the element.
 
-=item section
-
-The sectioning command associated with the element node.
-
 =back
 
 =item $tree_units = split_by_section($tree)
@@ -2102,14 +2101,15 @@ Similarly with C<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 extra hash keys set are the same, except that I<unit_command> is
+The C<structure> and C<extra> hash keys set are the same, except that 
I<unit_command> is
 the sectioning command associated with the element.
 
 =item $pages = split_pages($tree_units, $split)
 
 The tree units from the array reference argument have an extra
-I<first_in_page> value set to the first tree unit in the group, and
-based on the value of I<$split>.  The possible values for I<$split> are
+I<first_in_page> value set in the C<structure> hash reference to
+the first tree unit in the group, and based on the value of I<$split>.
+The possible values for I<$split> are
 
 =over
 
@@ -2133,15 +2133,15 @@ No splitting, only one page is returned, holding all 
the tree units.
 
 =item warn_non_empty_parts($registrar, $configuration_informations, 
$global_commands)
 
-Register a warning in C<$registrar> for each C<@part> that is not empty
-in C<$global_commands> information (typically obtained by calling
+Register a warning in I<$registrar> for each C<@part> that is not empty
+in I<$global_commands> information (typically obtained by calling
 C<global_commands_information()> on a parser).
 
 =back
 
 =head1 SEE ALSO
 
-L<Texinfo manual|http://www.gnu.org/s/texinfo/manual/texinfo/>, 
+L<Texinfo manual|http://www.gnu.org/s/texinfo/manual/texinfo/>,
 L<Texinfo::Parser>.
 
 =head1 AUTHOR