Texinfo modules documentation
*****************************

1 Texinfo::Commands
*******************

1.1 Texinfo::Commands NAME
==========================

Texinfo::Commands - Classification of commands

1.2 Texinfo::Commands SYNOPSIS
==============================

  use Texinfo::Commands;
  if ($Texinfo::Commands::accent_commands{$a_command}) {
    print STDERR "$a_command is an accent command\n";
  }

1.3 Texinfo::Commands NOTES
===========================

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.

1.4 Texinfo::Commands DESCRIPTION
=================================

Texinfo::Commands holds a few hashes with information on @-commands and
hashes classifying Texinfo @-commands.

1.5 @-COMMAND INFORMATION
=========================

Hashes are defined as ‘our’ variables, and are therefore available
outside of the module.

%index_names

     Hash describing the default Texinfo indices.  The format of this
     hash is described in
     ^?‘TexinfoDocument::indices_information’^?: Texinfo::Document
     $indices_information = $document->indices_information().

1.6 @-COMMAND CLASSES
=====================

Hashes are defined as ‘our’ variables, and are therefore available
outside of the module.

   The key of the hashes are @-command names without the @.  The
following hashes are available:

%accent_commands

     Accent @-commands taking an argument, like ‘@'’ or ‘@ringaccent’,
     including ‘@dotless’ and ‘@tieaccent’.

%block_commands

     Commands delimiting a block with a closing ‘@end’.  The values are:

     _conditional_

          ‘@if*’ commands;

     _def_

          Definition commands like ‘@deffn’;

     _float_

          ‘@float’;

     _format_raw_

          raw output format commands such as ‘@html’ or ‘@info’;

     _item_container_

          commands with ‘@item’ containing any content, ‘@itemize’ and
          ‘@enumerate’;

     _item_line_

          commands like ‘@table’ in which the ‘@item’ argument is on its
          line;

     _menu_

          menu @-commands, ‘@menu’, ‘@detailmenu’ and ‘@direntry’;

     _math_

          Math block commands, like ‘@displaymath’.

     _multitable_

          ‘@multitable’;

     _other_

          The remaining block commands.

     _preformatted_

          Commands whose content should not be filled, like ‘@example’
          or ‘@display’.

     _quotation_

          Commands like ‘@quotation’.

     _raw_

          @-commands that have no expansion of @-commands in their
          bodies (‘@macro’, ‘@verbatim’ and ‘@ignore’);

     _region_

          Commands delimiting a region of the document out of the main
          processing: ‘@titlepage’, ‘@copying’, ‘@documentdescription’.

%blockitem_commands

     Block commands containing ‘@item’ with possible content before an
     ‘@item’, like ‘@itemize’, ‘@table’ or ‘@multitable’.

%brace_code_commands

     Brace commands that have their argument in code style, like
     ‘@code’.

%brace_commands

     The commands that take braces.  Value is _noarg_ for brace commands
     without argument such as ‘@AA’, ‘@TeX’, or ‘@equiv’.  Other values
     include _accent_, _arguments_, _context_ and other values.

%close_paragraph_commands

     Commands that stop a paragraph.  Root commands are not specified
     here, but they also close paragraphs.

%commands_args_number

     Set to the number of arguments separated by commas that may appear
     in braces or on the @-command line.  That means 0 or unset for most
     block commands, including ‘@example’ which has an unlimited
     (variadic) number of arguments, 1 for ‘@quotation’, 2 for ‘@float’,
     1 for most brace commands, 2 for ‘@email’ and ‘@abbr’, 5 for
     ‘@image’ and ‘@ref’.

     Values are not necessarily set for all the commands, as commands
     are also classified by type of command, some type of commands
     implying a number of arguments, and the number of arguments may not
     be set if it corresponds to the default (0 for block commands, 1
     for other commands that take arguments).

%contain_basic_inline_commands

     Commands containing simple text only, much like paragraph text, but
     without ‘@ref’, ‘@footnote’, ‘@titlefont’, ‘@anchor’ nor ‘@verb’.

%contain_plain_text_commands

     Commands accepting only plain text with accent, symbol and glyph
     commands.

%def_commands

     Definition commands.

%default_index_commands

     Index entry commands corresponding to default indices.  For example
     ‘@cindex’.

%explained_commands

     @-commands whose second argument explain first argument and further
     @-command call without first argument, as ‘@abbr’ and ‘@acronym’.

%formattable_line_commands

     Line commands which may be formatted as text, but that require
     constructing some replacement text, for example ‘@printindex’,
     ‘@need’ or ‘@verbatiminclude’.  ‘@contents’ and ‘@shortcontents’
     are not in this hash, since they are in a corresponding situation
     only when the tables of contents are formatted where the commands
     are.

%formatted_nobrace_commands

     Commands not taking brace formatted as text or with text in the
     main document body, corresponding to symbol commands such as ‘@@’
     or ‘@:’ and commands such as ‘@item’.  @-commands appearing only in
     headers are not in this hash, but in in
     ‘%in_heading_spec_commands’.

%formatted_line_commands

     Line commands which arguments may be formatted as text, such as
     ‘@center’, ‘@author’, ‘@item’, ‘@node’, ‘@chapter’ and other.
     Index commands may be formatted as text too, but they may be added
     with ‘@def*index’, therefore they are not in that hash.  Also, in
     general, they are not formatted as text where they appear, only
     when an index is printed.

%heading_spec_commands

     @-commands used to specify custom headings, like ‘@everyheading’.

%in_heading_spec_commands

     Special @-commands appearing in custom headings, such as
     ‘@thischapter’, ‘@thistitle’ or ‘@|’.

%in_index_commands

     @-commands only valid in index entries, such as ‘@sortas’ or
     ‘@subentry’.

%inline_conditional_commands

%inline_format_commands

     Inline conditional commands, like ‘@inlineifclear’, and inline
     format commands like ‘@inlineraw’ and ‘@inlinefmt’.

%letter_no_arg_commands

     @-commands with braces but no argument corresponding to letters,
     like ‘@AA{}’ or ‘@ss{}’ or ‘@o{}’.

%math_commands

     @-commands which contains math, like ‘@math’ or ‘@displaymath’.

%line_commands

     Commands that do not take braces, take arguments on the command
     line and are not block commands either, like ‘@node’, ‘@chapter’,
     ‘@cindex’, ‘@deffnx’, ‘@end’, ‘@footnotestyle’, ‘@set’,
     ‘@settitle’, ‘@itemx’, ‘@definfoenclose’, ‘@comment’ and many
     others.

     Note that ‘@item’ is in ‘%line_commands’ for its role in ‘@table’
     and similar @-commands.

%no_paragraph_commands

     Commands that do not start a paragraph.

%nobrace_commands

     Command that do not take braces, do not have argument on their line
     and are not block commands either.  The value is _symbol_ for
     single character non-alphabetical @-commands such as ‘@@’, ‘@ ’ or
     ‘@:’.  Other commands in that hash include ‘@indent’, ‘@tab’ or
     ‘@thissection’.

     Note that ‘@item’ is in ‘%nobrace_commands’ for its role in
     ‘@multitable’, ‘@itemize’ and ‘@enumerate’.

%non_formatted_block_commands

     Block commands not formatted as text, such as ‘@ignore’ or
     ‘@macro’.

%non_formatted_brace_commands

     Brace commands that are not immediately replaced with text, such as
     ‘anchor’, ‘caption’, ‘errormsg’ and others.

%preamble_commands

     @-commands that do not stop the preamble.

%preformatted_commands

%preformatted_code_commands

     _%preformatted_commands_ is for commands whose content should not
     be filled, like ‘@example’ or ‘@display’.  If the command is meant
     for code, it is also in _%preformatted_code_commands_, like
     ‘@example’.

%ref_commands

     Cross reference @-command referencing nodes, like ‘@xref’ or
     ‘@link’.

%root_commands

     Commands that are at the root of a Texinfo document, namely ‘@node’
     and sectioning commands, except heading commands like ‘@heading’.

%sectioning_heading_commands

     All the sectioning and heading commands.

%variadic_commands

     Commands with unlimited arguments, like ‘@example’.

1.7 Texinfo::Commands SEE ALSO
==============================

^?TexinfoParser^?: Texinfo::Parser NAME.

1.8 Texinfo::Commands AUTHOR
============================

Patrice Dumas, <pertusus@free.fr>

1.9 Texinfo::Commands 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.

2 Texinfo::Common
*****************

2.1 Texinfo::Common NAME
========================

Texinfo::Common - Texinfo modules common data and miscellaneous methods

2.2 Texinfo::Common SYNOPSIS
============================

  use Texinfo::Common;

  my @commands_to_collect = ('math');
  my $collected_commands
    = Texinfo::Common::collect_commands_in_tree($document_root,
                                             \@commands_to_collect);

  my $package_version
    = Texinfo::Common::get_build_constant('PACKAGE_AND_VERSION');

2.3 Texinfo::Common NOTES
=========================

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.

2.4 Texinfo::Common DESCRIPTION
===============================

Texinfo::Common holds hashes with miscellaneous information and some
hashes with information on Texinfo @-commands, as well as miscellaneous
methods.

2.5 MISC INFORMATION
====================

Hashes are defined as ‘our’ variables, and are therefore available
outside of the module.

   Values defined for a Texinfo build independently of any document or
output format are available by calling ‘get_build_constant’:

$value = get_build_constant($name)

     The following build constants are available:

     PACKAGE

     PACKAGE_CONFIG

     PACKAGE_AND_VERSION

     PACKAGE_AND_VERSION_CONFIG

     PACKAGE_NAME

     PACKAGE_NAME_CONFIG

     PACKAGE_VERSION

     PACKAGE_VERSION_CONFIG

     PACKAGE_URL

     PACKAGE_URL_CONFIG

          Texinfo package name and versions.  Values of build constants
          without ‘_CONFIG’ appended are set by configure.  For each
          variable set by configure there is another one with ‘_CONFIG’
          appended to the name set to the same value, to match the name
          of the macros set in C. So, for example
          ‘PACKAGE_VERSION_CONFIG’ value is the same as
          ‘PACKAGE_VERSION’, set to the ‘PACKAGE_VERSION’ value set by
          configure.

%texinfo_output_formats

     Cannonical output formats that have associated conditionals.  In
     practice corresponds to ‘format_raw’ ‘%block_commands’ plus ‘info’
     and ‘plaintext’.

   TODO: undocumented %null_device_file
%default_parser_customization_values %multiple_at_command_options
%unique_at_command_options %converter_cmdline_options
%default_main_program_customization_options
%converter_customization_options %document_settable_at_commands %def_map
%command_structuring_level %level_to_structuring_command
%encoding_name_conversion_map %text_brace_no_arg_commands

2.6 @-COMMAND INFORMATION
=========================

Hashes are defined as ‘our’ variables, and are therefore available
outside of the module.

   The key of the hashes are @-command names without the @.  The
following hashes are available:

%all_commands

     All the @-commands.

%def_aliases

%def_no_var_arg_commands

     ‘%def_aliases’ associates an aliased command to the original
     command, for example ‘defun’ is associated to ‘deffn’.

     ‘%def_no_var_arg_commands’ associates a definition command name
     with a true value if the _argument_ on the definition command line
     can contain non-metasyntactic variables.  For instance, it is true
     for ‘deftypevr’ but false for ‘defun’, since ‘@defun’ _argument_ is
     supposed to contain metasyntactic variables only.

%nobrace_symbol_text

     Values are ASCII representation of single character
     non-alphabetical commands without brace such as ‘*’ or ‘:’.  The
     value may be an empty string.

%small_block_associated_command

     Associate small command like ‘smallexample’ to the regular command
     ‘example’.

2.7 Texinfo::Common METHODS
===========================

Two methods are exported in the default case for Texinfo modules
messages translation in the Uniforum gettext framework, ‘__’ and ‘__p’.

   The Texinfo tree and Texinfo tree elements used in argument of some
functions are documented in ^?TexinfoParser TEXINFO TREE^?::.  When
customization information is needed, an object that defines ‘set_conf’
and/or ‘get_conf’ is expected, for example a converter inheriting from
‘Texinfo::Convert::Converter’, see ^?TexinfoConvert::Converter
Getting and setting customization variables^?::.

$translated_string = __($msgid)

