Texinfo modules documentation ¶

1.1 Texinfo::Commands NAME ¶

Texinfo::Commands - Classification of commands

1.2 Texinfo::Commands SYNOPSIS ¶

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

1.3 Texinfo::Commands NOTES ¶

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

1.4 Texinfo::Commands DESCRIPTION ¶

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

1.5 @-COMMAND INFORMATION ¶

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

%index_names

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

1.6 @-COMMAND CLASSES ¶

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

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

%accent_commands

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

%block_commands

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

conditional

@if* commands;

def

Definition commands like @deffn;

float

@float;

format_raw

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

item_container

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

item_line

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

menu

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

math

Math block commands, like @displaymath.

multitable

@multitable;

other

The remaining block commands.

preformatted

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

quotation

Commands like @quotation.

raw

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

region

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

%blockitem_commands

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

%brace_code_commands

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

%brace_commands

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

%close_paragraph_commands

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

%commands_args_number

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

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

%contain_basic_inline_commands

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

%contain_plain_text_commands

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

%def_commands

Definition commands.

%default_index_commands

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

%explained_commands

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

%formattable_line_commands

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

%formatted_nobrace_commands

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

%formatted_line_commands

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

%heading_spec_commands

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

%in_heading_spec_commands

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

%in_index_commands

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

%inline_conditional_commands

%inline_format_commands

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

%letter_no_arg_commands

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

%math_commands

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

%line_commands

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

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

%no_paragraph_commands

Commands that do not start a paragraph.

%nobrace_commands

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

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

%non_formatted_block_commands

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

%non_formatted_brace_commands

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

%preamble_commands

@-commands that do not stop the preamble.

%preformatted_commands

%preformatted_code_commands

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

%ref_commands

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

%root_commands

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

%sectioning_heading_commands

All the sectioning and heading commands.

%variadic_commands

Commands with unlimited arguments, like @example.

1.7 Texinfo::Commands SEE ALSO ¶

Texinfo::Parser.

1.8 Texinfo::Commands AUTHOR ¶

Patrice Dumas, <pertusus@free.fr>

1.9 Texinfo::Commands COPYRIGHT AND LICENSE ¶

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

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

2.1 Texinfo::Common NAME ¶

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

2.2 Texinfo::Common SYNOPSIS ¶

  use Texinfo::Common;


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

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

2.3 Texinfo::Common NOTES ¶

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

2.4 Texinfo::Common DESCRIPTION ¶

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

2.5 MISC INFORMATION ¶

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

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

$value = get_build_constant($name)

The following build constants are available:

PACKAGE

PACKAGE_CONFIG

PACKAGE_AND_VERSION

PACKAGE_AND_VERSION_CONFIG

PACKAGE_NAME

PACKAGE_NAME_CONFIG

PACKAGE_VERSION

PACKAGE_VERSION_CONFIG

PACKAGE_URL

PACKAGE_URL_CONFIG

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

%texinfo_output_formats

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

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

2.6 @-COMMAND INFORMATION ¶

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

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

%all_commands

All the @-commands.

%def_aliases

%def_no_var_arg_commands

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

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

%nobrace_symbol_text

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

%small_block_associated_command

Associate small command like smallexample to the regular command example.

2.7 Texinfo::Common METHODS ¶

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

The Texinfo tree and Texinfo tree elements used in argument of some functions are documented in 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 = element_associated_processing_encoding($element)

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

$result = element_is_inline($element, $check_current)

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

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

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

$text = enumerate_item_representation($specification, $number)

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

  enumerate_item_representation('c', 3)

is e.

$command = find_parent_root_command($object, $tree_element)

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

$entry_content_element = index_content_element($element, $prefer_reference_element)

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

$result = is_content_empty($tree, $do_not_ignore_index_entries)

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

$file = locate_include_file($customization_information, $file_path)

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

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

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

The $index_entry hash is described in 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 = remove_from_array($array, $element)

Remove first occurence of $element in the array reference $array. Return the removed element, or undef if not found.

$level = section_level($section)

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

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

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

last

Set to the last value for the command.

preamble

Set sequentially to the values in the Texinfo preamble.

preamble_or_first

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

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

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

$status = set_informative_command_value($customization_information, $element)

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

set_output_encoding($customization_information, $document)

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

set_output_perl_encoding($customization_information)

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

$split_contents = split_custom_heading_command_contents($element)

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

