Texinfo modules documentation ¶

• 1 Texinfo::Commands
  • 1.1 Texinfo::Commands NAME
  • 1.2 Texinfo::Commands SYNOPSIS
  • 1.3 Texinfo::Commands NOTES
  • 1.4 Texinfo::Commands DESCRIPTION
  • 1.5 @-COMMAND INFORMATION
  • 1.6 @-COMMAND CLASSES
  • 1.7 Texinfo::Commands SEE ALSO
  • 1.8 Texinfo::Commands AUTHOR
  • 1.9 Texinfo::Commands COPYRIGHT AND LICENSE
• 2 Texinfo::CommandsValues
  • 2.1 Texinfo::CommandsValues NAME
  • 2.2 Texinfo::CommandsValues SYNOPSIS
  • 2.3 Texinfo::CommandsValues NOTES
  • 2.4 Texinfo::CommandsValues DESCRIPTION
  • 2.5 @-COMMAND ASSOCIATED INFORMATION
  • 2.6 Texinfo::CommandsValues SEE ALSO
  • 2.7 Texinfo::CommandsValues AUTHOR
  • 2.8 Texinfo::CommandsValues COPYRIGHT AND LICENSE
• 3 Texinfo::Common
  • 3.1 Texinfo::Common NAME
  • 3.2 Texinfo::Common SYNOPSIS
  • 3.3 Texinfo::Common NOTES
  • 3.4 Texinfo::Common DESCRIPTION
  • 3.5 MISC INFORMATION
  • 3.6 @-COMMAND INFORMATION
  • 3.7 Texinfo::Common METHODS
  • 3.8 Texinfo::Common SEE ALSO
  • 3.9 Texinfo::Common AUTHOR
  • 3.10 Texinfo::Common COPYRIGHT AND LICENSE
• 4 Texinfo::Parser
  • 4.1 Texinfo::Parser NAME
  • 4.2 Texinfo::Parser SYNOPSIS
  • 4.3 Texinfo::Parser NOTES
  • 4.4 Texinfo::Parser DESCRIPTION
  • 4.5 Texinfo::Parser METHODS
    • 4.5.1 Initialization
    • 4.5.2 Parsing Texinfo text
  • 4.6 TEXINFO TREE
    • 4.6.1 Texinfo tree structure
      • 4.6.1.1 Root and first level elements
      • 4.6.1.2 Line command tree element
      • 4.6.1.3 Block command tree element
      • 4.6.1.4 Paragraphs and preformatted
      • 4.6.1.5 Brace commands
      • 4.6.1.6 Texinfo line tree
      • 4.6.1.7 Showing the tree structure
    • 4.6.2 Element keys
    • 4.6.3 Element types
      • 4.6.3.1 Types for command and user-defined macro call elements
      • 4.6.3.2 Types for text elements
      • 4.6.3.3 Tree container elements
      • 4.6.3.4 Types of container elements
    • 4.6.4 Information available in the info key
    • 4.6.5 Information available in the extra key
      • 4.6.5.1 Extra keys available for more than one @-command
      • 4.6.5.2 Extra keys specific of certain @-commands or containers
  • 4.7 Texinfo::Parser SEE ALSO
  • 4.8 Texinfo::Parser AUTHOR
  • 4.9 Texinfo::Parser COPYRIGHT AND LICENSE
• 5 Texinfo::Document
  • 5.1 Texinfo::Document NAME
  • 5.2 Texinfo::Document SYNOPSIS
  • 5.3 Texinfo::Document NOTES
  • 5.4 Texinfo::Document DESCRIPTION
  • 5.5 Texinfo::Document METHODS
    • 5.5.1 Getting document information
    • 5.5.2 Merging and sorting indexes
    • 5.5.3 Getting errors and warnings
    • 5.5.4 Getting customization options values registered in document
    • 5.5.5 Registering information in document
    • 5.5.6 Methods for Perl and C code interactions
  • 5.6 Texinfo::Document SEE ALSO
  • 5.7 Texinfo::Document AUTHOR
  • 5.8 Texinfo::Document COPYRIGHT AND LICENSE
• 6 Texinfo::ManipulateTree
  • 6.1 Texinfo::ManipulateTree NAME
  • 6.2 Texinfo::ManipulateTree SYNOPSIS
  • 6.3 Texinfo::ManipulateTree NOTES
  • 6.4 Texinfo::ManipulateTree DESCRIPTION
  • 6.5 Texinfo::ManipulateTree METHODS
  • 6.6 Texinfo::ManipulateTree SEE ALSO
  • 6.7 Texinfo::ManipulateTree AUTHOR
  • 6.8 Texinfo::ManipulateTree COPYRIGHT AND LICENSE
• 7 Texinfo::Structuring
  • 7.1 Texinfo::Structuring NAME
  • 7.2 Texinfo::Structuring SYNOPSIS
  • 7.3 Texinfo::Structuring NOTES
  • 7.4 Texinfo::Structuring DESCRIPTION
  • 7.5 Texinfo::Structuring METHODS
  • 7.6 Texinfo::Structuring SEE ALSO
  • 7.7 Texinfo::Structuring AUTHOR
  • 7.8 Texinfo::Structuring COPYRIGHT AND LICENSE
• 8 Texinfo::Report
  • 8.1 Texinfo::Report NAME
  • 8.2 Texinfo::Report SYNOPSIS
  • 8.3 Texinfo::Report NOTES
  • 8.4 Texinfo::Report DESCRIPTION
  • 8.5 Texinfo::Report METHODS
  • 8.6 Texinfo::Report AUTHOR
  • 8.7 Texinfo::Report COPYRIGHT AND LICENSE
• 9 Texinfo::Translations
  • 9.1 Texinfo::Translations NAME
  • 9.2 Texinfo::Translations SYNOPSIS
  • 9.3 Texinfo::Translations NOTES
  • 9.4 Texinfo::Translations DESCRIPTION
  • 9.5 Texinfo::Translations METHODS
  • 9.6 Texinfo::Translations SEE ALSO
  • 9.7 Texinfo::Translations AUTHOR
  • 9.8 Texinfo::Translations COPYRIGHT AND LICENSE
• 10 Texinfo::Transformations
  • 10.1 Texinfo::Transformations NAME
  • 10.2 Texinfo::Transformations NOTES
  • 10.3 Texinfo::Transformations DESCRIPTION
  • 10.4 Texinfo::Transformations METHODS
  • 10.5 Texinfo::Transformations SEE ALSO
  • 10.6 Texinfo::Transformations AUTHOR
  • 10.7 Texinfo::Transformations COPYRIGHT AND LICENSE
• 11 Texinfo::Indices
  • 11.1 Texinfo::Indices NAME
  • 11.2 Texinfo::Indices SYNOPSIS
  • 11.3 Texinfo::Indices NOTES
  • 11.4 Texinfo::Indices DESCRIPTION
  • 11.5 Texinfo::Indices METHODS
  • 11.6 Texinfo::Indices SEE ALSO
  • 11.7 Texinfo::Indices AUTHOR
  • 11.8 Texinfo::Indices COPYRIGHT AND LICENSE
• 12 Texinfo::OutputUnits
  • 12.1 Texinfo::OutputUnits NAME
  • 12.2 Texinfo::OutputUnits SYNOPSIS
  • 12.3 Texinfo::OutputUnits NOTES
  • 12.4 Texinfo::OutputUnits DESCRIPTION
  • 12.5 Texinfo::OutputUnits METHODS
    • 12.5.1 Output units creation
    • 12.5.2 Grouping output units in pages
    • 12.5.3 Setting output units directions
  • 12.6 Texinfo::OutputUnits SEE ALSO
  • 12.7 Texinfo::OutputUnits AUTHOR
  • 12.8 Texinfo::OutputUnits COPYRIGHT AND LICENSE
• 13 Texinfo::Convert::Texinfo
  • 13.1 Texinfo::Convert::Texinfo NAME
  • 13.2 Texinfo::Convert::Texinfo SYNOPSIS
  • 13.3 Texinfo::Convert::Texinfo NOTES
  • 13.4 Texinfo::Convert::Texinfo DESCRIPTION
  • 13.5 Texinfo::Convert::Texinfo METHODS
  • 13.6 Texinfo::Convert::Texinfo AUTHOR
  • 13.7 Texinfo::Convert::Texinfo COPYRIGHT AND LICENSE
• 14 Texinfo::Convert::Utils
  • 14.1 Texinfo::Convert::Utils NAME
  • 14.2 Texinfo::Convert::Utils SYNOPSIS
  • 14.3 Texinfo::Convert::Utils NOTES
  • 14.4 Texinfo::Convert::Utils DESCRIPTION
  • 14.5 Texinfo::Convert::Utils METHODS
  • 14.6 Texinfo::Convert::Utils SEE ALSO
  • 14.7 Texinfo::Convert::Utils AUTHOR
  • 14.8 Texinfo::Convert::Utils COPYRIGHT AND LICENSE
• 15 Texinfo::Convert::Unicode
  • 15.1 Texinfo::Convert::Unicode NAME
  • 15.2 Texinfo::Convert::Unicode SYNOPSIS
  • 15.3 Texinfo::Convert::Unicode NOTES
  • 15.4 Texinfo::Convert::Unicode DESCRIPTION
  • 15.5 Texinfo::Convert::Unicode METHODS
  • 15.6 Texinfo::Convert::Unicode AUTHOR
  • 15.7 Texinfo::Convert::Unicode COPYRIGHT AND LICENSE
• 16 Texinfo::Convert::NodeNameNormalization
  • 16.1 Texinfo::Convert::NodeNameNormalization NAME
  • 16.2 Texinfo::Convert::NodeNameNormalization SYNOPSIS
  • 16.3 Texinfo::Convert::NodeNameNormalization NOTES
  • 16.4 Texinfo::Convert::NodeNameNormalization DESCRIPTION
  • 16.5 Texinfo::Convert::NodeNameNormalization METHODS
  • 16.6 Texinfo::Convert::NodeNameNormalization AUTHOR
  • 16.7 Texinfo::Convert::NodeNameNormalization COPYRIGHT AND LICENSE
• 17 Texinfo::Convert::Text
  • 17.1 Texinfo::Convert::Text NAME
  • 17.2 Texinfo::Convert::Text SYNOPSIS
  • 17.3 Texinfo::Convert::Text NOTES
  • 17.4 Texinfo::Convert::Text DESCRIPTION
  • 17.5 Texinfo::Convert::Text METHODS
  • 17.6 Texinfo::Convert::Text AUTHOR
  • 17.7 Texinfo::Convert::Text COPYRIGHT AND LICENSE
