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::Parser indices_information.

1.6 @-COMMAND CLASSES

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

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

%accent_commands

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

%block_commands

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

conditional

@if* commands;

def

Definition commands like @deffn;

float

@float;

format_raw

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

item_container

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

item_line

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

menu

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

math

Math block commands, like @displaymath.

multitable

@multitable;

other

The remaining block commands.

preformatted

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

quotation

Commands like @quotation.

raw

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

region

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

%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 or @abbr, 5 for @image of @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).

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

%def_commands

Definition commands.

%default_index_commands

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

%heading_spec_commands

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

%in_heading_spec_commands

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

%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

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

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

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

%root_commands

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

%sectioning_heading_commands

All the sectioning and heading commands.

%variadic_commands

Commands with unlimited arguments, like @example.

1.7 Texinfo::Commands SEE ALSO

Texinfo::Parser, Texinfo::Common.

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

2.3 Texinfo::Common NOTES

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

2.4 Texinfo::Common DESCRIPTION

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

2.5 MISC INFORMATION

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

TODO: undocumented %null_device_file %default_parser_customization_values %document_settable_multiple_at_commands %document_settable_unique_at_commands %default_converter_command_line_options %default_main_program_customization_options %default_converter_customization @variable_string_settables %document_settable_at_commands %def_map %command_structuring_level %level_to_structuring_command

%texinfo_output_formats

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

2.6 @-COMMAND INFORMATION

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

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

%all_commands

All the @-commands.

%brace_code_commands

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

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

%explained_commands

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

%inline_conditional_commands

%inline_format_commands

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

%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 (libintl-perl), 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.

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

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

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.

$normalized_name = normalize_top_node_name($node_string)

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

protect_colon_in_tree($tree)

protect_node_after_label_in_tree($tree)

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

protect_comma_in_tree($tree)

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

$contents_result = protect_first_parenthesis($contents)

Return a contents array reference with first parenthesis in the contents array reference protected. If $contents is undef a fatal error with a backtrace will be emitted.

relate_index_entries_to_table_entries_in_tree($tree)

In @*table @-commands, reassociate the index entry information from an index @-command appearing right after an @item line to the @item first element. Remove the index @-command from the tree.

$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 configuration option corresponding to $cmdname in $customization_information. The $global_commands_information should contain information about global commands in a Texinfo document, typically obtained from a parser $parser->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 configuration value, or undef if no configuration 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.

set_informative_command_value($customization_information, $element)

Set the Texinfo configuration 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.

set_output_encodings($customization_information, $parser_information)

If not already set, set OUTPUT_ENCODING_NAME based on input file encoding. Also set OUTPUT_PERL_ENCODING accordingly which is used to output in the correct encoding. In general, OUTPUT_PERL_ENCODING should not be set directly by user-defined code such that it corresponds to OUTPUT_ENCODING_NAME.

$split_contents = split_custom_heading_command_contents($contents)

Split the $contents array reference at @| in at max three parts. Return an array reference containing the split parts. The $contents array reference is supposed to be $element->{'args'}->[0]->{'contents'} of %Texinfo::Commands::heading_spec_commands commands such as @everyheading.

trim_spaces_comment_from_content($contents)

Remove empty spaces after commands or braces at begin and spaces and comments at end from a content array, modifying it.

valid_customization_option($name)

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

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 $tree = $parser->parse_texi_file("somefile.texi");
  # a Texinfo::Report object in which the errors and warnings
  # encountered while parsing are registered.
  my $registrar = $parser->registered_errors();
  my ($errors, $errors_count) = $registrar->errors();
  foreach my $error_message (@$errors) {
    warn $error_message->{'error_line'};
  }

  my $index_names = $parser->indices_information();
  my $float_types_arrays = $parser->floats_information();
  my $internal_references_array
    = $parser->internal_references_information();
  # $labels_information is an hash reference on normalized node/float/anchor names.
  my ($labels_information, $targets_list, $nodes_list) = $parser->labels_information();
  # A hash reference, keys are @-command names, value is an
  # array reference holding all the corresponding @-commands.
  my $global_commands_information = $parser->global_commands_information();
  # a hash reference on document information (encodings,
  # input file name, dircategory and direntry list, for example).
  my $global_information = $parser->global_information();

3.3 Texinfo::Parser NOTES

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

3.4 Texinfo::Parser DESCRIPTION

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

3.5 Texinfo::Parser METHODS

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

• Initialization
• Parsing Texinfo text
• Getting information on the document

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. args is also used for the elements of a menu entry, as a menu entry is well-structured with a limited number of arguments. 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 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::Structuring NAME