$status = valid_customization_option($name)

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

$status = valid_tree_transformation($name)

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

2.8 Texinfo::Common SEE ALSO ¶

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

2.9 Texinfo::Common AUTHOR ¶

Patrice Dumas, <pertusus@free.fr>

2.10 Texinfo::Common COPYRIGHT AND LICENSE ¶

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

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

3.1 Texinfo::Parser NAME ¶

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

3.2 Texinfo::Parser SYNOPSIS ¶

  use Texinfo::Parser;

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

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

3.3 Texinfo::Parser NOTES ¶

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

3.4 Texinfo::Parser DESCRIPTION ¶

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

3.5 Texinfo::Parser METHODS ¶

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

• Initialization
• Parsing Texinfo text

3.6 TEXINFO TREE ¶

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

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

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

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

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

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

  makeinfo -c TEXINFO_OUTPUT_FORMAT=debugtree document.texi

• Element keys
• Element types
• Information available in the info key
• Information available in the extra key

3.7 Texinfo::Parser SEE ALSO ¶

Texinfo manual.

3.8 Texinfo::Parser AUTHOR ¶

Patrice Dumas, <pertusus@free.fr>

3.9 Texinfo::Parser COPYRIGHT AND LICENSE ¶

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

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

4.1 Texinfo::Document NAME ¶

Texinfo::Document - Texinfo document tree and information

4.2 Texinfo::Document SYNOPSIS ¶

  use Texinfo::Parser;

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

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

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

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

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

4.3 Texinfo::Document NOTES ¶

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

4.4 Texinfo::Document DESCRIPTION ¶

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

4.5 Texinfo::Document METHODS ¶

• Getting document information
• Merging and sorting indices
• Getting errors and error registering object
• Getting customization options values registered in document
• Registering document and information in document
• Methods for Perl and C code interactions

4.6 Texinfo::Document SEE ALSO ¶

Texinfo::Parser. Texinfo::Structuring.

4.7 Texinfo::Document AUTHOR ¶

Patrice Dumas, <pertusus@free.fr>

4.8 Texinfo::Document COPYRIGHT AND LICENSE ¶

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

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

5.1 Texinfo::ManipulateTree NAME ¶

Texinfo::ManipulateTree - Texinfo modules common tree manipulation functions

5.2 Texinfo::ManipulateTree SYNOPSIS ¶

  use Texinfo::ManipulateTree;

5.3 Texinfo::ManipulateTree NOTES ¶

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

5.4 Texinfo::ManipulateTree DESCRIPTION ¶

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

For optional tree transformation, see Texinfo::Transformations.

5.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_tree($tree)

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

protect_colon_in_tree($tree)

protect_node_after_label_in_tree($tree)

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

protect_comma_in_tree($tree)

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

protect_first_parenthesis($element)

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

relate_index_entries_to_table_items_in_tree($document)

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

5.6 Texinfo::ManipulateTree SEE ALSO ¶

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

5.7 Texinfo::ManipulateTree AUTHOR ¶

Patrice Dumas, <pertusus@free.fr>

5.8 Texinfo::ManipulateTree COPYRIGHT AND LICENSE ¶

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

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

6.1 Texinfo::Structuring NAME ¶

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

6.2 Texinfo::Structuring SYNOPSIS ¶

  use Texinfo::Structuring qw(sectioning_structure nodes_tree number_floats
    associate_internal_references);

  # $document is a parsed Texinfo::Document document.
  # When customization variables information is needed, it is obtained
  # from the $document by calling the get_conf() method.
  my $sections_list = sectioning_structure($document);
  my $nodes_list = nodes_tree($document);
  set_menus_node_directions($document);
  complete_node_tree_with_menus($document);
  check_nodes_are_referenced($document);
  associate_internal_references($document);
  number_floats($document->floats_information());

6.3 Texinfo::Structuring NOTES ¶

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

6.4 Texinfo::Structuring DESCRIPTION ¶

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

6.5 Texinfo::Structuring METHODS ¶

No method is exported in the default case.

