"Fossies" - the Fresh Open Source Software Archive

Member "texinfo-6.5/doc/tp_api/tp_api.texi" (12 Sep 2017, 13413 Bytes) of package /linux/misc/texinfo-6.5.tar.xz:


Caution: As a special service "Fossies" has tried to format the requested Texinfo source page into HTML format but that may be not always succeeeded perfectly. Alternatively you can here view or download the uninterpreted Texinfo source code. A member file download can also be achieved by clicking within a package contents listing on the according byte size field. See also the last Fossies "Diffs" side-by-side code changes report for "tp_api.texi": 6.3_vs_6.4.

Texinfo perl module


[ < ] [ > ]   [Contents] [Index] [ ? ]

Texinfo perl module


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1 Texinfo::Common


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.1 NAME

Texinfo::Common - Classification of commands and miscellaneous methods


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.2 SYNOPSIS

  use Texinfo::Common qw(expand_today expand_verbatiminclude);
  if ($Texinfo::Common::accent_commands{$a_command}) {
    print STDERR "$a_command is an accent command\n";
  }
  
  my $today_tree = expand_today($converter);
  my $verbatiminclude_tree 
     = expand_verbatiminclude(undef, $verbatiminclude);

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.3 DESCRIPTION

Texinfo::Common holds interesting hashes classifying Texinfo @-commands, as well as miscellaneous methods that may be useful for any backend converting texinfo trees.

It also defines, as our variable a hash for default indices, named %index_names. The format of this hash is described in Texinfo::Parser indices_information.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.4 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:

%all_commands

All the @-commands.

%no_brace_commands

Commands without brace with a single character as name, like * or :. The value is an ascii representation of the command. It may be an empty string.

%misc_commands

Command that do not take braces and are not block commands either, like @node, @chapter, @cindex, @deffnx, @end, @footnotestyle, @set, @settitle, @indent, @definfoenclose, @comment and many others.

%default_index_commands

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

%root_commands

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

%sectioning_commands

All the sectioning and heading commands.

%brace_commands

The commands that take braces. The associated value is the maximum number of arguments.

%letter_no_arg_commands

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

%accent_commands

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

%style_commands

Commands that mark a fragment of texinfo, like @strong, @cite, @code or @asis.

%code_style_commands

style_commands that have their argument in code style, like @code.

%regular_font_style_commands

style_commands that have their argument in regular font, like @r or @slanted.

%context_brace_commands

@-commands with brace like @footnote, @caption and @math whose argument is outside of the main text flow in one way or another.

%ref_commands

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

%explained_commands

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

%block commands

Commands delimiting a block with a closing @end. The value is conditional for @if commands, def for definition commands like @deffn, raw for @-commands that have no expansion of @-commands in their bodies and multitable for @multitable. Otherwise it is set to the number of arguments separated by commas that may appear on the @-command line. That means 0 in most cases, 1 for @quotation and 2 for @float.

%raw_commands

@-commands that have no expansion of @-commands in their bodies, as @macro, @verbatim or @ignore.

%format_raw_commands

@-commands associated with raw output format, like @html, or @docbook.

%texinfo_output_formats

Cannonical output formats that have associated conditionals. In practice %format_raw_commands plus info and plaintext.

%def_commands

%def_aliases

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

%menu_commands

@-commands with menu entries.

%align_commands

@-commands related with alignement of text.

%region_commands

Block @-commands that enclose full text regions, like @titlepage.

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

%item_container_commands

Commands holding @item with @item that contains blocks of text, like @itemize.

%item_line_commands

Commands with @item that have their arguments on their lines, like @ftable.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.5 METHODS

No method is exported in the default case.

Most methods takes a $converter as argument, sometime optionally, to get some information and use methods for error reporting, see NAME and NAME.

$tree = expand_today($converter)

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

$tree = expand_verbatiminclude($converter, $verbatiminclude)

The $converter 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 $converter is not defined, the document encoding is not taken into account when reading the file.