• 18 Texinfo::Convert::Converter
  • 18.1 Texinfo::Convert::Converter NAME
  • 18.2 Texinfo::Convert::Converter SYNOPSIS
  • 18.3 Texinfo::Convert::Converter NOTES
  • 18.4 Texinfo::Convert::Converter DESCRIPTION
  • 18.5 Texinfo::Convert::Converter METHODS
    • 18.5.1 Converter Initialization
    • 18.5.2 Conversion
    • 18.5.3 Output units and converter destruction
    • 18.5.4 Getting and setting customization variables
    • 18.5.5 Registering error and warning messages
    • 18.5.6 Translations in output documents
    • 18.5.7 Index sorting
    • 18.5.8 Accents conversion
    • 18.5.9 Conversion to XML
    • 18.5.10 Helper methods
  • 18.6 Texinfo::Convert::Converter SEE ALSO
  • 18.7 Texinfo::Convert::Converter AUTHOR
  • 18.8 Texinfo::Convert::Converter COPYRIGHT AND LICENSE
• 19 Texinfo::Convert::Info
  • 19.1 Texinfo::Convert::Info NAME
  • 19.2 Texinfo::Convert::Info SYNOPSIS
  • 19.3 Texinfo::Convert::Info NOTES
  • 19.4 Texinfo::Convert::Info DESCRIPTION
  • 19.5 Texinfo::Convert::Info METHODS
  • 19.6 Texinfo::Convert::Info AUTHOR
  • 19.7 Texinfo::Convert::Info COPYRIGHT AND LICENSE
• 20 Texinfo::Convert::HTML
  • 20.1 Texinfo::Convert::HTML NAME
  • 20.2 Texinfo::Convert::HTML SYNOPSIS
  • 20.3 Texinfo::Convert::HTML NOTES
  • 20.4 Texinfo::Convert::HTML DESCRIPTION
  • 20.5 Texinfo::Convert::HTML METHODS
  • 20.6 Texinfo::Convert::HTML AUTHOR
  • 20.7 Texinfo::Convert::HTML COPYRIGHT AND LICENSE
• 21 Texinfo::Convert::DocBook
  • 21.1 Texinfo::Convert::DocBook NAME
  • 21.2 Texinfo::Convert::DocBook SYNOPSIS
  • 21.3 Texinfo::Convert::DocBook NOTES
  • 21.4 Texinfo::Convert::DocBook DESCRIPTION
  • 21.5 Texinfo::Convert::DocBook METHODS
  • 21.6 Texinfo::Convert::DocBook AUTHOR
  • 21.7 Texinfo::Convert::DocBook COPYRIGHT AND LICENSE
• 22 Texinfo::Convert::TexinfoMarkup
  • 22.1 Texinfo::Convert::TexinfoMarkup NAME
  • 22.2 Texinfo::Convert::TexinfoMarkup SYNOPSIS
  • 22.3 Texinfo::Convert::TexinfoMarkup NOTES
  • 22.4 Texinfo::Convert::TexinfoMarkup DESCRIPTION
  • 22.5 Texinfo::Convert::TexinfoMarkup METHODS
    • 22.5.1 Markup formatting methods defined by subclasses
    • 22.5.2 Formatting state information
  • 22.6 Texinfo::Convert::TexinfoMarkup AUTHOR
  • 22.7 Texinfo::Convert::TexinfoMarkup SEE ALSO
  • 22.8 Texinfo::Convert::TexinfoMarkup COPYRIGHT AND LICENSE
• 23 Texinfo::Convert::TexinfoXML
  • 23.1 Texinfo::Convert::TexinfoXML NAME
  • 23.2 Texinfo::Convert::TexinfoXML SYNOPSIS
  • 23.3 Texinfo::Convert::TexinfoXML NOTES
  • 23.4 Texinfo::Convert::TexinfoXML DESCRIPTION
  • 23.5 Texinfo::Convert::TexinfoXML METHODS
  • 23.6 Texinfo::Convert::TexinfoXML AUTHOR
  • 23.7 Texinfo::Convert::TexinfoXML COPYRIGHT AND LICENSE
• 24 Texinfo::Convert::Plaintext
  • 24.1 Texinfo::Convert::Plaintext NAME
  • 24.2 Texinfo::Convert::Plaintext SYNOPSIS
  • 24.3 Texinfo::Convert::Plaintext NOTES
  • 24.4 Texinfo::Convert::Plaintext DESCRIPTION
  • 24.5 Texinfo::Convert::Plaintext METHODS
  • 24.6 Texinfo::Convert::Plaintext AUTHOR
  • 24.7 Texinfo::Convert::Plaintext COPYRIGHT AND LICENSE
• 25 Texinfo::TreeElement
  • 25.1 Texinfo::TreeElement NAME
  • 25.2 Texinfo::TreeElement SYNOPSIS
  • 25.3 Texinfo::TreeElement NOTES
  • 25.4 Texinfo::TreeElement DESCRIPTION
  • 25.5 Texinfo::TreeElement METHODS
    • 25.5.1 Texinfo::TreeElement and XS extensions
  • 25.6 Texinfo::TreeElement SEE ALSO
  • 25.7 Texinfo::TreeElement AUTHOR
  • 25.8 Texinfo::TreeElement COPYRIGHT AND LICENSE
• 26 Texinfo::Reader
  • 26.1 Texinfo::Reader NAME
  • 26.2 Texinfo::Reader SYNOPSIS
  • 26.3 Texinfo::Reader NOTES
  • 26.4 Texinfo::Reader DESCRIPTION
  • 26.5 Texinfo::Reader METHODS
    • 26.5.1 Texinfo::Reader and XS extensions
  • 26.6 Texinfo::Reader SEE ALSO
  • 26.7 Texinfo::Reader AUTHOR
  • 26.8 Texinfo::Reader COPYRIGHT AND LICENSE
• 27 Texinfo::Example::TreeElementConverter
  • 27.1 Texinfo::Example::TreeElementConverter NAME
  • 27.2 Texinfo::Example::TreeElementConverter SYNOPSIS
  • 27.3 Texinfo::Example::TreeElementConverter NOTES
  • 27.4 Texinfo::Example::TreeElementConverter DESCRIPTION
  • 27.5 Texinfo::Example::TreeElementConverter METHODS
    • 27.5.1 Related methods from other modules
  • 27.6 Texinfo::Example::TreeElementConverter SEE ALSO
  • 27.7 Texinfo::Example::TreeElementConverter AUTHOR
  • 27.8 Texinfo::Example::TreeElementConverter COPYRIGHT AND LICENSE
• Appendix A Index

Next: Texinfo::Commands SYNOPSIS , Up: Texinfo::Commands [Contents][Index]

1.1 Texinfo::Commands NAME ¶

Texinfo::Commands - Classification of commands

Next: Texinfo::Commands NOTES , Previous: Texinfo::Commands NAME , Up: Texinfo::Commands [Contents][Index]

1.2 Texinfo::Commands SYNOPSIS ¶

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

Next: Texinfo::Commands DESCRIPTION , Previous: Texinfo::Commands SYNOPSIS , Up: Texinfo::Commands [Contents][Index]

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.

Next: @-COMMAND INFORMATION , Previous: Texinfo::Commands NOTES , Up: Texinfo::Commands [Contents][Index]

1.4 Texinfo::Commands DESCRIPTION ¶

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

Next: @-COMMAND CLASSES , Previous: Texinfo::Commands DESCRIPTION , Up: Texinfo::Commands [Contents][Index]

1.5 @-COMMAND INFORMATION ¶

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

%index_names

Hash describing the default Texinfo indices. The format of this hash is described in Texinfo::Document::indices_information.

Next: Texinfo::Commands SEE ALSO , Previous: @-COMMAND INFORMATION , Up: Texinfo::Commands [Contents][Index]

1.6 @-COMMAND CLASSES ¶

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

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

%accent_commands

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

%block_commands

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

conditional

@if* commands;

def

Definition commands like @deffn;

float

@float;

format_raw

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

item_container

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

item_line

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

menu

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

math

Math block commands, like @displaymath.

multitable

@multitable;

other

The remaining block commands.

preformatted

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

quotation

Commands like @quotation.

raw

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

region

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

%blockitem_commands

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

%brace_code_commands

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

%brace_commands

The commands that take braces. Value is noarg for brace commands without argument such as @AA, @TeX, or @equiv. Other values include accent, arguments, context and other values.

%close_paragraph_commands

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

%commands_args_number

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

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

%contain_basic_inline_commands

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

%contain_plain_text_commands

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

%def_commands

Definition commands.

%default_index_commands

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

%explained_commands

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

%formattable_line_commands

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

%formatted_nobrace_commands

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

%formatted_line_commands

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

%heading_spec_commands

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

%in_heading_spec_commands

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

%in_index_commands

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

%inline_conditional_commands

%inline_format_commands

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

%letter_no_arg_commands

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

%math_commands

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

%line_commands

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

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

%no_paragraph_commands

Commands that do not start a paragraph.

%nobrace_commands

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

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

%non_formatted_block_commands

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

%non_formatted_brace_commands

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

%preamble_commands

@-commands that do not stop the preamble.

%preformatted_commands

%preformatted_code_commands

%preformatted_commands is for commands whose content should not be filled, like @example or @display. If the command is meant for code, it is also in %preformatted_code_commands, like @example.

%ref_commands

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

%root_commands

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

%sectioning_heading_commands

All the sectioning and heading commands.

%variadic_commands

Commands with unlimited arguments, like @example.

Next: Texinfo::Commands AUTHOR , Previous: @-COMMAND CLASSES , Up: Texinfo::Commands [Contents][Index]

1.7 Texinfo::Commands SEE ALSO ¶

Texinfo::Parser.

Next: Texinfo::Commands COPYRIGHT AND LICENSE , Previous: Texinfo::Commands SEE ALSO , Up: Texinfo::Commands [Contents][Index]

1.8 Texinfo::Commands AUTHOR ¶

Patrice Dumas, <pertusus@free.fr>

Previous: Texinfo::Commands AUTHOR , Up: Texinfo::Commands [Contents][Index]

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.

Next: Texinfo::CommandsValues SYNOPSIS , Up: Texinfo::CommandsValues [Contents][Index]

2.1 Texinfo::CommandsValues NAME ¶

Texinfo::CommandsValues - Associations of information to Texinfo @-commands

Next: Texinfo::CommandsValues NOTES , Previous: Texinfo::CommandsValues NAME , Up: Texinfo::CommandsValues [Contents][Index]

2.2 Texinfo::CommandsValues SYNOPSIS ¶

 use Texinfo::CommandsValues;
 my $command_text = $Texinfo::CommandsValues::nobrace_symbol_text{'@'};

Next: Texinfo::CommandsValues DESCRIPTION , Previous: Texinfo::CommandsValues SYNOPSIS , Up: Texinfo::CommandsValues [Contents][Index]

2.3 Texinfo::CommandsValues NOTES ¶

The Texinfo Perl module main purpose is to be used in texi2any to convert Texinfo to other formats. There is no promise of API stability.

Next: @-COMMAND ASSOCIATED INFORMATION , Previous: Texinfo::CommandsValues NOTES , Up: Texinfo::CommandsValues [Contents][Index]

2.4 Texinfo::CommandsValues DESCRIPTION ¶

Texinfo::CommandsValues holds hashes with information on @-commands. Only hashes relevant for conversion of @-commands are documented.