Texinfo::Structuring - information on Texinfo::Parser tree

4.2 Texinfo::Structuring SYNOPSIS

  use Texinfo::Structuring qw(sectioning_structure nodes_tree number_floats
    associate_internal_references split_by_node split_by_section split_pages
    merge_indices sort_indices elements_directions elements_file_directions);

  # $tree is a Texinfo document tree.  $parser is a Texinfo::Parser object.
  # $config is an object implementing the get_conf() method.
  my $registrar = $parser->registered_errors();
  my $sections_root = sectioning_structure ($registrar, $config, $tree);
  my ($labels, $targets_list, $nodes_list) = $parser->labels_information();
  my $parser_information = $parser->global_information();
  my $global_commands = $parser->global_commands_information();
  set_menus_node_directions($registrar, $config, $parser_information,
                            $global_commands, $nodes_list, $labels);
  my $top_node = nodes_tree($registrar, $config, $parser_information, $nodes_list, $labels);
  complete_node_tree_with_menus($registrar, $config, $nodes_list, $top_node);
  my $refs = $parser->internal_references_information();
  check_nodes_are_referenced($registrar, $config, $nodes_list, $top_node, $labels, $refs);
  associate_internal_references($registrar, $parser, $parser_information, $labels, $refs);
  number_floats($parser->floats_information());
  my $tree_units;
  if ($split_at_nodes) {
    $tree_units = split_by_node($tree);
  } else {
    $tree_units = split_by_section($tree);
  }
  split_pages($tree_units, $split);
  elements_directions($config, $labels, $tree_units);
  elements_file_directions($tree_units);

  my $index_names = $parser->indices_information();
  my $merged_index_entries
     = merge_indices($index_names);
  my $index_entries_sorted;
  if ($sort_by_letter) {
    $index_entries_sorted = sort_indices($registrar, $config,
                                       $merged_index_entries, 'by_letter');
  } else {
    $index_entries_sorted = sort_indices($registrar, $config,
                                         $merged_index_entries);
  }

4.3 Texinfo::Structuring NOTES

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

4.4 Texinfo::Structuring DESCRIPTION

Texinfo::Structuring first allows to collect information on a Texinfo tree. In most case, it also requires information from a parser object to do that job. Thanks to sectioning_structure the hierarchy of sectioning commands is determined. The directions implied by menus are determined with set_menus_node_directions. The node tree is analysed with nodes_tree. Nodes directions are completed with menu directions with complete_node_tree_with_menus. Floats get their standard numbering with number_floats and internal references are matched up with nodes, floats or anchors with associate_internal_references.

The following methods depend on the output format, so are usually called from converters.

It is also possible to associate top-level contents of the tree, which consist in nodes and sectioning commands with tree unit elements that group together a node and the next sectioning element. With split_by_node nodes are considered to be the main sectioning elements, while with split_by_section the sectioning command elements are the main elements. The first mode is typical of Info format, while the second corresponds to a traditional book. The elements may be further split in pages, which are not pages as in book pages, but more like web pages, and hold series of tree unit elements.

The elements may have directions to other elements prepared by elements_directions. elements_file_directions should also set direction related to files, provided files are associated with elements by the user.

merge_indices may be used to merge indices, which may be sorted with sort_indices.

4.5 Texinfo::Structuring METHODS

No method is exported in the default case.

Most methods takes a Texinfo::Report $registrar as argument for error reporting. Most also require Texinfo customization variables information, which means an object implementing the get_conf method, in practice the main program configuration or a converter (Getting and setting customization variables). Other common input arguments such as parser information, labels or refs are obtained from a parser, see Texinfo::Parser.

associate_internal_references($registrar, $customization_information, $parser_information, $labels, $refs)

Verify that internal references (@ref and similar without fourth of fifth argument and menu entries) have an associated node, anchor or float. Set the normalized key in the extra hash menu_entry_node hash for menu entries and in the extra hash node_argument hash for internal references @ref and similar @-commands. Set the label key in the extra hash of the reference tree element to the associated labeled tree element. Register errors in $registrar.

check_nodes_are_referenced($registrar, $customization_information, $nodes_list, $top_node, $labels, $refs)

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

Should be called after complete_node_tree_with_menus in order to have the autogenerated menus available.

complete_node_tree_with_menus($registrar, $customization_information, $nodes_list, $top_node)

Complete nodes directions with menu directions. Check consistency of menus, sectionning and nodes direction structures. Register errors in $registrar.

elements_directions($customization_information, $labels, $tree_units)

