use Texinfo::Structuring qw(sectioning_structure nodes_tree number_floats
associate_internal_references split_by_node split_by_section split_pages
merge_indices sort_indices elements_directions elements_file_directions);
# $tree is a Texinfo document tree. $parser is a Texinfo::Parser object.
# $config is an object implementing the get_conf() method.
my $registrar = $parser->registered_errors();
my $sections_root = sectioning_structure ($registrar, $config, $tree);
my ($labels, $targets_list, $nodes_list) = $parser->labels_information();
my $parser_information = $parser->global_information();
my $global_commands = $parser->global_commands_information();
set_menus_node_directions($registrar, $config, $parser_information,
$global_commands, $nodes_list, $labels);
my $top_node = nodes_tree($registrar, $config, $parser_information,
$nodes_list, $labels);
complete_node_tree_with_menus($registrar, $config, $nodes_list, $top_node);
my $refs = $parser->internal_references_information();
check_nodes_are_referenced($registrar, $config, $nodes_list, $top_node,
$labels, $refs);
associate_internal_references($registrar, $parser, $parser_information,
$labels, $refs);
number_floats($parser->floats_information());
my $tree_units;
if ($split_at_nodes) {
$tree_units = split_by_node($tree);
} else {
$tree_units = split_by_section($tree);
}
split_pages($tree_units, $split);
elements_directions($config, $labels, $tree_units);
elements_file_directions($tree_units);
my $indices_information = $parser->indices_information();
my $merged_index_entries
= merge_indices($indices_information);
my $index_entries_sorted;
if ($sort_by_letter) {
$index_entries_sorted = sort_indices($registrar, $config,
$merged_index_entries, $indices_information,
'by_letter');
} else {
$index_entries_sorted = sort_indices($registrar, $config,
$merged_index_entries,
$indices_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 first allows to collect information on a Texinfo
tree. In most case, it also requires information from a parser object to
do that job. 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.
The following methods depend on the output format, so are usually called from converters.
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
split_by_node nodes are considered to be the main sectioning elements,
while with split_by_section the sectioning command elements are the
main elements. The first mode is typical of Info format, while the second
corresponds to a traditional book. The elements may be further split in
pages, which are not pages as in book pages, but more like web pages,
and hold series of tree unit elements.
The elements may have directions to other elements prepared
by elements_directions. elements_file_directions should also
set direction related to files, provided files are associated with
elements by the user.
merge_indices may be used to merge indices, which may be sorted
with sort_indices.
No method is exported in the default case.
Most methods takes a Texinfo::Report $registrar as argument for
error reporting. Most also require Texinfo customization variables
information, which means an object implementing the get_conf method, in
practice the main program configuration or a converter
(Getting and setting customization variables). Other common input arguments such as parser information,
labels or refs are obtained from a parser, see Texinfo::Parser.
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 menu_entry_node hash for
menu entries and in the first argument extra hash for internal
references @ref and similar @-commands. Register errors in $registrar.
Check that all the nodes are referenced (in menu, @*ref or node direction). Register errors in $registrar.
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. Register errors in $registrar.
Directions are set up for the tree unit elements in the array reference
$tree_units given in argument. The corresponding hash is in
{'structure'}->{'directions'}
and keys correspond to directions while values are elements.
The following directions are set up:
The element itself.
Element next.
Previous element.
Following node element in reading order. It is the next node, or the first in menu or the next of the up node.
Preceding node element.
The up, next and previous node elements.
The up, next and previous section elements.
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 that contains the subsection.
The next top level section element.
In the directions reference described above for elements_directions,
sets the PrevFile and NextFile directions to the elements in
previous and following files.
It also sets FirstInFile* directions for all the elements by using the directions of the first element in file. So, for example, 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.
$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.
Return a string suitable as a sort string, for index entries.
The index entry processed is $entry_tree_element, and can be a
@subentry. $main_entry is the main index entry tree element
that can be used to gather information. $sortas can be given to
override the sort string (typically obtained from @sortas). The
$options are options used for Texinfo to text conversion for
the generation of the sort string, typically obtained from
setup_index_entry_keys_formatting.
Using information returned by 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
merged into.
The $merged_entries returned is a hash reference whose keys are the index names and values arrays of index entry structures described in details in Texinfo::Parser index_entries.
Returns the texinfo tree corresponding to a block command named $command_name with contents $content and parent in tree $parent.
Returns a texinfo tree menu 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.
Returns a detailmenu tree element formatted as a master node. $translations, if defined, should be a Texinfo::Translations object and should also hold customization information. $menus is an array reference containing the regular menus of the Top node.
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 and set directions. Returns the top node. Register errors in $registrar.
This functions sets, in the structure node element hash:
Number the floats as described in the Texinfo manual. Sets
the number key in the structure 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 tree and gather information on the document structure for sectioning commands. It returns $sections_root the root of the sectioning commands tree and a reference on the sections elements list. Errors are registered in $registrar.
It sets section elements structure 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.
The up, previous and next sectioning elements.
The next and previous and up sectioning elements of toplevel sectioning
elements (like @top, @chapter, @appendix), not taking into
account @part elements.
Goes through menu and set directions. Register errors in $registrar.
This functions sets, in the structure node element hash reference:
Return options for conversion of Texinfo to text relevant for index keys sorting.
If $sort_by_letter is set, sort by letter, otherwise sort all entries together. In both cases, a hash reference with index names as keys $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 keys, a letter key with the letter, and an 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.
$index_entries_sort_strings is a hash reference associating the index entries with the strings that were used to sort them.
Register errors in $registrar.
Returns a reference array of tree units where a node is associated to 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.
Tree units are regular tree elements with type unit, the associated
nodes and sectioning tree elements are in the array associated with the
contents key. The associated elements have a associated_unit key
set in the structure hash that points to the associated tree unit.
Tree units have directions in the structure
hash reference, namely unit_next and unit_prev pointing to the
previous and the next tree unit.
In the extra hash reference, tree units have:
Similarly with 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 structure and extra hash keys set are the same, except that
unit_command is the sectioning command associated with the element.
The tree units from the array reference argument have an extra
first_in_page value set in the structure hash reference to
the first tree unit in the group, and based on the value of $split.
The possible values for $split are
Register a warning in $registrar for each @part that is not empty
in $global_commands information (typically obtained by calling
global_commands_information() on a parser).
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.