Most methods use the Texinfo::Report registrar from a parsed document for error reporting. Most also require Texinfo customization variables information, which means an object implementing the get_conf method, in general a parsed document with registered customization, or, sometime, a converter (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 the autogenerated menus available.

complete_node_tree_with_menus($document)

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

@children_nodes = get_node_node_childs_from_sectioning($node)

$node is a node tree element. Find the node $node children based on the sectioning structure. For the node associated with @top sectioning command, the sections associated with parts are considered.

new_block_command($element, $command_name)

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

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

Returns a @menu Texinfo tree element for node $node, pointing to the children of the node obtained with the sectioning structure. If $use_sections is set, use section names for the menu entry names. $customization_information, if defined, should hold information needed for translations. Translations are only needed when generating the top node menu.

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

Returns a detailmenu tree element formatted as a master node. $menus is an array reference containing the regular menus of the Top node. $customization_information should hold information needed for translations and error reporting.

The $registrar argument can be set to a Texinfo::Report object. If the $registrar argument is not set, $customization_information is assumed to be a converter, and error reporting uses converters error messages reporting functions (Registering error and warning messages).

$entry = new_node_menu_entry($node, $use_sections)

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

$nodes_list = nodes_tree($document)

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

This functions sets, in the extra node element hash:

node_directions

Hash reference with up, next and prev keys associated to elements corresponding to node line directions.

number_floats($float_information)

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

$command_name = section_level_adjusted_command_name($element)

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

$sections_list = sectioning_structure($document)

This function goes through the parsed document tree and gather information on the document structure for sectioning commands. It returns a reference on the sections elements list.

It sets section elements extra hash values:

section_level

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

section_number

The sectioning element number.

section_childs

An array holding sectioning elements children of the element.

section_directions

Hash reference with up, next and prev keys associated to elements corresponding to sectioning structure directions.

toplevel_directions

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

An element is created and used as the root of the sectioning commands tree. This element is associated to the extra sectioning_root key of the first section element of the sections list. It is also at the top of the tree when following the up section_directions.

set_menus_node_directions($document);

Goes through menu and set directions.

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

menu_directions

Hash reference with up, next and prev keys associated to elements corresponding to menu directions.

warn_non_empty_parts($document)

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

6.6 Texinfo::Structuring SEE ALSO ¶

Texinfo manual, Texinfo::Document.

6.7 Texinfo::Structuring AUTHOR ¶

Patrice Dumas, <pertusus@free.fr>

6.8 Texinfo::Structuring COPYRIGHT AND LICENSE ¶

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

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

7.1 Texinfo::Report NAME ¶

Texinfo::Report - Error storing for Texinfo modules

7.2 Texinfo::Report SYNOPSIS ¶

  use Texinfo::Report;

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

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

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

  $registrar->clear();

7.3 Texinfo::Report NOTES ¶

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

7.4 Texinfo::Report DESCRIPTION ¶

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

7.5 Texinfo::Report METHODS ¶

No method is exported in the default case.

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

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

Return an initialized Texinfo::Report object.

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

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

continuation

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

error_line

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

file_name

The file name where the error or warning occurs.

line_nr

The line number of the error or warning.

macro

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

text

The text of the error.

type

May be warning, or error.

$registrar->clear ()

Clear the previously registered messages.

$registrar->add_formatted_message ($msg)

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

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

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

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

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

The $debug optional integer arguments sets the debug level.

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

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

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

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

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

7.6 Texinfo::Report AUTHOR ¶

Patrice Dumas, <pertusus@free.fr>

7.7 Texinfo::Report COPYRIGHT AND LICENSE ¶

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

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

8.1 Texinfo::Translations NAME ¶

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

8.2 Texinfo::Translations SYNOPSIS ¶

  @ISA = qw(Texinfo::Translations);

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

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

8.3 Texinfo::Translations NOTES ¶

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

8.4 Texinfo::Translations DESCRIPTION ¶

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

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

8.5 Texinfo::Translations METHODS ¶

No method is exported.

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

configure($localesdir, $strings_textdomain)

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

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

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

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

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

$lang is the language used for the translation.

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

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

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

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

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

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

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

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

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

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

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

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

8.6 Texinfo::Translations SEE ALSO ¶

GNU gettext utilities manual.

8.7 Texinfo::Translations AUTHOR ¶

Patrice Dumas, <pertusus@free.fr>

8.8 Texinfo::Translations COPYRIGHT AND LICENSE ¶

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

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

9.1 Texinfo::Transformations NAME ¶

Texinfo::Transformations - transformations of Texinfo tree

9.2 Texinfo::Transformations NOTES ¶

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

9.3 Texinfo::Transformations DESCRIPTION ¶

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

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

9.4 Texinfo::Transformations METHODS ¶

No method is exported in the default case.

complete_tree_nodes_menus($tree, $add_section_names_in_entries)

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

complete_tree_nodes_missing_menu($document, $use_section_names_in_entries)

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

fill_gaps_in_sectioning($tree, $commands_heading_tree)

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

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

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

insert_nodes_for_sectioning_commands($document)

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

menu_to_simple_menu($menu)

set_menus_to_simple_menu($nodes_list)

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

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

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

protect_hashchar_at_line_beginning($tree, $registrar, $customization_information)

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

$modified_tree = reference_to_arg_in_tree($tree, $document)

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

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

regenerate_master_menu($document, $use_sections)

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

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

9.5 Texinfo::Transformations SEE ALSO ¶

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

9.6 Texinfo::Transformations AUTHOR ¶

Patrice Dumas, <pertusus@free.fr>

9.7 Texinfo::Transformations COPYRIGHT AND LICENSE ¶

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

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

10.1 Texinfo::Indices NAME ¶

Texinfo::Indices - merging and sorting indices from Texinfo

10.2 Texinfo::Indices SYNOPSIS ¶

  use Texinfo::Indices;

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

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

10.3 Texinfo::Indices NOTES ¶

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

10.4 Texinfo::Indices DESCRIPTION ¶

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

Note that, in general, the functions used to merge or sort indices should not be called directly, corresponding functions in 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.

10.5 Texinfo::Indices METHODS ¶

No method is exported.

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

Return a string suitable as a sort string, for index entries. $document_info is used by C code to retrieve the document data, using the document_descriptor key. $document_info can be a converter based on 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, $registrar, $customization_information, $use_unicode_collation, $locale_lang)

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

