Texinfo::Structuring - information on Texinfo::Document document structure
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());
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 node tree is analysed
with construct_nodes_tree. Structural checking and warning
on the consistency of menus and sectioning structure is done by
check_node_tree_menu_structure. 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 error messages list 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 corresponding autogenerated node directions set.
Complete nodes directions with menu directions and Top node first node directions.
Check consistency of menus, sectioning and nodes directions.
Find the $node_relations node relations 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 the node relations
$node_relations, 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. The
$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. $debug_level is an optional debugging level
similar to the DEBUG customization variable. If set, it is supplied to the
function called 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.
$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 $debug optional arguments is set, debugging mode
is assumed. $converter should hold information needed for
translations and error reporting. $identifier_target should hold
information on cross-reference target commands, typically obtained by
calling Texinfo::Document::labels_information.
$nodes_list should be the list of nores relations information, typically
obtained by calling Texinfo::Document::nodes_list.
$converter, if set, is used for error reporting (Registering error and warning messages). If not set, the $document is used for error reporting instead.
Returns the Texinfo tree corresponding to a single menu entry pointing to
$node_relations.
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. This functions sets, in each node relations 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 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 command formatted number.
The following is set in section relations hashes:
An array holding sectioning element children. The children are also section relations.
Hash reference with up, next and prev keys associated to section directions.
Hash reference with up, next and prev keys associated to toplevel
sectioning relations directions, for elements like @top, @chapter,
@appendix, not taking into account @part elements.
After calling this function, information on the sectioning tree root
can be obtained by calling $document->sectioning_root().
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.