Texinfo::OutputUnits - setup and manage Texinfo document output units
use Texinfo::OutputUnits qw(split_by_node split_by_section split_pages
units_directions units_file_directions);
# $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 $identifier_target = $document->labels_information();
my $output_units;
if ($split_at_nodes) {
$output_units = split_by_node($document);
} else {
$output_units = split_by_section($document);
}
split_pages($output_units, $split);
units_directions($identifier_target, $output_units,
$document->get_conf('DEBUG'));
units_file_directions($output_units);
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.
You can convert a Texinfo parsed document to an output format in a Converter code by first splitting the nodes and sectioning commands in units and then converting those units. We will call the main unit of output documents an output unit. Usually a node is associated with a following sectioning command, while a sectioning command is associated with a previous node; they both together make up the output unit. Either the node or the sectioning command is considered to be the main element component.
The module provides methods to setup output units associated with
node and sectioning commands of a Texinfo parsed document. With
split_by_node nodes are used as the main component for the separation of
output units, while with split_by_section the sectioning command elements
are used to separate output units. The first mode is typical of Info format,
while the second corresponds better to a traditional book. Note that the
result is different when there are unassociated sectioning commands or nodes,
in the usual case of each node being associated with a sectioning command and
each sectioning command being associated with a node, splitting by node or by
section does not make much difference as each output unit will consist of the
node and the associated section in both cases.
Output units are used for conversion to HTML and Info output formats. See
Texinfo::Convert::Converter::convert_output_unit
for more information on conversion of output units in Converters. Output units
are not relevant for all the formats, the Texinfo tree can also be converted
directly, see Texinfo::Convert::Converter::output_tree.
The output units may be further grouped in pages, which are not pages as
in book pages, but more like web pages, and hold series of output units.
The output units may have directions to other output units prepared
by units_directions. units_file_directions should also
set direction related to files, provided files are associated with
output units by the user.
No method is exported in the default case.
Output units are hash references created with the following keys:
typeThe type of the output unit. Set to unit for output units associated
with nodes and sectioning commands.
unit_commandMain node or sectioning command associated with the output unit.
unit_contentsThis array reference holds all the nodes and sectioning commands Texinfo tree
elements associated with the output unit (in order). The Texinfo tree nodes
and sectioning commands elements have an associated_unit key set that points
to the output unit.
tree_unit_directionsHash reference with next and prev pointing to the previous and the next output unit.
Call one of the following methods to create output units and associate them with nodes and sectioning command Texinfo tree elements:
Returns a reference array of output units where a node is associated with the following sectioning commands. Sectioning commands without nodes are also with the previous node, while nodes without sectioning commands are alone in their output units.
Each output unit unit_command key points to the node command associated with the output unit.
Similarly with split_by_node, returns an array of output units. This
time, lone nodes are associated with the previous sections and lone
sections makes up an output unit.
Output units unit_command keys point to the sectioning command associated with the output unit.
You can call split_pages to group together output units:
Add the first_in_page key to each output unit in the array reference argument $output_units, set to the first output unit in the group.
The first output unit in the group is based on the value of $split:
You can call the following methods to set output units directions:
The $identifier_target argument associates identifiers with target elements
and is generally obtained from a parsed document,
Texinfo::Document::labels_information.
Directions are set up for the output units in the array reference
$output_units given in argument. The corresponding hash is associated
with the directions key. In this hash, keys correspond to directions
while values are output units.
$print_debug is optional. If set, some debugging information is printed.
The following directions are set up:
The output unit itself.
Unit next.
Previous output unit.
Following node output unit in reading order. It is the next node unit, or the first in menu or the next of the up node.
Preceding node output unit.
The up, next and previous node output unit.
The up, next and previous section output unit.
For top level output units, the previous top level output unit. For other output units the up top level unit. For example, for a chapter output unit it is the previous chapter output unit, for a subsection output unit it is the chapter output unit that contains the subsection.
The next top level output unit.
In the directions reference described above for units_directions,
sets the PrevFile and NextFile directions to the output units in
previous and following files.
It also sets FirstInFile* directions for all the output units by using the directions of the first output unit in file. So, for example, FirstInFileNodeNext is the output unit associated with the next node of the first output unit node in the file for each output unit in the file.
The API for association of pages/output units to files is not defined yet.
Texinfo manual, Texinfo::Document, Texinfo::Convert::Converter.
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.