sort_indices_by_letter sorts by index and letter, while sort_indices_by_index sort all entries of an index together. Indices are obtained from $document, and should have been merged previously, in general by using 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 $registrar argument can be set to a Texinfo::Report object. Error reporting also requires Texinfo customization variables information, which means an object implementing the get_conf method, a converter (Getting and setting customization variables) or a document Getting customization options values registered in document) as $customization_information argument. If the $registrar argument is not set, the object used to get customization information is assumed to be a converter, and the error reporting uses converters error messages reporting functions (Registering error and warning messages).

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.

10.6 Texinfo::Indices SEE ALSO ¶

Texinfo manual, Texinfo::Document.

10.7 Texinfo::Indices AUTHOR ¶

Patrice Dumas, <pertusus@free.fr>

10.8 Texinfo::Indices COPYRIGHT AND LICENSE ¶

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

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

11.1 Texinfo::OutputUnits NAME ¶

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

11.2 Texinfo::OutputUnits SYNOPSIS ¶

  use Texinfo::OutputUnits qw(split_by_node split_by_section split_pages
    units_directions units_file_directions);

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

11.3 Texinfo::OutputUnits NOTES ¶

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

11.4 Texinfo::OutputUnits DESCRIPTION ¶

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

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

Output units are used for conversion to HTML and Info output formats. See 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.

11.5 Texinfo::OutputUnits METHODS ¶

No method is exported in the default case.

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

11.6 Texinfo::OutputUnits SEE ALSO ¶

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

11.7 Texinfo::OutputUnits AUTHOR ¶

Patrice Dumas, <pertusus@free.fr>

11.8 Texinfo::OutputUnits COPYRIGHT AND LICENSE ¶

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

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

12.1 Texinfo::Convert::Texinfo NAME ¶

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

12.2 Texinfo::Convert::Texinfo SYNOPSIS ¶

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

  my $texinfo_text = convert_to_texinfo($tree);

12.3 Texinfo::Convert::Texinfo NOTES ¶

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

12.4 Texinfo::Convert::Texinfo DESCRIPTION ¶

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

12.5 Texinfo::Convert::Texinfo METHODS ¶

$texinfo_text = convert_to_texinfo($tree)

Converts the Texinfo tree $tree to Texinfo code.

12.6 Texinfo::Convert::Texinfo AUTHOR ¶

Patrice Dumas, <pertusus@free.fr>

12.7 Texinfo::Convert::Texinfo COPYRIGHT AND LICENSE ¶

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

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

13.1 Texinfo::Convert::Utils NAME ¶

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