Directions are set up for the tree unit elements in the array reference $tree_units given in argument. The corresponding hash is in {'structure'}->{'directions'} and keys correspond to directions while values are elements.

The following directions are set up:

This

The element itself.

Forward

Element next.

Back

Previous element.

NodeForward

Following node element in reading order. It is the next node, or the first in menu or the next of the up node.

NodeBack

Preceding node element.

NodeUp

NodeNext

NodePrev

The up, next and previous node elements.

Up

Next

Prev

The up, next and previous section elements.

FastBack

For top level elements, the previous top level element. For other elements the up top level element. For example, for a chapter element it is the previous chapter, for a subsection element it is the chapter element that contains the subsection.

FastForward

The next top level section element.

elements_file_directions($tree_units)

In the directions reference described above for elements_directions, sets the PrevFile and NextFile directions to the elements in previous and following files.

It also sets FirstInFile* directions for all the elements by using the directions of the first element in file. So, for example, FirstInFileNodeNext is the next node of the first element in the file of each element.

The API for association of pages/elements to files is not defined yet.

@nodes_list = get_node_node_childs_from_sectioning($node)

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

$entry_key = index_entry_sort_string($main_entry, $entry_tree_element, $sortas, $options)

Return a string suitable as a sort string, for index entries. The index entry processed is $entry_tree_element, and can be a @subentry. $main_entry is the main index entry tree element that can be used to gather information. $sortas can be given to override the sort string (typically obtained from @sortas). The $options are options used for Texinfo to text conversion for the generation of the sort string, typically obtained from setup_index_entry_keys_formatting.

$merged_entries = merge_indices($index_names)

Using information returned by Texinfo::Parser indices_information, a structure holding all the index entries by index name is returned, with all the entries of merged indices merged with those of the indice merged into.

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

$new_block = new_block_command($content, $parent, $command_name)

Returns the texinfo tree corresponding to a block command named $command_name with contents $content and parent in tree $parent.

$new_menu = new_complete_node_menu($node, $use_sections)

Returns a texinfo tree menu for node $node, pointing to the children of the node obtained with the sectioning structure. If $use_sections is set, use section names for the menu entry names.

$entry = new_node_menu_entry($node, $use_sections)

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

$top_node = nodes_tree($registrar, $customization_information, $parser_information, $nodes_list, $labels)

Goes through nodes and set directions. Returns the top node. Register errors in $registrar.

This functions sets, in the structure node element hash:

node_up

node_prev

node_next

Up, next and previous directions for the node.

number_floats($float_information)

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

$command_name = section_level_adjusted_command_name($element)

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

$sections_root, $sections_list = sectioning_structure($registrar, $customization_information, $tree)

This function goes through the tree and gather information on the document structure for sectioning commands. It returns $sections_root the root of the sectioning commands tree and a reference on the sections elements list. Errors are registered in $registrar.

It sets section elements structure hash values:

section_level

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

section_number

The sectioning element number.

section_childs

An array holding sectioning elements children of the element.

section_up

section_prev

section_next

The up, previous and next sectioning elements.

toplevel_next

toplevel_prev

toplevel_up

The next and previous and up sectioning elements of toplevel sectioning elements (like @top, @chapter, @appendix), not taking into account @part elements.

set_menus_node_directions($registrar, $customization_information, $parser_information, $global_commands, $nodes_list, $labels);

Goes through menu and set directions. Register errors in $registrar.

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

menu_child

The first child in the menu of the node.

menu_up

menu_next

menu_prev

Up, next and previous directions as set in menus.

$option = setup_index_entry_keys_formatting($customization_information)

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

($index_entries_sorted, $index_entries_sort_strings) = sort_indices($registrar, $customization_information, $merged_index_entries, $sort_by_letter)

If $sort_by_letter is set, sort by letter, otherwise sort all entries together. In both cases, a hash reference with index names as keys $index_entries_sorted is returned.

When sorting by letter, an array reference of letter hash references is associated with each index name. Each letter hash reference has two keys, a letter key with the letter, and an entries key with an array reference of sorted index entries beginning with the letter.

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

$index_entries_sort_strings is a hash reference associating the index entries with the strings that were used to sort them.

Register errors in $registrar.

$tree_units = split_by_node($tree)

Returns a reference array of tree units where a node is associated to the following sectioning commands. Sectioning commands without nodes are also with the previous node, while nodes without sectioning commands are alone in their tree units.

Tree units are regular tree elements with type unit, the associated nodes and sectioning tree elements are in the array associated with the contents key. The associated elements have a associated_unit key set in the structure hash that points to the associated tree unit.

