use Texinfo::Common;
my @commands_to_collect = ('math');
my $collected_commands
= Texinfo::Common::collect_commands_in_tree($document_root,
\@commands_to_collect);
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 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.
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.
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.
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.
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.
Returns the encoding name that can be used for decoding derived from the encoding that was set where $element appeared.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Return numbered level of the tree sectioning element $section, as modified by raise/lowersections.
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.
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.
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 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.
Return true if the $name is a known customization option.
Return true if the $name is a known tree transformation name
that may be passed with TREE_TRANSFORMATIONS to modify a texinfo
tree.
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.