13.2 Texinfo::Convert::Utils SYNOPSIS ¶

  use Texinfo::Convert::Utils;

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

13.3 Texinfo::Convert::Utils NOTES ¶

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

13.4 Texinfo::Convert::Utils DESCRIPTION ¶

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

13.5 Texinfo::Convert::Utils METHODS ¶

No method is exported in the default case.

Most methods takes a $converter as argument, in some cases optionally, to get some information, see Getting and setting customization variables and use methods for error reporting, see Texinfo::Convert::Converter and Texinfo::Report, and for strings translations, see Texinfo::Translations.

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 which require a converter.

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

The $converter argument may be undef. $heading_element is a heading command tree element. $heading_text is the already formatted heading text. if the $do_number optional argument is defined and false, no number is used and the text is returned as is. This function returns the heading with a number and the appendix part if needed. If $converter is not defined, the resulting string won’t be translated.

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

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

$tree = definition_category_tree($converter, $def_line)

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

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

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

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

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

$tree = expand_today($converter)

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

$tree = expand_verbatiminclude($converter, $verbatiminclude)

The $converter argument is required and is used to output error messages and retrieve customization information Getting and setting customization variables. $verbatiminclude is a @verbatiminclude tree element. This function returns a @verbatim tree elements after finding the included file and reading it.

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

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

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

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

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

13.6 Texinfo::Convert::Utils SEE ALSO ¶

Texinfo::Convert::Converter and Texinfo::Translations.

13.7 Texinfo::Convert::Utils AUTHOR ¶

Patrice Dumas, <pertusus@free.fr>

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

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

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

14.1 Texinfo::Convert::Unicode NAME ¶

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

14.2 Texinfo::Convert::Unicode SYNOPSIS ¶

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

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

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

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

14.3 Texinfo::Convert::Unicode NOTES ¶

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

14.4 Texinfo::Convert::Unicode DESCRIPTION ¶

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

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

14.5 Texinfo::Convert::Unicode METHODS ¶

$result = brace_no_arg_command($command_name, $encoding)

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

$possible_conversion = check_unicode_point_conversion($arg, $output_debug)

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

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

$encoding is the encoding the accented characters should be encoded to. If $encoding not set, $result is set to undef. Nested accents and their content are passed with $text and $stack. $text is the text appearing within nested accent commands. $stack is an array reference holding the nested accents texinfo tree elements. In general, $text is the formatted contents and $stack the stack returned by Texinfo::Convert::Utils::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)

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

$is_decoded = unicode_point_decoded_in_encoding($encoding, $unicode_point)

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

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

$result = unicode_text($text, $in_code)

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

14.6 Texinfo::Convert::Unicode AUTHOR ¶

Patrice Dumas, <pertusus@free.fr>

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

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

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

15.1 Texinfo::Convert::NodeNameNormalization NAME ¶

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

15.2 Texinfo::Convert::NodeNameNormalization SYNOPSIS ¶

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

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

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

15.3 Texinfo::Convert::NodeNameNormalization NOTES ¶

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

15.4 Texinfo::Convert::NodeNameNormalization DESCRIPTION ¶

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

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

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

15.5 Texinfo::Convert::NodeNameNormalization METHODS ¶

$partially_normalized = convert_to_normalized($tree)

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

$normalized = convert_to_identifier($tree)

The Texinfo $tree is returned as a string, normalized as described in the Texinfo manual HTML Xref node.

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

$transliterated = normalize_transliterate_texinfo($tree, $no_unidecode)

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

$transliterated = transliterate_texinfo($tree, $no_unidecode)

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

$file_name = transliterate_protect_file_name($string, $no_unidecode)

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

15.6 Texinfo::Convert::NodeNameNormalization AUTHOR ¶

Patrice Dumas, <pertusus@free.fr>

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

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

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

16.1 Texinfo::Convert::Text NAME ¶

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

16.2 Texinfo::Convert::Text SYNOPSIS ¶

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

  my $result = convert_to_text($tree);

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

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

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

16.3 Texinfo::Convert::Text NOTES ¶

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

16.4 Texinfo::Convert::Text DESCRIPTION ¶

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

Converters derived from 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.

16.5 Texinfo::Convert::Text METHODS ¶

$result = convert_to_text($tree, $text_options)

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

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

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

enabled_encoding

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

set_case

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

sort_string

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

converter

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