Tree units have directions in the structure hash reference, namely unit_next and unit_prev pointing to the previous and the next tree unit.

In the extra hash reference, tree units have:

unit_command

The node command associated with the element.

$tree_units = split_by_section($tree)

Similarly with split_by_node, returns an array of tree units. This time, lone nodes are associated with the previous sections and lone sections makes up a tree unit.

The structure and extra hash keys set are the same, except that unit_command is the sectioning command associated with the element.

$pages = split_pages($tree_units, $split)

The tree units from the array reference argument have an extra first_in_page value set in the structure hash reference to the first tree unit in the group, and based on the value of $split. The possible values for $split are

chapter

The tree units are split at chapter or other toplevel sectioning tree units.

node

Each element has its own page.

section

The tree units are split at sectioning commands below chapter.

value evaluating to false

No splitting, only one page is returned, holding all the tree units.

warn_non_empty_parts($registrar, $customization_information, $global_commands)

Register a warning in $registrar for each @part that is not empty in $global_commands information (typically obtained by calling global_commands_information() on a parser).

4.6 Texinfo::Structuring SEE ALSO

Texinfo manual, Texinfo::Parser.

4.7 Texinfo::Structuring AUTHOR

Patrice Dumas, <pertusus@free.fr>

4.8 Texinfo::Structuring COPYRIGHT AND LICENSE

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

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

5.1 Texinfo::Report NAME

Texinfo::Report - Error storing for Texinfo modules

5.2 Texinfo::Report SYNOPSIS

  use Texinfo::Report;

  my $registrar = Texinfo::Report::new();
  
  if ($warning_happened) {
    $registrar->line_warn($converter, sprintf(__("\@%s is wrongly used"),
                       $current->{'cmdname'}), $current->{'source_info'});
  }
  
  my ($errors, $errors_count) = $registrar->errors();
  foreach my $error_message (@$errors) {
    warn $error_message->{'error_line'};
  }

5.3 Texinfo::Report NOTES

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

5.4 Texinfo::Report DESCRIPTION

The Texinfo::Report module helps with error handling. It is used by the Texinfo modules Texinfo::Parser and Texinfo::Convert::Converter. To use this module, either create a new Texinfo::Report object or initialize another object such as to be able to call Texinfo::Report methods. In any case, Texinfo::Report::new() is called to setup the module.

Besides the new method, errors is used for reporting errors, and the other methods to store errors (and warnings).

5.5 Texinfo::Report METHODS

No method is exported in the default case.

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

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

$converter->Texinfo::Report::new()

If called without argument, a Texinfo::Report object is initialized and returned. This is how the module is used in the Texinfo Parsers, as a separate object.

If called on a $converter, the $converter is initialized itself such as to be able to call Texinfo::Report methods. It is how it is used in the Converters.

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

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

type

May be warning, or error.

text

The text of the error.

error_line

The text of the error formatted with the file name, line number and macro name, as needed.

line_nr

The line number of the error or warning.

file_name

The file name where the error or warning occurs.

macro

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

$registrar->line_warn($text, $configuration_information, $error_location_info)

$registrar->line_error($text, $configuration_information, $error_location_info)

Register a warning or an error. The $text is the text of the error or warning. The $configuration_information object gives some information that can modify the messages or their delivery. The optional $error_location_info holds the information on the error or warning location. The $error_location_info reference on hash may be obtained from Texinfo elements source_info keys. It may also be setup to point to a file name, using the file_name key and to a line number, using the line_nr key. The file_name key value should be a binary string.

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

$registrar->document_warn($configuration_information, $text)

$registrar->document_error($configuration_information, $text)

Register a document-wide error or warning. $text is the error or warning message. The $configuration_information object gives some information that can modify the messages or their delivery.

5.6 Texinfo::Report AUTHOR

Patrice Dumas, <pertusus@free.fr>

5.7 Texinfo::Report COPYRIGHT AND LICENSE

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

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

6.1 Texinfo::Translations NAME

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

6.2 Texinfo::Translations SYNOPSIS

  @ISA = qw(Texinfo::Translations);

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

6.3 Texinfo::Translations NOTES

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

6.4 Texinfo::Translations DESCRIPTION

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

Translation of error messages uses another interface, which is the classical gettext based perl interface. It is not described as it is described in details elsewhere, some elements are in Texinfo::Common __ and __p.

6.5 Texinfo::Translations METHODS

No method is exported.

The gdt method is used to translate strings to be output in converted documents, and returns, in general, a texinfo tree.

$tree = $object->gdt($string, $replaced_substrings, $mode, $lang)