$translated_string = __p($msgctxt, $msgid)

     Returns the _$msgid_ string translated in the Texinfo messages text
     domain.  ‘__p’ can be used instead of ‘__’ to pass a _$msgctxt_
     context string to provide translators with information on the
     string context when the string is short or if the translation could
     depend on the context.  ‘__’ corresponds to the ‘gettext’ function
     and ‘__p’ to the ‘pgettext’ function.

     It is not advised to use those functions in user-defined code.  It
     is not practical either, as the translatable strings marked by ‘__’
     or ‘__p’ need to be collected and added to the Texinfo messages
     domain.  This facility could only be used in user-defined code with
     translatable strings already present in the domain anyway.  In
     fact, these functions are documented mainly because they are
     automatically exported.

     See Locale::Messages (https://metacpan.org/pod/Locale::Messages),
     ‘gettext’ C interface
     (https://www.gnu.org/software/gettext/manual/html_node/gettext.html),
     Perl in GNU Gettext
     (https://www.gnu.org/software/gettext/manual/html_node/Perl.html).
     For translation of strings in output, see
     ^?TexinfoTranslations^?: Texinfo::Translations NAME.

collect_commands_in_tree($tree, $commands_list)

     Returns a hash reference with keys @-commands names specified in
     the _$commands_list_ array reference and values arrays of tree
     elements corresponding to those @-command found in _$tree_ by
     traversing the tree.

collect_commands_list_in_tree($tree, $commands_list)

     Return a list reference containing the tree elements corresponding
     to the @-commands names specified in the _$commands_list_ found in
     _$tree_ by traversing the tree.  The order of the @-commands should
     be kept.

$encoding_name = element_associated_processing_encoding($element)

     Returns the encoding name that can be used for decoding derived
     from the encoding that was set where _$element_ appeared.

$result = element_is_inline($element, $check_current)

     Return true if the element passed in argument is in running text
     context.  If the optional _$check_current_ argument is set, check
     the element itself, in addition to the parent context.

($encoded_file_name, $encoding) = encode_file_name($file_name, $input_encoding)

     Encode the _$file_name_ text string to a binary string
     _$encoded_file_name_ based on _$input_encoding_.  Also returns the
     _$encoding_ name actually used which may have undergone some
     normalization.  This function is mostly a wrapper around Encode
     Encode::encode (https://metacpan.org/pod/Encode#encode) which
     avoids calling the module if not needed.  Do nothing if
     _$input_encoding_ is ‘undef’.

$text = enumerate_item_representation($specification, $number)

     This function returns the number or letter correponding to item
     number _$number_ for an ‘@enumerate’ specification
     _$specification_, appearing on an ‘@enumerate’ line.  For example

       enumerate_item_representation('c', 3)

     is ‘e’.

$command = find_parent_root_command($object, $tree_element)

     Find the parent root command (sectioning command or node) of a tree
     element.  The _$object_ argument is optional, its ‘global_commands’
     field is used to continue through ‘@insertcopying’ if in a
     ‘@copying’.

$entry_content_element = index_content_element($element, $prefer_reference_element)

     Return a Texinfo tree element corresponding to the content of the
     index entry associated to _$element_.  If
     _$prefer_reference_element_ is set, prefer an untranslated element.
     If the element is an index command like ‘@cindex’ or an ‘@ftable’
     ‘@item’, the content element is the argument of the command.  If
     the element is a definition line, the index entry element is based
     on the name and class.

$result = is_content_empty($tree, $do_not_ignore_index_entries)

     Return true if the _$tree_ has content that could be formatted.
     _$do_not_ignore_index_entries_ is optional.  If set, index entries
     are considered to be formatted.

$file = locate_include_file($customization_information, $file_path)

     Locate _$file_path_.  If _$file_path_ is an absolute path or has
     ‘.’ or ‘..’ in the path directories it is checked that the path
     exists and is a file.  Otherwise, the file name in _$file_path_ is
     located in include directories also used to find texinfo files
     included in Texinfo documents.  _$file_path_ should be a binary
     string.  ‘undef’ is returned if the file was not found, otherwise
     the file found is returned as a binary string.

($index_entry, $index_info) = lookup_index_entry($index_entry_info, $indices_information)

     Returns an _$index_entry_ hash based on the _$index_entry_info_ and
     _$indices_information_.  Also returns the _$index_info_ hash with
     information on the index associated to the index entry.
     _$index_entry_info_ should be an array reference with an index name
     as first element and the index entry number in that index (1-based)
     as second element.  In general, the _$index_entry_info_ is an
     ‘extra’ _index_entry_ associated to
     an element.

     The _$index_entry_ hash is described in ^?TexinfoDocument
     index_entries^?::.  The _$index_info_ hash is described in
     ^?‘TexinfoDocument::indices_information’^?: Texinfo::Document
     $indices_information = $document->indices_information().

$normalized_name = normalize_top_node_name($node_string)

     Normalize the node name string given in argument, by normalizing
     Top node case.

$result = remove_from_array($array, $element)

     Remove first occurence of _$element_ in the array reference
     _$array_.  Return the removed element, or ‘undef’ if not found.

$level = section_level($section)

     Return numbered level of the tree sectioning element _$section_, as
     modified by raise/lowersections.

$element = set_global_document_command($customization_information, $global_commands_information, $cmdname, $command_location)

     Set the Texinfo customization variable corresponding to _$cmdname_
     in _$customization_information_.  The
     _$global_commands_information_ should contain information about
     global commands in a Texinfo document, typically obtained from a
     parsed document $document->global_commands_information().
     _$command_location_
     specifies where in the document the value should be taken from, for
     commands that may appear more than once.  The possibilities are:

     last

          Set to the last value for the command.

     preamble

          Set sequentially to the values in the Texinfo preamble.

     preamble_or_first

          Set to the first value of the command if the first command is
          not in the Texinfo preamble, else set as with _preamble_,
          sequentially to the values in the Texinfo preamble.

     The _$element_ returned is the last element that was used to set
     the customization value, or ‘undef’ if no customization value was
     found.

     Notice that the only effect of this function is to set a
     customization variable value, no @-command side effects are run, no
     associated customization variables are set.

$status = set_informative_command_value($customization_information, $element)

     Set the Texinfo customization option corresponding to the tree
     element _$element_.  The command associated to the tree element
     should be a command that sets some information, such as
     ‘@documentlanguage’, ‘@contents’ or ‘@footnotestyle’ for example.
     Return true if the command argument was found and the customization
     variable was set.

set_output_encoding($customization_information, $document)

     If not already set, set ‘OUTPUT_ENCODING_NAME’ based on input file
     encoding.

set_output_perl_encoding($customization_information)

     Set ‘OUTPUT_PERL_ENCODING’ based on ‘OUTPUT_ENCODING_NAME’.  In
     general, ‘OUTPUT_PERL_ENCODING’ should not be set directly by
     user-defined code such that it corresponds to
     ‘OUTPUT_ENCODING_NAME’.

$split_contents = split_custom_heading_command_contents($element)

     Split the _$element_ contents at ‘@|’ in at max three parts.
     Return an element containing the split parts in contents, or
     ‘undef’ if the _$element_ has no useful content.  The input
     _$element_ is supposed to be ‘$element->{'args'}->[0]’ of
     ‘%Texinfo::Commands::heading_spec_commands’ commands such as
     ‘@everyheading’.

$status = valid_customization_option($name)

     Return true if the _$name_ is a known customization option.

$status = valid_tree_transformation($name)

     Return true if the _$name_ is a known tree transformation name that
     may be passed with ‘TREE_TRANSFORMATIONS’ to modify a texinfo tree.

2.8 Texinfo::Common SEE ALSO
============================

^?TexinfoParser^?: Texinfo::Parser NAME, see
^?TexinfoConvert::Converter^?: Texinfo::Convert::Converter NAME. and
^?TexinfoReport^?: Texinfo::Report NAME.

2.9 Texinfo::Common AUTHOR
==========================

Patrice Dumas, <pertusus@free.fr>

2.10 Texinfo::Common 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.

3 Texinfo::Parser
*****************

3.1 Texinfo::Parser NAME
========================

Texinfo::Parser - Parse Texinfo code into a Perl tree

3.2 Texinfo::Parser SYNOPSIS
============================

  use Texinfo::Parser;

  my $parser = Texinfo::Parser::parser();
  my $document = $parser->parse_texi_file("somefile.texi");

  my ($errors, $errors_count) = $document->parser_errors();
  foreach my $error_message (@$errors) {
    warn $error_message->{'error_line'};
  }

3.3 Texinfo::Parser NOTES
=========================

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.

3.4 Texinfo::Parser DESCRIPTION
===============================

‘Texinfo::Parser’ will parse Texinfo text into a Perl tree.  In one pass
it expands user-defined @-commands, conditionals (‘@ifset’,
‘@ifinfo’...)  and ‘@value’ and constructs the tree.  Some extra
information is gathered while doing the tree: for example, the
‘@quotation’ associated to an ‘@author’ command, the number of columns
in a multitable, or the node associated with a section.

3.5 Texinfo::Parser METHODS
===========================

No method is exported in the default case.  The module allows both an
object-oriented syntax, or traditional function, with the parser as an
opaque data structure given as an argument to every function.

3.5.1 Initialization
--------------------

The following method is used to construct a new ‘Texinfo::Parser’
object:

$parser = Texinfo::Parser::parser($options)

     This method creates a new parser.  The options may be provided as a
     hash reference.  Most of those options correspond to Texinfo
     customization options described in the Texinfo manual.

     CPP_LINE_DIRECTIVES

          Handle cpp like synchronization lines if set.  Set in the
          default case.

     EXPANDED_FORMATS

          An array reference of the output formats for which
          ‘@if_FORMAT_’ conditional blocks should be expanded.  Default
          is empty.

     FORMAT_MENU

          Possible values are ‘nomenu’, ‘menu’ and ‘sectiontoc’.  Only
          report menu-related errors for ‘menu’.

     INCLUDE_DIRECTORIES

          An array reference of directories in which ‘@include’ files
          should be searched for.  Default contains the working
          directory, ‘.’.

     IGNORE_SPACE_AFTER_BRACED_COMMAND_NAME

          If set, spaces after an @-command name that take braces are
          ignored.  Default on.

     MAX_MACRO_CALL_NESTING

          Maximal number of nested user-defined macro calls.  Default is
          100000.

     documentlanguage

          A string corresponding to a document language set by
          ‘@documentlanguage’.  It overrides the document
          ‘@documentlanguage’ information, if present.

     values

          A hash reference.  Keys are names, values are the
          corresponding values.  Same as values set by ‘@set’.

3.5.2 Parsing Texinfo text
--------------------------

Different methods may be called to parse some Texinfo code:
‘parse_texi_line’ for a line, ‘parse_texi_piece’ for a fragment of
Texinfo, ‘parse_texi_text’ for a string corresponding to a full document
and ‘parse_texi_file’ for a file.  The first argument of these functions
is a parser.

   When ‘parse_texi_line’ is used, the resulting tree is rooted at a
‘root_line’ type container.  Otherwise, the resulting tree should be
rooted at a ‘document_root’ type container.

$tree = $parser->parse_texi_line($text, $first_line_number)

     This function is used to parse a short fragment of Texinfo code.

     _$text_ is the string containing the texinfo line.
     _$first_line_number_ is the line number of the line, if undef, it
     will be set to 1.

$document = $parser->parse_texi_piece($text, $first_line_number)

     This function is used to parse Texinfo fragments.

     _$text_ is the string containing the texinfo text.
     _$first_line_number_ is the line number of the first text line, if
     undef, it will be set to 1.

$document = $parser->parse_texi_text($text, $first_line_number)

     This function is used to parse a text as a whole document.

     _$text_ is the string containing the texinfo text.
     _$first_line_number_ is the line number of the first text line, if
     undef, it will be set to 1.

$document = $parser->parse_texi_file($file_name)

     The file with name _$file_name_ is considered to be a Texinfo file
     and is parsed into a tree.  _$file_name_ should be a binary string.

   The errors collected during the tree parsing are available with the
resulting document ‘parser_errors’.  These errors are internally
registered in a ‘Texinfo::Report’ object.

($error_warnings_list, $error_count) = $document->parser_errors()

     This function returns as _$error_count_ the count of parsing
     errors.  The _$error_warnings_list_ is an array of hash references
     one for each error, warning or error line continuation.  They are
     described in detail in ^?TexinfoReport::errors^?:
     ^?Texinfo::Report ($error_warnings_list, $error_count) =
     errors($registrar)^?.

3.6 TEXINFO TREE
================

A Texinfo tree element (called element because node is overloaded in the
Texinfo world) is an hash reference.  There are three main categories of
tree element.  Tree elements associated with an @-command have a
‘cmdname’ key holding the @-command name.  Tree elements corresponding
to text fragments have a ‘text’ key holding the corresponding text.
Finally, the last category is other elements, which in most cases have a
‘type’ key holding their name.  Text fragments and @-command elements
may also have an associated type when such information is needed.

   The children of an @-command or of other container element are in the
array referred to with the ‘args’ key or with the ‘contents’ key.  The
‘args’ key is for arguments of @-commands, either in braces or on the
rest of the line after the command, depending on the type of command.
The ‘contents’ key array holds the contents of the texinfo code
appearing within a block @-command, within a container, or within a
‘@node’ or sectioning @-command.

   Another important key for the elements is the ‘extra’ key which is
associated to a hash reference and holds all kinds of information that
is gathered during the parsing and may help with the conversion.

   You can see examples of the tree structure by running makeinfo like
this:

  makeinfo -c DUMP_TREE=1 -c TEXINFO_OUTPUT_FORMAT=parse document.texi

   For a simpler, more regular representation of the tree structure, you
can do:

  makeinfo -c TEXINFO_OUTPUT_FORMAT=debugtree document.texi

3.6.1 Element keys
------------------

cmdname

     The command name of @-command elements.

text

     The text fragment of text elements.

type

     The type of element considered, in general a container.  Frequent
     types encountered are _paragraph_ for a paragraph container,
     _brace_container_ for the container holding a brace @-commands
     content, _line_arg_ and _block_line_arg_ contain the arguments
     appearing on the line of @-commands.  Text fragments may have a
     type to give an information of the kind of text fragment, for
     example _spaces_before_paragraph_ is associated to spaces appearing
     before a paragraph beginning.  Most @-commands elements do not have
     a type associated.

args

     Arguments in braces or on @-command line.  An array reference.

contents

     The Texinfo appearing in the element.  For block commands, other
     containers, ‘@node’ and sectioning commands.  An array reference.

parent

     The parent element.

source_info

     An hash reference corresponding to information on the location of
     the element in the Texinfo input manual.  It should mainly be
     available for @-command elements, and only for @-commands that are
     considered to be complex enough that the location in the document
     is needed, for example to prepare an error message.

     The keys of the line number hash references are

     line_nr

          The line number of the @-command.

     file_name

          The file name where @-command appeared.

     macro

          The user macro name the @-command is expanded from.

info

     A hash reference holding any other information that cannot be
     obtained otherwise from the tree.  See Information available in the ‘info’ key.

extra

     A hash reference holding information that could also be obtained
     from the tree, but is directly associated to the element to
     simplify downstream code.  See Information available in the ‘extra’ key.

3.6.2 Element types
-------------------

3.6.2.1 Types for command elements
..................................

Some types can be associated with @-commands (in addition to ‘cmdname’),
although usually there will be no type at all.  The following are the
possible values of ‘type’ for tree elements for @-commands.

definfoenclose_command

     This type is set for an @-command that is redefined by
     ‘@definfoenclose’.  The beginning is in ‘{'extra'}->{'begin'}’ and
     the end in ‘{'extra'}->{'end'}’.

     The command name is the info _command_name_ value.

index_entry_command

     This is the type of index entry command like ‘@cindex’, and, more
     importantly user-defined index entry commands.  So for example if
     there is:

      @defindex foo
       ...

      @fooindex index entry

     the ‘@fooindex’ @-command element will have the
     _index_entry_command_ type.

     The command name is the info _command_name_ value.

3.6.2.2 Types for text elements
...............................

The text elements may have the following types (or may have no type at
all):

after_menu_description_line

space_at_end_menu_node

     Space after a node in the menu entry, when there is no description,
     and space appearing after the description line.

delimiter

spaces

     Spaces on definition command line separating the definition command
     arguments.  Delimiters, such as comma, square brackets and
     parentheses appearing in definition command line arguments at the
     end of the line, separated from surrounding texts during the
     parsing phase.

empty_line

     An empty line (possibly containing whitespace characters only).

ignorable_spaces_after_command

     spaces appearing after an @-command without braces that does not
     take argument on the line, but which is followed by ignorable
     spaces, such as ‘@item’ in ‘@itemize’ or ‘@multitable’, or
     ‘@noindent’.

spaces_after_close_brace

     Spaces appearing after a closing brace, for some rare commands for
     which this space should be ignorable (like ‘@caption’ or
     ‘@sortas’).

spaces_before_paragraph

     Space appearing before a paragraph beginning.

raw

     Text in an environment where it should be kept as is (in
     ‘@verbatim’, ‘@verb’, ‘@macro’ body).

rawline_arg

     Used for the arguments to some special line commands whose
     arguments aren't subject to the usual macro expansion.  For example
     ‘@set’, ‘@clickstyle’, ‘@unmacro’, ‘@comment’.  The argument is
     associated to the _text_ key.

spaces_at_end

     Space within an index @-command before an @-command interrupting
     the index command.

text_after_end

     Text appearing after @bye.

text_before_beginning

     Text appearing before real content, including the ‘\input
     texinfo.tex’.

untranslated

     English text added by the parser that may need to be translated
     during conversion.  Happens for definition line @-commands aliases
     that leads to prepending text such as "Function".

3.6.2.3 Tree container elements
...............................

Some types of element are containers of portions of the tree, either for
the whole tree, or for contents appearing before ‘@node’ and sectioning
commands.

before_node_section

     Content before nodes and sectioning commands at the beginning of
     ‘document_root’.

document_root

root_line

     ‘root_line’ is the type of the root tree when parsing Texinfo line
     fragments using ‘parse_texi_line’.  ‘document_root’ is the document
     root otherwise.

     ‘document_root’ first content should be ‘before_node_section’, then
     nodes and sections @-commands elements, ‘@bye’ element and
     ‘postamble_after_end’.

postamble_after_end

     This container holds everything appearing after @bye.

preamble_before_beginning

     This container holds everything appearing before the first content,
     including the ‘\input texinfo.tex’ line and following blank lines.

preamble_before_setfilename

     This container holds everything that appears before ‘@setfilename’.

preamble_before_content

     This container holds everything appearing before the first
     formatted content, corresponding to the _preamble_ in the Texinfo
     documentation.

3.6.2.4 Types of container elements
...................................

The other types of element are containers with other elements appearing
in their ‘contents’.  The ‘paragraph’ container holds normal text from
the Texinfo manual outside of any @-commands, and within @-commands with
blocks of text (‘@footnote’, ‘@itemize’ ‘@item’, ‘@quotation’ for
example).  The ‘preformatted’ container holds the content appearing in
@-commands like ‘@example’ and the ‘rawpreformatted’ container holds the
content appearing in format commands such as ‘@html’.  The other
containers are more specific.

   The types of container element are the following:

balanced_braces

     Special type containing balanced braces content (braces included)
     in the context where they are valid, and where balanced braces need
     to be collected to know when a top-level brace command is closed.
     In ‘@math’, in raw output format brace commands and within brace
     @-commands in raw output format block commands.

before_defline

     A container for content before the first ‘@defline’ or
     ‘@deftypeline’ in ‘@defblock’.

before_item

     A container for content before the first ‘@item’ of block
     @-commands with items (‘@table’, ‘@multitable’, ‘@enumerate’...).

brace_container

brace_command_context

brace_arg

line_arg

block_line_arg

following_arg

     Those containers occur within the ‘args’ array of @-commands taking
     an argument.  _brace_container_ is used for the argument to
     commands taking arguments surrounded by braces when the whole text
     in the braces is in the argument.  _brace_arg_ is used for the
     arguments to commands taking arguments surrounded by braces when
     the leading and, in most cases, trailing spaces are not part of the
     argument, and for arguments in braces separated by commas.
     _brace_command_context_ is used for @-commands with braces that
     start a new context (‘@footnote’, ‘@caption’, ‘@math’).

     _line_arg_ is used for commands that take the texinfo code on the
     rest of the line as their argument, such as ‘@settitle’, ‘@node’,
     ‘@section’.  _block_line_arg_ is similar but is used for commands
     that start a new block (which is to be ended with ‘@end’).

     _following_arg_ is used for the accent @-commands argument that did
     not use braces but instead followed the @-command, possibly after a
     space, as

       @~n
       @ringaccent A

     For example

      @code{in code}

     leads to

      {'cmdname' => 'code',
       'args' => [{'type' => 'brace_container',
                   'contents' => [{'text' => 'in code'}]}]}

bracketed_arg

     Bracketed argument.  On definition command and on ‘@multitable’
     line.

bracketed_linemacro_arg

     Argument of a user defined linemacro call in bracket.  It holds
     directly the argument text (which does not contain the braces) and
     does not contain other elements.  It should not appear directly in
     the tree as the user defined linemacro call is replaced by the
     linemacro body.

def_category

def_class

def_type

def_name

def_typearg

def_arg

     Definition line arguments containers corresponding to the different
     parts of a definition line command.  Contains one ‘bracketed_arg’,
     ‘def_line_arg’ or ‘untranslated_def_line_arg’ container.

def_line

def_item

inter_def_item

     The _def_line_ type is associated with a container within a block
     definition command.  It holds the definition line arguments in
     _block_line_arg_.  A ‘@def*’ @-command line command such as
     ‘@deffnx’ or ‘@defline’ also holds the definition line arguments,
     in _line_arg_.  The type of each definition line arguments element
     describes the meaning of the element.  It is one of _def_category_,
     _def_name_, _def_class_, _def_type_, _def_arg_, _def_typearg_,
     _spaces_ or _delimiter_, depending on the definition.

     The container with type _def_item_ holds the definition text
     content.  Content appearing before a definition command with a x
     form is in an _inter_def_item_ container.

def_line_arg

untranslated_def_line_arg

     the _def_line_arg_ contains one or several elements that together
     are a single unit on a definition command line.  This container is
     very similar with a _bracketed_arg_ on a definition line, except
     that there is no bracket.  Appears in definition line arguments
     containers such as _def_category_, _def_arg_ or similar.

     The _untranslated_def_line_arg_ is similar, but only happens for
     automatically added categories and contains only a text element.
     For example, the ‘deffun’ line _def_category_ container may contain
     an _untranslated_def_line_arg_ type container containing itself a
     text element with "Function" as text, if the document language
     demands a translation.  Note that the _untranslated_def_line_arg_
     is special, as, in general, it should not be recursed into, as the
     text within is untranslated, but the untranslated text should be
     gathered when converting the _untranslated_def_line_arg_ type
     container.

macro_call

macro_call_line

rmacro_call

rmacro_call_line

linemacro_call

     Container holding the arguments of a user defined macro, linemacro
     or rmacro.  It should not appear directly in the tree as the user
     defined call is expanded.  The name of the macro, rmacro or
     linemacro is the the info _command_name_ value.  The
     _macro_call_line_ or _rmacro_call_line_ elements are used when
     there are no braces and the whole line is the argument.

macro_name

macro_arg

     Taken from ‘@macro’ definition and put in the ‘args’ key array of
     the macro, _macro_name_ is the type of the text fragment
     corresponding to the macro name, _macro_arg_ is the type of the
     text fragments corresponding to macro formal arguments.

menu_comment

     The _menu_comment_ container holds what is between menu entries in
     menus.  For example, in:

       @menu
       Menu title

       * entry::

       Between entries
       * other::
       @end menu

     Both

       Menu title

     and

       Between entries

     will be in a _menu_comment_.

menu_entry

menu_entry_leading_text

menu_entry_name

menu_entry_separator

menu_entry_node

menu_entry_description

     A _menu_entry_ holds a full menu entry, like

       * node::    description.

     The different elements of the menu entry are in the _menu_entry_
     ‘contents’ array reference.

     _menu_entry_leading_text_ holds the star and following spaces.
     _menu_entry_name_ is the menu entry name (if present),
     _menu_entry_node_ corresponds to the node in the menu entry,
     _menu_entry_separator_ holds the text after the node and before the
     description, in most cases ‘:: ’.  Lastly, _menu_entry_description_
     is for the description.

multitable_head

multitable_body

row

     In ‘@multitable’, a _multitable_head_ container contains all the
     rows with ‘@headitem’, while _multitable_body_ contains the rows
     associated with ‘@item’.  A _row_ container contains the ‘@item’
     and ‘@tab’ forming a row.

paragraph

     A paragraph.  The ‘contents’ of a paragraph (like other container
     elements for Texinfo content) are elements representing the
     contents of the paragraph in the order they occur, such as text
     elements without a ‘cmdname’ or ‘type’, or @-command elements for
     commands appearing in the paragraph.

preformatted

     Texinfo code within a format that is not filled.  Happens within
     some block commands like ‘@example’, but also in menu (in menu
     descriptions, menu comments...).

rawpreformatted

     Texinfo code within raw output format block commands such as ‘@tex’
     or ‘@html’.

table_entry

table_term

table_definition

inter_item

     Those containers appear in ‘@table’, ‘@ftable’ and ‘@vtable’.  A
     _table_entry_ container contains an entire row of the table.  It
     contains a _table_term_ container, which holds all the ‘@item’ and
     ‘@itemx’ lines.  This is followed by a _table_definition_
     container, which holds the content that is to go into the second
     column of the table.

     If there is any content before an ‘@itemx’ (normally only comments,
     empty lines or maybe index entries are allowed), it will be in a
     container with type _inter_item_ at the same level of ‘@item’ and
     ‘@itemx’, in a _table_term_.

3.6.3 Information available in the ‘info’ key
---------------------------------------------

arg_line

     The string correspond to the line after the @-command for
     @-commands that have special arguments on their line, and for
     ‘@macro’ line.

command_name

     Name of commands that can be defined dynamically.  The name of
     index command or definfoenclose defined command (also available in
     _cmdname_ for those commands).  The name of user defined macro,
     rmacro or linemacro called associated with the element holding the
     arguments of the user defined command call.

delimiter

     ‘@verb’ delimiter is in _delimiter_.

inserted

     Set if the element is not in the Texinfo input code, but is
     inserted as a default for @-command argument or as a definition
     command automatically inserted category (for example _Function_ for
     ‘@defun’).

spaces_after_argument

     A reference to an element containing the spaces after @-command
     arguments before a comma, a closing brace or at end of line, for
     some @-commands and bracketed content type with opening brace, and
     line commands and block command lines taking Texinfo as argument
     and comma delimited arguments.  Depending on the @-command, the
     _spaces_after_argument_ is associated with the @-command element,
     or with each argument element.

spaces_after_cmd_before_arg

     For accent commands with spaces following the @-command, like:

      @ringaccent A
      @^ u

     there is a _spaces_after_cmd_before_arg_ key linking to an element
     containing the spaces appearing after the command in _text_.

     Space between a brace @-command name and its opening brace also
     ends up in _spaces_after_cmd_before_arg_.  It is not recommended to
     leave space between an @-command name and its opening brace.

spaces_before_argument

     A reference to an element containing the spaces following the
     opening brace of some @-commands with braces and bracketed content
     type, spaces following @-commands for line commands and block
     command taking Texinfo as argument, and spaces following comma
     delimited arguments.  For context brace commands, line commands and
     block commands, _spaces_before_argument_ is associated with the
     @-command element, for other brace commands and for spaces after
     comma, it is associated with each argument element.

3.6.4 Information available in the ‘extra’ key
----------------------------------------------

3.6.4.1 Extra keys available for more than one @-command
........................................................

element_node

     The node element in the parsed tree containing the element.  Set
     for @-commands elements that have an associated index entry and for
     ‘@nodedescription’.

element_region

     The region command (‘@copying’, ‘@titlepage’) containing the
     element, if it is in such an environement.  Set for @-commands
     elements that have an associated index entry and for @anchor.

index_entry

     The index entry information is associated to @-commands that have
     an associated index entry.  The associated information should not
     be directly accessed, instead
     ^?‘TexinfoCommon::lookup_index_entry’^?: ^?Texinfo::Common
     ($index_entry, $index_info) = lookup_index_entry($index_entry_info,
     $indices_information)^?. should be called on the ‘extra’
     _index_entry_ value:

        my ($index_entry, $index_info)
         = Texinfo::Common::lookup_index_entry(
                             $element->{'extra'}->{'index_entry'},
                             $indices_information);

     The _$indices_information_ is the information on a Texinfo manual
     indices obtained from
     ^?‘TexinfoDocument::indices_information’^?: Texinfo::Document
     $indices_information = $document->indices_information().  The index
     entry information hash returned by
     ‘Texinfo::Common::lookup_index_entry’ is described in
     ^?TexinfoDocument index_entries^?::.

     Currently, the _index_entry_ value is an array reference with an
     index name as first element and the index entry number in that
     index (1-based) as second element.

index_ignore_chars

     A string containing the characters flagged as ignored in key
     sorting in the document by setting flags such as
     _txiindexbackslashignore_.  Set, if not empty, for @-commands
     elements that have an associated index entry.

misc_args

     An array holding strings, the arguments of @-commands taking simple
     textual arguments as arguments, like ‘@everyheadingmarks’,
     ‘@frenchspacing’, ‘@alias’, ‘@synindex’, ‘@columnfractions’.

text_arg

     The string correspond to the line after the @-command for
     @-commands that have an argument interpreted as simple text, like
     ‘@setfilename’, ‘@end’ or ‘@documentencoding’.

3.6.4.2 Extra keys specific of certain @-commands or containers
...............................................................

‘@abbr’

‘@acronym’

     The first argument normalized is in _normalized_.

‘@anchor’

‘@float’

     @-commands that are targets for cross-references have a
     _normalized_ key for the normalized label, built as specified in
     the Texinfo documentation in the _HTML Xref_ node.  There is also a
     _node_content_ key for an element holding the corresponding
     content.

‘@author’

     If in a ‘@titlepage’, the titlepage is in _titlepage_, if in
     ‘@quotation’ or ‘@smallquotation’, the corresponding tree element
     is in _quotation_.

     The author tree element is in the _authors_ array of the
     ‘@titlepage’ or the ‘@quotation’ or ‘@smallquotation’ it is
     associated with.

‘@click’

     In _clickstyle_ there is the current clickstyle command.

‘def_line’

line definition command

     _def_command_ holds the line definition command name, without x if
     the line definition command is an x form of a block definition
     command.  For a ‘def_line’ container, _def_command_ holds the
     command name associated with the ‘def_line’.
     _original_def_cmdname_ is the original def command name.

     If the element is a definition line command and is an x form of a
     block definition command, it has _not_after_command_ set if not
     appearing after the block definition command without x.

     The _def_index_element_ is a Texinfo tree element corresponding to
     the index entry associated to the definition line, based on the
     name and class.  If needed this element is based on translated
     strings.  In that case, if ‘@documentlanguage’ is defined where the
     element is located, _documentlanguage_ holds the documentlanguage
     value.  _def_index_ref_element_ is similar, but not translated, and
     only set if there could have been a translation.

     The _omit_def_name_space_ key value is set and true if the Texinfo
     variable ‘txidefnamenospace’ was set, signaling that the space
     between function definition name and arguments should be omitted.

‘@definfoenclose’ defined commands

     _begin_ holds the string beginning the ‘@definfoenclose’, _end_
     holds the string ending the ‘@definfoenclose’.

‘@documentencoding’

     The argument, normalized is in _input_encoding_name_.

‘@enumerate’

     The _enumerate_specification_ ‘extra’ key contains the enumerate
     argument.

‘@float’

‘@listoffloats’

     If ‘@float’ has a first argument, and for ‘@listoffloats’ argument
     there is a _float_type_ key with the normalized float type.

     _caption_ and _shortcaption_ hold the corresponding tree elements
     associated to a ‘@float’.  The ‘@caption’ or ‘@shortcaption’ have
     the float tree element stored in _float_.

index entry @-command

‘@subentry’

     If an index entry @-command, such as ‘@cindex’, or a ‘@subentry’
     contains a ‘@sortas’ command, _sortas_ holds the ‘@sortas’ command
     content formatted as plain text.

     _subentry_ links to the next level ‘@subentry’ element.
     _subentry_parent_ links to the previous level element.

     Index entry @-command (but not ‘@subentry’) can also have _seentry_
     and _seealso_ keys that link to the corresponding @-commands
     elements.

‘@inlinefmt’

‘@inlineraw’

‘@inlinefmtifelse’

‘@inlineifclear’

‘@inlineifset’

     The first argument is in _format_.  If an argument has been
     determined as being expanded by the Parser, the index of this
     argument is in _expand_index_.  Index numbering begins at 0, but
     the first argument is always the format or flag name, so, if set,
     it should be 1 or 2 for ‘@inlinefmtifelse’, and 1 for other
     commands.

‘@item’ in ‘@enumerate’ or ‘@itemize’

     The _item_number_ ‘extra’ key holds the number of this item.

‘@item’ and ‘@tab’ in ‘@multitable’

     The _cell_number_ index key holds the index of the column of the
     cell.

‘@itemize’

‘@table’

‘@vtable’

‘@ftable’

     The _command_as_argument_ ‘extra’ key points to the @-command as
     argument on the @-command line.

     If the command in argument for ‘@table’, ‘@vtable’ or ‘@ftable’ is
     ‘@kbd’ and the context and ‘@kbdinputstyle’ is such that ‘@kbd’
     should be formatted as code, the _command_as_argument_kbd_code_
     ‘extra’ key is set to 1.

‘@kbd’

     _code_ is set depending on the context and ‘@kbdinputstyle’.

‘@macro’

     _invalid_syntax_ is set if there was an error on the ‘@macro’ line.
     ‘info’ key hash _arg_line_ holds the line after ‘@macro’.

‘menu_entry_node’

     Extra keys with information about the node entry label same as
     those appearing in the ‘@node’ _line_arg_ explicit directions
     arguments ‘extra’ hash labels information.

‘@multitable’

     The key _max_columns_ holds the maximal number of columns.  If
     there is a ‘@columnfractions’ as argument, then the
     _columnfractions_ key is associated with the element for the
     @columnfractions command.

‘@node’

     Explicit directions labels information are available in the
     _line_arg_ node directions arguments of ‘@node’.  Each _line_arg_
     argument element ‘extra’ hash _node_content_ key value is an
     element holding the contents corresponding to the node name.  There
     is also a _manual_content_ key if there is an associated external
     manual name, and a _normalized_ key for the normalized label, built
     as specified in the _HTML Xref_ Texinfo documentation node.

     If you called ^?TexinfoStructuring::nodes_tree^?:
     Texinfo::Structuring $nodes_list = nodes_tree($document), the
     _node_directions_ hash in the ‘@node’ element ‘extra’ associates
     _up_, _next_ and _prev_ keys to the elements corresponding to the
     node line directions.

     An _associated_section_ key holds the tree element of the
     sectioning command that follows the node.  An _node_preceding_part_
     key holds the tree element of the ‘@part’ that precedes the node,
     if there is no sectioning command between the ‘@part’ and the node.
     A _node_description_ key holds the first ‘@nodedescription’
     associated to the node.

     A node containing a menu have a _menus_ key which refers to an
     array of references to menu elements occuring in the node.

     The first node containing a ‘@printindex’ @-command has the
     _isindex_ key set.

‘paragraph’

     The _indent_ or _noindent_ key value is set if the corresponding
     @-commands are associated with that paragraph.

‘@part’

     The next sectioning command tree element is in
     _part_associated_section_.  The following node tree element is in
     _part_following_node_ if there is no sectioning command between the
     ‘@part’ and the node.

‘@ref’

‘@xref’

‘@pxref’

‘@inforef’

     The _brace_arg_ corresponding to the node argument holds
     information on the label, with the same information in the ‘extra’
     hash as for the ‘@node’ _line_arg_ explicit directions arguments.

‘row’

     The _row_number_ index key holds the index of the row in the
     ‘@multitable’.

sectioning command

     The node preceding the command is in _associated_node_.  The part
     preceding the command is in _associated_part_.  If the level of the
     document was modified by ‘@raisections’ or ‘@lowersections’, the
     differential level is in _level_modifier_.

     Other ‘extra’ keys are set when you call
     ^?TexinfoStructuring::sectioning_structure^?: Texinfo::Structuring
     $sections_list = sectioning_structure($document).

‘untranslated_def_line_arg’

     _documentlanguage_ holds the ‘@documentlanguage’ value.  If there
     is a translation context, it should be in _translation_context_.

3.7 Texinfo::Parser SEE ALSO
============================

Texinfo manual (https://www.gnu.org/software/texinfo/manual/texinfo/).

3.8 Texinfo::Parser AUTHOR
==========================

Patrice Dumas, <pertusus@free.fr>

3.9 Texinfo::Parser 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.

4 Texinfo::Document
*******************

4.1 Texinfo::Document NAME
==========================

Texinfo::Document - Texinfo document tree and information

4.2 Texinfo::Document SYNOPSIS
==============================

  use Texinfo::Parser;

  my $parser = Texinfo::Parser::parser();
  my $document = $parser->parse_texi_file("somefile.texi");

  my $indices_information = $document->indices_information();
  my $float_types_arrays = $document->floats_information();
  my $internal_references_array
    = $parser->internal_references_information();

  # $identifier_target is an hash reference on normalized
  # node/float/anchor names.
  my $identifier_target = $document->labels_information();

  # A hash reference, keys are @-command names, value is an
  # array reference holding all the corresponding @-commands.
  # Also contains dircategory and direntry list.
  my $global_commands_information
                 = $document->global_commands_information();

  # a hash reference on document information (encodings,
  # input file name, for example).
  my $global_information = $document->global_information();

4.3 Texinfo::Document NOTES
===========================

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.

4.4 Texinfo::Document DESCRIPTION
=================================

This module is used to represent parsed Texinfo documents, with the
Texinfo tree and associated information.  In general a document is
obtained from a Texinfo parser call, there is no need to setup the
document.

4.5 Texinfo::Document METHODS
=============================

4.5.1 Getting document information
----------------------------------

The main purpose of Texinfo::Document methods is to retrieve information
on a Texinfo document.

   The Texinfo tree obtained by parsing a Texinfo document is available
through ‘tree’:

$tree = tree($document, $handler_only)

     The _$tree_ is a hash reference.  It is described in
     ^?TexinfoParser TEXINFO TREE^?::.

     If _$handler_only_ is set and XS extensions are used, the returned
     tree holds a reference to the C Texinfo tree data only, but no
     actual Perl Texinfo tree.  This avoids building the Perl tree if
     all the functions called with the tree as argument have XS
     interfaces and directly use the C data and do not use the Perl
     tree.

   Some global information is available through ‘global_information’:

$info = global_information($document)

     The _$info_ returned is a hash reference.  The possible keys are

     included_files

          An array of included file paths as they appear in the
          document.  Binary strings.  From both ‘@include’ and
          ‘@verbatiminclude’.

     input_encoding_name

          ‘input_encoding_name’ string is the encoding name used for the
          Texinfo code.

     input_file_name

     input_directory

          The name of the main Texinfo input file and the associated
          directory.  Binary strings.  In ‘texi2any’, they should come
          from the command line (and can be decoded with the encoding in
          the customization variable ‘COMMAND_LINE_ENCODING’).

   Some command lists are available, such that it is possible to go
through the corresponding tree elements without walking the tree.  They
are available through ‘global_commands_information’:

$commands = global_commands_information($document)

     _$commands_ is an hash reference.  The keys are @-command names.
     The associated values are array references containing all the
     corresponding tree elements.

     The following list of commands is also available as a key:

     dircategory_direntry

          An array of successive ‘@dircategory’ and ‘@direntry’ as they
          appear in the document.

   All the @-commands that have an associated label (so can be the
target of cross references) -- ‘@node’, ‘@anchor’ and ‘@float’ with
label -- have a normalized name associated, constructed as described in
the _HTML Xref_ node in the Texinfo documentation.  Those normalized
labels and the association with @-commands is available through
‘labels_information’:

$identifier_target = labels_information($document)

     _$identifier_target_ is a hash reference whose keys are normalized
     labels, and the associated value is the corresponding @-command.

$labels_list = labels_list ($document)

     _$labels_list_ is a list of Texinfo tree command elements that
     could be the target of cross references.

   Information on ‘@float’ grouped by type of floats, each type
corresponding to potential ‘@listoffloats’ is available through
‘floats_information’.

$float_types = floats_information($document)

     _$float_types_ is a hash reference whose keys are normalized float
     types (the first float argument, or the ‘@listoffloats’ argument).
     The normalization is the same as for the first step of node names
     normalization.  The value is the list of float tree elements
     appearing in the texinfo document.

   Internal references, nodes and section lists may also be available.

$internal_references_array = internal_references_information($document)

     The function returns an array reference of cross-reference commands
     referring to the same document with @-commands that refer to node,
     anchors or floats.

$nodes_list = nodes_list($document)

     Returns an array reference containing the document nodes.  In
     general set to the nodes list returned by
     ^?TexinfoStructuring nodes_tree^?: Texinfo::Structuring $nodes_list =
     nodes_tree($document), by a call to
     register_document_nodes_list,
     $nodes_list)^?.

$sections_list = sections_list($document)

     Returns an array reference containing the document sections.  In
     general set to the sections list returned by
     ^?TexinfoStructuring sectioning_structure^?: Texinfo::Structuring
     $sections_list = sectioning_structure($document), by a call to
     register_document_sections_list,
     $sections_list)^?.

   Information about defined indices, indices merging and index entries
is available through ‘indices_information’.

$indices_information = $document->indices_information()

     _$indices_information_ is a hash reference.  The keys are

     in_code

          1 if the index entries should be formatted as code, 0 in the
          opposite case.

     name

          The index name.

     prefix

          An array reference of prefix associated to the index.

     merged_in

          In case the index is merged to another index, this key holds
          the name of the index the index is merged into.  It takes into
          account indirectly merged indices.

     index_entries

          An array reference containing index entry structures for index
          entries associated with the index.  The index entry could be
          associated to @-commands like ‘@cindex’, or ‘@item’ in
          ‘@vtable’, or definition commands entries like ‘@deffn’.

          The keys of the index entry structures are

          index_name

               The index name associated to the command.  Not modified
               if the corresponding index is merged in another index
               (with ‘@synindex’, for example).

          entry_element

               The element in the parsed tree associated with the
               @-command holding the index entry.

          entry_number

               The number of the index entry.

     The following shows the references corresponding to the default
     indexes _cp_ and _fn_, the _fn_ index having its entries formatted
     as code and the indices corresponding to the following texinfo

       @defindex some
       @defcodeindex code

       $index_names = {'cp' => {'name' => 'cp', 'in_code' => 0, },
                       'fn' => {'name' => 'fn', 'in_code' => 1, },
                       'some' => {'in_code' => 0},
                       'code' => {'in_code' => 1}};

     If ‘name’ is not set, it is set to the index name.

4.5.2 Merging and sorting indices
---------------------------------

Merged and sorted document indices are also available.  Parsed indices
are not merged nor sorted, see ^?TexinfoIndices^?: Texinfo::Indices
NAME. functions are called to merge or sort the indices the first time
the following methods are called.  The results are afterwards associated
to the document and simply returned.

   In general, those methods should not be called directly, instead
^?TexinfoConvert::Converter Index sorting^?:: Converter methods
should be used, which already call the following functions.

$merged_indices = $document->merged_indices()

     Merge indices if needed and return merged indices.  The
     _$merged_indices_ returned is a hash reference whose keys are the
     index names and values arrays of index entry structures described
     in index_entries.

     ^?‘TexinfoIndices::merge_indices’^?: Texinfo::Indices
     $merged_indices = merge_indices($indices_information). is used to
     merge the indices.

     In general, it is not useful to call this function directly, as it
     is already called by index sorting functions.

$sorted_indices = $document->sorted_indices_by_index($customization_information, $use_unicode_collation, $locale_lang)

$sorted_indices = $document->sorted_indices_by_letter($customization_information, $use_unicode_collation, $locale_lang)

     ‘sorted_indices_by_letter’ returns the indices sorted by index and
     letter, while ‘sorted_indices_by_index’ returns the indices with
     all entries of an index together.

     By default, indices are sorted according to the _Unicode Collation
     Algorithm_ defined in the Unicode Technical Standard #10
     (http://www.unicode.org/reports/tr10/), without language-specific
     collation tailoring.  If _$use_unicode_collation_ is set to 0, the
     sorting will not use the _Unicode Collation Algorithm_ and simply
     sort according to the codepoints.  If _$locale_lang_ is set, the
     language is used for linguistic tailoring of the sorting, if
     possible.

     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.  The letter is a character string
     suitable for sorting letters, but is not necessarily the best to
     use for output.

     When simply sorting, the array of the sorted index entries is
     associated with the index name.

     The optional _$customization_information_ argument is used for
     error reporting, both to find the ^?TexinfoReport^?:
     Texinfo::Report NAME. object to use for error reporting and Texinfo
     customization variables information.  In general, it should be a
     converter (see ^?TexinfoConvert::Converter Getting and setting
     customization variables^?::) or a document ^?TexinfoDocument
     Getting customization options values registered in document^?::).

     ^?‘TexinfoIndices::sort_indices_by_index’^?: ^?Texinfo::Indices
     $index_entries_sorted = sort_indices_by_index($document,
     $registrar, $customization_information, $use_unicode_collation,
     $locale_lang)^?. and
     ^?‘TexinfoIndices::sort_indices_by_letter’^?: ^?Texinfo::Indices
     $index_entries_sorted = sort_indices_by_letter($document,
     $registrar, $customization_information, $use_unicode_collation,
     $locale_lang)^?. are used to sort the indices, if needed.

     In general, those methods should not be called directly, instead

     ^?‘TexinfoConvert::Converter::get_converter_indices_sorted_by_index’^?:
     Texinfo::Convert::Converter $sorted_indices =
     $converter->get_converter_indices_sorted_by_index(). and
     ^?‘TexinfoConvert::Converter::get_converter_indices_sorted_by_letter’^?:
     Texinfo::Convert::Converter $sorted_indices =
     $converter->get_converter_indices_sorted_by_letter(). should be
     used.  The ‘Texinfo::Convert::Converter’ methods call
     ‘sorted_indices_by_index’ and ‘sorted_indices_by_letter’.

4.5.3 Getting errors and error registering object
-------------------------------------------------

A document has a ^?TexinfoReport^?: Texinfo::Report NAME. objet
associated, that is used to register errors and warning messages in.  To
get the errors registered in the document, the ‘errors’ method should be
called.  It is also possible to get the document associated
‘Texinfo::Report’ objet by calling the ‘registrar’ accessor method.

$registrar = registrar($document)

     Returns the ‘Texinfo::Report’ object associated with the
     _$document_.

     In general, this is not needed as most functions use the document
     associated ‘Texinfo::Report’ object automatically.  However, for
     some functions a ‘Texinfo::Report’ object is passed in argument,
     being able to get the document registrar object is interesting in
     those cases.

($error warnings list, $error count) = errors($document)

     This function returns as _$error_count_ the count of errors since
     setting up the _$document_ (or calling the function).  The returned
     _$error_warnings_list_ is an array of hash references one for each
     error, warning or error line continuation.  The format of these
     hash references is described in ^?‘TexinfoReport::errors’^?:
     ^?Texinfo::Report ($error_warnings_list, $error_count) =
     errors($registrar)^?.

4.5.4 Getting customization options values registered in document
-----------------------------------------------------------------

By default, customization information is registered in a document object
just after parsing the Texinfo code.  Structuring and tree
transformation methods then get customization variables values from the
document object they have in argument.  The customization variables set
by default may be a subset selected to be useful for structuring and
tree transformation codes.

   To retrieve Texinfo customization variables you can call ‘get_conf’:

$value = $document->get_conf($variable_name)

     Returns the value of the Texinfo customization variable
     _$variable_name_ (possibly ‘undef’), if the variable value was
     registered in the document, or ‘undef’.

4.5.5 Registering document and information in document
------------------------------------------------------

The setup of a document is described next, it should only be used in
parsers codes.

$document = Texinfo::Document::register($tree, $global_information, $indices_information, $floats_information, $internal_references_information, $global_commands_information, $identifier_target, $labels_list, $parser_registrar)

     Setup a document.  There is no reason to call this method out of
     parsers, as it is already done by the Texinfo parsers.  The
     arguments are gathered during parsing and correspond to information
     returned by the other methods.

   Further information can be registered in the document.

register_document_nodes_list ($document, $nodes_list)

     Register the _$nodes_list_ array reference as _$document_ nodes
     list.  This method should be called after the processing of
     document structure.

register_document_options ($document, $options)

     The _$options_ hash reference holds options for the document.
     These options should be Texinfo customization options.  Usually,
     the options registered in the document contain those useful for
     structuring and tree transformation getting place between Texinfo
     code parsing and conversion to output formats.  Indeed, document
     customization options are mainly accessed by structuring and tree
     transformation methods (by calling ‘get_conf’).
     The options should in general be registered before the calls to
     ‘get_conf’.

register_document_sections_list ($document, $sections_list)

     Register the _$sections_list_ array reference as _$document_
     sections list.  This method should be called after the processing
     of document structure.

set_document_global_info($document, $key, $value)

     Add _$value_ _$key_ global information to _$document_.  This method
     should not be generally useful, as document global information is
     already set by the Texinfo parser.  The information set should be
     available through the next calls to global_information.
     The
     method should in general be called before the calls to
     ‘global_information’.

4.5.6 Methods for Perl and C code interactions
----------------------------------------------

The parsing of Texinfo code, structuring and transformations of the tree
called through Texinfo Perl modules may be done by pure Perl modules or
by C code called through XS interfaces.  In general, it makes no
difference whether pure Perl or C code is used.  When the document and
tree are modified by C code, the Perl structures are automatically
rebuilt when calling the accessors described previously.  In some cases,
however, specific functions need to be called to pass information from C
to Perl or perform actions related to C data.

   The methods can always be called on pure Perl modules even if they do
nothing.  Therefore it is, in general, better to call them assuming that
modules setting up C data were called, even when it is not the case.

   First, ‘document_descriptor’ can be called to get the document
identifier document used by C code to retrieve the document data in C.
In general this identifier is directly and transparently taken from the
document, but may need to be set on other objects in rare cases.

$document_descriptor = $document->document_descriptor()

     Returns the document descriptor if the document is available as C
     data, 0 or ‘undef’ if not.

   When the tree is directly accessed in Perl (not through a document)
but is modified by C code, for instance called through
^?TexinfoCommon^?: Texinfo::Common NAME. or
^?TexinfoTransformations^?: Texinfo::Transformations NAME. methods, the
Perl structures need to be rebuilt from the C data with ‘rebuild_tree’:

$rebuilt_tree = rebuild_tree($tree, $no_store)

     Return a _$rebuilt_tree_, rebuilt from C data if needed.  If there
     is no C data, the tree is returned as is.  The tree rebuilt is
     based on the Texinfo parsed document associated to the Texinfo tree
     _$tree_.

     If the optional _$no_store_ argument is set, remove the C data.

   Note that the Perl tree associated to a document is rebuilt from C
data when calling ‘$document->tree()’.  Similarly, the tree is rebuilt
when calling other accessors that depend on the document tree.
Therefore ‘rebuild_tree’ should only be called when there is no document
associated to a tree and ‘$document->tree()’ cannot be called to rebuild
the tree.

   Some methods allow to release the memory held by C data associated to
a Texinfo parsed document:

remove_document($document)

     Remove the C data corresponding to _$document_.

4.6 Texinfo::Document SEE ALSO
==============================

^?TexinfoParser^?: Texinfo::Parser NAME. ^?TexinfoStructuring^?:
Texinfo::Structuring NAME.

4.7 Texinfo::Document AUTHOR
============================

Patrice Dumas, <pertusus@free.fr>

4.8 Texinfo::Document 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.

5 Texinfo::ManipulateTree
*************************

5.1 Texinfo::ManipulateTree NAME
================================

Texinfo::ManipulateTree - Texinfo modules common tree manipulation
functions

5.2 Texinfo::ManipulateTree SYNOPSIS
====================================

  use Texinfo::ManipulateTree;

5.3 Texinfo::ManipulateTree NOTES
=================================

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.

5.4 Texinfo::ManipulateTree DESCRIPTION
=======================================

‘Texinfo::ManipulateTree’ contains methods for copying and modifying the
Texinfo tree used for default conversion to output formats.

   For optional tree transformation, see ^?TexinfoTransformations^?:
Texinfo::Transformations NAME.

5.5 Texinfo::ManipulateTree METHODS
===================================

The Texinfo tree and Texinfo tree elements used in argument of some
functions are documented in ^?TexinfoParser TEXINFO TREE^?::.  When
customization information is needed, an object that defines ‘get_conf’
is expected, normally a ^?TexinfoDocument Getting customization
options values registered in document^?:: object.

move_index_entries_after_items_in_tree($tree)

     In ‘@enumerate’ and ‘@itemize’ from the tree, move index entries
     appearing just before ‘@item’ after the ‘@item’.  Comment lines
     between index entries are moved too.

protect_colon_in_tree($tree)

protect_node_after_label_in_tree($tree)

     Protect colon with ‘protect_colon_in_tree’ and characters that are
     special in node names after a label in menu entries (tab dot and
     comma) with ‘protect_node_after_label_in_tree’.  The protection is
     achieved by putting protected characters in ‘@asis{}’.

protect_comma_in_tree($tree)

     Protect comma characters, replacing ‘,’ with @comma{} in tree.

protect_first_parenthesis($element)

     Modify _$element_ contents by protecting the first parenthesis.  If
     _$element_ is undef a fatal error with a backtrace will be emitted.

relate_index_entries_to_table_items_in_tree($document)

     In tables, relate index entries preceding and following an entry
     with said item.  Reference one of them in the entry's
     ‘entry_associated_element’.

5.6 Texinfo::ManipulateTree SEE ALSO
====================================

^?TexinfoDocument^?: Texinfo::Document NAME, see
^?TexinfoStructuring^?: Texinfo::Structuring NAME, see
^?TexinfoTransformations^?: Texinfo::Transformations NAME.

5.7 Texinfo::ManipulateTree AUTHOR
==================================

Patrice Dumas, <pertusus@free.fr>

5.8 Texinfo::ManipulateTree 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.

6 Texinfo::Structuring
**********************

6.1 Texinfo::Structuring NAME
=============================

Texinfo::Structuring - information on Texinfo::Document document
structure

6.2 Texinfo::Structuring SYNOPSIS
=================================

  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());

6.3 Texinfo::Structuring NOTES
==============================

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.

6.4 Texinfo::Structuring DESCRIPTION
====================================

‘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’.

6.5 Texinfo::Structuring METHODS
================================

No method is exported in the default case.

   Most methods use the ^?TexinfoReport^?: Texinfo::Report NAME.
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 (see
^?TexinfoConvert::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 ^?TexinfoDocument^?: Texinfo::Document NAME.

associate_internal_references($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_nodes_are_referenced($document)

     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_node_tree_with_menus($document)

     Complete nodes directions with menu directions.  Check consistency
     of menus, sectionning and nodes direction structures.

@children_nodes = get_node_node_childs_from_sectioning($node)

     _$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.

new_block_command($element, $command_name)

     Complete _$element_ by adding the _$command_name_, the command line
     argument and ‘@end’ to turn the element to a proper block command.

$new_menu = new_complete_node_menu($node, $customization_information, $use_sections)

     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.

$detailmenu = new_detailmenu($customization_information, $registrar, $identifier_target, $menus)

     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 ^?TexinfoReport^?:
     Texinfo::Report NAME. 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
     (see ^?TexinfoConvert::Converter Registering error and warning
     messages^?::).

$entry = new_node_menu_entry($node, $use_sections)

     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.

$nodes_list = nodes_tree($document)

     Goes through nodes in _$document_ tree and set directions.  Returns
     the list of nodes.

     This functions sets, in the ‘extra’ node element hash:

     node_directions

          Hash reference with _up_, _next_ and _prev_ keys associated to
          elements corresponding to node line directions.

number_floats($float_information)

     Number the floats as described in the Texinfo manual.  Sets the
     _float_number_ key in the ‘extra’ hash of the float tree elements.

$command_name = section_level_adjusted_command_name($element)

     Return the sectioning command name corresponding to the sectioning
     element _$element_, adjusted in order to take into account raised
     and lowered sections, when needed.

$sections_list = sectioning_structure($document)

     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:

     section_level

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

     section_number

          The sectioning element number.

     section_childs

          An array holding sectioning elements children of the element.

     section_directions

          Hash reference with _up_, _next_ and _prev_ keys associated to
          elements corresponding to sectioning structure directions.

     toplevel_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_.

set_menus_node_directions($document);

     Goes through menu and set directions.

     This functions sets, in the ‘extra’ node element hash reference:

     menu_directions

          Hash reference with _up_, _next_ and _prev_ keys associated to
          elements corresponding to menu directions.

warn_non_empty_parts($document)

     Register a warning in for each ‘@part’ in global commands
     information of _$document_ that is not empty.

6.6 Texinfo::Structuring SEE ALSO
=================================

Texinfo manual (http://www.gnu.org/s/texinfo/manual/texinfo/), see
^?TexinfoDocument^?: Texinfo::Document NAME.

6.7 Texinfo::Structuring AUTHOR
===============================

Patrice Dumas, <pertusus@free.fr>

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

7 Texinfo::Report
*****************

7.1 Texinfo::Report NAME
========================

Texinfo::Report - Error storing for Texinfo modules

7.2 Texinfo::Report SYNOPSIS
============================

  use Texinfo::Report;

  my $registrar = Texinfo::Report::new();

  if ($warning_happened) {
    $registrar->line_warn($converter, sprintf(__("\@%s is wrongly used"),
                       $current->{'cmdname'}), $current->{'source_info'});
  }

  my ($errors, $errors_count) = $registrar->errors();
  foreach my $error_message (@$errors) {
    warn $error_message->{'error_line'};
  }

  $registrar->clear();

7.3 Texinfo::Report NOTES
=========================

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.

7.4 Texinfo::Report DESCRIPTION
===============================

The ‘Texinfo::Report’ module helps with error handling.  Errors and
warnings can be setup, stored and retrieved later on.  This module is
used by the Texinfo modules ^?TexinfoParser^?: Texinfo::Parser NAME.
and ^?TexinfoConvert::Converter^?: Texinfo::Convert::Converter NAME.

7.5 Texinfo::Report METHODS
===========================

No method is exported in the default case.

   The ‘new’ method initializes a ‘Texinfo::Report’ object.  The errors
collected are available through the ‘errors’ method, the other methods
allow registering errors and warnings.

my $registrar = Texinfo::Report::new()

     Return an initialized ‘Texinfo::Report’ object.

($error_warnings_list, $error_count) = errors($registrar)

     This function returns as _$error_count_ the count of errors since
     calling ‘new’.  The _$error_warnings_list_ is an array of hash
     references one for each error, warning or error line continuation.
     Each of these has the following keys:

     continuation

          If set, the line is a continuation line of a message.

     error_line

          The text of the error formatted with the macro name, as
          needed.

     file_name

          The file name where the error or warning occurs.

     line_nr

          The line number of the error or warning.

     macro

          The user macro name that is expanded at the location of the
          error or warning.

     text

          The text of the error.

     type

          May be ‘warning’, or ‘error’.

$registrar->clear ()

     Clear the previously registered messages.

$registrar->add_formatted_message ($msg)

     Register the _$msg_ hash reference corresponding to an error,
     warning or error line continuation.  The _$msg_ hash reference
     should correspond to the structure returned by ‘errors’.

$registrar->line_warn($text, $error_location_info, $continuation, $debug, $silent)

$registrar->line_error($text, $error_location_info, $continuation, $debug, $silent)

     Register a warning or an error.  The _$text_ is the text of the
     error or warning.  The mandatory _$error_location_info_ holds the
     information on the error or warning location.  The
     _$error_location_info_ reference on hash may be obtained from
     Texinfo elements _source_info_ keys.  It may also be setup to point
     to a file name, using the ‘file_name’ key and to a line number,
     using the ‘line_nr’ key.  The ‘file_name’ key value should be a
     binary string.

     The _$continuation_ optional arguments, if true, conveys that the
     line is a continuation line of a message.

     The _$debug_ optional integer arguments sets the debug level.

     The _$silent_ optional arguments, if true, suppresses the output of
     a message that is output immediatly if debugging is set.

     The _source_info_ key of Texinfo tree elements is described in more
     details in ^?TexinfoParser source_info^?::.

$registrar->document_warn($text, $program_name, $continuation)

$registrar->document_error($text, $program_name, $continuation)

     Register a document-wide error or warning.  _$text_ is the error or
     warning message.  The _$program_name_ is prepended to the message,
     if defined.  The _$continuation_ optional arguments, if true,
     conveys that the line is a continuation line of a message.

7.6 Texinfo::Report AUTHOR
==========================

Patrice Dumas, <pertusus@free.fr>

7.7 Texinfo::Report 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.

8 Texinfo::Translations
***********************

8.1 Texinfo::Translations NAME
==============================

Texinfo::Translations - Translations of output documents strings for
Texinfo modules

8.2 Texinfo::Translations SYNOPSIS
==================================

  @ISA = qw(Texinfo::Translations);

  Texinfo::Translations::configure('LocaleData');

  my $tree_translated
    = Texinfo::Translations::gdt('See {reference} in @cite{{book}}',
                           $converter->get_conf('documentlanguage'),
                          {'reference' => $tree_reference,
                           'book'  => {'text' => $book_name}});

8.3 Texinfo::Translations NOTES
===============================

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.

8.4 Texinfo::Translations DESCRIPTION
=====================================

The ‘Texinfo::Translations’ module helps with translations in output
documents.

   Translation of error messages is not described here, some elements
are in ^?TexinfoCommon ‘__’ and ‘__p’^?: Texinfo::Common
$translated_string = __($msgid).

8.5 Texinfo::Translations METHODS
=================================

No method is exported.

   The ‘configure’ method sets the translation files base directory.  If
not called, system defaults are used.

configure($localesdir, $strings_textdomain)

     _$localesdir_ is the directory where translation files are found.
     The directory structure and files format should follow the
     conventions expected for gettext based internationalization
     (https://www.gnu.org/software/gettext/manual/html_node/Locating-Catalogs.html).
     The _$strings_textdomain_ is optional, if set, it determines the
     translation domain.

   The ‘gdt’ and ‘pgdt’ methods are used to translate strings to be
output in converted documents, and return a Texinfo tree.  The
‘gdt_string’ is similar but returns a simple string, for already
converted strings.

$tree = gdt($string, $lang, $replaced_substrings, $translation_context, $debug_level, $object, $translate_string_method)

$string = gdt_string($string, $lang, $replaced_substrings, $translation_context, $object, $translate_string_method)

     The _$string_ is a string to be translated.  With ‘gdt’ the
     function returns a Texinfo tree, as the string is interpreted as
     Texinfo code after translation.  With ‘gdt_string’ a string is
     returned.

     _$lang_ is the language used for the translation.

     _$replaced_substrings_ is an optional hash reference specifying
     some substitution to be done after the translation.  The key of the
     _$replaced_substrings_ hash reference identifies what is to be
     substituted.  In the string to be translated word in brace matching
     keys of _$replaced_substrings_ are replaced.  For ‘gdt’, the value
     is a Texinfo tree element that is substituted in the resulting
     Texinfo tree.  For ‘gdt_string’, the value is a string that is
     replaced in the resulting string.

     _$debug_level_ is an optional debugging level supplied to ‘gdt’,
     similar to the ‘DEBUG’ customization variable.  If set, the debug
     level minus one is passed to the Texinfo string parser called in
     ‘gdt’.

     The _$translation_context_ is optional.  If not ‘undef’ this is a
     translation context string for _$string_.  It is the first argument
     of ‘pgettext’ in the C API of Gettext.

     For example, in the following call, the string ‘See {reference} in
     @cite{{book}}’ is translated, then parsed as a Texinfo string, with
     _{reference}_ substituted by _$tree_reference_ in the resulting
     tree, and _{book}_ replaced by the associated Texinfo tree text
     element:

       $tree = gdt('See {reference} in @cite{{book}}', "ca",
                   {'reference' => $tree_reference,
                    'book'  => {'text' => $book_name}});

     By default, ‘gdt’ and ‘gdt_string’ call ‘translate_string’ to use a
     gettext-like infrastructure to retrieve the translated strings,
     using the _texinfo_document_ domain.  You can change the method
     used to retrieve the translated strings by providing a
     _$translate_string_method_ argument.  If not undef it should be a
     reference on a function that is called instead of
     ‘translate_string’.  The _$object_ is passed as first argument of
     the _$translate_string_method_, the other arguments are the same as
     ‘translate_string’,
     $lang, $translation_context)^?.
     arguments.

$tree = pgdt($translation_context, $string, $lang, $replaced_substrings, $debug_level)

     Same to ‘gdt’ except that the _$translation_context_ is not
     optional.  Calls ‘gdt’.  This function is useful to mark strings
     with a translation context for translation.  This function is
     similar to pgettext in the Gettext C API.

   By default, in ‘gdt’, ‘gdt_string’ and ‘pgdt’ a string is translated
with ‘translate_string’.

$translated_string = translate_string($string, $lang, $translation_context)

     The _$string_ is a string to be translated.  _$lang_ is the
     language used for the translation.  The _$translation_context_ is
     optional.  If not ‘undef’ this is a translation context string for
     _$string_.  It is the first argument of ‘pgettext’ in the C API of
     Gettext.

     ‘translate_string’ uses a gettext-like infrastructure to retrieve
     the translated strings, using the _texinfo_document_ domain.

8.6 Texinfo::Translations SEE ALSO
==================================

GNU gettext utilities manual
(https://www.gnu.org/software/gettext/manual/).

8.7 Texinfo::Translations AUTHOR
================================

Patrice Dumas, <pertusus@free.fr>

8.8 Texinfo::Translations 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.

9 Texinfo::Transformations
**************************

9.1 Texinfo::Transformations NAME
=================================

Texinfo::Transformations - transformations of Texinfo tree

9.2 Texinfo::Transformations NOTES
==================================

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.

9.3 Texinfo::Transformations DESCRIPTION
========================================

Includes miscellaneous methods such as as
‘insert_nodes_for_sectioning_commands’ that adds nodes for sectioning
commands without nodes and ‘complete_tree_nodes_menus’ and
‘complete_tree_nodes_missing_menu’ that completes the node menus based
on the sectioning tree.

   Methods for copying and modifying the Texinfo tree used for default
conversion to output formats are in ^?TexinfoManipulateTree^?:
Texinfo::ManipulateTree NAME.

9.4 Texinfo::Transformations METHODS
====================================

No method is exported in the default case.

complete_tree_nodes_menus($tree, $add_section_names_in_entries)

     Add menu entries or whole menus for nodes associated with sections,
     based on the sectioning tree.  If the optional
     ‘$add_section_names_in_entries’ argument is set, a menu entry name
     is added using the section name.  This function should be called
     after sectioning_structure.

complete_tree_nodes_missing_menu($document, $use_section_names_in_entries)

     Add whole menus for nodes associated with sections and without
     menu, based on the _$document_ sectioning tree.  If the optional
     _$add_section_names_in_entries_ argument is set, a menu entry name
     is added using the section name.  This function should be called
     after sectioning_structure.

fill_gaps_in_sectioning($tree, $commands_heading_tree)

     This function adds empty ‘@unnumbered’ and similar commands in a
     tree to fill gaps in sectioning.  This may be used, for example,
     when converting from a format that can handle gaps in sectioning.
     _$tree_ is the tree root, which is modified by adding the new
     sectioning commands.

     In the default case, the added sectioning commands headings are
     empty.  It is possible to use instead the _$commands_heading_tree_
     Texinfo tree element.

     If the sectioning commands are lowered or raised (with
     ‘@raisesections’, ‘@lowersection’) the tree may be modified with
     ‘@raisesections’ or ‘@lowersection’ added to some tree elements.

insert_nodes_for_sectioning_commands($document)

     Insert nodes for sectioning commands without node in ‘$document’
     tree.

menu_to_simple_menu($menu)

set_menus_to_simple_menu($nodes_list)

     ‘menu_to_simple_menu’ transforms the tree of a menu tree element.
     ‘set_menus_to_simple_menu’ calls ‘menu_to_simple_menu’ for all the
     menus of the nodes in ‘$nodes_list’.

     A simple menu has no _menu_comment_, _menu_entry_ or
     _menu_entry_description_ container anymore, their content are
     merged directly in the menu in _preformatted_ container.

     Note that this kind of tree is not supported by other codes, so
     this transformation should be avoided unless one knows exactly what
     to expect.

protect_hashchar_at_line_beginning($tree, $registrar, $customization_information)

     Protect hash (#) character at the beginning of line such that they
     would not be considered as lines to be processed by the CPP
     processor.  The _$registrar_ and _$customization_information_
     arguments are optional.  If defined, the _$registrar_ argument
     should be a ^?TexinfoReport^?: Texinfo::Report NAME. object in
     which the errors and warnings encountered while parsing are
     registered.  If defined, _$customization_information_ should give
     access to customization through ‘get_conf’.  If both _$registrar_
     and _$customization_information_ are defined they are used for
     error reporting in case an hash character could not be protected
     because it appeared in a raw formatted environment (‘@tex’,
     ‘@html’...).

$modified_tree = reference_to_arg_in_tree($tree, $document)

     Modify _$tree_ by converting reference @-commands to simple text
     using one of the arguments.  This transformation can be used, for
     example, to remove reference @-command from constructed node names
     trees, as node names cannot contain reference @-command while there
     could be some in the tree used in input for the node name tree.
     The _$document_ argument is optional.  If given, the converted
     reference @-command is removed from the _$document_ internal
     references list.

     A _$modified_tree_ is not systematically returned, if the _$tree_
     in argument is not replaced, undef may also be returned.

regenerate_master_menu($document, $use_sections)

     Regenerate the _$document_ Top node master menu, replacing the
     first detailmenu in Top node menus or appending at the end of the
     Top node menu.

     _$use_sections_ is an optional argument.  If set, sections
     associated with nodes are used as labels in the generated master
     menu.

9.5 Texinfo::Transformations SEE ALSO
=====================================

Texinfo manual (http://www.gnu.org/s/texinfo/manual/texinfo/), see
^?TexinfoParser^?: Texinfo::Parser NAME, see ^?TexinfoManipulateTree^?:
Texinfo::ManipulateTree NAME.

9.6 Texinfo::Transformations AUTHOR
===================================

Patrice Dumas, <pertusus@free.fr>

9.7 Texinfo::Transformations 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.

10 Texinfo::Indices
*******************

10.1 Texinfo::Indices NAME
==========================

Texinfo::Indices - merging and sorting indices from Texinfo

10.2 Texinfo::Indices SYNOPSIS
==============================

  use Texinfo::Indices;

  # $document is a parsed Texinfo::Document document.
  my $indices_information = $document->indices_information();
  my $merged_index_entries
     = Texinfo::Indices::merge_indices($indices_information);

  # $registrar is a Texinfo::Report object.  $config is an object
  # implementing the get_conf() method.
  my $index_entries_sorted;
  if ($sort_by_letter) {
    $index_entries_sorted
      = Texinfo::Indices::sort_indices_by_letter($document, $registrar,
                                                   $config);
  } else {
    $index_entries_sorted
      = Texinfo::Indices::sort_indices_by_index($document, $registrar,
                                                  $config);
  }

10.3 Texinfo::Indices NOTES
===========================

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.

10.4 Texinfo::Indices DESCRIPTION
=================================

‘merge_indices’ may be used to merge indices.  Document indices may be
sorted with ‘sort_indices_by_index’ or ‘sort_indices_by_letter’.  Other
functions deal with formatting of index entries as text or getting
information on index entry.

   Note that, in general, the functions used to merge or sort indices
should not be called directly, corresponding functions in
^?TexinfoDocument^?: Texinfo::Document NAME. already call the functions in
this module, and, in addition, cache the result with the document.
Furthermore, it should be even better to call converter functions, which
call document functions.

10.5 Texinfo::Indices METHODS
=============================

No method is exported.

$sort_string = index_entry_element_sort_string($document_info, $main_entry, $index_entry_element, $options, $prefer_reference_element)

     Return a string suitable as a sort string, for index entries.
     _$document_info_ is used by C code to retrieve the document data,
     using the ‘document_descriptor’ key.  _$document_info_ can be a
     converter based on ^?TexinfoConvert::Converter^?:
     Texinfo::Convert::Converter NAME, a ^?TexinfoDocument^?:
     Texinfo::Document NAME. document, otherwise ‘document_descriptor’
     need, in general, to be set up explicitely.

     The tree element index entry processed is _$index_entry_element_,
     and can be a ‘@subentry’.  _$main_entry_ is the main index entry
     that can be used to gather information.

     The _$options_ are options used for Texinfo to text conversion for
     the generation of the sort string.  If the sort string is supposed
     to be output, the _$options_ are typically obtained from
     setup_index_entry_keys_formatting.

     If _$prefer_reference_element_ is set, prefer an untranslated
     element for the formatting as sort string.

($text, $command) = index_entry_first_letter_text_or_command($index_entry)

     Return the _$index_entry_ leading text _$text_ or textual command
     Texinfo tree hash reference _$command_.  Here textual commands
     means accent commands, brace commands without arguments used for
     character and glyph insertion and ‘@U’.

     This method can in particular be used to format the leading letter
     of an index entry using _$command_ instead of the sort string set
     by ‘sort_indices_by_letter’.

$merged_indices = merge_indices($indices_information)

     Returns a structure holding all the index entries by index name
     with all the entries of merged indices merged with those of the
     indice merged into.  The _$indices_information_ argument should be
     an hash reference with indices information, it is described in
     details in ^?‘TexinfoDocument::indices_information’^?:
     Texinfo::Document $indices_information =
     $document->indices_information().

     The _$merged_indices_ returned is a hash reference whose keys are
     the index names and values arrays of index entry structures
     described in details in ^?TexinfoDocument index_entries^?::.

     In general, this method should not be called directly, instead
     ^?‘TexinfoDocument::merged_indices’^?: Texinfo::Document
     $merged_indices = $document->merged_indices(). should be called on
     a document, which calls ‘merge_indices’ if needed and associate the
     merged indices to the document.

$option = setup_index_entry_keys_formatting($customization_information)

     Return options relevant for index keys sorting for conversion of
     Texinfo to text to be output.

$index_entries_sorted = sort_indices_by_index($document, $registrar, $customization_information, $use_unicode_collation, $locale_lang)

$index_entries_sorted = sort_indices_by_letter($document, $registrar, $customization_information, $use_unicode_collation, $locale_lang)

     ‘sort_indices_by_letter’ sorts by index and letter, while
     ‘sort_indices_by_index’ sort all entries of an index together.
     Indices are obtained from _$document_, and should have been merged
     previously, in general by using
     ^?‘TexinfoDocument::merged_indices’^?: Texinfo::Document
     $merged_indices = $document->merged_indices().  In both cases, a
     hash reference with index names as keys _$index_entries_sorted_ is
     returned.

     By default, indices are sorted according to the _Unicode Collation
     Algorithm_ defined in the Unicode Technical Standard #10
     (http://www.unicode.org/reports/tr10/), without language-specific
     collation tailoring.  If _$use_unicode_collation_ is set to 0, the
     sorting will not use the _Unicode Collation Algorithm_ and simply
     sort according to the codepoints.  If _$locale_lang_ is set, the
     language is used for linguistic tailoring of the sorting, if
     possible.

     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.  The letter is a character string
     suitable for sorting letters, but is not necessarily the best to
     use for output.

     When simply sorting, the array of the sorted index entries is
     associated with the index name.

     The _$registrar_ argument can be set to a ^?TexinfoReport^?:
     Texinfo::Report NAME. object.  Error reporting also requires
     Texinfo customization variables information, which means an object
     implementing the ‘get_conf’ method, a converter (see
     ^?TexinfoConvert::Converter Getting and setting customization
     variables^?::) or a document ^?TexinfoDocument Getting
     customization options values registered in document^?::) as
     _$customization_information_ argument.  If the _$registrar_
     argument is not set, the object used to get customization
     information is assumed to be a converter, and the error reporting
     uses converters error messages reporting functions (see
     ^?TexinfoConvert::Converter Registering error and warning
     messages^?::).

     In general, those methods should not be called directly, instead
     ^?‘TexinfoDocument::sorted_indices_by_index’^?:
     ^?Texinfo::Document $sorted_indices =
     $document->sorted_indices_by_index($customization_information,
     $use_unicode_collation, $locale_lang)^?. or
     ^?‘TexinfoDocument::sorted_indices_by_letter’^?: ^?Texinfo::Document
     $sorted_indices =
     $document->sorted_indices_by_letter($customization_information,
     $use_unicode_collation, $locale_lang)^?. should be called on a
     document.  The ‘Texinfo::Document’ functions call
     ‘sort_indices_by_index’ or ‘sort_indices_by_letter’ if needed and
     associate the sorted indices to the document.

10.6 Texinfo::Indices SEE ALSO
==============================

Texinfo manual (http://www.gnu.org/s/texinfo/manual/texinfo/), see
^?TexinfoDocument^?: Texinfo::Document NAME.

10.7 Texinfo::Indices AUTHOR
============================

Patrice Dumas, <pertusus@free.fr>

10.8 Texinfo::Indices 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.

11 Texinfo::OutputUnits
***********************

11.1 Texinfo::OutputUnits NAME
==============================

Texinfo::OutputUnits - setup and manage Texinfo document output units

11.2 Texinfo::OutputUnits SYNOPSIS
==================================

  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);

11.3 Texinfo::OutputUnits NOTES
===============================

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.

11.4 Texinfo::OutputUnits DESCRIPTION
=====================================

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 ^?‘TexinfoConvert::Converter::convert_output_unit’^?:
Texinfo::Convert::Converter $result =
$converter->convert_output_unit($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 ^?‘TexinfoConvert::Converter::output_tree’^?:
Texinfo::Convert::Converter $result =
$converter->output_tree($document).

   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.

11.5 Texinfo::OutputUnits METHODS
=================================

No method is exported in the default case.

11.5.1 Output units creation
----------------------------

Output units are hash references created with the following keys:

‘type’

     The type of the output unit.  Set to ‘unit’ for output units
     associated with nodes and sectioning commands.

‘unit_command’

     Main node or sectioning command associated with the output unit.

‘unit_contents’

     This 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_directions’

     Hash 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:

$output_units = split_by_node($document)

     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.

$output_units = split_by_section($document)

     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.

11.5.2 Grouping output units in pages
-------------------------------------

You can call ‘split_pages’ to group together output units:

split_pages($output_units, $split)

     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_:

     ‘chapter’

          The output units are grouped at chapter or other toplevel
          sectioning commands.

     ‘node’

          Each output unit is on its own.

     ‘section’

          The output units are grouped at sectioning commands below
          chapter.

     empty string

          No splitting, all the output units are together.

11.5.3 Setting output units directions
--------------------------------------

You can call the following methods to set output units directions:

units_directions($identifier_target, $output_units, $print_debug)

     The _$identifier_target_ argument associates identifiers with
     target elements and is generally obtained from a parsed document,
     see ^?‘TexinfoDocument::labels_information’^?: Texinfo::Document
     $identifier_target = labels_information($document).  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:

     This

          The output unit itself.

     Forward

          Unit next.

     Back

          Previous output unit.

     NodeForward

          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.

     NodeBack

          Preceding node output unit.

     NodeUp

     NodeNext

     NodePrev

          The up, next and previous node output unit.

     Up

     Next

     Prev

          The up, next and previous section output unit.

     FastBack

          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.

     FastForward

          The next top level output unit.

units_file_directions($output_units)

     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.

11.6 Texinfo::OutputUnits SEE ALSO
==================================

Texinfo manual (http://www.gnu.org/s/texinfo/manual/texinfo/), see
^?TexinfoDocument^?: Texinfo::Document NAME, see
^?TexinfoConvert::Converter^?: Texinfo::Convert::Converter NAME.

11.7 Texinfo::OutputUnits AUTHOR
================================

Patrice Dumas, <pertusus@free.fr>

11.8 Texinfo::OutputUnits 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.

12 Texinfo::Convert::Texinfo
****************************

12.1 Texinfo::Convert::Texinfo NAME
===================================

Texinfo::Convert::Texinfo - Convert a Texinfo tree to Texinfo code

12.2 Texinfo::Convert::Texinfo SYNOPSIS
=======================================

  use Texinfo::Convert::Texinfo qw(convert_to_texinfo);

  my $texinfo_text = convert_to_texinfo($tree);

12.3 Texinfo::Convert::Texinfo NOTES
====================================

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.

12.4 Texinfo::Convert::Texinfo DESCRIPTION
==========================================

‘Texinfo::Convert::Texinfo’ converts a Texinfo tree (described in
^?TexinfoParser^?: Texinfo::Parser NAME.) to Texinfo code.  If the Texinfo
tree results from parsing some Texinfo document, The converted Texinfo
code should be exactly the same as the initial document, except that
user defined @-macros and ‘@value’ are expanded, and some invalid code
is discarded.

12.5 Texinfo::Convert::Texinfo METHODS
======================================

$texinfo_text = convert_to_texinfo($tree)

     Converts the Texinfo tree _$tree_ to Texinfo code.

12.6 Texinfo::Convert::Texinfo AUTHOR
=====================================

Patrice Dumas, <pertusus@free.fr>

12.7 Texinfo::Convert::Texinfo 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.

13 Texinfo::Convert::Utils
**************************

13.1 Texinfo::Convert::Utils NAME
=================================

Texinfo::Convert::Utils - miscellaneous functions usable in all
converters

13.2 Texinfo::Convert::Utils SYNOPSIS
=====================================

  use Texinfo::Convert::Utils;

  my $today_tree = Texinfo::Convert::Utils::expand_today($converter);
  my $verbatiminclude_tree
     = Texinfo::Convert::Utils::expand_verbatiminclude($converter,
                                                       $verbatiminclude);

13.3 Texinfo::Convert::Utils NOTES
==================================

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.

13.4 Texinfo::Convert::Utils DESCRIPTION
========================================

Miscellaneous methods that may be useful for backends converting Texinfo
trees.  This module contains the methods that can be used in converters
which do not inherit from ^?TexinfoConvert::Converter^?:
Texinfo::Convert::Converter NAME.

13.5 Texinfo::Convert::Utils METHODS
====================================

No method is exported in the default case.

   Most methods takes a _$converter_ as argument, in some cases
optionally, to get some information, see
^?TexinfoConvert::Converter Getting and setting customization
variables^?:: and use methods for error reporting, see
^?TexinfoConvert::Converter^?: Texinfo::Convert::Converter NAME. and
^?TexinfoReport^?: Texinfo::Report NAME, and for strings translations, see
^?TexinfoTranslations^?: Texinfo::Translations NAME.

   Even when the caller does not inherit from
^?TexinfoConvert::Converter^?: Texinfo::Convert::Converter NAME, it could
implement the required interfaces and could also have a converter
available in some cases, to call the functions which require a
converter.

$result = add_heading_number($converter, $heading_element, $heading_text, $do_number)

     The _$converter_ argument may be undef.  _$heading_element_ is a
     heading command tree element.  _$heading_text_ is the already
     formatted heading text.  if the _$do_number_ optional argument is
     defined and false, no number is used and the text is returned as
     is.  This function returns the heading with a number and the
     appendix part if needed.  If _$converter_ is not defined, the
     resulting string won't be translated.

($category, $class, $type, $name, $arguments) = definition_arguments_content($element)

     _$element_ should be a ‘@def*’ Texinfo tree element.  The
     _$category_, _$class_, _$type_, _$name_ are elements corresponding
     to the definition @-command line.  Texinfo elements on the
     @-command line corresponding to arguments in the function
     definition are returned in the _$arguments_ element.  Arguments
     correspond to text following the other elements on the @-command
     line.  If there is no argument, _$arguments_ will be ‘undef’.

$tree = definition_category_tree($converter, $def_line)

     The _$converter_ argument may be undef.  _$def_line_ is a
     ‘def_line’ Texinfo tree container.  This function returns a Texinfo
     tree corresponding to the category of the _$def_line_ taking the
     class into account, if there is one.  If _$converter_ is not
     defined, the resulting string won't be translated.

($encoded_name, $encoding) = $converter->encoded_input_file_name($character_string_name, $input_file_encoding)

($encoded_name, $encoding) = $converter->encoded_output_file_name($character_string_name)

     Encode _$character_string_name_ in the same way as other file names
     are encoded in converters, based on customization variables, and
     possibly on the input file encoding.  Return the encoded name and
     the encoding used to encode the name.  The
     ‘encoded_input_file_name’ and ‘encoded_output_file_name’ functions
     use different customization variables to determine the encoding.
     The _$converter_ argument is not optional and is used both to
     access to customization variables and to access to parser
     information.

     The _$input_file_encoding_ argument is optional.  If set, it is
     used for the input file encoding.  It is useful if there is more
     precise information on the input file encoding where the file name
     appeared.

$tree = expand_today($converter)

     Expand today's date, as a Texinfo tree with translations.  The
     _$converter_ argument is not optional and is used both to retrieve
     customization information and to translate strings.

$tree = expand_verbatiminclude($converter, $verbatiminclude)

     The _$converter_ argument is required and is used to output error
     messages and retrieve customization information
     ^?TexinfoConvert::Converter Getting and setting customization
     variables^?::.  _$verbatiminclude_ is a ‘@verbatiminclude’ tree
     element.  This function returns a ‘@verbatim’ tree elements after
     finding the included file and reading it.

($contents_element, \@accent_commands) = find_innermost_accent_contents($element)

     _$element_ should be an accent command Texinfo tree element.
     Returns an element containing the innermost accent @-command
     contents, normally a text element with one or two letter, and an
     array reference containing the accent commands nested in _$element_
     (including _$element_).  If there is no argument at all for the
     accent command, _$contents_element_ is ‘undef’.

$heading_element = find_root_command_next_heading_command($element, $expanded_format_raw, $do_not_ignore_contents, $do_not_ignore_index_entries)

     Return an heading element found in the _$element_ contents if it
     appears before contents that could be formatted.
     _$expanded_format_raw_ is a hash reference with raw output formats
     (html, docbook, xml...)  as keys, associated value should be set
     for expanded raw output formats.  _$do_not_ignore_contents_ is
     optional.  If set, ‘@contents’ and ‘@shortcontents’ are considered
     to be formatted.  _$do_not_ignore_index_entries_ is optional.  If
     set, index entries are considered to be formatted.

     Only heading elements corresponding to ‘@heading’, ‘@subheading’
     and similar @-commands that are not associated to nodes in general
     are found, not sectioning commands.

13.6 Texinfo::Convert::Utils SEE ALSO
=====================================

^?TexinfoConvert::Converter^?: Texinfo::Convert::Converter NAME. and
^?TexinfoTranslations^?: Texinfo::Translations NAME.

13.7 Texinfo::Convert::Utils AUTHOR
===================================

Patrice Dumas, <pertusus@free.fr>

13.8 Texinfo::Convert::Utils 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.

14 Texinfo::Convert::Unicode
****************************

14.1 Texinfo::Convert::Unicode NAME
===================================

Texinfo::Convert::Unicode - Representation as Unicode characters

14.2 Texinfo::Convert::Unicode SYNOPSIS
=======================================

  use Texinfo::Convert::Unicode qw(unicode_accent encoded_accents
                                   unicode_text);
  use Texinfo::Convert::Text qw(convert_to_text);

  my ($contents_element, $stack)
      = Texinfo::Convert::Utils::find_innermost_accent_contents($accent);

  my $formatted_accents = encoded_accents ($converter,
                 convert_to_text($contents_element), $stack, $encoding,
                        \&Texinfo::Text::ascii_accent_fallback);

  my $accent_text = unicode_accent('e', $accent_command);

14.3 Texinfo::Convert::Unicode NOTES
====================================

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.

14.4 Texinfo::Convert::Unicode DESCRIPTION
==========================================

‘Texinfo::Convert::Unicode’ provides methods dealing with Unicode
representation and conversion of Unicode code points, to be used in
Texinfo converters.

   When an encoding supported in Texinfo is given as argument of a
method of the module, the accented letters or characters returned by the
method should only be represented by Unicode code points if it is known
that Perl should manage to convert the Unicode code points to encoded
characters in the encoding character set.  Note that the actual
conversion is done by Perl, not by the module.

14.5 Texinfo::Convert::Unicode METHODS
======================================

$result = brace_no_arg_command($command_name, $encoding)

     Return the Unicode representation of a command with brace and no
     argument _$command_name_ (like ‘@bullet{}’, ‘@aa{}’ or
     ‘@guilsinglleft{}’), or ‘undef’ if the Unicode representation
     cannot be converted to encoding _$encoding_.

$possible_conversion = check_unicode_point_conversion($arg, $output_debug)

     Check that it is possible to output actual UTF-8 binary bytes
     corresponding to the Unicode code point string _$arg_ (such as
     ‘201D’).  Perl gives a warning and will not output UTF-8 for
     Unicode non-characters such as U+10FFFF. If the optional
     _$output_debug_ argument is set, a debugging output warning is
     emitted if the test of the conversion failed.  Returns 1 if the
     conversion is possible and can be attempted, 0 otherwise.

$result = encoded_accents($converter, $text, $stack, $encoding, $format_accent, $set_case)

     _$encoding_ is the encoding the accented characters should be
     encoded to.  If _$encoding_ not set, _$result_ is set to ‘undef’.
     Nested accents and their content are passed with _$text_ and
     _$stack_.  _$text_ is the text appearing within nested accent
     commands.  _$stack_ is an array reference holding the nested
     accents texinfo tree elements.  In general, _$text_ is the
     formatted contents and _$stack_ the stack returned by
     ^?TexinfoConvert::Utils::find_innermost_accent_contents^?:
     ^?Texinfo::Convert::Utils ($contents_element, \@accent_commands) =
     find_innermost_accent_contents($element)^?.  The function tries to
     convert as much as possible the accents to _$encoding_ starting
     from the innermost accent.

     _$format_accent_ is a function reference that is used to format the
     accent commands if there is no encoded character available at some
     point of the conversion of the _$stack_.  _$converter_ is a
     converter object optionaly used by _$format_accent_.  It may be
     ‘undef’ if there is no need of converter object in
     _$format_accent_.

     The _$set_case_ argument is optional.  If _$set_case_ is positive,
     the result is upper-cased, while if it is negative, the result is
     lower-cased.

$width = string_width($string)

     Return the string width, taking into account the fact that some
     characters have a zero width (like composing accents) while some
     have a width of 2 (most chinese characters, for example).

$result = unicode_accent($text, $accent_command)

     _$text_ is the text appearing within an accent command.
     _$accent_command_ should be a Texinfo tree element corresponding to
     an accent command taking an argument.  The function returns the
     Unicode representation of the accented character.

$is_decoded = unicode_point_decoded_in_encoding($encoding, $unicode_point)

     Return true if the _$unicode_point_ will be encoded in the encoding
     _$encoding_.  The _$unicode_point_ should be specified as a four
     letter string describing an hexadecimal number with letters in
     upper case (such as ‘201D’).  Tables are used to determine if the
     _$unicode_point_ will be encoded, when the encoding does not cover
     the whole Unicode range.

     If the encoding is not supported in Texinfo, the result will always
     be false.

$result = unicode_text($text, $in_code)

     Return _$text_ with dashes and quotes corresponding, for example to
     ‘---’ or ‘'’, represented as Unicode code points.  If _$in_code_ is
     set, the text is considered to be in code style.

14.6 Texinfo::Convert::Unicode AUTHOR
=====================================

Patrice Dumas, <pertusus@free.fr>

14.7 Texinfo::Convert::Unicode 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.

15 Texinfo::Convert::NodeNameNormalization
******************************************

15.1 Texinfo::Convert::NodeNameNormalization NAME
=================================================

Texinfo::Convert::NodeNameNormalization - Normalize and transliterate
Texinfo trees

15.2 Texinfo::Convert::NodeNameNormalization SYNOPSIS
=====================================================

  use Texinfo::Convert::NodeNameNormalization qw(convert_to_identifier
                                        normalize_transliterate_texinfo);

  my $normalized = convert_to_identifier($node_element->{'args'}->[0]);

  my $file_name
    = normalize_transliterate_texinfo($section_element->{'args'}->[0]);

15.3 Texinfo::Convert::NodeNameNormalization NOTES
==================================================

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.

15.4 Texinfo::Convert::NodeNameNormalization DESCRIPTION
========================================================

‘Texinfo::Convert::NodeNameNormalization’ allows to normalize node names
with ‘convert_to_normalized’ and ‘convert_to_identifier’.
‘convert_to_identifier’ follows the specification described in the
Texinfo manual _HTML Xref_ node.  This is useful whenever one want a
unique identifier for Texinfo content, which is only composed of letter,
digits, ‘-’ and ‘_’, for example for ‘@node’, ‘@float’ and ‘@anchor’
names normalization.  ‘convert_to_normalized’ leaves out the step of
protecting characters.

   It is also possible to transliterate non-ASCII letters, instead of
mangling them, with ‘normalize_transliterate_texinfo’, losing the
uniqueness feature of normalized node names.

   Another method, ‘transliterate_protect_file_name’ transliterates
non-ASCII letters and protect characters that should not appear on file
names.

15.5 Texinfo::Convert::NodeNameNormalization METHODS
====================================================

$partially_normalized = convert_to_normalized($tree)

     The Texinfo _$tree_ is returned as a string, with @-commands and
     spaces normalized as described in the Texinfo manual _HTML Xref_
     node.  ASCII 7-bit characters other than spaces and non-ASCII
     characters are left as is in the resulting string.

$normalized = convert_to_identifier($tree)

     The Texinfo _$tree_ is returned as a string, normalized as
     described in the Texinfo manual _HTML Xref_ node.

     The result will be poor for Texinfo trees which are not @-command
     arguments (on an @-command line or in braces), for instance if the
     tree contains ‘@node’ or block commands.

$transliterated = normalize_transliterate_texinfo($tree, $no_unidecode)

     The Texinfo _$tree_ is returned as a string, with non-ASCII letters
     transliterated as ASCII, but otherwise similar with
     ‘convert_to_identifier’ output.  If the optional _$no_unidecode_
     argument is set, ‘Text::Unidecode’ is not used for characters whose
     transliteration is not built-in.

$transliterated = transliterate_texinfo($tree, $no_unidecode)

     The Texinfo _$tree_ is returned as a string, with non-ASCII letters
     transliterated as ASCII. If the optional _$no_unidecode_ argument
     is set, ‘Text::Unidecode’ is not used for characters whose
     transliteration is not built-in.

$file_name = transliterate_protect_file_name($string, $no_unidecode)

     The string _$string_ is returned with non-ASCII letters
     transliterated as ASCII, and ASCII characters not safe in file
     names protected as in node normalization.  If the optional
     _$no_unidecode_ argument is set, ‘Text::Unidecode’ is not used for
     characters whose transliteration is not built-in.

15.6 Texinfo::Convert::NodeNameNormalization AUTHOR
===================================================

Patrice Dumas, <pertusus@free.fr>

15.7 Texinfo::Convert::NodeNameNormalization 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.

16 Texinfo::Convert::Text
*************************

16.1 Texinfo::Convert::Text NAME
================================

Texinfo::Convert::Text - Convert Texinfo tree to simple text

16.2 Texinfo::Convert::Text SYNOPSIS
====================================

  use Texinfo::Convert::Text qw(convert_to_text text_accents);

  my $result = convert_to_text($tree);

  my $accents_text = text_accents($accents, 'utf-8');

  # using text conversion options set in $converter derived from
  # Texinfo::Convert::Converter
  my $text_options = $converter->{'convert_text_options'};

  set_options_code($text_options);
  my $result_with_converter = convert_to_text($tree, $text_options);
  reset_options_code($text_options);

16.3 Texinfo::Convert::Text NOTES
=================================

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.

16.4 Texinfo::Convert::Text DESCRIPTION
=======================================

‘Texinfo::Convert::Text’ is a simple backend that converts a Texinfo
tree to simple text.  It is used in converters, especially for file
names.  The conversion is very simple, and, in the default case, cannot
handle error handling nor some output strings translation.

   Converters derived from ^?TexinfoConvert::Converter^?:
Texinfo::Convert::Converter NAME. should have conversion text options
preset associated to the ‘convert_text_options’ key.

   The main function is ‘convert_to_text’.  The text conversion options
can be modified with the ‘set_*’ functions before calling
‘convert_to_text’, and reset afterwards with the corresponding ‘reset_*’
functions.

16.5 Texinfo::Convert::Text METHODS
===================================

$result = convert_to_text($tree, $text_options)

     Convert a Texinfo tree to simple text.  _$text_options_ is a hash
     reference of options.  The converter is very simple, and has almost
     no internal state besides the options.  It cannot handle as is
     output strings translation or error storing.

     If the _converter_ option is set in _$text_options_, some
     additional features may be available for the conversion of some
     @-commands, like output strings translation or error reporting.

     The ‘NUMBER_SECTIONS’, ‘ASCII_GLYPH’ and ‘TEST’ options
     corresponding to customization variables may be set in
     _$text_options_.  The following options may also be set:

     enabled_encoding

          If set, the value is considered to be the encoding name
          texinfo accented letters should be converted to.  This option
          being set corresponds to the ‘--enable-encoding’ option, or
          the ‘ENABLE_ENCODING’ customization variable for Info and
          Plaintext and for some conversion to text in other formats.
          For file names in HTML and LaTeX, and for DocBook or Texinfo
          XML, this variable should in general be set unless the output
          encoding is US-ASCII.

     set_case

          If positive, the text is upper-cased, if negative, the text is
          lower-cased.

     sort_string

          A somehow internal option to convert to text more suitable for
          alphabetical sorting rather than presentation.

     converter

          If this converter object is passed to the function, some
          features of this object may be used during conversion.  Mostly
          error reporting and strings translation.  See also
          ^?TexinfoConvert::Converter^?: Texinfo::Convert::Converter NAME.

     expanded_formats

          A reference on a hash.  The keys should be format names (like
          ‘html’, ‘tex’), and if the corresponding value is set, the
          format is expanded.

$result_accent_text = ascii_accent_fallback($converter, $text, $accent_command)

     _$text_ is the text appearing within an accent command.
     _$accent_command_ should be a Texinfo tree element corresponding to
     an accent command taking an argument.  The function returns a
     transliteration of the accented character.  The _$converter_
     argument is ignored, but needed for this function to be in argument
     of functions that need a fallback for accents conversion.

set_options_code($text_options)

reset_options_code($text_options)

     ‘set_options_code’ sets _$text_options_ to be in code style.
     (mostly ‘--’, ‘---’, ‘''’ and ‘``’ are kept as is).
     ‘reset_options_code’ undo the effect of ‘set_options_code’.

     ‘reset_options_code’ should always be called after
     ‘set_options_code’.

set_options_encoding($text_options, $encoding)

set_options_encoding_if_not_ascii($customization_information, $text_options)

reset_options_encoding($text_options)

     ‘set_options_encoding’ sets ‘enabled_encoding’ in _$text_options_
     to _$encoding_.  ‘set_options_encoding_if_not_ascii’ sets
     ‘enabled_encoding’ in _$text_options_ based on customization
     options associated to _$customization_information_.  In that case,
     ‘enabled_encoding’ is set unless the output encoding is US-ASCII
     even if ‘ENABLE_ENCODING’ is not set.

     ‘reset_options_encoding’ undo the effect of ‘set_options_encoding’
     and ‘set_options_encoding_if_not_ascii’ and should always be called
     after these functions.

$accents_text = text_accents($accents, $encoding, $set_case)

     _$accents_ is an accent command that may contain other nested
     accent commands.  The function will format the whole stack of
     nested accent commands and the innermost text.  If _$encoding_ is
     set, the formatted text is converted to this encoding as much as
     possible instead of being converted as simple ASCII. If _$set_case_
     is positive, the result is meant to be upper-cased, if it is
     negative, the result is to be lower-cased.

16.6 Texinfo::Convert::Text AUTHOR
==================================

Patrice Dumas, <pertusus@free.fr>

16.7 Texinfo::Convert::Text 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.

17 Texinfo::Convert::Converter
******************************

17.1 Texinfo::Convert::Converter NAME
=====================================

Texinfo::Convert::Converter - Parent class for Texinfo tree converters

17.2 Texinfo::Convert::Converter SYNOPSIS
=========================================

  package Texinfo::Convert::MyConverter;

  use Texinfo::Convert::Converter;
  @ISA = qw(Texinfo::Convert::Converter);

  sub converter_defaults ($$) {
    return \%myconverter_defaults;
  }
  sub converter_initialize($) {
    my $self = shift;
    ...
  }

  sub conversion_initialization($;$) {
    my $self = shift;
    my $document = shift;

    if ($document) {
      $self->set_document($document);
    }

    $self->{'document_context'} = [{}];
    ...
  }

  sub conversion_finalization($) {
    my $self = shift;
  }

  sub convert_tree($$) {
    ...
  }

  sub convert($$) {
    my $self = shift;
    my $document = shift;

    $self->conversion_initialization($document);

    ...
    $self->conversion_finalization();
  }

  sub output($$) {
    my $self = shift;
    my $document = shift;

    $self->conversion_initialization($document);

    ...
    $self->conversion_finalization();
    ...
  }

  # end of Texinfo::Convert::MyConverter

  my $converter = Texinfo::Convert::MyConverter->converter();
  $converter->output($texinfo_parsed_document);

17.3 Texinfo::Convert::Converter NOTES
======================================

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.

17.4 Texinfo::Convert::Converter DESCRIPTION
============================================

‘Texinfo::Convert::Converter’ is a super class that can be used to
simplify converters initialization.  The class also provide some useful
methods.  In turn, the converter should define some methods for
conversion.  In general ‘convert_tree’, ‘output’ and ‘convert’ should be
defined.

$result = $converter->convert_tree($tree)

     The ‘convert_tree’ method is mandatory and should convert portions
     of Texinfo tree.  Takes a _$converter_ and Texinfo tree _$tree_ in
     arguments.  Returns the converted output.

$result = $converter->output($document)

$result = $converter->output_tree($document)

     The ‘output’ method is used by converters as entry point for
     conversion to a file with headers and so on.  This method should be
     implemented by converters.  ‘output’ is called from ‘texi2any’.
     ‘output’ takes a _$converter_ and a Texinfo parsed document
     ‘Texinfo::Document’ _$document_ as arguments.

     ‘Texinfo::Convert::Converter’ implements a generic ‘output_tree’
     function suitable for conversion of the Texinfo tree, with the
     conversion result output into a file or returned from the function.
     ‘output_tree’ takes a _$converter_ and a Texinfo parsed document
     ‘Texinfo::Document’ _$document_ as arguments.  In a converter that
     uses ‘output_tree’, ‘output’ is in general defined as:

       sub output($$) {
         my $self = shift;
         my $document = shift;

         return $self->output_tree($document);
       }

     In general, ‘output’ and ‘output_tree’ output to files and return
     ‘undef’.  When the output file name is an empty string, however, it
     is customary for ‘output’ and ‘output_tree’ to return the output as
     a character string instead.  The output file name is obtained in
     ‘output_tree’ through a call to
     ‘determine_files_and_directory’,
     $destination_directory, $output_filename,
     $document_name, $input_basefile) =
     $converter->determine_files_and_directory($output_format)^?.  In
     general ‘determine_files_and_directory’ is also used when
     ‘output_tree’ is not used.

$result = $converter->convert($document)

     Entry point for the conversion of a Texinfo parsed document to an
     output format, without the headers usually done when outputting to
     a file.  ‘convert’ takes a _$converter_ and a Texinfo parsed
     document ‘Texinfo::Document’ _$document_ as arguments.  Returns the
     output as a character string.  Not mandatory, not called from
     ‘texi2any’, but used in the ‘texi2any’ test suite.

$result = $converter->convert_output_unit($output_unit)

     Can be used for the conversion of output units by converters.
     ‘convert_output_unit’ takes a _$converter_ and an output unit
     _$output_unit_ as argument.  The implementation of
     ‘convert_output_unit’ of ‘Texinfo::Convert::Converter’ could be
     suitable in many cases.  Output units are typically returned by
     ^?‘TexinfoOutputUnits’ ‘split_by_section’^?:
     Texinfo::OutputUnits $output_units = split_by_section($document).
     or ^?‘TexinfoOutputUnits’ ‘split_by_node’^?:
     Texinfo::OutputUnits $output_units = split_by_node($document).

   Two methods, ‘converter_defaults’ and ‘converter_initialize’ are used
for initialization, to give information to ‘Texinfo::Convert::Converter’
and can be redefined in converters.

   To help with the conversion, the ‘set_document’ function associates a
‘Texinfo::Document’ to a converter.  Other methods are called in default
implementations to be redefined to call code at specific moments of the
conversion.  ‘conversion_initialization’, for instance, is generally
called at the beginning of ‘output’, ‘output_tree’ and ‘convert’.
‘conversion_finalization’ is generally called at the end of
‘output_tree’, ‘output’ and ‘convert’.  ‘output_tree’ also calls the
‘conversion_output_begin’ method before the Texinfo tree conversion to
obtain the beginning of the output.  ‘output_tree’ calls the
‘conversion_output_end’ method after the Texinfo tree conversion to
obtain the end of the output.

   For output formats based on output units conversion, the
‘Texinfo::Convert::Plaintext’ ‘output’ method could be a good starting
point.  HTML and Info output are also based on output units conversion.
Output units are not relevant for all the formats, the Texinfo tree can
also be converted directly, in general by using ‘output_tree’.  This is
how the other Converters are implemented.

   Existing backends based on ‘output_tree’ may be used as examples.
‘Texinfo::Convert::Texinfo’ together with
‘Texinfo::Convert::PlainTexinfo’, as well as
‘Texinfo::Convert::TextContent’ are trivial examples.
‘Texinfo::Convert::Text’ is less trivial, although still simple, while
‘Texinfo::Convert::DocBook’ is a real converter that is also not too
complex.

   The documentation of ^?TexinfoCommon^?: Texinfo::Common NAME,
see ^?TexinfoOutputUnits^?: Texinfo::OutputUnits NAME, see
^?TexinfoConvert::Unicode^?: Texinfo::Convert::Unicode NAME. and
^?TexinfoConvert::Text^?: Texinfo::Convert::Text NAME. describes modules
or additional function that may be useful for backends, while the parsed
Texinfo tree is described in ^?TexinfoParser^?: Texinfo::Parser
NAME.

17.5 Texinfo::Convert::Converter METHODS
========================================

17.5.1 Converter Initialization
-------------------------------

A module subclassing ‘Texinfo::Convert::Converter’ is created by calling
the ‘converter’ method that should be inherited from
‘Texinfo::Convert::Converter’.

$converter = MyConverter->converter($options)

     The _$options_ hash reference holds options for the converter.
     These options should be Texinfo customization options.  The
     customization options are described in the Texinfo manual or in the
     customization API manual.

     The ‘converter’ function returns a converter object (a blessed hash
     reference) after checking the options and performing some
     initializations.

   To help with the initializations, the modules subclassing
‘Texinfo::Convert::Converter’ can define two methods:

\%defaults = $converter_or_class->converter_defaults($options)

     Returns a reference on a hash with defaults for the converter
     module customization options or ‘undef’.  The _$options_ hash
     reference holds options for the converter.  This method is called
     through a converter by ‘converter’,
     but it may also be called through
     a converter module class.

converter_initialize

     This method is called at the end of the
     ‘Texinfo::Convert::Converter’ converter initialization.

17.5.2 Conversion
-----------------

For conversion with ‘output’ and ‘convert’ a document to convert should
be associated to the converter, in general the document passed in
argument of ‘output’ or ‘convert’.  The ‘set_document’ function
associates a ‘Texinfo::Document’ to a converter.  This function is used
in the default implementations.

$converter->set_document($document)

     Associate _$document_ to _$converter_.  Also set the encoding
     related customization options based on _$converter_ customization
     information and information on document encoding, and setup
     converter hash ‘convert_text_options’ value that can be used to
     call ^?‘TexinfoConvert::Text::convert_to_text’^?:
     ^?Texinfo::Convert::Text $result = convert_to_text($tree,
     $text_options)^?.

   The ‘conversion_initialization’, ‘conversion_finalization’,
‘conversion_output_begin’ and ‘conversion_output_end’ can be redefined
to call code at diverse moments:

$converter->conversion_initialization($document)

$converter->conversion_finalization()

     ‘conversion_initialization’ is called at the beginning of
     ‘output_tree’ and of the default implementations of the ‘output’
     and ‘convert’ functions.  ‘conversion_finalization’ is called at
     the end of ‘output_tree’ and of the default ‘output’ and ‘convert’
     methods implementations.  These functions should be redefined to
     have code run before a document conversion and after the document
     conversion.

     In the default case, ‘conversion_initialization’ calls
     set_document
     to associate the
     ‘Texinfo::Document’ document passed in argument to the converter.
     A subclass converter redefining ‘conversion_initialization’ should
     in general call ‘set_document’ in the redefined function too to
     associate the converted document to the converter.

$beginning = $converter->conversion_output_begin($output_file, $output_filename)

$end = $converter->conversion_output_end()

     ‘conversion_output_begin’ returned string _$beginning_ is output by
     the ‘output_tree’ calling method before the Texinfo tree
     conversion.  The _$output_file_ argument is the output file path.
     If _$output_file_ is an empty string, it means that text will be
     returned by the converter instead of being written to an output
     file.  _$output_filename_ is, in general, the file name portion of
     _$output_file_ (without directory) but can also be set based on
     ‘@setfilename’.

     ‘conversion_output_end’ returned string _$end_ is output by the
     ‘output_tree’ calling method after the Texinfo tree conversion.

     The default methods implementations return an empty string.

   Calling ‘conversion_initialization’ and, if needed,
‘conversion_finalization’ in redefined ‘output’ and ‘convert’ methods is
not mandated, but it is recommended to have similar converter codes.  In
subclassed converters that do not need to define
‘conversion_initialization’, calling the default
‘Texinfo::Convert::Converter’ ‘conversion_initialization’ implementation
is also recommended to avoid having to explictely call ‘set_document’.
If ‘conversion_initialization’ is defined in a converter subclass it is
recommended to call ‘set_document’ at the very beginning of the function
to have the document associated to the converter.

17.5.3 Getting and setting customization variables
--------------------------------------------------

‘Texinfo::Convert::Converter’ implements a simple interface to set and
retrieve Texinfo customization variables.  Helper functions from diverse
Texinfo modules needing customization information expect an object
implementing ‘get_conf’ and/or ‘set_conf’.  The converter itself can
therefore be used in such cases.

   Customization variables are typically setup when initializing a
converter with ‘converter’
and completed by Texinfo informative
@-commands tree element values, for commands such as ‘@frenchspacing’ or
‘@footnotestyle’.

$converter->force_conf($variable_name, $variable_value)

     Set the Texinfo customization option _$variable_name_ to
     _$variable_value_.  This should rarely be used, but the purpose of
     this method is to be able to revert a customization that is always
     wrong for a given output format, like the splitting for example.

$converter->get_conf($variable_name)

     Returns the value of the Texinfo customization variable
     _$variable_name_.

$status = $converter->set_conf($variable_name, $variable_value)

     Set the Texinfo customization option _$variable_name_ to
     _$variable_value_ if not set as a converter option.  Returns false
     if the customization options was not set.

17.5.4 Registering error and warning messages
---------------------------------------------

‘Texinfo::Convert::Converter’ implements an interface to register error
and warning messages in the converter, that can be retrieved later on,
in general to be given to ‘Texinfo::Report::add_formatted_message’.
Underneath, ‘Texinfo::Report’ is used to setup the messages data
structure.

$converter->converter_document_error($text, $continuation)

$converter->converter_document_warn($text, $continuation)

     Register a warning or an error.  The _$text_ is the text of the
     error or warning.

     The _$continuation_ optional arguments, if true, conveys that the
     line is a continuation line of a message.

$converter->converter_line_error($text, $error_location_info, $continuation)

$converter->converter_line_warn($text, $error_location_info, $continuation)

     Register a warning or an error with a line information.  The
     _$text_ is the text of the error or warning.  The
     _$error_location_info_ argument holds the information on the error
     or warning location.  The _$error_location_info_ reference on hash
     may be obtained from Texinfo elements _source_info_ keys.  It may
     also be setup to point to a file name, using the ‘file_name’ key
     and to a line number, using the ‘line_nr’ key.  The ‘file_name’ key
     value should be a binary string.

     The _$continuation_ optional arguments, if true, conveys that the
     line is a continuation line of a message.

\@error_warning_messages = $converter->get_converter_errors()

     Return a reference on an array containing the error or warning
     messages registered in the converter.  Error and warning messages
     are hash references as described in ^?TexinfoReport::errors^?:
     ^?Texinfo::Report ($error_warnings_list, $error_count) =
     errors($registrar)^?. and can be used in input of
     ^?TexinfoReport::add_formatted_message^?: Texinfo::Report
     $registrar->add_formatted_message ($msg).

17.5.5 Translations in output documents
---------------------------------------

‘Texinfo::Convert::Converter’ provides wrappers around
^?TexinfoTranslations^?: Texinfo::Translations NAME. methods that sets the
language to the current ‘documentlanguage’.

   The ‘cdt’ and ‘pcdt’ methods are used to translate strings to be
output in converted documents, and return a Texinfo tree.  The
‘cdt_string’ is similar but returns a simple string, for already
converted strings.

$tree = $converter->cdt($string, $replaced_substrings, $translation_context)

$string = $converter->cdt_string($string, $replaced_substrings, $translation_context)

     The _$string_ is a string to be translated.  With ‘cdt’ the
     function returns a Texinfo tree, as the string is interpreted as
     Texinfo code after translation.  With ‘cdt_string’ a string is
     returned.

     _$replaced_substrings_ is an optional hash reference specifying
     some substitution to be done after the translation.  The key of the
     _$replaced_substrings_ hash reference identifies what is to be
     substituted.  In the string to be translated word in brace matching
     keys of _$replaced_substrings_ are replaced.  For ‘cdt’, the value
     is a Texinfo tree that is substituted in the resulting Texinfo
     tree.  For ‘cdt_string’, the value is a string that is replaced in
     the resulting string.

     The _$translation_context_ is optional.  If not ‘undef’ this is a
     translation context string for _$string_.  It is the first argument
     of ‘pgettext’ in the C API of Gettext.

$tree = $object->pcdt($translation_context, $string, $replaced_substrings)

     Same to ‘cdt’ except that the _$translation_context_ is not
     optional.  This function is useful to mark strings with a
     translation context for translation.  This function is similar to
     pgettext in the Gettext C API.

17.5.6 Index sorting
--------------------

You should call the following methods to sort indices in conversion:

$sorted_indices = $converter->get_converter_indices_sorted_by_index()

$sorted_indices = $converter->get_converter_indices_sorted_by_letter()

     ‘get_converter_indices_sorted_by_letter’ returns the indices sorted
     by index and letter, while ‘get_converter_indices_sorted_by_index’
     returns the indices with all entries of an index together.

     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.  The letter is a character string
     suitable for sorting letters, but is not necessarily the best to
     use for output.

     When simply sorting, the array of the sorted index entries is
     associated with the index name.

     The functions call
     ^?‘TexinfoDocument::sorted_indices_by_letter’^?: ^?Texinfo::Document
     $sorted_indices =
     $document->sorted_indices_by_letter($customization_information,
     $use_unicode_collation, $locale_lang)^?. or
     ^?‘TexinfoDocument::sorted_indices_by_index’^?: ^?Texinfo::Document
     $sorted_indices =
     $document->sorted_indices_by_index($customization_information,
     $use_unicode_collation, $locale_lang)^?. with arguments based on
     ‘USE_UNICODE_COLLATION’, ‘COLLATION_LANGUAGE’ and
     ‘DOCUMENTLANGUAGE_COLLATION’ customization options, and, if
     relevant, current ‘@documentlanguage’.

17.5.7 Conversion to XML
------------------------

Some ‘Texinfo::Convert::Converter’ methods target conversion to XML.
Most methods take a _$converter_ as argument to get some information and
use methods for error reporting.

$formatted_text = $converter->xml_format_text_with_numeric_entities($text)

     Replace quotation marks and hyphens used to represent dash in
     Texinfo text with numeric XML entities.

$protected_text = $converter->xml_protect_text($text)

     Protect special XML characters (&, <, >, ") of _$text_.

$comment = $converter->xml_comment($text)

     Returns an XML comment for _$text_.

$result = xml_accent($text, $accent_command, $in_upper_case, $use_numeric_entities)

     _$text_ is the text appearing within an accent command.
     _$accent_command_ should be a Texinfo tree element corresponding to
     an accent command taking an argument.  _$in_upper_case_ is
     optional, and, if set, the text is put in upper case.  The function
     returns the accented letter as XML named entity if possible,
     falling back to numeric entities if there is no named entity and
     returns the argument as last resort.  _$use_numeric_entities_ is
     optional.  If set, numerical entities are used instead of named
     entities if possible.

$result = $converter->xml_accents($accent_command, $in_upper_case)

     _$accent_command_ is an accent command, which may have other accent
     commands nested.  If _$in_upper_case_ is set, the result should be
     upper cased.  The function returns the accents formatted as XML.

$result = xml_numeric_entity_accent($accent_command_name, $text)

     _$accent_command_name_ is the name of an accent command.  _$text_
     is the text appearing within the accent command.  Returns the
     accented letter as XML numeric entity, or ‘undef’ is there is no
     such entity.

17.5.8 Helper methods
---------------------

The module provides methods that may be useful for converter.  Most
methods take a _$converter_ as argument to get some information and use
methods for error reporting, see Registering error and warning messages.
Also to translate strings, see Translations in output documents.
For useful methods that need a converter optionally and can be used in
converters that do not inherit from ‘Texinfo::Convert::Converter’, see
^?TexinfoConvert::Utils^?: Texinfo::Convert::Utils NAME.

$contents_element = $converter->comma_index_subentries_tree($entry, $separator)

     _$entry_ is a Texinfo tree index entry element.  The function sets
     up an array with the ‘@subentry’ contents.  The result is returned
     as ‘contents’ in the _$contents_element_ element, or ‘undef’ if
     there is no such content.  _$separator_ is an optional separator
     argument used, if given, instead of the default: a comma followed
     by a space.

$result = $converter->convert_accents($accent_command, \&format_accents, $output_encoded_characters, $in_upper_case)

     _$accent_command_ is an accent command, which may have other accent
     commands nested.  The function returns the accents formatted either
     as encoded letters if _$output_encoded_characters_ is set, or
     formatted using _\&format_accents_.  If _$in_upper_case_ is set,
     the result should be uppercased.

$succeeded = $converter->create_destination_directory($destination_directory_path, $destination_directory_name)

     Create destination directory _$destination_directory_path_.
     _$destination_directory_path_ should be a binary string, while
     _$destination_directory_name_ should be a character string, that
     can be used in error messages.  _$succeeded_ is true if the
     creation was successful or uneeded, false otherwise.

($output_file, $destination_directory, $output_filename, $document_name, $input_basefile) = $converter->determine_files_and_directory($output_format)

     Determine output file and directory, as well as names related to
     files.  The result depends on the presence of ‘@setfilename’, on
     the Texinfo input file name, and on customization options such as
     ‘OUTPUT’, ‘SUBDIR’ or ‘SPLIT’, as described in the Texinfo manual.
     If _$output_format_ is defined and not an empty string,
     ‘_$output_format’ is prepended to the default directory name.

     _$output_file_ is mainly relevant when not split and should be used
     as the output file name.  In general, if not split and
     _$output_file_ is an empty string, it means that text should be
     returned by the converter instead of being written to an output
     file.  This is used in the test suite.  _$destination_directory_ is
     either the directory _$output_file_ is in, or if split, the
     directory where the files should be created.  _$output_filename_
     is, in general, the file name portion of _$output_file_ (without
     directory) but can also be set based on ‘@setfilename’, in
     particular when _$output_file_ is an empty string.
     _$document_name_ is _$output_filename_ without extension.
     _$input_basefile_ is based on the input Texinfo file name, with the
     file name portion only (without directory).

     The strings returned are text strings.

($encoded_name, $encoding) = $converter->encoded_input_file_name($character_string_name, $input_file_encoding)

($encoded_name, $encoding) = $converter->encoded_output_file_name($character_string_name)

     Encode _$character_string_name_ in the same way as other file names
     are encoded in the converter, based on customization variables, and
     possibly on the input file encoding.  Return the encoded name and
     the encoding used to encode the name.  The
     ‘encoded_input_file_name’ and ‘encoded_output_file_name’ functions
     use different customization variables to determine the encoding.

     The _$input_file_encoding_ argument is optional.  If set, it is
     used for the input file encoding.  It is useful if there is more
     precise information on the input file encoding where the file name
     appeared.

     Note that ‘encoded_output_file_name’ is a wrapper around the
     function with the same name in
     ^?‘TexinfoConvert::Utils::encoded_output_file_name’^?:
     ^?Texinfo::Convert::Utils ($encoded_name, $encoding) =
     $converter->encoded_output_file_name($character_string_name)^?, and
     ‘encoded_input_file_name’ is a wrapper around the function with the
     same name in
     ^?‘TexinfoConvert::Utils::encoded_input_file_name’^?:
     ^?Texinfo::Convert::Utils ($encoded_name, $encoding) =
     $converter->encoded_input_file_name($character_string_name,
     $input_file_encoding)^?.

($caption, $prepended) = $converter->float_name_caption($float)

     _$float_ is a Texinfo tree ‘@float’ element.  This function returns
     the caption element that should be used for the float formatting
     and the _$prepended_ Texinfo tree combining the type and label of
     the float.

$tree = $converter->float_type_number($float)

     _$float_ is a Texinfo tree ‘@float’ element.  This function returns
     the type and number of the float as a Texinfo tree with
     translations.

$end_line = $converter->format_comment_or_return_end_line($element)

     Format comment at end of line or return the end of line associated
     with the element.  In many cases, converters ignore comments and
     output is better formatted with new lines added independently of
     the presence of newline or comment in the initial Texinfo line, so
     most converters are better off not using this method.

$filename = sub $converter->node_information_filename($normalized, $label_element)

     Returns the normalized file name corresponding to the _$normalized_
     node name and to the _$label_element_ node name element contents.

($normalized_name, $filename) = $converter->normalized_sectioning_command_filename($element)

     Returns a normalized name _$normalized_name_ corresponding to a
     sectioning command tree element _$element_, expanding the command
     argument using transliteration and characters protection.  Also
     returns _$filename_ the corresponding filename based on
     _$normalized_name_ taking into account additional constraint on
     file names and adding a file extension.

$converter->present_bug_message($message, $element)

     Show a bug message using _$message_ text.  Use information on
     _$element_ tree element if given in argument.

$converter->set_global_document_commands($commands_location, $selected_commands)

     Set the Texinfo customization options for @-commands.
     _$selected_commands_ is an array reference containing the
     @-commands set.  _$commands_location_ specifies where in the
     document the value should be taken from.  The possibilities are:

     before

          Set to the values before document conversion, from defaults
          and command-line.

     last

          Set to the last value for the command.

     preamble

          Set sequentially to the values in the Texinfo preamble.

     preamble_or_first

          Set to the first value of the command if the first command is
          not in the Texinfo preamble, else set as with _preamble_,
          sequentially to the values in the Texinfo preamble.

     Notice that the only effect of this function is to set a
     customization variable value, no @-command side effects are run, no
     associated customization variables are set.

     For more information on the function used to set the value for each
     of the command, see ^?‘TexinfoCommon’
     ‘set_global_document_command’^?: ^?Texinfo::Common $element =
     set_global_document_command($customization_information,
     $global_commands_information, $cmdname, $command_location)^?.

$table_item_tree = $converter->table_item_content_tree($element)

     _$element_ should be an ‘@item’ or ‘@itemx’ tree element.  Returns
     a tree in which the @-command in argument of ‘@*table’ of the
     _$element_ has been applied to the _$element_ line argument, or
     ‘undef’.

$result = $converter->top_node_filename($document_name)

     Returns a file name for the Top node file using either ‘TOP_FILE’
     customization value, or ‘EXTENSION’ customization value and
     _$document_name_.

   Finally, there is:

$result = $converter->output_internal_links()

     At this level, the method just returns undef.  It is used in the
     HTML output, following the ‘--internal-links’ option of ‘texi2any’
     specification.

17.6 Texinfo::Convert::Converter SEE ALSO
=========================================

TexinfoCommon: Texinfo::Common NAME, see
TexinfoConvert::Unicode: Texinfo::Convert::Unicode NAME, see
TexinfoReport: Texinfo::Report NAME, see TexinfoTranslations:
Texinfo::Translations NAME, see TexinfoConvert::Utils:
Texinfo::Convert::Utils NAME. and TexinfoParser: Texinfo::Parser
NAME.

17.7 Texinfo::Convert::Converter AUTHOR
=======================================

Patrice Dumas, <pertusus@free.fr>

17.8 Texinfo::Convert::Converter COPYRIGHT AND LICENSE
======================================================

Copyright 2011- 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.

18 Texinfo::Convert::Info
*************************

18.1 Texinfo::Convert::Info NAME
================================

Texinfo::Convert::Info - Convert Texinfo tree to Info

18.2 Texinfo::Convert::Info SYNOPSIS
====================================

  my $converter
    = Texinfo::Convert::Info->converter({'NUMBER_SECTIONS' => 0});

  $converter->output($document);
  $converter->convert($document);
  $converter->convert_tree($tree);

18.3 Texinfo::Convert::Info NOTES
=================================

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.

18.4 Texinfo::Convert::Info DESCRIPTION
=======================================

Texinfo::Convert::Info converts a Texinfo tree to Info.

18.5 Texinfo::Convert::Info METHODS
===================================

$converter = Texinfo::Convert::Info->converter($options)

     Initialize converter from Texinfo to Info.

     The _$options_ hash reference holds Texinfo customization options
     for the converter.  These options should be Texinfo customization
     options that can be passed to the converter.  Most of the
     customization options are described in the Texinfo manual or in the
     customization API manual.  Those customization options, when
     appropriate, override the document content.

     See ^?TexinfoConvert::Converter^?: Texinfo::Convert::Converter
     NAME. for more information.

$converter->output($document)

     Convert a Texinfo parsed document _$document_ and output the result
     in files as described in the Texinfo manual.

$result = $converter->convert($document)

     Convert a Texinfo parsed document _$document_ and return the
     resulting output.

$result = $converter->convert_tree($tree)

     Convert a Texinfo tree portion _$tree_ and return the resulting
     output.  This function does not try to output a full document but
     only portions.  For a full document use ‘convert’.

     In general, this function should be called after the converter has
     been associated to a document by a call to ‘output’ or ‘convert’.

18.6 Texinfo::Convert::Info AUTHOR
==================================

Patrice Dumas, <pertusus@free.fr>

18.7 Texinfo::Convert::Info 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.

19 Texinfo::Convert::HTML
*************************

19.1 Texinfo::Convert::HTML NAME
================================

Texinfo::Convert::HTML - Convert Texinfo tree to HTML

19.2 Texinfo::Convert::HTML SYNOPSIS
====================================

  my $converter
    = Texinfo::Convert::HTML->converter({'NUMBER_SECTIONS' => 0});

  $converter->output($document);
  $converter->convert($document);
  $converter->convert_tree($tree);
  $converter->output_internal_links(); # HTML only

19.3 Texinfo::Convert::HTML NOTES
=================================

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.

19.4 Texinfo::Convert::HTML DESCRIPTION
=======================================

Texinfo::Convert::HTML converts a Texinfo tree to HTML.

19.5 Texinfo::Convert::HTML METHODS
===================================

$converter = Texinfo::Convert::HTML->converter($options)

     Initialize converter from Texinfo to HTML.

     The _$options_ hash reference holds Texinfo customization options
     for the converter.  These options should be Texinfo customization
     options that can be passed to the converter.  Most of the
     customization options are described in the Texinfo manual or in the
     customization API manual.  Those customization options, when
     appropriate, override the document content.

     See ^?TexinfoConvert::Converter^?: Texinfo::Convert::Converter
     NAME. for more information.

$converter->output($document)

     Convert a Texinfo parsed document _$document_ and output the result
     in files as described in the Texinfo manual.

$result = $converter->convert($document)

     Convert a Texinfo parsed document _$document_ and return the
     resulting output.

$result = $converter->convert_tree($tree)

     Convert a Texinfo tree portion _$tree_ and return the resulting
     output.  This function does not try to output a full document but
     only portions.  For a full document use ‘convert’.

     In general, this function should be called after the converter has
     been associated to a document by a call to ‘output’ or ‘convert’.

$result = $converter->output_internal_links()

     Returns text representing the links in the document.  The format
     should follow the ‘--internal-links’ option of the ‘texi2any’
     specification.  This is only supported in (and relevant for) HTML.

19.6 Texinfo::Convert::HTML AUTHOR
==================================

Patrice Dumas, <pertusus@free.fr>

19.7 Texinfo::Convert::HTML 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.

20 Texinfo::Convert::DocBook
****************************

20.1 Texinfo::Convert::DocBook NAME
===================================

Texinfo::Convert::DocBook - Convert Texinfo tree to DocBook

20.2 Texinfo::Convert::DocBook SYNOPSIS
=======================================

  my $converter
    = Texinfo::Convert::DocBook->converter({'NUMBER_SECTIONS' => 0});

  $converter->output($document);
  $converter->convert($document);
  $converter->convert_tree($tree);

20.3 Texinfo::Convert::DocBook NOTES
====================================

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.

20.4 Texinfo::Convert::DocBook DESCRIPTION
==========================================

Texinfo::Convert::DocBook converts a Texinfo tree to DocBook.

20.5 Texinfo::Convert::DocBook METHODS
======================================

$converter = Texinfo::Convert::DocBook->converter($options)

     Initialize converter from Texinfo to DocBook.

     The _$options_ hash reference holds Texinfo customization options
     for the converter.  These options should be Texinfo customization
     options that can be passed to the converter.  Most of the
     customization options are described in the Texinfo manual or in the
     customization API manual.  Those customization options, when
     appropriate, override the document content.

     See ^?TexinfoConvert::Converter^?: Texinfo::Convert::Converter
     NAME. for more information.

$converter->output($document)

     Convert a Texinfo parsed document _$document_ and output the result
     in files as described in the Texinfo manual.

$result = $converter->convert($document)

     Convert a Texinfo parsed document _$document_ and return the
     resulting output.

$result = $converter->convert_tree($tree)

     Convert a Texinfo tree portion _$tree_ and return the resulting
     output.  This function does not try to output a full document but
     only portions.  For a full document use ‘convert’.

     In general, this function should be called after the converter has
     been associated to a document by a call to ‘output’ or ‘convert’.

20.6 Texinfo::Convert::DocBook AUTHOR
=====================================

Patrice Dumas, <pertusus@free.fr>

20.7 Texinfo::Convert::DocBook 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.

21 Texinfo::Convert::TexinfoMarkup
**********************************

21.1 Texinfo::Convert::TexinfoMarkup NAME
=========================================

Texinfo::Convert::TexinfoMarkup - Convert Texinfo tree to element and
attribute markup

21.2 Texinfo::Convert::TexinfoMarkup SYNOPSIS
=============================================

  package Texinfo::Convert::TexinfoMyMarkup;

  use Texinfo::Convert::TexinfoMarkup;

  @ISA = qw(Texinfo::Convert::TexinfoMarkup);

  sub converter_defaults ($$) {
    return %myconverter_defaults;
  }

  sub txi_markup_protect_text($$)
  {
    my $self = shift;
    ....
  }

21.3 Texinfo::Convert::TexinfoMarkup NOTES
==========================================

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.

21.4 Texinfo::Convert::TexinfoMarkup DESCRIPTION
================================================

‘Texinfo::Convert::TexinfoMarkup’ converts a Texinfo tree to the Texinfo
Markup Language which is based on nested elements with attributes,
similar to XML. All the information present in the Texinfo tree, after
expansion of ‘@macro’, ‘@value’ and inclusion of include files is kept.
‘Texinfo::Convert::TexinfoMarkup’ is an abstract class, to be used as a
super class for modules implementing specific markup formatting
functions called by ‘Texinfo::Convert::TexinfoMarkup’.

   The Texinfo Markup Language elements and attributes are not
documented, but the Texinfo XML output by the
‘Texinfo::Convert::TexinfoXML’ subclass (see
^?TexinfoConvert::TexinfoXML^?: Texinfo::Convert::TexinfoXML NAME.) is a
straightforward formatting as XML, and is described by the Texinfo DTD.
Therefore the Texinfo DTD can be used as a description of the structure
of both Texinfo XML and of the more abstract Texinfo Markup Language.

21.5 Texinfo::Convert::TexinfoMarkup METHODS
============================================

21.5.1 Markup formatting methods defined by subclasses
------------------------------------------------------

The following methods should be implemented by the modules inheriting
from ‘Texinfo::Convert::TexinfoMarkup’:

$result = $converter->txi_markup_atom($atom)

     Format the _$atom_ symbol string in a simpler way than with an
     element.  For example in XML the formatting of the symbol is
     achieved with an entity.

$result = $converter->txi_markup_comment($comment_string)

     Format _$comment_string_ as a comment.

$result = $converter->txi_markup_convert_text($element)

     Called to format the Texinfo tree _$element_ text, which is a
     reference on a hash.  The _$element_ text is in the ‘text’ key.
     The ‘type’ key value may also be set to distinguish the type of
     text (see ^?TexinfoParser Types for text elements^?::).  Texinfo
     tree elements are described in details in ^?TexinfoParser
     TEXINFO TREE^?::.

$result = $converter->txi_markup_element($format_element, $attributes)

$result = $converter->txi_markup_open_element($format_element, $attributes)

$result = $converter->txi_markup_close_element($format_element, $attributes)

     ‘txi_markup_element’ is called for the formatting of empty
     elements.  Otherwise, ‘txi_markup_open_element’ is called when an
     element is opened, and ‘txi_markup_close_element’ is called when an
     element is closed.  _$format_element_ is the element name,
     _$attributes_ is a reference on an array containing references on
     arrays of pairs, one pair for each attribute, with the attribute
     name as the first item of the pair and the attribute text as the
     second item of the pair.

$result = $converter->txi_markup_header()

     Called to format a header at the beginning of output files.

$result = $converter->txi_markup_protect_text($string)

     Protect special character in text for text fragments out of text
     Texinfo tree elements.  For example, for spaces at end of line that
     are ignorable in most output formats, for ‘@set’ or ‘@macro’
     arguments.

21.5.2 Formatting state information
-----------------------------------

A method is available for subclasses to gather information on the
formatting state:

$converter->in_monospace()

     Return 1 if in a context where spacing should be kept and ‘---’ or
     ‘''’ left as is, for example in ‘@code’, ‘@example’.

21.6 Texinfo::Convert::TexinfoMarkup AUTHOR
===========================================

Patrice Dumas, <pertusus@free.fr>

21.7 Texinfo::Convert::TexinfoMarkup SEE ALSO
=============================================

^?TexinfoConvert::Converter^?: Texinfo::Convert::Converter NAME.
^?TexinfoConvert::TexinfoXML^?: Texinfo::Convert::TexinfoXML NAME.
The ‘Texinfo::Convert::TexinfoSXML’ is another subclass, which outputs
SXML. It is not much documented.

21.8 Texinfo::Convert::TexinfoMarkup 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.

22 Texinfo::Convert::TexinfoXML
*******************************

22.1 Texinfo::Convert::TexinfoXML NAME
======================================

Texinfo::Convert::TexinfoXML - Convert Texinfo tree to TexinfoXML

22.2 Texinfo::Convert::TexinfoXML SYNOPSIS
==========================================

  my $converter
    = Texinfo::Convert::TexinfoXML->converter({'NUMBER_SECTIONS' => 0});

  $converter->output($document);
  $converter->convert($document);
  $converter->convert_tree($tree);

22.3 Texinfo::Convert::TexinfoXML NOTES
=======================================

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.

22.4 Texinfo::Convert::TexinfoXML DESCRIPTION
=============================================

Texinfo::Convert::TexinfoXML converts a Texinfo tree to TexinfoXML.

22.5 Texinfo::Convert::TexinfoXML METHODS
=========================================

$converter = Texinfo::Convert::TexinfoXML->converter($options)

     Initialize converter from Texinfo to TexinfoXML.

     The _$options_ hash reference holds Texinfo customization options
     for the converter.  These options should be Texinfo customization
     options that can be passed to the converter.  Most of the
     customization options are described in the Texinfo manual or in the
     customization API manual.  Those customization options, when
     appropriate, override the document content.

     See ^?TexinfoConvert::Converter^?: Texinfo::Convert::Converter
     NAME. for more information.

$converter->output($document)

     Convert a Texinfo parsed document _$document_ and output the result
     in files as described in the Texinfo manual.

$result = $converter->convert($document)

     Convert a Texinfo parsed document _$document_ and return the
     resulting output.

$result = $converter->convert_tree($tree)

     Convert a Texinfo tree portion _$tree_ and return the resulting
     output.  This function does not try to output a full document but
     only portions.  For a full document use ‘convert’.

     In general, this function should be called after the converter has
     been associated to a document by a call to ‘output’ or ‘convert’.

22.6 Texinfo::Convert::TexinfoXML AUTHOR
========================================

Patrice Dumas, <pertusus@free.fr>

22.7 Texinfo::Convert::TexinfoXML 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.

23 Texinfo::Convert::Plaintext
******************************

23.1 Texinfo::Convert::Plaintext NAME
=====================================

Texinfo::Convert::Plaintext - Convert Texinfo tree to Plaintext

23.2 Texinfo::Convert::Plaintext SYNOPSIS
=========================================

  my $converter
    = Texinfo::Convert::Plaintext->converter({'NUMBER_SECTIONS' => 0});

  $converter->output($document);
  $converter->convert($document);
  $converter->convert_tree($tree);

23.3 Texinfo::Convert::Plaintext NOTES
======================================

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.

23.4 Texinfo::Convert::Plaintext DESCRIPTION
============================================

Texinfo::Convert::Plaintext converts a Texinfo tree to Plaintext.

23.5 Texinfo::Convert::Plaintext METHODS
========================================

$converter = Texinfo::Convert::Plaintext->converter($options)

     Initialize converter from Texinfo to Plaintext.

     The _$options_ hash reference holds Texinfo customization options
     for the converter.  These options should be Texinfo customization
     options that can be passed to the converter.  Most of the
     customization options are described in the Texinfo manual or in the
     customization API manual.  Those customization options, when
     appropriate, override the document content.

     See ^?TexinfoConvert::Converter^?: Texinfo::Convert::Converter
     NAME. for more information.

$converter->output($document)

     Convert a Texinfo parsed document _$document_ and output the result
     in files as described in the Texinfo manual.

$result = $converter->convert($document)

     Convert a Texinfo parsed document _$document_ and return the
     resulting output.

$result = $converter->convert_tree($tree)

     Convert a Texinfo tree portion _$tree_ and return the resulting
     output.  This function does not try to output a full document but
     only portions.  For a full document use ‘convert’.

     In general, this function should be called after the converter has
     been associated to a document by a call to ‘output’ or ‘convert’.

23.6 Texinfo::Convert::Plaintext AUTHOR
=======================================

Patrice Dumas, <pertusus@free.fr>

23.7 Texinfo::Convert::Plaintext 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.