Next: Texinfo::CommandsValues SEE ALSO , Previous: Texinfo::CommandsValues DESCRIPTION , Up: Texinfo::CommandsValues [Contents][Index]

2.5 @-COMMAND ASSOCIATED INFORMATION ¶

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

%nobrace_symbol_text

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

%text_brace_no_arg_commands

Values are ASCII representation of commands with empty braces such as atchar, LaTeX, arrow, quoteleft or AA.

%unicode_diacritics

Keys are Texinfo accent commands, such as ' or ogonek. Values are strings of hexadecimal numbers representing the Unicode codepoint of the diacritic associated to the accent command. A diacritic is a zero-length character that should be combined with adjacent characters to have the whole interpreted as an accented character.

Next: Texinfo::CommandsValues AUTHOR , Previous: @-COMMAND ASSOCIATED INFORMATION , Up: Texinfo::CommandsValues [Contents][Index]

2.6 Texinfo::CommandsValues SEE ALSO ¶

Texinfo::Commands. Texinfo::Convert::Unicode.

Next: Texinfo::CommandsValues COPYRIGHT AND LICENSE , Previous: Texinfo::CommandsValues SEE ALSO , Up: Texinfo::CommandsValues [Contents][Index]

2.7 Texinfo::CommandsValues AUTHOR ¶

Patrice Dumas, <pertusus@free.fr>

Previous: Texinfo::CommandsValues AUTHOR , Up: Texinfo::CommandsValues [Contents][Index]

2.8 Texinfo::CommandsValues COPYRIGHT AND LICENSE ¶

Copyright 2010- Free Software Foundation, Inc. See the source file for all copyright years.

This library is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

Next: Texinfo::Common SYNOPSIS , Up: Texinfo::Common [Contents][Index]

3.1 Texinfo::Common NAME ¶

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

Next: Texinfo::Common NOTES , Previous: Texinfo::Common NAME , Up: Texinfo::Common [Contents][Index]

3.2 Texinfo::Common SYNOPSIS ¶

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

Next: Texinfo::Common DESCRIPTION , Previous: Texinfo::Common SYNOPSIS , Up: Texinfo::Common [Contents][Index]

3.3 Texinfo::Common NOTES ¶

The Texinfo Perl module main purpose is to be used in texi2any to convert Texinfo to other formats. There is no promise of API stability.

Next: MISC INFORMATION , Previous: Texinfo::Common NOTES , Up: Texinfo::Common [Contents][Index]

3.4 Texinfo::Common DESCRIPTION ¶

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

Next: @-COMMAND INFORMATION , Previous: Texinfo::Common DESCRIPTION , Up: Texinfo::Common [Contents][Index]

3.5 MISC INFORMATION ¶

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

$value = get_build_constant($name)

The following build constants are available:

PACKAGE

PACKAGE_CONFIG

PACKAGE_AND_VERSION

PACKAGE_AND_VERSION_CONFIG

PACKAGE_NAME

PACKAGE_NAME_CONFIG

PACKAGE_VERSION

PACKAGE_VERSION_CONFIG

PACKAGE_URL

PACKAGE_URL_CONFIG

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

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

%document_settable_at_commands

Keys are customization options corresponding to @-commands. For example frenchspacing or footnotestyle.

%null_device_file

Keys are null devices names, such as /dev/null or NUL.

%texinfo_output_formats

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

Next: Texinfo::Common METHODS , Previous: MISC INFORMATION , Up: Texinfo::Common [Contents][Index]

3.6 @-COMMAND INFORMATION ¶

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

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

%all_commands

All the @-commands.

%def_aliases

%def_no_var_arg_commands

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

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

%small_block_associated_command

Associate small command like smallexample to the regular command example.

Next: Texinfo::Common SEE ALSO , Previous: @-COMMAND INFORMATION , Up: Texinfo::Common [Contents][Index]

3.7 Texinfo::Common METHODS ¶

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

The Texinfo tree and Texinfo tree elements used in argument of some functions are documented in TEXINFO 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 Getting and setting customization variables.

$translated_string = __($msgid)

$translated_string = __p($msgctxt, $msgid)

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

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

See Locale::Messages, gettext C interface, Perl in GNU Gettext. For translation of strings in output, see Texinfo::Translations.

collect_commands_in_tree($tree, $commands_list)

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

collect_commands_list_in_tree($tree, $commands_list)

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

$encoding_name = associated_processing_encoding($element)

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

$result = element_is_inline($element, $check_current)

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

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

Encode the $file_name text string to a binary string $encoded_file_name based on $input_encoding. Also returns the $encoding name actually used which may have undergone some normalization. This function is mostly a wrapper around Encode Encode::encode which avoids calling the module if not needed. Do nothing if $input_encoding is undef.

$text = enumerate_item_representation($specification, $number)

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

 enumerate_item_representation('c', 3)

is e.

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

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

$command = find_parent_root_command($object, $tree_element)

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

$entry_content_element = index_content_element($element, $prefer_reference_element)

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

$encoding = input_file_name_encoding($name_encoding, $doc_encoding_for_input_file_name, $locale_encoding, $document, $input_file_encoding)

Returns the encoding assumed for input file names. $name_encoding is used as encoding name if defined. If $doc_encoding_for_input_file_name is set, the encoding is based on the input file content encoding, otherwise $locale_encoding is used. The $document argument is an optional Texinfo parsed document used to get the input document content encoding. The $input_file_encoding argument is optional, it will be used in priority if the the encoding is based on the input file encoding. If $input_file_encoding is not given, it is recommended to pass $document, otherwise there is no way to determine the input document content encoding.

$result = is_content_empty($tree, $do_not_ignore_index_entries)

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

$file = locate_include_file($customization_information, $file_path)

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

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

Returns an $index_entry hash based on the $index_entry_info and $indices_information. Also returns the $index_info hash with information on the index associated to the index entry. $index_entry_info should be an array reference with an index name as first element and the index entry number in that index (1-based) as second element. In general, the $index_entry_info is an extra index_entry associated to an element.

The $index_entry hash is described in Texinfo::Document index_entries. The $index_info hash is described in Texinfo::Document::indices_information.

$normalized_name = normalize_top_node_name($node_string)

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

$result = replace_remove_list_element($array, $element, $replacement)

Remove first occurence of $element in the array reference $array. If the optional $replacement argument is given, replace the $element by $replacement. Return the removed element, or undef if not found.

$level = section_level($section)

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

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

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

last

Set to the last value for the command.

preamble

Set sequentially to the values in the Texinfo preamble.

preamble_or_first

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

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

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

$status = set_informative_command_value($customization_information, $element)

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

set_output_encoding($customization_information, $document)

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

$split_contents = split_custom_heading_command_contents($element)

Split the $element contents at @| in at max three parts. Return an element containing the split parts in contents, or undef if the $element has no useful content. The input $element is supposed to be the argument line element of %Texinfo::Commands::heading_spec_commands commands such as @everyheading.

$status = valid_customization_option($name)

Return true if the $name is a known customization option.

$status = valid_tree_transformation($name)

Return true if the $name is a known tree transformation name that may be passed with TREE_TRANSFORMATIONS to modify a Texinfo tree.

Next: Texinfo::Common AUTHOR , Previous: Texinfo::Common METHODS , Up: Texinfo::Common [Contents][Index]

3.8 Texinfo::Common SEE ALSO ¶

Texinfo::Parser, Texinfo::Convert::Converter and Texinfo::Report.

Next: Texinfo::Common COPYRIGHT AND LICENSE , Previous: Texinfo::Common SEE ALSO , Up: Texinfo::Common [Contents][Index]

3.9 Texinfo::Common AUTHOR ¶

Patrice Dumas, <bug-texinfo@gnu.org>

Previous: Texinfo::Common AUTHOR , Up: Texinfo::Common [Contents][Index]

3.10 Texinfo::Common COPYRIGHT AND LICENSE ¶

Copyright 2010- Free Software Foundation, Inc. See the source file for all copyright years.

This library is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

Next: Texinfo::Parser SYNOPSIS , Up: Texinfo::Parser [Contents][Index]

4.1 Texinfo::Parser NAME ¶

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

Next: Texinfo::Parser NOTES , Previous: Texinfo::Parser NAME , Up: Texinfo::Parser [Contents][Index]

4.2 Texinfo::Parser SYNOPSIS ¶

 use Texinfo::Parser;
 my $parser = Texinfo::Parser::parser();
 my $document = $parser->parse_texi_file("somefile.texi");
 my $errors = $document->parser_errors();
 foreach my $error_message (@$errors) {
 warn $error_message->{'error_line'};
 }

Next: Texinfo::Parser DESCRIPTION , Previous: Texinfo::Parser SYNOPSIS , Up: Texinfo::Parser [Contents][Index]

4.3 Texinfo::Parser NOTES ¶

The Texinfo Perl module main purpose is to be used in texi2any to convert Texinfo to other formats. There is no promise of API stability.

Next: Texinfo::Parser METHODS , Previous: Texinfo::Parser NOTES , Up: Texinfo::Parser [Contents][Index]

4.4 Texinfo::Parser DESCRIPTION ¶

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

Next: TEXINFO TREE , Previous: Texinfo::Parser DESCRIPTION , Up: Texinfo::Parser [Contents][Index]

4.5 Texinfo::Parser METHODS ¶

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

• Initialization
• Parsing Texinfo text

Next: Texinfo::Parser SEE ALSO , Previous: Texinfo::Parser METHODS , Up: Texinfo::Parser [Contents][Index]

4.6 TEXINFO TREE ¶

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

The contents key holds an array reference for the children of @-command tree elements and containers. In particular for arguments of an @-command, either in braces or on the rest of the line after the command, depending on the type of command. Also for content appearing within a block @-command, within a container, or within a @node or sectioning @-command. Text fragments do not have children.

The extra and info keys are associated to hash references and hold information gathered during the parsing.

• Texinfo tree structure
• Element keys
• Element types
• Information available in the info key
• Information available in the extra key

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

 makeinfo -c TEXINFO_OUTPUT_FORMAT=debugtree document.texi

Next: Texinfo::Parser AUTHOR , Previous: TEXINFO TREE , Up: Texinfo::Parser [Contents][Index]

4.7 Texinfo::Parser SEE ALSO ¶

Texinfo manual.

Next: Texinfo::Parser COPYRIGHT AND LICENSE , Previous: Texinfo::Parser SEE ALSO , Up: Texinfo::Parser [Contents][Index]

4.8 Texinfo::Parser AUTHOR ¶

Patrice Dumas, <bug-texinfo@gnu.org>

Previous: Texinfo::Parser AUTHOR , Up: Texinfo::Parser [Contents][Index]

4.9 Texinfo::Parser COPYRIGHT AND LICENSE ¶

Copyright 2010- Free Software Foundation, Inc. See the source file for all copyright years.

This library is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

Next: Texinfo::Document SYNOPSIS , Up: Texinfo::Document [Contents][Index]

