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::Common 2.1 Texinfo::Common NAME 2.2 Texinfo::Common SYNOPSIS 2.3 Texinfo::Common NOTES 2.4 Texinfo::Common DESCRIPTION 2.5 MISC INFORMATION 2.6 @-COMMAND INFORMATION 2.7 Texinfo::Common METHODS 2.8 Texinfo::Common SEE ALSO 2.9 Texinfo::Common AUTHOR 2.10 Texinfo::Common COPYRIGHT AND LICENSE 3 Texinfo::Parser 3.1 Texinfo::Parser NAME 3.2 Texinfo::Parser SYNOPSIS 3.3 Texinfo::Parser NOTES 3.4 Texinfo::Parser DESCRIPTION 3.5 Texinfo::Parser METHODS 3.5.1 Initialization 3.5.2 Parsing Texinfo text 3.5.3 Getting information on the document 3.6 TEXINFO TREE 3.6.1 Element keys 3.6.2 Element types 3.6.2.1 Types for command elements 3.6.2.2 Types for text elements 3.6.2.3 Tree container elements 3.6.2.4 Types of container elements 3.6.3 Information available in the ‘info’ key 3.6.4 Information available in the ‘extra’ key 3.6.4.1 Extra keys available for more than one @-command 3.6.4.2 Extra keys specific of certain @-commands or containers 3.7 Texinfo::Parser SEE ALSO 3.8 Texinfo::Parser AUTHOR 3.9 Texinfo::Parser COPYRIGHT AND LICENSE 4 Texinfo::Structuring 4.1 Texinfo::Structuring NAME 4.2 Texinfo::Structuring SYNOPSIS 4.3 Texinfo::Structuring NOTES 4.4 Texinfo::Structuring DESCRIPTION 4.5 Texinfo::Structuring METHODS 4.6 Texinfo::Structuring SEE ALSO 4.7 Texinfo::Structuring AUTHOR 4.8 Texinfo::Structuring COPYRIGHT AND LICENSE 5 Texinfo::Report 5.1 Texinfo::Report NAME 5.2 Texinfo::Report SYNOPSIS 5.3 Texinfo::Report NOTES 5.4 Texinfo::Report DESCRIPTION 5.5 Texinfo::Report METHODS 5.6 Texinfo::Report AUTHOR 5.7 Texinfo::Report COPYRIGHT AND LICENSE 6 Texinfo::Translations 6.1 Texinfo::Translations NAME 6.2 Texinfo::Translations SYNOPSIS 6.3 Texinfo::Translations NOTES 6.4 Texinfo::Translations DESCRIPTION 6.5 Texinfo::Translations METHODS 6.6 Texinfo::Translations AUTHOR 6.7 Texinfo::Translations COPYRIGHT AND LICENSE 7 Texinfo::Transformations 7.1 Texinfo::Transformations NAME 7.2 Texinfo::Transformations NOTES 7.3 Texinfo::Transformations DESCRIPTION 7.4 Texinfo::Transformations METHODS 7.5 Texinfo::Transformations SEE ALSO 7.6 Texinfo::Transformations AUTHOR 7.7 Texinfo::Transformations COPYRIGHT AND LICENSE 8 Texinfo::Convert::Texinfo 8.1 Texinfo::Convert::Texinfo NAME 8.2 Texinfo::Convert::Texinfo SYNOPSIS 8.3 Texinfo::Convert::Texinfo NOTES 8.4 Texinfo::Convert::Texinfo DESCRIPTION 8.5 Texinfo::Convert::Texinfo METHODS 8.6 Texinfo::Convert::Texinfo AUTHOR 8.7 Texinfo::Convert::Texinfo COPYRIGHT AND LICENSE 9 Texinfo::Convert::Utils 9.1 Texinfo::Convert::Utils NAME 9.2 Texinfo::Convert::Utils SYNOPSIS 9.3 Texinfo::Convert::Utils NOTES 9.4 Texinfo::Convert::Utils DESCRIPTION 9.5 Texinfo::Convert::Utils METHODS 9.6 Texinfo::Convert::Utils SEE ALSO 9.7 Texinfo::Convert::Utils AUTHOR 9.8 Texinfo::Convert::Utils COPYRIGHT AND LICENSE 10 Texinfo::Convert::Unicode 10.1 Texinfo::Convert::Unicode NAME 10.2 Texinfo::Convert::Unicode SYNOPSIS 10.3 Texinfo::Convert::Unicode NOTES 10.4 Texinfo::Convert::Unicode DESCRIPTION 10.5 Texinfo::Convert::Unicode METHODS 10.6 Texinfo::Convert::Unicode AUTHOR 10.7 Texinfo::Convert::Unicode COPYRIGHT AND LICENSE 11 Texinfo::Convert::NodeNameNormalization 11.1 Texinfo::Convert::NodeNameNormalization NAME 11.2 Texinfo::Convert::NodeNameNormalization SYNOPSIS 11.3 Texinfo::Convert::NodeNameNormalization NOTES 11.4 Texinfo::Convert::NodeNameNormalization DESCRIPTION 11.5 Texinfo::Convert::NodeNameNormalization METHODS 11.6 Texinfo::Convert::NodeNameNormalization AUTHOR 11.7 Texinfo::Convert::NodeNameNormalization COPYRIGHT AND LICENSE 12 Texinfo::Convert::Text 12.1 Texinfo::Convert::Text NAME 12.2 Texinfo::Convert::Text SYNOPSIS 12.3 Texinfo::Convert::Text NOTES 12.4 Texinfo::Convert::Text DESCRIPTION 12.5 Texinfo::Convert::Text METHODS 12.6 Texinfo::Convert::Text AUTHOR 12.7 Texinfo::Convert::Text COPYRIGHT AND LICENSE 13 Texinfo::Convert::Converter 13.1 Texinfo::Convert::Converter NAME 13.2 Texinfo::Convert::Converter SYNOPSIS 13.3 Texinfo::Convert::Converter NOTES 13.4 Texinfo::Convert::Converter DESCRIPTION 13.5 Texinfo::Convert::Converter METHODS 13.5.1 Initialization 13.5.2 Getting and setting customization variables 13.5.3 Conversion to XML 13.5.4 Helper methods 13.6 Texinfo::Convert::Converter SEE ALSO 13.7 Texinfo::Convert::Converter AUTHOR 13.8 Texinfo::Convert::Converter COPYRIGHT AND LICENSE 14 Texinfo::Convert::Info 14.1 Texinfo::Convert::Info NAME 14.2 Texinfo::Convert::Info SYNOPSIS 14.3 Texinfo::Convert::Info NOTES 14.4 Texinfo::Convert::Info DESCRIPTION 14.5 Texinfo::Convert::Info METHODS 14.6 Texinfo::Convert::Info AUTHOR 14.7 Texinfo::Convert::Info COPYRIGHT AND LICENSE 15 Texinfo::Convert::HTML 15.1 Texinfo::Convert::HTML NAME 15.2 Texinfo::Convert::HTML SYNOPSIS 15.3 Texinfo::Convert::HTML NOTES 15.4 Texinfo::Convert::HTML DESCRIPTION 15.5 Texinfo::Convert::HTML METHODS 15.6 Texinfo::Convert::HTML AUTHOR 15.7 Texinfo::Convert::HTML COPYRIGHT AND LICENSE 16 Texinfo::Convert::DocBook 16.1 Texinfo::Convert::DocBook NAME 16.2 Texinfo::Convert::DocBook SYNOPSIS 16.3 Texinfo::Convert::DocBook NOTES 16.4 Texinfo::Convert::DocBook DESCRIPTION 16.5 Texinfo::Convert::DocBook METHODS 16.6 Texinfo::Convert::DocBook AUTHOR 16.7 Texinfo::Convert::DocBook COPYRIGHT AND LICENSE 17 Texinfo::Convert::TexinfoMarkup 17.1 Texinfo::Convert::TexinfoMarkup NAME 17.2 Texinfo::Convert::TexinfoMarkup SYNOPSIS 17.3 Texinfo::Convert::TexinfoMarkup NOTES 17.4 Texinfo::Convert::TexinfoMarkup DESCRIPTION 17.5 Texinfo::Convert::TexinfoMarkup METHODS 17.5.1 Markup formatting methods defined by subclasses 17.5.2 Formatting state information 17.6 Texinfo::Convert::TexinfoMarkup AUTHOR 17.7 Texinfo::Convert::TexinfoMarkup SEE ALSO 17.8 Texinfo::Convert::TexinfoMarkup COPYRIGHT AND LICENSE 18 Texinfo::Convert::TexinfoXML 18.1 Texinfo::Convert::TexinfoXML NAME 18.2 Texinfo::Convert::TexinfoXML SYNOPSIS 18.3 Texinfo::Convert::TexinfoXML NOTES 18.4 Texinfo::Convert::TexinfoXML DESCRIPTION 18.5 Texinfo::Convert::TexinfoXML METHODS 18.6 Texinfo::Convert::TexinfoXML AUTHOR 18.7 Texinfo::Convert::TexinfoXML COPYRIGHT AND LICENSE 19 Texinfo::Convert::Plaintext 19.1 Texinfo::Convert::Plaintext NAME 19.2 Texinfo::Convert::Plaintext SYNOPSIS 19.3 Texinfo::Convert::Plaintext NOTES 19.4 Texinfo::Convert::Plaintext DESCRIPTION 19.5 Texinfo::Convert::Plaintext METHODS 19.6 Texinfo::Convert::Plaintext AUTHOR 19.7 Texinfo::Convert::Plaintext 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 *note ‘Texinfo::Parser::indices_information’: Texinfo::Parser $indices_information = $parser->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’. %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 ============================== *note 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::Common ***************** 2.1 Texinfo::Common NAME ======================== Texinfo::Common - Texinfo modules common data and miscellaneous methods 2.2 Texinfo::Common SYNOPSIS ============================ use Texinfo::Common; my @commands_to_collect = ('math'); my $collected_commands = Texinfo::Common::collect_commands_in_tree($document_root, \@commands_to_collect); 2.3 Texinfo::Common NOTES ========================= The Texinfo Perl module main purpose is to be used in ‘texi2any’ to convert Texinfo to other formats. There is no promise of API stability. 2.4 Texinfo::Common DESCRIPTION =============================== Texinfo::Common holds hashes with miscellaneous information and some hashes with information on Texinfo @-commands, as well as miscellaneous methods. 2.5 MISC INFORMATION ==================== Hashes are defined as ‘our’ variables, and are therefore available outside of the module. TODO: undocumented %null_device_file %default_parser_customization_values %document_settable_multiple_at_commands %document_settable_unique_at_commands %default_converter_command_line_options %default_main_program_customization_options %default_converter_customization @variable_string_settables %document_settable_at_commands %def_map %command_structuring_level %level_to_structuring_command %encoding_name_conversion_map %texinfo_output_formats Cannonical output formats that have associated conditionals. In practice corresponds to ‘format_raw’ ‘%block_commands’ plus ‘info’ and ‘plaintext’. 2.6 @-COMMAND INFORMATION ========================= Hashes are defined as ‘our’ variables, and are therefore available outside of the module. The key of the hashes are @-command names without the @. The following hashes are available: %all_commands All the @-commands. %def_aliases %def_no_var_arg_commands ‘%def_aliases’ associates an aliased command to the original command, for example ‘defun’ is associated to ‘deffn’. ‘%def_no_var_arg_commands’ associates a definition command name with a true value if the _argument_ on the definition command line can contain non-metasyntactic variables. For instance, it is true for ‘deftypevr’ but false for ‘defun’, since ‘@defun’ _argument_ is supposed to contain metasyntactic variables only. %nobrace_symbol_text Values are ASCII representation of single character non-alphabetical commands without brace such as ‘*’ or ‘:’. The value may be an empty string. %non_formatted_brace_commands Brace commands that are not immediately replaced with text, such as ‘anchor’, ‘caption’, ‘errormsg’ and others. %small_block_associated_command Associate small command like ‘smallexample’ to the regular command ‘example’. 2.7 Texinfo::Common METHODS =========================== Two methods are exported in the default case for Texinfo modules messages translation in the Uniforum gettext framework, ‘__’ and ‘__p’. The Texinfo tree and Texinfo tree elements used in argument of some functions are documented in *note 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 *note 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 *note (libintl-perl)::, ‘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 *note 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 = element_associated_processing_encoding($element) Returns the encoding name that can be used for decoding derived from the encoding that was set where _$element_ appeared. $result = element_is_inline($element, $check_current) Return true if the element passed in argument is in running text context. If the optional _$check_current_ argument is set, check the element itself, in addition to the parent context. ($encoded_file_name, $encoding) = encode_file_name($file_name, $input_encoding) Encode the _$file_name_ text string to a binary string _$encoded_file_name_ based on _$input_encoding_. Also returns the _$encoding_ name actually used which may have undergone some normalization. This function is mostly a wrapper around *note Encode::encode: (Encode)encode. which avoids calling the module if not needed. Do nothing if _$input_encoding_ is ‘undef’. $text = enumerate_item_representation($specification, $number) This function returns the number or letter correponding to item number _$number_ for an ‘@enumerate’ specification _$specification_, appearing on an ‘@enumerate’ line. For example enumerate_item_representation('c', 3) is ‘e’. $command = find_parent_root_command($object, $tree_element) Find the parent root command (sectioning command or node) of a tree element. The _$object_ argument is optional, its ‘global_commands’ field is used to continue through ‘@insertcopying’ if in a ‘@copying’. $entry_content_element = index_content_element($element, $prefer_reference_element) Return a Texinfo tree element corresponding to the content of the index entry associated to _$element_. If _$prefer_reference_element_ is set, prefer an untranslated element. If the element is an index command like ‘@cindex’ or an ‘@ftable’ ‘@item’, the content element is the argument of the command. If the element is a definition line, the index entry element is based on the name and class. $result = is_content_empty($tree, $do_not_ignore_index_entries) Return true if the _$tree_ has content that could be formatted. _$do_not_ignore_index_entries_ is optional. If set, index entries are considered to be formatted. $file = locate_include_file($customization_information, file_path) Locate _$file_path_. If _$file_path_ is an absolute path or has ‘.’ or ‘..’ in the path directories it is checked that the path exists and is a file. Otherwise, the file name in _$file_path_ is located in include directories also used to find texinfo files included in Texinfo documents. _$file_path_ should be a binary string. ‘undef’ is returned if the file was not found, otherwise the file found is returned as a binary string. ($index_entry, $index_info) = lookup_index_entry($index_entry_info, $indices_information) Returns an _$index_entry_ hash based on the _$index_entry_info_ and _$indices_information_. Also returns the _$index_info_ hash with information on the index associated to the index entry. _$index_entry_info_ should be an array reference with an index name as first element and the index entry number in that index (1-based) as second element. In general, the _$index_entry_info_ is an *note ‘extra’ _index_entry_: Texinfo::Parser index_entry. associated to an element. The _$index_entry_ hash is described in *note Texinfo::Parser index_entries::. The _$index_info_ hash is described in L*note ‘Texinfo::Parser::indices_information’: Texinfo::Parser $indices_information = $parser->indices_information(). move_index_entries_after_items_in_tree($tree) In ‘@enumerate’ and ‘@itemize’ from the tree, move index entries appearing just before ‘@item’ after the ‘@item’. Comment lines between index entries are moved too. relate_index_entries_to_table_items_in_tree($tree) In tables, relate index entries preceding and following an entry with said item. Reference one of them in the entry's ‘entry_associated_element’. $normalized_name = normalize_top_node_name($node_string) Normalize the node name string given in argument, by normalizing Top node case. 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. $contents_result = protect_first_parenthesis($contents) Return a contents array reference with first parenthesis in the contents array reference protected. If _$contents_ is undef a fatal error with a backtrace will be emitted. $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 parser *note $parser->global_commands_information(): Texinfo::Parser $commands = global_commands_information($parser). _$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_encodings($customization_information, $parser_information) If not already set, set ‘OUTPUT_ENCODING_NAME’ based on input file encoding. Also set ‘OUTPUT_PERL_ENCODING’ accordingly which is used to output in the correct encoding. In general, ‘OUTPUT_PERL_ENCODING’ should not be set directly by user-defined code such that it corresponds to ‘OUTPUT_ENCODING_NAME’. $split_contents = split_custom_heading_command_contents($contents) Split the _$contents_ array reference at ‘@|’ in at max three parts. Return an array reference containing the split parts. The _$contents_ array reference is supposed to be ‘$element->{'args'}->[0]->{'contents'}’ of ‘%Texinfo::Commands::heading_spec_commands’ commands such as ‘@everyheading’. trim_spaces_comment_from_content($contents) Remove empty spaces after commands or braces at begin and spaces and comments at end from a content array, modifying it. $status = valid_customization_option($name) Return true if the _$name_ is a known customization option. $status = valid_tree_transformation($name) Return true if the _$name_ is a known tree transformation name that may be passed with ‘TREE_TRANSFORMATIONS’ to modify a texinfo tree. 2.8 Texinfo::Common SEE ALSO ============================ *note Texinfo::Parser: Texinfo::Parser NAME, *note Texinfo::Convert::Converter: Texinfo::Convert::Converter NAME. and *note Texinfo::Report: Texinfo::Report NAME. 2.9 Texinfo::Common AUTHOR ========================== Patrice Dumas, 2.10 Texinfo::Common COPYRIGHT AND LICENSE ========================================== Copyright 2010- Free Software Foundation, Inc. See the source file for all copyright years. This library is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version. 3 Texinfo::Parser ***************** 3.1 Texinfo::Parser NAME ======================== Texinfo::Parser - Parse Texinfo code into a Perl tree 3.2 Texinfo::Parser SYNOPSIS ============================ use Texinfo::Parser; my $parser = Texinfo::Parser::parser(); my $tree = $parser->parse_texi_file("somefile.texi"); # a Texinfo::Report object in which the errors and warnings # encountered while parsing are registered. my $registrar = $parser->registered_errors(); my ($errors, $errors_count) = $registrar->errors(); foreach my $error_message (@$errors) { warn $error_message->{'error_line'}; } my $indices_information = $parser->indices_information(); my $float_types_arrays = $parser->floats_information(); my $internal_references_array = $parser->internal_references_information(); # $labels_information is an hash reference on normalized node/float/anchor names. my ($labels_information, $targets_list, $nodes_list) = $parser->labels_information(); # A hash reference, keys are @-command names, value is an # array reference holding all the corresponding @-commands. my $global_commands_information = $parser->global_commands_information(); # a hash reference on document information (encodings, # input file name, dircategory and direntry list, for example). my $global_information = $parser->global_information(); 3.3 Texinfo::Parser NOTES ========================= The Texinfo Perl module main purpose is to be used in ‘texi2any’ to convert Texinfo to other formats. There is no promise of API stability. 3.4 Texinfo::Parser DESCRIPTION =============================== ‘Texinfo::Parser’ will parse Texinfo text into a Perl tree. In one pass it expands user-defined @-commands, conditionals (‘@ifset’, ‘@ifinfo’...) and ‘@value’ and constructs the tree. Some extra information is gathered while doing the tree: for example, the ‘@quotation’ associated to an ‘@author’ command, the number of columns in a multitable, or the node associated with a section. 3.5 Texinfo::Parser METHODS =========================== No method is exported in the default case. The module allows both an object-oriented syntax, or traditional function, with the parser as an opaque data structure given as an argument to every function. 3.5.1 Initialization -------------------- The following method is used to construct a new ‘Texinfo::Parser’ object: $parser = Texinfo::Parser::parser($options); This method creates a new parser. The options may be provided as a hash reference. Most of those options correspond to Texinfo customization options described in the Texinfo manual. CPP_LINE_DIRECTIVES Handle cpp like synchronization lines if set. Set in the default case. EXPANDED_FORMATS An array reference of the output formats for which ‘@if_FORMAT_’ conditional blocks should be expanded. Default is empty. FORMAT_MENU Possible values are ‘nomenu’, ‘menu’ and ‘sectiontoc’. Only report menu-related errors for ‘menu’. INCLUDE_DIRECTORIES An array reference of directories in which ‘@include’ files should be searched for. Default contains the working directory, ‘.’. IGNORE_SPACE_AFTER_BRACED_COMMAND_NAME If set, spaces after an @-command name that take braces are ignored. Default on. MAX_MACRO_CALL_NESTING Maximal number of nested user-defined macro calls. Default is 100000. documentlanguage A string corresponding to a document language set by ‘@documentlanguage’. It overrides the document ‘@documentlanguage’ information, if present. registrar *note Texinfo::Report: Texinfo::Report NAME. object reused by the parser to register errors. values A hash reference. Keys are names, values are the corresponding values. Same as values set by ‘@set’. 3.5.2 Parsing Texinfo text -------------------------- Different methods may be called to parse some Texinfo code: ‘parse_texi_line’ for a line, ‘parse_texi_piece’ for a fragment of Texinfo, ‘parse_texi_text’ for a string corresponding to a full document and ‘parse_texi_file’ for a file. For all those functions, if the _$parser_ argument is undef, a new parser object is generated to parse the line. Otherwise the parser given as an argument is used to parse into a tree. 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 = parse_texi_line($parser, $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. $tree = parse_texi_piece($parser, $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. $tree = parse_texi_text($parser, $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. $tree = parse_texi_file($parser, $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. undef is returned if the file couldn't be read. The errors collected during the tree parsing are registered in a *note Texinfo::Report: Texinfo::Report NAME. object. This object is available with ‘registered_errors’. The errors registered in the ‘Texinfo::Report’ object are available through the ‘errors’ method. This method is described in *note Texinfo::Report::errors: Texinfo::Report ($error_warnings_list, $error_count) = errors($registrar). $registrar = registered_errors($parser) _$registrar_ is a *note Texinfo::Report: Texinfo::Report NAME. object in which the errors and warnings encountered while parsing are registered. If a _registrar_ is passed to the parser initialization options, it is reused, otherwise a new one is created. 3.5.3 Getting information on the document ----------------------------------------- After parsing some information about the Texinfo code that was processed is available from the parser. Some global information is available through ‘global_information’: $info = global_information($parser) The _$info_ returned is a hash reference. The possible keys are dircategory_direntry An array of successive ‘@dircategory’ and ‘@direntry’ as they appear in the document. input_encoding_name input_perl_encoding ‘input_encoding_name’ string is the encoding name used for the Texinfo code. ‘input_perl_encoding’ string is a corresponding Perl encoding name. input_file_name input_directory The name of the main Texinfo input file and the associated directory. Binary strings. In ‘texi2any’, they should come from the command line (and can be decoded with the encoding in the customization variable ‘COMMAND_LINE_ENCODING’). Some command lists are available, such that it is possible to go through the corresponding tree elements without walking the tree. They are available through ‘global_commands_information’: $commands = global_commands_information($parser) _$commands_ is an hash reference. The keys are @-command names. The associated values are array references containing all the corresponding tree elements. All the @-commands that have an associated label (so can be the target of cross references) -- ‘@node’, ‘@anchor’ and ‘@float’ with label -- have a normalized name associated, constructed as described in the _HTML Xref_ node in the Texinfo documentation. Those normalized labels and the association with @-commands is available through ‘labels_information’: $labels_information, $targets_list, $nodes_list = labels_information($parser) _$labels_information_ is a hash reference whose keys are normalized labels, and the associated value is the corresponding @-command. _$targets_list_ is a list of labels @-command. Using _$labels_information_ is preferred. _$nodes_list_ is a list of all the nodes appearing in the document. Information on ‘@float’ is also available, grouped by type of floats, each type corresponding to potential ‘@listoffloats’. This information is available through the method ‘floats_information’. $float_types = floats_information($parser) _$float_types_ is a hash reference whose keys are normalized float types (the first float argument, or the ‘@listoffloats’ argument). The normalization is the same as for the first step of node names normalization. The value is the list of float tree elements appearing in the texinfo document. Internal references, that is, @-commands that refer to node, anchors or floats within the document are also available: $internal_references_array = internal_references_information($parser) The function returns a list of cross-reference commands referring to the same document. Information about defined indices, merged indices and index entries is also available through the ‘indices_information’ method. $indices_information = $parser->indices_information() _$indices_information_ is a hash reference. The keys are in_code 1 if the index entries should be formatted as code, 0 in the opposite case. name The index name. prefix An array reference of prefix associated to the index. merged_in In case the index is merged to another index, this key holds the name of the index the index is merged into. It takes into account indirectly merged indices. contained_indices An hash reference holding names of indices that are merged into the index, including itself. It also contains indirectly merged indices. This key is removed if the index is itself later merged to another index. index_entries An array reference containing index entry structures for index entries associated with the index. The index entry could be associated to @-commands like ‘@cindex’, or ‘@item’ in ‘@vtable’, or definition commands entries like ‘@deffn’. The keys of the index entry structures are index_name The index name associated to the command. Not modified if the corresponding index is merged in another index (with ‘@synindex’, for example). entry_element The element in the parsed tree associated with the @-command holding the index entry. entry_number The number of the index entry. The following shows the references corresponding to the default indexes _cp_ and _fn_, the _fn_ index having its entries formatted as code and the indices corresponding to the following texinfo @defindex some @defcodeindex code $index_names = {'cp' => {'name' => 'cp', 'in_code' => 0, }, 'fn' => {'name' => 'fn', 'in_code' => 1, }, 'some' => {'in_code' => 0}, 'code' => {'in_code' => 1}}; If ‘name’ is not set, it is set to the index name. 3.6 TEXINFO TREE ================ A Texinfo tree element (called element because node is overloaded in the Texinfo world) is an hash reference. There are three main categories of tree element. Tree elements associated with an @-command have a ‘cmdname’ key holding the @-command name. Tree elements corresponding to text fragments have a ‘text’ key holding the corresponding text. Finally, the last category is other elements, which in most cases have a ‘type’ key holding their name. Text fragments and @-command elements may also have an associated type when such information is needed. The children of an @-command or of other container element are in the array referred to with the ‘args’ key or with the ‘contents’ key. The ‘args’ key is for arguments of @-commands, either in braces or on the rest of the line after the command, depending on the type of command. The ‘contents’ key array holds the contents of the texinfo code appearing within a block @-command, within a container, or within a ‘@node’ or sectioning @-command. Another important key for the elements is the ‘extra’ key which is associated to a hash reference and holds all kinds of information that is gathered during the parsing and may help with the conversion. You can see examples of the tree structure by running makeinfo like this: makeinfo -c DUMP_TREE=1 -c TEXINFO_OUTPUT_FORMAT=parse document.texi For a simpler, more regular representation of the tree structure, you can do: makeinfo -c TEXINFO_OUTPUT_FORMAT=debugtree document.texi 3.6.1 Element keys ------------------ cmdname The command name of @-command elements. text The text fragment of text elements. type The type of element considered, in general a container. Frequent types encountered are _paragraph_ for a paragraph container, _brace_command_arg_ for the container holding the brace @-commands contents, _line_arg_ and _block_line_arg_ contain the arguments appearing on the line of @-commands. Text fragments may have a type to give an information of the kind of text fragment, for example _spaces_before_paragraph_ is associated to spaces appearing before a paragraph beginning. Most @-commands elements do not have a type associated. args Arguments in braces or on @-command line. An array reference. contents The Texinfo appearing in the element. For block commands, other containers, ‘@node’ and sectioning commands. An array reference. parent The parent element. source_info An hash reference corresponding to information on the location of the element in the Texinfo input manual. It should mainly be available for @-command elements, and only for @-commands that are considered to be complex enough that the location in the document is needed, for example to prepare an error message. The keys of the line number hash references are line_nr The line number of the @-command. file_name The file name where @-command appeared. macro The user macro name the @-command is expanded from. info A hash reference holding any other information that cannot be obtained otherwise from the tree. See *note 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 *note Information available in the ‘extra’ key: Texinfo::Parser Information available in the extra key. 3.6.2 Element types ------------------- 3.6.2.1 Types for command elements .................................. Some types can be associated with @-commands (in addition to ‘cmdname’), although usually there will be no type at all. The following are the possible values of ‘type’ for tree elements for @-commands. command_as_argument This is the type of a command given in argument of ‘@itemize’, ‘@table’, ‘@vtable’ or ‘@ftable’. For example in @itemize @bullet @item item @end itemize the element corresponding with bullet has the following keys: 'cmdname' => 'bullet' 'type' => 'command_as_argument' The parent @-command has an entry in ‘extra’ for the _command_as_argument_ element: 'cmdname' => 'itemize' 'extra' => {'command_as_argument' => $command_element_as_argument} def_line This type may be associated with a definition command with a x form, like ‘@defunx’, ‘@defvrx’. For the form without x, the associated _def_line_ is the first ‘contents’ element. It is described in more details below. 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. 3.6.2.2 Types for text elements ............................... The text elements may have the following types (or may have no type at all): after_menu_description_line space_at_end_menu_node Space after a node in the menu entry, when there is no description, and space appearing after the description line. 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 takes argument on the line, but which is followed by ignorable spaces, such as ‘@item’ in ‘@itemize’ or ‘@multitable’, or ‘@noindent’. spaces_after_close_brace Spaces appearing after a closing brace, for some rare commands for which this space should be ignorable (like ‘@caption’ or ‘@sortas’). spaces_before_paragraph Space appearing before a paragraph beginning. raw Text in an environment where it should be kept as is (in ‘@verbatim’, ‘@verb’, ‘@macro’ body). rawline_arg Used for the arguments to some special line commands whose arguments aren't subject to the usual macro expansion. For example ‘@set’, ‘@clickstyle’, ‘@unmacro’, ‘@comment’. The argument is associated to the _text_ key. spaces_at_end Space within an index @-command before an @-command interrupting the index command. text_after_end Text appearing after @bye. text_before_beginning Text appearing before real content, including the ‘\input texinfo.tex’. untranslated English text added by the parser that may need to be translated during conversion. Happens for ‘@def*’ @-commands aliases that leads to prepending text such as 'Function'. 3.6.2.3 Tree container elements ............................... Some types of element are containers of portions of the tree, either for the whole tree, or for contents appearing before ‘@node’ and sectioning commands. before_node_section Content before nodes and sectioning commands at the beginning of ‘document_root’. document_root root_line ‘root_line’ is the type of the root tree when parsing Texinfo line fragments using ‘parse_texi_line’. ‘document_root’ is the document root otherwise. ‘document_root’ first content should be ‘before_node_section’, then nodes and sections @-commands elements, ‘@bye’ element and ‘postamble_after_end’. postamble_after_end This container holds everything appearing after @bye. preamble_before_beginning This container holds everything appearing before the first content, including the ‘\input texinfo.tex’ line and following blank lines. preamble_before_setfilename This container holds everything that appears before ‘@setfilename’. preamble_before_content This container holds everything appearing before the first formatted content, corresponding to the _preamble_ in the Texinfo documentation. 3.6.2.4 Types of container elements ................................... The other types of element are containers with other elements appearing in their ‘contents’. The ‘paragraph’ container holds normal text from the Texinfo manual outside of any @-commands, and within @-commands with blocks of text (‘@footnote’, ‘@itemize’ ‘@item’, ‘@quotation’ for example). The ‘preformatted’ container holds the content appearing in @-commands like ‘@example’ and the ‘rawpreformatted’ container holds the content appearing in format commands such as ‘@html’. The other containers are more specific. The types of container element are the following: balanced_braces Special type containing balanced braces content (braces included) in the context where they are valid, and where balanced braces need to be collected to know when a top-level brace command is closed. In ‘@math’, in raw output format brace commands and within brace @-commands in raw output format block commands. before_item A container for content before the first ‘@item’ of block @-commands with items (‘@table’, ‘@multitable’, ‘@enumerate’...). brace_command_arg brace_command_context line_arg block_line_arg following_arg Those containers occur within the ‘args’ array of @-commands taking an argument. _brace_command_arg_ is used for the arguments to commands taking arguments surrounded by braces (and in some cases separated by commas). _brace_command_context_ is used for @-commands with braces that start a new context (‘@footnote’, ‘@caption’, ‘@math’). _line_arg_ is used for commands that take the texinfo code on the rest of the line as their argument, such as ‘@settitle’, ‘@node’, ‘@section’. _block_line_arg_ is similar but is used for commands that start a new block (which is to be ended with ‘@end’). _following_arg_ is used for the accent @-commands argument that did not use braces but instead followed the @-command, possibly after a space, as @~n @ringaccent A For example @code{in code} leads to {'cmdname' => 'code', 'args' => [{'type' => 'brace_command_arg', 'contents' => [{'text' => 'in code'}]}]} As an exception, ‘@value’ flag argument is directly in the _args_ array reference, not in a _brace_command_arg_ container. Note that only ‘@value’ commands that are not expanded because there is no corresponding value set are present as elements in the tree. bracketed_arg Bracketed argument. On definition command and on ‘@multitable’ line. bracketed_linemacro_arg Argument of a user defined linemacro call in bracket. It holds directly the argument text (which does not contain the braces) and does not contain other elements. It should not appear directly in the tree as the user defined linemacro call is replaced by the linemacro body. def_aggregate Contains several elements that together are a single unit on a @def* line. def_line def_item inter_def_item The _def_line_ type is either associated with a container within a definition command, or is the type of a definition command with a x form, like ‘@deffnx’, or ‘@defline’. It holds the definition line arguments. 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. macro_call rmacro_call linemacro_call Container holding the arguments of a user defined macro, linemacro or rmacro. It should not appear directly in the tree as the user defined call is expanded. The name of the macro, rmacro or linemacro is the the info _command_name_ value. macro_name macro_arg Taken from ‘@macro’ definition and put in the ‘args’ key array of the macro, _macro_name_ is the type of the text fragment corresponding to the macro name, _macro_arg_ is the type of the text fragments corresponding to macro formal arguments. menu_comment The _menu_comment_ container holds what is between menu entries in menus. For example, in: @menu Menu title * entry:: Between entries * other:: @end menu Both Menu title and Between entries will be in a _menu_comment_. menu_entry menu_entry_leading_text menu_entry_name menu_entry_separator menu_entry_node menu_entry_description A _menu_entry_ holds a full menu entry, like * node:: description. The different elements of the menu entry are in the _menu_entry_ ‘contents’ array reference. _menu_entry_leading_text_ holds the star and following spaces. _menu_entry_name_ is the menu entry name (if present), _menu_entry_node_ corresponds to the node in the menu entry, _menu_entry_separator_ holds the text after the node and before the description, in most cases ‘:: ’. Lastly, _menu_entry_description_ is for the description. multitable_head multitable_body row In ‘@multitable’, a _multitable_head_ container contains all the rows with ‘@headitem’, while _multitable_body_ contains the rows associated with ‘@item’. A _row_ container contains the ‘@item’ and ‘@tab’ forming a row. paragraph A paragraph. The ‘contents’ of a paragraph (like other container elements for Texinfo content) are elements representing the contents of the paragraph in the order they occur, such as text elements without a ‘cmdname’ or ‘type’, or @-command elements for commands appearing in the paragraph. preformatted Texinfo code within a format that is not filled. Happens within some block commands like ‘@example’, but also in menu (in menu descriptions, menu comments...). rawpreformatted Texinfo code within raw output format block commands such as ‘@tex’ or ‘@html’. table_entry table_term table_definition inter_item Those containers appear in ‘@table’, ‘@ftable’ and ‘@vtable’. A _table_entry_ container contains an entire row of the table. It contains a _table_term_ container, which holds all the ‘@item’ and ‘@itemx’ lines. This is followed by a _table_definition_ container, which holds the content that is to go into the second column of the table. If there is any content before an ‘@itemx’ (normally only comments, empty lines or maybe index entries are allowed), it will be in a container with type _inter_item_ at the same level of ‘@item’ and ‘@itemx’, in a _table_term_. 3.6.3 Information available in the ‘info’ key --------------------------------------------- arg_line The string correspond to the line after the @-command for @-commands that have special arguments on their line, and for ‘@macro’ line. command_name The name of the user defined macro, rmacro or linemacro called associated with the element holding the arguments of the user defined command call. delimiter ‘@verb’ delimiter is in _delimiter_. spaces_after_argument A reference to an element containing the spaces after @-command arguments before a comma, a closing brace or at end of line, for some @-commands and bracketed content type with opening brace, and line commands and block command lines taking Texinfo as argument and comma delimited arguments. Depending on the @-command, the _spaces_after_argument_ is associated with the @-command element, or with each argument element. spaces_after_cmd_before_arg For accent commands with spaces following the @-command, like: @ringaccent A @^ u there is a _spaces_after_cmd_before_arg_ key linking to an element containing the spaces appearing after the command in _text_. Space between a brace @-command name and its opening brace also ends up in _spaces_after_cmd_before_arg_. It is not recommended to leave space between an @-command name and its opening brace. spaces_before_argument A reference to an element containing the spaces following the opening brace of some @-commands with braces and bracketed content type, spaces following @-commands for line commands and block command taking Texinfo as argument, and spaces following comma delimited arguments. For context brace commands, line commands and block commands, _spaces_before_argument_ is associated with the @-command element, for other brace commands and for spaces after comma, it is associated with each argument element. 3.6.4 Information available in the ‘extra’ key ---------------------------------------------- 3.6.4.1 Extra keys available for more than one @-command ........................................................ element_node The node element in the parsed tree containing the element. Set for @-commands elements that have an associated index entry and for ‘@nodedescription’. element_region The region command (‘@copying’, ‘@titlepage’) containing the element, if it is in such an environement. Set for @-commands elements that have an associated index entry and for @anchor. index_entry The index entry information is associated to @-commands that have an associated index entry. The associated information should not be directly accessed, instead *note ‘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. The _$indices_information_ is the information on a Texinfo manual indices obtained from *note ‘Texinfo::Parser::indices_information’: Texinfo::Parser $indices_information = $parser->indices_information(). The index entry information hash returned by ‘Texinfo::Common::lookup_index_entry’ is described in *note index_entries: Texinfo::Parser 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’. missing_argument Set for some @-commands with line arguments and a missing argument. text_arg The string correspond to the line after the @-command for @-commands that have an argument interpreted as simple text, like ‘@setfilename’, ‘@end’ or ‘@documentencoding’. 3.6.4.2 Extra keys specific of certain @-commands or containers ............................................................... ‘@abbr’ ‘@acronym’ The first argument normalized is in _normalized_. ‘@anchor’ ‘@float’ @-commands that are targets for cross-references have a _normalized_ key for the normalized label, built as specified in the Texinfo documentation in the _HTML Xref_ node. There is also a _node_content_ key for an array holding the corresponding content. ‘@author’ If in a ‘@titlepage’, the titlepage is in _titlepage_, if in ‘@quotation’ or ‘@smallquotation’, the corresponding tree element is in _quotation_. The author tree element is in the _authors_ array of the ‘@titlepage’ or the ‘@quotation’ or ‘@smallquotation’ it is associated with. ‘@click’ In _clickstyle_ there is the current clickstyle command. definition command _def_command_ holds the command name, without x if it is an x form of a definition command. _original_def_cmdname_ is the original def command. If it is an x form, it has _not_after_command_ set if not appearing after the definition command without x. ‘def_line’ For each element in a ‘def_line’, the key _def_role_ holds a string describing the meaning of the element. It is one of _category_, _name_, _class_, _type_, _arg_, _typearg_, _spaces_ or _delimiter_, depending on the definition. 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 ‘def_line’ 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 for the ‘def_line’, signaling that the space between function definition name and arguments should be omitted. ‘@definfoenclose’ defined commands _begin_ holds the string beginning the ‘@definfoenclose’, _end_ holds the string ending the ‘@definfoenclose’. ‘@documentencoding’ The argument, normalized is in _input_encoding_name_. ‘@enumerate’ The _enumerate_specification_ ‘extra’ key contains the enumerate argument. ‘@float’ ‘@listoffloats’ If ‘@float’ has a first argument, and for ‘@listoffloats’ argument there is a _float_type_ key with the normalized float type. _caption_ and _shortcaption_ hold the corresponding tree elements associated to a ‘@float’. The ‘@caption’ or ‘@shortcaption’ have the float tree element stored in _float_. index entry @-command ‘@subentry’ If an index entry @-command, such as ‘@cindex’, or a ‘@subentry’ contains a ‘@sortas’ command, _sortas_ holds the ‘@sortas’ command content formatted as plain text. _subentry_ links to the next level ‘@subentry’ element. Index entry @-command (but not ‘@subentry’) can also have _seentry_ and _seealso_ keys that link to the corresponding @-commands elements. ‘@inlinefmt’ ‘@inlineraw’ ‘@inlinefmtifelse’ ‘@inlineifclear’ ‘@inlineifset’ The first argument is in _format_. If an argument has been determined as being expanded by the Parser, the index of this argument is in _expand_index_. Index numbering begins at 0, but the first argument is always the format or flag name, so, if set, it should be 1 or 2 for ‘@inlinefmtifelse’, and 1 for other commands. ‘@item’ in ‘@enumerate’ or ‘@itemize’ The _item_number_ ‘extra’ key holds the number of this item. ‘@item’ and ‘@tab’ in ‘@multitable’ The _cell_number_ index key holds the index of the column of the cell. ‘@itemize’ ‘@table’ ‘@vtable’ ‘@ftable’ The _command_as_argument_ ‘extra’ key points to the @-command on as argument on the @-command line. If the command in argument for ‘@table’, ‘@vtable’ or ‘@ftable’ is ‘@kbd’ and the context and ‘@kbdinputstyle’ is such that ‘@kbd’ should be formatted as code, the _command_as_argument_kbd_code_ ‘extra’ key is set to 1. ‘@kbd’ _code_ is set depending on the context and ‘@kbdinputstyle’. ‘@macro’ _invalid_syntax_ is set if there was an error on the ‘@macro’ line. ‘info’ key hash _arg_line_ holds the line after ‘@macro’. ‘menu_entry_node’ Extra keys with information about the node entry label same as those appearing in the ‘@node’ _line_arg_ explicit directions arguments ‘extra’ hash labels information. ‘@multitable’ The key _max_columns_ holds the maximal number of columns. If there is a ‘@columnfractions’ as argument, then the _columnfractions_ key is associated with the element for the @columnfractions command. ‘@node’ Explicit directions labels information is in the _line_arg_ arguments ‘extra’ node direction ‘@node’ arguments. They consist in a hash with the _node_content_ key for an array holding the corresponding content, 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. An _associated_section_ key holds the tree element of the sectioning command that follows the node. An _node_preceding_part_ key holds the tree element of the ‘@part’ that precedes the node, if there is no sectioning command between the ‘@part’ and the node. A _node_description_ key holds the first ‘@nodedescription’ associated to the node. A node containing a menu have a _menus_ key which refers to an array of references to menu elements occuring in the node. The first node containing a ‘@printindex’ @-command has the _isindex_ key set. ‘paragraph’ The _indent_ or _noindent_ key value is set if the corresponding @-commands are associated with that paragraph. ‘@part’ The next sectioning command tree element is in _part_associated_section_. The following node tree element is in _part_following_node_ if there is no sectioning command between the ‘@part’ and the node. ‘@ref’ ‘@xref’ ‘@pxref’ ‘@inforef’ The node argument _brace_command_arg_ holds information on the label, like the one appearing in the ‘@node’ _line_arg_ explicit directions arguments ‘extra’ hash labels information. ‘row’ The _row_number_ index key holds the index of the row in the ‘@multitable’. sectioning command The node preceding the command is in _associated_node_. The part preceding the command is in _associated_part_. If the level of the document was modified by ‘@raisections’ or ‘@lowersections’, the differential level is in _sections_level_. ‘untranslated’ _documentlanguage_ holds the ‘@documentlanguage’ value. If there is a translation context, it should be in _translation_context_. 3.7 Texinfo::Parser SEE ALSO ============================ Texinfo manual (http://www.gnu.org/software/texinfo/manual/texinfo/). 3.8 Texinfo::Parser AUTHOR ========================== Patrice Dumas, 3.9 Texinfo::Parser COPYRIGHT AND LICENSE ========================================= Copyright 2010- Free Software Foundation, Inc. See the source file for all copyright years. This library is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version. 4 Texinfo::Structuring ********************** 4.1 Texinfo::Structuring NAME ============================= Texinfo::Structuring - information on Texinfo::Parser tree 4.2 Texinfo::Structuring SYNOPSIS ================================= use Texinfo::Structuring qw(sectioning_structure nodes_tree number_floats associate_internal_references split_by_node split_by_section split_pages merge_indices sort_indices elements_directions elements_file_directions); # $tree is a Texinfo document tree. $parser is a Texinfo::Parser object. # $config is an object implementing the get_conf() method. my $registrar = $parser->registered_errors(); my $sections_root = sectioning_structure ($registrar, $config, $tree); my ($labels, $targets_list, $nodes_list) = $parser->labels_information(); my $parser_information = $parser->global_information(); my $global_commands = $parser->global_commands_information(); set_menus_node_directions($registrar, $config, $parser_information, $global_commands, $nodes_list, $labels); my $top_node = nodes_tree($registrar, $config, $parser_information, $nodes_list, $labels); complete_node_tree_with_menus($registrar, $config, $nodes_list, $top_node); my $refs = $parser->internal_references_information(); check_nodes_are_referenced($registrar, $config, $nodes_list, $top_node, $labels, $refs); associate_internal_references($registrar, $parser, $parser_information, $labels, $refs); number_floats($parser->floats_information()); my $tree_units; if ($split_at_nodes) { $tree_units = split_by_node($tree); } else { $tree_units = split_by_section($tree); } split_pages($tree_units, $split); elements_directions($config, $labels, $tree_units); elements_file_directions($tree_units); my $indices_information = $parser->indices_information(); my $merged_index_entries = merge_indices($indices_information); my $index_entries_sorted; if ($sort_by_letter) { $index_entries_sorted = sort_indices($registrar, $config, $merged_index_entries, $indices_information, 'by_letter'); } else { $index_entries_sorted = sort_indices($registrar, $config, $merged_index_entries, $indices_information); } 4.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. 4.4 Texinfo::Structuring DESCRIPTION ==================================== Texinfo::Structuring first allows to collect information on a Texinfo tree. In most case, it also requires information from a parser object to do that job. Thanks to ‘sectioning_structure’ the hierarchy of sectioning commands is determined. The directions implied by menus are determined with ‘set_menus_node_directions’. The node tree is analysed with ‘nodes_tree’. Nodes directions are completed with menu directions with ‘complete_node_tree_with_menus’. Floats get their standard numbering with ‘number_floats’ and internal references are matched up with nodes, floats or anchors with ‘associate_internal_references’. The following methods depend on the output format, so are usually called from converters. It is also possible to associate top-level contents of the tree, which consist in nodes and sectioning commands with tree unit elements that group together a node and the next sectioning element. With ‘split_by_node’ nodes are considered to be the main sectioning elements, while with ‘split_by_section’ the sectioning command elements are the main elements. The first mode is typical of Info format, while the second corresponds to a traditional book. The elements may be further split in _pages_, which are not pages as in book pages, but more like web pages, and hold series of tree unit elements. The elements may have directions to other elements prepared by ‘elements_directions’. ‘elements_file_directions’ should also set direction related to files, provided files are associated with elements by the user. ‘merge_indices’ may be used to merge indices, which may be sorted with ‘sort_indices’. 4.5 Texinfo::Structuring METHODS ================================ No method is exported in the default case. Most methods takes a *note Texinfo::Report: Texinfo::Report NAME. ‘$registrar’ as argument for error reporting. Most also require Texinfo customization variables information, which means an object implementing the ‘get_conf’ method, in practice the main program configuration or a converter (*note Texinfo::Convert::Converter Getting and setting customization variables::). Other common input arguments such as parser information, labels or refs are obtained from a parser, see *note Texinfo::Parser: Texinfo::Parser NAME. associate_internal_references($registrar, $customization_information, $parser_information, $labels, $refs) Verify that internal references (‘@ref’ and similar without fourth of fifth argument and menu entries) have an associated node, anchor or float. Set the ‘normalized’ key in the ‘extra’ hash ‘menu_entry_node’ hash for menu entries and in the first argument ‘extra’ hash for internal references ‘@ref’ and similar @-commands. Register errors in _$registrar_. check_nodes_are_referenced($registrar, $customization_information, $nodes_list, $top_node, $labels, $refs) Check that all the nodes are referenced (in menu, @*ref or node direction). Register errors in _$registrar_. Should be called after ‘complete_node_tree_with_menus’ in order to have the autogenerated menus available. complete_node_tree_with_menus($registrar, $customization_information, $nodes_list, $top_node) Complete nodes directions with menu directions. Check consistency of menus, sectionning and nodes direction structures. Register errors in _$registrar_. elements_directions($customization_information, $labels, $tree_units) Directions are set up for the tree unit elements in the array reference _$tree_units_ given in argument. The corresponding hash is in ‘{'structure'}->{'directions'}’ and keys correspond to directions while values are elements. The following directions are set up: This The element itself. Forward Element next. Back Previous element. NodeForward Following node element in reading order. It is the next node, or the first in menu or the next of the up node. NodeBack Preceding node element. NodeUp NodeNext NodePrev The up, next and previous node elements. Up Next Prev The up, next and previous section elements. FastBack For top level elements, the previous top level element. For other elements the up top level element. For example, for a chapter element it is the previous chapter, for a subsection element it is the chapter element that contains the subsection. FastForward The next top level section element. elements_file_directions($tree_units) In the directions reference described above for ‘elements_directions’, sets the _PrevFile_ and _NextFile_ directions to the elements in previous and following files. It also sets _FirstInFile*_ directions for all the elements by using the directions of the first element in file. So, for example, _FirstInFileNodeNext_ is the next node of the first element in the file of each element. The API for association of pages/elements to files is not defined yet. @nodes_list = get_node_node_childs_from_sectioning($node) _$node_ is a node tree element. Find the node _$node_ children based on the sectioning structure. For the node associated with ‘@top’ sectioning command, the sections associated with parts are considered. $entry_key = index_entry_sort_string($main_entry, $entry_tree_element, $sortas, $options) Return a string suitable as a sort string, for index entries. The index entry processed is _$entry_tree_element_, and can be a ‘@subentry’. _$main_entry_ is the main index entry tree element that can be used to gather information. _$sortas_ can be given to override the sort string (typically obtained from ‘@sortas’). The _$options_ are options used for Texinfo to text conversion for the generation of the sort string, typically obtained from *note setup_index_entry_keys_formatting: Texinfo::Structuring $option = setup_index_entry_keys_formatting($customization_information). $merged_entries = merge_indices($indices_information) Using information returned by *note ‘Texinfo::Parser::indices_information’: Texinfo::Parser $indices_information = $parser->indices_information(), a structure holding all the index entries by index name is returned, with all the entries of merged indices merged with those of the indice merged into. The _$merged_entries_ returned is a hash reference whose keys are the index names and values arrays of index entry structures described in details in *note Texinfo::Parser index_entries::. $new_block = new_block_command($content, $parent, $command_name) Returns the texinfo tree corresponding to a block command named _$command_name_ with contents _$content_ and parent in tree _$parent_. $new_menu = new_complete_node_menu($node, $use_sections) Returns a texinfo tree menu for node _$node_, pointing to the children of the node obtained with the sectioning structure. If _$use_sections_ is set, use section names for the menu entry names. $detailmenu = new_master_menu($translations, $labels, $menus) Returns a detailmenu tree element formatted as a master node. _$translations_, if defined, should be a *note Texinfo::Translations: Texinfo::Translations NAME. object and should also hold customization information. _$menus_ is an array reference containing the regular menus of the Top node. $entry = new_node_menu_entry($node, $use_sections) Returns the texinfo tree corresponding to a single menu entry pointing to _$node_. If _$use_sections_ is set, use the section name for the menu entry name. Returns ‘undef’ if the node argument is missing. $top_node = nodes_tree($registrar, $customization_information, $parser_information, $nodes_list, $labels) Goes through nodes and set directions. Returns the top node. Register errors in _$registrar_. This functions sets, in the ‘structure’ node element hash: node_up node_prev node_next Up, next and previous directions for the node. number_floats($float_information) Number the floats as described in the Texinfo manual. Sets the _number_ key in the ‘structure’ hash of the float tree elements. $command_name = section_level_adjusted_command_name($element) Return the sectioning command name corresponding to the sectioning element _$element_, adjusted in order to take into account raised and lowered sections, when needed. $sections_root, $sections_list = sectioning_structure($registrar, $customization_information, $tree) This function goes through the tree and gather information on the document structure for sectioning commands. It returns _$sections_root_ the root of the sectioning commands tree and a reference on the sections elements list. Errors are registered in _$registrar_. It sets section elements ‘structure’ hash values: section_level The level in the sectioning tree hierarchy. 0 is for ‘@top’ or ‘@part’, 1 for ‘@chapter’, ‘@appendix’... This level is corrected by ‘@raisesections’ and ‘@lowersections’. section_number The sectioning element number. section_childs An array holding sectioning elements children of the element. section_up section_prev section_next The up, previous and next sectioning elements. toplevel_next toplevel_prev toplevel_up The next and previous and up sectioning elements of toplevel sectioning elements (like ‘@top’, ‘@chapter’, ‘@appendix’), not taking into account ‘@part’ elements. set_menus_node_directions($registrar, $customization_information, $parser_information, $global_commands, $nodes_list, $labels); Goes through menu and set directions. Register errors in _$registrar_. This functions sets, in the ‘structure’ node element hash reference: menu_child The first child in the menu of the node. menu_up menu_next menu_prev Up, next and previous directions as set in menus. $option = setup_index_entry_keys_formatting($customization_information) Return options for conversion of Texinfo to text relevant for index keys sorting. ($index_entries_sorted, $index_entries_sort_strings) = sort_indices($registrar, $customization_information, $merged_index_entries, $indices_information, $sort_by_letter) If _$sort_by_letter_ is set, sort by letter, otherwise sort all entries together. In both cases, a hash reference with index names as keys _$index_entries_sorted_ is returned. When sorting by letter, an array reference of letter hash references is associated with each index name. Each letter hash reference has two keys, a _letter_ key with the letter, and an _entries_ key with an array reference of sorted index entries beginning with the letter. When simply sorting, the array of the sorted index entries is associated with the index name. _$index_entries_sort_strings_ is a hash reference associating the index entries with the strings that were used to sort them. Register errors in _$registrar_. $tree_units = split_by_node($tree) Returns a reference array of tree units where a node is associated to the following sectioning commands. Sectioning commands without nodes are also with the previous node, while nodes without sectioning commands are alone in their tree units. Tree units are regular tree elements with type _unit_, the associated nodes and sectioning tree elements are in the array associated with the ‘contents’ key. The associated elements have a _associated_unit_ key set in the ‘structure’ hash that points to the associated tree unit. Tree units have directions in the ‘structure’ hash reference, namely _unit_next_ and _unit_prev_ pointing to the previous and the next tree unit. In the ‘extra’ hash reference, tree units have: unit_command The node command associated with the element. $tree_units = split_by_section($tree) Similarly with ‘split_by_node’, returns an array of tree units. This time, lone nodes are associated with the previous sections and lone sections makes up a tree unit. The ‘structure’ and ‘extra’ hash keys set are the same, except that _unit_command_ is the sectioning command associated with the element. $pages = split_pages($tree_units, $split) The tree units from the array reference argument have an extra _first_in_page_ value set in the ‘structure’ hash reference to the first tree unit in the group, and based on the value of _$split_. The possible values for _$split_ are chapter The tree units are split at chapter or other toplevel sectioning tree units. node Each element has its own page. section The tree units are split at sectioning commands below chapter. value evaluating to false No splitting, only one page is returned, holding all the tree units. warn_non_empty_parts($registrar, $customization_information, $global_commands) Register a warning in _$registrar_ for each ‘@part’ that is not empty in _$global_commands_ information (typically obtained by calling ‘global_commands_information()’ on a parser). 4.6 Texinfo::Structuring SEE ALSO ================================= Texinfo manual (http://www.gnu.org/s/texinfo/manual/texinfo/), *note Texinfo::Parser: Texinfo::Parser NAME. 4.7 Texinfo::Structuring AUTHOR =============================== Patrice Dumas, 4.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. 5 Texinfo::Report ***************** 5.1 Texinfo::Report NAME ======================== Texinfo::Report - Error storing for Texinfo modules 5.2 Texinfo::Report SYNOPSIS ============================ use Texinfo::Report; my $registrar = Texinfo::Report::new(); if ($warning_happened) { $registrar->line_warn($converter, sprintf(__("\@%s is wrongly used"), $current->{'cmdname'}), $current->{'source_info'}); } my ($errors, $errors_count) = $registrar->errors(); foreach my $error_message (@$errors) { warn $error_message->{'error_line'}; } 5.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. 5.4 Texinfo::Report DESCRIPTION =============================== The ‘Texinfo::Report’ module helps with error handling. It is used by the Texinfo modules *note Texinfo::Parser: Texinfo::Parser NAME. and *note Texinfo::Convert::Converter: Texinfo::Convert::Converter NAME. To use this module, either create a new ‘Texinfo::Report’ object or initialize another object such as to be able to call ‘Texinfo::Report’ methods. In any case, ‘Texinfo::Report::new()’ is called to setup the module. Besides the ‘new’ method, ‘errors’ is used for reporting errors, and the other methods to store errors (and warnings). 5.5 Texinfo::Report METHODS =========================== No method is exported in the default case. The ‘new’ method initializes ‘Texinfo::Report’ related fields. The errors collected are available through the ‘errors’ method, the other methods allow registering errors and warnings. my $registrar = Texinfo::Report::new() $converter->Texinfo::Report::new() If called without argument, a ‘Texinfo::Report’ object is initialized and returned. This is how the module is used in the Texinfo Parsers, as a separate object. If called on a ‘$converter’, the ‘$converter’ is initialized itself such as to be able to call ‘Texinfo::Report’ methods. It is how it is used in the Converters. ($error_warnings_list, $error_count) = errors($registrar) This function returns as _$error_count_ the count of errors since calling ‘new’. The _$error_warnings_list_ is an array of hash references one for each error, warning or error line continuation. Each of these has the following keys: type May be ‘warning’, or ‘error’. text The text of the error. error_line The text of the error formatted with the file name, line number and macro name, as needed. line_nr The line number of the error or warning. file_name The file name where the error or warning occurs. macro The user macro name that is expanded at the location of the error or warning. $registrar->line_warn($text, $configuration_information, $error_location_info, $continuation, $silent) $registrar->line_error($text, $configuration_information, $error_location_info, $continuation, $silent) Register a warning or an error. The _$text_ is the text of the error or warning. The _$configuration_information_ object gives some information that can modify the messages or their delivery. The optional _$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 _$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 *note Texinfo::Parser source_info::. $registrar->document_warn($configuration_information, $text, $continuation) $registrar->document_error($configuration_information, $text, $continuation) Register a document-wide error or warning. _$text_ is the error or warning message. The _$configuration_information_ object gives some information that can modify the messages or their delivery. The _$continuation_ optional arguments, if true, conveys that the line is a continuation line of a message. 5.6 Texinfo::Report AUTHOR ========================== Patrice Dumas, 5.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. 6 Texinfo::Translations *********************** 6.1 Texinfo::Translations NAME ============================== Texinfo::Translations - Translations of output documents strings for Texinfo modules 6.2 Texinfo::Translations SYNOPSIS ================================== @ISA = qw(Texinfo::Translations); my $tree_translated = $converter->gdt('See {reference} in @cite{{book}}', {'reference' => $tree_reference, 'book' => {'text' => $book_name}}); 6.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. 6.4 Texinfo::Translations DESCRIPTION ===================================== The ‘Texinfo::Translations’ module helps with translations in output documents. Translation of error messages uses another interface, which is the classical gettext based perl interface. It is not described as it is described in details elsewhere, some elements are in *note Texinfo::Common ‘__’ and ‘__p’: Texinfo::Common $translated_string = __($msgid). 6.5 Texinfo::Translations METHODS ================================= No method is exported. The ‘gdt’ and ‘pgdt’ methods are used to translate strings to be output in converted documents, and returns, in general, a Texinfo tree. The ‘replace_convert_substrings’ method is called by ‘gdt’ to substitute replaced substrings in a translated string and convert to a Texinfo tree. It may be especially useful when overriding or reimplementing ‘gdt’. $tree = $object->gdt($string, $replaced_substrings, $translation_context, $mode, $lang) The _$string_ is a string to be translated. In the default case, the function returns a Texinfo tree, as the string is interpreted as Texinfo code after translation. _$replaced_substrings_ is an optional hash reference specifying some substitution to be done after the translation. The key of the _$replaced_substrings_ hash reference identifies what is to be substituted, and the value is some string, texinfo tree or array content that is substituted in the resulting texinfo tree. In the string to be translated word in brace matching keys of _$replaced_substrings_ are replaced. The _$object_ is typically a converter, but can be any object that implements ‘get_conf’, or undefined (‘undef’). If not undefined, the information in the _$object_ is used to determine the encoding, the documentlanguage and get some customization information. 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. _$lang_ is optional. If set, it overrides the documentlanguage. 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 = $converter->gdt('See {reference} in @cite{{book}}', {'reference' => $tree_reference, 'book' => {'text' => $book_name}}); ‘gdt’ uses a gettext-like infrastructure to retrieve the translated strings, using the _texinfo_document_ domain. _$mode_ is an optional string which may modify how the function behaves. The possible values are: translated_text In that case the string is not considered to be Texinfo, a plain string that is returned after translation and substitution. The substitutions may only be strings in that case. $tree = $object->pgdt($translation_context, $string, $replaced_substrings, $mode, $lang) 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. $tree = $object->replace_convert_substrings($translated_string, $replaced_substrings, $mode) _$translated_string_ is a string already translated. _$replaced_substrings_ is an optional hash reference specifying some substitution to be done. _$mode_ is an optional string which may modify how the function behaves, and in particular whether the translated string should be converted to a Texinfo tree. _$object_ is typically a converter, but can be any object that implements ‘get_conf’, or undefined (‘undef’). If not undefined, the information in the _$object_ is used to get some customization information. The function performs the substitutions of substrings in the translated string and converts to a Texinfo tree if needed. It is called from ‘gdt’ after the retrieval of the translated string. 6.6 Texinfo::Translations AUTHOR ================================ Patrice Dumas, 6.7 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. 7 Texinfo::Transformations ************************** 7.1 Texinfo::Transformations NAME ================================= Texinfo::Transformations - transformations of Texinfo Perl tree 7.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. 7.3 Texinfo::Transformations DESCRIPTION ======================================== Includes miscellaneous methods ‘set_menus_to_simple_menu’ and ‘menu_to_simple_menu’ to change the menu texinfo tree, as well as ‘insert_nodes_for_sectioning_commands’ that adds nodes for sectioning commands without nodes and ‘complete_tree_nodes_menus’ and ‘complete_tree_nodes_missing_menu’ that completes the node menus based on the sectioning tree. 7.4 Texinfo::Transformations METHODS ==================================== No method is exported in the default case. complete_tree_nodes_menus($tree, $add_section_names_in_entries) Add menu entries or whole menus for nodes associated with sections, based on the sectioning tree. If the optional ‘$add_section_names_in_entries’ argument is set, a menu entry name is added using the section name. This function should be called after *note sectioning_structure: Texinfo::Structuring $sections_root, $sections_list = sectioning_structure($registrar, $customization_information, $tree). complete_tree_nodes_missing_menu($tree, $use_section_names_in_entries) Add whole menus for nodes associated with sections and without menu, 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 *note sectioning_structure: Texinfo::Structuring $sections_root, $sections_list = sectioning_structure($registrar, $customization_information, $tree). ($root_content, $added_sections) = fill_gaps_in_sectioning($tree) This function adds empty ‘@unnumbered’ and similar commands in a tree to fill gaps in sectioning. This may be used, for example, when converting from a format that can handle gaps in sectioning. _$tree_ is the tree root. An array reference is returned, containing the root contents with added sectioning commands, as well as an array reference containing the added sectioning commands. 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. ($root_content, $added_nodes) = insert_nodes_for_sectioning_commands($tree, $nodes_list, $targets_list, $labels) Insert nodes for sectioning commands without node in ‘$tree’. Add nodes to the labels used as targets for references ‘$labels’ and ‘$targets_list’ and to ‘$nodes_list’. An array reference is returned, containing the root contents with added nodes, as well as an array reference containing the added nodes. menu_to_simple_menu($menu) set_menus_to_simple_menu($nodes_list) ‘menu_to_simple_menu’ transforms the tree of a menu tree element. ‘set_menus_to_simple_menu’ calls ‘menu_to_simple_menu’ for all the menus of the nodes in ‘$nodes_list’. A simple menu has no _menu_comment_, _menu_entry_ or _menu_entry_description_ container anymore, their content are merged directly in the menu in _preformatted_ container. protect_hashchar_at_line_beginning($registrar, $customization_information, $tree) Protect hash (#) character at the beginning of line such that they would not be considered as lines to be processed by the CPP processor. The _$registrar_ and _$customization_information_ arguments may be undef. If defined, the _$registrar_ argument should be a *note Texinfo::Report: Texinfo::Report NAME. object in which the errors and warnings encountered while parsing are registered. If defined, _$customization_information_ should give access to customization through ‘get_conf’. If both _$registrar_ and _$customization_information_ are defined they are used for error reporting in case an hash character could not be protected because it appeared in a raw environment. $modified_tree = reference_to_arg_in_tree($tree) 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. regenerate_master_menu($translations, $labels) Regenerate the Top node master menu, replacing the first detailmenu in Top node menus or appending at the end of the Top node menu. _$translations_, if defined, should be a *note Texinfo::Translations: Texinfo::Translations NAME. object and should also hold customization information. 7.5 Texinfo::Transformations SEE ALSO ===================================== Texinfo manual (http://www.gnu.org/s/texinfo/manual/texinfo/), *note Texinfo::Parser: Texinfo::Parser NAME. 7.6 Texinfo::Transformations AUTHOR =================================== Patrice Dumas, 7.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. 8 Texinfo::Convert::Texinfo *************************** 8.1 Texinfo::Convert::Texinfo NAME ================================== Texinfo::Convert::Texinfo - Convert a Texinfo tree to Texinfo code 8.2 Texinfo::Convert::Texinfo SYNOPSIS ====================================== use Texinfo::Convert::Texinfo qw(convert_to_texinfo); my $texinfo_text = convert_to_texinfo($tree); 8.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. 8.4 Texinfo::Convert::Texinfo DESCRIPTION ========================================= ‘Texinfo::Convert::Texinfo’ converts a Texinfo tree (described in *note 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. 8.5 Texinfo::Convert::Texinfo METHODS ===================================== $texinfo_text = convert_to_texinfo($tree) Converts the Texinfo tree _$tree_ to Texinfo code. 8.6 Texinfo::Convert::Texinfo AUTHOR ==================================== Patrice Dumas, 8.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. 9 Texinfo::Convert::Utils ************************* 9.1 Texinfo::Convert::Utils NAME ================================ Texinfo::Convert::Utils - miscellaneous functions usable in all converters 9.2 Texinfo::Convert::Utils SYNOPSIS ==================================== use Texinfo::Convert::Utils; my $today_tree = Texinfo::Convert::Utils::expand_today($converter); my $verbatiminclude_tree = Texinfo::Convert::Utils::expand_verbatiminclude(undef, $converter, $verbatiminclude); 9.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. 9.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 *note Texinfo::Convert::Converter: Texinfo::Convert::Converter NAME. 9.5 Texinfo::Convert::Utils METHODS =================================== No method is exported in the default case. Most methods takes a _$converter_ as argument, in some cases optionally, to get some information, see *note Texinfo::Convert::Converter Getting and setting customization variables:: and use methods for error reporting, see *note Texinfo::Convert::Converter: Texinfo::Convert::Converter NAME. and *note Texinfo::Report: Texinfo::Report NAME, and for strings translations, see *note Texinfo::Translations: Texinfo::Translations NAME. Even when the caller does not inherit from *note 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 which require a converter. $result = add_heading_number($converter, $heading_element, $heading_text, $do_number) The _$converter_ argument may be undef. _$heading_element_ is a heading command tree element. _$heading_text_ is the already formatted heading text. if the _$do_number_ optional argument is defined and false, no number is used and the text is returned as is. This function returns the heading with a number and the appendix part if needed. If _$converter_ is not defined, the resulting string won't be translated. ($category, $class, $type, $name, $arguments) = definition_arguments_content($element) _$element_ should be a ‘@def*’ Texinfo tree element. The _$category_, _$class_, _$type_, _$name_ are elements corresponding to the definition @-command line. Texinfo elements on the @-command line corresponding to arguments in the function definition are returned in the _$arguments_ array reference. Arguments correspond to text following the other elements on the @-command line. If there is no argument, _$arguments_ will be ‘undef’. $tree = definition_category_tree($converter, $def_line) The _$converter_ argument may be undef. _$def_line_ is a ‘def_line’ texinfo tree container. This function returns a texinfo tree corresponding to the category of the _$def_line_ taking the class into account, if there is one. If _$converter_ is not defined, the resulting string won't be translated. ($encoded_name, $encoding) = $converter->encoded_input_file_name($converter, $character_string_name, $input_file_encoding) ($encoded_name, $encoding) = $converter->encoded_output_file_name($converter, $character_string_name) Encode _$character_string_name_ in the same way as other file names are encoded in converters, based on customization variables, and possibly on the input file encoding. Return the encoded name and the encoding used to encode the name. The ‘encoded_input_file_name’ and ‘encoded_output_file_name’ functions use different customization variables to determine the encoding. The _$converter_ argument is not optional and is used both to access to customization variables and to access to parser information. The <$input_file_encoding> argument is optional. If set, it is used for the input file encoding. It is useful if there is more precise information on the input file encoding where the file name appeared. $tree = expand_today($converter) Expand today's date, as a texinfo tree with translations. The _$converter_ argument is not optional and is used both to retrieve customization information and to translate strings. $tree = expand_verbatiminclude($registrar, $customization_information, $verbatiminclude) The _$registrar_ argument may be undef. The _$customization_information_ argument is required and is used to retrieve customization information *note Texinfo::Convert::Converter Getting and setting customization variables::. _$verbatiminclude_ is a ‘@verbatiminclude’ tree element. This function returns a ‘@verbatim’ tree elements after finding the included file and reading it. If _$registrar_ is not defined, error messages are not registered. (\@contents, \@accent_commands) = find_innermost_accent_contents($element) _$element_ should be an accent command Texinfo tree element. Returns an array reference 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_). $heading_element = find_root_command_next_heading_command($element, $expanded_format_raw, $do_not_ignore_contents, $do_not_ignore_index_entries) Return an heading element found in the _$element_ contents if it appears before contents that could be formatted. _$expanded_format_raw_ is a hash reference with raw output formats (html, docbook, xml...) as keys, associated value should be set for expanded raw output formats. _$do_not_ignore_contents_ is optional. If set, ‘@contents’ and ‘@shortcontents’ are considered to be formatted. _$do_not_ignore_index_entries_ is optional. If set, index entries are considered to be formatted. Only heading elements corresponding to ‘@heading’, ‘@subheading’ and similar @-commands that are not associated to nodes in general are found, not sectioning commands. 9.6 Texinfo::Convert::Utils SEE ALSO ==================================== *note Texinfo::Convert::Converter: Texinfo::Convert::Converter NAME. and *note Texinfo::Translations: Texinfo::Translations NAME. 9.7 Texinfo::Convert::Utils AUTHOR ================================== Patrice Dumas, 9.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. 10 Texinfo::Convert::Unicode **************************** 10.1 Texinfo::Convert::Unicode NAME =================================== Texinfo::Convert::Unicode - Representation as Unicode characters 10.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 ($innermost_contents, $stack) = Texinfo::Convert::Utils::find_innermost_accent_contents($accent); my $formatted_accents = encoded_accents ($converter, convert_to_text($innermost_contents), $stack, $encoding, \&Texinfo::Text::ascii_accent_fallback); my $accent_text = unicode_accent('e', $accent_command); 10.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. 10.4 Texinfo::Convert::Unicode DESCRIPTION ========================================== ‘Texinfo::Convert::Unicode’ provides methods dealing with Unicode representation and conversion of Unicode code points, to be used in 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. 10.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 *note Texinfo::Convert::Utils::find_innermost_accent_contents: Texinfo::Convert::Utils (\@contents, \@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_. If _$set_case_ is positive, the result is upper-cased, while if it is negative, the result is lower-cased. $width = string_width($string) Return the string width, taking into account the fact that some characters have a zero width (like composing accents) while some have a width of 2 (most chinese characters, for example). $result = unicode_accent($text, $accent_command) _$text_ is the text appearing within an accent command. _$accent_command_ should be a Texinfo tree element corresponding to an accent command taking an argument. The function returns the Unicode representation of the accented character. $is_decoded = unicode_point_decoded_in_encoding($encoding, $unicode_point) Return true if the _$unicode_point_ will be encoded in the encoding _$encoding_. The _$unicode_point_ should be specified as a four letter string describing an hexadecimal number with letters in upper case (such as ‘201D’). Tables are used to determine if the _$unicode_point_ will be encoded, when the encoding does not cover the whole Unicode range. If the encoding is not supported in Texinfo, the result will always be false. $result = unicode_text($text, $in_code) Return _$text_ with dashes and quotes corresponding, for example to ‘---’ or ‘'’, represented as Unicode code points. If _$in_code_ is set, the text is considered to be in code style. 10.6 Texinfo::Convert::Unicode AUTHOR ===================================== Patrice Dumas, 10.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. 11 Texinfo::Convert::NodeNameNormalization ****************************************** 11.1 Texinfo::Convert::NodeNameNormalization NAME ================================================= Texinfo::Convert::NodeNameNormalization - Normalize and transliterate Texinfo trees 11.2 Texinfo::Convert::NodeNameNormalization SYNOPSIS ===================================================== use Texinfo::Convert::NodeNameNormalization qw(normalize_node normalize_transliterate_texinfo); my $normalized = normalize_node({'contents' => $node_contents}); my $file_name = normalize_transliterate_texinfo({'contents' => $section_contents}); 11.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. 11.4 Texinfo::Convert::NodeNameNormalization DESCRIPTION ======================================================== ‘Texinfo::Convert::NodeNameNormalization’ allows to normalize node names, with ‘normalize_node’ following 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 ‘_’. In *note Texinfo::Parser: Texinfo::Parser NAME, ‘normalize_node’ is used for ‘@node’, ‘@float’ and ‘@anchor’ names normalization, but also ‘@float’ types and ‘@acronym’ and ‘@abbr’ first argument. 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. 11.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 = normalize_node($tree) The Texinfo _$tree_ is returned as a string, normalized as described in the Texinfo manual _HTML Xref_ node. The result will be poor for Texinfo trees which are not @-command arguments (on an @-command line or in braces), for instance if the tree contains ‘@node’ or block commands. $transliterated = normalize_transliterate_texinfo($tree, $no_unidecode) The Texinfo _$tree_ is returned as a string, with non-ASCII letters transliterated as ASCII, but otherwise similar with ‘normalize_node’ 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. 11.6 Texinfo::Convert::NodeNameNormalization AUTHOR =================================================== Patrice Dumas, 11.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. 12 Texinfo::Convert::Text ************************* 12.1 Texinfo::Convert::Text NAME ================================ Texinfo::Convert::Text - Convert Texinfo tree to simple text 12.2 Texinfo::Convert::Text SYNOPSIS ==================================== use Texinfo::Convert::Text qw(convert_to_text ascii_accent text_accents); my $result = convert_to_text($tree); my $result_encoded = convert_to_text($tree, {'enabled_encoding' => 'utf-8'}); my $result_converter = convert_to_text($tree, {'converter' => $converter}); my $result_accent_text = ascii_accent('e', $accent_command); my $accents_text = text_accents($accents, 'utf-8'); 12.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. 12.4 Texinfo::Convert::Text DESCRIPTION ======================================= ‘Texinfo::Convert::Text’ is a simple backend that converts a Texinfo tree to simple text. It is used in converters, especially for file names. The converter is very simple, and, in the default case, cannot handle output strings translation or error handling. 12.5 Texinfo::Convert::Text METHODS =================================== $result = convert_to_text($tree, $options) Convert a Texinfo tree to simple text. _$options_ is a hash reference of options. The converter is very simple, and has almost no internal state besides the options. It cannot handle as is output strings translation or error storing. If the _converter_ option is set, some additional features may be available for the conversion of some @-commands, like output strings translation or error reporting. The following options may be set: enabled_encoding If set, the value is considered to be the encoding name texinfo accented letters should be converted to. This option being set corresponds to the ‘--enable-encoding’ option, or the ‘ENABLE_ENCODING’ customization variable for Info and Plaintext and for some conversion to text in other formats. For file names in HTML and LaTeX, and for DocBook or Texinfo XML, this variable should in general be set unless the output encoding is US-ASCII. sc If set, the text is upper-cased. code If set the text is in code style. (mostly ‘--’, ‘---’, ‘''’ and ‘``’ are kept as is). NUMBER_SECTIONS If set, sections are numbered when output. sort_string A somehow internal option to convert to text more suitable for alphabetical sorting rather than presentation. converter If this converter object is passed to the function, some features of this object may be used during conversion. Mostly error reporting and strings translation, as the converter object is also supposed to be a *note Texinfo::Report: Texinfo::Report NAME. objet. See also *note Texinfo::Convert::Converter: Texinfo::Convert::Converter NAME. expanded_formats_hash A reference on a hash. The keys should be format names (like ‘html’, ‘tex’), and if the corresponding value is set, the format is expanded. $result_accent_text = ascii_accent($text, $accent_command) _$text_ is the text appearing within an accent command. _$accent_command_ should be a Texinfo tree element corresponding to an accent command taking an argument. The function returns a transliteration of the accented character. $result_accent_text = ascii_accent_fallback($converter, $text, $accent_command) Same as ‘ascii_accent’ but with an additional first argument converter, which is ignored, but needed if this function is to be in argument of functions that need a fallback for accents conversion. $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. 12.6 Texinfo::Convert::Text AUTHOR ================================== Patrice Dumas, 12.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. 13 Texinfo::Convert::Converter ****************************** 13.1 Texinfo::Convert::Converter NAME ===================================== Texinfo::Convert::Converter - Parent class for Texinfo tree converters 13.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; $self->{'document_context'} = [{}]; } sub convert($$) { ... } sub convert_tree($$) { ... } sub output($$) { ... } # end of Texinfo::Convert::MyConverter my $converter = Texinfo::Convert::MyConverter->converter( {'parser' => $parser}); $converter->output($texinfo_tree); 13.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. 13.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. Two are optional, ‘converter_defaults’, ‘converter_initialize’ and used for initialization, to give information to ‘Texinfo::Convert::Converter’. The ‘convert_tree’ method is mandatory and should convert portions of Texinfo tree. The ‘output’ method is used by converters as entry point for conversion to a file with headers and so on. Although it is is not called from other modules, it should in general be implemented by converters. ‘output’ is called from ‘texi2any’. ‘convert’ is not required, but customarily used by converters as entry point for a conversion of a whole Texinfo tree without the headers done when outputting to a file. Existing backends may be used as examples that implement those methods. ‘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 *note Texinfo::Common: Texinfo::Common NAME, *note Texinfo::Convert::Unicode: Texinfo::Convert::Unicode NAME. and *note Texinfo::Report: Texinfo::Report NAME. describes modules or additional function that may be useful for backends, while the parsed Texinfo tree is described in *note Texinfo::Parser: Texinfo::Parser NAME. 13.5 Texinfo::Convert::Converter METHODS ======================================== 13.5.1 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. In this option hash reference a *note parser object: Texinfo::Parser NAME. may be associated with the _parser_ key. The other options are Texinfo customization options and a few other options that can be passed to the converter. Most of the customization options are described in the Texinfo manual. Those customization options, when appropriate, override the document content. *TODO what about the other options (all are used in converters; 'structuring' is available in HTML $converter->get_info()?* The parser should not be available directly anymore after getting the associated information. *TODO document this associated information ('parser_info', 'indices_information', 'floats'..., most available in HTML converter, either through $converter->get_info() or label_command())* The ‘converter’ function returns a converter object (a blessed hash reference) after checking the options and performing some initializations, especially when a parser is given among the options. The converter is also initialized as a *note Texinfo::Report: Texinfo::Report NAME. To help with these initializations, the modules subclassing ‘Texinfo::Convert::Converter’ can define two methods: %defaults = $converter->converter_defaults($options) The module can provide a defaults hash for converter customization options. The _$options_ hash reference holds options for the converter. converter_initialize This method is called at the end of the ‘Texinfo::Convert::Converter’ converter initialization. 13.5.2 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. $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. 13.5.3 Conversion to XML ------------------------ Some ‘Texinfo::Convert::Converter’ methods target conversion to XML. Most methods take a _$converter_ as argument to get some information and use methods for error reporting. $formatted_text = $converter->xml_format_text_with_numeric_entities($text) Replace quotation marks and hyphens used to represent dash in Texinfo text with numeric XML entities. $protected_text = $converter->xml_protect_text($text) Protect special XML characters (&, <, >, ") of _$text_. $comment = $converter->xml_comment($text) Returns an XML comment for _$text_. $result = xml_accent($text, $accent_command, $in_upper_case, $use_numeric_entities) _$text_ is the text appearing within an accent command. _$accent_command_ should be a Texinfo tree element corresponding to an accent command taking an argument. _$in_upper_case_ is optional, and, if set, the text is put in upper case. The function returns the accented letter as XML named entity if possible, falling back to numeric entities if there is no named entity and to an ASCII transliteration as last resort. _$use_numeric_entities_ is optional. If set, numerical entities are used instead of named entities if possible. $result = $converter->xml_accents($accent_command, $in_upper_case) _$accent_command_ is an accent command, which may have other accent commands nested. If _$in_upper_case_ is set, the result should be upper cased. The function returns the accents formatted as XML. $result = xml_numeric_entity_accent($accent_command_name, $text) _$accent_command_name_ is the name of an accent command. _$text_ is the text appearing within the accent command. Returns the accented letter as XML numeric entity, or ‘undef’ is there is no such entity. 13.5.4 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 *note Texinfo::Report: Texinfo::Report NAME. Also to translate strings, see *note Texinfo::Translations: Texinfo::Translations NAME. For useful methods that need a converter optionally and can be used in converters that do not inherit from ‘Texinfo::Convert::Converter’, see *note Texinfo::Convert::Utils: Texinfo::Convert::Utils NAME. $contents_element = $converter->comma_index_subentries_tree($entry, $separator) _$entry_ is a Texinfo tree index entry element. The function sets up an array with the ‘@subentry’ contents. The result is returned as ‘contents’ in the _$contents_element_ element, or ‘undef’ if there is no such content. _$separator_ is an optional separator argument used, if given, instead of the default: a comma followed by a space. $result = $converter->convert_accents($accent_command, \&format_accents, $output_encoded_characters, $in_upper_case) _$accent_command_ is an accent command, which may have other accent commands nested. The function returns the accents formatted either as encoded letters if _$output_encoded_characters_ is set, or formatted using _\&format_accents_. If _$in_upper_case_ is set, the result should be uppercased. $result = $converter->convert_document_sections($root, $file_handler) This method splits the _$root_ Texinfo tree at sections and calls ‘convert_tree’ on the elements. If the optional _$file_handler_ is given in argument, the result are output in _$file_handler_, otherwise the resulting string is returned. $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. _$output_format_ is optional. If it is not set the current output format, if defined, is used instead. If not an empty string, ‘_$output_format’ is prepended to the default directory name. _$output_file_ is mainly relevant when not split and should be used as the output file name. In general, if not split and _$output_file_ is an empty string, it means that text should be returned by the converter instead of being written to an output file. This is used in the test suite. _$destination_directory_ is either the directory _$output_file_ is in, or if split, the directory where the files should be created. _$output_filename_ is, in general, the file name portion of _$output_file_ (without directory) but can also be set based on ‘@setfilename’, in particular when _$output_file_ is an empty string. _$document_name_ is _$output_filename_ without extension. _$input_basefile_ is based on the input texinfo file name, with the file name portion only (without directory). The strings returned are text strings. ($encoded_name, $encoding) = $converter->encoded_input_file_name($character_string_name, $input_file_encoding) ($encoded_name, $encoding) = $converter->encoded_output_file_name($character_string_name) Encode _$character_string_name_ in the same way as other file names are encoded in the converter, based on customization variables, and possibly on the input file encoding. Return the encoded name and the encoding used to encode the name. The ‘encoded_input_file_name’ and ‘encoded_output_file_name’ functions use different customization variables to determine the encoding. The <$input_file_encoding> argument is optional. If set, it is used for the input file encoding. It is useful if there is more precise information on the input file encoding where the file name appeared. Note that ‘encoded_output_file_name’ is a wrapper around the function with the same name in *note Texinfo::Convert::Utils::encoded_output_file_name: Texinfo::Convert::Utils ($encoded_name, $encoding) = $converter->encoded_output_file_name($converter, $character_string_name), and ‘encoded_input_file_name’ is a wrapper around the function with the same name in *note Texinfo::Convert::Utils::encoded_input_file_name: Texinfo::Convert::Utils ($encoded_name, $encoding) = $converter->encoded_input_file_name($converter, $character_string_name, $input_file_encoding). ($caption, $prepended) = $converter->float_name_caption($float) _$float_ is a texinfo tree ‘@float’ element. This function returns the caption element that should be used for the float formatting and the _$prepended_ texinfo tree combining the type and label of the float. $tree = $converter->float_type_number($float) _$float_ is a texinfo tree ‘@float’ element. This function returns the type and number of the float as a texinfo tree with translations. $end_line = $converter->format_comment_or_return_end_line($element) Format comment at end of line or return the end of line associated with the element. In many cases, converters ignore comments and output is better formatted with new lines added independently of the presence of newline or comment in the initial Texinfo line, so most converters are better off not using this method. $filename = sub $converter->node_information_filename($normalized, $node_contents) Returns the normalized file name corresponding to the _$normalized_ node name and to the _$node_contents_ node name 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 optional array reference containing the @-commands set, if not given all the global informative @-commands are 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 *note 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, $contents) _$element_ should be an ‘@item’ or ‘@itemx’ tree element, _$contents_ should be corresponding texinfo tree contents. Returns a tree in which the @-command in argument of ‘@*table’ of the _$element_ has been applied to _$contents_. $result = $converter->top_node_filename($document_name) Returns a file name for the Top node file using either ‘TOP_FILE’ customization value, or ‘EXTENSION’ customization value and _$document_name_. Finally, there is: $result = $converter->output_internal_links() At this level, the method just returns undef. It is used in the HTML output, following the ‘--internal-links’ option of ‘texi2any’ specification. 13.6 Texinfo::Convert::Converter SEE ALSO ========================================= *note Texinfo::Common: Texinfo::Common NAME, *note Texinfo::Convert::Unicode: Texinfo::Convert::Unicode NAME, *note Texinfo::Report: Texinfo::Report NAME, *note Texinfo::Translations: Texinfo::Translations NAME, *note Texinfo::Convert::Utils: Texinfo::Convert::Utils NAME. and *note Texinfo::Parser: Texinfo::Parser NAME. 13.7 Texinfo::Convert::Converter AUTHOR ======================================= Patrice Dumas, 13.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. 14 Texinfo::Convert::Info ************************* 14.1 Texinfo::Convert::Info NAME ================================ Texinfo::Convert::Info - Convert Texinfo tree to Info 14.2 Texinfo::Convert::Info SYNOPSIS ==================================== my $converter = Texinfo::Convert::Info->converter({'parser' => $parser}); $converter->output($tree); $converter->convert($tree); $converter->convert_tree($tree); 14.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. 14.4 Texinfo::Convert::Info DESCRIPTION ======================================= Texinfo::Convert::Info converts a Texinfo tree to Info. 14.5 Texinfo::Convert::Info METHODS =================================== $converter = Texinfo::Convert::Info->converter($options) Initialize converter from Texinfo to Info. The _$options_ hash reference holds options for the converter. In this option hash reference a *note parser object: Texinfo::Parser NAME. may be associated with the _parser_ key. The other options are Texinfo customization options and a few other options that can be passed to the converter. Most of the customization options are described in the Texinfo manual. Those customization options, when appropriate, override the document content. The parser should not be available directly anymore after getting the associated information. See *note Texinfo::Convert::Converter: Texinfo::Convert::Converter NAME. for more information. $converter->output($tree) Convert a Texinfo tree _$tree_ and output the result in files as described in the Texinfo manual. $result = $converter->convert($tree) Convert a Texinfo tree _$tree_ and return the resulting output. $result = $converter->convert_tree($tree) Convert a Texinfo tree portion _$tree_ and return the resulting output. This function does not try to output a full document but only portions. For a full document use ‘convert’. 14.6 Texinfo::Convert::Info AUTHOR ================================== Patrice Dumas, 14.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. 15 Texinfo::Convert::HTML ************************* 15.1 Texinfo::Convert::HTML NAME ================================ Texinfo::Convert::HTML - Convert Texinfo tree to HTML 15.2 Texinfo::Convert::HTML SYNOPSIS ==================================== my $converter = Texinfo::Convert::HTML->converter({'parser' => $parser}); $converter->output($tree); $converter->convert($tree); $converter->convert_tree($tree); $converter->output_internal_links(); # HTML only 15.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. 15.4 Texinfo::Convert::HTML DESCRIPTION ======================================= Texinfo::Convert::HTML converts a Texinfo tree to HTML. 15.5 Texinfo::Convert::HTML METHODS =================================== $converter = Texinfo::Convert::HTML->converter($options) Initialize converter from Texinfo to HTML. The _$options_ hash reference holds options for the converter. In this option hash reference a *note parser object: Texinfo::Parser NAME. may be associated with the _parser_ key. The other options are Texinfo customization options and a few other options that can be passed to the converter. Most of the customization options are described in the Texinfo manual. Those customization options, when appropriate, override the document content. The parser should not be available directly anymore after getting the associated information. See *note Texinfo::Convert::Converter: Texinfo::Convert::Converter NAME. for more information. $converter->output($tree) Convert a Texinfo tree _$tree_ and output the result in files as described in the Texinfo manual. $result = $converter->convert($tree) Convert a Texinfo tree _$tree_ and return the resulting output. $result = $converter->convert_tree($tree) Convert a Texinfo tree portion _$tree_ and return the resulting output. This function does not try to output a full document but only portions. For a full document use ‘convert’. $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. 15.6 Texinfo::Convert::HTML AUTHOR ================================== Patrice Dumas, 15.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. 16 Texinfo::Convert::DocBook **************************** 16.1 Texinfo::Convert::DocBook NAME =================================== Texinfo::Convert::DocBook - Convert Texinfo tree to DocBook 16.2 Texinfo::Convert::DocBook SYNOPSIS ======================================= my $converter = Texinfo::Convert::DocBook->converter({'parser' => $parser}); $converter->output($tree); $converter->convert($tree); $converter->convert_tree($tree); 16.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. 16.4 Texinfo::Convert::DocBook DESCRIPTION ========================================== Texinfo::Convert::DocBook converts a Texinfo tree to DocBook. 16.5 Texinfo::Convert::DocBook METHODS ====================================== $converter = Texinfo::Convert::DocBook->converter($options) Initialize converter from Texinfo to DocBook. The _$options_ hash reference holds options for the converter. In this option hash reference a *note parser object: Texinfo::Parser NAME. may be associated with the _parser_ key. The other options are Texinfo customization options and a few other options that can be passed to the converter. Most of the customization options are described in the Texinfo manual. Those customization options, when appropriate, override the document content. The parser should not be available directly anymore after getting the associated information. See *note Texinfo::Convert::Converter: Texinfo::Convert::Converter NAME. for more information. $converter->output($tree) Convert a Texinfo tree _$tree_ and output the result in files as described in the Texinfo manual. $result = $converter->convert($tree) Convert a Texinfo tree _$tree_ and return the resulting output. $result = $converter->convert_tree($tree) Convert a Texinfo tree portion _$tree_ and return the resulting output. This function does not try to output a full document but only portions. For a full document use ‘convert’. 16.6 Texinfo::Convert::DocBook AUTHOR ===================================== Patrice Dumas, 16.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. 17 Texinfo::Convert::TexinfoMarkup ********************************** 17.1 Texinfo::Convert::TexinfoMarkup NAME ========================================= Texinfo::Convert::TexinfoMarkup - Convert Texinfo tree to element and attribute markup 17.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; .... } 17.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. 17.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 (*note 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. 17.5 Texinfo::Convert::TexinfoMarkup METHODS ============================================ 17.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 (*note Texinfo::Parser Types for text elements::). Texinfo tree elements are described in details in *note 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. 17.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’. 17.6 Texinfo::Convert::TexinfoMarkup AUTHOR =========================================== Patrice Dumas, 17.7 Texinfo::Convert::TexinfoMarkup SEE ALSO ============================================= *note Texinfo::Convert::Converter: Texinfo::Convert::Converter NAME. *note Texinfo::Convert::TexinfoXML: Texinfo::Convert::TexinfoXML NAME. The ‘Texinfo::Convert::TexinfoSXML’ is another subclass, which outputs SXML. It is not much documented. 17.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. 18 Texinfo::Convert::TexinfoXML ******************************* 18.1 Texinfo::Convert::TexinfoXML NAME ====================================== Texinfo::Convert::TexinfoXML - Convert Texinfo tree to TexinfoXML 18.2 Texinfo::Convert::TexinfoXML SYNOPSIS ========================================== my $converter = Texinfo::Convert::TexinfoXML->converter({'parser' => $parser}); $converter->output($tree); $converter->convert($tree); $converter->convert_tree($tree); 18.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. 18.4 Texinfo::Convert::TexinfoXML DESCRIPTION ============================================= Texinfo::Convert::TexinfoXML converts a Texinfo tree to TexinfoXML. 18.5 Texinfo::Convert::TexinfoXML METHODS ========================================= $converter = Texinfo::Convert::TexinfoXML->converter($options) Initialize converter from Texinfo to TexinfoXML. The _$options_ hash reference holds options for the converter. In this option hash reference a *note parser object: Texinfo::Parser NAME. may be associated with the _parser_ key. The other options are Texinfo customization options and a few other options that can be passed to the converter. Most of the customization options are described in the Texinfo manual. Those customization options, when appropriate, override the document content. The parser should not be available directly anymore after getting the associated information. See *note Texinfo::Convert::Converter: Texinfo::Convert::Converter NAME. for more information. $converter->output($tree) Convert a Texinfo tree _$tree_ and output the result in files as described in the Texinfo manual. $result = $converter->convert($tree) Convert a Texinfo tree _$tree_ and return the resulting output. $result = $converter->convert_tree($tree) Convert a Texinfo tree portion _$tree_ and return the resulting output. This function does not try to output a full document but only portions. For a full document use ‘convert’. 18.6 Texinfo::Convert::TexinfoXML AUTHOR ======================================== Patrice Dumas, 18.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. 19 Texinfo::Convert::Plaintext ****************************** 19.1 Texinfo::Convert::Plaintext NAME ===================================== Texinfo::Convert::Plaintext - Convert Texinfo tree to Plaintext 19.2 Texinfo::Convert::Plaintext SYNOPSIS ========================================= my $converter = Texinfo::Convert::Plaintext->converter({'parser' => $parser}); $converter->output($tree); $converter->convert($tree); $converter->convert_tree($tree); 19.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. 19.4 Texinfo::Convert::Plaintext DESCRIPTION ============================================ Texinfo::Convert::Plaintext converts a Texinfo tree to Plaintext. 19.5 Texinfo::Convert::Plaintext METHODS ======================================== $converter = Texinfo::Convert::Plaintext->converter($options) Initialize converter from Texinfo to Plaintext. The _$options_ hash reference holds options for the converter. In this option hash reference a *note parser object: Texinfo::Parser NAME. may be associated with the _parser_ key. The other options are Texinfo customization options and a few other options that can be passed to the converter. Most of the customization options are described in the Texinfo manual. Those customization options, when appropriate, override the document content. The parser should not be available directly anymore after getting the associated information. See *note Texinfo::Convert::Converter: Texinfo::Convert::Converter NAME. for more information. $converter->output($tree) Convert a Texinfo tree _$tree_ and output the result in files as described in the Texinfo manual. $result = $converter->convert($tree) Convert a Texinfo tree _$tree_ and return the resulting output. $result = $converter->convert_tree($tree) Convert a Texinfo tree portion _$tree_ and return the resulting output. This function does not try to output a full document but only portions. For a full document use ‘convert’. 19.6 Texinfo::Convert::Plaintext AUTHOR ======================================= Patrice Dumas, 19.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. Appendix A Index **************** * Menu: * %accent_commands: Texinfo::Commands @-COMMAND CLASSES. (line 238) * %all_commands: Texinfo::Common @-COMMAND INFORMATION. (line 570) * %block_commands: Texinfo::Commands @-COMMAND CLASSES. (line 243) * %blockitem_commands: Texinfo::Commands @-COMMAND CLASSES. (line 308) * %brace_code_commands: Texinfo::Commands @-COMMAND CLASSES. (line 313) * %brace_commands: Texinfo::Commands @-COMMAND CLASSES. (line 318) * %close_paragraph_commands: Texinfo::Commands @-COMMAND CLASSES. (line 324) * %commands_args_number: Texinfo::Commands @-COMMAND CLASSES. (line 329) * %contain_basic_inline_commands: Texinfo::Commands @-COMMAND CLASSES. (line 344) * %contain_plain_text: Texinfo::Commands @-COMMAND CLASSES. (line 349) * %def_aliases: Texinfo::Common @-COMMAND INFORMATION. (line 576) * %def_commands: Texinfo::Commands @-COMMAND CLASSES. (line 354) * %def_no_var_arg_commands: Texinfo::Common @-COMMAND INFORMATION. (line 576) * %default_index_commands: Texinfo::Commands @-COMMAND CLASSES. (line 358) * %explained_commands: Texinfo::Commands @-COMMAND CLASSES. (line 363) * %formattable_line_commands: Texinfo::Commands @-COMMAND CLASSES. (line 368) * %formatted_line_commands: Texinfo::Commands @-COMMAND CLASSES. (line 385) * %formatted_nobrace_commands: Texinfo::Commands @-COMMAND CLASSES. (line 377) * %heading_spec_commands: Texinfo::Commands @-COMMAND CLASSES. (line 394) * %in_heading_spec_commands: Texinfo::Commands @-COMMAND CLASSES. (line 398) * %index_names: Texinfo::Commands @-COMMAND INFORMATION. (line 222) * %inline_conditional_commands: Texinfo::Commands @-COMMAND CLASSES. (line 410) * %inline_format_commands: Texinfo::Commands @-COMMAND CLASSES. (line 410) * %letter_no_arg_commands: Texinfo::Commands @-COMMAND CLASSES. (line 415) * %line_commands: Texinfo::Commands @-COMMAND CLASSES. (line 424) * %math_commands: Texinfo::Commands @-COMMAND CLASSES. (line 420) * %no_paragraph_commands: Texinfo::Commands @-COMMAND CLASSES. (line 435) * %nobrace_commands: Texinfo::Commands @-COMMAND CLASSES. (line 439) * %nobrace_symbol_text: Texinfo::Common @-COMMAND INFORMATION. (line 587) * %non_formatted_block_commands: Texinfo::Commands @-COMMAND CLASSES. (line 450) * %preamble_commands: Texinfo::Commands @-COMMAND CLASSES. (line 455) * %preformatted_code_commands: Texinfo::Commands @-COMMAND CLASSES. (line 461) * %preformatted_commands: Texinfo::Commands @-COMMAND CLASSES. (line 461) * %ref_commands: Texinfo::Commands @-COMMAND CLASSES. (line 468) * %root_commands: Texinfo::Commands @-COMMAND CLASSES. (line 473) * %sectioning_heading_commands: Texinfo::Commands @-COMMAND CLASSES. (line 478) * %small_block_associated_command: Texinfo::Common @-COMMAND INFORMATION. (line 598) * %texinfo_output_formats: Texinfo::Common MISC INFORMATION. (line 555) * %variadic_commands: Texinfo::Commands @-COMMAND CLASSES. (line 482) * add_heading_number: Texinfo::Convert::Utils METHODS. (line 3052) * ascii_accent: Texinfo::Convert::Text METHODS. (line 3498) * ascii_accent_fallback: Texinfo::Convert::Text METHODS. (line 3505) * associate_internal_references: Texinfo::Structuring METHODS. (line 2175) * brace_no_arg_command: Texinfo::Convert::Unicode METHODS. (line 3209) * check_nodes_are_referenced: Texinfo::Structuring METHODS. (line 2184) * check_unicode_point_conversion: Texinfo::Convert::Unicode METHODS. (line 3216) * collect_commands_in_tree: Texinfo::Common METHODS. (line 642) * collect_commands_list_in_tree: Texinfo::Common METHODS. (line 649) * comma_index_subentries_tree: Texinfo::Convert::Converter Helper methods. (line 3750) * complete_node_tree_with_menus: Texinfo::Structuring METHODS. (line 2192) * complete_tree_nodes_menus: Texinfo::Transformations METHODS. (line 2838) * complete_tree_nodes_missing_menu: Texinfo::Transformations METHODS. (line 2848) * convert: Texinfo::Convert::Converter DESCRIPTION. (line 3594) * convert_accents: Texinfo::Convert::Converter Helper methods. (line 3759) * convert_document_sections: Texinfo::Convert::Converter Helper methods. (line 3767) * convert_to_normalized: Texinfo::Convert::NodeNameNormalization METHODS. (line 3347) * convert_to_texinfo: Texinfo::Convert::Texinfo METHODS. (line 2980) * convert_to_text: Texinfo::Convert::Text METHODS. (line 3441) * convert_tree: Texinfo::Convert::Converter DESCRIPTION. (line 3594) * converter: Texinfo::Convert::Converter Initialization. (line 3624) * converter_defaults: Texinfo::Convert::Converter Initialization. (line 3655) * converter_initialize: Texinfo::Convert::Converter Initialization. (line 3661) * create_destination_directory: Texinfo::Convert::Converter Helper methods. (line 3774) * definition_arguments_content: Texinfo::Convert::Utils METHODS. (line 3062) * definition_category_tree: Texinfo::Convert::Utils METHODS. (line 3073) * determine_files_and_directory: Texinfo::Convert::Converter Helper methods. (line 3782) * document_error: Texinfo::Report METHODS. (line 2652) * document_warn: Texinfo::Report METHODS. (line 2652) * element_associated_processing_encoding: Texinfo::Common METHODS. (line 656) * element_is_inline: Texinfo::Common METHODS. (line 661) * elements_directions: Texinfo::Structuring METHODS. (line 2198) * elements_file_directions: Texinfo::Structuring METHODS. (line 2256) * encoded_accents: Texinfo::Convert::Unicode METHODS. (line 3226) * encoded_input_file_name: Texinfo::Convert::Utils METHODS. (line 3083) * encoded_input_file_name <1>: Texinfo::Convert::Converter Helper methods. (line 3810) * encoded_output_file_name: Texinfo::Convert::Utils METHODS. (line 3083) * encoded_output_file_name <1>: Texinfo::Convert::Converter Helper methods. (line 3810) * enumerate_item_representation: Texinfo::Common METHODS. (line 676) * errors: Texinfo::Report METHODS. (line 2594) * expand_today: Texinfo::Convert::Utils METHODS. (line 3100) * expand_verbatiminclude: Texinfo::Convert::Utils METHODS. (line 3106) * fill_gaps_in_sectioning: Texinfo::Transformations METHODS. (line 2858) * find_innermost_accent_contents: Texinfo::Convert::Utils METHODS. (line 3117) * find_parent_root_command: Texinfo::Common METHODS. (line 686) * float_name_caption: Texinfo::Convert::Converter Helper methods. (line 3836) * float_type_number: Texinfo::Convert::Converter Helper methods. (line 3843) * floats_information: Texinfo::Parser Getting information on the document. (line 1117) * force_conf: Texinfo::Convert::Converter Getting and setting customization variables. (line 3675) * format_comment_or_return_end_line: Texinfo::Convert::Converter Helper methods. (line 3849) * gdt: Texinfo::Translations METHODS. (line 2725) * get_conf: Texinfo::Convert::Converter Getting and setting customization variables. (line 3682) * get_node_node_childs_from_sectioning: Texinfo::Structuring METHODS. (line 2270) * global_commands_information: Texinfo::Parser Getting information on the document. (line 1092) * global_information: Texinfo::Parser Getting information on the document. (line 1062) * index_entry_sort_string: Texinfo::Structuring METHODS. (line 2277) * indices_information: Texinfo::Parser Getting information on the document. (line 1136) * insert_nodes_for_sectioning_commands: Texinfo::Transformations METHODS. (line 2872) * internal_references_information: Texinfo::Parser Getting information on the document. (line 1128) * is_content_empty: Texinfo::Common METHODS. (line 703) * labels_information: Texinfo::Parser Getting information on the document. (line 1105) * line_error: Texinfo::Report METHODS. (line 2629) * line_warn: Texinfo::Report METHODS. (line 2629) * locate_include_file: Texinfo::Common METHODS. (line 709) * menu_to_simple_menu: Texinfo::Transformations METHODS. (line 2884) * merge_indices: Texinfo::Structuring METHODS. (line 2289) * move_index_entries_after_items_in_tree: Texinfo::Common METHODS. (line 735) * new_block_command: Texinfo::Structuring METHODS. (line 2302) * new_complete_node_menu: Texinfo::Structuring METHODS. (line 2308) * new_master_menu: Texinfo::Structuring METHODS. (line 2314) * new_node_menu_entry: Texinfo::Structuring METHODS. (line 2322) * node_information_filename: Texinfo::Convert::Converter Helper methods. (line 3857) * nodes_tree: Texinfo::Structuring METHODS. (line 2329) * normalize_node: Texinfo::Convert::NodeNameNormalization METHODS. (line 3354) * normalize_top_node_name: Texinfo::Common METHODS. (line 747) * normalize_transliterate_texinfo: Texinfo::Convert::NodeNameNormalization METHODS. (line 3363) * normalized_sectioning_command_filename: Texinfo::Convert::Converter Helper methods. (line 3862) * number_floats: Texinfo::Structuring METHODS. (line 2344) * output: Texinfo::Convert::Converter DESCRIPTION. (line 3594) * output_internal_links: Texinfo::Convert::Converter Helper methods. (line 3928) * output_internal_links <1>: Texinfo::Convert::HTML METHODS. (line 4105) * parse_texi_file: Texinfo::Parser Parsing Texinfo text. (line 1031) * parse_texi_line: Texinfo::Parser Parsing Texinfo text. (line 1007) * parse_texi_piece: Texinfo::Parser Parsing Texinfo text. (line 1015) * parse_texi_text: Texinfo::Parser Parsing Texinfo text. (line 1023) * Parser initialization: Texinfo::Parser Initialization. (line 937) * pgdt: Texinfo::Translations METHODS. (line 2770) * present_bug_message: Texinfo::Convert::Converter Helper methods. (line 3871) * protect_colon_in_tree: Texinfo::Common METHODS. (line 754) * protect_comma_in_tree: Texinfo::Common METHODS. (line 761) * protect_first_parenthesis: Texinfo::Common METHODS. (line 765) * protect_hashchar_at_line_beginning: Texinfo::Transformations METHODS. (line 2894) * protect_node_after_label_in_tree: Texinfo::Common METHODS. (line 754) * reference_to_arg_in_tree: Texinfo::Transformations METHODS. (line 2908) * regenerate_master_menu: Texinfo::Transformations METHODS. (line 2916) * registered_errors: Texinfo::Parser Parsing Texinfo text. (line 1046) * relate_index_entries_to_table_items_in_tree: Texinfo::Common METHODS. (line 741) * replace_convert_substrings: Texinfo::Translations METHODS. (line 2777) * section_level: Texinfo::Common METHODS. (line 771) * section_level_adjusted_command_name: Texinfo::Structuring METHODS. (line 2349) * sectioning_structure: Texinfo::Structuring METHODS. (line 2355) * set_conf: Texinfo::Convert::Converter Getting and setting customization variables. (line 3687) * set_global_document_command: Texinfo::Common METHODS. (line 776) * set_global_document_commands: Texinfo::Convert::Converter Helper methods. (line 3876) * set_informative_command_value: Texinfo::Common METHODS. (line 810) * set_menus_node_directions: Texinfo::Structuring METHODS. (line 2397) * set_menus_to_simple_menu: Texinfo::Transformations METHODS. (line 2884) * set_output_encodings: Texinfo::Common METHODS. (line 819) * setup_index_entry_keys_formatting: Texinfo::Structuring METHODS. (line 2417) * sort_indices: Texinfo::Structuring METHODS. (line 2422) * split_by_node: Texinfo::Structuring METHODS. (line 2442) * split_by_section: Texinfo::Structuring METHODS. (line 2465) * split_custom_heading_command_contents: Texinfo::Common METHODS. (line 827) * split_pages: Texinfo::Structuring METHODS. (line 2475) * string_width: Texinfo::Convert::Unicode METHODS. (line 3251) * table_item_content_tree: Texinfo::Convert::Converter Helper methods. (line 3913) * Texinfo tree element extra key: Texinfo::Parser Information available in the extra key. (line 1754) * Texinfo tree element structure: Texinfo::Parser Element keys. (line 1240) * Texinfo tree elements: Texinfo::Parser TEXINFO TREE. (line 1206) * Texinfo::Convert::Converter initialization: Texinfo::Convert::Converter Initialization. (line 3624) * Texinfo::Parser::parser: Texinfo::Parser Initialization. (line 937) * Texinfo::Report::new: Texinfo::Report METHODS. (line 2584) * text_accents: Texinfo::Convert::Text METHODS. (line 3512) * top_node_filename: Texinfo::Convert::Converter Helper methods. (line 3920) * transliterate_protect_file_name: Texinfo::Convert::NodeNameNormalization METHODS. (line 3378) * transliterate_texinfo: Texinfo::Convert::NodeNameNormalization METHODS. (line 3371) * trim_spaces_comment_from_content: Texinfo::Common METHODS. (line 836) * unicode_accent: Texinfo::Convert::Unicode METHODS. (line 3257) * unicode_point_decoded_in_encoding: Texinfo::Convert::Unicode METHODS. (line 3264) * unicode_text: Texinfo::Convert::Unicode METHODS. (line 3276) * valid_option: Texinfo::Common METHODS. (line 841) * valid_tree_transformation: Texinfo::Common METHODS. (line 845) * warn_non_empty_parts: Texinfo::Structuring METHODS. (line 2500) * xml_accent: Texinfo::Convert::Converter Conversion to XML. (line 3713) * xml_accents: Texinfo::Convert::Converter Conversion to XML. (line 3725) * xml_comment: Texinfo::Convert::Converter Conversion to XML. (line 3709) * xml_format_text_with_numeric_entities: Texinfo::Convert::Converter Conversion to XML. (line 3700) * xml_numeric_entity_accent: Texinfo::Convert::Converter Conversion to XML. (line 3731) * xml_protect_text: Texinfo::Convert::Converter Conversion to XML. (line 3705)