Texinfo modules documentation 1 Texinfo::Commands 1.1 Texinfo::Commands NAME 1.2 Texinfo::Commands SYNOPSIS 1.3 Texinfo::Commands NOTES 1.4 Texinfo::Commands DESCRIPTION 1.5 @-COMMAND INFORMATION 1.6 @-COMMAND CLASSES 1.7 Texinfo::Commands SEE ALSO 1.8 Texinfo::Commands AUTHOR 1.9 Texinfo::Commands COPYRIGHT AND LICENSE 2 Texinfo::CommandsValues 2.1 Texinfo::CommandsValues NAME 2.2 Texinfo::CommandsValues SYNOPSIS 2.3 Texinfo::CommandsValues NOTES 2.4 Texinfo::CommandsValues DESCRIPTION 2.5 @-COMMAND ASSOCIATED INFORMATION 2.6 Texinfo::CommandsValues SEE ALSO 2.7 Texinfo::CommandsValues AUTHOR 2.8 Texinfo::CommandsValues COPYRIGHT AND LICENSE 3 Texinfo::Common 3.1 Texinfo::Common NAME 3.2 Texinfo::Common SYNOPSIS 3.3 Texinfo::Common NOTES 3.4 Texinfo::Common DESCRIPTION 3.5 MISC INFORMATION 3.6 @-COMMAND INFORMATION 3.7 Texinfo::Common METHODS 3.8 Texinfo::Common SEE ALSO 3.9 Texinfo::Common AUTHOR 3.10 Texinfo::Common COPYRIGHT AND LICENSE 4 Texinfo::Parser 4.1 Texinfo::Parser NAME 4.2 Texinfo::Parser SYNOPSIS 4.3 Texinfo::Parser NOTES 4.4 Texinfo::Parser DESCRIPTION 4.5 Texinfo::Parser METHODS 4.5.1 Initialization 4.5.2 Parsing Texinfo text 4.6 TEXINFO TREE 4.6.1 Texinfo tree structure 4.6.1.1 Root and first level elements 4.6.1.2 Line command tree element 4.6.1.3 Block command tree element 4.6.1.4 Paragraphs and preformatted 4.6.1.5 Brace commands 4.6.1.6 Texinfo line tree 4.6.1.7 Showing the tree structure 4.6.2 Element keys 4.6.3 Element types 4.6.3.1 Types for command and user-defined macro call elements 4.6.3.2 Types for text elements 4.6.3.3 Tree container elements 4.6.3.4 Types of container elements 4.6.4 Information available in the ‘info’ key 4.6.5 Information available in the ‘extra’ key 4.6.5.1 Extra keys available for more than one @-command 4.6.5.2 Extra keys specific of certain @-commands or containers 4.7 Texinfo::Parser SEE ALSO 4.8 Texinfo::Parser AUTHOR 4.9 Texinfo::Parser COPYRIGHT AND LICENSE 5 Texinfo::Document 5.1 Texinfo::Document NAME 5.2 Texinfo::Document SYNOPSIS 5.3 Texinfo::Document NOTES 5.4 Texinfo::Document DESCRIPTION 5.5 Texinfo::Document METHODS 5.5.1 Getting document information 5.5.2 Merging and sorting indexes 5.5.3 Getting errors and warnings 5.5.4 Getting customization options values registered in document 5.5.5 Registering information in document 5.5.6 Methods for Perl and C code interactions 5.6 Texinfo::Document SEE ALSO 5.7 Texinfo::Document AUTHOR 5.8 Texinfo::Document COPYRIGHT AND LICENSE 6 Texinfo::ManipulateTree 6.1 Texinfo::ManipulateTree NAME 6.2 Texinfo::ManipulateTree SYNOPSIS 6.3 Texinfo::ManipulateTree NOTES 6.4 Texinfo::ManipulateTree DESCRIPTION 6.5 Texinfo::ManipulateTree METHODS 6.6 Texinfo::ManipulateTree SEE ALSO 6.7 Texinfo::ManipulateTree AUTHOR 6.8 Texinfo::ManipulateTree COPYRIGHT AND LICENSE 7 Texinfo::Structuring 7.1 Texinfo::Structuring NAME 7.2 Texinfo::Structuring SYNOPSIS 7.3 Texinfo::Structuring NOTES 7.4 Texinfo::Structuring DESCRIPTION 7.5 Texinfo::Structuring METHODS 7.6 Texinfo::Structuring SEE ALSO 7.7 Texinfo::Structuring AUTHOR 7.8 Texinfo::Structuring COPYRIGHT AND LICENSE 8 Texinfo::Report 8.1 Texinfo::Report NAME 8.2 Texinfo::Report SYNOPSIS 8.3 Texinfo::Report NOTES 8.4 Texinfo::Report DESCRIPTION 8.5 Texinfo::Report METHODS 8.6 Texinfo::Report AUTHOR 8.7 Texinfo::Report COPYRIGHT AND LICENSE 9 Texinfo::Translations 9.1 Texinfo::Translations NAME 9.2 Texinfo::Translations SYNOPSIS 9.3 Texinfo::Translations NOTES 9.4 Texinfo::Translations DESCRIPTION 9.5 Texinfo::Translations METHODS 9.6 Texinfo::Translations SEE ALSO 9.7 Texinfo::Translations AUTHOR 9.8 Texinfo::Translations COPYRIGHT AND LICENSE 10 Texinfo::Transformations 10.1 Texinfo::Transformations NAME 10.2 Texinfo::Transformations NOTES 10.3 Texinfo::Transformations DESCRIPTION 10.4 Texinfo::Transformations METHODS 10.5 Texinfo::Transformations SEE ALSO 10.6 Texinfo::Transformations AUTHOR 10.7 Texinfo::Transformations COPYRIGHT AND LICENSE 11 Texinfo::Indices 11.1 Texinfo::Indices NAME 11.2 Texinfo::Indices SYNOPSIS 11.3 Texinfo::Indices NOTES 11.4 Texinfo::Indices DESCRIPTION 11.5 Texinfo::Indices METHODS 11.6 Texinfo::Indices SEE ALSO 11.7 Texinfo::Indices AUTHOR 11.8 Texinfo::Indices COPYRIGHT AND LICENSE 12 Texinfo::OutputUnits 12.1 Texinfo::OutputUnits NAME 12.2 Texinfo::OutputUnits SYNOPSIS 12.3 Texinfo::OutputUnits NOTES 12.4 Texinfo::OutputUnits DESCRIPTION 12.5 Texinfo::OutputUnits METHODS 12.5.1 Output units creation 12.5.2 Grouping output units in pages 12.5.3 Setting output units directions 12.6 Texinfo::OutputUnits SEE ALSO 12.7 Texinfo::OutputUnits AUTHOR 12.8 Texinfo::OutputUnits COPYRIGHT AND LICENSE 13 Texinfo::Convert::Texinfo 13.1 Texinfo::Convert::Texinfo NAME 13.2 Texinfo::Convert::Texinfo SYNOPSIS 13.3 Texinfo::Convert::Texinfo NOTES 13.4 Texinfo::Convert::Texinfo DESCRIPTION 13.5 Texinfo::Convert::Texinfo METHODS 13.6 Texinfo::Convert::Texinfo AUTHOR 13.7 Texinfo::Convert::Texinfo COPYRIGHT AND LICENSE 14 Texinfo::Convert::Utils 14.1 Texinfo::Convert::Utils NAME 14.2 Texinfo::Convert::Utils SYNOPSIS 14.3 Texinfo::Convert::Utils NOTES 14.4 Texinfo::Convert::Utils DESCRIPTION 14.5 Texinfo::Convert::Utils METHODS 14.6 Texinfo::Convert::Utils SEE ALSO 14.7 Texinfo::Convert::Utils AUTHOR 14.8 Texinfo::Convert::Utils COPYRIGHT AND LICENSE 15 Texinfo::Convert::Unicode 15.1 Texinfo::Convert::Unicode NAME 15.2 Texinfo::Convert::Unicode SYNOPSIS 15.3 Texinfo::Convert::Unicode NOTES 15.4 Texinfo::Convert::Unicode DESCRIPTION 15.5 Texinfo::Convert::Unicode METHODS 15.6 Texinfo::Convert::Unicode AUTHOR 15.7 Texinfo::Convert::Unicode COPYRIGHT AND LICENSE 16 Texinfo::Convert::NodeNameNormalization 16.1 Texinfo::Convert::NodeNameNormalization NAME 16.2 Texinfo::Convert::NodeNameNormalization SYNOPSIS 16.3 Texinfo::Convert::NodeNameNormalization NOTES 16.4 Texinfo::Convert::NodeNameNormalization DESCRIPTION 16.5 Texinfo::Convert::NodeNameNormalization METHODS 16.6 Texinfo::Convert::NodeNameNormalization AUTHOR 16.7 Texinfo::Convert::NodeNameNormalization COPYRIGHT AND LICENSE 17 Texinfo::Convert::Text 17.1 Texinfo::Convert::Text NAME 17.2 Texinfo::Convert::Text SYNOPSIS 17.3 Texinfo::Convert::Text NOTES 17.4 Texinfo::Convert::Text DESCRIPTION 17.5 Texinfo::Convert::Text METHODS 17.6 Texinfo::Convert::Text AUTHOR 17.7 Texinfo::Convert::Text COPYRIGHT AND LICENSE 18 Texinfo::Convert::Converter 18.1 Texinfo::Convert::Converter NAME 18.2 Texinfo::Convert::Converter SYNOPSIS 18.3 Texinfo::Convert::Converter NOTES 18.4 Texinfo::Convert::Converter DESCRIPTION 18.5 Texinfo::Convert::Converter METHODS 18.5.1 Converter Initialization 18.5.2 Conversion 18.5.3 Output units and converter destruction 18.5.4 Getting and setting customization variables 18.5.5 Registering error and warning messages 18.5.6 Translations in output documents 18.5.7 Index sorting 18.5.8 Accents conversion 18.5.9 Conversion to XML 18.5.10 Helper methods 18.6 Texinfo::Convert::Converter SEE ALSO 18.7 Texinfo::Convert::Converter AUTHOR 18.8 Texinfo::Convert::Converter COPYRIGHT AND LICENSE 19 Texinfo::Convert::Info 19.1 Texinfo::Convert::Info NAME 19.2 Texinfo::Convert::Info SYNOPSIS 19.3 Texinfo::Convert::Info NOTES 19.4 Texinfo::Convert::Info DESCRIPTION 19.5 Texinfo::Convert::Info METHODS 19.6 Texinfo::Convert::Info AUTHOR 19.7 Texinfo::Convert::Info COPYRIGHT AND LICENSE 20 Texinfo::Convert::HTML 20.1 Texinfo::Convert::HTML NAME 20.2 Texinfo::Convert::HTML SYNOPSIS 20.3 Texinfo::Convert::HTML NOTES 20.4 Texinfo::Convert::HTML DESCRIPTION 20.5 Texinfo::Convert::HTML METHODS 20.6 Texinfo::Convert::HTML AUTHOR 20.7 Texinfo::Convert::HTML COPYRIGHT AND LICENSE 21 Texinfo::Convert::DocBook 21.1 Texinfo::Convert::DocBook NAME 21.2 Texinfo::Convert::DocBook SYNOPSIS 21.3 Texinfo::Convert::DocBook NOTES 21.4 Texinfo::Convert::DocBook DESCRIPTION 21.5 Texinfo::Convert::DocBook METHODS 21.6 Texinfo::Convert::DocBook AUTHOR 21.7 Texinfo::Convert::DocBook COPYRIGHT AND LICENSE 22 Texinfo::Convert::TexinfoMarkup 22.1 Texinfo::Convert::TexinfoMarkup NAME 22.2 Texinfo::Convert::TexinfoMarkup SYNOPSIS 22.3 Texinfo::Convert::TexinfoMarkup NOTES 22.4 Texinfo::Convert::TexinfoMarkup DESCRIPTION 22.5 Texinfo::Convert::TexinfoMarkup METHODS 22.5.1 Markup formatting methods defined by subclasses 22.5.2 Formatting state information 22.6 Texinfo::Convert::TexinfoMarkup AUTHOR 22.7 Texinfo::Convert::TexinfoMarkup SEE ALSO 22.8 Texinfo::Convert::TexinfoMarkup COPYRIGHT AND LICENSE 23 Texinfo::Convert::TexinfoXML 23.1 Texinfo::Convert::TexinfoXML NAME 23.2 Texinfo::Convert::TexinfoXML SYNOPSIS 23.3 Texinfo::Convert::TexinfoXML NOTES 23.4 Texinfo::Convert::TexinfoXML DESCRIPTION 23.5 Texinfo::Convert::TexinfoXML METHODS 23.6 Texinfo::Convert::TexinfoXML AUTHOR 23.7 Texinfo::Convert::TexinfoXML COPYRIGHT AND LICENSE 24 Texinfo::Convert::Plaintext 24.1 Texinfo::Convert::Plaintext NAME 24.2 Texinfo::Convert::Plaintext SYNOPSIS 24.3 Texinfo::Convert::Plaintext NOTES 24.4 Texinfo::Convert::Plaintext DESCRIPTION 24.5 Texinfo::Convert::Plaintext METHODS 24.6 Texinfo::Convert::Plaintext AUTHOR 24.7 Texinfo::Convert::Plaintext COPYRIGHT AND LICENSE 25 Texinfo::TreeElement 25.1 Texinfo::TreeElement NAME 25.2 Texinfo::TreeElement SYNOPSIS 25.3 Texinfo::TreeElement NOTES 25.4 Texinfo::TreeElement DESCRIPTION 25.5 Texinfo::TreeElement METHODS 25.5.1 ‘Texinfo::TreeElement’ and XS extensions 25.6 Texinfo::TreeElement SEE ALSO 25.7 Texinfo::TreeElement AUTHOR 25.8 Texinfo::TreeElement COPYRIGHT AND LICENSE 26 Texinfo::Reader 26.1 Texinfo::Reader NAME 26.2 Texinfo::Reader SYNOPSIS 26.3 Texinfo::Reader NOTES 26.4 Texinfo::Reader DESCRIPTION 26.5 Texinfo::Reader METHODS 26.5.1 ‘Texinfo::Reader’ and XS extensions 26.6 Texinfo::Reader SEE ALSO 26.7 Texinfo::Reader AUTHOR 26.8 Texinfo::Reader COPYRIGHT AND LICENSE 27 Texinfo::Example::TreeElementConverter 27.1 Texinfo::Example::TreeElementConverter NAME 27.2 Texinfo::Example::TreeElementConverter SYNOPSIS 27.3 Texinfo::Example::TreeElementConverter NOTES 27.4 Texinfo::Example::TreeElementConverter DESCRIPTION 27.5 Texinfo::Example::TreeElementConverter METHODS 27.5.1 Related methods from other modules 27.6 Texinfo::Example::TreeElementConverter SEE ALSO 27.7 Texinfo::Example::TreeElementConverter AUTHOR 27.8 Texinfo::Example::TreeElementConverter COPYRIGHT AND LICENSE Appendix A Index 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 ‘Texinfo::Document::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 ============================== Texinfo::Parser: Texinfo::Parser NAME. 1.8 Texinfo::Commands AUTHOR ============================ Patrice Dumas, 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::CommandsValues ************************* 2.1 Texinfo::CommandsValues NAME ================================ Texinfo::CommandsValues - Associations of information to Texinfo @-commands 2.2 Texinfo::CommandsValues SYNOPSIS ==================================== use Texinfo::CommandsValues; my $command_text = $Texinfo::CommandsValues::nobrace_symbol_text{'@'}; 2.3 Texinfo::CommandsValues 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::CommandsValues DESCRIPTION ======================================= Texinfo::CommandsValues holds hashes with information on @-commands. Only hashes relevant for conversion of @-commands are documented. 2.5 @-COMMAND ASSOCIATED INFORMATION ==================================== Hashes are defined as ‘our’ variables, and are therefore available outside of the module. %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. %text_brace_no_arg_commands Values are ASCII representation of commands with empty braces such as ‘atchar’, ‘LaTeX’, ‘arrow’, ‘quoteleft’ or ‘AA’. %unicode_diacritics Keys are Texinfo accent commands, such as ‘'’ or ‘ogonek’. Values are strings of hexadecimal numbers representing the Unicode codepoint of the diacritic associated to the accent command. A diacritic is a zero-length character that should be combined with adjacent characters to have the whole interpreted as an accented character. 2.6 Texinfo::CommandsValues SEE ALSO ==================================== Texinfo::Commands: Texinfo::Commands NAME. Texinfo::Convert::Unicode: Texinfo::Convert::Unicode NAME. 2.7 Texinfo::CommandsValues AUTHOR ================================== Patrice Dumas, 2.8 Texinfo::CommandsValues 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::Common ***************** 3.1 Texinfo::Common NAME ======================== Texinfo::Common - Texinfo modules common data and miscellaneous methods 3.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'); 3.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. 3.4 Texinfo::Common DESCRIPTION =============================== Texinfo::Common holds hashes with miscellaneous information and some hashes with information on Texinfo @-commands, as well as miscellaneous methods. 3.5 MISC INFORMATION ==================== 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. Hashes are defined as ‘our’ variables, and are therefore available outside of the module. %document_settable_at_commands Keys are customization options corresponding to @-commands. For example ‘frenchspacing’ or ‘footnotestyle’. %null_device_file Keys are null devices names, such as ‘/dev/null’ or ‘NUL’. %texinfo_output_formats Cannonical output formats that have associated conditionals. In practice corresponds to ‘format_raw’ ‘%block_commands’ plus ‘info’ and ‘plaintext’. 3.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. %small_block_associated_command Associate small command like ‘smallexample’ to the regular command ‘example’. 3.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 Texinfo::Parser 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 Texinfo::Convert::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 Texinfo::Translations: 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 = 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’. ($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’. $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. $encoding = input_file_name_encoding($name_encoding, $doc_encoding_for_input_file_name, $locale_encoding, $document, $input_file_encoding) Returns the encoding assumed for input file names. _$name_encoding_ is used as encoding name if defined. If _$doc_encoding_for_input_file_name_ is set, the encoding is based on the input file content encoding, otherwise _$locale_encoding_ is used. The _$document_ argument is an optional Texinfo parsed document used to get the input document content encoding. The _$input_file_encoding_ argument is optional, it will be used in priority if the the encoding is based on the input file encoding. If _$input_file_encoding_ is not given, it is recommended to pass _$document_, otherwise there is no way to determine the input document content encoding. $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_: Texinfo::Parser index_entry associated to an element. The _$index_entry_ hash is described in Texinfo::Document index_entries. The _$index_info_ hash is described in ‘Texinfo::Document::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 = replace_remove_list_element($array, $element, $replacement) Remove first occurence of _$element_ in the array reference _$array_. If the optional _$replacement_ argument is given, replace the _$element_ by _$replacement_. 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(): Texinfo::Document $commands = global_commands_information($document). _$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. $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 the argument line element 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. 3.8 Texinfo::Common SEE ALSO ============================ Texinfo::Parser: Texinfo::Parser NAME, Texinfo::Convert::Converter: Texinfo::Convert::Converter NAME and Texinfo::Report: Texinfo::Report NAME. 3.9 Texinfo::Common AUTHOR ========================== Patrice Dumas, 3.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. 4 Texinfo::Parser ***************** 4.1 Texinfo::Parser NAME ======================== Texinfo::Parser - Parse Texinfo code into a Perl tree 4.2 Texinfo::Parser SYNOPSIS ============================ use Texinfo::Parser; my $parser = Texinfo::Parser::parser(); my $document = $parser->parse_texi_file("somefile.texi"); my $errors = $document->parser_errors(); foreach my $error_message (@$errors) { warn $error_message->{'error_line'}; } 4.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. 4.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 number of columns in a multitable, or the node associated with a section. 4.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. 4.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’, ‘menu_no_detailmenu’ and ‘sectiontoc’. Only report menu-related errors for ‘menu’ and ‘menu_no_detailmenu’. 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’. 4.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’. $error_warnings_list = $document->parser_errors() This function returns the _$error_warnings_list_ as an array of hash references one for each error, warning or error line continuation. They are described in detail in Texinfo::Report::count_errors: Texinfo::Report $error_count = count_errors ($error_messages). 4.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 ‘contents’ key holds an array reference for the children of @-command tree elements and containers. In particular for arguments of an @-command, either in braces or on the rest of the line after the command, depending on the type of command. Also for content appearing within a block @-command, within a container, or within a ‘@node’ or sectioning @-command. Text fragments do not have children. The ‘extra’ and ‘info’ keys are associated to hash references and hold information gathered during the parsing. 4.6.1 Texinfo tree structure ---------------------------- 4.6.1.1 Root and first level elements ..................................... A full Texinfo tree is rooted at a _document_root_ type element. _document_root_ first element in ‘contents’ should be a _before_node_section_ container for content appearing before the first node or sectioning command. Nodes and sections @-commands elements follow. The node or sectioning command elements ‘contents’ hold all the elements corresponding to Texinfo code before the next node or sectioning command element or ‘@bye’. If present in the Texinfo document, the ‘@bye’ element is next. If there is content after ‘@bye’, it is last in the _postamble_after_end_ container element. The content of _before_node_section_ depend on the presence of ‘@setfilename’ in the document before the first node or sectioning element: with ‘@setfilename’ The first container in _before_node_section_ is _preamble_before_setfilename_. The first element in _preamble_before_setfilename_ is _preamble_before_beginning_, which holds everything appearing before the first content, including the \input texinfo.tex line and following blank lines. It may be followed by paragraphs and block commands elements, if any, although it is not recommended to have such content before ‘@setfilename’. The second container in _before_node_section_ is _preamble_before_content_, which begins with ‘@setfilename’ and contains everything appearing before the first formatted content, corresponding to the _preamble_ in the Texinfo documentation. The paragraphs and other contents follow up in _before_node_section_ ‘contents’ until the first node or section. without ‘@setfilename’ The first container in _before_node_section_ is _preamble_before_beginning_, which holds everything appearing before the first content, including the \input texinfo.tex line and following blank lines. It is followed by _preamble_before_content_, which contains everything appearing before the first formatted content, corresponding to the _preamble_ in the Texinfo documentation. The paragraphs and other contents follow up in _before_node_section_ ‘contents’ until the first node or section. _preamble_before_content_ contains empty lines text elements, elements corresponding to line commands such as ‘@documentlanguage’ or ‘@frenchspacing’, block commands such as ‘@copying’ that are not immediately output but also raw output block commands such as ‘@html’. The first element of a node or sectioning command ‘contents’ is an _arguments_line_ container holding the command arguments appearing on the @-command line. The _arguments_line_ in turn contains _line_arg_ containers for each of the node arguments separated by commas, or the unique sectioning command argument. The node or sectioning command contents follow, including paragraphs, empty line text elements, all kind of block commands and line commands such as ‘@center’ or index commands such as ‘@cindex’ as well as ‘@image’ command elements out of paragraphs. 4.6.1.2 Line command tree element ................................. There are three main types of line commands, regular line commands, _lineraw_ line commands and definition line commands. All the line commands hold _line_arg_ containers for their arguments. _lineraw_ line commands _lineraw_ line commands arguments are not subject to the usual macro expansion. _lineraw_ line commands with arguments are, for example, ‘@set’, ‘@unmacro’ and ‘@comment’. ‘@raisesections’, ‘@contents’ and ‘@novalidate’ are examples of _lineraw_ line commands without arguments. They only have one _line_arg_ container, which should only contain one _rawline_text_ text element. regular line commands Most line commands with arguments that are not node or sectioning commands are regular line commands. Regular line command ‘contents’ holds _line_arg_ containers for each of the line arguments separated by commas. _line_arg_ containers contain in turn text elements, elements of @-commands without arguments, with empty braces, such as ‘@equiv’ and with braces such as ‘@code’ or ‘@ref’. definition line commands Definition line commands elements are elements associated to commands like ‘@deffnx’ or ‘@defline’. They contain a _line_arg_ container, which, in turn contains the specific definition line containers such as _def_category_, _def_arg_ and some special text elements such as _space_. 4.6.1.3 Block command tree element .................................. The first element of block command ‘contents’ is an _arguments_line_ container holding the command arguments appearing on the @-command line, similar to node and sectioning command elements. The _arguments_line_ holds _block_line_arg_ containers for each of the arguments separated by commas, similar to line commands. Definition block commands such as ‘@deffn’ do not follow the same rule and do not have an _arguments_line_ container. ‘@defblock’ command element, however, is like regular block commands, with an _arguments_line_ container as first ‘contents’ element. The remaining elements in ‘contents’ depend on the block command. Block commands like ‘@float’, ‘@quotation’ or ‘@flushleft’ remaining ‘contents’ are paragraphs, empty line text elements, line commands and nested block commands, much like node and sectioning elements, appearing before the matching ‘@end’ commmand element. Block commands like ‘@example’ or ‘@display’ are similar except that they contain _preformatted_ containers instead of paragraphs and so do other block commands nested in those @-commands. Other block commands contain specific containers depending on the block command. Block commands with ‘@item’ may contain a _before_item_ container for contents before the first ‘@item’. ‘@itemize’ and ‘@enumerate’ block commands following contents are ‘@item’ commands holding the Texinfo code elements until the next ‘@item’ or ‘@end’. ‘@table’ and similar block commands elements in ‘contents’ are _table_entry_ containers for each table line, that contain themselves specific containers. ‘@multitable’ contains _multitable_head_ and _multitable_body_ containers. ‘@menu’ ‘contents’ hold _menu_entry_ and _menu_comments_ container elements. The definition commands such as ‘@deffn’ contain a _def_line_ container as first ‘contents’, may contain an _inter_def_item_ container, also contains ‘@deffnx’ line commands, and ends with a _def_item_ container for the main contents of the definition command. The ‘@defblock’ commands ‘contents’ may hold a _before_defline_ element after the line arguments, also contains line @-commands such as ‘@defline’ and a _def_item_ container. The _def_line_ container contains a _block_line_arg_ container, which, in turn contains the specific definition line containers such as _def_category_, _def_arg_ and some special text elements such as _space_. Raw block commands such as ‘@verbatim’, ‘@ignore’ or ‘@macro’ contain directly _raw_ text elements. Lastly, raw output commands such as ‘@html’ element in ‘contents’ after the _arguments_line_ is either an _elided_rawpreformatted_ element container containing _raw_ text elements if ignored, or a _rawpreformatted_ container containing directly text and @-command elements if output. The ‘@end’ command element is a regular line command element and is the last element of all the block commands ‘contents’. 4.6.1.4 Paragraphs and preformatted ................................... _paragraph_ and _preformatted_ container ‘contents’ are text elements, elements of @-commands without arguments, such as ‘@}’, with empty braces, such as ‘@equiv’ and with braces such as ‘@code’ or ‘@ref’. They may also contain elements corresponding to the few line commands that do not stop a paragraph, such as index command elements. _preformatted_ container may contain empty line text elements, while _paragraph_ containers do not. 4.6.1.5 Brace commands ...................... ‘@footnote’ and ‘@caption’ @-command elements that start a new context and contain paragraphs and block commands contain a _brace_command_context_ container. The _brace_command_context_ container contains _paragraph_, line command and block command elements, much like node, sectioning and block command elements. ‘@math’ also contains a _brace_command_context_ container, which contains directly text and brace commands more similar to the _preformatted_ container. For commands taking arguments surrounded by braces when the whole text in the braces is in the argument, such as ‘@u’ or ‘@code’ the first and only ‘contents’ element is a _brace_container_. Other brace commands, in particular brace commands with arguments separated by commas contain _brace_arg_ containers, one for each of the arguments. The _brace_container_ and _brace_arg_ containers contain directly text elements some @-commands without arguments and other @-commands with braces, similar to _line_arg_ or _paragraph_ containers. 4.6.1.6 Texinfo line tree ......................... When parsing Texinfo line fragments using ‘parse_texi_line’, a _root_line_ type element is the root element. It should typically contain elements that appear in _paragraph_, _preformatted_ or containers like _line_arg_. 4.6.1.7 Showing the tree structure .................................. 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 4.6.2 Element keys ------------------ cmdname The command name of @-command and user-defined macro call 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. contents An array reference holding the list of children of the element. parent The parent element. Not set for text elements. 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: Texinfo::Parser 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: Texinfo::Parser Information available in the extra key. 4.6.3 Element types ------------------- 4.6.3.1 Types for command and user-defined macro call 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 and user-defined macro call elements. 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'}’. 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. macro_call macro_call_line rmacro_call rmacro_call_line linemacro_call Container holding the arguments of user-defined macro, linemacro or rmacro. It should not appear directly in the tree as the user defined call is expanded. The _macro_call_line_ or _rmacro_call_line_ elements are used when there are no braces and the whole line is the argument. 4.6.3.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’. ignorable_spaces_before_command Spaces appearing before an @-command that are ignorable. For example spaces appearing before a ‘@subentry’ on an index command line. bracketed_linemacro_arg Text of the argument of a user defined linemacro call in bracket. It does not contain the braces. It should not appear directly in the tree as the user defined linemacro call is replaced by the linemacro body. macro_call_arg_text Macro call arguments texts. Linemacro call arguments when the arguments are not bracketed. These elements should not appear directly in the tree, as the macro calls are replaced by the expansion of the macro bodies. macro_line Text appearing on a ‘@macro’, ‘@linemacro’ or ‘@rmacro’ line after the @-command, including the leading space and the newline. In the _arguments_line_ container @-command. other_text Text elements that are not in the Texinfo tree elements. It could be part of informative out of tree elements, added for separators or used for other specific purposes. 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_after_argument text Spaces after @-command arguments before a comma, a closing brace or at end of line. Not directly in the tree. spaces_after_cmd_before_arg text Spaces following an @-command before that argument (for accent commands) or before the opening brace. Not directly in the tree. spaces_before_argument text 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. Not directly in the tree. 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_text Used for the text in arguments to some special line commands whose arguments aren't subject to the usual macro expansion. For example ‘@set’, ‘@unmacro’, ‘@comment’. spaces_at_end Space within an index @-command before an @-command interrupting the index command, when there are only spaces after the interrupting @-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". 4.6.3.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. 4.6.3.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 ‘contents’ 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’, or for ‘@node’, ‘@section’ _arguments_line_ container. _block_line_arg_ is similar but is used for _arguments_line_ container of 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', 'contents' => [{'type' => 'brace_container', 'contents' => [{'text' => 'in code'}]}]} bracketed_arg Bracketed argument. On definition command and on ‘@multitable’ line. 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. 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_. 4.6.4 Information available in the ‘info’ key --------------------------------------------- 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. 4.6.5 Information available in the ‘extra’ key ---------------------------------------------- 4.6.5.1 Extra keys available for more than one @-command ........................................................ input_encoding_name Normalized argument of ‘@documentencoding’. For ‘@documentencoding’ itself, and also for @-command arguments that name a file, which could make use of the document encoding at the localtion they are defined. element_node The node element identifier in the parsed tree containing the element. Set for @-commands elements that have an associated index entry. 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 ‘Texinfo::Common::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 ‘Texinfo::Document::indices_information’: Texinfo::Document $indices_information = $document->indices_information(). The index entry information hash returned by ‘Texinfo::Common::lookup_index_entry’ is described in Texinfo::Document 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’. 4.6.5.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. ‘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’. ‘@float’ ‘@listoffloats’ If ‘@float’ has a first argument, and for ‘@listoffloats’ argument there is a _float_type_ key with the normalized float type. 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. ‘@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. ‘@table’ ‘@vtable’ ‘@ftable’ 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’ _macro_name_ holds the macro name. _invalid_syntax_ is set if there was an error on the ‘@macro’ line. ‘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. ‘@node’ Node name and explicit directions labels information are available as _line_arg_ tree element arguments of the ‘@node’ line. 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. 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. ‘@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 If the level of the document was modified by ‘@raisections’ or ‘@lowersections’, the differential level is in _level_modifier_. The section level, taking into account ‘@raisections’ and ‘@lowersections’ is in _section_level_. Level 0 corresponds to ‘@top’ or ‘@part’ and level 1 to ‘@chapter’. The sectioning command formatted number is in _section_heading_number_. This information is only present if the sectioning structure has been determined by ‘Texinfo::Structuring::sectioning_structure’: Texinfo::Structuring sectioning_structure($document). ‘untranslated_def_line_arg’ _documentlanguage_ holds the ‘@documentlanguage’ value. If there is a translation context, it should be in _translation_context_. 4.7 Texinfo::Parser SEE ALSO ============================ Texinfo manual (https://www.gnu.org/software/texinfo/manual/texinfo/). 4.8 Texinfo::Parser AUTHOR ========================== Patrice Dumas, 4.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. 5 Texinfo::Document ******************* 5.1 Texinfo::Document NAME ========================== Texinfo::Document - Texinfo document tree and information 5.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 = $document->internal_references_information(); # $identifier_target is an hash reference on normalized # node/float/anchor/namedanchor names. my $identifier_target = $document->labels_information(); # A hash reference, keys are @-command names, value is the # corresponding @-commands tree element or 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(); 5.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. 5.4 Texinfo::Document DESCRIPTION ================================= This module is used to represent parsed Texinfo documents, with the Texinfo tree and associated information. A document is always obtained from a Texinfo parser method call as the result of parsing a Texinfo text or file. For example, the _$document_ obtained in the following example is a ‘Texinfo::Document’ object: my $parser = Texinfo::Parser::parser(); my $document = $parser->parse_texi_file("somefile.texi"); 5.5 Texinfo::Document METHODS ============================= 5.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 Texinfo::Parser 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 elements. This avoids building the Perl tree if all the functions called with the tree as argument have XS interfaces, directly use the C data and do not need 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’). If the global information changed, ‘global_information’ should be called to update the hash returned by previous calls before accessing the hash again. 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. For @-commands that may appear multiple time in the Texinfo document, the associated values are array references containing all the corresponding tree elements. For @-commands that should appear only once, the associated value is the tree element. 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’, ‘@namedanchor’ 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 a list of array references, one per float of that type. The first item of the float array reference is the float tree element. The second item of the float array reference is the section relations information of the section containing the float. Internal references, nodes and section information 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_relations_list = nodes_list($document) Returns an array reference containing each node relations information. $sections_relations_list = sections_list($document) Returns an array reference containing each section relations information. $sectioning_root = sectioning_root($document) Return the sectioning root information. It is an hash reference with the _section_children_ key, an array reference of the top level sectioning commands relations. Information about defined indexes, indexes 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. 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 indexes. 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 a partial view of _$indices_information_ corresponding to the default indexes _cp_ and _fn_, the _fn_ index having its entries formatted as code and the indexes corresponding to the following texinfo @defindex some @defcodeindex code $index_names = {'cp' => {'name' => 'cp', 'in_code' => 0, }, 'fn' => {'name' => 'fn', 'in_code' => 1, }, 'some' => {'name' => 'some', 'in_code' => 0}, 'code' => {'name' => 'code', 'in_code' => 1}}; 5.5.2 Merging and sorting indexes --------------------------------- Merged and sorted document indexes are also available. Parsed indexes are not merged nor sorted, Texinfo::Indices: Texinfo::Indices NAME functions are called to merge or sort the indexes the first time the following methods are called. The results are afterwards associated to the document and simply returned. $merged_indices = $document->merged_indices() Merge indexes if needed and return merged indexes. 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: Texinfo::Document index_entries. ‘Texinfo::Indices::merge_indices’: Texinfo::Indices $merged_indices = merge_indices($indices_information) is used to merge the indexes. It is not useful to call this function directly if indexes are sorted, as it is already called by index sorting functions. In general, the sorting methods should not be called directly, instead Texinfo::Convert::Converter Index sorting Converter methods should be used, which already call the following functions. $sorted_indices = sorted_indices_by_index($document, $converter, $use_unicode_collation, $locale_lang) $sorted_indices = sorted_indices_by_letter($document, $converter, $use_unicode_collation, $locale_lang) ‘sorted_indices_by_letter’ returns the indices sorted by index and letter, while ‘sorted_indices_by_index’ returns the indexes with all entries of an index together. By default, indexes 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 _$converter_ argument is used for error reporting, if not defined, the _$document_ is used. ‘Texinfo::Indices::sort_indices_by_index’: Texinfo::Indices $index_entries_sorted = sort_indices_by_index($document, $converter, $use_unicode_collation, $locale_lang) and ‘Texinfo::Indices::sort_indices_by_letter’: Texinfo::Indices $index_entries_sorted = sort_indices_by_letter($document, $converter, $use_unicode_collation, $locale_lang) are used to sort the indexes, if needed. In general, those methods should not be called directly, instead ‘Texinfo::Convert::Converter::get_converter_indices_sorted_by_index’: Texinfo::Convert::Converter $sorted_indices = $converter->get_converter_indices_sorted_by_index() and ‘Texinfo::Convert::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’. 5.5.3 Getting errors and warnings --------------------------------- A document has a list of error and warning messages 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. $error_warnings_list = errors($document) This function returns as the 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 Texinfo::Report::count_errors: Texinfo::Report $error_count = count_errors ($error_messages). 5.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’. 5.5.5 Registering information in document ----------------------------------------- Some information can be registered in the document. 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’: Texinfo::Document $value = $document->get_conf($variable_name)). The options should in general be registered before the calls to ‘get_conf’. 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: Texinfo::Document $info = global_information($document). The method should in general be called before the calls to ‘global_information’. 5.5.6 Methods for Perl and C code interactions ---------------------------------------------- The parsing of Texinfo code, structuring and transformations of the document and tree called through Texinfo Perl modules may be done by pure Perl modules or by Perl XS extensions in native code (written in C). In general, it makes no difference whether pure Perl or C code is used. When the document and tree are modified through native code based on C code, the Perl data are automatically rebuilt when calling the accessors described previously. In some cases, however, specific functions need to be called to pass information from C data to Perl or perform actions related to C data. When the tree is directly accessed in Perl (not through a document) but is modified by C code, when the Perl tree holds only a reference to C data, but no Perl data, or when you want to update all the Perl data before doing changes in Perl only, you can build the Perl data from the C data with ‘build_tree’: $perl_tree = build_tree($tree, $no_store) Return a _$perl_tree_, built from C data. If there is no Perl extensions in C, the tree is returned as is. The tree built is based on the Texinfo parsed document data associated to the Texinfo tree _$tree_. If the optional _$no_store_ argument is set, remove the C data. It may be useful if you call functions that modify the Perl tree only, and not the C data, followed by functions call that output the result and uses the C data if present. Removing the C data makes sure that the output is not based on unmodified C data, but on the modified Perl 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 ‘build_tree’ should mainly be called when there is no document associated to a tree and ‘$document->tree()’ cannot be called to rebuild the tree, or with the _$no_store_ argument, if you want to remove the link with C data. Some methods allow to release the memory held by C data associated to a Texinfo parsed document: destroy_document($document) Release the C data corresponding to _$document_. 5.6 Texinfo::Document SEE ALSO ============================== Texinfo::Parser: Texinfo::Parser NAME. Texinfo::Structuring: Texinfo::Structuring NAME. 5.7 Texinfo::Document AUTHOR ============================ Patrice Dumas, 5.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. 6 Texinfo::ManipulateTree ************************* 6.1 Texinfo::ManipulateTree NAME ================================ Texinfo::ManipulateTree - Texinfo modules common tree manipulation functions 6.2 Texinfo::ManipulateTree SYNOPSIS ==================================== use Texinfo::ManipulateTree; 6.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. 6.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 Texinfo::Transformations: Texinfo::Transformations NAME. 6.5 Texinfo::ManipulateTree METHODS =================================== The Texinfo tree and Texinfo tree elements used in argument of some functions are documented in Texinfo::Parser TEXINFO TREE. When customization information is needed, an object that defines ‘get_conf’ is expected, normally a Texinfo::Document Getting customization options values registered in document object. move_index_entries_after_items_in_document($document) In ‘@enumerate’ and ‘@itemize’ from the _$document_ 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_document($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’. 6.6 Texinfo::ManipulateTree SEE ALSO ==================================== Texinfo::Document: Texinfo::Document NAME, Texinfo::Structuring: Texinfo::Structuring NAME, Texinfo::Transformations: Texinfo::Transformations NAME. 6.7 Texinfo::ManipulateTree AUTHOR ================================== Patrice Dumas, 6.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. 7 Texinfo::Structuring ********************** 7.1 Texinfo::Structuring NAME ============================= Texinfo::Structuring - information on Texinfo::Document document structure 7.2 Texinfo::Structuring SYNOPSIS ================================= use Texinfo::Structuring qw(sectioning_structure construct_nodes_tree number_floats associate_internal_references); # $document is a parsed Texinfo::Document document. # When customization variables information is needed, it is obtained # from the $document by calling the get_conf() method. sectioning_structure($document); construct_nodes_tree($document); check_node_tree_menu_structure($document); complete_node_tree_with_menus($document); check_nodes_are_referenced($document); associate_internal_references($document); number_floats($document->floats_information()); 7.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. 7.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 node tree is analysed with ‘construct_nodes_tree’. Structural checking and warning on the consistency of menus and sectioning structure is done by ‘check_node_tree_menu_structure’. Nodes directions are completed with menu directions with ‘complete_node_tree_with_menus’. Floats get their standard numbering with ‘number_floats’ and internal references are matched up with nodes, floats or anchors with ‘associate_internal_references’. 7.5 Texinfo::Structuring METHODS ================================ No method is exported in the default case. Most methods use the error messages list from a parsed document for error reporting. Most also require Texinfo customization variables information, which means an object implementing the ‘get_conf’ method, in general a parsed document with registered customization, or, sometime, a converter (Texinfo::Convert::Converter Getting and setting customization variables). Other common data needed such as target elements associated to identifiers or refs are obtained from a parsed document, see Texinfo::Document: 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 corresponding autogenerated node directions set. complete_node_tree_with_menus($document) Complete nodes directions with menu directions and _Top_ node first node directions. check_node_tree_menu_structure($document) Check consistency of menus, sectioning and nodes directions. @children_nodes = get_node_node_childs_from_sectioning($node_relations) Find the _$node_relations_ node relations children based on the sectioning structure. For the node associated with ‘@top’ sectioning command, the sections associated with parts are considered. 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_relations, $lang_translations, $debug_level, $use_sections) Returns a ‘@menu’ Texinfo tree element for the node relations _$node_relations_, pointing to the children of the node obtained with the sectioning structure. If _$use_sections_ is set, use section names for the menu entry names. The _$lang_translations_ argument should be an array reference with one or two elements. The first element of the array is the language used for translations. The second element, if set, should be an hash reference holding translations already done. _$debug_level_ is an optional debugging level similar to the ‘DEBUG’ customization variable. If set, it is supplied to the function called for translations. Translations are only needed when generating the top node menu. $detailmenu = new_detailmenu($lang_translations, $converter, $document, $identifier_target, $nodes_list, $debug, $menus) Returns a detailmenu tree element formatted as a master node. _$menus_ is an array reference containing the regular menus of the Top node. _$lang_translations_ argument should be an array reference with one or two elements. The first element of the array is the language used for translations. The second element, if set, should be an hash reference holding translations already done. If _$debug_ optional arguments is set, debugging mode is assumed. _$converter_ should hold information needed for translations and error reporting. _$identifier_target_ should hold information on cross-reference target commands, typically obtained by calling ‘Texinfo::Document::labels_information’: Texinfo::Document $identifier_target = labels_information($document). _$nodes_list_ should be the list of nores relations information, typically obtained by calling ‘Texinfo::Document::nodes_list’: Texinfo::Document $nodes_relations_list = nodes_list($document). _$converter_, if set, is used for error reporting (Texinfo::Convert::Converter Registering error and warning messages). If not set, the _$document_ is used for error reporting instead. $entry = new_node_menu_entry($node_relations, $use_sections) Returns the Texinfo tree corresponding to a single menu entry pointing to _$node_relations_. If _$use_sections_ is set, use the section name for the menu entry name. Returns ‘undef’ if the node argument is missing. construct_nodes_tree($document) Goes through nodes in _$document_ tree and set directions. This functions sets, in each node relations element hash: node_directions Hash reference with _up_, _next_ and _prev_ keys associated to the node line direction node relations. 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. sectioning_structure($document) This function goes through the parsed document tree and gather information on the document structure for sectioning commands. It sets section elements ‘extra’ hash values: 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_heading_number The sectioning command formatted number. The following is set in section relations hashes: section_children An array holding sectioning element children. The children are also section relations. section_directions Hash reference with _up_, _next_ and _prev_ keys associated to section directions. toplevel_directions Hash reference with _up_, _next_ and _prev_ keys associated to toplevel sectioning relations directions, for elements like ‘@top’, ‘@chapter’, ‘@appendix’, not taking into account ‘@part’ elements. After calling this function, information on the sectioning tree root can be obtained by calling ‘$document->sectioning_root()’. warn_non_empty_parts($document) Register a warning in for each ‘@part’ in global commands information of _$document_ that is not empty. 7.6 Texinfo::Structuring SEE ALSO ================================= Texinfo manual (http://www.gnu.org/s/texinfo/manual/texinfo/), Texinfo::Document: Texinfo::Document NAME. 7.7 Texinfo::Structuring AUTHOR =============================== Patrice Dumas, 7.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. 8 Texinfo::Report ***************** 8.1 Texinfo::Report NAME ======================== Texinfo::Report - Error storing for Texinfo modules 8.2 Texinfo::Report SYNOPSIS ============================ use Texinfo::Report; my $error_messages = []; if ($warning_happened) { push @$error_messages, Texinfo::Report::line_warn( sprintf(__("\@%s is wrongly used"), $current->{'cmdname'}), $current->{'source_info'}, 0, $converter->get_conf('DEBUG')); } foreach my $error_message (@$error_messages) { warn $error_message->{'error_line'}; } 8.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. 8.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 methods are used by the Texinfo::Parser: Texinfo::Parser NAME and Texinfo::Convert::Converter: Texinfo::Convert::Converter NAME modules. 8.5 Texinfo::Report METHODS =========================== No method is exported in the default case. The methods allow registering errors and warnings. $error_count = count_errors ($error_messages) This function returns as _$error_count_ the count of errors in the error messages list (as opposed to warnings). 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’. $message = line_warn ($text, $error_location_info, $continuation, $debug, $silent) $message = line_error ($text, $error_location_info, $continuation, $debug, $silent) Register a warning or an error message structure. 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 Texinfo::Parser source_info. $message = document_warn ($text, $program_name, $continuation) $message = document_error ($text, $program_name, $continuation) Returns a document-wide error or warning message structure. _$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. 8.6 Texinfo::Report AUTHOR ========================== Patrice Dumas, 8.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. 9 Texinfo::Translations *********************** 9.1 Texinfo::Translations NAME ============================== Texinfo::Translations - Translations of output documents strings for Texinfo modules 9.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}}); 9.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. 9.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 Texinfo::Common ‘__’ and ‘__p’: Texinfo::Common $translated_string = __($msgid). 9.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 ‘new_lang_translation’ method sets up a lang translation object that is used as argument inthe other method, that contains the language and associated already translated strings. $lang_translations = new_lang_translation($lang, $locale_encoding) _$lang_ is the language of the returned lang translations. _$locale_ encoding is optional and should be the encoding used to encode character strings to for environment variables. In general, you should base it on the _COMMAND_LINE_ENCODING_ customization variable value. The returned _$lang_translations_ is an array reference. The first element of the array is the language. The second element is the language encoded to the local encoding. The third element should be set to an hash reference holding translations already done. 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_translations, $replaced_substrings, $translation_context, $debug_level, $object, $translate_string_method) $string = gdt_string($string, $lang_translations, $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. The _$lang_translations_ argument should be an array reference with one or two elements. The first element of the array is the language used for the translation. The second element, if set, should be an hash reference holding translations already done. _$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 ‘cache_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 ‘cache_translate_string’. The _$object_ is passed as first argument of the _$translate_string_method_, the other arguments are the same as ‘cache_translate_string’: Texinfo::Translations $translated_string_tree = cache_translate_string($string, $lang_translations, $translation_context) arguments. $tree = pgdt($translation_context, $string, $lang_translations, $replaced_substrings, $debug_level, $object, $translate_string_method) 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 ‘cache_translate_string’. $translated_string_tree = cache_translate_string($string, $lang_translations, $translation_context) The _$string_ is a string to be translated. The _$lang_translations_ argument should be an array reference with one or two elements. The first element of the array is the language used for the translation. The second element, if set, should be an hash reference holding translations already done. If the language is ‘undef’ or an empty string, the input string does not need to be translated. 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. ‘cache_translate_string’ uses a gettext-like infrastructure to retrieve the translated strings, using the _texinfo_document_ domain. Returns an array reference with the translated string as first element, or undef if the input string should be used as translation. The second element of the reference array, if present, should be the Texinfo tree corresponding to the translated string, without the braced arguments substituted. 9.6 Texinfo::Translations SEE ALSO ================================== GNU gettext utilities manual (https://www.gnu.org/software/gettext/manual/). 9.7 Texinfo::Translations AUTHOR ================================ Patrice Dumas, 9.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. 10 Texinfo::Transformations *************************** 10.1 Texinfo::Transformations NAME ================================== Texinfo::Transformations - transformations of Texinfo tree 10.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. 10.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_in_document’ 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 Texinfo::ManipulateTree: Texinfo::ManipulateTree NAME. 10.4 Texinfo::Transformations METHODS ===================================== No method is exported in the default case. complete_tree_nodes_menus_in_document($document, $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: Texinfo::Structuring sectioning_structure($document). 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: Texinfo::Structuring sectioning_structure($document). fill_gaps_in_sectioning_in_document($document, $commands_heading_tree) This function adds empty ‘@unnumbered’ and similar commands in a _$document_ tree to fill gaps in sectioning. This may be used, for example, when converting from a format that can handle gaps in sectioning. 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) ‘menu_to_simple_menu’ transforms the tree of a menu tree element. 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, $document) 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 _$document_ argument is optional. If defined, the _$document_ is 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. 10.5 Texinfo::Transformations SEE ALSO ====================================== Texinfo manual (http://www.gnu.org/s/texinfo/manual/texinfo/), Texinfo::Parser: Texinfo::Parser NAME, Texinfo::ManipulateTree: Texinfo::ManipulateTree NAME. 10.6 Texinfo::Transformations AUTHOR ==================================== Patrice Dumas, 10.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. 11 Texinfo::Indices ******************* 11.1 Texinfo::Indices NAME ========================== Texinfo::Indices - merging and sorting indices from Texinfo 11.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); # $converter is a converter object my $index_entries_sorted; if ($sort_by_letter) { $index_entries_sorted = Texinfo::Indices::sort_indices_by_letter($document, $converter); } else { $index_entries_sorted = Texinfo::Indices::sort_indices_by_index($document, $converter); } 11.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. 11.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 Texinfo::Document: 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. 11.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 Texinfo::Convert::Converter: Texinfo::Convert::Converter NAME, a Texinfo::Document: 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: Texinfo::Indices $option = setup_index_entry_keys_formatting($customization_information). 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 ‘Texinfo::Document::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 Texinfo::Document index_entries. In general, this method should not be called directly, instead ‘Texinfo::Document::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, $converter, $use_unicode_collation, $locale_lang) $index_entries_sorted = sort_indices_by_letter($document, $converter, $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 ‘Texinfo::Document::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 optional argument _$converter_ is used for error reporting if present, otherwise the _$document_ is used. In general, those methods should not be called directly, instead ‘Texinfo::Document::sorted_indices_by_index’: Texinfo::Document $sorted_indices = sorted_indices_by_index($document, $converter, $use_unicode_collation, $locale_lang) or ‘Texinfo::Document::sorted_indices_by_letter’: Texinfo::Document $sorted_indices = sorted_indices_by_letter($document, $converter, $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. 11.6 Texinfo::Indices SEE ALSO ============================== Texinfo manual (http://www.gnu.org/s/texinfo/manual/texinfo/), Texinfo::Document: Texinfo::Document NAME. 11.7 Texinfo::Indices AUTHOR ============================ Patrice Dumas, 11.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. 12 Texinfo::OutputUnits *********************** 12.1 Texinfo::OutputUnits NAME ============================== Texinfo::OutputUnits - setup and manage Texinfo document output units 12.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); } my $nodes_list = $document->nodes_list(); split_pages($output_units, $nodes_list, $split); units_directions($identifier_target, $output_units, $nodes_list, $document->get_conf('DEBUG')); units_file_directions($output_units); 12.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. 12.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 ‘Texinfo::Convert::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 ‘Texinfo::Convert::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. 12.5 Texinfo::OutputUnits METHODS ================================= No method is exported in the default case. 12.5.1 Output units creation ---------------------------- Output units are hash references created with the following keys: ‘unit_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. 12.5.2 Grouping output units in pages ------------------------------------- You can call ‘split_pages’ to group together output units: split_pages($output_units, $nodes_list, $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. _$nodes_list_ is the nodes relations list. 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. 12.5.3 Setting output units directions -------------------------------------- You can call the following methods to set output units directions: units_directions($identifier_target, $nodes_list, $output_units, $print_debug) The _$identifier_target_ argument associates identifiers with target elements and is generally obtained from a parsed document, ‘Texinfo::Document::labels_information’: Texinfo::Document $identifier_target = labels_information($document). The _$nodes_list_ argument holds nodes relations, and is also generally obtained from a parsed 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. 12.6 Texinfo::OutputUnits SEE ALSO ================================== Texinfo manual (http://www.gnu.org/s/texinfo/manual/texinfo/), Texinfo::Document: Texinfo::Document NAME, Texinfo::Convert::Converter: Texinfo::Convert::Converter NAME. 12.7 Texinfo::OutputUnits AUTHOR ================================ Patrice Dumas, 12.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. 13 Texinfo::Convert::Texinfo **************************** 13.1 Texinfo::Convert::Texinfo NAME =================================== Texinfo::Convert::Texinfo - Convert a Texinfo tree to Texinfo code 13.2 Texinfo::Convert::Texinfo SYNOPSIS ======================================= use Texinfo::Convert::Texinfo qw(convert_to_texinfo); my $texinfo_text = convert_to_texinfo($tree); 13.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. 13.4 Texinfo::Convert::Texinfo DESCRIPTION ========================================== ‘Texinfo::Convert::Texinfo’ converts a Texinfo tree (described in Texinfo::Parser: 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. 13.5 Texinfo::Convert::Texinfo METHODS ====================================== $texinfo_text = convert_to_texinfo($tree) Converts the Texinfo tree _$tree_ to Texinfo code. 13.6 Texinfo::Convert::Texinfo AUTHOR ===================================== Patrice Dumas, 13.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. 14 Texinfo::Convert::Utils ************************** 14.1 Texinfo::Convert::Utils NAME ================================= Texinfo::Convert::Utils - miscellaneous functions usable in all converters 14.2 Texinfo::Convert::Utils SYNOPSIS ===================================== use Texinfo::Convert::Utils; 14.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. 14.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 Texinfo::Convert::Converter: Texinfo::Convert::Converter NAME. 14.5 Texinfo::Convert::Utils METHODS ==================================== No method is exported in the default case. Some methods take an optional _$converter_ argument for error reporting, see Texinfo::Convert::Converter Registering error and warning messages. Even when the caller does not inherit from Texinfo::Convert::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 with the converter argument set. $result = add_heading_number($heading_element, $heading_text, $do_number, $lang_translations) _$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. The _$lang_translations_ optional argument should be an array reference with one or two elements. The first element of the array is the language the resulting string is translated to. The second element, if set, should be an hash reference holding translations already done. If a language is set in _$lang_translations_, the string is translated and the optional _$debug_ argument is passed to the translation function. This function returns the heading with a number and the appendix part if needed. $contents_element = 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. ($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($def_line, $lang_translations, $command_line_encoding, $debug, $converter) _$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. The _$lang_translations_ optional argument should be an array reference holding information on the current language and translations. It could be obtained from the converter ‘current_lang_translations’ or be setup by a call to ‘Texinfo::Translations::new_lang_translation’: Texinfo::Translations $lang_translations = new_lang_translation($lang, $locale_encoding). If _$lang_translations_ is set, _$command_line_encoding_ should be set to the encoding suitable for environment variables, usually obtained from the _COMMAND_LINE_ENCODING_ customization variable, and the optional _$debug_ argument is passed to the translation function. If the optional _$converter_ argument is set, the translation is done by a converter method. In that case, _$lang_translations_ and _$debug_ are ignored, the converter method uses similar converter information. ($encoded_name, $encoding) = encoded_input_file_name($character_string_name, $input_file_name_encoding, $doc_encoding_for_input_file_name, $locale_encoding, $document, $input_file_encoding) ($encoded_name, $encoding) = encoded_output_file_name($character_string_name, $output_file_name_encoding, $doc_encoding_for_output_file_name, $locale_encoding, $document) ‘encoded_input_file_name’ encodes _$character_string_name_ as an input file name. If _$doc_encoding_for_input_file_name_ is set, the encoding is based on the input file content encoding, otherwise _$locale_encoding_ is used. The _$document_ argument is an optional Texinfo parsed document used to get the input document content encoding. ‘encoded_output_file_name’ encodes _$character_string_name_ as an output file name and takes similar arguments. Return the encoded name and the encoding used to encode the name. The _$input_file_encoding_ argument is optional and only available for ‘encoded_input_file_name’. 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_verbatiminclude($verbatiminclude, $include_directories, $name_encoding, $doc_encoding_for_input_file_name, $locale_encoding, $document, $converter) _$verbatiminclude_ is a ‘@verbatiminclude’ tree element. _$include_directories_ is an array reference with include directories where the file specified as ‘@verbatiminclude’ argument is searched for. _$name_encoding_, _$doc_encoding_for_input_file_name_, _$locale_encoding_ and _$document_ are ‘encoded_input_file_name’ arguments: Texinfo::Convert::Utils ($encoded_name, $encoding) = encoded_input_file_name($character_string_name, $input_file_name_encoding, $doc_encoding_for_input_file_name, $locale_encoding, $document, $input_file_encoding). The optional _$converter_ argument is used to output error messages. This function returns a ‘@verbatim’ tree elements after finding the included file and reading it. $documentinfo_info = get_document_documentinfo($document) _$document_ is a Texinfo parsed document. If ‘@documentinfo’ is found in the document, return an hash reference with @-command names appearing in ‘@documentinfo’ as keys associated to an array reference as value containing the @-commands Texinfo tree elements. Otherwise, returns ‘undef’. 14.6 Texinfo::Convert::Utils SEE ALSO ===================================== Texinfo::Common: Texinfo::Common NAME, Texinfo::Convert::Converter: Texinfo::Convert::Converter NAME and Texinfo::Translations: Texinfo::Translations NAME. 14.7 Texinfo::Convert::Utils AUTHOR =================================== Patrice Dumas, 14.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. 15 Texinfo::Convert::Unicode **************************** 15.1 Texinfo::Convert::Unicode NAME =================================== Texinfo::Convert::Unicode - Representation as Unicode characters 15.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::Common::find_innermost_accent_contents($accent); my $formatted_accents = encoded_accents($converter, convert_to_text($contents_element), $stack, $encoding, \&Texinfo::Text::ascii_accent_fallback); 15.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. 15.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. 15.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 Texinfo::Common::find_innermost_accent_contents: Texinfo::Common ($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, $index_in_stack, $accents_stack) _$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. _$index_in_stack_ is the position in the _$accents_stack_ of the accent command being converted. 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. 15.6 Texinfo::Convert::Unicode AUTHOR ===================================== Patrice Dumas, 15.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. 16 Texinfo::Convert::NodeNameNormalization ****************************************** 16.1 Texinfo::Convert::NodeNameNormalization NAME ================================================= Texinfo::Convert::NodeNameNormalization - Normalize and transliterate Texinfo trees 16.2 Texinfo::Convert::NodeNameNormalization SYNOPSIS ===================================================== use Texinfo::Convert::NodeNameNormalization qw(convert_to_node_identifier normalize_transliterate_texinfo); my $normalized = convert_to_node_identifier($node_element->{'contents'}->[0]); my $file_name = normalize_transliterate_texinfo($section_element->{'contents'}->[0]); 16.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. 16.4 Texinfo::Convert::NodeNameNormalization DESCRIPTION ======================================================== ‘Texinfo::Convert::NodeNameNormalization’ allows to normalize node names with ‘convert_to_normalized’ and ‘convert_to_node_identifier’. ‘convert_to_node_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_identifier’ leaves out the step of normalizing ‘Top’. ‘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. 16.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_node_identifier($tree) $normalized = convert_to_identifier($tree) With ‘convert_to_node_identifier’, the Texinfo _$tree_ is returned as a string, normalized as described in the Texinfo manual _HTML Xref_ node. ‘convert_to_identifier’ leaves out the normalization of the name if it is a _Top_ node name. 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. 16.6 Texinfo::Convert::NodeNameNormalization AUTHOR =================================================== Patrice Dumas, 16.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. 17 Texinfo::Convert::Text ************************* 17.1 Texinfo::Convert::Text NAME ================================ Texinfo::Convert::Text - Convert Texinfo tree to simple text 17.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); 17.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. 17.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. Converters derived from Texinfo::Convert::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. 17.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 ‘ASCII_GLYPH’, ‘DEBUG’, ‘DOC_ENCODING_FOR_INPUT_FILE_NAME’, ‘COMMAND_LINE_ENCODING’, ‘NUMBER_SECTIONS’, ‘TEST’, ‘documentlanguage’, ‘INPUT_FILE_NAME_ENCODING’, ‘LOCALE_ENCODING’ and ‘INCLUDE_DIRECTORIES’ options corresponding to customization variables may be set in _$text_options_. The following options may also be set: converter If a converter object is passed to the function, generated error messages are passed back to the converter. See also Texinfo::Convert::Converter: Texinfo::Convert::Converter NAME. enabled_encoding If set, the value is considered to be the encoding name texinfo accented letters should be converted to. In the default case, this option is set from the main program directly or through converters calling conversion to text if the ‘--enable-encoding’ option, or the ‘ENABLE_ENCODING’ customization variable is set. 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. 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. 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. $result_accent_text = ascii_accent_fallback($converter, $text, $accent_command, $index_in_stack, $accents_stack, $in_upper_case $converter) _$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. The remaining arguments are also ignored and similarly may be 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. 17.6 Texinfo::Convert::Text AUTHOR ================================== Patrice Dumas, 17.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. 18 Texinfo::Convert::Converter ****************************** 18.1 Texinfo::Convert::Converter NAME ===================================== Texinfo::Convert::Converter - Parent class for Texinfo tree converters 18.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->set_global_document_commands('before', \@global_commands); ... $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(); ... } # if some data needs to be released explicitly sub converter_destroy($) { my $self = shift; ... } # end of Texinfo::Convert::MyConverter my $converter = Texinfo::Convert::MyConverter->converter(); $converter->output($texinfo_parsed_document); 18.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. 18.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. This method should not perform converter initialization, as it should only be called with converter setup for immediate conversion, in general when conversion is already ongoing. $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’: Texinfo::Convert::Converter ($output_file, $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. 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 Texinfo::Common: Texinfo::Common NAME, Texinfo::OutputUnits: Texinfo::OutputUnits NAME, Texinfo::Convert::Unicode: Texinfo::Convert::Unicode NAME and Texinfo::Convert::Text: Texinfo::Convert::Text NAME describes modules or additional function that may be useful for backends, while the parsed Texinfo tree is described in Texinfo::Parser: Texinfo::Parser NAME. 18.5 Texinfo::Convert::Converter METHODS ======================================== 18.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 optional _$options_ hash reference holds options for the converter. This method is called through a converter by ‘converter’: Texinfo::Convert::Converter $converter = MyConverter->converter($options), but it may also be called through a converter module class. $converter->converter_initialize() This method is called at the end of the ‘Texinfo::Convert::Converter’ converter initialization. 18.5.2 Conversion ----------------- For conversion with ‘output’ and ‘convert’ a document to convert should be associated with 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 ‘Texinfo::Convert::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: Texinfo::Convert::Converter $converter->set_document($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. For a converter to be reusable for multiple documents conversion, variables values corresponding to @-commands that can be set in the document and influence formatting should be reset at conversion initialization. This can be done with ‘set_global_document_commands’: Texinfo::Convert::Converter $converter->set_global_document_commands($commands_location, $selected_commands). If the list of such @-commands is ‘@global_commands’, the following call would reset them to the values they had before starting the conversion: $self->set_global_document_commands('before', \@global_commands); $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 with the converter. If a converter uses output units, the ‘convert_output_unit’ method can be used and can be redefined if needed: $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. This method is not needed for all the converters. The implementation of ‘convert_output_unit’ of ‘Texinfo::Convert::Converter’ could be suitable in many cases. Output units are typically returned by ‘Texinfo::OutputUnits’ ‘split_by_section’: Texinfo::OutputUnits $output_units = split_by_section($document) or ‘Texinfo::OutputUnits’ ‘split_by_node’: Texinfo::OutputUnits $output_units = split_by_node($document). 18.5.3 Output units and converter destruction --------------------------------------------- Removing output units and destroying the converter is only needed if one want to be sure that the memory held is released or reused. It is optional, and in general takes longer than having the memory be released at the end of a script. Output units associated with a converter are removed by calling the ‘converter_remove_output_units’ method that should be inherited from ‘Texinfo::Convert::Converter’. $converter->converter_remove_output_units() Release the output units associated with a converter. It does not necessarily means that the output units are explicitly undefined, it could be that cycles in output units are removed such that Perl can release or reuse the memory. To help with the output units release, the modules subclassing ‘Texinfo::Convert::Converter’ can define the method: $converter->converter_release_output_units() This method is called at the beginning of the ‘Texinfo::Convert::Converter’ converter output units removal. A module subclassing ‘Texinfo::Convert::Converter’ is destroyed by calling the ‘destroy_converter’ method that should be inherited from ‘Texinfo::Convert::Converter’. $converter->destroy_converter() Destroy converter data. To help with the destruction, the modules subclassing ‘Texinfo::Convert::Converter’ can define the method: $converter->converter_destroy() This method is called at the beginning of the ‘Texinfo::Convert::Converter’ converter destruction. The default ‘converter_release_output_units’ and ‘converter_destroy’ methods do nothing. 18.5.4 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’: Texinfo::Convert::Converter $converter = MyConverter->converter($options) 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. 18.5.5 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. 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 Texinfo::Report::count_errors: Texinfo::Report $error_count = count_errors ($error_messages). 18.5.6 Translations in output documents --------------------------------------- ‘Texinfo::Convert::Converter’ provides wrappers around Texinfo::Translations: 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. 18.5.7 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 ‘Texinfo::Document::sorted_indices_by_letter’: Texinfo::Document $sorted_indices = sorted_indices_by_letter($document, $converter, $use_unicode_collation, $locale_lang) or ‘Texinfo::Document::sorted_indices_by_index’: Texinfo::Document $sorted_indices = sorted_indices_by_index($document, $converter, $use_unicode_collation, $locale_lang) with arguments based on ‘USE_UNICODE_COLLATION’, ‘COLLATION_LANGUAGE’ and ‘DOCUMENTLANGUAGE_COLLATION’ customization options, and, if relevant, current ‘@documentlanguage’. 18.5.8 Accents conversion ------------------------- Accent @-commands that take arguments can be nested in Texinfo code, as in ‘@'{@^a}’. To handle this situation, a user defined function can be called for each of the accent commands, starting by the innermost accent command. For this the user-defined function and the outermost accent command tree elements should be given to the ‘convert_accents’ function: $result = $converter->convert_accents($accent_command, \&format_accents, $output_encoded_characters, $in_upper_case) _$accent_command_ is an accent command tree elements, which may have other accent commands tree elements nested inside. The function returns the accents formatted either as encoded letters if _$output_encoded_characters_ is set, or formatted by calling _\&format_accents_ repeatedly starting from the innermost accent command tree element within _$accent_command_. The innermost accent command argument (usually a letter), is also converted, by calling ‘$converter->convert_tree’: Texinfo::Convert::Converter $result = $converter->convert_tree($tree). If _$in_upper_case_ is set, the result should be uppercased. $result = &$format_accents($self, $text, $accent_command, $index_in_stack, $accents_stack, $in_upper_case) _$self_ is the converter in the call to ‘convert_accents’. For the innermost accent command, _$text_ is the text appearing within the accent command converted. For the other accent commands, _$text_ is the result of the previously converted accent command. _$accent_command_ the Texinfo tree element corresponding to the accent command being converted. _$index_in_stack_ is the position in the _$accents_stack_ of the accent command being converted. The _$accents_stack_ is an array holding the nested accent command Texinfo tree elements. The innermost tree element command is last. _$in_upper_case_ is optional, and, if set, the text should be put in upper case. The function should return the converted accent argument to be processed by the following accent command. 18.5.9 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($self, $text, $accent_command, $index_in_stack, $accents_stack, $in_upper_case, $use_numeric_entities) _$self_ is an object, in general a converter. _$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. _$index_in_stack_ is the position in the _$accents_stack_ of the accent command being converted. It is optional, but if not present the formatting cannot take into account the position of the accent in the current accents group being converted. _$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. This function is similar to the accent formatting function passed to ‘convert_accents’ for Accents conversion: Texinfo::Convert::Converter Accents conversion. $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. The following hashes, defined as ‘our’ variable are also available: %xml_text_entity_no_arg_commands_formatting Values are entities or, if not available, ASCII representation of single character non-alphabetical commands without brace such as ‘*’ or ‘:’ and of commands with empty braces such as ‘atchar’, ‘LaTeX’, ‘arrow’, ‘quoteleft’ or ‘AA’. 18.5.10 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: Texinfo::Convert::Converter Registering error and warning messages. Also to translate strings, see Translations in output documents: Texinfo::Convert::Converter 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 Texinfo::Convert::Utils: Texinfo::Convert::Utils NAME. $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 these functions are wrappers around functions from Texinfo::Convert::Utils: Texinfo::Convert::Utils NAME with the same names. $tree = $converter->expand_today() Expand today's date, as a Texinfo tree with translations. ($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. $filename = $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 ‘Texinfo::Common’ ‘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_. $tree = $converter->expand_verbatiminclude($verbatiminclude) _$verbatiminclude_ is a ‘@verbatiminclude’ tree element. This function returns a ‘@verbatim’ tree elements after finding the included file and reading it. 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. 18.6 Texinfo::Convert::Converter SEE ALSO ========================================= Texinfo::Common: Texinfo::Common NAME, Texinfo::Convert::Unicode: Texinfo::Convert::Unicode NAME, Texinfo::Report: Texinfo::Report NAME, Texinfo::Translations: Texinfo::Translations NAME, Texinfo::Convert::Utils: Texinfo::Convert::Utils NAME and Texinfo::Parser: Texinfo::Parser NAME. 18.7 Texinfo::Convert::Converter AUTHOR ======================================= Patrice Dumas, 18.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. 19 Texinfo::Convert::Info ************************* 19.1 Texinfo::Convert::Info NAME ================================ Texinfo::Convert::Info - Convert Texinfo tree to Info 19.2 Texinfo::Convert::Info SYNOPSIS ==================================== my $converter = Texinfo::Convert::Info->converter({'NUMBER_SECTIONS' => 0}); # output to files $converter->output($document); # no header nor footer output my $converted = $converter->convert($document); 19.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. 19.4 Texinfo::Convert::Info DESCRIPTION ======================================= Texinfo::Convert::Info converts a Texinfo tree to Info. 19.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 Texinfo::Convert::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. In general it is better to call this function when conversion is already ongoing, as it requires an association to a document and a suitably initialized converter formatting state. 19.6 Texinfo::Convert::Info AUTHOR ================================== Patrice Dumas, 19.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. 20 Texinfo::Convert::HTML ************************* 20.1 Texinfo::Convert::HTML NAME ================================ Texinfo::Convert::HTML - Convert Texinfo tree to HTML 20.2 Texinfo::Convert::HTML SYNOPSIS ==================================== my $converter = Texinfo::Convert::HTML->converter({'NUMBER_SECTIONS' => 0}); # output to files $converter->output($document); # no header nor footer output my $converted = $converter->convert($document); $converter->output_internal_links(); # HTML only 20.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. 20.4 Texinfo::Convert::HTML DESCRIPTION ======================================= Texinfo::Convert::HTML converts a Texinfo tree to HTML. 20.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 Texinfo::Convert::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. In general it is better to call this function when conversion is already ongoing, as it requires an association to a document and a suitably initialized converter formatting state. $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. 20.6 Texinfo::Convert::HTML AUTHOR ================================== Patrice Dumas, 20.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. 21 Texinfo::Convert::DocBook **************************** 21.1 Texinfo::Convert::DocBook NAME =================================== Texinfo::Convert::DocBook - Convert Texinfo tree to DocBook 21.2 Texinfo::Convert::DocBook SYNOPSIS ======================================= my $converter = Texinfo::Convert::DocBook->converter({'NUMBER_SECTIONS' => 0}); # output to files $converter->output($document); # no header nor footer output my $converted = $converter->convert($document); 21.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. 21.4 Texinfo::Convert::DocBook DESCRIPTION ========================================== Texinfo::Convert::DocBook converts a Texinfo tree to DocBook. 21.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 Texinfo::Convert::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. In general it is better to call this function when conversion is already ongoing, as it requires an association to a document and a suitably initialized converter formatting state. 21.6 Texinfo::Convert::DocBook AUTHOR ===================================== Patrice Dumas, 21.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. 22 Texinfo::Convert::TexinfoMarkup ********************************** 22.1 Texinfo::Convert::TexinfoMarkup NAME ========================================= Texinfo::Convert::TexinfoMarkup - Convert Texinfo tree to element and attribute markup 22.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; .... } 22.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. 22.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 (Texinfo::Convert::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. 22.5 Texinfo::Convert::TexinfoMarkup METHODS ============================================ 22.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 (Texinfo::Parser Types for text elements). Texinfo tree elements are described in details in Texinfo::Parser 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. 22.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’. 22.6 Texinfo::Convert::TexinfoMarkup AUTHOR =========================================== Patrice Dumas, 22.7 Texinfo::Convert::TexinfoMarkup SEE ALSO ============================================= Texinfo::Convert::Converter: Texinfo::Convert::Converter NAME. Texinfo::Convert::TexinfoXML: Texinfo::Convert::TexinfoXML NAME. The ‘Texinfo::Convert::TexinfoSXML’ is another subclass, which outputs SXML. It is not much documented. 22.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. 23 Texinfo::Convert::TexinfoXML ******************************* 23.1 Texinfo::Convert::TexinfoXML NAME ====================================== Texinfo::Convert::TexinfoXML - Convert Texinfo tree to TexinfoXML 23.2 Texinfo::Convert::TexinfoXML SYNOPSIS ========================================== my $converter = Texinfo::Convert::TexinfoXML->converter({'NUMBER_SECTIONS' => 0}); # output to files $converter->output($document); # no header nor footer output my $converted = $converter->convert($document); 23.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. 23.4 Texinfo::Convert::TexinfoXML DESCRIPTION ============================================= Texinfo::Convert::TexinfoXML converts a Texinfo tree to TexinfoXML. 23.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 Texinfo::Convert::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. In general it is better to call this function when conversion is already ongoing, as it requires an association to a document and a suitably initialized converter formatting state. 23.6 Texinfo::Convert::TexinfoXML AUTHOR ======================================== Patrice Dumas, 23.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. 24 Texinfo::Convert::Plaintext ****************************** 24.1 Texinfo::Convert::Plaintext NAME ===================================== Texinfo::Convert::Plaintext - Convert Texinfo tree to Plaintext 24.2 Texinfo::Convert::Plaintext SYNOPSIS ========================================= my $converter = Texinfo::Convert::Plaintext->converter({'NUMBER_SECTIONS' => 0}); # output to files $converter->output($document); # no header nor footer output my $converted = $converter->convert($document); 24.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. 24.4 Texinfo::Convert::Plaintext DESCRIPTION ============================================ Texinfo::Convert::Plaintext converts a Texinfo tree to Plaintext. 24.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 Texinfo::Convert::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. In general it is better to call this function when conversion is already ongoing, as it requires an association to a document and a suitably initialized converter formatting state. 24.6 Texinfo::Convert::Plaintext AUTHOR ======================================= Patrice Dumas, 24.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. 25 Texinfo::TreeElement *********************** 25.1 Texinfo::TreeElement NAME ============================== Texinfo::TreeElement - Texinfo tree element interface 25.2 Texinfo::TreeElement SYNOPSIS ================================== my $element = Texinfo::TreeElement::new({}); 25.3 Texinfo::TreeElement 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. Note that this module is not used in ‘texi2any’ (except for the ‘new’ method, which is trivial and could be moved to another module). Note that this module could be removed at any time. 25.4 Texinfo::TreeElement DESCRIPTION ===================================== ‘Texinfo::TreeElement::new’ should be called on every Perl tree elements created. ‘Texinfo::TreeElement’ defines accessors and methods for Texinfo tree elements obtained from parsing Texinfo code. There is no specific advantage of using the accessors, but they may be needed when some Texinfo modules XS interfaces are used. These accessors are not used in ‘texi2any’. 25.5 Texinfo::TreeElement METHODS ================================= $element = new($element_hash) Turns the _$element_hash_ element hash into a ‘Texinfo::TreeElement’ object. This function is called on all the tree elements created in Texinfo modules codes. Since no accessors are used in ‘texi2any’ Texinfo modules, the call to ‘new’ is mainly cosmetic. It also allows to distinguish a Texinfo tree element from a hash. $type = $element->type() Return the _$element_ type, or ‘undef’. $cmdname = $element->cmdname() Return the _$element_ command name, if defined, or ‘undef’. $text = $element->text() Return the _$element_ text if the element is a text element, or ‘undef’. $number = $element->children_number() Return the number of children elements contained in _$element_. $child = $element->get_child($index) Return the _$element_ child element at index _$index_. $children_list = $element->get_children() Return an array reference holding the elements contained in _$element_. $parent = $element->parent() Return the parent element of _$element_. $source_info = $element->source_info() Return the _$element_ source info, or ‘undef’ if there is none. $value = $element->get_attribute($attribute_name) Return the _$element_ _$attribute_name_ attribute value. If the _$attribute_name_ does not exist or is not set at all, return ‘undef’. $element->add_to_element_contents($added_element) Insert _$added_element_ at the end of the _$element_ contents (ie the element children array). 25.5.1 ‘Texinfo::TreeElement’ and XS extensions ----------------------------------------------- The Texinfo Perl modules can be setup to use Perl XS module extensions in native code (written in C) that replace Perl package or methods by native code for faster execution. It may be important to use the ‘Texinfo::TreeElement’ accessors that return elements instead of using hash keys described in Texinfo::Parser TEXINFO TREE when some Texinfo modules XS interfaces are used. The Texinfo modules XS interface is designed such that the Texinfo tree actually processed is not the Perl elements tree, but a tree stored in native code in XS extensions, corresponding to compiled C data structures. For some Texinfo modules XS extensions, Perl tree elements need to have a link from Perl to native code C data registered in the Perl element to find the C tree data corresponding to a Perl element. Using the ‘Texinfo::TreeElement’ methods may help setting up this link. Indeed, if an element has already a link to C data, the elements returned by ‘Texinfo::TreeElement’ methods will also have this link setup. For example, if _$element_ has already a link to C data, _$element_child_ will also have a link to C data setup: my $element_child = $element->get_child(0) Note that, even if XS extensions are used, calling ‘new’: Texinfo::TreeElement $element = new($element_hash) does not set up a link to C, Texinfo::Example::TreeElementConverter ‘new_tree_element’: Texinfo::Example::TreeElementConverter $converter->new_tree_element($element, $use_sv) should be used for that. For other ways to setup this link, see Texinfo::Example::TreeElementConverter: Texinfo::Example::TreeElementConverter NAME and Texinfo::Reader Texinfo::Reader and XS extensions. 25.6 Texinfo::TreeElement SEE ALSO ================================== Texinfo::Parser TEXINFO TREE. 25.7 Texinfo::TreeElement AUTHOR ================================ Patrice Dumas. 25.8 Texinfo::TreeElement COPYRIGHT AND LICENSE =============================================== Copyright 2025- 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. 26 Texinfo::Reader ****************** 26.1 Texinfo::Reader NAME ========================= Texinfo::Reader - Texinfo tree reader 26.2 Texinfo::Reader SYNOPSIS ============================= use Texinfo::Parser; use Texinfo::Reader; my $parser = Texinfo::Parser::parser(); my $document = $parser->parse_texi_file("somefile.texi"); my $start_element = $document->tree(); my $reader = Texinfo::Reader::new($start_element); while (1) { my $next = $reader->read(); last if (!defined($next)); my $category = $next->{'category'}; my $element = $next->{'element'}; if ($category == Texinfo::Reader->TXI_READ_TEXT) { my $text = $element->{'text'}; .... } elsif ($category == Texinfo::Reader->TXI_READ_ELEMENT_START) { my $cmdname = $element->{'cmdname'}; ... .... } } 26.3 Texinfo::Reader 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. Note that this module is not used in ‘texi2any’. Note that this module could be removed at any time. 26.4 Texinfo::Reader DESCRIPTION ================================ ‘Texinfo::Reader’ offers an interface to a Texinfo tree obtained from parsing Texinfo code. This interface is based on a stream of tokens associated to tree elements. This interface is conceptually similar to the interface of XML::LibXML::Reader (https://metacpan.org/pod/XML::LibXML::Reader) or Pod::Simple::PullParser (https://metacpan.org/pod/Pod::Simple::PullParser). The Reader acts as a cursor going forward on the Texinfo tree and stopping at each element on the way, providing with a new token. The user's code keeps control of the progress and simply calls the ‘read()’ function repeatedly to progress to the next token in the Texinfo document order. The other function provides means for skipping sub-trees. 26.5 Texinfo::Reader METHODS ============================ $reader = Texinfo::Reader::new ($element) Initialize a reader starting at the _$element_ Texinfo tree element. $token = $reader->read() Returns the next token or undef at the end of the tree. A token is an hash reference with string keys: element The current tree element. category Information on the tree element and on the position read. The possible token category values are declared as constants and are accessed through the ‘Texinfo::Reader’ package, like ‘Texinfo::Reader->TXI_READ_ELEMENT_START’. The token category can take the following ‘Texinfo::Reader’ constant values: TXI_READ_ELEMENT_START Start of the tree element, before getting the element contents. TXI_READ_ELEMENT_END End of the tree element after having read the contents (after a closing brace, an @end, at the end of a container). TXI_READ_TEXT Text element. TXI_READ_IGNORABLE_TEXT Text element supposed to be ignored, such as spaces appearing after an opening brace or around a comma delimiting arguments. TXI_READ_EMPTY A tree element which is not a text tree element and does not hold content. For Texinfo @-commands without braces nor line argument such as ‘@@’ and for empty arguments. For example the ‘brace_container’ argument container of ‘@TeX{}’ is empty. Also for invalid constructs such as brace @-commands without braces. The Texinfo tree element is described in Texinfo::Parser TEXINFO TREE. $token = $reader->skip_children($element) Skip the remaining of the contents currently being processed. Return a token with the _TXI_READ_ELEMENT_END_ category, or undef at the end of the tree. If the _$element_ optional argument is specified, a fatal error is emitted if it does not match with the parent element of the skipped contents. $elements = reader_collect_commands_list($element, $command_names) Collect all the tree elements corresponding to @-command names in the _$command_names_ array reference, starting at _$element_. The return value is an array reference of the collected elements, in the order of their appearence in the Texinfo tree. 26.5.1 ‘Texinfo::Reader’ and XS extensions ------------------------------------------ The Texinfo Perl modules can be setup to use Perl XS module extensions in native code (written in C) that replace Perl package or methods by native code for faster execution. In general, using pure Perl or XS extensions is transparent. This is not fully the case for ‘Texinfo::Reader’. The XS interface is designed such that the Texinfo tree actually processed is not the Perl elements tree, but a tree stored in native code in XS extensions, corresponding to compiled C data structures. If the ‘Texinfo::Reader’ XS extension is used, the element used to initialize the reader through new: Texinfo::Reader $reader = Texinfo::Reader::new ($element) need to have a link from Perl to native code C data registered in the Perl element to find the C tree data corresponding to the Perl element. This is done automatically if the element is the Texinfo tree root element. For other elements, this link may need to be setup especially. To setup this link explicitly for the element associated to the current Reader token or the child elements of the current Reader token the following methods may be called: $reader->register_token_element() Add a link from the current token Perl element to the associated C data. $reader->register_token_element_child($index) Add a link from the Perl element to the associated C data for the child of the current token Perl element at index _$index_. If the first child of the current token Perl element is of type ‘arguments_line’, the child of the ‘arguments_line’ tree element is selected instead of the child of the current token Perl element. For example, to register all the elements upon reading them: while (1) { my $next = $reader->read(); last if (!defined($next)); my $element = $next->{'element'}; my $registerd_element = $reader->register_token_element(); if (!defined($element)) { $element = $registerd_element; } ... } Calling these two functions is not the only possibility to create a link from Perl to C data. Another possibility is to use the Texinfo::TreeElement: Texinfo::TreeElement NAME interface to access other elements from elements with the link to C data already setup, or to use the Texinfo::Example::TreeElementConverter: Texinfo::Example::TreeElementConverter NAME module methods. 26.6 Texinfo::Reader SEE ALSO ============================= Texinfo::Parser: Texinfo::Parser NAME. Texinfo::Document: Texinfo::Document NAME. Texinfo::Example::TreeElementConverter: Texinfo::Example::TreeElementConverter NAME. 26.7 Texinfo::Reader AUTHOR =========================== Patrice Dumas. 26.8 Texinfo::Reader COPYRIGHT AND LICENSE ========================================== Copyright 2025- 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. 27 Texinfo::Example::TreeElementConverter ***************************************** 27.1 Texinfo::Example::TreeElementConverter NAME ================================================ Texinfo::Example::TreeElementConverter - Parent class for TreeElement based converters 27.2 Texinfo::Example::TreeElementConverter SYNOPSIS ==================================================== package Texinfo::Convert::MyConverter; use Texinfo::Convert::Converter; use Texinfo::Example::TreeElementConverter; our @ISA = qw(Texinfo::Example::TreeElementConverter); # define the methods needed for Texinfo::Convert::Converter ... sub convert_tree($$) { ... } ... # end of Texinfo::Convert::MyConverter my $converter = Texinfo::Convert::MyConverter->converter(); $converter->output($texinfo_parsed_document); 27.3 Texinfo::Example::TreeElementConverter 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. Note that this module is not used in ‘texi2any’. Note that this module could be removed at any time. 27.4 Texinfo::Example::TreeElementConverter DESCRIPTION ======================================================= ‘Texinfo::Example::TreeElementConverter’ is a super class that helps using the Texinfo::TreeElement: Texinfo::TreeElement NAME interface in converters. It provides implementations of methods from other Texinfo Perl modules using the TreeElement Texinfo::TreeElement: Texinfo::TreeElement NAME interface only. The original methods can be in the Texinfo::Convert::Converter: Texinfo::Convert::Converter NAME, Texinfo::Common: Texinfo::Common NAME, Texinfo::Convert::Utils: Texinfo::Convert::Utils NAME and Texinfo::Structuring: Texinfo::Structuring NAME modules. The Texinfo Perl modules can be setup to use Perl XS module extensions in native code (written in C) that replace Perl package or methods by native code for faster execution. The Texinfo modules XS interface is designed such that the Texinfo tree actually processed is not the Perl elements tree, but a tree stored in native code in XS extensions, corresponding to compiled C data structures. If XS extensions are loaded, finding a Perl element associated C data is required in some cases, namely to initialize Texinfo::Reader Texinfo::Reader and XS extensions with XS on an element (except for the tree root) or to find replaced substrings elements in translations. The ‘Texinfo::Example::TreeElementConverter’ modules helps with setting up the link from Perl elements to C, first by providing the methods using the TreeElement interface since the Texinfo::TreeElement: Texinfo::TreeElement NAME interface automatically sets up this link. The module also provides XS interfaces for methods also available in other modules that setup the link from Perl elements to C. Lastly, some methods are also available to create or access Texinfo tree elements that also setup Texinfo elements with the link from Perl elements to C. Using the Reader, the TreeElement interface and the methods provided in this module with XS to access and create elements also allows to go through the Texinfo tree without ever building full Perl element data. This may be all the more important that building full Perl element data wipes out the link from Perl elements to C element data. 27.5 Texinfo::Example::TreeElementConverter METHODS =================================================== The following methods allow to create new elements and get elements. If XS extensions are used, elements should be created and accessed through these methods to have a link from Perl to C data setup for the created or returned element. $converter->new_tree_element($element, $use_sv) Create a new tree elements based on the _$element_ hash reference. The _$use_sv_ argument is optional; if set and XS is used, the _$element_ hash reference is associated to the new tree element data in C, otherwise it is discarded. ($index_entry, $index_info) = $converter->get_tree_element_index_entry($element) Finds the index entry and index information associated to the tree element _$element_. See Texinfo::Common lookup_index_entry: Texinfo::Common ($index_entry, $index_info) = lookup_index_entry($index_entry_info, $indices_information) for a general description of the return values. Note that the returned _$index_info_ information does not contain the index entries associated to the index, only some basic information on the index. $element = $converter->get_global_unique_tree_element($command_name) $elements = global_commands_information_command_list($document, $command_name) Returns the tree element or tree elements corresponding to the _$command_name_ @-command with a link from Perl to C element data setup. Only for @-commands that could also be accessed through Texinfo::Document global_commands_information: Texinfo::Document $commands = global_commands_information($document) (if the link from Perl to C element data was not needed). ‘get_global_unique_tree_element’ should be called for @-commands that should appear only once in a Texinfo document. This method returns the element. ‘global_commands_information_command_list’ requires a ‘Texinfo::Document’ _$document_ argument. The _$document_ could be available as ‘$converter->{'document'}’. This method should be called for @-commands that may appear more than once in a Texinfo document. This method returns a reference on the array of all the _$command_name_ @-command tree elements appearing in the document. The other methods are documented in the modules that provide the non-TreeElement interface or the methods that do not setup elements with link from Perl to C element data. The method name is either the same as in this module, if the method is used as a wrapper around the method with the same name, or can be obtained by removing a leading ‘tree_element_’. For example, the ‘index_content_element’ documentation can be used for the ‘tree_element_index_content_element’ method of this module. 27.5.1 Related methods from other modules ----------------------------------------- To associate sectioning commands and nodes tree elements Perl to C data, the ‘register_document_relations_lists_elements’ ‘Texinfo::Document’ method may be called after getting the tree before starting the tree conversion, such that sectioning commands and nodes elements accessed through nodes and section relations have the association to C data already setup: $converter->{'document'}->register_document_relations_lists_elements() If you use the Texinfo::Reader: Texinfo::Reader NAME to go through the tree you can call reader methods to associate Perl to C data based on the current element being read, Texinfo::Reader ‘register_token_element’: Texinfo::Reader $reader->register_token_element() and Texinfo::Reader ‘register_token_element_child’: Texinfo::Reader $reader->register_token_element_child($index). 27.6 Texinfo::Example::TreeElementConverter SEE ALSO ==================================================== Texinfo::Convert::Converter: Texinfo::Convert::Converter NAME, Texinfo::Common: Texinfo::Common NAME, Texinfo::Convert::Utils: Texinfo::Convert::Utils NAME and Texinfo::Structuring: Texinfo::Structuring NAME. 27.7 Texinfo::Example::TreeElementConverter AUTHOR ================================================== Patrice Dumas, 27.8 Texinfo::Example::TreeElementConverter 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. Appendix A Index **************** * Menu: * %accent_commands: Texinfo::Commands @-COMMAND CLASSES. (line 337) * %all_commands: Texinfo::Common @-COMMAND INFORMATION. (line 788) * %block_commands: Texinfo::Commands @-COMMAND CLASSES. (line 342) * %blockitem_commands: Texinfo::Commands @-COMMAND CLASSES. (line 407) * %brace_code_commands: Texinfo::Commands @-COMMAND CLASSES. (line 412) * %brace_commands: Texinfo::Commands @-COMMAND CLASSES. (line 417) * %close_paragraph_commands: Texinfo::Commands @-COMMAND CLASSES. (line 423) * %commands_args_number: Texinfo::Commands @-COMMAND CLASSES. (line 428) * %contain_basic_inline_commands: Texinfo::Commands @-COMMAND CLASSES. (line 443) * %contain_plain_text: Texinfo::Commands @-COMMAND CLASSES. (line 448) * %def_aliases: Texinfo::Common @-COMMAND INFORMATION. (line 794) * %def_commands: Texinfo::Commands @-COMMAND CLASSES. (line 453) * %def_no_var_arg_commands: Texinfo::Common @-COMMAND INFORMATION. (line 794) * %default_index_commands: Texinfo::Commands @-COMMAND CLASSES. (line 457) * %explained_commands: Texinfo::Commands @-COMMAND CLASSES. (line 462) * %formattable_line_commands: Texinfo::Commands @-COMMAND CLASSES. (line 467) * %formatted_line_commands: Texinfo::Commands @-COMMAND CLASSES. (line 484) * %formatted_nobrace_commands: Texinfo::Commands @-COMMAND CLASSES. (line 476) * %heading_spec_commands: Texinfo::Commands @-COMMAND CLASSES. (line 493) * %in_heading_spec_commands: Texinfo::Commands @-COMMAND CLASSES. (line 497) * %index_names: Texinfo::Commands @-COMMAND INFORMATION. (line 321) * %inline_conditional_commands: Texinfo::Commands @-COMMAND CLASSES. (line 509) * %inline_format_commands: Texinfo::Commands @-COMMAND CLASSES. (line 509) * %letter_no_arg_commands: Texinfo::Commands @-COMMAND CLASSES. (line 514) * %line_commands: Texinfo::Commands @-COMMAND CLASSES. (line 523) * %math_commands: Texinfo::Commands @-COMMAND CLASSES. (line 519) * %no_paragraph_commands: Texinfo::Commands @-COMMAND CLASSES. (line 534) * %nobrace_commands: Texinfo::Commands @-COMMAND CLASSES. (line 538) * %nobrace_symbol_text: Texinfo::CommandsValues @-COMMAND ASSOCIATED INFORMATION. (line 645) * %non_formatted_block_commands: Texinfo::Commands @-COMMAND CLASSES. (line 549) * %preamble_commands: Texinfo::Commands @-COMMAND CLASSES. (line 559) * %preformatted_code_commands: Texinfo::Commands @-COMMAND CLASSES. (line 565) * %preformatted_commands: Texinfo::Commands @-COMMAND CLASSES. (line 565) * %ref_commands: Texinfo::Commands @-COMMAND CLASSES. (line 572) * %root_commands: Texinfo::Commands @-COMMAND CLASSES. (line 577) * %sectioning_heading_commands: Texinfo::Commands @-COMMAND CLASSES. (line 582) * %small_block_associated_command: Texinfo::Common @-COMMAND INFORMATION. (line 805) * %texinfo_output_formats: Texinfo::Common MISC INFORMATION. (line 773) * %text_brace_no_arg_commands: Texinfo::CommandsValues @-COMMAND ASSOCIATED INFORMATION. (line 651) * %unicode_diacritics: Texinfo::CommandsValues @-COMMAND ASSOCIATED INFORMATION. (line 656) * %variadic_commands: Texinfo::Commands @-COMMAND CLASSES. (line 586) * %xml_text_entity_no_arg_commands_formatting: Texinfo::Convert::Converter Conversion to XML. (line 5217) * add_heading_number: Texinfo::Convert::Utils METHODS. (line 4072) * add_to_element_contents: Texinfo::TreeElement METHODS. (line 6058) * ascii_accent_fallback: Texinfo::Convert::Text METHODS. (line 4537) * associate_internal_references: Texinfo::Structuring METHODS. (line 2894) * associated_processing_encoding: Texinfo::Common METHODS. (line 864) * brace_no_arg_command: Texinfo::Convert::Unicode METHODS. (line 4240) * build_tree: Texinfo::Document Methods for Perl and C code interactions. (line 2692) * cache_translate_string: Texinfo::Translations METHODS. (line 3340) * cdt: Texinfo::Convert::Converter Translations in output documents. (line 5063) * cdt_string: Texinfo::Convert::Converter Translations in output documents. (line 5063) * check_node_tree_menu_structure: Texinfo::Structuring METHODS. (line 2916) * check_nodes_are_referenced: Texinfo::Structuring METHODS. (line 2903) * check_unicode_point_conversion: Texinfo::Convert::Unicode METHODS. (line 4247) * children_number: Texinfo::TreeElement METHODS. (line 6031) * cmdname: Texinfo::TreeElement METHODS. (line 6022) * collect_commands_in_tree: Texinfo::Common METHODS. (line 850) * collect_commands_list_in_tree: Texinfo::Common METHODS. (line 857) * comma_index_subentries_tree: Texinfo::Convert::Utils METHODS. (line 4089) * complete_node_tree_with_menus: Texinfo::Structuring METHODS. (line 2911) * complete_tree_nodes_menus_in_document: Texinfo::Transformations METHODS. (line 3414) * complete_tree_nodes_missing_menu: Texinfo::Transformations METHODS. (line 3423) * construct_nodes_tree: Texinfo::Structuring METHODS. (line 2977) * conversion_finalization: Texinfo::Convert::Converter Conversion. (line 4854) * conversion_initialization: Texinfo::Convert::Converter Conversion. (line 4854) * conversion_output_begin: Texinfo::Convert::Converter Conversion. (line 4886) * conversion_output_end: Texinfo::Convert::Converter Conversion. (line 4886) * convert: Texinfo::Convert::Converter DESCRIPTION. (line 4743) * convert_accents: Texinfo::Convert::Converter Accents conversion. (line 5134) * convert_output_unit: Texinfo::Convert::Converter Conversion. (line 4916) * convert_to_identifier: Texinfo::Convert::NodeNameNormalization METHODS. (line 4392) * convert_to_node_identifier: Texinfo::Convert::NodeNameNormalization METHODS. (line 4392) * convert_to_normalized: Texinfo::Convert::NodeNameNormalization METHODS. (line 4382) * convert_to_texinfo: Texinfo::Convert::Texinfo METHODS. (line 4011) * convert_to_text: Texinfo::Convert::Text METHODS. (line 4491) * convert_tree: Texinfo::Convert::Converter DESCRIPTION. (line 4698) * converter: Texinfo::Convert::Converter Converter Initialization. (line 4795) * converter <1>: Texinfo::Convert::Converter Converter Initialization. (line 4800) * converter_defaults: Texinfo::Convert::Converter Converter Initialization. (line 4814) * converter_destroy: Texinfo::Convert::Converter Output units and converter destruction. (line 4967) * converter_document_error: Texinfo::Convert::Converter Registering error and warning messages. (line 5018) * converter_document_warn: Texinfo::Convert::Converter Registering error and warning messages. (line 5018) * converter_initialize: Texinfo::Convert::Converter Converter Initialization. (line 4824) * converter_line_error: Texinfo::Convert::Converter Registering error and warning messages. (line 5028) * converter_line_warn: Texinfo::Convert::Converter Registering error and warning messages. (line 5028) * converter_release_output_units: Texinfo::Convert::Converter Output units and converter destruction. (line 4951) * create_destination_directory: Texinfo::Convert::Converter Helper methods. (line 5237) * definition_arguments_content: Texinfo::Convert::Utils METHODS. (line 4098) * definition_category_tree: Texinfo::Convert::Utils METHODS. (line 4108) * destroy_converter: Texinfo::Convert::Converter Output units and converter destruction. (line 4941) * destroy_converter <1>: Texinfo::Convert::Converter Output units and converter destruction. (line 4960) * destroy_document: Texinfo::Document Methods for Perl and C code interactions. (line 2717) * determine_files_and_directory: Texinfo::Convert::Converter Helper methods. (line 5245) * document_error: Texinfo::Report METHODS. (line 3175) * document_warn: Texinfo::Report METHODS. (line 3175) * element_is_inline: Texinfo::Common METHODS. (line 869) * encoded_accents: Texinfo::Convert::Unicode METHODS. (line 4257) * encoded_input_file_name: Texinfo::Convert::Utils METHODS. (line 4132) * encoded_input_file_name <1>: Texinfo::Convert::Converter Helper methods. (line 5272) * encoded_output_file_name: Texinfo::Convert::Utils METHODS. (line 4132) * encoded_output_file_name <1>: Texinfo::Convert::Converter Helper methods. (line 5272) * enumerate_item_representation: Texinfo::Common METHODS. (line 885) * expand_verbatiminclude: Texinfo::Convert::Utils METHODS. (line 4148) * expand_verbatiminclude <1>: Texinfo::Convert::Converter Helper methods. (line 5375) * fill_gaps_in_sectioning_in_document: Texinfo::Transformations METHODS. (line 3432) * find_innermost_accent_contents: Texinfo::Common METHODS. (line 895) * find_parent_root_command: Texinfo::Common METHODS. (line 904) * float_name_caption: Texinfo::Convert::Converter Helper methods. (line 5294) * float_type_number: Texinfo::Convert::Converter Helper methods. (line 5301) * floats_information: Texinfo::Document Getting document information. (line 2442) * force_conf: Texinfo::Convert::Converter Getting and setting customization variables. (line 4990) * gdt: Texinfo::Translations METHODS. (line 3279) * gdt_string: Texinfo::Translations METHODS. (line 3279) * get_attribute: Texinfo::TreeElement METHODS. (line 6052) * get_child: Texinfo::TreeElement METHODS. (line 6035) * get_children: Texinfo::TreeElement METHODS. (line 6039) * get_conf: Texinfo::Convert::Converter Getting and setting customization variables. (line 4997) * get_converter_errors: Texinfo::Convert::Converter Registering error and warning messages. (line 5042) * get_converter_indices_sorted_by_index: Texinfo::Convert::Converter Index sorting. (line 5097) * get_converter_indices_sorted_by_letter: Texinfo::Convert::Converter Index sorting. (line 5097) * get_document_documentinfo: Texinfo::Convert::Utils METHODS. (line 4164) * get_global_unique_tree_element: Texinfo::Example::TreeElementConverter METHODS. (line 6462) * get_node_node_childs_from_sectioning: Texinfo::Structuring METHODS. (line 2920) * get_tree_element_index_entry: Texinfo::Example::TreeElementConverter METHODS. (line 6449) * global_commands_information: Texinfo::Document Getting document information. (line 2406) * global_commands_information_command_list: Texinfo::Example::TreeElementConverter METHODS. (line 6462) * global_information: Texinfo::Document Getting document information. (line 2374) * index_entry_element_sort_string: Texinfo::Indices METHODS. (line 3576) * indices_information: Texinfo::Document Getting document information. (line 2481) * input_file_encoding: Texinfo::Common METHODS. (line 921) * insert_nodes_for_sectioning_commands: Texinfo::Transformations METHODS. (line 3447) * internal_references_information: Texinfo::Document Getting document information. (line 2456) * is_content_empty: Texinfo::Common METHODS. (line 935) * labels_information: Texinfo::Document Getting document information. (line 2428) * labels_list: Texinfo::Document Getting document information. (line 2433) * line_error: Texinfo::Report METHODS. (line 3151) * line_warn: Texinfo::Report METHODS. (line 3151) * locate_include_file: Texinfo::Common METHODS. (line 941) * menu_to_simple_menu: Texinfo::Transformations METHODS. (line 3452) * merge_indices: Texinfo::Indices METHODS. (line 3610) * merged_indices: Texinfo::Document Merging and sorting indexes. (line 2546) * move_index_entries_after_items_in_document: Texinfo::ManipulateTree METHODS. (line 2781) * new: Texinfo::TreeElement METHODS. (line 6008) * new_block_command: Texinfo::Structuring METHODS. (line 2927) * new_complete_node_menu: Texinfo::Structuring METHODS. (line 2932) * new_detailmenu: Texinfo::Structuring METHODS. (line 2947) * new_lang_translation: Texinfo::Translations METHODS. (line 3258) * new_node_menu_entry: Texinfo::Structuring METHODS. (line 2970) * new_tree_element: Texinfo::Example::TreeElementConverter METHODS. (line 6442) * node_information_filename: Texinfo::Convert::Converter Helper methods. (line 5307) * normalize_top_node_name: Texinfo::Common METHODS. (line 967) * normalize_transliterate_texinfo: Texinfo::Convert::NodeNameNormalization METHODS. (line 4402) * normalized_sectioning_command_filename: Texinfo::Convert::Converter Helper methods. (line 5312) * number_floats: Texinfo::Structuring METHODS. (line 2987) * output: Texinfo::Convert::Converter DESCRIPTION. (line 4710) * output_internal_links: Texinfo::Convert::Converter Helper methods. (line 5383) * output_internal_links <1>: Texinfo::Convert::HTML METHODS. (line 5562) * output_tree: Texinfo::Convert::Converter DESCRIPTION. (line 4710) * parent: Texinfo::TreeElement METHODS. (line 6044) * parse_texi_file: Texinfo::Parser Parsing Texinfo text. (line 1209) * parse_texi_line: Texinfo::Parser Parsing Texinfo text. (line 1185) * parse_texi_piece: Texinfo::Parser Parsing Texinfo text. (line 1193) * parse_texi_text: Texinfo::Parser Parsing Texinfo text. (line 1201) * Parser initialization: Texinfo::Parser Initialization. (line 1122) * parser_errors: Texinfo::Parser Parsing Texinfo text. (line 1217) * pcdt: Texinfo::Convert::Converter Translations in output documents. (line 5083) * pgdt: Texinfo::Translations METHODS. (line 3330) * present_bug_message: Texinfo::Convert::Converter Helper methods. (line 5321) * protect_colon_in_tree: Texinfo::ManipulateTree METHODS. (line 2789) * protect_comma_in_tree: Texinfo::ManipulateTree METHODS. (line 2796) * protect_first_parenthesis: Texinfo::ManipulateTree METHODS. (line 2800) * protect_hashchar_at_line_beginning: Texinfo::Transformations METHODS. (line 3464) * protect_node_after_label_in_tree: Texinfo::ManipulateTree METHODS. (line 2789) * read: Texinfo::Reader METHODS. (line 6197) * reference_to_arg_in_tree: Texinfo::Transformations METHODS. (line 3473) * regenerate_master_menu: Texinfo::Transformations METHODS. (line 3487) * register_document_options: Texinfo::Document Registering information in document. (line 2651) * relate_index_entries_to_table_items_in_document: Texinfo::ManipulateTree METHODS. (line 2805) * reset_options_code: Texinfo::Convert::Text METHODS. (line 4551) * reset_options_encoding: Texinfo::Convert::Text METHODS. (line 4564) * section_level: Texinfo::Common METHODS. (line 979) * section_level_adjusted_command_name: Texinfo::Structuring METHODS. (line 2992) * sectioning_structure: Texinfo::Structuring METHODS. (line 2998) * set_conf: Texinfo::Convert::Converter Getting and setting customization variables. (line 5002) * set_document: Texinfo::Convert::Converter Conversion. (line 4838) * set_document_global_info: Texinfo::Document Registering information in document. (line 2663) * set_global_document_command: Texinfo::Common METHODS. (line 984) * set_global_document_commands: Texinfo::Convert::Converter Helper methods. (line 5326) * set_informative_command_value: Texinfo::Common METHODS. (line 1018) * set_options_code: Texinfo::Convert::Text METHODS. (line 4551) * set_options_encoding: Texinfo::Convert::Text METHODS. (line 4564) * set_options_encoding_if_not_ascii: Texinfo::Convert::Text METHODS. (line 4564) * set_output_encoding: Texinfo::Common METHODS. (line 1027) * setup_index_entry_keys_formatting: Texinfo::Indices METHODS. (line 3630) * skip_children: Texinfo::Reader METHODS. (line 6250) * sort_indices_by_index: Texinfo::Indices METHODS. (line 3637) * sort_indices_by_letter: Texinfo::Indices METHODS. (line 3637) * sorted_indices_by_index: Texinfo::Document Merging and sorting indexes. (line 2565) * sorted_indices_by_letter: Texinfo::Document Merging and sorting indexes. (line 2565) * source_info: Texinfo::TreeElement METHODS. (line 6048) * split_by_node: Texinfo::OutputUnits Output units creation. (line 3816) * split_by_section: Texinfo::OutputUnits Output units creation. (line 3826) * split_custom_heading_command_contents: Texinfo::Common METHODS. (line 1032) * split_pages: Texinfo::OutputUnits Grouping output units in pages. (line 3840) * string_width: Texinfo::Convert::Unicode METHODS. (line 4283) * table_item_content_tree: Texinfo::Convert::Converter Helper methods. (line 5362) * Texinfo tree element extra key: Texinfo::Parser Information available in the extra key. (line 2028) * Texinfo tree element structure: Texinfo::Parser Element keys. (line 1461) * Texinfo tree elements: Texinfo::Parser TEXINFO TREE. (line 1227) * Texinfo::Convert::Converter initialization: Texinfo::Convert::Converter Converter Initialization. (line 4795) * Texinfo::Parser::parser: Texinfo::Parser Initialization. (line 1122) * Texinfo::Reader::new: Texinfo::Reader METHODS. (line 6192) * text: Texinfo::TreeElement METHODS. (line 6026) * text_accents: Texinfo::Convert::Text METHODS. (line 4577) * top_node_filename: Texinfo::Convert::Converter Helper methods. (line 5369) * transliterate_protect_file_name: Texinfo::Convert::NodeNameNormalization METHODS. (line 4417) * transliterate_texinfo: Texinfo::Convert::NodeNameNormalization METHODS. (line 4410) * tree: Texinfo::Document Getting document information. (line 2361) * type: Texinfo::TreeElement METHODS. (line 6018) * unicode_accent: Texinfo::Convert::Unicode METHODS. (line 4289) * unicode_point_decoded_in_encoding: Texinfo::Convert::Unicode METHODS. (line 4298) * unicode_text: Texinfo::Convert::Unicode METHODS. (line 4310) * units_directions: Texinfo::OutputUnits Setting output units directions. (line 3872) * units_file_directions: Texinfo::OutputUnits Setting output units directions. (line 3939) * valid_option: Texinfo::Common METHODS. (line 1041) * valid_tree_transformation: Texinfo::Common METHODS. (line 1045) * warn_non_empty_parts: Texinfo::Structuring METHODS. (line 3037) * xml_accent: Texinfo::Convert::Converter Conversion to XML. (line 5182) * xml_accents: Texinfo::Convert::Converter Conversion to XML. (line 5202) * xml_comment: Texinfo::Convert::Converter Conversion to XML. (line 5178) * xml_format_text_with_numeric_entities: Texinfo::Convert::Converter Conversion to XML. (line 5169) * xml_numeric_entity_accent: Texinfo::Convert::Converter Conversion to XML. (line 5208) * xml_protect_text: Texinfo::Convert::Converter Conversion to XML. (line 5174)

AltStyle によって変換されたページ (->オリジナル) /