doc/tta_api/api_includes/Texinfo-Structuring.texi

@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 construct_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.
  sectioning_structure($document);
  construct_nodes_tree($document);
  check_node_tree_menu_structure($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 node tree is analysed
with @code{construct_nodes_tree}.  Structural checking and warning
on the consistency of menus and sectioning structure is done by
@code{check_node_tree_menu_structure}.  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 error messages list 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 corresponding autogenerated node directions set.

@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 and @emph{Top} node first node
directions.

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

Check consistency of menus, sectioning and nodes directions.

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

Find the @emph{$node_relations} node relations 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_relations, $lang_translations, $debug_level, $use_sections)
@anchor{Texinfo@asis{::}Structuring $new_menu = new_complete_node_menu($node_relations@comma{} $lang_translations@comma{} $debug_level@comma{} $use_sections)}
@cindex @code{new_complete_node_menu}

Returns a @code{@@menu} Texinfo tree element for the node relations
@emph{$node_relations}, 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.  The
@emph{$lang_translations} argument should be an array reference with one or two
elements.  The first element of the array is the language used for translations.
The second element, if set, should be an hash reference holding
translations already done.  @emph{$debug_level} is an optional debugging level
similar to the @code{DEBUG} customization variable.  If set, it is supplied to the
function called for translations.  Translations are only needed when generating
the top node menu.

@item $detailmenu = new_detailmenu($lang_translations, $converter, $document, $identifier_target, $nodes_list, $debug, $menus)
@anchor{Texinfo@asis{::}Structuring $detailmenu = new_detailmenu($lang_translations@comma{} $converter@comma{} $document@comma{} $identifier_target@comma{} $nodes_list@comma{} $debug@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{$lang_translations} argument should be an array reference with one or two
elements.  The first element of the array is the language used for translations.
The second element, if set, should be an hash reference holding translations
already done.  If @emph{$debug} optional arguments is set, debugging mode
is assumed.  @emph{$converter} should hold information needed for
translations and error reporting.  @emph{$identifier_target} should hold
information on cross-reference target commands, typically obtained by
calling @ref{Texinfo@asis{::}Document $identifier_target = labels_information($document),, @code{Texinfo::Document::labels_information}}.
@emph{$nodes_list} should be the list of nores relations information, typically
obtained by calling @ref{Texinfo@asis{::}Document $nodes_relations_list = nodes_list($document),, @code{Texinfo::Document::nodes_list}}.

@emph{$converter}, if set, is used for error reporting
(@ref{Texinfo@asis{::}Convert@asis{::}Converter Registering error and warning messages}).  If
not set, the @emph{$document} is used for error reporting instead.

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

Returns the Texinfo tree corresponding to a single menu entry pointing to
@emph{$node_relations}.
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 construct_nodes_tree($document)
@anchor{Texinfo@asis{::}Structuring construct_nodes_tree($document)}
@cindex @code{construct_nodes_tree}

Goes through nodes in @emph{$document} tree and set directions.
This functions sets, in each node relations 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
the node line direction node relations.

@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 sectioning_structure($document)
@anchor{Texinfo@asis{::}Structuring 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 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.

@end table

The following is set in section relations hashes:

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

An array holding sectioning element children.  The children are also
section relations.

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

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

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

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

@end table

After calling this function, information on the sectioning tree root
can be obtained by calling @code{$document->sectioning_root()}.

@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, <bug-texinfo@@gnu.org>

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