2 Texinfo::Common

2.1 Texinfo::Common NAME

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

2.2 Texinfo::Common SYNOPSIS

  use Texinfo::Common;

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

2.3 Texinfo::Common NOTES

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

2.4 Texinfo::Common DESCRIPTION

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


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

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


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


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 the @-commands.


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

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


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


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


Associate small command like smallexample to the regular command example.

2.7 Texinfo::Common METHODS

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

The Texinfo tree and Texinfo tree elements used in argument of some functions are documented in TEXINFO TREE. When customization information is needed, an object that defines set_conf and/or get_conf is expected, for example a converter inheriting from Texinfo::Convert::Converter, see Getting and setting customization variables.

$translated_string = __($msgid)
$translated_string = __p($msgctxt, $msgid)

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

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

See (libintl-perl), gettext C interface, Perl in GNU Gettext. For translation of strings in output, see Texinfo::Translations.

collect_commands_in_tree($tree, $commands_list)

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

collect_commands_list_in_tree($tree, $commands_list)

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

$encoding_name = element_associated_processing_encoding($element)

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

$result = element_is_inline($element, $check_current)

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

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

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

$text = enumerate_item_representation($specification, $number)

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

  enumerate_item_representation('c', 3)

is e.

$command = find_parent_root_command($object, $tree_element)

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

$entry_content_element = index_content_element($element, $prefer_reference_element)

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

$result = is_content_empty($tree, $do_not_ignore_index_entries)

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

$file = locate_include_file($customization_information, file_path)

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

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

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

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


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.


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

$normalized_name = normalize_top_node_name($node_string)

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


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


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

$contents_result = protect_first_parenthesis($contents)

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

$level = section_level($section)

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

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

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


Set to the last value for the command.


Set sequentially to the values in the Texinfo preamble.


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

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

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

$status = set_informative_command_value($customization_information, $element)

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

set_output_encodings($customization_information, $parser_information)

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

$split_contents = split_custom_heading_command_contents($contents)

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


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

$status = valid_customization_option($name)

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

$status = valid_tree_transformation($name)

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

2.8 Texinfo::Common SEE ALSO

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

2.9 Texinfo::Common AUTHOR

Patrice Dumas, <pertusus@free.fr>