Texinfo::Structuring - information on Texinfo::Document document structure
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());
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 allows to collect information on a Texinfo
document structure. 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.
No method is exported in the default case.
Most methods use the Texinfo::Report registrar from a parsed document
for error reporting. Most also require Texinfo customization variables
information, which means an object implementing the get_conf method, in
general a parsed document with registered customization, or, sometime,
a 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
Texinfo::Document.
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 of menu_entry_node container
for menu entries and in the first argument extra hash for internal
references @ref and similar @-commands.
Check that all the nodes are referenced (in menu, @*ref or node direction).
Should be called after complete_node_tree_with_menus in order to
have the autogenerated menus available.
Complete nodes directions with menu directions. Check consistency of menus, sectionning and nodes direction structures.
$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.
Complete $element by adding the $command_name, the command line
argument and @end to turn the element to a proper block command.
Returns a @menu Texinfo tree element 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.
$customization_information, if defined, should hold information needed for
translations. Translations are only needed when generating the top node menu.
Returns a detailmenu tree element formatted as a master node. $menus is an array reference containing the regular menus of the Top node. $customization_information should hold information needed for translations and error reporting.
The $registrar argument can be set to a Texinfo::Report object. If the $registrar argument is not set, $customization_information is assumed to be a converter, and error reporting uses converters error messages reporting functions (Registering error and warning messages).
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.
Goes through nodes in $document tree and set directions. Returns the list of nodes.
This functions sets, in the extra node element hash:
Number the floats as described in the Texinfo manual. Sets
the float_number key in the extra hash of the float
tree elements.
Return the sectioning command name corresponding to the sectioning element $element, adjusted in order to take into account raised and lowered sections, when needed.
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 extra hash values:
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.
The sectioning element number.
An array holding sectioning elements children of the element.
Hash reference with up, next and prev keys associated to elements corresponding to sectioning structure directions.
Hash reference with up, next and prev keys associated to
elements corresponding to toplevel sectioning structure directions,
for elements like @top, @chapter, @appendix, not taking into
account @part elements.
An element is created and used as the root of the sectioning commands tree.
This element is associated to the extra sectioning_root key of the first
section element of the sections list. It is also at the top of the tree when
following the up section_directions.
Goes through menu and set directions.
This functions sets, in the extra node element hash reference:
Register a warning in for each @part in global commands information of
$document that is not empty.
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.