@node Texinfo@asis{::}Common
@chapter Texinfo::Common

@node Texinfo@asis{::}Common NAME
@section Texinfo::Common NAME

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

@node Texinfo@asis{::}Common SYNOPSIS
@section Texinfo::Common SYNOPSIS

@verbatim
  use Texinfo::Common;


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

@node Texinfo@asis{::}Common NOTES
@section Texinfo::Common NOTES

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

@node Texinfo@asis{::}Common DESCRIPTION
@section Texinfo::Common DESCRIPTION

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

@node Texinfo@asis{::}Common MISC INFORMATION
@section MISC INFORMATION

Hashes are defined as @code{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

@table @asis
@item %texinfo_output_formats
@anchor{Texinfo@asis{::}Common %texinfo_output_formats}
@cindex @code{%texinfo_output_formats}

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

@end table

@node Texinfo@asis{::}Common @@-COMMAND INFORMATION
@section @@-COMMAND INFORMATION

Hashes are defined as @code{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:

@table @asis
@item %all_commands
@anchor{Texinfo@asis{::}Common %all_commands}
@cindex @code{%all_commands}

All the @@-commands.

@item %def_aliases
@anchor{Texinfo@asis{::}Common %def_aliases}

@item %def_no_var_arg_commands
@anchor{Texinfo@asis{::}Common %def_no_var_arg_commands}
@cindex @code{%def_aliases}
@cindex @code{%def_no_var_arg_commands}

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

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

@item %nobrace_symbol_text
@anchor{Texinfo@asis{::}Common %nobrace_symbol_text}
@cindex @code{%nobrace_symbol_text}

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

@item %non_formatted_brace_commands
@anchor{Texinfo@asis{::}Common %non_formatted_brace_commands}

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

@item %small_block_associated_command
@anchor{Texinfo@asis{::}Common %small_block_associated_command}
@cindex @code{%small_block_associated_command}

Associate small command like @code{smallexample} to the regular command
@code{example}.

@end table

@node Texinfo@asis{::}Common METHODS
@section Texinfo::Common METHODS

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

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

@table @asis
@item $translated_string = __($msgid)
@anchor{Texinfo@asis{::}Common $translated_string = __($msgid)}

@item $translated_string = __p($msgctxt, $msgid)
@anchor{Texinfo@asis{::}Common $translated_string = __p($msgctxt@comma{} $msgid)}

Returns the @emph{$msgid} string translated in the Texinfo messages text domain.
@code{__p} can be used instead of @code{__} to pass a @emph{$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. @code{__} corresponds to
the @code{gettext} function and @code{__p} to the @code{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 @code{__} or @code{__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 @ref{,,, libintl-perl},
@url{https://www.gnu.org/software/gettext/manual/html_node/gettext.html, @code{gettext} C interface},
@url{https://www.gnu.org/software/gettext/manual/html_node/Perl.html, Perl in GNU Gettext}.
For translation of strings in output, see @ref{Texinfo@asis{::}Translations NAME,, Texinfo::Translations}.

@item collect_commands_in_tree($tree, $commands_list)
@anchor{Texinfo@asis{::}Common collect_commands_in_tree($tree@comma{} $commands_list)}
@cindex @code{collect_commands_in_tree}

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

@item collect_commands_list_in_tree($tree, $commands_list)
@anchor{Texinfo@asis{::}Common collect_commands_list_in_tree($tree@comma{} $commands_list)}
@cindex @code{collect_commands_list_in_tree}

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

@item $encoding_name = element_associated_processing_encoding($element)
@anchor{Texinfo@asis{::}Common $encoding_name = element_associated_processing_encoding($element)}
@cindex @code{element_associated_processing_encoding}

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

@item $result = element_is_inline($element, $check_current)
@anchor{Texinfo@asis{::}Common $result = element_is_inline($element@comma{} $check_current)}
@cindex @code{element_is_inline}

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

@item ($encoded_file_name, $encoding) = encode_file_name($file_name, $input_encoding)
@anchor{Texinfo@asis{::}Common ($encoded_file_name@comma{} $encoding) = encode_file_name($file_name@comma{} $input_encoding)}

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

@item $text = enumerate_item_representation($specification, $number)
@anchor{Texinfo@asis{::}Common $text = enumerate_item_representation($specification@comma{} $number)}
@cindex @code{enumerate_item_representation}

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

@verbatim
  enumerate_item_representation('c', 3)
@end verbatim

is @code{e}.

@item $command = find_parent_root_command($object, $tree_element)
@anchor{Texinfo@asis{::}Common $command = find_parent_root_command($object@comma{} $tree_element)}
@cindex @code{find_parent_root_command}

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

@item $entry_content_element = index_content_element($element, $prefer_reference_element)
@anchor{Texinfo@asis{::}Common $entry_content_element = index_content_element($element@comma{} $prefer_reference_element)}

Return a Texinfo tree element corresponding to the content of the index
entry associated to @emph{$element}.  If @emph{$prefer_reference_element} is set,
prefer an untranslated element.  If the element is an index command like
@code{@@cindex} or an @code{@@ftable} @code{@@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.

@item $result = is_content_empty($tree, $do_not_ignore_index_entries)
@anchor{Texinfo@asis{::}Common $result = is_content_empty($tree@comma{} $do_not_ignore_index_entries)}
@cindex @code{is_content_empty}

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

@item $file = locate_include_file($customization_information, file_path)
@anchor{Texinfo@asis{::}Common $file = locate_include_file($customization_information@comma{} file_path)}
@cindex @code{locate_include_file}

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

@item ($index_entry, $index_info) = lookup_index_entry($index_entry_info, $indices_information)
@anchor{Texinfo@asis{::}Common ($index_entry@comma{} $index_info) = lookup_index_entry($index_entry_info@comma{} $indices_information)}

Returns an @emph{$index_entry} hash based on the @emph{$index_entry_info} and
@emph{$indices_information}.  Also returns the @emph{$index_info} hash with information on
the index associated to the index entry.  @emph{$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 @emph{$index_entry_info}
is an @ref{Texinfo@asis{::}Parser index_entry,, @code{extra} @emph{index_entry}} associated to an element.

The @emph{$index_entry} hash is described in @ref{Texinfo@asis{::}Parser index_entries}.  The
@emph{$index_info} hash is described in L@ref{Texinfo@asis{::}Parser $indices_information = $parser->indices_information(),, @code{Texinfo::Parser::indices_information}}.

@item move_index_entries_after_items_in_tree($tree)
@anchor{Texinfo@asis{::}Common move_index_entries_after_items_in_tree($tree)}
@cindex @code{move_index_entries_after_items_in_tree}

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

@item relate_index_entries_to_table_items_in_tree($tree)
@anchor{Texinfo@asis{::}Common relate_index_entries_to_table_items_in_tree($tree)}
@cindex @code{relate_index_entries_to_table_items_in_tree}

In tables, relate index entries preceding and following an
entry with said item.  Reference one of them in the entry's
@code{entry_associated_element}.

@item $normalized_name = normalize_top_node_name($node_string)
@anchor{Texinfo@asis{::}Common $normalized_name = normalize_top_node_name($node_string)}
@cindex @code{normalize_top_node_name}

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

@item protect_colon_in_tree($tree)
@anchor{Texinfo@asis{::}Common protect_colon_in_tree($tree)}

@item protect_node_after_label_in_tree($tree)
@anchor{Texinfo@asis{::}Common protect_node_after_label_in_tree($tree)}
@cindex @code{protect_colon_in_tree}
@cindex @code{protect_node_after_label_in_tree}

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

@item protect_comma_in_tree($tree)
@anchor{Texinfo@asis{::}Common protect_comma_in_tree($tree)}
@cindex @code{protect_comma_in_tree}

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

@item $contents_result = protect_first_parenthesis($contents)
@anchor{Texinfo@asis{::}Common $contents_result = protect_first_parenthesis($contents)}
@cindex @code{protect_first_parenthesis}

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

@item $level = section_level($section)
@anchor{Texinfo@asis{::}Common $level = section_level($section)}
@cindex @code{section_level}

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

@item $element = set_global_document_command($customization_information, $global_commands_information, $cmdname, $command_location)
@anchor{Texinfo@asis{::}Common $element = set_global_document_command($customization_information@comma{} $global_commands_information@comma{} $cmdname@comma{} $command_location)}
@cindex @code{set_global_document_command}

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

@table @asis
@item last
@anchor{Texinfo@asis{::}Common last}

Set to the last value for the command.

@item preamble
@anchor{Texinfo@asis{::}Common preamble}

Set sequentially to the values in the Texinfo preamble.

@item preamble_or_first
@anchor{Texinfo@asis{::}Common 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 @emph{preamble},
sequentially to the values in the Texinfo preamble.

@end table

The @emph{$element} returned is the last element that was used to set the
customization value, or @code{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.

@item $status = set_informative_command_value($customization_information, $element)
@anchor{Texinfo@asis{::}Common $status = set_informative_command_value($customization_information@comma{} $element)}
@cindex @code{set_informative_command_value}

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

@item set_output_encodings($customization_information, $parser_information)
@anchor{Texinfo@asis{::}Common set_output_encodings($customization_information@comma{} $parser_information)}
@cindex @code{set_output_encodings}

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

@item $split_contents = split_custom_heading_command_contents($contents)
@anchor{Texinfo@asis{::}Common $split_contents = split_custom_heading_command_contents($contents)}
@cindex @code{split_custom_heading_command_contents}

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

@item trim_spaces_comment_from_content($contents)
@anchor{Texinfo@asis{::}Common trim_spaces_comment_from_content($contents)}
@cindex @code{trim_spaces_comment_from_content}

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

@item $status = valid_customization_option($name)
@anchor{Texinfo@asis{::}Common $status = valid_customization_option($name)}
@cindex @code{valid_option}

Return true if the @emph{$name} is a known customization option.

@item $status = valid_tree_transformation($name)
@anchor{Texinfo@asis{::}Common $status = valid_tree_transformation($name)}
@cindex @code{valid_tree_transformation}

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

@end table

@node Texinfo@asis{::}Common SEE ALSO
@section Texinfo::Common SEE ALSO

@ref{Texinfo@asis{::}Parser NAME,, Texinfo::Parser}, @ref{Texinfo@asis{::}Convert@asis{::}Converter NAME,, Texinfo::Convert::Converter} and @ref{Texinfo@asis{::}Report NAME,, Texinfo::Report}.

@node Texinfo@asis{::}Common AUTHOR
@section Texinfo::Common AUTHOR

Patrice Dumas, <pertusus@@free.fr>

@node Texinfo@asis{::}Common COPYRIGHT AND LICENSE
@section 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.