$tree = definition_category($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.

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

$result = numbered_heading ($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.

($caption, $prepended) = float_name_caption ($converter, $float)

$float is a texinfo tree @float element. This function returns the caption that should be used for the float formatting and the $prepended texinfo tree combining the type and label of the float.

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

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.

$normalized_name = normalize_top_node_name ($node_string)

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

protect_comma_in_tree($tree)

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

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{}.

$contents_result = protect_first_parenthesis ($contents)

Return a contents array reference with first parenthesis in the contents array reference protected.

protect_hashchar_at_line_beginning($parser, $tree)

Protect hash character at beginning of line if the line is a cpp line directive. The $parser argument maybe undef, if it is defined it is used for error reporting in case an hash character could not be protected because it appeared in a raw environment.

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.

$command = find_parent_root_command($parser, $tree_element)

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

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.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.6 SEE ALSO

NAME, NAME and NAME.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.7 AUTHOR

Patrice Dumas, <pertusus@free.fr>


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.8 COPYRIGHT AND LICENSE

Copyright 2010, 2011, 2012, 2013, 2014, 2015 Free Software Foundation, Inc.

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.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2 Texinfo::Parser


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.1 NAME

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


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.2 SYNOPSIS

  use Texinfo::Parser;
  my $parser = Texinfo::Parser::parser();
  my $tree = $parser->parse_texi_file("somefile.texi");
  my ($errors, $errors_count) = $parser->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();
  # An hash reference on normalized node/float/anchor names
  my $labels_information = $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 some document informations (encodings, 
  # input file name, dircategory and direntry list, for exampel).
  my $global_informations = $parser->global_informations();

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.3 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 block command associated with @end, the number of rows in a multitable, or the node associated with a section.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.4.1 Initialization

The following method is used to construct a new Texinfo::Parser object:

$parser = Texinfo::Parser::parser($options);

This method creates a new parser. The options may be provided as a hash reference. There are two types of option. The first type of option change the way the parser behaves; they are described right here. The other type of option allows giving the parser some information as if it came from texinfo code; for example, allow setting aliases (as with @alias), values (as with @set), or merged indices (as with @synindex). These options are described below in Texinfo Parser options.

expanded_formats

An array reference of the output formats for which @ifFORMAT conditional blocks should be expanded. Default is empty.

gettext

If set, the function reference is used to translate error and warning messages. It takes a string as argument and returns a string. The default function returns the error message as-is.

GLOBAL_COMMANDS

The associated value is a reference on an array. All the commands in the array are collected during parsing. They are afterwards available through global_informations.

include_directories

An array reference of directories in which @include files should be searched for. Default contains the working directory, ‘.’.

IGNORE_BEFORE_SETFILENAME

If set, and @setfilename exists, everything before @setfilename is put in a special container type, @preamble_before_setfilename. This option is set in the default case.

IGNORE_SPACE_AFTER_BRACED_COMMAND_NAME

If set, spaces after an @-command name that take braces are ignored. Default on.

MAX_MACRO_CALL_NESTING

Maximal number of nested user-defined macro calls. Default is 100000.

SHOW_MENU

If false, no menu-related errors are reported. Default is true.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.4.2 Parsing Texinfo text

There are three methods that may be called to parse some Texinfo code: parse_texi_line for a line, parse_texi_text for a text fragment, and parse_texi_file for a file.

For all those functions, if the $parser argument is undef, a new parser object is generated to parse the line. Otherwise the parser given as an argument is used to parse into a tree.

When parse_texi_text is used, the resulting tree is rooted at a root_line type container. Otherwise, the resulting tree should be rooted at a text_root type container if it does not contain nodes or sections, at a document_root type container otherwise.

$tree = parse_texi_line($parser, $text, $first_line_number, $file_name, $macro_name, $fixed_line_number)

This function is used to parse a short fragment of Texinfo code.

$text may be either an array reference of lines, or a text.

The other arguments are optional and allow specifying the position information of the Texinfo code. $first_line_number is the line number of the first text line. $file_name is the name of the file the text comes from. $macro is for the user-defined macro name the text is expanded from. If $fixed_line_number is set, the line number is not increased for the different lines, as if the text was the expansion of a macro.

$tree = parse_texi_text ($parser, $text, $line_numbers_specification, $file_name, $macro_name, $fixed_line_number)

This function is used to parse some Texinfo text.

$text may be either an array reference of lines, or a text.

The other arguments are optional and allow specifying the position information of the Texinfo code. There are two distinct cases for $line_numbers_specification.

  1. If it is an array reference, it is considered to hold objects describing the position information of each text line.
  2. If $line_numbers_specification is a scalar, it is the line number of the first text line. In that case (like for parse_texi_text), $file_name is the name of the file the text comes from. and $macro is for the user-defined macro name the text is expanded from. If $fixed_line_number is set, the line number is not increased for the different lines, as if the text was the expansion of a macro.
$tree = parse_texi_file($parser, $file_name)

The file with name $file_name is considered to be a Texinfo file and is parsed into a tree.

undef is returned if the file couldn’t be read.

The errors collected during the tree parsing are available through the errors method. This method comes from Texinfo::Report, and is described in errors.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.4.3 Getting information on the document

After parsing some information about the Texinfo code that was processed is available from the parser.

Some global information is available through global_informations

$info = global_informations($parser)

The $info returned is a hash reference. The possible keys are

input_file_name

The name of the main Texinfo input file.

input_encoding_name

input_perl_encoding

input_encoding_name string is the encoding name used for the Texinfo code. input_perl_encoding string is a corresponding perl encoding name.

dircategory_direntry

An array of successive @dircategory and @direntry as they appear in the document.

novalidate

If set, it is as if @novalidate was set in the document.

Some command lists are available, such that it is possible to go through the corresponding tree elements without walking the tree. They are available through global_commands_information

$commands = global_commands_information($parser)

$commands is an hash reference. The keys are @-command names. The associated values are array references containing all the corresponding tree elements.

All the @-commands that have an associated label (so can be the target of cross references) - @node, @anchor and @float with label - have a normalized name associated, constructed as described in the HTML Xref node in the Texinfo manual. Those normalized labels and the association with @-commands is available through labels_information:

$labels_information = labels_information($parser)

$labels_information is a hash reference whose keys are normalized labels, and the associated value is the corresponding @-command.

Information on @float is also available, grouped by type of floats, each type correponding to potential @listoffloats. This information is available through the method floats_information.

$float_types = floats_information($parser)

$float_types is a hash reference whose keys are normalized float types (the first float argument, or the @listoffloats argument). The normalization is the same than for node names. The value is the list of float tree elements appearing in the texinfo document.

Internal references, that is, @-commands that refer to node, anchors or floats within the document are also available:

$internal_references_array = internal_references_information($parser);

The function returns a list of cross-reference commands referring to the same document.

Information about defined indices, merged indices and index entries is also available through the indices_information method.

indices_information

  $index_names = indices_information($parser);

The index names is a hash reference. The keys are

in_code

1 if the index entries should be formatted as code, 0 in the opposite case.

name

The index name.

prefix

An array reference of prefix associated to the index.

merged_in

In case the index is merged to another index, this key holds the name of the index the index is merged into. It takes into account indirectly merged indices.

contained_indices

An hash reference holding names of indices that are merged into the index, including itself. It also contains indirectly merged indices. This key is removed if the index is itself later merged to another index.

index_entries

An array reference containing index entry structures for index entries associated with the index. The index entry could be associated to @-commands like @cindex, or @item in @vtable, or definition commands entries like @deffn.

The keys of the index entry structures are

index_name

The index name.

index_at_command

The name of the @-command associated with the index entry.

index_type_command

The @-command associated with the index entry allowing to find the index type.

content

An array reference corresponding to the index entry content.

content_normalized

An array reference corresponding to the index entry content, independent of the current language.

command

The element in the parsed tree associated with the @-command holding the index entry.

node

The node in the parsed tree containing the index entry.

number

The number of the index entry.

region

The region command (@copying, @titlepage) containing the index entry, if it is in such an environement.

The following shows the references corresponding to the default indexes cp and fn, the fn index having its entries formatted as code and the indices corresponding to the following texinfo

  @defindex some
  @defcodeindex code

  $index_names = {'cp' => {'name' => 'cp', 'in_code' => 0, },
                  'fn' => {'name' => 'fn', 'in_code' => 1, },
                  'some' => {'in_code' => 0},
                  'code' => {'in_code' => 1}};

If name is not set, it is set to the index name.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.4.4 Texinfo Parser options

Setting these options is the same as seeing some Texinfo constructs in the document.

aliases

A hash reference. The key is a command name, the value is the alias, as could be set by @alias.

clickstyle

A string, the command name associated with @clickstyle.

documentlanguage

A string corresponding to a document language set by @documentlanguage.

INPUT_ENCODING_NAME

INPUT_PERL_ENCODING

INPUT_ENCODING_NAME string is the encoding name as set by @documentencoding. INPUT_PERL_ENCODING string is a corresponding perl encoding name. In general those two strings should be set simultaneously.

indices

If it is a hash reference, the keys are index names, the values are index prefix hash references. The index prefix hash reference values are prefix, the value is set if the corresponding index entries should be formatted as if in @code. An example is as indices_information.

If it is an array reference, it is a list of index names, as if they were entered as

  @defindex name
kbdinputstyle

A string, the @kbdinputstyle style.

labels

A hash reference. Keys are normalized node names as described in the HTML Xref node in the Texinfo manual. Instead of a node, it may also be a float label or an anchor name. The value is the corresponding @-command element in the tree.

macros

The associated hash reference has as keys user-defined macro names. The value is the reference on a macro definition element as obtained by the Parser when parsing a @macro. For example

  @macro mymacro{arg}
  coucou \arg\ after arg
  @end macro

Is associated to a macro definition element

  {'cmdname' => 'macro',
   'args' => [{'text' => 'mymacro', 'type' => 'macro_name'},
              {'text' => 'arg', 'type' => 'macro_arg}],
   'contents' => [{'text' => "coucou \arg\ after arg\n", 'type' => 'raw'}],
   'extra' => {'arg_line' => " mymacro{arg}\n", }}

= item merged_indices

The associated hash reference holds merged indices information, each key is merged in the value. Same as setting @synindex or syncodeindex.

sections_level

Modifier of the sections level. Same as calling @lowersections or @raisesections.

values

A hash reference. Keys are names, values are the corresponding values. Same as values set by @set.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.5 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 containers (hereafter called containers) 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 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

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.5.1 Element keys

cmdname

The command name of @-command elements.

text

The text fragment of text elements.

type

The type of the element. For @verb it is the delimiter. But otherwise it is the type of element considered as a container. Frequent types encountered are paragraph for a paragraph container, brace_command_arg for the container holding the brace @-commands contents, misc_line_arg and block_line_arg contain the arguments appearing on the line of @-commands. Text fragments may have a type to give an information of the kind of text fragment, for example empty_spaces_before_argument is associated to spaces after a brace opening and before the argument. Many @-commands elements don’t have a type associated.

args

Arguments in braces or on @-command line, and the elements of a menu entry.

contents

The Texinfo appearing in the element. For block commands, other containers, @node and sectioning commands.

parent

The parent element.

line_nr

An hash reference corresponding to information on the location of the element in the Texinfo input manual. It should only be available for @-command elements, and only for @-commands that are considered to be complex enough that the location in the document is needed, for example to prepare an error message.

The keys of the line number hash references are

line_nr

The line number of the @-command.

file_name

The file name where @-command appeared.

macro

The user macro name the @-command is expanded from.

extra

A hash reference holding any additional information. See Information available in the extra key.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.5.2 Element types


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.5.2.1 Types for command elements

Some types can be associated with @-commands (in addition to the element being described by cmdname), although usually there will be no type at all. As said above, for @verb the type is the delimiter. For a @value command that is not expanded because there is no corresponding value set, the type is the value argument string.

The following are the other possible values of type for tree elements for @-commands.

def_line

This type may be associated with a definition command with a x form, like @defunx, @defvrx. For the form without x, the associated def_line is the first contents element. It is described in more details below.

command_as_argument

This is the type of a command given in argument of @itemize, @table, @vtable or @ftable. For example in

 @itemize @bullet
 @item item
 @end itemize

the element corresponding with bullet has the following keys:

  'cmdname' => 'bullet'
  'type' => 'command_as_argument'

The parent @-command has an entry in extra for the command_as_argument element:

  'cmdname' => 'itemize'
  'extra => {'command_as_argument' => $command_element_as_argument}
index_entry_command

This is the type of index entry command like @cindex, and, more importantly user-defined index entry commands. So for example if there is

 @defindex foo
  ...

 @fooindex index entry

the @fooindex @-command element will have the index_entry_command type.

following_arg

This type is set for non-alphabetic accent @-commands that don’t use braces but instead have their argument right after them, as

  @~n
space_command_arg

This type is set for accent @-commands that don’t use brace but instead have their argument after some space, as

  @ringaccent A
definfoenclose_command

This type is set for an @-command that is redefined by @definfoenclose. The beginning is in {'extra'}->{'begin'} and the end in {'extra'}->{'end'}.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.5.2.2 Types for text elements

The text elements may have the following types (or may have no type at all):

empty_line

An empty line (possibly containing whitespace characters only).

empty_line_after_command

empty_spaces_after_command

The text is spaces for empty_spaces_after_command or spaces followed by a newline for empty_line_after_command, appearing after an @-command that takes an argument on the line or a block @-command.

empty_spaces_before_argument

The text is spaces appearing after an opening brace or after a comma separating a command’s arguments.

spaces_at_end

Space at the end of an argument to a line command, at the end of an comma-separated argument for some brace commands, or at the end of bracketed content on a @multitable line or definition line.

space_at_end_block_command

Space at the end of a block @-command line.

empty_spaces_after_close_brace

Spaces appearing after a closing brace, for some rare commands for which this space should be ignorable (like @caption).

empty_spaces_before_paragraph

Space appearing before a paragraph beginning.

raw

Text in an environment where it should be kept as is (in @verbatim, @verb, @html, @macro body).

last_raw_newline

The last end of line in a raw block (except for @verbatim).

preamble_text

Text appearing before real content, including the \input texinfo.tex.

space_at_end_menu_node

after_description_line

Space after a node in the menu entry, when there is no description, and space appearing after the description line.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.5.2.3 Types of container elements

The other types of element are the following. These are containers with other elements appearing in their contents.

text_root

document_root

root_line

These types correspond to document roots. text_root is the document root when there is no @node or sectioning command. When such a command appears, a new root container is used, document_root, and text_root becomes the first element in the contents of document_root. root_line is the type of the root tree when parsing Texinfo line fragments using parse_texi_line.

preamble

This container holds the text appearing before the first content, including the \input texinfo.tex line and following blank lines.

preamble_before_setfilename

This container holds everything that appears before @setfilename if IGNORE_BEFORE_SETFILENAME parser option is set.

paragraph

A paragraph. The contents of a paragraph (like other container elements for Texinfo content) are elements representing the contents of the paragraph in the order they occur, such as simple text elements without a cmdname or type, or @-command elements for commands appearing in the paragraph.

preformatted

Texinfo code within a format that is not filled. Happens within some block commands like @example, but also in menu (in menu descriptions, menu comments...).

brace_command_arg

brace_command_context

misc_line_arg

block_line_arg

Those containers occur within the args array of @-commands taking an argument. brace_command_arg is used for the arguments to commands taking arguments surrounded by braces (and in some cases separated by commas). brace_command_context is used for @-commands with braces that start a new context (@footnote, @caption, @math).

misc_line_arg is used for commands that take the texinfo code on the rest of the line as their argument (for example (@settitle, @node, @section and similar). block_line_arg is similar but is used for commands that start a new block (which is to be ended with @end).

For example

 @code{in code}

leads to

 {'cmdname' => 'code',
  'args' => [{'type' => 'brace_command_arg',
              'contents' => [{'text' => 'in code'}]}]}
misc_arg

Used for the arguments to some special line commands whose arguments aren’t subject to the usual macro expansion. For example @set, @clickstyle, @unmacro, @comment. The argument is associated to the text key.

menu_entry

menu_entry_leading_text

menu_entry_name

menu_entry_separator

menu_entry_node

menu_entry_description

A menu_entry holds a full menu entry, like

  * node::    description.

The different elements of the menu entry are directly in the menu_entry args array reference.

menu_entry_leading_text holds the star and following spaces. menu_entry_name is the menu entry name (if present), menu_entry_node corresponds to the node in the menu entry, menu_entry_separator holds the text after the node and before the description, in most cases :: . Lastly, menu_entry_description is for the description.

menu_comment

The menu_comment container holds what is between menu entries in menus. For example in

  @menu
  Menu title

  * entry::

  Between entries
  * other::
  @end menu

Both

  Menu title

and

  Between entries

will be in menu_comment.

macro_name

macro_arg

Taken from @macro definition and put in the args key array of the macro, macro_name is the type of the text fragment corresponding to the macro name, macro_arg is the type of the text fragments correponding to macro formal arguments.

before_item

A container for content before the first @item of block @-commands with items (@table, @multitable, @enumerate...).

table_entry

table_term

table_item

inter_item

Those containers appear in @table, @ftable and @vtable. A table_entry container contains an entire row of the table. It contains a table_term container, which holds all the @item and @itemx lines. This is followed by a table_item container, which holds the content that is to go into the second column of the table.

If there is any content before an @itemx (normally only comments, empty lines or maybe index entries are allowed), it will be in a container with type inter_item.

def_line

def_item

inter_def_item

The def_line type is either associated with a container within a definition command, or is the type of a definition command with a x form, like @deffnx. It holds the definition line arguments. The container with type def_item holds the definition text content. Content appearing before a definition command with a x form is in an inter_def_item container.

multitable_head

multitable_body

row

In @multitable, a multitable_head container contains all the rows with @headitem, while multitable_body contains the rows associated with @item. A row container contains the @item and @<tab> forming a row.

bracketed

This a special type containing content in brackets in the context where they are valid, in @math.

bracketed_def_content

Content in brackets on definition command lines.

bracketed_multitable_prototype

row_prototype

On @multitable line, content in brackets is in bracketed_multitable_prototype, text not in brackets is in row_prototype.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.5.3 Information available in the extra key


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.5.3.1 Extra keys available for more than one @-command

block_command_line_contents

brace_command_contents

An array associated with block @-commands or @-commands with braces taking more than one argument or with simple text content (@anchor, @titlefont, @dmn). Each of the elements of the array is either undef, if there is no argument at that place, or an array reference holding the argument contents.

misc_content

The contents of an @-command taking regular Texinfo code as argument, like @settitle or @exdent.

end_command

The @end associated to the block @-command.

missing_argument

Set for some @-commands with line arguments and a missing argument.

invalid_nesting

Set if the @-command appears in a context it shouldn’t appear in, like a block @-command on sectioning @-command line.

arg_line

The string correspond to the line after the @-command for @-commands that have special arguments on their line, and for @macro line.

text_arg

The string correspond to the line after the @-command for @-commands that have an argument interpreted as simple text, like @setfilename, @end or @documentencoding.

index_entry

The index entry information (described in index_entries in details) is associated to @-commands that have an associated index entry.

misc_args

An array holding strings, the arguments of @-commands taking simple textual arguments as arguments, like @everyheadingmarks, @frenchspacing, @alias, @synindex, @columnfractions. Also filled for @set, @clickstyle, @unmacro or @comment arguments.

spaces_after_command

For @-commands followed by spaces, a reference to the corresponding text element.

spaces_before_argument

For @-commands with opening brace followed by spaces held in a empty_spaces_before_argument element, a reference to that element.

spaces

For accent commands acting on one letter only, like @ringaccent appearing like

 @ringaccent A

there is a spaces key which holds the spaces appearing between the command and the argument.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.5.3.2 Extra keys specific of certain @-commands or containers

@macro

invalid_syntax is set if there was an error on the @macro line. arg_line holds the line after @macro.

@node

The arguments are in the nodes_manuals array. Each of the entries is a hash with a node_content key for an array holding the corresponding content, a manual_content key if there is an associated external manual name, and a normalized key for the normalized label, built as specified in the Texinfo manual in the HTML Xref node.

An associated_section key holds the tree element of the sectioning command that follows the node.

@part

The next sectioning command is in part_associated_section.

sectioning command

The node preceding the command is in associated_node. The part preceding the command is in associated_part. If the level of the document was modified by @raisections or @lowersections, the differential level is in sections_level.

@float

@listoffloats

If float has a second argument, and for @listoffloats argument there is a type key which is also a hash reference, with two keys. content is an array holding the associated contents, normalized holds the normalized float type.

caption and shortcaption holds the corresponding tree elements for float. The @caption or @shortcaption have the float tree element stored in float.

@float

@anchor

@-commands that are targets for cross-references have a normalized key for the normalized label, built as specified in the Texinfo manual in the HTML Xref node. There is also a node_content key for an array holding the corresponding content.

@anchor also has region set to the special region name if in a special region (@copying, @titlepage).

@ref

@xref

@pxref

@inforef

The node_argument entry holds a parsed node entry, like the one appearing in the nodes_manuals array for @node.

@abbr

@acronym

The first argument normalized is in normalized.

definition command

def_command holds the command name, without x if it is an x form of a definition command. original_def_cmdname is the original def command.

If it is an x form, it has not_after_command set if not appearing after the definition command without x.

def_line

The def_arg extra key holds an array reference corresponding to the parsed definition line argument. Each of the elements of the array is a two-element array reference. The first element is the type, which could be spaces for a space, types specific of the definition, like category, name, class, type, and, at the end, a mix of arg, typearg, delimiter depending on the definition. The second element is a hash reference holding the content of the type.

The def_parsed_hash hash reference has as key the type specific of the definition, and as value the corresponding content tree.

@multitable

The key max_columns holds the maximal number of columns. If there are prototypes on the line they are in the array associated with prototypes. If there is a @columnfractions as argument, then the columnfractions key is associated with the array of columnfractions arguments, holding all the column fractions.

@enumerate

The extra key enumerate_specification contains the enumerate argument.

@itemize

@table

@vtable

@ftable

The command_as_argument extra key points to the @-command on as argument on the @-command line.

paragraph

The indent or noindent key value is set if the corresponding @-commands are associated with that paragraph.

@item in @enumerate or @itemize

The item_number extra key holds the number of this item.

@item and @tab in @multitable

The cell_number index key holds the index of the column of the cell.

row

The row_number index key holds the index of the row in the @multitable.

@author

If in a @titlepage, the titlepage is in titlepage, if in @quotation or @smallquotation, the corresponding tree element is in quotation.

The author tree element is in the author array of the @titlepage or the @quotation or @smallquotation it is associated with.

@ifclear

@ifset

The original line is in line.

@end

The textual argument is in command_argument. The corresponding @-command is in command.

@documentencoding

The argument, normalized is in input_encoding_name if it is recognized. The corresponding perl encoding name is in input_perl_encoding.

@click

In clickstyle there is the current clickstyle command.

@kbd

code is set depending on the context and @kbdinputstyle.

definfoenclose defined commands

begin holds the string beginning the definfoenclose, end holds the string ending the definfoenclose.

menu_entry

The menu_entry_description and menu_entry_name keys are associated with the corresponding tree elements. The menu_entry_node value is a hash with information about the parsed node entry; its keys are the same as those appearing in the elements of the nodes_manuals array for @node.

empty_line_after_command

The corresponding command is in command.

@inlinefmt

@inlineraw

@inlinefmtifelse

@inlineifclear

@inlineifset

The first argument is in format. If an argument has been determined as being expanded by the Parser, the index of this argument is in expand_index. Index numbering begins at 0, but the first argument is always the format or flag name, so, if set, it should be 1 or 2 for @inlinefmtifelse, and 1 for other commands.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.5.4 Other information set by the parser

The parser creates an array of nodes and stores this in the nodes key of the parser object.

Each element in the tree corresponding to a node contaning a menu has a menus key which refers to an array of references to menu elements occuring in the node.

These are both used by the Texinfo::Structuring module.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.6 SEE ALSO

Texinfo manual


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.7 AUTHOR

Patrice Dumas, <pertusus@free.fr>


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.8 COPYRIGHT AND LICENSE

Copyright 2010, 2011, 2012, 2013, 2014, 2015 Free Software Foundation, Inc.

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.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3 Texinfo::Structuring


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.1 NAME

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


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2 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_by_letter sort_indices elements_directions
    elements_file_directions);
  # $tree is a Texinfo document tree.  $parser is a Texinfo::Parser object.
  my $sections_root = sectioning_structure ($parser, $tree);
  my $top_node = nodes_tree($parser);
  number_floats($parser->floats_information());
  associate_internal_references($parser);
  my $elements;
  if ($split_at_nodes) {
    $elements = split_by_node($tree);
  } else {
    $elements = split_by_section($tree);
  }
  split_pages($elements, $split);
  elements_directions($parser, $elements);
  elements_file_directions($parser, $elements);

  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_by_letter($parser,
                                       $merged_index_entries, $index_names);
  } else {
    $index_entries_sorted = sort_indices($parser, $merged_index_entries,
                                         $index_names);
  }
  
  

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.3 DESCRIPTION

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

It is also possible to group the top-level contents of the tree, which consist in nodes and sectioning commands into 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 correspond 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 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 or sort_indices_by_letter to sort by letters.

Other miscellaneous methods include 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 that completes the node menus based on the sectioning tree.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.4 METHODS

No method is exported in the default case.

Most of those function references takes a Texinfo::Parser object as argument, see NAME.

$sections_root = sectioning_structure ($parser, $tree)

This function goes through the tree and gather information on the document structure for sectioning commands. It returns the root of the sectioning commands tree.

For section elements, it sets:

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.

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.

my $top_node = nodes_tree($parser)

Goes through menu and nodes and set directions. Returns the top node.

This functions sets:

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.

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 of the float tree elements.

associate_internal_references($parser)

Verify that internal references (@ref and similar without fourth of fifth argument) have an associated node, anchor or float. Set the label key in the extra hash of the reference tree element to the associated labeled tree element.

warn_non_empty_parts($parser)

Register a warning in $parser for each @part that is not empty.

$elements = split_by_node($tree)

Returns a reference array of elements 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 elements.

Elements are regular tree items with type element, the associated nodes and sectioning tree items are in the array associated with the contents key. They have directions, namely element_next and element_prev pointing to the previous and the next element.

In the extra hash they have

no_node

A special case, if there are no nodes in the document, the value is set.

node

element_command

The node command associated with the element.

section

The sectioning command associated with the element node.

$elements = split_by_section($tree)

Similarly with split_by_node, returns an array of elements. This time, lone nodes are associated with the previous sections and lone sections makes up an element.

The extra hash keys set are the same, except that element_command is the sectioning command associated with the element, and no_node is replaced by no_section.

$pages = split_pages($elements, $split)

The elements from the array reference argument have an extra first_in_page value set to the first element on the unit, and based on the value of $split. The possible values for $split are

chapter

The elements are split at chapter or other toplevel sectioning elements.

node

Each element has its own page.

section

The elements are split at sectioning commands below chapter.

value evaluating to false

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

elements_directions($parser, $elements)

Directions are set up for the elements in the array reference given in argument. The corresponding hash reference is in {'extra'}->{'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.

FastForward

The next top level section element.

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

elements_file_directions($parser, $elements)

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

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

$merged_entries = merge_indices($index_names)

Using informations 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.

$index_entries_sorted = sort_indices_by_letter($parser, $merged_index_entries, $index_names)

$index_entries_sorted = sort_indices($parser, $merged_index_entries, $index_names)

These functions first sets a plain text key for each index entry, used for sorting. In both cases, a hash reference with index names as keys 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 indes entries is associated with the index name.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.5 SEE ALSO

Texinfo manual, NAME.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.6 AUTHOR

Patrice Dumas, <pertusus@free.fr>


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.7 COPYRIGHT AND LICENSE

Copyright 2010, 2011, 2012 Free Software Foundation, Inc.

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.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4 Texinfo::Report


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.1 NAME

Texinfo::Report - Error storing and string translations for Texinfo modules


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.2 SYNOPSIS

  @ISA = qw(Texinfo::Report);

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

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

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.3 DESCRIPTION

The Texinfo::Report module helps with string translations and error handling. It is used by the Texinfo modules Texinfo::Parser and Texinfo::Convert::Converter. To use this module, the usual way is to inherit Texinfo::Report methods and initialize the Texinfo::Report variables for a $converter object. This is done by calling Texinfo::Report::new() on the $converter object. This is done by Texinfo::Convert::Converter, for instance, so every module that inherits Texinfo::Convert::Converter can automatically use the Texinfo::Report methods in an object-oriented way.

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


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.4 METHODS

No method is exported in the default case.

The new method initializes Texinfo::Report related fields:

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

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

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

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.

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

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 the information in the $converter to know the encoding and documentlanguage. More precisely, $converter->{'encoding_name'}, $converter->{'perl_encoding'} and $converter->get_conf('documentlanguage') are used.

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

The errors collected are available through the errors method, the other methods allow registering errors and warnings.

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

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.

$converter->line_warn($text, $line_nr)

$converter->line_error($text, $line_nr)

Register a warning or an error. The $text is the text of the error or warning. The optional $line_nr holds the information on the error or warning location. It is associated with the line_nr key of Texinfo tree elements as described in Texinfo::Parser line_nr for the @-commands. The $line_nr structure is described in (error_warnings_list_error_count__errors_converter)errors above.

$converter->document_warn($text)

$converter->document_error($text)

Register a document-wide error or warning. $text is the error or warning message.

$converter->file_line_warn($text, $file, $line_nr)

Register the warning message $text for file $file, with, optionally the line $line_nr in the file.

$converter->file_line_error($text, $file, $line_nr)

Register the error message $text for file $file, with, optionally the line $line_nr in the file.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.5 AUTHOR

Patrice Dumas, <pertusus@free.fr>


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.6 COPYRIGHT AND LICENSE

Copyright 2010, 2011, 2012 Free Software Foundation, Inc.

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.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5 Texinfo::Encoding


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.1 NAME

Texinfo::Encoding - Encodings and encoding aliases


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.2 SYNOPSIS

  use Texinfo::Encoding qw(encoding_alias);

  my ($canonical_texinfo_encoding, $perl_encoding, 
      $canonical_output_encoding) = encoding_alias($encoding);

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.3 DESCRIPTION

Texinfo::Encoding takes care of encoding definition and aliasing.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.4 METHODS

($canonical_texinfo_encoding, $perl_encoding, $canonical_output_encoding) = encoding_alias($encoding)

Taking an encoding name as argument, the function returns the corresponding canonical Texinfo encoding $canonical_texinfo_encoding as described in the Texinfo manual (or undef), an encoding name suitable for perl $perl_encoding, and an encoding name suitable for most output formaats, especially HTML, $canonical_output_encoding.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.5 AUTHOR

Patrice Dumas, <pertusus@free.fr>


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.6 COPYRIGHT AND LICENSE

Copyright 2010, 2011, 2012 Free Software Foundation, Inc.

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.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6 Texinfo::Convert::NodeNameNormalization


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.1 NAME

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


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.3 DESCRIPTION

Texinfo::Convert::NodeNameNormalization allows to normalize node names, with normalize_node following the specification described in the Texinfo manual for HTML Xref. 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, floats and anchor names normalization, but also float types @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.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.4 METHODS

$normalized = normalize_node($tree)

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

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.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.5 AUTHOR

Patrice Dumas, <pertusus@free.fr>


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.6 COPYRIGHT AND LICENSE

Copyright 2010, 2011, 2012 Free Software Foundation, Inc.

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.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7 Texinfo::Convert::Text


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7.1 NAME

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


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7.2 SYNOPSIS

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

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

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

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7.3 DESCRIPTION

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


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7.4 METHODS

$result = convert($tree, $options)

Convert a Texinfo tree to simple text. $options is a hash reference of options. The converter is very simple, and has 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 corresponds to the --enable-encoding option, or the ENABLE_ENCODING customization variable.

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 NAME objet. See also NAME.

expanded_formats_hash

A reference on a hash. The keys should be format names (like html, tex), and if thecorresponding 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 in 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.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7.5 AUTHOR

Patrice Dumas, <pertusus@free.fr>


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7.6 COPYRIGHT AND LICENSE

Copyright 2010, 2011, 2012 Free Software Foundation, Inc.

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.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

8 Texinfo::Convert::Texinfo


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

8.1 NAME

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


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

8.2 SYNOPSIS

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

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

8.3 DESCRIPTION

Texinfo::Convert::Texinfo converts a Texinfo tree (described in NAME) to Texinfo code. If the Texinfo tree results from parsing some Texinfo document, The converted Texinfo code should be exactly the same as the initial document, except that user defined @-macros and @value are expanded, and some invalid code is discarded.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

8.4 METHODS

$texinfo_text = convert($tree)

Converts the Texinfo tree $tree to Texinfo code.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

8.5 AUTHOR

Patrice Dumas, <pertusus@free.fr>


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

8.6 COPYRIGHT AND LICENSE

Copyright 2010, 2011, 2012 Free Software Foundation, Inc.

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.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

9 Texinfo::Convert::Converter


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

9.1 NAME

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


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

9.2 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 converter_global_commands($) {
    return ('documentlanguage', documentencoding', 'paragraphindent');
  }

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

  # end of Texinfo::Convert::MyConverter

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

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

9.3 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. Three are optional, converter_defaults, converter_initialize and converter_global_commands and used for initialization, to give Texinfo::Convert::Converter some informations.

The convert_tree method is more or less mandatory and should convert portions of Texinfo tree. The output and convert are not required, but customarily used by converters as entry points for conversion to a file with headers and so on, or conversion of a whole Texinfo tree.

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 simplistic, while Texinfo::Convert::DocBook is a real converter that is also not too complex.

NAME, NAME and NAME document modules or additional function that may be useful for backends, while the parsed Texinfo tree is described in NAME.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

9.4 METHODS


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

9.4.1 Initialization

A module subclassing Texinfo::Convert::Converter is created by calling the converter method that should be inherited from Texinfo::Convert::Converter.

$converter = MyConverter->converter($options)

The $options hash reference holds options for the converter. In this option hash reference a parser object may be associated with the parser key. The other options should be configuration options described in the Texinfo manual. Those options, when appropriate, override the document content.

The converter function returns a converter object (a blessed hash reference) after checking the options and performing some initializations, especially when a parser is given among the options. The converter is also initialized as a NAME.

To help with these initializations, the modules can define three methods:

%defaults = $converter->converter_defaults($options)

The converter can provide a defaults hash for configuration options. The $options hash reference holds options for the converter.

@global_commands = $converter->converter_global_commands()

The list returned is the list of Texinfo global commands (like @paragraphindent, @documentlanguage...) that are relevant for the converter.

converter_initialize

This method is called at the end of the converter initialization.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

9.4.2 Helper methods

Texinfo::Convert::Converter provides methods that may be useful for every converter:

$converter->get_conf($option_string)

Returns the value of the Texinfo configuration option $option_string.

$converter->set_conf($option_string, $value)

Set the Texinfo configuration option $option_string to $value if not set as a converter option.

$converter->force_conf($option_string, $value)

Set the Texinfo configuration option $option_string to $value. This should rarely be used, but the purpose of this method is to be able to revert a configuration that is always wrong for a given output format, like the splitting for example.

$result = $converter->convert_document_sections($root, $file_handler)

This method splits the $root Texinfo tree at sections and calls convert_tree on the elements. If the optional $file_handler is given in argument, the result are output in $file_handler, otherwise the resulting string is returned.

$result = $converter->convert_accents($accent_command, \&format_accents, $in_upper_case)

$accent_command is an accent command, which may have other accent commands nested. The function returns the accents formatted either as encoded letters, or formatted using \&format_accents. If $in_upper_case is set, the result should be uppercased.

Other Texinfo::Convert::Converter methods target conversion to XML:

$protected_text = $converter->xml_protect_text($text)

Protect special XML characters (&, <, >, ") of $text.

$comment = $converter->xml_comment($text)

Returns an XML comment for $text.

$result = xml_accent($text, $accent_command, $in_upper_case, $use_numeric_entities)

$text is the text appearing within an accent command. $accent_command should be a Texinfo tree element corresponding to an accent command taking an argument. $in_upper_case is optional, and, if set, the text is put in upper case. The function returns the accented letter as XML entity if possible. $use_numeric_entities is also optional, and, if set, and there is no XML entity, the numerical entity corresponding to Unicode points is preferred to an ASCII transliteration.

$result = $converter->xml_accents($accent_command, $in_upper_case)

$accent_command is an accent command, which may have other accent commands nested. If $in_upper_case is set, the result should be upper cased. The function returns the accents formatted as XML.

Finally, there is:

$result = $converter->output_internal_links()

At this level, the method just returns undef. It is used in the HTML output, following the --internal-links option of texi2any/makeinfo specification.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

9.5 SEE ALSO

NAME, NAME, NAME and NAME.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

9.6 AUTHOR

Patrice Dumas, <pertusus@free.fr>


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

9.7 COPYRIGHT AND LICENSE

Copyright 2011, 2012, 2013, 2014, 2015 Free Software Foundation, Inc.

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.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

9.8 POD ERRORS

Hey! The above document had some coding errors, which are explained below:

Around line 1810:

’=item’ outside of any ’=over’


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

10 Texinfo::Convert::Unicode


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

10.1 NAME

Texinfo::Convert::Unicode - Handle conversion to Unicode


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

10.2 SYNOPSIS

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

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

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

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

10.3 DESCRIPTION

Texinfo::Convert::Unicode provides methods that deals with unicode for converters. Unicode is important, because it is used internally in perl for strings, therefore if converted to Unicode, a string could be output in other encodings as well when writting out the converted documents.

When an encoding is given as argument of a method of the module, the accented letters should only be converted to unicode if it is known that it will be possible to convert the unicode points to encoded charactes in the encoding character set.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

10.4 METHODS

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

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

$converter is a converter object. It may be undef if there is no need of converter object in $format_accent ($format_accent described below). $text is the text appearing within nested accent commands. $stack is an array reference holding the nested accents texinfo element trees. For example, $text could be the formatted content and $stack the stack returned by Texinfo::Common::find_innermost_accent_contents. $encoding is the encoding the accented characters should be encoded to. If $encoding not set the $result is set to undef. $format_accent is a function reference that is used to format the accent commands if there is no encoded character available for the encoding $encoding at some point of the conversion of the $stack. Last, if $set_case is positive, the result is upper-cased, while if it is negative, the result is lower-cased.

$result = unicode_text ($text, $in_code)

Return $text with characters encoded in unicode. If $in_code is set, the text is considered to be in code style.

$result = unicode_for_brace_no_arg_command($command_name, $encoding)

Return the unicode representing a command with brace and no argument $command_name (like @bullet{}, @aa{} or @guilsinglleft{}), or undef if there is no available encoded character for encoding $encoding.

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


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

10.5 AUTHOR

Patrice Dumas, <pertusus@free.fr>


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

10.6 COPYRIGHT AND LICENSE

Copyright 2010, 2011, 2012 Free Software Foundation, Inc.

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.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

11 Texinfo::Convert::Info


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

11.1 NAME

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


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

11.2 SYNOPSIS

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

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

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

11.3 DESCRIPTION

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


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

11.4 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 should be configuration options described in the Texinfo manual. Those options, when appropriate, override the document content.

See NAME for more informations.

$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 or tree portion 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.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

11.5 AUTHOR

Patrice Dumas, <pertusus@free.fr>


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

11.6 COPYRIGHT AND LICENSE

Copyright 2015 Free Software Foundation, Inc.

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.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

12 Texinfo::Convert::DocBook


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

12.1 NAME

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


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

12.2 SYNOPSIS

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

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

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

12.3 DESCRIPTION

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


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

12.4 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 should be configuration options described in the Texinfo manual. Those options, when appropriate, override the document content.

See NAME for more informations.

$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 or tree portion 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.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

12.5 AUTHOR

Patrice Dumas, <pertusus@free.fr>


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

12.6 COPYRIGHT AND LICENSE

Copyright 2015 Free Software Foundation, Inc.

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.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

13 Texinfo::Convert::TexinfoXML


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

13.1 NAME

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


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

13.2 SYNOPSIS

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

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

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

13.3 DESCRIPTION

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


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

13.4 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 should be configuration options described in the Texinfo manual. Those options, when appropriate, override the document content.

See NAME for more informations.

$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 or tree portion 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.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

13.5 AUTHOR

Patrice Dumas, <pertusus@free.fr>


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

13.6 COPYRIGHT AND LICENSE

Copyright 2015 Free Software Foundation, Inc.

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.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

14 Texinfo::Convert::Plaintext


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

14.1 NAME

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


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

14.2 SYNOPSIS

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

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

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

14.3 DESCRIPTION

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


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

14.4 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 should be configuration options described in the Texinfo manual. Those options, when appropriate, override the document content.

See NAME for more informations.

$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 or tree portion 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.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

14.5 AUTHOR

Patrice Dumas, <pertusus@free.fr>


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

14.6 COPYRIGHT AND LICENSE

Copyright 2015 Free Software Foundation, Inc.

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.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

15 Texinfo::Convert::HTML


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

15.1 NAME

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


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

15.2 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

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

15.3 DESCRIPTION

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


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

15.4 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 should be configuration options described in the Texinfo manual. Those options, when appropriate, override the document content.

See NAME for more informations.

$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 or tree portion 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/makeinfo specification. This is only supported in (and relevant for) HTML.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

15.5 AUTHOR

Patrice Dumas, <pertusus@free.fr>


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

15.6 COPYRIGHT AND LICENSE

Copyright 2015 Free Software Foundation, Inc.

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.


[Top] [Contents] [Index] [ ? ]

Table of Contents


[Top] [Contents] [Index] [ ? ]

About This Document

This document was generated on September 14, 2017 using texi2html.

The buttons in the navigation panels have the following meaning:

Button Name Go to From 1.2.3 go to
[ << ] FastBack Beginning of this chapter or previous chapter 1
[ < ] Back Previous section in reading order 1.2.2
[ Up ] Up Up section 1.2
[ > ] Forward Next section in reading order 1.2.4
[ >> ] FastForward Next chapter 2
[Top] Top Cover (top) of document  
[Contents] Contents Table of contents  
[Index] Index Index  
[ ? ] About About (help)  

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:


This document was generated on September 14, 2017 using texi2html.