[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
branch master updated: Update POD documentation. Replace configuration b
|
From: |
Patrice Dumas |
|
Subject: |
branch master updated: Update POD documentation. Replace configuration by customization in code |
|
Date: |
Sun, 11 Sep 2022 17:39:12 -0400 |
This is an automated email from the git hooks/post-receive script.
pertusus pushed a commit to branch master
in repository texinfo.
The following commit(s) were added to refs/heads/master by this push:
new e55305e97f Update POD documentation. Replace configuration by
customization in code
e55305e97f is described below
commit e55305e97fb8c1ca00c36646df49dea02f485b8e
Author: Patrice Dumas <pertusus@free.fr>
AuthorDate: Sun Sep 11 23:38:37 2022 +0200
Update POD documentation. Replace configuration by customization in
code
---
tp/Texinfo/Common.pm | 75 +++++-----
tp/Texinfo/Convert/Converter.pm | 204 ++++++++++++++++------------
tp/Texinfo/Convert/DocBook.pm | 12 +-
tp/Texinfo/Convert/HTML.pm | 14 +-
tp/Texinfo/Convert/IXIN.pm | 6 +-
tp/Texinfo/Convert/IXINSXML.pm | 6 -
tp/Texinfo/Convert/Info.pm | 12 +-
tp/Texinfo/Convert/LaTeX.pm | 10 +-
tp/Texinfo/Convert/NodeNameNormalization.pm | 8 +-
tp/Texinfo/Convert/Plaintext.pm | 12 +-
tp/Texinfo/Convert/Texinfo.pm | 2 +-
tp/Texinfo/Convert/TexinfoXML.pm | 14 +-
tp/Texinfo/Convert/Text.pm | 8 +-
tp/Texinfo/Convert/Unicode.pm | 4 +-
tp/Texinfo/Convert/Utils.pm | 20 +--
tp/Texinfo/ParserNonXS.pm | 138 ++++++++++---------
tp/Texinfo/Report.pm | 12 +-
tp/Texinfo/Structuring.pm | 119 ++++++++--------
tp/Texinfo/Transformations.pm | 24 ++--
tp/Texinfo/Translations.pm | 12 +-
tp/maintain/template.pod | 14 +-
util/texinfo.dtd | 2 +-
22 files changed, 398 insertions(+), 330 deletions(-)
diff --git a/tp/Texinfo/Common.pm b/tp/Texinfo/Common.pm
index 49f8f8f1ef..3555ce70d6 100644
--- a/tp/Texinfo/Common.pm
+++ b/tp/Texinfo/Common.pm
@@ -261,7 +261,7 @@ our %default_converter_customization = (
# only used in HTML
'HANDLER_FATAL_ERROR_LEVEL' => 100,
'TEST' => 0,
- 'TEXTCONTENT_COMMENT', => undef, # in textcontent format
+ 'TEXTCONTENT_COMMENT' => undef, # in textcontent format
);
# Some are for all converters, EXTENSION for instance, some for
@@ -1228,7 +1228,7 @@ sub locate_init_file($$$)
sub output_files_open_out($$$;$$)
{
my $self = shift;
- my $configuration_information = shift;
+ my $customization_information = shift;
my $file_path = shift;
my $use_binmode = shift;
my $output_encoding = shift;
@@ -1236,8 +1236,8 @@ sub output_files_open_out($$$;$$)
my $encoding;
if (defined($output_encoding)) {
$encoding = $output_encoding;
- } elsif
(defined($configuration_information->get_conf('OUTPUT_PERL_ENCODING'))) {
- $encoding = $configuration_information->get_conf('OUTPUT_PERL_ENCODING');
+ } elsif
(defined($customization_information->get_conf('OUTPUT_PERL_ENCODING'))) {
+ $encoding = $customization_information->get_conf('OUTPUT_PERL_ENCODING');
}
if ($file_path eq '-') {
@@ -1561,10 +1561,10 @@ sub parse_node_manual($)
# ASCII, as the name of the directory it is located within may contain
# non-ASCII characters.
# Otherwise, the -e operator and similar may not work correctly.
-# TODO Really use configuration_information? Document when the API is final
+# TODO Really use customization_information? Document when the API is final
sub encode_file_name($$;$)
{
- my $configuration_information = shift;
+ my $customization_information = shift;
my $file_name = shift;
my $input_encoding = shift;
@@ -1583,7 +1583,7 @@ sub encode_file_name($$;$)
sub locate_include_file($$)
{
- my $configuration_information = shift;
+ my $customization_information = shift;
my $input_file_path = shift;
my $ignore_include_directories = 0;
@@ -1592,8 +1592,8 @@ sub locate_include_file($$)
= File::Spec->splitpath($input_file_path);
my @directories = File::Spec->splitdir($directories);
- #print STDERR "$configuration_information $input_file_path ".
- # @{$configuration_information->get_conf('INCLUDE_DIRECTORIES')}\n";
+ #print STDERR "$customization_information $input_file_path ".
+ # @{$customization_information->get_conf('INCLUDE_DIRECTORIES')}\n";
# If the path is absolute or begins with . or .., do not search in
# include directories.
if (File::Spec->file_name_is_absolute($input_file_path)) {
@@ -1614,14 +1614,14 @@ sub locate_include_file($$)
$found_file = $input_file_path if (-e $input_file_path and -r
$input_file_path);
} else {
my @dirs;
- if ($configuration_information
- and $configuration_information->get_conf('INCLUDE_DIRECTORIES')) {
- @dirs = @{$configuration_information->get_conf('INCLUDE_DIRECTORIES')};
+ if ($customization_information
+ and $customization_information->get_conf('INCLUDE_DIRECTORIES')) {
+ @dirs = @{$customization_information->get_conf('INCLUDE_DIRECTORIES')};
} else {
# no object with directory list and not an absolute path, never succeed
return undef;
}
- foreach my $include_dir
(@{$configuration_information->get_conf('INCLUDE_DIRECTORIES')}) {
+ foreach my $include_dir
(@{$customization_information->get_conf('INCLUDE_DIRECTORIES')}) {
my ($include_volume, $include_directories, $include_filename)
= File::Spec->splitpath($include_dir, 1);
@@ -1704,7 +1704,7 @@ sub set_global_document_command($$$$)
if ($command_location ne 'last' and $command_location ne 'preamble_or_first'
and $command_location ne 'preamble') {
- warn "BUG: set_global_document_commands: unknown command_location:
$command_location";
+ warn "BUG: set_global_document_command: unknown command_location:
$command_location";
}
my $element;
@@ -1741,18 +1741,18 @@ sub set_global_document_command($$$$)
sub set_output_encodings($$)
{
- my $configuration_information = shift;
+ my $customization_information = shift;
my $parser_information = shift;
- $configuration_information->set_conf('OUTPUT_ENCODING_NAME',
+ $customization_information->set_conf('OUTPUT_ENCODING_NAME',
$parser_information->{'input_encoding_name'})
if ($parser_information->{'input_encoding_name'});
- if (!$configuration_information->get_conf('OUTPUT_PERL_ENCODING')
- and $configuration_information->get_conf('OUTPUT_ENCODING_NAME')) {
+ if (!$customization_information->get_conf('OUTPUT_PERL_ENCODING')
+ and $customization_information->get_conf('OUTPUT_ENCODING_NAME')) {
my $perl_encoding
- =
Encode::resolve_alias($configuration_information->get_conf('OUTPUT_ENCODING_NAME'));
+ =
Encode::resolve_alias($customization_information->get_conf('OUTPUT_ENCODING_NAME'));
if ($perl_encoding) {
- $configuration_information->set_conf('OUTPUT_PERL_ENCODING',
$perl_encoding);
+ $customization_information->set_conf('OUTPUT_PERL_ENCODING',
$perl_encoding);
}
}
}
@@ -2930,7 +2930,7 @@ All the @-commands.
=item %accent_commands
X<C<%accent_commands>>
-Accent @-commands taking an argument, like C<@'> or C<@ringaccent>
+Accent @-commands taking an argument, like C<@'> or C<@ringaccent>,
including C<@dotless> and C<@tieaccent>.
=item %align_commands
@@ -2944,7 +2944,8 @@ X<C<%block_commands>>
Commands delimiting a block with a closing C<@end>. The value
is I<conditional> for C<@if> commands, I<def> for definition
commands like C<@deffn>, I<raw> for @-commands that have no expansion
-of @-commands in their bodies and I<multitable> for C<@multitable>.
+of @-commands in their bodies (C<@macro>, C<@verbatim> and C<@ignore>),
+and I<multitable> for C<@multitable>.
Otherwise it is set to the number of arguments separated by commas
that may appear on the @-command line, or to I<variadic> if there is
an unlimited number of arguments. That means 0 in most cases,
@@ -3105,7 +3106,8 @@ I<style_commands> that have their argument in regular
font, C<@r>.
X<C<%root_commands>>
Commands that are at the root of a Texinfo document, namely
-C<@node> and sectioning commands, except heading commands.
+C<@node> and sectioning commands, except heading commands
+like C<@heading>.
=item %sectioning_heading_commands
X<C<%sectioning_heading_commands>>
@@ -3128,7 +3130,12 @@ C<@cite>, C<@code> or C<@asis>.
=head1 METHODS
-No method is exported in the default case.
+No method is exported in the default case. The Texinfo tree
+and Texinfo tree elements are documented in L<Texinfo::Parser/TEXINFO TREE>.
+When customization information is needed, an object that defines
+C<set_conf> and/or C<get_conf> is expected, for example
+a converter inheriting from C<Texinfo::Convert::Converter>, see
+L<Texinfo::Convert::Converter/Getting and setting customization variables>.
=over
@@ -3169,7 +3176,7 @@ is C<e>.
=item $command = find_parent_root_command($object, $tree_element)
X<C<find_parent_root_command>>
-Find the parent root command of a tree element (sectioning command or node).
+Find the parent root command (sectioning command or node) of a tree element.
The I<$object> argument is optional, its C<global_commands> field is used
to continue through C<@insertcopying> if in a C<@copying>.
@@ -3180,7 +3187,7 @@ Return true if the I<$tree> has content that could be
formatted.
I<$do_not_ignore_index_entries> is optional. If set, index entries
are considered to be formatted.
-=item $file = $converter->locate_include_file($file_path)
+=item $file = locate_include_file($customization_information, file_path)
X<C<locate_include_file>>
Locate I<$file_path>. If I<$file_path> is an absolute path or has C<.>
@@ -3243,16 +3250,16 @@ and C<move_index_entries_after_items> together.
=item $level = section_level($section)
X<C<section_level>>
-Return numbered level of the tree sectioning I<$section>, as modified by
+Return numbered level of the tree sectioning element I<$section>, as modified
by
raise/lowersections.
-=item $element = set_global_document_command($configuration_information,
$global_commands_information, $cmdname, $command_location)
+=item $element = set_global_document_command($customization_information,
$global_commands_information, $cmdname, $command_location)
X<C<set_global_document_command>>
Set the Texinfo configuration option corresponding to I<$cmdname> in
-I<$configuration_information>. The I<$global_commands_information> should
+I<$customization_information>. The I<$global_commands_information> should
contain information about global commands in a Texinfo document, typically
obtained
-from a parser, like L<Texinfo::Parser/$commands =
global_commands_information($parser)>.
+from a parser, like L<<
$parser->global_commands_information()|Texinfo::Parser/$commands =
global_commands_information($parser) >>.
I<$command_location> specifies where in the document the value should be taken
from,
for commands that may appear more than once. The possibilities are:
@@ -3277,7 +3284,11 @@ sequentially to the values in the Texinfo preamble.
The I<$element> returned is the last element that was used to set the
configuration value, or C<undef> if no configuration value was found.
-=item set_informative_command_value($configuration_information, $element)
+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 set_informative_command_value($customization_information, $element)
X<C<set_informative_command_value>>
Set the Texinfo configuration option corresponding to the tree element
@@ -3285,7 +3296,7 @@ I<$element>. The command associated to the tree element
should be
a command that sets some information, such as C<@documentlanguage>,
C<@contents> or C<@footnotestyle> for example.
-=item set_output_encodings($configuration_information, $parser_information)
+=item set_output_encodings($customization_information, $parser_information)
X<C<set_output_encodings>>
If not already set, set C<OUTPUT_ENCODING_NAME> based on input file
diff --git a/tp/Texinfo/Convert/Converter.pm b/tp/Texinfo/Convert/Converter.pm
index 6b4f44f367..4a5458036c 100644
--- a/tp/Texinfo/Convert/Converter.pm
+++ b/tp/Texinfo/Convert/Converter.pm
@@ -68,6 +68,9 @@ my %defaults = (
# but is available directly in the converter as a hash key.
# FIXME separate the two types of information and check that those
# items are not valid customization options?
+# NOTE converters for now do not add more, and, in general set only
+# output_format. It would be good to keep it that way and add
+# customization options instead.
my %common_converters_defaults = (
'language_config_dirs' => undef,
'converted_format' => undef,
@@ -76,8 +79,11 @@ my %common_converters_defaults = (
'output_format' => undef,
'structuring' => undef,
'translated_commands' => {'error' => 'error@arrow{}',},
+
# This is the default, mainly for tests; the caller should set them. These
-# values are what is used in tests of the Converters.
+# values are what is used in tests of the Converters. These variables are
+# customization options, set in the main program when a converter is
+# called from the main program.
'PACKAGE_AND_VERSION' => 'texinfo',
'PACKAGE_VERSION' => '',
'PACKAGE_URL' => 'http://www.gnu.org/software/texinfo/',
@@ -223,9 +229,9 @@ sub converter(;$)
$converter->{'set'}->{$key} = 1;
}
}
- # set $converter->{'converter_init_conf'} to the configuration
+ # set $converter->{'converter_init_conf'} to the customization
# options obtained after setting the defaults and applying
- # the configuration passed as argument.
+ # the customization passed as argument.
$converter->{'converter_init_conf'} = { %{$converter->{'conf'}} };
foreach my $key (keys (%defaults)) {
if (defined($converter->{$key})) {
@@ -461,7 +467,7 @@ sub output($$)
###############################################################
-# Implementation of the configuration API that is used in many
+# Implementation of the customization API that is used in many
# Texinfo modules
sub get_conf($$)
@@ -975,7 +981,7 @@ sub set_global_document_commands($$;$)
my $init_conf;
if (defined($self->{'output_init_conf'})) {
- # use in priority the initial configuration per output
+ # use in priority the initial customization per output
$init_conf = $self->{'output_init_conf'};
} else {
$init_conf = $self->{'converter_init_conf'};
@@ -995,7 +1001,7 @@ sub set_global_document_commands($$;$)
# in $self->get_conf(), but what is available from $self->get_conf()
could
# also be a value set by a previous call of set_global_document_commands.
# There is no easy way to deal with this issue, other than making sure
that
- # a configuration value that is expected to be set early is set in
$init_conf.
+ # a customization value that is expected to be set early is set in
$init_conf.
}
} else {
foreach my $global_command (@{$selected_commands}) {
@@ -1677,7 +1683,7 @@ Texinfo to other formats. There is no promise of API
stability.
=head1 DESCRIPTION
-Texinfo::Convert::Converter is a super class that can be used to
+C<Texinfo::Convert::Converter> is a super class that can be used to
simplify converters initialization. The class also provide some
useful methods.
@@ -1726,10 +1732,16 @@ C<Texinfo::Convert::Converter>.
The I<$options> hash reference holds options for the converter. In
this option hash reference a L<parser object|Texinfo::Parser>
may be associated with the I<parser> key. The other options
-should be configuration options described in the Texinfo manual.
-Those options, when appropriate, override the document content. The parser
-should not be available directly anymore after getting the associated
-information.
+are Texinfo customization options and a few other options that can
+be passed to the converter. Most of the customization options
+are described in the Texinfo manual.
+Those customization options, when appropriate, override the document content.
+B<TODO what about the other options (all are used in converters;
+'structuring' is available in HTML $converter-E<gt>get_info()?>
+The parser should not be available directly anymore after getting the
+associated information. B<TODO document this associated information
+('parser_info', 'indices_information', 'floats'..., most available
+in HTML converter, either through $converter-E<gt>get_info() or
label_command())>
The C<converter> function returns a converter object (a blessed hash
reference) after checking the options and performing some initializations,
@@ -1738,24 +1750,102 @@ also initialized as a L<Texinfo::Report>.
=back
-To help with these initializations, the modules subclassing
C<Texinfo::Convert::Converter> can define two methods:
+To help with these initializations, the modules subclassing
C<Texinfo::Convert::Converter>
+can define two methods:
=over
=item %defaults = $converter->converter_defaults($options)
X<C<converter_defaults>>
-The module can provide a defaults hash for converter configuration options.
+The module can provide a defaults hash for converter customization options.
The I<$options> hash reference holds options for the converter.
=item converter_initialize
X<C<converter_initialize>>
-This method is called at the end of the Texinfo::Convert::Converter
+This method is called at the end of the C<Texinfo::Convert::Converter>
converter initialization.
=back
+=head2 Getting and setting customization variables
+
+C<Texinfo::Convert::Converter> implements a simple interface to
+set and retrieve Texinfo customization variables. Helper
+functions from diverse Texinfo modules needing customization
+information expect an object implementing C<get_conf> and/or
+C<set_conf>. The converter itself can therefore be used in
+such cases.
+
+=over
+
+=item $converter->force_conf($variable_name, $variable_value)
+X<C<force_conf>>
+
+Set the Texinfo customization option I<$variable_name> to I<$variable_value>.
+This should rarely be used, but the purpose of this method is to be able
+to revert a customization that is always wrong for a given output
+format, like the splitting for example.
+
+=item $converter->get_conf($variable_name)
+X<C<get_conf>>
+
+Returns the value of the Texinfo customization variable I<$variable_name>.
+
+=item $converter->set_conf($variable_name, $variable_value)
+X<C<set_conf>>
+
+Set the Texinfo customization option I<$variable_name> to I<$variable_value> if
+not set as a converter option.
+
+=back
+
+=head2 Conversion to XML
+
+Some C<Texinfo::Convert::Converter> methods target conversion to XML.
+Most methods take a I<$converter> as argument to get some
+information and use methods for error reporting.
+
+=over
+
+=item $formatted_text =
$converter->xml_format_text_with_numeric_entities($text)
+X<C<xml_format_text_with_numeric_entities>>
+
+Replace quotation marks and hyphens used to represent dash in
+Texinfo text with numeric XML entities.
+
+=item $protected_text = $converter->xml_protect_text($text)
+X<C<xml_protect_text>>
+
+Protect special XML characters (&, E<lt>, E<gt>, ") of I<$text>.
+
+=item $comment = $converter->xml_comment($text)
+X<C<xml_comment>>
+
+Returns an XML comment for I<$text>.
+
+=item $result = xml_accent($text, $accent_command, $in_upper_case,
$use_numeric_entities)
+X<C<xml_accent>>
+
+I<$text> is the text appearing within an accent command. I<$accent_command>
+should be a Texinfo tree element corresponding to an accent command taking
+an argument. I<$in_upper_case> is optional, and, if set, the text is put
+in upper case. The function returns the accented letter as XML named entity
+if possible, falling back to numeric entities if there is no named entity
+and to an ASCII transliteration as last resort. I<$use_numeric_entities>
+is optional. If set, numerical entities are used instead of named entities
+if possible.
+
+=item $result = $converter->xml_accents($accent_command, $in_upper_case)
+X<C<xml_accents>>
+
+I<$accent_command> is an accent command, which may have other accent
+commands nested. If I<$in_upper_case> is set, the result should be
+upper cased. The function returns the accents formatted as XML.
+
+=back
+
=head2 Helper methods
The module provides methods that may be useful for converter.
@@ -1763,7 +1853,7 @@ Most methods take a I<$converter> as argument to get some
information and use methods for error reporting, see L<Texinfo::Report>. Also
to translate strings, see L<Texinfo::Translations>. For
useful methods that need a converter optionally and can be used
-in converters that do not inherit from Texinfo::Convert::Converter,
+in converters that do not inherit from C<Texinfo::Convert::Converter>,
see L<Texinfo::Convert::Utils>.
=over
@@ -1806,10 +1896,10 @@ X<C<determine_files_and_directory>>
Determine output file and directory, as well as names related to files. The
result depends on the presence of C<@setfilename>, on the Texinfo input file
-name, and on customization options such as OUTPUT, SUBDIR or SPLIT, as
described
-in the Texinfo manual. I<$output_format> is optional. If it is not set the
-current output format, if defined, is used instead. If not an empty string,
-C<_$output_format> is prepended to the default directory name.
+name, and on customization options such as C<OUTPUT>, C<SUBDIR> or C<SPLIT>,
+as described in the Texinfo manual. I<$output_format> is optional. If it is
+not set the current output format, if defined, is used instead. If not an
+empty string, C<_$output_format> is prepended to the default directory name.
I<$output_file> is mainly relevant when not split and should be used as the
output file name. In general, if not split and I<$output_file> is an empty
@@ -1819,7 +1909,7 @@ I<$destination_directory> is either the directory
I<$output_file> is in, or if
split, the directory where the files should be created. I<$output_filename>
is, in general, the file name portion of I<$output_file> (without directory)
but can also be set based on C<@setfilename>, in particular when
-C<$output_file> is an empty string. I<$document_name> is C<$output_filename>
+I<$output_file> is an empty string. I<$document_name> is I<$output_filename>
without extension. I<$input_basefile> is based on the input texinfo file name,
with the file name portion only (without directory).
@@ -1855,14 +1945,6 @@ I<$float> is a texinfo tree C<@float> element. This
function
returns the type and number of the float as a texinfo tree with
translations.
-=item $converter->force_conf($option_string, $value)
-X<C<force_conf>>
-
-Set the Texinfo configuration option I<$option_string> to I<$value>.
-This should rarely be used, but the purpose of this method is to be able
-to revert a configuration that is always wrong for a given output
-format, like the splitting for example.
-
=item $end_line = $converter->format_comment_or_return_end_line($element)
X<C<format_comment_or_return_end_line>>
@@ -1872,11 +1954,6 @@ better formatted with new lines added independently of
the presence
of newline or comment in the initial Texinfo line, so most converters
are better off not using this method.
-=item $converter->get_conf($option_string)
-X<C<get_conf>>
-
-Returns the value of the Texinfo configuration option I<$option_string>.
-
=item $filename = sub $converter->node_information_filename($node_info)
X<C<node_information_filename>>
@@ -1898,16 +1975,10 @@ X<C<present_bug_message>>
Show a bug message using I<$message> text. Use information on
I<$element> tree element if given in argument.
-=item $converter->set_conf($option_string, $value)
-X<C<set_conf>>
-
-Set the Texinfo configuration option I<$option_string> to I<$value> if
-not set as a converter option.
-
=item $converter->set_global_document_commands($commands_location,
$selected_commands)
X<C<set_global_document_commands>>
-Set the Texinfo configuration options for @-commands. I<$selected_commands>
+Set the Texinfo customization options for @-commands. I<$selected_commands>
is an optional array reference containing the @-commands set, if not given
all the global informative @-commands are set. I<$commands_location> specifies
where in the document the value should be taken from. The possibilities are:
@@ -1938,60 +2009,22 @@ 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.
+For more information on the function used to set the value for each of the
command, see
+L<Texinfo::Common set_global_document_command|Texinfo::Common/$element =
set_global_document_command($customization_information,
$global_commands_information, $cmdname, $command_location)>.
+
=item $table_item_tree = $converter->table_item_content_tree($element,
$contents)
X<C<table_item_content_tree>>
I<$element> should be an C<@item> or C<@itemx> tree element,
I<$contents> should be corresponding texinfo tree contents.
-Returns a tree in which the @-command in argument of @*table
+Returns a tree in which the @-command in argument of C<@*table>
of the I<$element> has been applied to I<$contents>.
=item $result = $converter->top_node_filename($document_name)
X<C<top_node_filename>>
-Returns a file name for the Top node file using either TOP_FILE
-customization value, or EXTENSION customization value and I<$document_name>.
-
-=back
-
-Other C<Texinfo::Convert::Converter> methods target conversion to XML:
-
-=over
-
-=item $formatted_text =
$converter->xml_format_text_with_numeric_entities($text)
-X<C<xml_format_text_with_numeric_entities>>
-
-Replace quotation marks and hyphens used to represent dash in
-Texinfo text with numeric XML entities.
-
-=item $protected_text = $converter->xml_protect_text($text)
-X<C<xml_protect_text>>
-
-Protect special XML characters (&, E<lt>, E<gt>, ") of I<$text>.
-
-=item $comment = $converter->xml_comment($text)
-X<C<xml_comment>>
-
-Returns an XML comment for I<$text>.
-
-=item $result = xml_accent($text, $accent_command, $in_upper_case,
$use_numeric_entities)
-X<C<xml_accent>>
-
-I<$text> is the text appearing within an accent command. I<$accent_command>
-should be a Texinfo tree element corresponding to an accent command taking
-an argument. I<$in_upper_case> is optional, and, if set, the text is put
-in upper case. The function returns the accented letter as XML named entity
-if possible, falling back to numeric entities if there is no named entity
-and to an ASCII transliteration as last resort. I<$use_numeric_entities>
-is optional. If set, numerical entities are used instead of named entities
-if possible.
-
-=item $result = $converter->xml_accents($accent_command, $in_upper_case)
-X<C<xml_accents>>
-
-I<$accent_command> is an accent command, which may have other accent
-commands nested. If I<$in_upper_case> is set, the result should be
-upper cased. The function returns the accents formatted as XML.
+Returns a file name for the Top node file using either C<TOP_FILE>
+customization value, or C<EXTENSION> customization value and I<$document_name>.
=back
@@ -2000,9 +2033,10 @@ Finally, there is:
=over
=item $result = $converter->output_internal_links()
+X<C<output_internal_links>>
At this level, the method just returns undef. It is used in the HTML
-output, following the C<--internal-links> option of texi2any/makeinfo
+output, following the C<--internal-links> option of C<texi2any>
specification.
=back
diff --git a/tp/Texinfo/Convert/DocBook.pm b/tp/Texinfo/Convert/DocBook.pm
index 1522b5ce74..c9e3388ec7 100644
--- a/tp/Texinfo/Convert/DocBook.pm
+++ b/tp/Texinfo/Convert/DocBook.pm
@@ -1760,11 +1760,13 @@ Texinfo::Convert::DocBook converts a Texinfo tree to
DocBook.
Initialize converter from Texinfo to DocBook.
The I<$options> hash reference holds options for the converter. In
-this option hash reference a parser object may be associated with the
-I<parser> key. The other options should be configuration options
-described in the Texinfo manual. Those options, when appropriate,
-override the document content. The parser should not be available
-directly anymore after getting the associated information.
+this option hash reference a L<parser object|Texinfo::Parser>
+may be associated with the I<parser> key. The other options
+are Texinfo customization options and a few other options that can
+be passed to the converter. Most of the customization options are described in
+the Texinfo manual. Those customization options, when appropriate, override
+the document content. The parser should not be available directly anymore
+after getting the associated information.
See L<Texinfo::Convert::Converter> for more information.
diff --git a/tp/Texinfo/Convert/HTML.pm b/tp/Texinfo/Convert/HTML.pm
index 588e015b78..22d88bb347 100644
--- a/tp/Texinfo/Convert/HTML.pm
+++ b/tp/Texinfo/Convert/HTML.pm
@@ -10498,11 +10498,13 @@ Texinfo::Convert::HTML converts a Texinfo tree to
HTML.
Initialize converter from Texinfo to HTML.
The I<$options> hash reference holds options for the converter. In
-this option hash reference a parser object may be associated with the
-I<parser> key. The other options should be configuration options
-described in the Texinfo manual. Those options, when appropriate,
-override the document content. The parser should not be available
-directly anymore after getting the associated information.
+this option hash reference a L<parser object|Texinfo::Parser>
+may be associated with the I<parser> key. The other options
+are Texinfo customization options and a few other options that can
+be passed to the converter. Most of the customization options are described in
+the Texinfo manual. Those customization options, when appropriate, override
+the document content. The parser should not be available directly anymore
+after getting the associated information.
See L<Texinfo::Convert::Converter> for more information.
@@ -10525,7 +10527,7 @@ portions. For a full document use C<convert>.
X<C<output_internal_links>>
Returns text representing the links in the document. The format should
-follow the C<--internal-links> option of the texi2any/makeinfo
+follow the C<--internal-links> option of the C<texi2any>
specification. This is only supported in (and relevant for) HTML.
=back
diff --git a/tp/Texinfo/Convert/IXIN.pm b/tp/Texinfo/Convert/IXIN.pm
index 21cabb6ae4..d5999928f0 100644
--- a/tp/Texinfo/Convert/IXIN.pm
+++ b/tp/Texinfo/Convert/IXIN.pm
@@ -351,7 +351,7 @@ sub output_ixin($$)
my %end_of_nodes_setting_commands;
my %setting_commands_defaults;
# FIXME this code is unclear and probably needs to be fixed if developemnt
- # resumes.
+ # resumes. Maybe could be replaced by set_global_document_commands.
foreach my $global_command (keys(%{$self->{'global_commands'}})) {
if ((($Texinfo::Common::misc_commands{$global_command}
and $Texinfo::Common::misc_commands{$global_command} =~ /^\d/)
@@ -390,7 +390,7 @@ sub output_ixin($$)
my $setting_command = $setting_commands{$setting_command_name};
$setting_command_name = 'shortcontents'
if ($setting_command_name eq 'summarycontents');
- # FIXME should use set_informative_command_value and get_conf instead
+ # FIXME should use get_conf instead?
my $value = Texinfo::Common::_informative_command_value($setting_command);
#print STDERR "$setting_command_name $value\n";
# do not register settings if sete at the default value.
@@ -465,7 +465,7 @@ sub output_ixin($$)
# update current settings
if (defined($end_of_nodes_setting_commands{$normalized_node_name})) {
foreach my $setting_command_name
(keys(%{$end_of_nodes_setting_commands{$normalized_node_name}})) {
- # FIXME should use Texinfo::Common::set_informative_command_value
and get_conf
+ # FIXME should use get_conf instead?
my $value =
Texinfo::Common::_informative_command_value_informative_command_value(
$end_of_nodes_setting_commands{$normalized_node_name}->{$setting_command_name});
if ((defined($settings{$setting_command_name})
diff --git a/tp/Texinfo/Convert/IXINSXML.pm b/tp/Texinfo/Convert/IXINSXML.pm
index 59eb8bbfd2..6864af4aca 100644
--- a/tp/Texinfo/Convert/IXINSXML.pm
+++ b/tp/Texinfo/Convert/IXINSXML.pm
@@ -16,12 +16,6 @@
# along with this program. If not, see <http://www.gnu.org/licenses/>.
#
# Original author: Patrice Dumas <pertusus@free.fr>
-#
-# This module implements abstract functions that output the IXIN format
-# using lower level formatting funtions, here adapted to lisp like
-# output. For other output, the output specific functions should be
-# redefined. This module is not enough to output IXIN format, a module
-# inheriting both from a converter module and this module is required.
package Texinfo::Convert::IXINSXML;
diff --git a/tp/Texinfo/Convert/Info.pm b/tp/Texinfo/Convert/Info.pm
index 8a45ba26c2..44efa57e1a 100644
--- a/tp/Texinfo/Convert/Info.pm
+++ b/tp/Texinfo/Convert/Info.pm
@@ -640,11 +640,13 @@ Texinfo::Convert::Info converts a Texinfo tree to Info.
Initialize converter from Texinfo to Info.
The I<$options> hash reference holds options for the converter. In
-this option hash reference a parser object may be associated with the
-I<parser> key. The other options should be configuration options
-described in the Texinfo manual. Those options, when appropriate,
-override the document content. The parser should not be available
-directly anymore after getting the associated information.
+this option hash reference a L<parser object|Texinfo::Parser>
+may be associated with the I<parser> key. The other options
+are Texinfo customization options and a few other options that can
+be passed to the converter. Most of the customization options are described in
+the Texinfo manual. Those customization options, when appropriate, override
+the document content. The parser should not be available directly anymore
+after getting the associated information.
See L<Texinfo::Convert::Converter> for more information.
diff --git a/tp/Texinfo/Convert/LaTeX.pm b/tp/Texinfo/Convert/LaTeX.pm
index 9ab58b7ffc..b36f6712d2 100644
--- a/tp/Texinfo/Convert/LaTeX.pm
+++ b/tp/Texinfo/Convert/LaTeX.pm
@@ -94,7 +94,9 @@
#
# CAN WAIT
#
-# Use texinfo.cnf? Here? in texi2any.pl?
+# Use texinfo.cnf? Here? in texi2any.pl? What about customization of
+# LaTeX output? Some customization would be relevant, for example the
+# document type, fonts, packages...
#
# @need is implemented in a specific way, maybe there could be a definition of
# \mil instead.
@@ -752,6 +754,12 @@ my %defaults = (
'converted_format' => 'latex',
+ # FIXME this sets an option that is not a customization variable
+ # and will not be documented anywhere. It should probably be better
+ # to add and document a customization in the Texinfo manual if needed.
+ # For LaTeX in general, it could make sense to have some customization,
+ # for example of packages, fonts, document type, to be discussed/though
+ # about how to setup this customization.
# FIXME any idea what could be used?
'floats_extension' => 'tfl',
);
diff --git a/tp/Texinfo/Convert/NodeNameNormalization.pm
b/tp/Texinfo/Convert/NodeNameNormalization.pm
index ad43ebd6f5..ff885a1745 100644
--- a/tp/Texinfo/Convert/NodeNameNormalization.pm
+++ b/tp/Texinfo/Convert/NodeNameNormalization.pm
@@ -422,11 +422,11 @@ Texinfo to other formats. There is no promise of API
stability.
C<Texinfo::Convert::NodeNameNormalization> allows to normalize node names,
with C<normalize_node> following the specification described in the
-Texinfo manual for HTML Xref. This is usefull each time one want a
+Texinfo manual I<HTML Xref> node. This is usefull each time one want a
unique identifier for Texinfo content that is only composed of letter,
digits, C<-> and C<_>. In L<Texinfo::Parser>, C<normalize_node> is used
-for node, floats and anchor names normalization, but also float
-types C<@acronym> and C<@abbr> first argument.
+for C<@node>, C<@float> and C<@anchor> names normalization, but also C<@float>
+types and C<@acronym> and C<@abbr> first argument.
It is also possible to transliterate non ascii letters, instead of mangling
them, with C<transliterate_texinfo>, losing the uniqueness feature of
@@ -443,7 +443,7 @@ letters and protect characters that should not appear on
file names.
X<C<normalize_node>>
The Texinfo I<$tree> is returned as a string, normalized as described in the
-Texinfo manual for HTML Xref.
+Texinfo manual I<HTML Xref> node.
The result will be poor for Texinfo trees which are not @-command arguments
(on an @-command line or in braces), for instance if the tree contains
diff --git a/tp/Texinfo/Convert/Plaintext.pm b/tp/Texinfo/Convert/Plaintext.pm
index fb1710aa09..32f7f10496 100644
--- a/tp/Texinfo/Convert/Plaintext.pm
+++ b/tp/Texinfo/Convert/Plaintext.pm
@@ -3446,11 +3446,13 @@ Texinfo::Convert::Plaintext converts a Texinfo tree to
Plaintext.
Initialize converter from Texinfo to Plaintext.
The I<$options> hash reference holds options for the converter. In
-this option hash reference a parser object may be associated with the
-I<parser> key. The other options should be configuration options
-described in the Texinfo manual. Those options, when appropriate,
-override the document content. The parser should not be available
-directly anymore after getting the associated information.
+this option hash reference a L<parser object|Texinfo::Parser>
+may be associated with the I<parser> key. The other options
+are Texinfo customization options and a few other options that can
+be passed to the converter. Most of the customization options are described in
+the Texinfo manual. Those customization options, when appropriate, override
+the document content. The parser should not be available directly anymore
+after getting the associated information.
See L<Texinfo::Convert::Converter> for more information.
diff --git a/tp/Texinfo/Convert/Texinfo.pm b/tp/Texinfo/Convert/Texinfo.pm
index e4cff61eb9..48b0d846ce 100644
--- a/tp/Texinfo/Convert/Texinfo.pm
+++ b/tp/Texinfo/Convert/Texinfo.pm
@@ -250,7 +250,7 @@ Texinfo to other formats. There is no promise of API
stability.
=head1 DESCRIPTION
-Texinfo::Convert::Texinfo converts a Texinfo tree (described in
+C<Texinfo::Convert::Texinfo> converts a Texinfo tree (described in
L<Texinfo::Parser>) to Texinfo code. If the Texinfo tree results from
parsing some Texinfo document, The converted Texinfo code should be
exactly the same as the initial document, except that user defined @-macros
diff --git a/tp/Texinfo/Convert/TexinfoXML.pm b/tp/Texinfo/Convert/TexinfoXML.pm
index b2b0472da2..b5f567d948 100644
--- a/tp/Texinfo/Convert/TexinfoXML.pm
+++ b/tp/Texinfo/Convert/TexinfoXML.pm
@@ -43,6 +43,8 @@ my %defaults = (
'EXTENSION' => 'xml',
#'output_perl_encoding' => 'utf8',
'OUTPUT_ENCODING_NAME' => 'utf-8',
+ # the TEXINFO_DTD_VERSION is reset by the main program
+ # so this would only be used in tests
'TEXINFO_DTD_VERSION' => '5.0',
'OUTFILE' => undef,
'SUBDIR' => undef,
@@ -1739,11 +1741,13 @@ Texinfo::Convert::TexinfoXML converts a Texinfo tree to
TexinfoXML.
Initialize converter from Texinfo to TexinfoXML.
The I<$options> hash reference holds options for the converter. In
-this option hash reference a parser object may be associated with the
-I<parser> key. The other options should be configuration options
-described in the Texinfo manual. Those options, when appropriate,
-override the document content. The parser should not be available
-directly anymore after getting the associated information.
+this option hash reference a L<parser object|Texinfo::Parser>
+may be associated with the I<parser> key. The other options
+are Texinfo customization options and a few other options that can
+be passed to the converter. Most of the customization options are described in
+the Texinfo manual. Those customization options, when appropriate, override
+the document content. The parser should not be available directly anymore
+after getting the associated information.
See L<Texinfo::Convert::Converter> for more information.
diff --git a/tp/Texinfo/Convert/Text.pm b/tp/Texinfo/Convert/Text.pm
index 511024fb41..ac6d25f692 100644
--- a/tp/Texinfo/Convert/Text.pm
+++ b/tp/Texinfo/Convert/Text.pm
@@ -895,10 +895,8 @@ Texinfo to other formats. There is no promise of API
stability.
=head1 DESCRIPTION
-Texinfo::Convert::Text is a simple backend that converts a Texinfo tree
-to simple text. It is used for some command argument expansion in
-C<Texinfo::Parser>, for instance the file names, or encoding names.
-It is also used in some converters, especially for file names.
+C<Texinfo::Convert::Text> is a simple backend that converts a Texinfo tree
+to simple text. It is used in converters, especially for file names.
The converter is very simple, and, in the default case, cannot handle
output strings translation or error handling.
@@ -974,7 +972,7 @@ character.
X<C<ascii_accent_fallback>>
Same as C<ascii_accent> but with an additional first argument
-converter, which is in ignored, but needed if this function is to
+converter, which is ignored, but needed if this function is to
be in argument of functions that need a fallback for accents
conversion.
diff --git a/tp/Texinfo/Convert/Unicode.pm b/tp/Texinfo/Convert/Unicode.pm
index f2a97411ef..a135f83900 100644
--- a/tp/Texinfo/Convert/Unicode.pm
+++ b/tp/Texinfo/Convert/Unicode.pm
@@ -1624,7 +1624,7 @@ Texinfo to other formats. There is no promise of API
stability.
=head1 DESCRIPTION
-Texinfo::Convert::Unicode provides methods dealing with Unicode representation
+C<Texinfo::Convert::Unicode> provides methods dealing with Unicode
representation
and conversion of Unicode code points, to be used in converters.
When an encoding supported in Texinfo is given as argument of a method of the
@@ -1674,7 +1674,7 @@ innermost accent.
I<$format_accent> is a function reference that is used to format the accent
commands if there is no encoded character available at some point of the
conversion of the I<$stack>. I<$converter> is a converter object optionaly
-used by I<$format_accent>. It may be undef if there is no need of
+used by I<$format_accent>. It may be C<undef> if there is no need of
converter object in I<$format_accent>.
If I<$set_case> is positive, the result is upper-cased, while if it is
negative,
diff --git a/tp/Texinfo/Convert/Utils.pm b/tp/Texinfo/Convert/Utils.pm
index ac034dca9d..db3d8d7da5 100644
--- a/tp/Texinfo/Convert/Utils.pm
+++ b/tp/Texinfo/Convert/Utils.pm
@@ -199,7 +199,7 @@ sub find_innermost_accent_contents($)
sub expand_verbatiminclude($$$)
{
my $registrar = shift;
- my $configuration_information = shift;
+ my $customization_information = shift;
my $current = shift;
my $input_encoding;
@@ -211,21 +211,21 @@ sub expand_verbatiminclude($$$)
if (defined($current->{'extra'}->{'input_perl_encoding'}));
my $encoding;
- my $input_file_name_encoding =
$configuration_information->get_conf('INPUT_FILE_NAME_ENCODING');
+ my $input_file_name_encoding =
$customization_information->get_conf('INPUT_FILE_NAME_ENCODING');
if ($input_file_name_encoding) {
$encoding = $input_file_name_encoding;
- } elsif
($configuration_information->get_conf('DOC_ENCODING_FOR_INPUT_FILE_NAME')) {
+ } elsif
($customization_information->get_conf('DOC_ENCODING_FOR_INPUT_FILE_NAME')) {
$encoding = $input_encoding;
} else {
- $encoding = $configuration_information->get_conf('LOCALE_ENCODING');
+ $encoding = $customization_information->get_conf('LOCALE_ENCODING');
}
my ($file_name, $file_name_encoding)
- = Texinfo::Common::encode_file_name($configuration_information,
+ = Texinfo::Common::encode_file_name($customization_information,
$file_name_text,
$encoding);
- my $file = Texinfo::Common::locate_include_file($configuration_information,
+ my $file = Texinfo::Common::locate_include_file($customization_information,
$file_name);
my $verbatiminclude;
@@ -237,7 +237,7 @@ sub expand_verbatiminclude($$$)
# need to decode to the internal perl codepoints for error message
$decoded_file = Encode::decode($file_name_encoding, $file)
if (defined($file_name_encoding));
- $registrar->line_error($configuration_information,
+ $registrar->line_error($customization_information,
sprintf(__("could not read %s: %s"), $decoded_file, $!),
$current->{'source_info'});
}
@@ -260,14 +260,14 @@ sub expand_verbatiminclude($$$)
$decoded_file = Encode::decode($file_name_encoding, $file)
if (defined($file_name_encoding));
$registrar->document_warn(
- $configuration_information, sprintf(__(
+ $customization_information, sprintf(__(
"error on closing \@verbatiminclude file %s: %s"),
$decoded_file, $!));
}
}
}
} elsif ($registrar) {
- $registrar->line_error($configuration_information,
+ $registrar->line_error($customization_information,
sprintf(__("\@%s: could not find %s"),
$current->{'cmdname'}, $file_name_text),
$current->{'source_info'});
@@ -426,7 +426,7 @@ X<C<expand_today>>
Expand today's date, as a texinfo tree with translations.
-=item $tree = expand_verbatiminclude($registrar, $configuration_information,
$verbatiminclude)
+=item $tree = expand_verbatiminclude($registrar, $customization_information,
$verbatiminclude)
X<C<expand_verbatiminclude>>
The I<$registrar> argument may be undef. I<$verbatiminclude> is a
diff --git a/tp/Texinfo/ParserNonXS.pm b/tp/Texinfo/ParserNonXS.pm
index 97e1ef4543..a6d35249d8 100644
--- a/tp/Texinfo/ParserNonXS.pm
+++ b/tp/Texinfo/ParserNonXS.pm
@@ -6261,7 +6261,7 @@ C<Texinfo::Parser> will parse Texinfo text into a Perl
tree. In one pass
it expands user-defined @-commands, conditionals (C<@ifset>, C<@ifinfo>...)
and C<@value> and constructs the tree. Some extra information is gathered
while doing the tree: for example, the C<@quotation> associated to an
C<@author>
-command, the number of cilumns in a multitable, or the node associated with a
+command, the number of columns in a multitable, or the node associated with a
section.
=head1 METHODS
@@ -6281,7 +6281,8 @@ X<C<Texinfo::Parser::parser>>
X<Parser initialization>
This method creates a new parser. The options may be provided as a hash
-reference.
+reference. Most of those options correspond to Texinfo customization options
+described in the Texinfo manual.
=over
@@ -6296,8 +6297,8 @@ conditional blocks should be expanded. Default is empty.
=item FORMAT_MENU
-Possible values are 'nomenu', 'menu' and 'sectiontoc'. Only report
-menu-related errors for 'menu'.
+Possible values are C<nomenu>, C<menu> and C<sectiontoc>. Only report
+menu-related errors for C<menu>.
=item INCLUDE_DIRECTORIES
@@ -6482,7 +6483,7 @@ X<C<registered_errors>>
I<$registrar> is a L<Texinfo::Report> object in which the errors
and warnings encountered while parsing are registered. If a I<registrar>
-passed to the parser initialization options, it is reused, otherwise
+is passed to the parser initialization options, it is reused, otherwise
a new one is created.
=back
@@ -6492,7 +6493,7 @@ a new one is created.
After parsing some information about the Texinfo code that was processed
is available from the parser.
-Some global information is available through C<global_information>
+Some global information is available through C<global_information>:
=over
@@ -6521,9 +6522,9 @@ C<input_perl_encoding> string is a corresponding Perl
encoding name.
=item input_directory
The name of the main Texinfo input file and the associated directory.
-Binary strings. They should come from the command line and can
-be decoded with the encoding in the customization variable
-C<COMMAND_LINE_ENCODING>.
+Binary strings. In C<texi2any>, they should come from the command line
+(and can be decoded with the encoding in the customization variable
+C<COMMAND_LINE_ENCODING>).
=back
@@ -6531,7 +6532,7 @@ C<COMMAND_LINE_ENCODING>.
Some command lists are available, such that it is possible to go through
the corresponding tree elements without walking the tree. They are
-available through C<global_commands_information>
+available through C<global_commands_information>:
=over
@@ -6545,9 +6546,9 @@ tree elements.
=back
All the @-commands that have an associated label (so can be the
-target of cross references) - C<@node>, C<@anchor> and C<@float> with
-label - have a normalized name associated, constructed as described in the
-I<HTML Xref> node in the Texinfo documenation. Those normalized labels and
+target of cross references) -- C<@node>, C<@anchor> and C<@float> with
+label -- have a normalized name associated, constructed as described in the
+I<HTML Xref> node in the Texinfo documentation. Those normalized labels and
the association with @-commands is available through C<labels_information>:
=over
@@ -6842,17 +6843,18 @@ contents, I<line_arg> and I<block_line_arg> contain the
arguments
appearing on the line of @-commands. Text fragments may have a type to
give an information of the kind of text fragment, for example
I<empty_spaces_before_paragraph> is associated to spaces appearing
-before a paragraph beginning. Many @-commands elements do not have
+before a paragraph beginning. Most @-commands elements do not have
a type associated.
=item args
Arguments in braces or on @-command line, and the elements of a menu entry.
+An array reference.
=item contents
The Texinfo appearing in the element. For block commands, other
-containers, C<@node> and sectioning commands.
+containers, C<@node> and sectioning commands. An array reference.
=item parent
@@ -6886,7 +6888,7 @@ The user macro name the @-command is expanded from.
=item extra
-A hash reference holding any additional information.
+A hash reference holding any other information.
See L</Information available in the extra key>.
=back
@@ -6895,20 +6897,12 @@ See L</Information available in the extra key>.
=head3 Types for command elements
-Some types can be associated with @-commands (in addition to the element
-being described by C<cmdname>), although usually there will be no type
-at all. The following are the possible values of C<type> for tree elements
-for @-commands.
+Some types can be associated with @-commands (in addition to C<cmdname>),
+although usually there will be no type at all. The following are the
+possible values of C<type> for tree elements for @-commands.
=over
-=item def_line
-
-This type may be associated with a definition command with a x form,
-like C<@defunx>, C<@defvrx>. For the form without x, the associated
-I<def_line> is the first C<contents> element. It is described in more
-details below.
-
=item command_as_argument
This is the type of a command given in argument of C<@itemize>,
@@ -6923,25 +6917,24 @@ the element corresponding with bullet has the following
keys:
'cmdname' => 'bullet'
'type' => 'command_as_argument'
-The parent @-command has an entry in extra for the I<command_as_argument>
+The parent @-command has an entry in C<extra> for the I<command_as_argument>
element:
'cmdname' => 'itemize'
- 'extra => {'command_as_argument' => $command_element_as_argument}
+ 'extra' => {'command_as_argument' => $command_element_as_argument}
-=item index_entry_command
-
-This is the type of index entry command like C<@cindex>, and, more
-importantly user-defined index entry commands. So for example if there
-is:
+=item def_line
- @defindex foo
- ...
+This type may be associated with a definition command with a x form,
+like C<@defunx>, C<@defvrx>. For the form without x, the associated
+I<def_line> is the first C<contents> element. It is described in more
+details below.
- @fooindex index entry
+=item definfoenclose_command
-the C<@fooindex> @-command element will have the I<index_entry_command>
-type.
+This type is set for an @-command that is redefined by C<@definfoenclose>.
+The beginning is in C<< {'extra'}->{'begin'} >> and the end in
+C<< {'extra'}->{'end'} >>.
=item following_arg
@@ -6951,11 +6944,19 @@ have their argument after them, as
@~n
@ringaccent A
-=item definfoenclose_command
+=item index_entry_command
-This type is set for an @-command that is redefined by C<@definfoenclose>.
-The beginning is in C<< {'extra'}->{'begin'} >> and the end in
-C<< {'extra'}->{'end'} >>.
+This is the type of index entry command like C<@cindex>, and, more
+importantly user-defined index entry commands. So for example if there
+is:
+
+ @defindex foo
+ ...
+
+ @fooindex index entry
+
+the C<@fooindex> @-command element will have the I<index_entry_command>
+type.
=back
@@ -7017,7 +7018,7 @@ Text appearing before real content, including the
C<\input texinfo.tex>.
=item untranslated
English text added by the parser that may need to be translated
-during conversion. Happens for @def* @-commands aliases that
+during conversion. Happens for C<@def*> @-commands aliases that
leads to prepending text such as 'Function'.
=back
@@ -7063,8 +7064,15 @@ corresponding to the I<preamble> in the Texinfo
documentation.
=head3 Types of container elements
-The other types of element are the following. These are containers with
-other elements appearing in their C<contents>.
+The other types of element are containers with other elements appearing in
+their C<contents>. The C<paragraph> container holds normal text from the
Texinfo
+manual outside of any @-commands, and within @-commands with blocks of text
+(C<@footnote>, C<@itemize> C<@item>, C<@quotation> for example). The
C<preformatted>
+container holds the content appearing in @-commands like C<@example> and
+the C<rawpreformatted> container holds the content appearing in format commands
+such as C<@html>. The other containers are more specific.
+
+The types of container element are the following:
=over
@@ -7219,6 +7227,11 @@ Texinfo code within a format that is not filled.
Happens within some
block commands like C<@example>, but also in menu (in menu descriptions,
menu comments...).
+=item rawpreformatted
+
+Texinfo code within raw output format block commands such as C<@tex>
+or C<@html>.
+
=item table_entry
=item table_term
@@ -7240,7 +7253,7 @@ and C<@itemx>, in a I<table_term>.
=back
-=head2 Information available in the extra key
+=head2 Information available in the C<extra> key
X<Texinfo tree element extra key>
=head3 Extra keys available for more than one @-command
@@ -7352,9 +7365,9 @@ I<original_def_cmdname> is the original def command.
If it is an x form, it has I<not_after_command> set if not
appearing after the definition command without x.
-=item def_line
+=item C<def_line>
-For each element in a def_line, the key I<def_role> holds a string
+For each element in a C<def_line>, the key I<def_role> holds a string
describing the meaning of the element. It is one of
I<category>, I<name>, I<class>, I<type>, I<arg>, I<typearg>,
I<spaces> or I<delimiter>, depending on the definition.
@@ -7363,27 +7376,22 @@ The I<def_parsed_hash> hash reference has these strings
as keys,
and the values are the corresponding elements.
The I<omit_def_name_space> key value is set and true if the Texinfo variable
-@code{txidefnamenospace} was set for the def_line, signaling that the
+C<txidefnamenospace> was set for the C<def_line>, signaling that the
space between function definition name and arguments should be omitted.
-=item definfoenclose defined commands
+=item C<@definfoenclose> defined commands
-I<begin> holds the string beginning the definfoenclose,
-I<end> holds the string ending the definfoenclose.
+I<begin> holds the string beginning the C<@definfoenclose>,
+I<end> holds the string ending the C<@definfoenclose>.
=item C<@documentencoding>
The argument, normalized is in I<input_encoding_name> if it is recognized.
The corresponding Perl encoding name is in I<input_perl_encoding>.
-=item empty_line_after_command
-
-The corresponding command is in I<spaces_associated_command>.
-
=item C<@enumerate>
-The extra key I<enumerate_specification> contains the enumerate
-argument.
+The I<enumerate_specification> C<extra> key contains the enumerate argument.
=item C<@float>
@@ -7422,7 +7430,7 @@ C<@inlinefmtifelse>, and 1 for other commands.
=item C<@item> in C<@enumerate> or C<@itemize>
-The I<item_number> extra key holds the number of this item.
+The I<item_number> C<extra> key holds the number of this item.
=item C<@item> and C<@tab> in C<@multitable>
@@ -7437,13 +7445,13 @@ the cell.
=item C<@ftable>
-The I<command_as_argument> extra key points to the @-command on
+The I<command_as_argument> C<extra> key points to the @-command on
as argument on the @-command line.
If the command in argument for C<@table>, C<@vtable> or C<@ftable>
is C<@kbd> and the context and C<@kbdinputstyle> is such that C<@kbd>
should be formatted as code, the I<command_as_argument_kbd_code>
-extra key is set to 1.
+C<extra> key is set to 1.
=item C<@kbd>
@@ -7454,7 +7462,7 @@ I<code> is set depending on the context and
C<@kbdinputstyle>.
I<invalid_syntax> is set if there was an error on the C<@macro>
line. I<arg_line> holds the line after C<@macro>.
-=item menu_entry
+=item <menu_entry>
The I<menu_entry_description> and I<menu_entry_name> keys
are associated with the corresponding tree elements. The
@@ -7490,7 +7498,7 @@ references to menu elements occuring in the node.
The first node containing a C<@printindex> @-command has the I<isindex>
key set.
-=item paragraph
+=item C<paragraph>
The I<indent> or I<noindent> key value is set if the corresponding
@-commands are associated with that paragraph.
@@ -7512,7 +7520,7 @@ no sectioning command between the C<@part> and the node.
The I<node_argument> entry holds a parsed node entry, like
the one appearing in the I<nodes_manuals> array for C<@node>.
-=item row
+=item C<row>
The I<row_number> index key holds the index of the row in
the C<@multitable>.
diff --git a/tp/Texinfo/Report.pm b/tp/Texinfo/Report.pm
index 703935366a..d05261feb3 100644
--- a/tp/Texinfo/Report.pm
+++ b/tp/Texinfo/Report.pm
@@ -195,11 +195,11 @@ Texinfo to other formats. There is no promise of API
stability.
=head1 DESCRIPTION
-The Texinfo::Report module helps with error handling. It is
+The C<Texinfo::Report> module helps with error handling. It is
used by the Texinfo modules L<Texinfo::Parser> and
L<Texinfo::Convert::Converter>. To use this module, either create
-a new Texinfo::Report object or initialize another object
-such as to be able to call Texinfo::Report methods. In any
+a new C<Texinfo::Report> object or initialize another object
+such as to be able to call C<Texinfo::Report> methods. In any
case, C<Texinfo::Report::new()> is called to setup the module.
Besides the C<new> method, C<errors> is used for reporting errors, and the
@@ -209,7 +209,7 @@ other methods to store errors (and warnings).
No method is exported in the default case.
-The C<new> method initializes Texinfo::Report related fields.
+The C<new> method initializes C<Texinfo::Report> related fields.
The errors collected are available through the C<errors> method, the other
methods allow registering errors and warnings.
@@ -220,12 +220,12 @@ methods allow registering errors and warnings.
=item $converter->Texinfo::Report::new()
X<C<Texinfo::Report::new>>
-If called without argument, a Texinfo::Report object is initialized and
+If called without argument, a C<Texinfo::Report> object is initialized and
returned. This is how the module is used in the Texinfo Parsers, as
a separate object.
If called on a C<$converter>, the C<$converter> is initialized itself
-such as to be able to call Texinfo::Report methods. It is how it is
+such as to be able to call C<Texinfo::Report> methods. It is how it is
used in the Converters.
=item ($error_warnings_list, $error_count) = errors($registrar)
diff --git a/tp/Texinfo/Structuring.pm b/tp/Texinfo/Structuring.pm
index 423b839a7c..272e2cb633 100644
--- a/tp/Texinfo/Structuring.pm
+++ b/tp/Texinfo/Structuring.pm
@@ -103,7 +103,7 @@ $unnumbered_commands{'part'} = 1;
sub sectioning_structure($$$)
{
my $registrar = shift;
- my $configuration_information = shift;
+ my $customization_information = shift;
my $root = shift;
my $sec_root;
@@ -145,7 +145,7 @@ sub sectioning_structure($$$)
# new command is below
if ($previous_section->{'structure'}->{'section_level'} < $level) {
if ($level - $previous_section->{'structure'}->{'section_level'} > 1) {
- $registrar->line_error($configuration_information,
+ $registrar->line_error($customization_information,
sprintf(__("raising the section level of \@%s which is too low"),
$content->{'cmdname'}), $content->{'source_info'});
$content->{'structure'}->{'section_level'}
@@ -179,12 +179,12 @@ sub sectioning_structure($$$)
if ($content->{'cmdname'} eq 'part') {
$new_upper_part_element = 1;
if ($level < $up->{'structure'}->{'section_level'}) {
- $registrar->line_warn($configuration_information,
+ $registrar->line_warn($customization_information,
sprintf(__("no chapter-level command before \@%s"),
$content->{'cmdname'}), $content->{'source_info'});
}
} else {
- $registrar->line_warn($configuration_information,
+ $registrar->line_warn($customization_information,
sprintf(__("lowering the section level of \@%s appearing after a lower
element"),
$content->{'cmdname'}), $content->{'source_info'});
$content->{'structure'}->{'section_level'}
@@ -278,7 +278,7 @@ sub sectioning_structure($$$)
}
} elsif ($content->{'cmdname'} eq 'part'
and !$content->{'extra'}->{'part_associated_section'}) {
- $registrar->line_warn($configuration_information,
+ $registrar->line_warn($customization_information,
sprintf(__("no sectioning command associated with \@%s"),
$content->{'cmdname'}), $content->{'source_info'});
}
@@ -303,13 +303,13 @@ sub _print_sectioning_tree($)
sub warn_non_empty_parts($$$)
{
my $registrar = shift;
- my $configuration_information = shift;
+ my $customization_information = shift;
my $global_commands = shift;
if ($global_commands->{'part'}) {
foreach my $part (@{$global_commands->{'part'}}) {
if (!Texinfo::Common::is_content_empty($part)) {
- $registrar->line_warn($configuration_information,
+ $registrar->line_warn($customization_information,
sprintf(__("\@%s not empty"),
$part->{'cmdname'}), $part->{'source_info'});
}
@@ -357,7 +357,7 @@ my %direction_texts = (
sub _check_menu_entry($$$$$)
{
my $registrar = shift;
- my $configuration_information = shift;
+ my $customization_information = shift;
my $labels = shift;
my $command = shift;
my $menu_content = shift;
@@ -368,14 +368,14 @@ sub _check_menu_entry($$$$$)
my $menu_node = $labels->{$normalized_menu_node};
if (!$menu_node) {
- $registrar->line_error($configuration_information,
+ $registrar->line_error($customization_information,
sprintf(__("\@%s reference to nonexistent node `%s'"), $command,
node_extra_to_texi($menu_content->{'extra'}->{'menu_entry_node'})),
$menu_content->{'source_info'});
} else {
if (!_check_node_same_texinfo_code($menu_node,
$menu_content->{'extra'}->{'menu_entry_node'})) {
- $registrar->line_warn($configuration_information,
+ $registrar->line_warn($customization_information,
sprintf(__("\@%s entry node name `%s' different from %s name `%s'"),
$command,
node_extra_to_texi($menu_content->{'extra'}->{'menu_entry_node'}),
@@ -390,7 +390,7 @@ sub _check_menu_entry($$$$$)
# to try to generate menus automatically before checking.
sub check_nodes_are_referenced
{
- my ($registrar, $configuration_information, $nodes_list, $top_node, $labels,
$refs) = @_;
+ my ($registrar, $customization_information, $nodes_list, $top_node, $labels,
$refs) = @_;
return undef unless ($nodes_list and scalar(@{$nodes_list}));
@@ -426,7 +426,7 @@ sub check_nodes_are_referenced
foreach my $node (@{$nodes_list}) {
if (not exists($referenced_nodes{$node})) {
- $registrar->line_warn($configuration_information,
+ $registrar->line_warn($customization_information,
sprintf(__("node `%s' unreferenced"),
node_extra_to_texi($node->{'extra'})),
$node->{'source_info'});
@@ -438,7 +438,7 @@ sub check_nodes_are_referenced
sub set_menus_node_directions($$$$$$)
{
my $registrar = shift;
- my $configuration_information = shift;
+ my $customization_information = shift;
my $parser_information = shift;
my $global_commands = shift;
my $nodes_list = shift;
@@ -446,8 +446,8 @@ sub set_menus_node_directions($$$$$$)
return undef unless ($nodes_list and scalar(@{$nodes_list}));
- my $check_menu_entries = (!$configuration_information->get_conf('novalidate')
- and $configuration_information->get_conf('FORMAT_MENU') eq 'menu');
+ my $check_menu_entries = (!$customization_information->get_conf('novalidate')
+ and $customization_information->get_conf('FORMAT_MENU') eq 'menu');
# First go through all the menus and set menu_up, menu_next and menu_prev,
# and warn for unknown nodes.
@@ -460,7 +460,7 @@ sub set_menus_node_directions($$$$$$)
if ($node->{'extra'}->{'menus'}) {
if (@{$node->{'extra'}->{'menus'}} > 1) {
foreach my $menu (@{$node->{'extra'}->{'menus'}}[1 ..
$#{$node->{'extra'}->{'menus'}}]) {
- $registrar->line_warn($configuration_information,
+ $registrar->line_warn($customization_information,
sprintf(__("multiple \@%s"),
$menu->{'cmdname'}), $menu->{'source_info'});
}
@@ -478,7 +478,7 @@ sub set_menus_node_directions($$$$$$)
->{'menu_entry_node'}->{'normalized'}};
if ($check_menu_entries) {
- _check_menu_entry($registrar, $configuration_information,
+ _check_menu_entry($registrar, $customization_information,
$labels, 'menu', $menu_content);
}
# this may happen more than once for a given node if the node
@@ -518,7 +518,7 @@ sub set_menus_node_directions($$$$$$)
if ($menu_content->{'extra'}
and $menu_content->{'extra'}->{'menu_entry_node'}) {
if
(!$menu_content->{'extra'}->{'menu_entry_node'}->{'manual_content'}) {
- _check_menu_entry($registrar, $configuration_information,
+ _check_menu_entry($registrar, $customization_information,
$labels, 'detailmenu', $menu_content);
}
}
@@ -556,7 +556,7 @@ sub _section_direction_associated_node($$)
sub complete_node_tree_with_menus($$$$)
{
my $registrar = shift;
- my $configuration_information = shift;
+ my $customization_information = shift;
my $nodes_list = shift;
my $top_node = shift;
@@ -587,13 +587,13 @@ sub complete_node_tree_with_menus($$$$)
my $direction_associated_node
= _section_direction_associated_node($section, $direction);
if ($direction_associated_node) {
- if
($configuration_information->get_conf('CHECK_NORMAL_MENU_STRUCTURE')) {
+ if
($customization_information->get_conf('CHECK_NORMAL_MENU_STRUCTURE')) {
if ($section->{'structure'}->{'section_up'}{'extra'}
and
$section->{'structure'}->{'section_up'}{'extra'}{'associated_node'}
and
$section->{'structure'}->{'section_up'}{'extra'}{'associated_node'}{'menus'}
and
@{$section->{'structure'}->{'section_up'}{'extra'}{'associated_node'}{'menus'}}
and !$node->{'structure'}->{'menu_'.$direction}) {
- $registrar->line_warn($configuration_information,
+ $registrar->line_warn($customization_information,
sprintf(__("node %s for `%s' is `%s' in sectioning but not in
menu"),
$direction,
node_extra_to_texi($node->{'extra'}),
@@ -609,9 +609,9 @@ sub complete_node_tree_with_menus($$$$)
if (!$node->{'structure'}->{'node_'.$direction}
and $node->{'structure'}->{'menu_'.$direction}
and
!$node->{'structure'}->{'menu_'.$direction}->{'extra'}->{'manual_content'}) {
- if
($configuration_information->get_conf('CHECK_NORMAL_MENU_STRUCTURE')
+ if
($customization_information->get_conf('CHECK_NORMAL_MENU_STRUCTURE')
and $node->{'extra'}->{'associated_section'}) {
- $registrar->line_warn($configuration_information,
+ $registrar->line_warn($customization_information,
sprintf(__("node `%s' is %s for `%s' in menu but not in sectioning"),
node_extra_to_texi($node->{'structure'}->{'menu_'.$direction}->{'extra'}),
$direction,
@@ -648,13 +648,13 @@ sub complete_node_tree_with_menus($$$$)
# check consistency between node pointer and node entries menu order
if ($node->{'extra'}->{'normalized'} ne 'Top') {
foreach my $direction (@node_directions) {
- if ($configuration_information->get_conf('CHECK_NORMAL_MENU_STRUCTURE')
+ if ($customization_information->get_conf('CHECK_NORMAL_MENU_STRUCTURE')
and $node->{'structure'}->{'node_'.$direction}
and $node->{'structure'}->{'menu_'.$direction}
and $node->{'structure'}->{'menu_'.$direction}
ne $node->{'structure'}->{'node_'.$direction}
and not
$node->{'structure'}->{'menu_'.$direction}->{'extra'}->{'manual_content'}) {
- $registrar->line_warn($configuration_information,
+ $registrar->line_warn($customization_information,
sprintf(__("node %s pointer for `%s' is `%s' but %s is `%s' in
menu"),
$direction,
node_extra_to_texi($node->{'extra'}),
@@ -667,7 +667,7 @@ sub complete_node_tree_with_menus($$$$)
}
# check for node up / menu up mismatch
- if ($configuration_information->get_conf('CHECK_NORMAL_MENU_STRUCTURE')
+ if ($customization_information->get_conf('CHECK_NORMAL_MENU_STRUCTURE')
and $node->{'structure'}->{'node_up'}
# No check if node up is an external manual
and (!$node->{'structure'}->{'node_up'}->{'extra'}->{'manual_content'})
@@ -676,7 +676,7 @@ sub complete_node_tree_with_menus($$$$)
# check if up node has a menu
if ($node->{'structure'}->{'node_up'}->{'extra'}->{'menus'}
and @{$node->{'structure'}->{'node_up'}->{'extra'}->{'menus'}}) {
- $registrar->line_warn($configuration_information,
+ $registrar->line_warn($customization_information,
sprintf(
__("node `%s' lacks menu item for `%s' despite being its Up
target"),
node_extra_to_texi($node->{'structure'}->{'node_up'}->{'extra'}),
@@ -694,7 +694,7 @@ sub complete_node_tree_with_menus($$$$)
sub nodes_tree($$$$$)
{
my $registrar = shift;
- my $configuration_information = shift;
+ my $customization_information = shift;
my $parser_information = shift;
my $nodes_list = shift;
my $labels = shift;
@@ -763,10 +763,10 @@ sub nodes_tree($$$$$)
= $labels->{$node_direction->{'normalized'}};
$node->{'structure'}->{'node_'.$direction} = $node_target;
- if (!$configuration_information->get_conf('novalidate')
+ if (!$customization_information->get_conf('novalidate')
and !_check_node_same_texinfo_code($node_target,
$node_direction)) {
- $registrar->line_warn($configuration_information,
+ $registrar->line_warn($customization_information,
sprintf(
__("%s pointer `%s' (for node `%s') different from %s name
`%s'"),
$direction_texts{$direction},
@@ -777,10 +777,10 @@ sub nodes_tree($$$$$)
$node->{'source_info'});
}
} else {
- if ($configuration_information->get_conf('novalidate')) {
+ if ($customization_information->get_conf('novalidate')) {
$node->{'structure'}->{'node_'.$direction} = { 'extra' =>
$node_direction };
} else {
- $registrar->line_error($configuration_information,
+ $registrar->line_error($customization_information,
sprintf(__("%s reference to nonexistent `%s'"),
$direction_texts{$direction},
node_extra_to_texi($node_direction)),
@@ -1017,7 +1017,7 @@ sub _tree_unit_node($)
# other root elements could probably be used, in theory.
sub elements_directions($$$)
{
- my $configuration_information = shift;
+ my $customization_information = shift;
my $labels = shift;
my $tree_units = shift;
return if (!$tree_units or !@$tree_units);
@@ -1150,7 +1150,7 @@ sub elements_directions($$$)
}
# Use node up for Up if there is no section up.
# Not done in the default case.
- if ($configuration_information->get_conf('USE_UP_NODE_FOR_ELEMENT_UP')
+ if ($customization_information->get_conf('USE_UP_NODE_FOR_ELEMENT_UP')
and !$directions->{'Up'} and defined($node)
and $node->{'structure'}->{'node_up'}
and (!$node_top or ($node ne $node_top))) {
@@ -1166,7 +1166,7 @@ sub elements_directions($$$)
$tree_unit->{'structure'}->{'directions'} = $directions;
}
}
- if ($configuration_information->get_conf('DEBUG')) {
+ if ($customization_information->get_conf('DEBUG')) {
foreach my $tree_unit (@$tree_units) {
print STDERR "Directions($tree_unit): "
. print_element_directions($tree_unit)."\n";
@@ -1297,7 +1297,7 @@ sub print_element_directions($)
sub associate_internal_references($$$$$)
{
my $registrar = shift;
- my $configuration_information = shift;
+ my $customization_information = shift;
my $parser_information = shift;
my $labels = shift;
my $refs = shift;
@@ -1326,8 +1326,8 @@ sub associate_internal_references($$$$$)
$node_arg->{'normalized'} = $normalized;
if (!defined($labels->{$node_arg->{'normalized'}})) {
- if (!$configuration_information->get_conf('novalidate')) {
- $registrar->line_error($configuration_information,
+ if (!$customization_information->get_conf('novalidate')) {
+ $registrar->line_error($customization_information,
sprintf(__("\@%s reference to nonexistent node `%s'"),
$ref->{'cmdname'}, node_extra_to_texi($node_arg)),
$ref->{'source_info'});
@@ -1335,9 +1335,9 @@ sub associate_internal_references($$$$$)
} else {
my $node_target = $labels->{$node_arg->{'normalized'}};
$ref->{'extra'}->{'label'} = $node_target;
- if (!$configuration_information->get_conf('novalidate')
+ if (!$customization_information->get_conf('novalidate')
and !_check_node_same_texinfo_code($node_target, $node_arg)) {
- $registrar->line_warn($configuration_information,
+ $registrar->line_warn($customization_information,
sprintf(__("\@%s to `%s', different from %s name `%s'"),
$ref->{'cmdname'},
node_extra_to_texi($node_arg),
@@ -1586,14 +1586,14 @@ sub _sort_index_entries($$)
sub setup_index_entry_keys_formatting($)
{
- my $configuration_information = shift;
+ my $customization_information = shift;
# FIXME should the encoding be used by setting the
# copy_options_for_convert_text optional argument? The result does
# not seem so good.
my $options = {'sort_string' => 1, 'ascii_punctuation' => 1,
Texinfo::Convert::Text::copy_options_for_convert_text(
- $configuration_information)};
+ $customization_information)};
return $options;
}
@@ -1637,11 +1637,11 @@ sub index_entry_sort_string($$$$)
sub sort_indices($$$;$)
{
my $registrar = shift;
- my $configuration_information = shift;
+ my $customization_information = shift;
my $index_entries = shift;
my $sort_by_letter = shift;
- my $options = setup_index_entry_keys_formatting($configuration_information);
+ my $options = setup_index_entry_keys_formatting($customization_information);
my $sorted_index_entries;
my $index_entries_sort_strings = {};
foreach my $index_name (keys(%$index_entries)) {
@@ -1655,7 +1655,7 @@ sub sort_indices($$$;$)
$entry->{'sortas'}, $options);
$index_entries_sort_strings->{$entry} = $entry_key;
if ($entry_key !~ /\S/) {
- $registrar->line_warn($configuration_information,
+ $registrar->line_warn($customization_information,
sprintf(__("empty index key in \@%s"),
$entry->{'index_at_command'}),
$entry->{'command'}->{'source_info'});
@@ -1803,14 +1803,15 @@ with C<sort_indices>.
No method is exported in the default case.
Most methods takes a L<Texinfo::Report> C<$registrar> as argument for error
-reporting. Most also require configuration information, which means an object
-implementing the C<get_conf()> method, in practice the main program
-configuration or a converter. Other common input arguments such as parser
+reporting. Most also require Texinfo customization variables information,
+which means an object implementing the C<get_conf> method, in practice the main
+program configuration or a converter (L<Texinfo::Convert::Converter/Getting and
+setting customization variables>). Other common input arguments such as parser
information, labels or refs are obtained from a parser, see L<Texinfo::Parser>.
=over
-=item associate_internal_references($registrar, $configuration_information,
$parser_information, $labels, $refs)
+=item associate_internal_references($registrar, $customization_information,
$parser_information, $labels, $refs)
X<C<associate_internal_references>>
Verify that internal references (C<@ref> and similar without
@@ -1821,7 +1822,7 @@ references C<@ref> and similar @-commands. Set the
C<label> key in the
C<extra> hash of the reference tree element to the associated labeled tree
element. Register errors in I<$registrar>.
-=item check_nodes_are_referenced($registrar, $configuration_information,
$nodes_list, $top_node, $labels, $refs)
+=item check_nodes_are_referenced($registrar, $customization_information,
$nodes_list, $top_node, $labels, $refs)
X<C<check_nodes_are_referenced>>
Check that all the nodes are referenced (in menu, @*ref or node direction).
@@ -1830,14 +1831,14 @@ Register errors in I<$registrar>.
Should be called after C<complete_node_tree_with_menus> in order to
have the autogenerated menus available.
-=item complete_node_tree_with_menus($registrar, $configuration_information,
$nodes_list, $top_node)
+=item complete_node_tree_with_menus($registrar, $customization_information,
$nodes_list, $top_node)
X<C<complete_node_tree_with_menus>>
Complete nodes directions with menu directions. Check consistency
of menus, sectionning and nodes direction structures.
Register errors in I<$registrar>.
-=item elements_directions($configuration_information, $labels, $tree_units)
+=item elements_directions($customization_information, $labels, $tree_units)
X<C<elements_directions>>
Directions are set up for the tree unit elements in the array reference
@@ -1934,7 +1935,7 @@ that can be used to gather information. I<$sortas> can
be given to
override the sort string (typically obtained from C<@sortas>). The
I<$options> are options used for Texinfo to text conversion for
the generation of the sort string, typically obtained from
-L<setup_index_entry_keys_formatting|/$option =
setup_index_entry_keys_formatting($configuration_information)>.
+L<setup_index_entry_keys_formatting|/$option =
setup_index_entry_keys_formatting($customization_information)>.
=item $merged_entries = merge_indices($index_names)
X<C<merge_indices>>
@@ -1968,7 +1969,7 @@ Returns the texinfo tree corresponding to a single menu
entry pointing to
I<$node>. If I<$use_sections> is set, use the section name instead of node
name.
Returns C<undef> if the node argument is missing.
-=item $top_node = nodes_tree($registrar, $configuration_information,
$parser_information, $nodes_list, $labels)
+=item $top_node = nodes_tree($registrar, $customization_information,
$parser_information, $nodes_list, $labels)
X<C<nodes_tree>>
Goes through nodes and set directions. Returns the top
@@ -2002,7 +2003,7 @@ Return the sectioning command name corresponding to the
sectioning
element I<$element>, adjusted in order to take into account raised
and lowered sections, when needed.
-=item $sections_root, $sections_list = sectioning_structure($registrar,
$configuration_information, $tree)
+=item $sections_root, $sections_list = sectioning_structure($registrar,
$customization_information, $tree)
X<C<sectioning_structure>>
This function goes through the tree and gather information on
@@ -2048,7 +2049,7 @@ account C<@part> elements.
=back
-=item set_menus_node_directions($registrar, $configuration_information,
$parser_information, $global_commands, $nodes_list, $labels);
+=item set_menus_node_directions($registrar, $customization_information,
$parser_information, $global_commands, $nodes_list, $labels);
X<C<set_menus_node_directions>>
Goes through menu and set directions. Register errors in I<$registrar>.
@@ -2071,12 +2072,12 @@ Up, next and previous directions as set in menus.
=back
-=item $option = setup_index_entry_keys_formatting($configuration_information)
+=item $option = setup_index_entry_keys_formatting($customization_information)
X<C<setup_index_entry_keys_formatting>>
Return options for conversion of Texinfo to text relevant for index keys
sorting.
-=item ($index_entries_sorted, $index_entries_sort_strings) =
sort_indices($registrar, $configuration_information, $merged_index_entries,
$sort_by_letter)
+=item ($index_entries_sorted, $index_entries_sort_strings) =
sort_indices($registrar, $customization_information, $merged_index_entries,
$sort_by_letter)
X<C<sort_indices>>
If I<$sort_by_letter> is set, sort by letter, otherwise sort all
@@ -2161,7 +2162,7 @@ No splitting, only one page is returned, holding all the
tree units.
=back
-=item warn_non_empty_parts($registrar, $configuration_information,
$global_commands)
+=item warn_non_empty_parts($registrar, $customization_information,
$global_commands)
X<C<warn_non_empty_parts>>
Register a warning in I<$registrar> for each C<@part> that is not empty
diff --git a/tp/Texinfo/Transformations.pm b/tp/Texinfo/Transformations.pm
index a65078e221..f02f823845 100644
--- a/tp/Texinfo/Transformations.pm
+++ b/tp/Texinfo/Transformations.pm
@@ -795,7 +795,7 @@ sub _protect_hashchar_at_line_beginning($$$)
my $current = shift;
my $argument = shift;
- my ($registrar, $configuration_information) = @$argument;
+ my ($registrar, $customization_information) = @$argument;
#print STDERR "$type $current ".debug_print_element($current)."\n";
# if the next is a hash character at line beginning, mark it
@@ -839,7 +839,7 @@ sub _protect_hashchar_at_line_beginning($$$)
while ($parent) {
if ($parent->{'cmdname'} and $parent->{'source_info'}) {
if ($registrar) {
- $registrar->line_warn($configuration_information, sprintf(__(
+ $registrar->line_warn($customization_information, sprintf(__(
"could not protect hash character in \@%s"),
$parent->{'cmdname'}), $parent->{'source_info'});
}
@@ -865,11 +865,11 @@ sub _protect_hashchar_at_line_beginning($$$)
sub protect_hashchar_at_line_beginning($$$)
{
my $registrar = shift;
- my $configuration_information = shift;
+ my $customization_information = shift;
my $tree = shift;
return Texinfo::Common::modify_tree($tree,
\&_protect_hashchar_at_line_beginning,
- [$registrar,
$configuration_information]);
+ [$registrar,
$customization_information]);
}
1;
@@ -907,7 +907,7 @@ Add menu entries or whole menus for nodes associated with
sections,
based on the sectioning tree. If the optional
C<$add_section_names_in_entries> argument is set, a menu entry
name is added using the section name. This function should be
-called after L<sectioning_structure|Texinfo::Structuring/$sections_root,
$sections_list = sectioning_structure($registrar, $configuration_information,
$tree)>.
+called after L<sectioning_structure|Texinfo::Structuring/$sections_root,
$sections_list = sectioning_structure($registrar, $customization_information,
$tree)>.
=item complete_tree_nodes_missing_menu($tree, $use_section_names_in_entries)
X<C<complete_tree_nodes_missing_menu>>
@@ -916,7 +916,7 @@ Add whole menus for nodes associated with sections and
without menu,
based on the sectioning tree. If the optional
C<$add_section_names_in_entries> argument is set, a menu entry
name is added using the section name. This function should be
-called after L<sectioning_structure|Texinfo::Structuring/$sections_root,
$sections_list = sectioning_structure($registrar, $configuration_information,
$tree)>.
+called after L<sectioning_structure|Texinfo::Structuring/$sections_root,
$sections_list = sectioning_structure($registrar, $customization_information,
$tree)>.
=item ($root_content, $added_sections) = fill_gaps_in_sectioning($tree)
X<C<fill_gaps_in_sectioning>>
@@ -962,18 +962,18 @@ X<C<new_master_menu>>
Returns a detailmenu tree element formatted as a master node.
I<$translations>, if defined, should be a L<Texinfo::Translations> object and
-should also hold configuration information.
+should also hold customization information.
-=item protect_hashchar_at_line_beginning($registrar,
$configuration_information, $tree)
+=item protect_hashchar_at_line_beginning($registrar,
$customization_information, $tree)
X<C<protect_hashchar_at_line_beginning>>
Protect hash (#) character at the beginning of line such that they would not be
considered as lines to be processed by the CPP processor. The I<$registrar>
-and I<$configuration_information> arguments may be undef. If defined, the
+and I<$customization_information> arguments may be undef. If defined, the
I<$registrar> argument should be a L<Texinfo::Report> object in which the
errors and warnings encountered while parsing are registered. If defined,
-I<$configuration_information> should give access to configuration through
-C<get_conf()>. If both I<$registrar> and I<$configuration_information> are
+I<$customization_information> should give access to customization through
+C<get_conf>. If both I<$registrar> and I<$customization_information> are
defined they are used for error reporting in case an hash character could not
be protected because it appeared in a raw environment.
@@ -992,7 +992,7 @@ X<C<regenerate_master_menu>>
Regenerate the Top node master menu, replacing the first detailmenu
in Top node menus or appending at the end of the Top node menu.
I<$translations>, if defined, should be a L<Texinfo::Translations> object and
-should also hold configuration information.
+should also hold customization information.
=back
diff --git a/tp/Texinfo/Translations.pm b/tp/Texinfo/Translations.pm
index f655863d84..bf4c849a80 100644
--- a/tp/Texinfo/Translations.pm
+++ b/tp/Texinfo/Translations.pm
@@ -229,7 +229,7 @@ sub gdt($$;$$$)
# relevant information (if any). It could also mess with the parser
# state, though this has not been checked for a long time.
- # configuration only found in parser, not available through get_conf().
+ # information only found in parser, not available through get_conf().
# Note that it is only available for the NonXS parser.
my $parser_conf;
if ($current_parser) {
@@ -238,7 +238,7 @@ sub gdt($$;$$$)
if (defined($current_parser->{$duplicated_conf}));
}
}
- # general configuration relevant for parser
+ # general customization relevant for parser
if ($self) {
foreach my $conf_variable ('DEBUG') {
if (defined($self->get_conf($conf_variable))) {
@@ -420,7 +420,7 @@ Texinfo to other formats. There is no promise of API
stability.
=head1 DESCRIPTION
-The Texinfo::Translations module helps with translations
+The C<Texinfo::Translations> module helps with translations
in output documents.
Translation of error messages uses another interface which
@@ -449,9 +449,9 @@ some string, texinfo tree or array content that is
substituted in
the resulting texinfo tree. In the string to be translated word
in brace matching keys of I<$replaced_substrings> are replaced.
The I<$object> is typically a converter, but can be any object that implements
-C<get_conf()>, or undefined (C<undef>). If not undefined, the information in
the
+C<get_conf>, or undefined (C<undef>). If not undefined, the information in the
I<$object> is used to determine the encoding, the documentlanguage and get some
-configuration information. I<$lang> is optional. If set, it overrides the
+customization information. I<$lang> is optional. If set, it overrides the
documentlanguage.
=begin comment
@@ -464,7 +464,7 @@ documentation.
=end comment
For example, in the following call, the string
-I<See {reference} in @cite{{book}}> is translated, then
+C<See {reference} in @cite{{book}}> is translated, then
parsed as a Texinfo string, with I<{reference}> substituted by
I<$tree_reference> in the resulting tree, and I<{book}>
replaced by the associated texinfo tree text element:
diff --git a/tp/maintain/template.pod b/tp/maintain/template.pod
index 494225cb55..3bc57cbd8b 100644
--- a/tp/maintain/template.pod
+++ b/tp/maintain/template.pod
@@ -32,11 +32,13 @@ Texinfo::Convert::OUTFORMAT converts a Texinfo tree to
OUTFORMAT.
Initialize converter from Texinfo to OUTFORMAT.
The I<$options> hash reference holds options for the converter. In
-this option hash reference a parser object may be associated with the
-I<parser> key. The other options should be configuration options
-described in the Texinfo manual. Those options, when appropriate,
-override the document content. The parser should not be available
-directly anymore after getting the associated information.
+this option hash reference a L<parser object|Texinfo::Parser>
+may be associated with the I<parser> key. The other options
+are Texinfo customization options and a few other options that can
+be passed to the converter. Most of the customization options are described in
+the Texinfo manual. Those customization options, when appropriate, override
+the document content. The parser should not be available directly anymore
+after getting the associated information.
See L<Texinfo::Convert::Converter> for more information.
@@ -59,7 +61,7 @@ __HTML =item $result = $converter->output_internal_links()
__HTML X<C<output_internal_links>>
__HTML
__HTML Returns text representing the links in the document. The format should
-__HTML follow the C<--internal-links> option of the texi2any/makeinfo
+__HTML follow the C<--internal-links> option of the C<texi2any>
__HTML specification. This is only supported in (and relevant for) HTML.
__HTML
=back
diff --git a/util/texinfo.dtd b/util/texinfo.dtd
index ec9f5cb525..88a88fd16c 100644
--- a/util/texinfo.dtd
+++ b/util/texinfo.dtd
@@ -1,7 +1,7 @@
<!--
Document Type Definition for Texinfo XML output (the '-'-xml option).
- Copyright 2001-2019 Free Software Foundation, Inc.
+ Copyright 2001-2022 Free Software Foundation, Inc.
Copying and distribution of this file, with or without modification,
are permitted in any medium without royalty provided the copyright
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- branch master updated: Update POD documentation. Replace configuration by customization in code,
Patrice Dumas <=