Texinfo::Common
***************

Texinfo::Common NAME
====================

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

Texinfo::Common SYNOPSIS
========================

  use Texinfo::Common;

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

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.

Texinfo::Common DESCRIPTION
===========================

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

MISC INFORMATION
================

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

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

%texinfo_output_formats

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

@-COMMAND INFORMATION
=====================

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

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

%all_commands

     All the @-commands.

%brace_code_commands

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

%def_aliases

%def_no_var_arg_commands

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

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

%explained_commands

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

%inline_conditional_commands

%inline_format_commands

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

%nobrace_symbol_text

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

%small_block_associated_command

     Associate small command like smallexample to the regular command example.

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::Parser 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 Texinfo::Convert::Converter 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 (https://www.gnu.org/software/gettext/manual/html_node/gettext.html), Perl in GNU Gettext (https://www.gnu.org/software/gettext/manual/html_node/Perl.html). For translation of strings in output, see Texinfo::Translations.

collect_commands_in_tree($tree, $commands_list)

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

collect_commands_list_in_tree($tree, $commands_list)

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

$result = element_is_inline($element, $check_current)

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

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

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

$text = enumerate_item_representation($specification, $number)

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

       enumerate_item_representation('c', 3)

     is e.

$command = find_parent_root_command($object, $tree_element)

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

$result = is_content_empty($tree, $do_not_ignore_index_entries)

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

$file = locate_include_file($customization_information, file_path)

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

move_index_entries_after_items_in_tree($tree)

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

$normalized_name = normalize_top_node_name($node_string)

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

protect_colon_in_tree($tree)

protect_node_after_label_in_tree($tree)

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

protect_comma_in_tree($tree)

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

$contents_result = protect_first_parenthesis($contents)

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

relate_index_entries_to_table_entries_in_tree($tree)

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

$level = section_level($section)

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

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

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

     last

          Set to the last value for the command.

     preamble

          Set sequentially to the values in the Texinfo preamble.

     preamble_or_first

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

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

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

set_informative_command_value($customization_information, $element)

     Set the Texinfo configuration option corresponding to the tree element $element.  The command associated to the tree element should be a command that sets some information, such as @documentlanguage, @contents or @footnotestyle for example.

set_output_encodings($customization_information, $parser_information)

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

$split_contents = split_custom_heading_command_contents($contents)

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

trim_spaces_comment_from_content($contents)

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

valid_customization_option($name)

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

valid_tree_transformation($name)

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

Texinfo::Common SEE ALSO
========================

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

Texinfo::Common AUTHOR
======================

Patrice Dumas, <pertusus@free.fr>

Texinfo::Common COPYRIGHT AND LICENSE
=====================================

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

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