@node Texinfo@asis{::}Structuring
@chapter Texinfo::Structuring

@node Texinfo@asis{::}Structuring NAME
@section Texinfo::Structuring NAME

Texinfo::Structuring - information on Texinfo::Document document structure

@node Texinfo@asis{::}Structuring SYNOPSIS
@section Texinfo::Structuring SYNOPSIS

@verbatim
  use Texinfo::Structuring qw(sectioning_structure nodes_tree number_floats
    associate_internal_references);

  # $document is a parsed Texinfo::Document document.
  # When customization variables information is needed, it is obtained
  # from the $document by calling the get_conf() method.
  my $sections_list = sectioning_structure($document);
  my $nodes_list = nodes_tree($document);
  set_menus_node_directions($document);
  complete_node_tree_with_menus($document);
  check_nodes_are_referenced($document);
  associate_internal_references($document);
  number_floats($document->floats_information());
@end verbatim

@node Texinfo@asis{::}Structuring NOTES
@section Texinfo::Structuring NOTES

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

@node Texinfo@asis{::}Structuring DESCRIPTION
@section Texinfo::Structuring DESCRIPTION

@code{Texinfo::Structuring} allows to collect information on a Texinfo
document structure.  Thanks to @code{sectioning_structure} the hierarchy of
sectioning commands is determined.  The directions implied by menus are
determined with @code{set_menus_node_directions}.  The node tree is analysed
with @code{nodes_tree}.  Nodes directions are completed with menu directions
with @code{complete_node_tree_with_menus}.  Floats get their standard
numbering with @code{number_floats} and internal references are matched up
with nodes, floats or anchors with @code{associate_internal_references}.

@node Texinfo@asis{::}Structuring METHODS
@section Texinfo::Structuring METHODS

No method is exported in the default case.

Most methods use the @ref{Texinfo@asis{::}Report NAME,, Texinfo::Report} registrar from a parsed document
for error reporting. Most also require Texinfo customization variables
information, which means an object implementing the @code{get_conf} method, in
general a parsed document with registered customization, or, sometime,
a converter (@ref{Texinfo@asis{::}Convert@asis{::}Converter Getting and setting customization
variables}).  Other common data needed such as target elements associated to
identifiers or refs are obtained from a parsed document, see
@ref{Texinfo@asis{::}Document NAME,, Texinfo::Document}.

@table @asis
@item associate_internal_references($document)
@anchor{Texinfo@asis{::}Structuring associate_internal_references($document)}
@cindex @code{associate_internal_references}

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

@item check_nodes_are_referenced($document)
@anchor{Texinfo@asis{::}Structuring check_nodes_are_referenced($document)}
@cindex @code{check_nodes_are_referenced}

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

Should be called after @code{complete_node_tree_with_menus} in order to
have the autogenerated menus available.

@item complete_node_tree_with_menus($document)
@anchor{Texinfo@asis{::}Structuring complete_node_tree_with_menus($document)}
@cindex @code{complete_node_tree_with_menus}

Complete nodes directions with menu directions.  Check consistency
of menus, sectionning and nodes direction structures.

@item @@children_nodes = get_node_node_childs_from_sectioning($node)
@anchor{Texinfo@asis{::}Structuring @@children_nodes = get_node_node_childs_from_sectioning($node)}
@cindex @code{get_node_node_childs_from_sectioning}

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

@item new_block_command($element, $command_name)
@anchor{Texinfo@asis{::}Structuring new_block_command($element@comma{} $command_name)}
@cindex @code{new_block_command}

Complete @emph{$element} by adding the @emph{$command_name}, the command line
argument and @code{@@end} to turn the element to a proper block command.

@item $new_menu = new_complete_node_menu($node, $customization_information, $use_sections)
@anchor{Texinfo@asis{::}Structuring $new_menu = new_complete_node_menu($node@comma{} $customization_information@comma{} $use_sections)}
@cindex @code{new_complete_node_menu}

Returns a @code{@@menu} Texinfo tree element for node @emph{$node}, pointing to the
children of the node obtained with the sectioning structure.  If
@emph{$use_sections} is set, use section names for the menu entry names.
@emph{$customization_information}, if defined, should hold information needed for
translations.  Translations are only needed when generating the top node menu.

@item $detailmenu = new_detailmenu($customization_information, $registrar, $identifier_target, $menus)
@anchor{Texinfo@asis{::}Structuring $detailmenu = new_detailmenu($customization_information@comma{} $registrar@comma{} $identifier_target@comma{} $menus)}
@cindex @code{new_detailmenu}

Returns a detailmenu tree element formatted as a master node.
@emph{$menus} is an array reference containing the regular menus of the Top node.
@emph{$customization_information} should hold information needed for translations
and error reporting.

