use Texinfo::Common;
my @commands_to_collect = ('math');
my $collected_commands
= Texinfo::Common::collect_commands_in_tree($document_root,
\@commands_to_collect);
my $package_version
= Texinfo::Common::get_build_constant('PACKAGE_AND_VERSION');
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.
Values defined for a Texinfo build independently of any document or
output format are available by calling get_build_constant:
The following build constants are available:
Texinfo package name and versions. Values of build constants without
_CONFIG appended are set by configure. For each variable set by
configure there is another one with _CONFIG appended
to the name set to the same value, to match the name of the macros set in
C. So, for example PACKAGE_VERSION_CONFIG value is the same as
PACKAGE_VERSION, set to the PACKAGE_VERSION value set by configure.
Cannonical output formats that have associated conditionals. In
practice corresponds to format_raw %block_commands plus info
and plaintext.
TODO: undocumented %null_device_file %default_parser_customization_values %multiple_at_command_options %unique_at_command_options %converter_cmdline_options %default_main_program_customization_options %converter_customization_options %document_settable_at_commands %def_map %command_structuring_level %level_to_structuring_command %encoding_name_conversion_map %text_brace_no_arg_commands
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.
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 Locale::Messages,
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::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::Document index_entries. The
$index_info hash is described in Texinfo::Document::indices_information.
Normalize the node name string given in argument, by normalizing Top node case.
Remove first occurence of $element in the array reference $array.
Return the removed element, or undef if not found.
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 parsed document $document->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.
Set OUTPUT_PERL_ENCODING based on OUTPUT_ENCODING_NAME. In general,
OUTPUT_PERL_ENCODING should not be set directly by user-defined code such
that it corresponds to OUTPUT_ENCODING_NAME.
Split the $element contents at @| in at max three parts.
Return an element containing the split parts in contents, or undef if
the $element has no useful content. The input $element
is supposed to be $element->{'args'}->[0]
of %Texinfo::Commands::heading_spec_commands commands such as @everyheading.
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.