expanded_formats

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

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

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

set_options_code($text_options)

reset_options_code($text_options)

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

reset_options_code should always be called after set_options_code.

set_options_encoding($text_options, $encoding)

set_options_encoding_if_not_ascii($customization_information, $text_options)

reset_options_encoding($text_options)

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

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

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

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

16.6 Texinfo::Convert::Text AUTHOR ¶

Patrice Dumas, <pertusus@free.fr>

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

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

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

17.1 Texinfo::Convert::Converter NAME ¶

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

17.2 Texinfo::Convert::Converter SYNOPSIS ¶

  package Texinfo::Convert::MyConverter;

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

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

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

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

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

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

  sub convert_tree($$) {
    ...
  }

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

    $self->conversion_initialization($document);

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

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

    $self->conversion_initialization($document);

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

  # end of Texinfo::Convert::MyConverter

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

17.3 Texinfo::Convert::Converter NOTES ¶

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

17.4 Texinfo::Convert::Converter DESCRIPTION ¶

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

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

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

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

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

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

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

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

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

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

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

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

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

Can be used for the conversion of output units by converters. convert_output_unit takes a $converter and an output unit $output_unit as argument. The implementation of convert_output_unit of Texinfo::Convert::Converter could be suitable in many cases. Output units are typically returned by Texinfo::OutputUnits split_by_section or Texinfo::OutputUnits split_by_node.

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.

17.5 Texinfo::Convert::Converter METHODS ¶

• Converter Initialization
• Conversion
• Getting and setting customization variables
• Registering error and warning messages
• Translations in output documents
• Index sorting
• Conversion to XML
• Helper methods

17.6 Texinfo::Convert::Converter SEE ALSO ¶

Texinfo::Common, Texinfo::Convert::Unicode, Texinfo::Report, Texinfo::Translations, Texinfo::Convert::Utils and Texinfo::Parser.

17.7 Texinfo::Convert::Converter AUTHOR ¶

Patrice Dumas, <pertusus@free.fr>

17.8 Texinfo::Convert::Converter COPYRIGHT AND LICENSE ¶

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

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

18.1 Texinfo::Convert::Info NAME ¶

Texinfo::Convert::Info - Convert Texinfo tree to Info

18.2 Texinfo::Convert::Info SYNOPSIS ¶

  my $converter
    = Texinfo::Convert::Info->converter({'NUMBER_SECTIONS' => 0});

  $converter->output($document);
  $converter->convert($document);
  $converter->convert_tree($tree);

18.3 Texinfo::Convert::Info NOTES ¶

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

18.4 Texinfo::Convert::Info DESCRIPTION ¶

Texinfo::Convert::Info converts a Texinfo tree to Info.

18.5 Texinfo::Convert::Info METHODS ¶

$converter = Texinfo::Convert::Info->converter($options)

Initialize converter from Texinfo to Info.

The $options hash reference holds Texinfo customization options for the converter. These options should be Texinfo customization options that can be passed to the converter. Most of the customization options are described in the Texinfo manual or in the customization API manual. Those customization options, when appropriate, override the document content.

See Texinfo::Convert::Converter for more information.

$converter->output($document)

Convert a Texinfo parsed document $document and output the result in files as described in the Texinfo manual.

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

Convert a Texinfo parsed document $document and return the resulting output.

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

Convert a Texinfo tree portion $tree and return the resulting output. This function does not try to output a full document but only portions. For a full document use convert.

In general, this function should be called after the converter has been associated to a document by a call to output or convert.

18.6 Texinfo::Convert::Info AUTHOR ¶

Patrice Dumas, <pertusus@free.fr>

18.7 Texinfo::Convert::Info COPYRIGHT AND LICENSE ¶

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

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

19.1 Texinfo::Convert::HTML NAME ¶

Texinfo::Convert::HTML - Convert Texinfo tree to HTML

19.2 Texinfo::Convert::HTML SYNOPSIS ¶

  my $converter
    = Texinfo::Convert::HTML->converter({'NUMBER_SECTIONS' => 0});

  $converter->output($document);
  $converter->convert($document);
  $converter->convert_tree($tree);
  $converter->output_internal_links(); # HTML only

19.3 Texinfo::Convert::HTML NOTES ¶

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

19.4 Texinfo::Convert::HTML DESCRIPTION ¶

Texinfo::Convert::HTML converts a Texinfo tree to HTML.