5.1 Texinfo::Document NAME ¶

Texinfo::Document - Texinfo document tree and information

Next: Texinfo::Document NOTES , Previous: Texinfo::Document NAME , Up: Texinfo::Document [Contents][Index]

5.2 Texinfo::Document SYNOPSIS ¶

 use Texinfo::Parser;
 my $parser = Texinfo::Parser::parser();
 my $document = $parser->parse_texi_file("somefile.texi");
 my $indices_information = $document->indices_information();
 my $float_types_arrays = $document->floats_information();
 my $internal_references_array
 = $document->internal_references_information();
 # $identifier_target is an hash reference on normalized
 # node/float/anchor/namedanchor names.
 my $identifier_target = $document->labels_information();
 # A hash reference, keys are @-command names, value is the
 # corresponding @-commands tree element or an
 # array reference holding all the corresponding @-commands.
 # Also contains dircategory and direntry list.
 my $global_commands_information
 = $document->global_commands_information();
 # a hash reference on document information (encodings,
 # input file name, for example).
 my $global_information = $document->global_information();

Next: Texinfo::Document DESCRIPTION , Previous: Texinfo::Document SYNOPSIS , Up: Texinfo::Document [Contents][Index]

5.3 Texinfo::Document NOTES ¶

The Texinfo Perl module main purpose is to be used in texi2any to convert Texinfo to other formats. There is no promise of API stability.

Next: Texinfo::Document METHODS , Previous: Texinfo::Document NOTES , Up: Texinfo::Document [Contents][Index]

5.4 Texinfo::Document DESCRIPTION ¶

This module is used to represent parsed Texinfo documents, with the Texinfo tree and associated information. A document is always obtained from a Texinfo parser method call as the result of parsing a Texinfo text or file.

For example, the $document obtained in the following example is a Texinfo::Document object:

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

Next: Texinfo::Document SEE ALSO , Previous: Texinfo::Document DESCRIPTION , Up: Texinfo::Document [Contents][Index]

5.5 Texinfo::Document METHODS ¶

• Getting document information
• Merging and sorting indexes
• Getting errors and warnings
• Getting customization options values registered in document
• Registering information in document
• Methods for Perl and C code interactions

Next: Texinfo::Document AUTHOR , Previous: Texinfo::Document METHODS , Up: Texinfo::Document [Contents][Index]

5.6 Texinfo::Document SEE ALSO ¶

Texinfo::Parser. Texinfo::Structuring.

Next: Texinfo::Document COPYRIGHT AND LICENSE , Previous: Texinfo::Document SEE ALSO , Up: Texinfo::Document [Contents][Index]

5.7 Texinfo::Document AUTHOR ¶

Patrice Dumas, <bug-texinfo@gnu.org>

Previous: Texinfo::Document AUTHOR , Up: Texinfo::Document [Contents][Index]

5.8 Texinfo::Document COPYRIGHT AND LICENSE ¶

Copyright 2010- Free Software Foundation, Inc. See the source file for all copyright years.

This library is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

Next: Texinfo::ManipulateTree SYNOPSIS , Up: Texinfo::ManipulateTree [Contents][Index]

6.1 Texinfo::ManipulateTree NAME ¶

Texinfo::ManipulateTree - Texinfo modules common tree manipulation functions

Next: Texinfo::ManipulateTree NOTES , Previous: Texinfo::ManipulateTree NAME , Up: Texinfo::ManipulateTree [Contents][Index]

6.2 Texinfo::ManipulateTree SYNOPSIS ¶

 use Texinfo::ManipulateTree;

Next: Texinfo::ManipulateTree DESCRIPTION , Previous: Texinfo::ManipulateTree SYNOPSIS , Up: Texinfo::ManipulateTree [Contents][Index]

6.3 Texinfo::ManipulateTree NOTES ¶

The Texinfo Perl module main purpose is to be used in texi2any to convert Texinfo to other formats. There is no promise of API stability.

Next: Texinfo::ManipulateTree METHODS , Previous: Texinfo::ManipulateTree NOTES , Up: Texinfo::ManipulateTree [Contents][Index]

6.4 Texinfo::ManipulateTree DESCRIPTION ¶

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

For optional tree transformation, see Texinfo::Transformations.

Next: Texinfo::ManipulateTree SEE ALSO , Previous: Texinfo::ManipulateTree DESCRIPTION , Up: Texinfo::ManipulateTree [Contents][Index]

6.5 Texinfo::ManipulateTree METHODS ¶

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

move_index_entries_after_items_in_document($document)

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

protect_colon_in_tree($tree)

protect_node_after_label_in_tree($tree)

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

protect_comma_in_tree($tree)

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

protect_first_parenthesis($element)

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

relate_index_entries_to_table_items_in_document($document)

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

Next: Texinfo::ManipulateTree AUTHOR , Previous: Texinfo::ManipulateTree METHODS , Up: Texinfo::ManipulateTree [Contents][Index]

6.6 Texinfo::ManipulateTree SEE ALSO ¶

Texinfo::Document, Texinfo::Structuring, Texinfo::Transformations.

Next: Texinfo::ManipulateTree COPYRIGHT AND LICENSE , Previous: Texinfo::ManipulateTree SEE ALSO , Up: Texinfo::ManipulateTree [Contents][Index]

6.7 Texinfo::ManipulateTree AUTHOR ¶

Patrice Dumas, <bug-texinfo@gnu.org>

Previous: Texinfo::ManipulateTree AUTHOR , Up: Texinfo::ManipulateTree [Contents][Index]

6.8 Texinfo::ManipulateTree COPYRIGHT AND LICENSE ¶

Copyright 2010- Free Software Foundation, Inc. See the source file for all copyright years.

This library is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

Next: Texinfo::Structuring SYNOPSIS , Up: Texinfo::Structuring [Contents][Index]

7.1 Texinfo::Structuring NAME ¶

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

Next: Texinfo::Structuring NOTES , Previous: Texinfo::Structuring NAME , Up: Texinfo::Structuring [Contents][Index]

7.2 Texinfo::Structuring SYNOPSIS ¶

 use Texinfo::Structuring qw(sectioning_structure construct_nodes_tree
 number_floats associate_internal_references);
 # $document is a parsed Texinfo::Document document.
 # When customization variables information is needed, it is obtained
 # from the $document by calling the get_conf() method.
 sectioning_structure($document);
 construct_nodes_tree($document);
 check_node_tree_menu_structure($document);
 complete_node_tree_with_menus($document);
 check_nodes_are_referenced($document);
 associate_internal_references($document);
 number_floats($document->floats_information());

Next: Texinfo::Structuring DESCRIPTION , Previous: Texinfo::Structuring SYNOPSIS , Up: Texinfo::Structuring [Contents][Index]

7.3 Texinfo::Structuring NOTES ¶

The Texinfo Perl module main purpose is to be used in texi2any to convert Texinfo to other formats. There is no promise of API stability.

Next: Texinfo::Structuring METHODS , Previous: Texinfo::Structuring NOTES , Up: Texinfo::Structuring [Contents][Index]

7.4 Texinfo::Structuring DESCRIPTION ¶

Texinfo::Structuring allows to collect information on a Texinfo document structure. Thanks to sectioning_structure the hierarchy of sectioning commands is determined. The node tree is analysed with construct_nodes_tree. Structural checking and warning on the consistency of menus and sectioning structure is done by check_node_tree_menu_structure. Nodes directions are completed with menu directions with complete_node_tree_with_menus. Floats get their standard numbering with number_floats and internal references are matched up with nodes, floats or anchors with associate_internal_references.

Next: Texinfo::Structuring SEE ALSO , Previous: Texinfo::Structuring DESCRIPTION , Up: Texinfo::Structuring [Contents][Index]

7.5 Texinfo::Structuring METHODS ¶

No method is exported in the default case.

Most methods use the error messages list from a parsed document for error reporting. Most also require Texinfo customization variables information, which means an object implementing the get_conf method, in general a parsed document with registered customization, or, sometime, a converter (Getting and setting customization variables). Other common data needed such as target elements associated to identifiers or refs are obtained from a parsed document, see Texinfo::Document.

associate_internal_references($document)

Verify that internal references (@ref and similar without fourth of fifth argument and menu entries) have an associated node, anchor or float. Set the normalized key in the extra hash of menu_entry_node container for menu entries and in the first argument extra hash for internal references @ref and similar @-commands.

check_nodes_are_referenced($document)

Check that all the nodes are referenced (in menu, @*ref or node direction).

Should be called after complete_node_tree_with_menus in order to have corresponding autogenerated node directions set.

complete_node_tree_with_menus($document)

Complete nodes directions with menu directions and Top node first node directions.

check_node_tree_menu_structure($document)

Check consistency of menus, sectioning and nodes directions.

@children_nodes = get_node_node_childs_from_sectioning($node_relations)

Find the $node_relations node relations children based on the sectioning structure. For the node associated with @top sectioning command, the sections associated with parts are considered.

new_block_command($element, $command_name)

Complete $element by adding the $command_name, the command line argument and @end to turn the element to a proper block command.

$new_menu = new_complete_node_menu($node_relations, $lang_translations, $debug_level, $use_sections)

Returns a @menu Texinfo tree element for the node relations $node_relations, pointing to the children of the node obtained with the sectioning structure. If $use_sections is set, use section names for the menu entry names. The $lang_translations argument should be an array reference with one or two elements. The first element of the array is the language used for translations. The second element, if set, should be an hash reference holding translations already done. $debug_level is an optional debugging level similar to the DEBUG customization variable. If set, it is supplied to the function called for translations. Translations are only needed when generating the top node menu.

$detailmenu = new_detailmenu($lang_translations, $converter, $document, $identifier_target, $nodes_list, $debug, $menus)

Returns a detailmenu tree element formatted as a master node. $menus is an array reference containing the regular menus of the Top node. $lang_translations argument should be an array reference with one or two elements. The first element of the array is the language used for translations. The second element, if set, should be an hash reference holding translations already done. If $debug optional arguments is set, debugging mode is assumed. $converter should hold information needed for translations and error reporting. $identifier_target should hold information on cross-reference target commands, typically obtained by calling Texinfo::Document::labels_information. $nodes_list should be the list of nores relations information, typically obtained by calling Texinfo::Document::nodes_list.

$converter, if set, is used for error reporting (Registering error and warning messages). If not set, the $document is used for error reporting instead.

$entry = new_node_menu_entry($node_relations, $use_sections)

Returns the Texinfo tree corresponding to a single menu entry pointing to $node_relations. If $use_sections is set, use the section name for the menu entry name. Returns undef if the node argument is missing.

construct_nodes_tree($document)

Goes through nodes in $document tree and set directions. This functions sets, in each node relations element hash:

node_directions

Hash reference with up, next and prev keys associated to the node line direction node relations.

number_floats($float_information)

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

$command_name = section_level_adjusted_command_name($element)

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

sectioning_structure($document)

This function goes through the parsed document tree and gather information on the document structure for sectioning commands.

It sets section elements extra hash values:

section_level

The level in the sectioning tree hierarchy. 0 is for @top or @part, 1 for @chapter, @appendix... This level is corrected by @raisesections and @lowersections.

section_heading_number

The sectioning command formatted number.

The following is set in section relations hashes:

section_children

An array holding sectioning element children. The children are also section relations.

section_directions

Hash reference with up, next and prev keys associated to section directions.

toplevel_directions

Hash reference with up, next and prev keys associated to toplevel sectioning relations directions, for elements like @top, @chapter, @appendix, not taking into account @part elements.

After calling this function, information on the sectioning tree root can be obtained by calling $document->sectioning_root().

warn_non_empty_parts($document)

Register a warning in for each @part in global commands information of $document that is not empty.

Next: Texinfo::Structuring AUTHOR , Previous: Texinfo::Structuring METHODS , Up: Texinfo::Structuring [Contents][Index]

7.6 Texinfo::Structuring SEE ALSO ¶

Texinfo manual, Texinfo::Document.

Next: Texinfo::Structuring COPYRIGHT AND LICENSE , Previous: Texinfo::Structuring SEE ALSO , Up: Texinfo::Structuring [Contents][Index]

7.7 Texinfo::Structuring AUTHOR ¶

Patrice Dumas, <bug-texinfo@gnu.org>

Previous: Texinfo::Structuring AUTHOR , Up: Texinfo::Structuring [Contents][Index]

7.8 Texinfo::Structuring COPYRIGHT AND LICENSE ¶

Copyright 2010- Free Software Foundation, Inc. See the source file for all copyright years.

This library is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

Next: Texinfo::Report SYNOPSIS , Up: Texinfo::Report [Contents][Index]

8.1 Texinfo::Report NAME ¶

Texinfo::Report - Error storing for Texinfo modules

Next: Texinfo::Report NOTES , Previous: Texinfo::Report NAME , Up: Texinfo::Report [Contents][Index]

8.2 Texinfo::Report SYNOPSIS ¶

 use Texinfo::Report;
 my $error_messages = [];
 if ($warning_happened) {
 push @$error_messages, Texinfo::Report::line_warn(
 sprintf(__("\@%s is wrongly used"),
 $current->{'cmdname'}), $current->{'source_info'},
 0, $converter->get_conf('DEBUG'));
 }
 foreach my $error_message (@$error_messages) {
 warn $error_message->{'error_line'};
 }

Next: Texinfo::Report DESCRIPTION , Previous: Texinfo::Report SYNOPSIS , Up: Texinfo::Report [Contents][Index]

8.3 Texinfo::Report NOTES ¶

The Texinfo Perl module main purpose is to be used in texi2any to convert Texinfo to other formats. There is no promise of API stability.

Next: Texinfo::Report METHODS , Previous: Texinfo::Report NOTES , Up: Texinfo::Report [Contents][Index]

8.4 Texinfo::Report DESCRIPTION ¶

The Texinfo::Report module helps with error handling. Errors and warnings can be setup, stored and retrieved later on. This module methods are used by the Texinfo::Parser and Texinfo::Convert::Converter modules.

Next: Texinfo::Report AUTHOR , Previous: Texinfo::Report DESCRIPTION , Up: Texinfo::Report [Contents][Index]

8.5 Texinfo::Report METHODS ¶

No method is exported in the default case.

The methods allow registering errors and warnings.

$error_count = count_errors ($error_messages)

This function returns as $error_count the count of errors in the error messages list (as opposed to warnings). The $error_warnings_list is an array of hash references one for each error, warning or error line continuation. Each of these has the following keys:

continuation

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

error_line

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

file_name

The file name where the error or warning occurs.

line_nr

The line number of the error or warning.

macro

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

text

The text of the error.

type

May be warning, or error.

$message = line_warn ($text, $error_location_info, $continuation, $debug, $silent)

$message = line_error ($text, $error_location_info, $continuation, $debug, $silent)

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

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

The $debug optional integer arguments sets the debug level.

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

The source_info key of Texinfo tree elements is described in more details in Texinfo::Parser source_info.

$message = document_warn ($text, $program_name, $continuation)

$message = document_error ($text, $program_name, $continuation)

Returns a document-wide error or warning message structure. $text is the error or warning message. The $program_name is prepended to the message, if defined. The $continuation optional arguments, if true, conveys that the line is a continuation line of a message.

Next: Texinfo::Report COPYRIGHT AND LICENSE , Previous: Texinfo::Report METHODS , Up: Texinfo::Report [Contents][Index]

8.6 Texinfo::Report AUTHOR ¶

Patrice Dumas, <bug-texinfo@gnu.org>

Previous: Texinfo::Report AUTHOR , Up: Texinfo::Report [Contents][Index]

8.7 Texinfo::Report COPYRIGHT AND LICENSE ¶

Copyright 2010- Free Software Foundation, Inc. See the source file for all copyright years.

This library is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

Next: Texinfo::Translations SYNOPSIS , Up: Texinfo::Translations [Contents][Index]

9.1 Texinfo::Translations NAME ¶

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

Next: Texinfo::Translations NOTES , Previous: Texinfo::Translations NAME , Up: Texinfo::Translations [Contents][Index]

9.2 Texinfo::Translations SYNOPSIS ¶

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

Next: Texinfo::Translations DESCRIPTION , Previous: Texinfo::Translations SYNOPSIS , Up: Texinfo::Translations [Contents][Index]

9.3 Texinfo::Translations NOTES ¶

The Texinfo Perl module main purpose is to be used in texi2any to convert Texinfo to other formats. There is no promise of API stability.

Next: Texinfo::Translations METHODS , Previous: Texinfo::Translations NOTES , Up: Texinfo::Translations [Contents][Index]

9.4 Texinfo::Translations DESCRIPTION ¶

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

Translation of error messages is not described here, some elements are in Texinfo::Common __ and __p.

Next: Texinfo::Translations SEE ALSO , Previous: Texinfo::Translations DESCRIPTION , Up: Texinfo::Translations [Contents][Index]

9.5 Texinfo::Translations METHODS ¶

No method is exported.

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

configure($localesdir, $strings_textdomain)

$localesdir is the directory where translation files are found. The directory structure and files format should follow the conventions expected for gettext based internationalization. The $strings_textdomain is optional, if set, it determines the translation domain.

The new_lang_translation method sets up a lang translation object that is used as argument inthe other method, that contains the language and associated already translated strings.

$lang_translations = new_lang_translation($lang, $locale_encoding)

$lang is the language of the returned lang translations. $locale encoding is optional and should be the encoding used to encode character strings to for environment variables. In general, you should base it on the COMMAND_LINE_ENCODING customization variable value.

The returned $lang_translations is an array reference. The first element of the array is the language. The second element is the language encoded to the local encoding. The third element should be set to an hash reference holding translations already done.

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

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

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

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

The $lang_translations argument should be an array reference with one or two elements. The first element of the array is the language used for the translation. The second element, if set, should be an hash reference holding translations already done.

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

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

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

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

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

By default, gdt and gdt_string call cache_translate_string to use a gettext-like infrastructure to retrieve the translated strings, using the texinfo_document domain. You can change the method used to retrieve the translated strings by providing a $translate_string_method argument. If not undef it should be a reference on a function that is called instead of cache_translate_string. The $object is passed as first argument of the $translate_string_method, the other arguments are the same as cache_translate_string arguments.

$tree = pgdt($translation_context, $string, $lang_translations, $replaced_substrings, $debug_level, $object, $translate_string_method)

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

By default, in gdt, gdt_string and pgdt a string is translated with cache_translate_string.

$translated_string_tree = cache_translate_string($string, $lang_translations, $translation_context)

The $string is a string to be translated. The $lang_translations argument should be an array reference with one or two elements. The first element of the array is the language used for the translation. The second element, if set, should be an hash reference holding translations already done. If the language is undef or an empty string, the input string does not need to be translated. The $translation_context is optional. If not undef this is a translation context string for $string. It is the first argument of pgettext in the C API of Gettext.

cache_translate_string uses a gettext-like infrastructure to retrieve the translated strings, using the texinfo_document domain. Returns an array reference with the translated string as first element, or undef if the input string should be used as translation. The second element of the reference array, if present, should be the Texinfo tree corresponding to the translated string, without the braced arguments substituted.

Next: Texinfo::Translations AUTHOR , Previous: Texinfo::Translations METHODS , Up: Texinfo::Translations [Contents][Index]

9.6 Texinfo::Translations SEE ALSO ¶

GNU gettext utilities manual.

Next: Texinfo::Translations COPYRIGHT AND LICENSE , Previous: Texinfo::Translations SEE ALSO , Up: Texinfo::Translations [Contents][Index]

9.7 Texinfo::Translations AUTHOR ¶

Patrice Dumas, <bug-texinfo@gnu.org>

Previous: Texinfo::Translations AUTHOR , Up: Texinfo::Translations [Contents][Index]

9.8 Texinfo::Translations COPYRIGHT AND LICENSE ¶

Copyright 2010- Free Software Foundation, Inc. See the source file for all copyright years.

This library is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

Next: Texinfo::Transformations NOTES , Up: Texinfo::Transformations [Contents][Index]

10.1 Texinfo::Transformations NAME ¶

Texinfo::Transformations - transformations of Texinfo tree

Next: Texinfo::Transformations DESCRIPTION , Previous: Texinfo::Transformations NAME , Up: Texinfo::Transformations [Contents][Index]

10.2 Texinfo::Transformations NOTES ¶

The Texinfo Perl module main purpose is to be used in texi2any to convert Texinfo to other formats. There is no promise of API stability.

Next: Texinfo::Transformations METHODS , Previous: Texinfo::Transformations NOTES , Up: Texinfo::Transformations [Contents][Index]

10.3 Texinfo::Transformations DESCRIPTION ¶

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

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

Next: Texinfo::Transformations SEE ALSO , Previous: Texinfo::Transformations DESCRIPTION , Up: Texinfo::Transformations [Contents][Index]

10.4 Texinfo::Transformations METHODS ¶

No method is exported in the default case.

complete_tree_nodes_menus_in_document($document, $add_section_names_in_entries)

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

complete_tree_nodes_missing_menu($document, $use_section_names_in_entries)

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

fill_gaps_in_sectioning_in_document($document, $commands_heading_tree)

This function adds empty @unnumbered and similar commands in a $document tree to fill gaps in sectioning. This may be used, for example, when converting from a format that can handle gaps in sectioning.

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

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

insert_nodes_for_sectioning_commands($document)

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

menu_to_simple_menu($menu)

menu_to_simple_menu transforms the tree of a menu tree element.

A simple menu has no menu_comment, menu_entry or menu_entry_description container anymore, their content are merged directly in the menu in preformatted container.

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

protect_hashchar_at_line_beginning($tree, $document)