The $string is a string to be translated. In the default case, the function returns a Texinfo tree, as the string is interpreted as Texinfo code after translation. $replaced_substrings is an optional hash reference specifying some substitution to be done after the translation. The key of the $replaced_substrings hash reference identifies what is to be substituted, and the value is some string, texinfo tree or array content that is substituted in the resulting texinfo tree. In the string to be translated word in brace matching keys of $replaced_substrings are replaced. The $object is typically a converter, but can be any object that implements get_conf, or undefined (undef). If not undefined, the information in the $object is used to determine the encoding, the documentlanguage and get some customization information. $lang is optional. If set, it overrides the documentlanguage.

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

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

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

$mode is an optional string which may modify how the function behaves. The possible values are:

translated_text

In that case the string is not considered to be Texinfo, a plain string that is returned after translation and substitution. The substitutions may only be strings in that case.

6.6 Texinfo::Translations AUTHOR

Patrice Dumas, <pertusus@free.fr>

6.7 Texinfo::Translations COPYRIGHT AND LICENSE

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

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

7.1 Texinfo::Transformations NAME

Texinfo::Transformations - transformations of Texinfo Perl tree

7.2 Texinfo::Transformations NOTES

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

7.3 Texinfo::Transformations DESCRIPTION

Includes miscellaneous methods set_menus_to_simple_menu and menu_to_simple_menu to change the menu texinfo tree, as well as insert_nodes_for_sectioning_commands that adds nodes for sectioning commands without nodes and complete_tree_nodes_menus and complete_tree_nodes_missing_menu that completes the node menus based on the sectioning tree.

7.4 Texinfo::Transformations METHODS

No method is exported in the default case.

complete_tree_nodes_menus($tree, $add_section_names_in_entries)

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

complete_tree_nodes_missing_menu($tree, $use_section_names_in_entries)

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

($root_content, $added_sections) = fill_gaps_in_sectioning($tree)

This function adds empty @unnumbered and similar commands in a tree to fill gaps in sectioning. This may be used, for example, when converting from a format that can handle gaps in sectioning. $tree is the tree root. An array reference is returned, containing the root contents with added sectioning commands, as well as an array reference containing the added sectioning commands.

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

($root_content, $added_nodes) = insert_nodes_for_sectioning_commands($tree, $nodes_list, $targets_list, $labels)

Insert nodes for sectioning commands without node in $tree. Add nodes to the labels used as targets for references $labels and $targets_list and to $nodes_list.

An array reference is returned, containing the root contents with added nodes, as well as an array reference containing the added nodes.

menu_to_simple_menu($menu)

set_menus_to_simple_menu($nodes_list)

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

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

$detailmenu = new_master_menu($translations, $labels)

Returns a detailmenu tree element formatted as a master node. $translations, if defined, should be a Texinfo::Translations object and should also hold customization information.

protect_hashchar_at_line_beginning($registrar, $customization_information, $tree)