19.5 Texinfo::Convert::HTML METHODS ¶

$converter = Texinfo::Convert::HTML->converter($options)

Initialize converter from Texinfo to HTML.

The $options hash reference holds Texinfo customization options for the converter. These options should be Texinfo customization options that can be passed to the converter. Most of the customization options are described in the Texinfo manual or in the customization API manual. Those customization options, when appropriate, override the document content.

See Texinfo::Convert::Converter for more information.

$converter->output($document)

Convert a Texinfo parsed document $document and output the result in files as described in the Texinfo manual.

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

Convert a Texinfo parsed document $document and return the resulting output.

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

Convert a Texinfo tree portion $tree and return the resulting output. This function does not try to output a full document but only portions. For a full document use convert.

In general, this function should be called after the converter has been associated to a document by a call to output or convert.

$result = $converter->output_internal_links()

Returns text representing the links in the document. The format should follow the --internal-links option of the texi2any specification. This is only supported in (and relevant for) HTML.

19.6 Texinfo::Convert::HTML AUTHOR ¶

Patrice Dumas, <pertusus@free.fr>

19.7 Texinfo::Convert::HTML COPYRIGHT AND LICENSE ¶

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

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

20.1 Texinfo::Convert::DocBook NAME ¶

Texinfo::Convert::DocBook - Convert Texinfo tree to DocBook

20.2 Texinfo::Convert::DocBook SYNOPSIS ¶

  my $converter
    = Texinfo::Convert::DocBook->converter({'NUMBER_SECTIONS' => 0});

  $converter->output($document);
  $converter->convert($document);
  $converter->convert_tree($tree);

20.3 Texinfo::Convert::DocBook NOTES ¶

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

20.4 Texinfo::Convert::DocBook DESCRIPTION ¶

Texinfo::Convert::DocBook converts a Texinfo tree to DocBook.

20.5 Texinfo::Convert::DocBook METHODS ¶

$converter = Texinfo::Convert::DocBook->converter($options)

Initialize converter from Texinfo to DocBook.

The $options hash reference holds Texinfo customization options for the converter. These options should be Texinfo customization options that can be passed to the converter. Most of the customization options are described in the Texinfo manual or in the customization API manual. Those customization options, when appropriate, override the document content.

See Texinfo::Convert::Converter for more information.

$converter->output($document)

Convert a Texinfo parsed document $document and output the result in files as described in the Texinfo manual.

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

Convert a Texinfo parsed document $document and return the resulting output.

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

Convert a Texinfo tree portion $tree and return the resulting output. This function does not try to output a full document but only portions. For a full document use convert.

In general, this function should be called after the converter has been associated to a document by a call to output or convert.

20.6 Texinfo::Convert::DocBook AUTHOR ¶

Patrice Dumas, <pertusus@free.fr>

20.7 Texinfo::Convert::DocBook COPYRIGHT AND LICENSE ¶

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

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

21.1 Texinfo::Convert::TexinfoMarkup NAME ¶

Texinfo::Convert::TexinfoMarkup - Convert Texinfo tree to element and attribute markup

21.2 Texinfo::Convert::TexinfoMarkup SYNOPSIS ¶

  package Texinfo::Convert::TexinfoMyMarkup;

  use Texinfo::Convert::TexinfoMarkup;

  @ISA = qw(Texinfo::Convert::TexinfoMarkup);

  sub converter_defaults ($$) {
    return %myconverter_defaults;
  }

  sub txi_markup_protect_text($$)
  {
    my $self = shift;
    ....
  }

21.3 Texinfo::Convert::TexinfoMarkup NOTES ¶

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

21.4 Texinfo::Convert::TexinfoMarkup DESCRIPTION ¶

Texinfo::Convert::TexinfoMarkup converts a Texinfo tree to the Texinfo Markup Language which is based on nested elements with attributes, similar to XML. All the information present in the Texinfo tree, after expansion of @macro, @value and inclusion of include files is kept. Texinfo::Convert::TexinfoMarkup is an abstract class, to be used as a super class for modules implementing specific markup formatting functions called by Texinfo::Convert::TexinfoMarkup.

The Texinfo Markup Language elements and attributes are not documented, but the Texinfo XML output by the Texinfo::Convert::TexinfoXML subclass (Texinfo::Convert::TexinfoXML) is a straightforward formatting as XML, and is described by the Texinfo DTD. Therefore the Texinfo DTD can be used as a description of the structure of both Texinfo XML and of the more abstract Texinfo Markup Language.