Protect hash (#) character at the beginning of line such that they would not be considered as lines to be processed by the CPP processor. The $document argument is optional. If defined, the $document is used for error reporting in case an hash character could not be protected because it appeared in a raw formatted environment (@tex, @html...).

$modified_tree = reference_to_arg_in_tree($tree, $document)

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

A $modified_tree is not systematically returned, if the $tree in argument is not replaced, undef may also be returned.

regenerate_master_menu($document, $use_sections)

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

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

Next: Texinfo::Transformations AUTHOR , Previous: Texinfo::Transformations METHODS , Up: Texinfo::Transformations [Contents][Index]

10.5 Texinfo::Transformations SEE ALSO ¶

Texinfo manual, Texinfo::Parser, Texinfo::ManipulateTree.

Next: Texinfo::Transformations COPYRIGHT AND LICENSE , Previous: Texinfo::Transformations SEE ALSO , Up: Texinfo::Transformations [Contents][Index]

10.6 Texinfo::Transformations AUTHOR ¶

Patrice Dumas, <bug-texinfo@gnu.org>

Previous: Texinfo::Transformations AUTHOR , Up: Texinfo::Transformations [Contents][Index]

10.7 Texinfo::Transformations COPYRIGHT AND LICENSE ¶

Copyright 2010- Free Software Foundation, Inc. See the source file for all copyright years.

This library is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

Next: Texinfo::Indices SYNOPSIS , Up: Texinfo::Indices [Contents][Index]

11.1 Texinfo::Indices NAME ¶

Texinfo::Indices - merging and sorting indices from Texinfo

Next: Texinfo::Indices NOTES , Previous: Texinfo::Indices NAME , Up: Texinfo::Indices [Contents][Index]

11.2 Texinfo::Indices SYNOPSIS ¶

 use Texinfo::Indices;
 # $document is a parsed Texinfo::Document document.
 my $indices_information = $document->indices_information();
 my $merged_index_entries
 = Texinfo::Indices::merge_indices($indices_information);
 # $converter is a converter object
 my $index_entries_sorted;
 if ($sort_by_letter) {
 $index_entries_sorted
 = Texinfo::Indices::sort_indices_by_letter($document,
 $converter);
 } else {
 $index_entries_sorted
 = Texinfo::Indices::sort_indices_by_index($document,
 $converter);
 }

Next: Texinfo::Indices DESCRIPTION , Previous: Texinfo::Indices SYNOPSIS , Up: Texinfo::Indices [Contents][Index]

11.3 Texinfo::Indices NOTES ¶

The Texinfo Perl module main purpose is to be used in texi2any to convert Texinfo to other formats. There is no promise of API stability.

Next: Texinfo::Indices METHODS , Previous: Texinfo::Indices NOTES , Up: Texinfo::Indices [Contents][Index]

11.4 Texinfo::Indices DESCRIPTION ¶

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

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

Next: Texinfo::Indices SEE ALSO , Previous: Texinfo::Indices DESCRIPTION , Up: Texinfo::Indices [Contents][Index]

11.5 Texinfo::Indices METHODS ¶

No method is exported.

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

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

The tree element index entry processed is $index_entry_element, and can be a @subentry. $main_entry is the main index entry that can be used to gather information.

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

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

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

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

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

$merged_indices = merge_indices($indices_information)

Returns a structure holding all the index entries by index name with all the entries of merged indices merged with those of the indice merged into. The $indices_information argument should be an hash reference with indices information, it is described in details in Texinfo::Document::indices_information.

The $merged_indices returned is a hash reference whose keys are the index names and values arrays of index entry structures described in details in Texinfo::Document index_entries.

In general, this method should not be called directly, instead Texinfo::Document::merged_indices should be called on a document, which calls merge_indices if needed and associate the merged indices to the document.

$option = setup_index_entry_keys_formatting($customization_information)

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

$index_entries_sorted = sort_indices_by_index($document, $converter, $use_unicode_collation, $locale_lang)

$index_entries_sorted = sort_indices_by_letter($document, $converter, $use_unicode_collation, $locale_lang)

sort_indices_by_letter sorts by index and letter, while sort_indices_by_index sort all entries of an index together. Indices are obtained from $document, and should have been merged previously, in general by using Texinfo::Document::merged_indices. In both cases, a hash reference with index names as keys $index_entries_sorted is returned.

By default, indices are sorted according to the Unicode Collation Algorithm defined in the Unicode Technical Standard #10, without language-specific collation tailoring. If $use_unicode_collation is set to 0, the sorting will not use the Unicode Collation Algorithm and simply sort according to the codepoints. If $locale_lang is set, the language is used for linguistic tailoring of the sorting, if possible.

When sorting by letter, an array reference of letter hash references is associated with each index name. Each letter hash reference has two keys, a letter key with the letter, and an entries key with an array reference of sorted index entries beginning with the letter. The letter is a character string suitable for sorting letters, but is not necessarily the best to use for output.

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

The optional argument $converter is used for error reporting if present, otherwise the $document is used.

In general, those methods should not be called directly, instead Texinfo::Document::sorted_indices_by_index or Texinfo::Document::sorted_indices_by_letter should be called on a document. The Texinfo::Document functions call sort_indices_by_index or sort_indices_by_letter if needed and associate the sorted indices to the document.

Next: Texinfo::Indices AUTHOR , Previous: Texinfo::Indices METHODS , Up: Texinfo::Indices [Contents][Index]

11.6 Texinfo::Indices SEE ALSO ¶

Texinfo manual, Texinfo::Document.

Next: Texinfo::Indices COPYRIGHT AND LICENSE , Previous: Texinfo::Indices SEE ALSO , Up: Texinfo::Indices [Contents][Index]

11.7 Texinfo::Indices AUTHOR ¶

Patrice Dumas, <bug-texinfo@gnu.org>

Previous: Texinfo::Indices AUTHOR , Up: Texinfo::Indices [Contents][Index]

11.8 Texinfo::Indices COPYRIGHT AND LICENSE ¶

Copyright 2010- Free Software Foundation, Inc. See the source file for all copyright years.

This library is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

Next: Texinfo::OutputUnits SYNOPSIS , Up: Texinfo::OutputUnits [Contents][Index]

12.1 Texinfo::OutputUnits NAME ¶

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

Next: Texinfo::OutputUnits NOTES , Previous: Texinfo::OutputUnits NAME , Up: Texinfo::OutputUnits [Contents][Index]

12.2 Texinfo::OutputUnits SYNOPSIS ¶

 use Texinfo::OutputUnits qw(split_by_node split_by_section split_pages
 units_directions units_file_directions);
 # $document is a parsed Texinfo::Document document.
 # When customization variables information is needed, it is obtained
 # from the $document by calling the get_conf() method.
 my $identifier_target = $document->labels_information();
 my $output_units;
 if ($split_at_nodes) {
 $output_units = split_by_node($document);
 } else {
 $output_units = split_by_section($document);
 }
 my $nodes_list = $document->nodes_list();
 split_pages($output_units, $nodes_list, $split);
 units_directions($identifier_target, $output_units,
 $nodes_list, $document->get_conf('DEBUG'));
 units_file_directions($output_units);

Next: Texinfo::OutputUnits DESCRIPTION , Previous: Texinfo::OutputUnits SYNOPSIS , Up: Texinfo::OutputUnits [Contents][Index]

12.3 Texinfo::OutputUnits NOTES ¶

The Texinfo Perl module main purpose is to be used in texi2any to convert Texinfo to other formats. There is no promise of API stability.

Next: Texinfo::OutputUnits METHODS , Previous: Texinfo::OutputUnits NOTES , Up: Texinfo::OutputUnits [Contents][Index]

12.4 Texinfo::OutputUnits DESCRIPTION ¶

You can convert a Texinfo parsed document to an output format in a Converter code by first splitting the nodes and sectioning commands in units and then converting those units. We will call the main unit of output documents an output unit. Usually a node is associated with a following sectioning command, while a sectioning command is associated with a previous node; they both together make up the output unit. Either the node or the sectioning command is considered to be the main element component.

The module provides methods to setup output units associated with node and sectioning commands of a Texinfo parsed document. With split_by_node nodes are used as the main component for the separation of output units, while with split_by_section the sectioning command elements are used to separate output units. The first mode is typical of Info format, while the second corresponds better to a traditional book. Note that the result is different when there are unassociated sectioning commands or nodes, in the usual case of each node being associated with a sectioning command and each sectioning command being associated with a node, splitting by node or by section does not make much difference as each output unit will consist of the node and the associated section in both cases.

Output units are used for conversion to HTML and Info output formats. See Texinfo::Convert::Converter::convert_output_unit for more information on conversion of output units in Converters. Output units are not relevant for all the formats, the Texinfo tree can also be converted directly, see Texinfo::Convert::Converter::output_tree.

The output units may be further grouped in pages, which are not pages as in book pages, but more like web pages, and hold series of output units. The output units may have directions to other output units prepared by units_directions. units_file_directions should also set direction related to files, provided files are associated with output units by the user.

Next: Texinfo::OutputUnits SEE ALSO , Previous: Texinfo::OutputUnits DESCRIPTION , Up: Texinfo::OutputUnits [Contents][Index]

12.5 Texinfo::OutputUnits METHODS ¶

No method is exported in the default case.

• Output units creation
• Grouping output units in pages
• Setting output units directions

Next: Texinfo::OutputUnits AUTHOR , Previous: Texinfo::OutputUnits METHODS , Up: Texinfo::OutputUnits [Contents][Index]

12.6 Texinfo::OutputUnits SEE ALSO ¶

Texinfo manual, Texinfo::Document, Texinfo::Convert::Converter.

Next: Texinfo::OutputUnits COPYRIGHT AND LICENSE , Previous: Texinfo::OutputUnits SEE ALSO , Up: Texinfo::OutputUnits [Contents][Index]

12.7 Texinfo::OutputUnits AUTHOR ¶

Patrice Dumas, <bug-texinfo@gnu.org>

Previous: Texinfo::OutputUnits AUTHOR , Up: Texinfo::OutputUnits [Contents][Index]

12.8 Texinfo::OutputUnits COPYRIGHT AND LICENSE ¶

Copyright 2010- Free Software Foundation, Inc. See the source file for all copyright years.

This library is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

Next: Texinfo::Convert::Texinfo SYNOPSIS , Up: Texinfo::Convert::Texinfo [Contents][Index]

13.1 Texinfo::Convert::Texinfo NAME ¶

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

Next: Texinfo::Convert::Texinfo NOTES , Previous: Texinfo::Convert::Texinfo NAME , Up: Texinfo::Convert::Texinfo [Contents][Index]

13.2 Texinfo::Convert::Texinfo SYNOPSIS ¶

 use Texinfo::Convert::Texinfo qw(convert_to_texinfo);
 my $texinfo_text = convert_to_texinfo($tree);

Next: Texinfo::Convert::Texinfo DESCRIPTION , Previous: Texinfo::Convert::Texinfo SYNOPSIS , Up: Texinfo::Convert::Texinfo [Contents][Index]

13.3 Texinfo::Convert::Texinfo NOTES ¶

The Texinfo Perl module main purpose is to be used in texi2any to convert Texinfo to other formats. There is no promise of API stability.

Next: Texinfo::Convert::Texinfo METHODS , Previous: Texinfo::Convert::Texinfo NOTES , Up: Texinfo::Convert::Texinfo [Contents][Index]

13.4 Texinfo::Convert::Texinfo DESCRIPTION ¶

Texinfo::Convert::Texinfo converts a Texinfo tree (described in Texinfo::Parser) 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.

Next: Texinfo::Convert::Texinfo AUTHOR , Previous: Texinfo::Convert::Texinfo DESCRIPTION , Up: Texinfo::Convert::Texinfo [Contents][Index]

13.5 Texinfo::Convert::Texinfo METHODS ¶

$texinfo_text = convert_to_texinfo($tree)

Converts the Texinfo tree $tree to Texinfo code.

Next: Texinfo::Convert::Texinfo COPYRIGHT AND LICENSE , Previous: Texinfo::Convert::Texinfo METHODS , Up: Texinfo::Convert::Texinfo [Contents][Index]

13.6 Texinfo::Convert::Texinfo AUTHOR ¶

Patrice Dumas, <bug-texinfo@gnu.org>

Previous: Texinfo::Convert::Texinfo AUTHOR , Up: Texinfo::Convert::Texinfo [Contents][Index]

13.7 Texinfo::Convert::Texinfo COPYRIGHT AND LICENSE ¶

Copyright 2010- Free Software Foundation, Inc. See the source file for all copyright years.

This library is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

Next: Texinfo::Convert::Utils SYNOPSIS , Up: Texinfo::Convert::Utils [Contents][Index]

14.1 Texinfo::Convert::Utils NAME ¶

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

Next: Texinfo::Convert::Utils NOTES , Previous: Texinfo::Convert::Utils NAME , Up: Texinfo::Convert::Utils [Contents][Index]

14.2 Texinfo::Convert::Utils SYNOPSIS ¶

 use Texinfo::Convert::Utils;

Next: Texinfo::Convert::Utils DESCRIPTION , Previous: Texinfo::Convert::Utils SYNOPSIS , Up: Texinfo::Convert::Utils [Contents][Index]

14.3 Texinfo::Convert::Utils NOTES ¶

The Texinfo Perl module main purpose is to be used in texi2any to convert Texinfo to other formats. There is no promise of API stability.

Next: Texinfo::Convert::Utils METHODS , Previous: Texinfo::Convert::Utils NOTES , Up: Texinfo::Convert::Utils [Contents][Index]

14.4 Texinfo::Convert::Utils DESCRIPTION ¶

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

Next: Texinfo::Convert::Utils SEE ALSO , Previous: Texinfo::Convert::Utils DESCRIPTION , Up: Texinfo::Convert::Utils [Contents][Index]

14.5 Texinfo::Convert::Utils METHODS ¶

No method is exported in the default case.

Some methods take an optional $converter argument for error reporting, see Registering error and warning messages. Even when the caller does not inherit from Texinfo::Convert::Converter, it could implement the required interfaces and could also have a converter available in some cases, to call the functions with the converter argument set.

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

$heading_element is a heading command tree element. $heading_text is the already formatted heading text. if the $do_number optional argument is defined and false, no number is used and the text is returned as is. The $lang_translations optional argument should be an array reference with one or two elements. The first element of the array is the language the resulting string is translated to. The second element, if set, should be an hash reference holding translations already done. If a language is set in $lang_translations, the string is translated and the optional $debug argument is passed to the translation function.

This function returns the heading with a number and the appendix part if needed.

$contents_element = comma_index_subentries_tree($entry, $separator)

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

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

$element should be a @def* Texinfo tree element. The $category, $class, $type, $name are elements corresponding to the definition @-command line. Texinfo elements on the @-command line corresponding to arguments in the function definition are returned in the $arguments element. Arguments correspond to text following the other elements on the @-command line. If there is no argument, $arguments will be undef.

$tree = definition_category_tree($def_line, $lang_translations, $command_line_encoding, $debug, $converter)

$def_line is a def_line Texinfo tree container. This function returns a Texinfo tree corresponding to the category of the $def_line taking the class into account, if there is one. The $lang_translations optional argument should be an array reference holding information on the current language and translations. It could be obtained from the converter current_lang_translations or be setup by a call to Texinfo::Translations::new_lang_translation. If $lang_translations is set, $command_line_encoding should be set to the encoding suitable for environment variables, usually obtained from the COMMAND_LINE_ENCODING customization variable, and the optional $debug argument is passed to the translation function. If the optional $converter argument is set, the translation is done by a converter method. In that case, $lang_translations and $debug are ignored, the converter method uses similar converter information.

($encoded_name, $encoding) = encoded_input_file_name($character_string_name, $input_file_name_encoding, $doc_encoding_for_input_file_name, $locale_encoding, $document, $input_file_encoding)

($encoded_name, $encoding) = encoded_output_file_name($character_string_name, $output_file_name_encoding, $doc_encoding_for_output_file_name, $locale_encoding, $document)

encoded_input_file_name encodes $character_string_name as an input file name. If $doc_encoding_for_input_file_name is set, the encoding is based on the input file content encoding, otherwise $locale_encoding is used. The $document argument is an optional Texinfo parsed document used to get the input document content encoding. encoded_output_file_name encodes $character_string_name as an output file name and takes similar arguments. Return the encoded name and the encoding used to encode the name.

The $input_file_encoding argument is optional and only available for encoded_input_file_name. If set, it is used for the input file encoding. It is useful if there is more precise information on the input file encoding where the file name appeared.

$tree = expand_verbatiminclude($verbatiminclude, $include_directories, $name_encoding, $doc_encoding_for_input_file_name, $locale_encoding, $document, $converter)

$verbatiminclude is a @verbatiminclude tree element. $include_directories is an array reference with include directories where the file specified as @verbatiminclude argument is searched for. $name_encoding, $doc_encoding_for_input_file_name, $locale_encoding and $document are encoded_input_file_name arguments. The optional $converter argument is used to output error messages. This function returns a @verbatim tree elements after finding the included file and reading it.

$documentinfo_info = get_document_documentinfo($document)

$document is a Texinfo parsed document. If @documentinfo is found in the document, return an hash reference with @-command names appearing in @documentinfo as keys associated to an array reference as value containing the @-commands Texinfo tree elements. Otherwise, returns undef.

Next: Texinfo::Convert::Utils AUTHOR , Previous: Texinfo::Convert::Utils METHODS , Up: Texinfo::Convert::Utils [Contents][Index]

14.6 Texinfo::Convert::Utils SEE ALSO ¶

Texinfo::Common, Texinfo::Convert::Converter and Texinfo::Translations.

Next: Texinfo::Convert::Utils COPYRIGHT AND LICENSE , Previous: Texinfo::Convert::Utils SEE ALSO , Up: Texinfo::Convert::Utils [Contents][Index]

14.7 Texinfo::Convert::Utils AUTHOR ¶

Patrice Dumas, <bug-texinfo@gnu.org>

Previous: Texinfo::Convert::Utils AUTHOR , Up: Texinfo::Convert::Utils [Contents][Index]

14.8 Texinfo::Convert::Utils COPYRIGHT AND LICENSE ¶

Copyright 2010- Free Software Foundation, Inc. See the source file for all copyright years.

This library is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

Next: Texinfo::Convert::Unicode SYNOPSIS , Up: Texinfo::Convert::Unicode [Contents][Index]

15.1 Texinfo::Convert::Unicode NAME ¶

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

Next: Texinfo::Convert::Unicode NOTES , Previous: Texinfo::Convert::Unicode NAME , Up: Texinfo::Convert::Unicode [Contents][Index]

15.2 Texinfo::Convert::Unicode SYNOPSIS ¶

 use Texinfo::Convert::Unicode qw(unicode_accent encoded_accents
 unicode_text);
 use Texinfo::Convert::Text qw(convert_to_text);
 my ($contents_element, $stack)
 = Texinfo::Common::find_innermost_accent_contents($accent);
 my $formatted_accents = encoded_accents($converter,
 convert_to_text($contents_element), $stack, $encoding,
 \&Texinfo::Text::ascii_accent_fallback);

Next: Texinfo::Convert::Unicode DESCRIPTION , Previous: Texinfo::Convert::Unicode SYNOPSIS , Up: Texinfo::Convert::Unicode [Contents][Index]

15.3 Texinfo::Convert::Unicode NOTES ¶

The Texinfo Perl module main purpose is to be used in texi2any to convert Texinfo to other formats. There is no promise of API stability.

Next: Texinfo::Convert::Unicode METHODS , Previous: Texinfo::Convert::Unicode NOTES , Up: Texinfo::Convert::Unicode [Contents][Index]

15.4 Texinfo::Convert::Unicode DESCRIPTION ¶

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

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

Next: Texinfo::Convert::Unicode AUTHOR , Previous: Texinfo::Convert::Unicode DESCRIPTION , Up: Texinfo::Convert::Unicode [Contents][Index]

15.5 Texinfo::Convert::Unicode METHODS ¶

$result = brace_no_arg_command($command_name, $encoding)

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

$possible_conversion = check_unicode_point_conversion($arg, $output_debug)

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

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

$encoding is the encoding the accented characters should be encoded to. If $encoding not set, $result is set to undef. Nested accents and their content are passed with $text and $stack. $text is the text appearing within nested accent commands. $stack is an array reference holding the nested accents texinfo tree elements. In general, $text is the formatted contents and $stack the stack returned by Texinfo::Common::find_innermost_accent_contents. The function tries to convert as much as possible the accents to $encoding starting from the innermost accent.

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

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

$width = string_width($string)

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

$result = unicode_accent($text, $accent_command, $index_in_stack, $accents_stack)

$text is the text appearing within an accent command. $accent_command should be a Texinfo tree element corresponding to an accent command taking an argument. $index_in_stack is the position in the $accents_stack of the accent command being converted. The function returns the Unicode representation of the accented character.

$is_decoded = unicode_point_decoded_in_encoding($encoding, $unicode_point)

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

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

$result = unicode_text($text, $in_code)

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

Next: Texinfo::Convert::Unicode COPYRIGHT AND LICENSE , Previous: Texinfo::Convert::Unicode METHODS , Up: Texinfo::Convert::Unicode [Contents][Index]

15.6 Texinfo::Convert::Unicode AUTHOR ¶

Patrice Dumas, <bug-texinfo@gnu.org>

Previous: Texinfo::Convert::Unicode AUTHOR , Up: Texinfo::Convert::Unicode [Contents][Index]

15.7 Texinfo::Convert::Unicode COPYRIGHT AND LICENSE ¶

Copyright 2010- Free Software Foundation, Inc. See the source file for all copyright years.

This library is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

Next: Texinfo::Convert::NodeNameNormalization SYNOPSIS , Up: Texinfo::Convert::NodeNameNormalization [Contents][Index]

16.1 Texinfo::Convert::NodeNameNormalization NAME ¶

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

Next: Texinfo::Convert::NodeNameNormalization NOTES , Previous: Texinfo::Convert::NodeNameNormalization NAME , Up: Texinfo::Convert::NodeNameNormalization [Contents][Index]

16.2 Texinfo::Convert::NodeNameNormalization SYNOPSIS ¶

 use Texinfo::Convert::NodeNameNormalization qw(convert_to_node_identifier
 normalize_transliterate_texinfo);
 my $normalized = convert_to_node_identifier($node_element->{'contents'}->[0]);
 my $file_name
 = normalize_transliterate_texinfo($section_element->{'contents'}->[0]);

Next: Texinfo::Convert::NodeNameNormalization DESCRIPTION , Previous: Texinfo::Convert::NodeNameNormalization SYNOPSIS , Up: Texinfo::Convert::NodeNameNormalization [Contents][Index]

16.3 Texinfo::Convert::NodeNameNormalization NOTES ¶

The Texinfo Perl module main purpose is to be used in texi2any to convert Texinfo to other formats. There is no promise of API stability.

Next: Texinfo::Convert::NodeNameNormalization METHODS , Previous: Texinfo::Convert::NodeNameNormalization NOTES , Up: Texinfo::Convert::NodeNameNormalization [Contents][Index]

16.4 Texinfo::Convert::NodeNameNormalization DESCRIPTION ¶

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

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

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

Next: Texinfo::Convert::NodeNameNormalization AUTHOR , Previous: Texinfo::Convert::NodeNameNormalization DESCRIPTION , Up: Texinfo::Convert::NodeNameNormalization [Contents][Index]

16.5 Texinfo::Convert::NodeNameNormalization METHODS ¶

$partially_normalized = convert_to_normalized($tree)

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

$normalized = convert_to_node_identifier($tree)

$normalized = convert_to_identifier($tree)

With convert_to_node_identifier, the Texinfo $tree is returned as a string, normalized as described in the Texinfo manual HTML Xref node. convert_to_identifier leaves out the normalization of the name if it is a Top node name.

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

$transliterated = normalize_transliterate_texinfo($tree, $no_unidecode)

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

$transliterated = transliterate_texinfo($tree, $no_unidecode)

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

$file_name = transliterate_protect_file_name($string, $no_unidecode)

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

Next: Texinfo::Convert::NodeNameNormalization COPYRIGHT AND LICENSE , Previous: Texinfo::Convert::NodeNameNormalization METHODS , Up: Texinfo::Convert::NodeNameNormalization [Contents][Index]

16.6 Texinfo::Convert::NodeNameNormalization AUTHOR ¶

Patrice Dumas, <bug-texinfo@gnu.org>

Previous: Texinfo::Convert::NodeNameNormalization AUTHOR , Up: Texinfo::Convert::NodeNameNormalization [Contents][Index]

16.7 Texinfo::Convert::NodeNameNormalization COPYRIGHT AND LICENSE ¶

Copyright 2010- Free Software Foundation, Inc. See the source file for all copyright years.

This library is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

Next: Texinfo::Convert::Text SYNOPSIS , Up: Texinfo::Convert::Text [Contents][Index]

17.1 Texinfo::Convert::Text NAME ¶

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

Next: Texinfo::Convert::Text NOTES , Previous: Texinfo::Convert::Text NAME , Up: Texinfo::Convert::Text [Contents][Index]

17.2 Texinfo::Convert::Text SYNOPSIS ¶

 use Texinfo::Convert::Text qw(convert_to_text text_accents);
 my $result = convert_to_text($tree);
 my $accents_text = text_accents($accents, 'utf-8');
 # using text conversion options set in $converter derived from
 # Texinfo::Convert::Converter
 my $text_options = $converter->{'convert_text_options'};
 set_options_code($text_options);
 my $result_with_converter = convert_to_text($tree, $text_options);
 reset_options_code($text_options);

Next: Texinfo::Convert::Text DESCRIPTION , Previous: Texinfo::Convert::Text SYNOPSIS , Up: Texinfo::Convert::Text [Contents][Index]

17.3 Texinfo::Convert::Text NOTES ¶

The Texinfo Perl module main purpose is to be used in texi2any to convert Texinfo to other formats. There is no promise of API stability.

Next: Texinfo::Convert::Text METHODS , Previous: Texinfo::Convert::Text NOTES , Up: Texinfo::Convert::Text [Contents][Index]

17.4 Texinfo::Convert::Text DESCRIPTION ¶

Texinfo::Convert::Text is a simple backend that converts a Texinfo tree to simple text. It is used in converters, especially for file names.

Converters derived from Texinfo::Convert::Converter should have conversion text options preset associated to the convert_text_options key.

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

Next: Texinfo::Convert::Text AUTHOR , Previous: Texinfo::Convert::Text DESCRIPTION , Up: Texinfo::Convert::Text [Contents][Index]

17.5 Texinfo::Convert::Text METHODS ¶

$result = convert_to_text($tree, $text_options)

Convert a Texinfo tree to simple text. $text_options is a hash reference of options.

The ASCII_GLYPH, DEBUG, DOC_ENCODING_FOR_INPUT_FILE_NAME, COMMAND_LINE_ENCODING, NUMBER_SECTIONS, TEST, documentlanguage, INPUT_FILE_NAME_ENCODING, LOCALE_ENCODING and INCLUDE_DIRECTORIES options corresponding to customization variables may be set in $text_options.

The following options may also be set:

converter

If a converter object is passed to the function, generated error messages are passed back to the converter. See also Texinfo::Convert::Converter.

enabled_encoding

If set, the value is considered to be the encoding name texinfo accented letters should be converted to. In the default case, this option is set from the main program directly or through converters calling conversion to text if the --enable-encoding option, or the ENABLE_ENCODING customization variable is set. For file names in HTML and LaTeX, and for DocBook or Texinfo XML, this variable should in general be set unless the output encoding is US-ASCII.

expanded_formats

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

set_case

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

sort_string

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

$result_accent_text = ascii_accent_fallback($converter, $text, $accent_command, $index_in_stack, $accents_stack, $in_upper_case $converter)

$text is the text appearing within an accent command. $accent_command should be a Texinfo tree element corresponding to an accent command taking an argument. The function returns a transliteration of the accented character. The $converter argument is ignored, but needed for this function to be in argument of functions that need a fallback for accents conversion. The remaining arguments are also ignored and similarly may be needed for this function to be in argument of functions that need a fallback for accents conversion.

set_options_code($text_options)

reset_options_code($text_options)

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

reset_options_code should always be called after set_options_code.

set_options_encoding($text_options, $encoding)

set_options_encoding_if_not_ascii($customization_information, $text_options)

reset_options_encoding($text_options)

set_options_encoding sets enabled_encoding in $text_options to $encoding. set_options_encoding_if_not_ascii sets enabled_encoding in $text_options based on customization options associated to $customization_information. In that case, enabled_encoding is set unless the output encoding is US-ASCII even if ENABLE_ENCODING is not set.

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

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

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

Next: Texinfo::Convert::Text COPYRIGHT AND LICENSE , Previous: Texinfo::Convert::Text METHODS , Up: Texinfo::Convert::Text [Contents][Index]

17.6 Texinfo::Convert::Text AUTHOR ¶

Patrice Dumas, <bug-texinfo@gnu.org>

Previous: Texinfo::Convert::Text AUTHOR , Up: Texinfo::Convert::Text [Contents][Index]

17.7 Texinfo::Convert::Text COPYRIGHT AND LICENSE ¶

Copyright 2010- Free Software Foundation, Inc. See the source file for all copyright years.

This library is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

Next: Texinfo::Convert::Converter SYNOPSIS , Up: Texinfo::Convert::Converter [Contents][Index]

18.1 Texinfo::Convert::Converter NAME ¶

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

Next: Texinfo::Convert::Converter NOTES , Previous: Texinfo::Convert::Converter NAME , Up: Texinfo::Convert::Converter [Contents][Index]

18.2 Texinfo::Convert::Converter SYNOPSIS ¶

 package Texinfo::Convert::MyConverter;
 use Texinfo::Convert::Converter;
 @ISA = qw(Texinfo::Convert::Converter);
 sub converter_defaults ($;$) {
 return \%myconverter_defaults;
 }
 sub converter_initialize($) {
 my $self = shift;
 ...
 }
 sub conversion_initialization($;$) {
 my $self = shift;
 my $document = shift;
 if ($document) {
 $self->set_document($document);
 }
 $self->set_global_document_commands('before', \@global_commands);
 ...
 $self->{'document_context'} = [{}];
 ...
 }
 sub conversion_finalization($) {
 my $self = shift;
 }
 sub convert_tree($$) {
 ...
 }
 sub convert($$) {
 my $self = shift;
 my $document = shift;
 $self->conversion_initialization($document);
 ...
 $self->conversion_finalization();
 }
 sub output($$) {
 my $self = shift;
 my $document = shift;
 $self->conversion_initialization($document);
 ...
 $self->conversion_finalization();
 ...
 }
 # if some data needs to be released explicitly
 sub converter_destroy($) {
 my $self = shift;
 ...
 }
 # end of Texinfo::Convert::MyConverter
 my $converter = Texinfo::Convert::MyConverter->converter();
 $converter->output($texinfo_parsed_document);

Next: Texinfo::Convert::Converter DESCRIPTION , Previous: Texinfo::Convert::Converter SYNOPSIS , Up: Texinfo::Convert::Converter [Contents][Index]

18.3 Texinfo::Convert::Converter NOTES ¶

The Texinfo Perl module main purpose is to be used in texi2any to convert Texinfo to other formats. There is no promise of API stability.

Next: Texinfo::Convert::Converter METHODS , Previous: Texinfo::Convert::Converter NOTES , Up: Texinfo::Convert::Converter [Contents][Index]

18.4 Texinfo::Convert::Converter DESCRIPTION ¶

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

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

The convert_tree method is mandatory and should convert portions of Texinfo tree. Takes a $converter and Texinfo tree $tree in arguments. Returns the converted output.

This method should not perform converter initialization, as it should only be called with converter setup for immediate conversion, in general when conversion is already ongoing.

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

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

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

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

 sub output($$) {
 my $self = shift;
 my $document = shift;
 return $self->output_tree($document);
 }

In general, output and output_tree output to files and return undef. When the output file name is an empty string, however, it is customary for output and output_tree to return the output as a character string instead. The output file name is obtained in output_tree through a call to determine_files_and_directory. In general determine_files_and_directory is also used when output_tree is not used.

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

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

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

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

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

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

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

Next: Texinfo::Convert::Converter SEE ALSO , Previous: Texinfo::Convert::Converter DESCRIPTION , Up: Texinfo::Convert::Converter [Contents][Index]

18.5 Texinfo::Convert::Converter METHODS ¶

• Converter Initialization
• Conversion
• Output units and converter destruction
• Getting and setting customization variables
• Registering error and warning messages
• Translations in output documents
• Index sorting
• Accents conversion
• Conversion to XML
• Helper methods