Protect hash (#) character at the beginning of line such that they would not be considered as lines to be processed by the CPP processor. The $registrar and $customization_information arguments may be undef. If defined, the $registrar argument should be a 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 environment.

$modified_tree = reference_to_arg_in_tree($tree)

Modify $tree by converting reference @-commands to simple text using one of the arguments. This transformation can be used, for example, to remove reference @-command from constructed node names trees, as node names cannot contain reference @-command while there could be some in the tree used in input for the node name tree.

regenerate_master_menu($translations, $labels)

Regenerate the Top node master menu, replacing the first detailmenu in Top node menus or appending at the end of the Top node menu. $translations, if defined, should be a Texinfo::Translations object and should also hold customization information.

7.5 Texinfo::Transformations SEE ALSO

Texinfo manual, Texinfo::Parser.

7.6 Texinfo::Transformations AUTHOR

Patrice Dumas, <pertusus@free.fr>

7.7 Texinfo::Transformations COPYRIGHT AND LICENSE

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

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

8.1 Texinfo::Convert::Texinfo NAME

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

8.2 Texinfo::Convert::Texinfo SYNOPSIS

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

8.3 Texinfo::Convert::Texinfo NOTES

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

8.4 Texinfo::Convert::Texinfo DESCRIPTION

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

8.5 Texinfo::Convert::Texinfo METHODS

$texinfo_text = convert_to_texinfo($tree)

Converts the Texinfo tree $tree to Texinfo code.

8.6 Texinfo::Convert::Texinfo AUTHOR

Patrice Dumas, <pertusus@free.fr>

8.7 Texinfo::Convert::Texinfo COPYRIGHT AND LICENSE

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

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

9.1 Texinfo::Convert::Utils NAME

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

9.2 Texinfo::Convert::Utils SYNOPSIS

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

9.3 Texinfo::Convert::Utils NOTES

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

9.4 Texinfo::Convert::Utils DESCRIPTION

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

9.5 Texinfo::Convert::Utils METHODS

No method is exported in the default case.

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

$arguments = definition_arguments_content($element)

$element should be a @def* Texinfo tree element. Texinfo elements on the @-command line corresponding to arguments in the function definition are returned in the $arguments array reference. Arguments correspond to text following the category and the name 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_output_file_name($converter, $character_string_name)

Encode $character_string_name in the same way as other file name 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 $converter argument is not optional and is used both to access to customization variables and to access to parser information.

$tree = expand_today($converter)

Expand today’s date, as a texinfo tree with translations.

$tree = expand_verbatiminclude($registrar, $customization_information, $verbatiminclude)

The $registrar argument may be undef. $verbatiminclude is a @verbatiminclude tree element. This function returns a @verbatim tree elements after finding the included file and reading it. If $registrar is not defined, errors messages are not registered.

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

$element should be an accent command Texinfo tree element. Returns an array reference containing the innermost accent command contents, normally a text element with one or two letter, and an array reference containing the accent commands nested in $element (including $element).

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

9.6 Texinfo::Convert::Utils SEE ALSO

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

9.7 Texinfo::Convert::Utils AUTHOR

Patrice Dumas, <pertusus@free.fr>

9.8 Texinfo::Convert::Utils COPYRIGHT AND LICENSE

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

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

10.1 Texinfo::Convert::Unicode NAME

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

10.2 Texinfo::Convert::Unicode SYNOPSIS

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

  my ($innermost_contents, $stack)
      = Texinfo::Convert::Utils::find_innermost_accent_contents($accent);
  
  my $formatted_accents = encoded_accents ($converter,
                 convert_to_text($innermost_contents), $stack, $encoding,
                        \&Texinfo::Text::ascii_accent_fallback);

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

10.3 Texinfo::Convert::Unicode NOTES

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

10.4 Texinfo::Convert::Unicode DESCRIPTION

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

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

10.5 Texinfo::Convert::Unicode METHODS

$result = brace_no_arg_command($command_name, $encoding)

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

$possible_conversion = check_unicode_point_conversion($arg, $output_debug)

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

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

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

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

$width = string_width($string)

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

$result = unicode_accent($text, $accent_command)

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

$is_decoded = unicode_point_decoded_in_encoding($encoding, $unicode_point)

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

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

$result = unicode_text($text, $in_code)

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

10.6 Texinfo::Convert::Unicode AUTHOR

Patrice Dumas, <pertusus@free.fr>

10.7 Texinfo::Convert::Unicode COPYRIGHT AND LICENSE

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

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

11.1 Texinfo::Convert::NodeNameNormalization NAME

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

11.2 Texinfo::Convert::NodeNameNormalization SYNOPSIS

  use Texinfo::Convert::NodeNameNormalization qw(normalize_node
                                              transliterate_texinfo);

  my $normalized = normalize_node({'contents' => $node_contents});

  my $file_name = transliterate_texinfo({'contents'
                                            => $section_contents});

11.3 Texinfo::Convert::NodeNameNormalization NOTES

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

11.4 Texinfo::Convert::NodeNameNormalization DESCRIPTION

Texinfo::Convert::NodeNameNormalization allows to normalize node names, with normalize_node following the specification described in the Texinfo manual HTML Xref node. This is usefull each time one want a unique identifier for Texinfo content that is only composed of letter, digits, - and _. In Texinfo::Parser, normalize_node is used for @node, @float and @anchor names normalization, but also @float types and @acronym and @abbr first argument.

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

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

11.5 Texinfo::Convert::NodeNameNormalization METHODS

$partially_normalized = convert_to_normalized($tree)

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

$normalized = normalize_node($tree)

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

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

$transliterated = transliterate_texinfo($tree, $no_unidecode)

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

$file_name = transliterate_protect_file_name($string, $no_unidecode)

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

11.6 Texinfo::Convert::NodeNameNormalization AUTHOR

Patrice Dumas, <pertusus@free.fr>

11.7 Texinfo::Convert::NodeNameNormalization COPYRIGHT AND LICENSE

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

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

12.1 Texinfo::Convert::Text NAME

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

12.2 Texinfo::Convert::Text SYNOPSIS

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

  my $result = convert_to_text($tree);
  my $result_encoded = convert_to_text($tree,
             {'enabled_encoding' => 'utf-8'});
  my $result_converter = convert_to_text($tree,
             {'converter' => $converter});

  my $result_accent_text = ascii_accent('e', $accent_command);
  my $accents_text = text_accents($accents, 'utf-8');

12.3 Texinfo::Convert::Text NOTES

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

12.4 Texinfo::Convert::Text DESCRIPTION

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

12.5 Texinfo::Convert::Text METHODS

$result = convert_to_text($tree, $options)

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

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

The following options may be set:

enabled_encoding

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

sc

If set, the text is upper-cased.

code

If set the text is in code style. (mostly --, ---, '' and `` are kept as is).

NUMBER_SECTIONS

If set, sections are numbered when output.

sort_string

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

converter

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

expanded_formats_hash

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

$result_accent_text = ascii_accent($text, $accent_command)

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

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

Same as ascii_accent but with an additional first argument converter, which is ignored, but needed if this function is to be in argument of functions that need a fallback for accents conversion.

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

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

12.6 Texinfo::Convert::Text AUTHOR

Patrice Dumas, <pertusus@free.fr>

12.7 Texinfo::Convert::Text COPYRIGHT AND LICENSE

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

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

13.1 Texinfo::Convert::Converter NAME

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

13.2 Texinfo::Convert::Converter SYNOPSIS

  package Texinfo::Convert::MyConverter;

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

  sub converter_defaults ($$) {
    return %myconverter_defaults;
  }
  sub converter_initialize($) {
    my $self = shift;
    $self->{'document_context'} = [{}];
  }

  sub convert($$) {
    ...
  }
  sub convert_tree($$) {
    ...
  }
  sub output($$) {
    ...
  }

  # end of Texinfo::Convert::MyConverter

  my $converter = Texinfo::Convert::MyConverter->converter(
                                               {'parser' => $parser});
  $converter->output($texinfo_tree);

13.3 Texinfo::Convert::Converter NOTES

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

13.4 Texinfo::Convert::Converter DESCRIPTION

Texinfo::Convert::Converter is a super class that can be used to simplify converters initialization. The class also provide some useful methods.

In turn, the converter should define some methods. Two are optional, converter_defaults, converter_initialize and used for initialization, to give information to Texinfo::Convert::Converter.

The convert_tree method is mandatory and should convert portions of Texinfo tree. The output method is used by converters as entry point for conversion to a file with headers and so on. Although it is is not called from other modules, it should in general be implemented by converters. output is called from texi2any. convert is not required, but customarily used by converters as entry point for a conversion of a whole Texinfo tree without the headers done when outputting to a file.

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

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

13.5 Texinfo::Convert::Converter METHODS

• Initialization
• Getting and setting customization variables
• Conversion to XML
• Helper methods

13.6 Texinfo::Convert::Converter SEE ALSO

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

13.7 Texinfo::Convert::Converter AUTHOR

Patrice Dumas, <pertusus@free.fr>

13.8 Texinfo::Convert::Converter COPYRIGHT AND LICENSE

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

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

14.1 Texinfo::Convert::Info NAME

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

14.2 Texinfo::Convert::Info SYNOPSIS

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

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

14.3 Texinfo::Convert::Info NOTES

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

14.4 Texinfo::Convert::Info DESCRIPTION

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

14.5 Texinfo::Convert::Info METHODS

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

Initialize converter from Texinfo to Info.

The $options hash reference holds options for the converter. In this option hash reference a parser object may be associated with the parser key. The other options are Texinfo customization options and a few other options that can be passed to the converter. Most of the customization options are described in the Texinfo manual. Those customization options, when appropriate, override the document content. The parser should not be available directly anymore after getting the associated information.

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

$converter->output($tree)

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

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

Convert a Texinfo tree $tree and return the resulting output.

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

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

14.6 Texinfo::Convert::Info AUTHOR

Patrice Dumas, <pertusus@free.fr>

14.7 Texinfo::Convert::Info COPYRIGHT AND LICENSE

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

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

15.1 Texinfo::Convert::HTML NAME

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

15.2 Texinfo::Convert::HTML SYNOPSIS

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

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

15.3 Texinfo::Convert::HTML NOTES

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

15.4 Texinfo::Convert::HTML DESCRIPTION

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

15.5 Texinfo::Convert::HTML METHODS

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

Initialize converter from Texinfo to HTML.

The $options hash reference holds options for the converter. In this option hash reference a parser object may be associated with the parser key. The other options are Texinfo customization options and a few other options that can be passed to the converter. Most of the customization options are described in the Texinfo manual. Those customization options, when appropriate, override the document content. The parser should not be available directly anymore after getting the associated information.

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

$converter->output($tree)

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

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

Convert a Texinfo tree $tree and return the resulting output.

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

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

$result = $converter->output_internal_links()

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

15.6 Texinfo::Convert::HTML AUTHOR

Patrice Dumas, <pertusus@free.fr>

15.7 Texinfo::Convert::HTML COPYRIGHT AND LICENSE

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

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

16.1 Texinfo::Convert::DocBook NAME

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

16.2 Texinfo::Convert::DocBook SYNOPSIS

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

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

16.3 Texinfo::Convert::DocBook NOTES

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

16.4 Texinfo::Convert::DocBook DESCRIPTION

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

16.5 Texinfo::Convert::DocBook METHODS

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

Initialize converter from Texinfo to DocBook.

The $options hash reference holds options for the converter. In this option hash reference a parser object may be associated with the parser key. The other options are Texinfo customization options and a few other options that can be passed to the converter. Most of the customization options are described in the Texinfo manual. Those customization options, when appropriate, override the document content. The parser should not be available directly anymore after getting the associated information.

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

$converter->output($tree)

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

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

Convert a Texinfo tree $tree and return the resulting output.

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

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

16.6 Texinfo::Convert::DocBook AUTHOR

Patrice Dumas, <pertusus@free.fr>

16.7 Texinfo::Convert::DocBook COPYRIGHT AND LICENSE

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

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

17.1 Texinfo::Convert::TexinfoMarkup NAME

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

17.2 Texinfo::Convert::TexinfoMarkup SYNOPSIS

  package Texinfo::Convert::TexinfoMyMarkup;

  use Texinfo::Convert::TexinfoMarkup;

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

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

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

17.3 Texinfo::Convert::TexinfoMarkup NOTES

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

17.4 Texinfo::Convert::TexinfoMarkup DESCRIPTION

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

The Texinfo Markup Language elements and attributes are not documented, but the Texinfo XML output by the Texinfo::Convert::TexinfoXML subclass (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.

17.5 Texinfo::Convert::TexinfoMarkup METHODS

• Markup formatting methods defined by subclasses
• Formatting state information

17.6 Texinfo::Convert::TexinfoMarkup AUTHOR

Patrice Dumas, <pertusus@free.fr>

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

17.8 Texinfo::Convert::TexinfoMarkup COPYRIGHT AND LICENSE

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

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

18.1 Texinfo::Convert::TexinfoXML NAME

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

18.2 Texinfo::Convert::TexinfoXML SYNOPSIS

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

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

18.3 Texinfo::Convert::TexinfoXML NOTES

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

18.4 Texinfo::Convert::TexinfoXML DESCRIPTION

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

18.5 Texinfo::Convert::TexinfoXML METHODS

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

Initialize converter from Texinfo to TexinfoXML.

The $options hash reference holds options for the converter. In this option hash reference a parser object may be associated with the parser key. The other options are Texinfo customization options and a few other options that can be passed to the converter. Most of the customization options are described in the Texinfo manual. Those customization options, when appropriate, override the document content. The parser should not be available directly anymore after getting the associated information.

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

$converter->output($tree)

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

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

Convert a Texinfo tree $tree and return the resulting output.

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

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

18.6 Texinfo::Convert::TexinfoXML AUTHOR

Patrice Dumas, <pertusus@free.fr>

18.7 Texinfo::Convert::TexinfoXML COPYRIGHT AND LICENSE

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

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

19.1 Texinfo::Convert::Plaintext NAME

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

19.2 Texinfo::Convert::Plaintext SYNOPSIS

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

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

19.3 Texinfo::Convert::Plaintext NOTES

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

19.4 Texinfo::Convert::Plaintext DESCRIPTION

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

19.5 Texinfo::Convert::Plaintext METHODS

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

Initialize converter from Texinfo to Plaintext.

The $options hash reference holds options for the converter. In this option hash reference a parser object may be associated with the parser key. The other options are Texinfo customization options and a few other options that can be passed to the converter. Most of the customization options are described in the Texinfo manual. Those customization options, when appropriate, override the document content. The parser should not be available directly anymore after getting the associated information.

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

$converter->output($tree)

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

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

Convert a Texinfo tree $tree and return the resulting output.

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

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

19.6 Texinfo::Convert::Plaintext AUTHOR

Patrice Dumas, <pertusus@free.fr>

19.7 Texinfo::Convert::Plaintext COPYRIGHT AND LICENSE

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

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