21.5 Texinfo::Convert::TexinfoMarkup METHODS ¶

• Markup formatting methods defined by subclasses
• Formatting state information

21.6 Texinfo::Convert::TexinfoMarkup AUTHOR ¶

Patrice Dumas, <pertusus@free.fr>

21.7 Texinfo::Convert::TexinfoMarkup SEE ALSO ¶

Texinfo::Convert::Converter. Texinfo::Convert::TexinfoXML. The Texinfo::Convert::TexinfoSXML is another subclass, which outputs SXML. It is not much documented.

21.8 Texinfo::Convert::TexinfoMarkup COPYRIGHT AND LICENSE ¶

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

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

22.1 Texinfo::Convert::TexinfoXML NAME ¶

Texinfo::Convert::TexinfoXML - Convert Texinfo tree to TexinfoXML

22.2 Texinfo::Convert::TexinfoXML SYNOPSIS ¶

  my $converter
    = Texinfo::Convert::TexinfoXML->converter({'NUMBER_SECTIONS' => 0});

  $converter->output($document);
  $converter->convert($document);
  $converter->convert_tree($tree);

22.3 Texinfo::Convert::TexinfoXML NOTES ¶

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

22.4 Texinfo::Convert::TexinfoXML DESCRIPTION ¶

Texinfo::Convert::TexinfoXML converts a Texinfo tree to TexinfoXML.

22.5 Texinfo::Convert::TexinfoXML METHODS ¶

$converter = Texinfo::Convert::TexinfoXML->converter($options)

Initialize converter from Texinfo to TexinfoXML.

The $options hash reference holds Texinfo customization options for the converter. These options should be Texinfo customization options that can be passed to the converter. Most of the customization options are described in the Texinfo manual or in the customization API manual. Those customization options, when appropriate, override the document content.

See Texinfo::Convert::Converter for more information.

$converter->output($document)

Convert a Texinfo parsed document $document and output the result in files as described in the Texinfo manual.

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

Convert a Texinfo parsed document $document and return the resulting output.

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

Convert a Texinfo tree portion $tree and return the resulting output. This function does not try to output a full document but only portions. For a full document use convert.

In general, this function should be called after the converter has been associated to a document by a call to output or convert.

22.6 Texinfo::Convert::TexinfoXML AUTHOR ¶

Patrice Dumas, <pertusus@free.fr>

22.7 Texinfo::Convert::TexinfoXML COPYRIGHT AND LICENSE ¶

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

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

23.1 Texinfo::Convert::Plaintext NAME ¶

Texinfo::Convert::Plaintext - Convert Texinfo tree to Plaintext

23.2 Texinfo::Convert::Plaintext SYNOPSIS ¶

  my $converter
    = Texinfo::Convert::Plaintext->converter({'NUMBER_SECTIONS' => 0});

  $converter->output($document);
  $converter->convert($document);
  $converter->convert_tree($tree);

23.3 Texinfo::Convert::Plaintext NOTES ¶

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

23.4 Texinfo::Convert::Plaintext DESCRIPTION ¶

Texinfo::Convert::Plaintext converts a Texinfo tree to Plaintext.

23.5 Texinfo::Convert::Plaintext METHODS ¶

$converter = Texinfo::Convert::Plaintext->converter($options)

Initialize converter from Texinfo to Plaintext.

The $options hash reference holds Texinfo customization options for the converter. These options should be Texinfo customization options that can be passed to the converter. Most of the customization options are described in the Texinfo manual or in the customization API manual. Those customization options, when appropriate, override the document content.

See Texinfo::Convert::Converter for more information.

$converter->output($document)

Convert a Texinfo parsed document $document and output the result in files as described in the Texinfo manual.

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

Convert a Texinfo parsed document $document and return the resulting output.

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

Convert a Texinfo tree portion $tree and return the resulting output. This function does not try to output a full document but only portions. For a full document use convert.

In general, this function should be called after the converter has been associated to a document by a call to output or convert.

23.6 Texinfo::Convert::Plaintext AUTHOR ¶

Patrice Dumas, <pertusus@free.fr>

23.7 Texinfo::Convert::Plaintext COPYRIGHT AND LICENSE ¶

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

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