The @emph{$registrar} argument can be set to a @ref{Texinfo@asis{::}Report NAME,, Texinfo::Report} object.
If the @emph{$registrar} argument is not set, @emph{$customization_information} is
assumed to be a converter, and error reporting uses converters error
messages reporting functions (@ref{Texinfo@asis{::}Convert@asis{::}Converter Registering error
and warning messages}).

@item $entry = new_node_menu_entry($node, $use_sections)
@anchor{Texinfo@asis{::}Structuring $entry = new_node_menu_entry($node@comma{} $use_sections)}
@cindex @code{new_node_menu_entry}

Returns the Texinfo tree corresponding to a single menu entry pointing to
@emph{$node}.  If @emph{$use_sections} is set, use the section name for the menu
entry name.  Returns @code{undef} if the node argument is missing.

@item $nodes_list = nodes_tree($document)
@anchor{Texinfo@asis{::}Structuring $nodes_list = nodes_tree($document)}
@cindex @code{nodes_tree}

Goes through nodes in @emph{$document} tree and set directions.  Returns the
list of nodes.

This functions sets, in the @code{extra} node element hash:

@table @asis
@item node_directions
@anchor{Texinfo@asis{::}Structuring node_directions}

Hash reference with @emph{up}, @emph{next} and @emph{prev} keys associated to
elements corresponding to node line directions.

@end table

@item number_floats($float_information)
@anchor{Texinfo@asis{::}Structuring number_floats($float_information)}
@cindex @code{number_floats}

Number the floats as described in the Texinfo manual.  Sets
the @emph{float_number} key in the @code{extra} hash of the float
tree elements.

@item $command_name = section_level_adjusted_command_name($element)
@anchor{Texinfo@asis{::}Structuring $command_name = section_level_adjusted_command_name($element)}
@cindex @code{section_level_adjusted_command_name}

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

@item $sections_list = sectioning_structure($document)
@anchor{Texinfo@asis{::}Structuring $sections_list = sectioning_structure($document)}
@cindex @code{sectioning_structure}

This function goes through the parsed document tree and gather information
on the document structure for sectioning commands.  It returns a reference
on the sections elements list.

It sets section elements @code{extra} hash values:

@table @asis
@item section_level
@anchor{Texinfo@asis{::}Structuring section_level}

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

@item section_number
@anchor{Texinfo@asis{::}Structuring section_number}

The sectioning element number.

@item section_childs
@anchor{Texinfo@asis{::}Structuring section_childs}

An array holding sectioning elements children of the element.

@item section_directions
@anchor{Texinfo@asis{::}Structuring section_directions}

Hash reference with @emph{up}, @emph{next} and @emph{prev} keys associated to
elements corresponding to sectioning structure directions.

@item toplevel_directions
@anchor{Texinfo@asis{::}Structuring toplevel_directions}

Hash reference with @emph{up}, @emph{next} and @emph{prev} keys associated to
elements corresponding to toplevel sectioning structure directions,
for elements like @code{@@top}, @code{@@chapter}, @code{@@appendix}, not taking into
account @code{@@part} elements.

@end table

An element is created and used as the root of the sectioning commands tree.
This element is associated to the @code{extra} @emph{sectioning_root} key of the first
section element of the sections list.  It is also at the top of the tree when
following the @emph{up} @emph{section_directions}.

@item set_menus_node_directions($document);
@anchor{Texinfo@asis{::}Structuring set_menus_node_directions($document);}
@cindex @code{set_menus_node_directions}

Goes through menu and set directions.

This functions sets, in the @code{extra} node element hash reference:

@table @asis
@item menu_directions
@anchor{Texinfo@asis{::}Structuring menu_directions}

Hash reference with @emph{up}, @emph{next} and @emph{prev} keys associated to
elements corresponding to menu directions.

@end table

@item warn_non_empty_parts($document)
@anchor{Texinfo@asis{::}Structuring warn_non_empty_parts($document)}
@cindex @code{warn_non_empty_parts}

Register a warning in for each @code{@@part} in global commands information of
@emph{$document} that is not empty.

@end table

@node Texinfo@asis{::}Structuring SEE ALSO
@section Texinfo::Structuring SEE ALSO

@url{http://www.gnu.org/s/texinfo/manual/texinfo/, Texinfo manual},
@ref{Texinfo@asis{::}Document NAME,, Texinfo::Document}.

@node Texinfo@asis{::}Structuring AUTHOR
@section Texinfo::Structuring AUTHOR

Patrice Dumas, <pertusus@@free.fr>

@node Texinfo@asis{::}Structuring COPYRIGHT AND LICENSE
@section 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.