[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[no subject]
|
From: |
Patrice Dumas |
|
Date: |
Sun, 6 Feb 2022 18:26:30 -0500 (EST) |
branch: master
commit d0061d0153c7500c661ddcb76bebad14b4dc2dff
Author: Patrice Dumas <pertusus@free.fr>
AuthorDate: Mon Feb 7 00:25:52 2022 +0100
Improve POD documentation and minor code/space change.
---
tp/Texinfo/Common.pm | 5 ++
tp/Texinfo/Convert/Converter.pm | 21 +++---
tp/Texinfo/Convert/DocBook.pm | 8 ++-
tp/Texinfo/Convert/HTML.pm | 5 ++
tp/Texinfo/Convert/Info.pm | 8 ++-
tp/Texinfo/Convert/NodeNameNormalization.pm | 5 ++
tp/Texinfo/Convert/Plaintext.pm | 8 ++-
tp/Texinfo/Convert/Texinfo.pm | 5 ++
tp/Texinfo/Convert/TexinfoXML.pm | 8 ++-
tp/Texinfo/Convert/Text.pm | 9 ++-
tp/Texinfo/Convert/Unicode.pm | 100 +++++++++++++++++-----------
tp/Texinfo/Convert/Utils.pm | 22 ++++--
tp/Texinfo/Encoding.pm | 7 +-
tp/Texinfo/ParserNonXS.pm | 35 +++++-----
tp/Texinfo/Report.pm | 5 ++
tp/Texinfo/Structuring.pm | 16 +++--
tp/Texinfo/Transformations.pm | 4 +-
tp/Texinfo/Translations.pm | 5 ++
tp/maintain/template.pod | 8 ++-
19 files changed, 195 insertions(+), 89 deletions(-)
diff --git a/tp/Texinfo/Common.pm b/tp/Texinfo/Common.pm
index 74c2f837f8..af7f71e0ed 100644
--- a/tp/Texinfo/Common.pm
+++ b/tp/Texinfo/Common.pm
@@ -2787,6 +2787,11 @@ Texinfo::Common - Classification of commands and
miscellaneous methods
print STDERR "$a_command is an accent command\n";
}
+=head1 DISCLAIMER
+
+The Texinfo Perl module main purpose is to be used in C<texi2any> to convert
+Texinfo to other formats. There is no promise of API stability.
+
=head1 DESCRIPTION
Texinfo::Common holds hashes with miscellaneous information and hashes
diff --git a/tp/Texinfo/Convert/Converter.pm b/tp/Texinfo/Convert/Converter.pm
index d4e1d5cc90..497ad06586 100644
--- a/tp/Texinfo/Convert/Converter.pm
+++ b/tp/Texinfo/Convert/Converter.pm
@@ -1412,11 +1412,11 @@ our %xml_text_entity_no_arg_commands_formatting = (
'aa' => 'å',
'AA' => 'Å',
'ae' => 'æ',
- 'oe' => 'œ', #pertusus: also œ. œ
not in html 3.2
+ 'oe' => 'œ', # œ not in html 3.2
'AE' => 'Æ',
- 'OE' => 'Œ', #pertusus: also Œ. Œ
not in html 3.2
- 'o' => 'ø',
- 'O' => 'Ø',
+ 'OE' => 'Œ', # Œ not in html 3.2
+ 'o' => 'ø',
+ 'O' => 'Ø',
'ss' => 'ß',
'DH' => 'Ð',
'dh' => 'ð',
@@ -1627,6 +1627,11 @@ Texinfo::Convert::Converter - Parent class for Texinfo
tree converters
{'parser' => $parser});
$converter->output($texinfo_tree);
+=head1 DISCLAIMER
+
+The Texinfo Perl module main purpose is to be used in C<texi2any> to convert
+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
@@ -1673,7 +1678,9 @@ 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.
+Those options, when appropriate, override the document content. The parser
+should not be available directly anymore after getting the associated
+information.
The C<converter> function returns a converter object (a blessed hash
reference) after checking the options and performing some initializations,
@@ -1735,9 +1742,7 @@ the resulting string is returned.
Create destination directory. I<$succeeded> is true if the creation was
successful or uneeded, false otherwise. I<$created_directory> is the directory
-actually created, which is, if possible, I<$destination_directory>, but can
also
-be different from I<$destination_directory> if I<$destination_directory>
-already exists as a file, output is split and there is an extension.
+actually created, which should be the same as I<$destination_directory>.
=item ($output_file, $destination_directory, $output_filename, $document_name,
$input_basefile) = $converter->determine_files_and_directory($output_format)
diff --git a/tp/Texinfo/Convert/DocBook.pm b/tp/Texinfo/Convert/DocBook.pm
index 5583a81599..a75f1b5d36 100644
--- a/tp/Texinfo/Convert/DocBook.pm
+++ b/tp/Texinfo/Convert/DocBook.pm
@@ -1485,6 +1485,11 @@ Texinfo::Convert::DocBook - Convert Texinfo tree to
DocBook
$converter->convert($tree);
$converter->convert_tree($tree);
+=head1 DISCLAIMER
+
+The Texinfo Perl module main purpose is to be used in C<texi2any> to convert
+Texinfo to other formats. There is no promise of API stability.
+
=head1 DESCRIPTION
Texinfo::Convert::DocBook converts a Texinfo tree to DocBook.
@@ -1513,8 +1518,7 @@ described in the Texinfo manual.
=item $result = $converter->convert($tree)
-Convert a Texinfo tree I<$tree> or tree portion and return
-the resulting output.
+Convert a Texinfo tree I<$tree> and return the resulting output.
=item $result = $converter->convert_tree($tree)
diff --git a/tp/Texinfo/Convert/HTML.pm b/tp/Texinfo/Convert/HTML.pm
index 5b1aa0f2d5..445a9a52dc 100644
--- a/tp/Texinfo/Convert/HTML.pm
+++ b/tp/Texinfo/Convert/HTML.pm
@@ -10181,6 +10181,11 @@ Texinfo::Convert::HTML - Convert Texinfo tree to HTML
$converter->convert_tree($tree);
$converter->output_internal_links(); # HTML only
+=head1 DISCLAIMER
+
+The Texinfo Perl module main purpose is to be used in C<texi2any> to convert
+Texinfo to other formats. There is no promise of API stability.
+
=head1 DESCRIPTION
Texinfo::Convert::HTML converts a Texinfo tree to HTML.
diff --git a/tp/Texinfo/Convert/Info.pm b/tp/Texinfo/Convert/Info.pm
index b81eafb1f0..3f162be8c6 100644
--- a/tp/Texinfo/Convert/Info.pm
+++ b/tp/Texinfo/Convert/Info.pm
@@ -578,6 +578,11 @@ Texinfo::Convert::Info - Convert Texinfo tree to Info
$converter->convert($tree);
$converter->convert_tree($tree);
+=head1 DISCLAIMER
+
+The Texinfo Perl module main purpose is to be used in C<texi2any> to convert
+Texinfo to other formats. There is no promise of API stability.
+
=head1 DESCRIPTION
Texinfo::Convert::Info converts a Texinfo tree to Info.
@@ -606,8 +611,7 @@ described in the Texinfo manual.
=item $result = $converter->convert($tree)
-Convert a Texinfo tree I<$tree> or tree portion and return
-the resulting output.
+Convert a Texinfo tree I<$tree> and return the resulting output.
=item $result = $converter->convert_tree($tree)
diff --git a/tp/Texinfo/Convert/NodeNameNormalization.pm
b/tp/Texinfo/Convert/NodeNameNormalization.pm
index ef41b0d3e8..91ec62dfab 100644
--- a/tp/Texinfo/Convert/NodeNameNormalization.pm
+++ b/tp/Texinfo/Convert/NodeNameNormalization.pm
@@ -371,6 +371,11 @@ Texinfo::Convert::NodeNameNormalization - Normalize and
transliterate Texinfo tr
my $file_name = transliterate_texinfo({'contents'
=> $section_contents});
+=head1 DISCLAIMER
+
+The Texinfo Perl module main purpose is to be used in C<texi2any> to convert
+Texinfo to other formats. There is no promise of API stability.
+
=head1 DESCRIPTION
Texinfo::Convert::NodeNameNormalization allows to normalize node names,
diff --git a/tp/Texinfo/Convert/Plaintext.pm b/tp/Texinfo/Convert/Plaintext.pm
index 9fad4ac035..59eb55ea81 100644
--- a/tp/Texinfo/Convert/Plaintext.pm
+++ b/tp/Texinfo/Convert/Plaintext.pm
@@ -3325,6 +3325,11 @@ Texinfo::Convert::Plaintext - Convert Texinfo tree to
Plaintext
$converter->convert($tree);
$converter->convert_tree($tree);
+=head1 DISCLAIMER
+
+The Texinfo Perl module main purpose is to be used in C<texi2any> to convert
+Texinfo to other formats. There is no promise of API stability.
+
=head1 DESCRIPTION
Texinfo::Convert::Plaintext converts a Texinfo tree to Plaintext.
@@ -3353,8 +3358,7 @@ described in the Texinfo manual.
=item $result = $converter->convert($tree)
-Convert a Texinfo tree I<$tree> or tree portion and return
-the resulting output.
+Convert a Texinfo tree I<$tree> and return the resulting output.
=item $result = $converter->convert_tree($tree)
diff --git a/tp/Texinfo/Convert/Texinfo.pm b/tp/Texinfo/Convert/Texinfo.pm
index ec513b610a..38222cae60 100644
--- a/tp/Texinfo/Convert/Texinfo.pm
+++ b/tp/Texinfo/Convert/Texinfo.pm
@@ -249,6 +249,11 @@ Texinfo::Convert::Texinfo - Convert a Texinfo tree to
Texinfo code
my $texinfo_text = convert_to_texinfo($tree);
+=head1 DISCLAIMER
+
+The Texinfo Perl module main purpose is to be used in C<texi2any> to convert
+Texinfo to other formats. There is no promise of API stability.
+
=head1 DESCRIPTION
Texinfo::Convert::Texinfo converts a Texinfo tree (described in
diff --git a/tp/Texinfo/Convert/TexinfoXML.pm b/tp/Texinfo/Convert/TexinfoXML.pm
index dcd23391d9..5ef491e7ef 100644
--- a/tp/Texinfo/Convert/TexinfoXML.pm
+++ b/tp/Texinfo/Convert/TexinfoXML.pm
@@ -1729,6 +1729,11 @@ Texinfo::Convert::TexinfoXML - Convert Texinfo tree to
TexinfoXML
$converter->convert($tree);
$converter->convert_tree($tree);
+=head1 DISCLAIMER
+
+The Texinfo Perl module main purpose is to be used in C<texi2any> to convert
+Texinfo to other formats. There is no promise of API stability.
+
=head1 DESCRIPTION
Texinfo::Convert::TexinfoXML converts a Texinfo tree to TexinfoXML.
@@ -1757,8 +1762,7 @@ described in the Texinfo manual.
=item $result = $converter->convert($tree)
-Convert a Texinfo tree I<$tree> or tree portion and return
-the resulting output.
+Convert a Texinfo tree I<$tree> and return the resulting output.
=item $result = $converter->convert_tree($tree)
diff --git a/tp/Texinfo/Convert/Text.pm b/tp/Texinfo/Convert/Text.pm
index e1f1f41a10..da7df8264a 100644
--- a/tp/Texinfo/Convert/Text.pm
+++ b/tp/Texinfo/Convert/Text.pm
@@ -833,6 +833,11 @@ Texinfo::Convert::Text - Convert Texinfo tree to simple
text
my $result_accent_text = ascii_accent('e', $accent_command);
my $accents_text = text_accents($accents, 'utf-8');
+=head1 DISCLAIMER
+
+The Texinfo Perl module main purpose is to be used in C<texi2any> to convert
+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
@@ -874,8 +879,8 @@ If set, the text is upper-cased.
=item code
-If set the text is in code style. (mostly --, ---, '' and `` are kept as
-is).
+If set the text is in code style. (mostly C<-->, C<--->, C<''> and C<``> are
+kept as is).
=item NUMBER_SECTIONS
diff --git a/tp/Texinfo/Convert/Unicode.pm b/tp/Texinfo/Convert/Unicode.pm
index c1ecb17d5d..290352cbdc 100644
--- a/tp/Texinfo/Convert/Unicode.pm
+++ b/tp/Texinfo/Convert/Unicode.pm
@@ -1576,7 +1576,7 @@ __END__
=head1 NAME
-Texinfo::Convert::Unicode - Handle conversion to Unicode
+Texinfo::Convert::Unicode - Representation as Unicode characters
=head1 SYNOPSIS
@@ -1592,61 +1592,37 @@ Texinfo::Convert::Unicode - Handle conversion to Unicode
my $accent_text = unicode_accent('e', $accent_command);
+=head1 DISCLAIMER
+
+The Texinfo Perl module main purpose is to be used in C<texi2any> to convert
+Texinfo to other formats. There is no promise of API stability.
+
=head1 DESCRIPTION
-Texinfo::Convert::Unicode provides methods that deals with unicode for
-converters. Unicode is important, because it is used internally in Perl
-for strings, therefore if converted to Unicode, a string could be output
-in other encodings as well when writting out the converted documents.
+Texinfo::Convert::Unicode provides methods dealing with Unicode representation
+and conversion of Unicode code points, to be used in converters.
-When an encoding is given as argument of a method of the module, the
-accented letters should only be converted to unicode if it is known that
-it will be possible to convert the unicode points to encoded characters
-in the encoding character set.
+When an encoding supported in Texinfo is given as argument of a method of the
+module, the accented letters or characters should only be represented by
Unicode
+code points if it is known that Perl should manage to convert the Unicode code
+points to encoded characters in the encoding character set. Note that the
+actual conversion is done by Perl, not by the module.
=head1 METHODS
=over
-=item $result = unicode_accent($text, $accent_command)
-
-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. The function returns the unicode representation of the accented
-character.
-
-=item $result = encoded_accents ($converter, $text, $stack, $encoding,
$format_accent, $set_case)
-
-I<$converter> is a converter object. It may be undef if there is no need of
-converter object in I<$format_accent> (I<$format_accent> described below).
-I<$text> is the text appearing within nested accent commands. I<$stack> is
-an array reference holding the nested accents texinfo element trees. For
-example, I<$text> could be the formatted content and I<$stack> the stack
-returned by C<Texinfo::Convert::Utils::find_innermost_accent_contents>.
I<$encoding>
-is the encoding the accented characters should be encoded to. If
-I<$encoding> not set the I<$result> is set to undef. I<$format_accent>
-is a function reference that is used to format the accent commands if
-there is no encoded character available for the encoding I<$encoding>
-at some point of the conversion of the I<$stack>. Last, if
-I<$set_case> is positive, the result is upper-cased, while if it is negative,
-the result is lower-cased.
-
-=item $result = unicode_text ($text, $in_code)
-
-Return I<$text> with characters encoded in unicode. If I<$in_code>
-is set, the text is considered to be in code style.
-
=item $result = brace_no_arg_command($command_name, $encoding)
-Return the text representing a command with brace and no argument
+Return the Unicode representation of a command with brace and no argument
I<$command_name> (like C<@bullet{}>, C<@aa{}> or C<@guilsinglleft{}>),
-or undef if there is no available encoded character for encoding
+or C<undef> if there the Unicode representation cannot be converted to encoding
I<$encoding>.
=item $possible_conversion = check_unicode_point_conversion($arg,
$output_debug)
Check that it is possible to output actual UTF-8 binary bytes
-corresponding to the Unicode codepoint string I<$args> (such as
+corresponding to the Unicode code point string I<$arg> (such as
C<201D>). Perl gives a warning and will not output UTF-8 for
Unicode non-characters such as U+10FFFF. If the optional
I<$output_debug> argument is set, a debugging output warning
@@ -1654,12 +1630,56 @@ is emitted if the test of the conversion failed.
Returns 1 if the conversion is possible and can be attempted,
0 otherwise.
+=item $result = encoded_accents($converter, $text, $stack, $encoding,
$format_accent, $set_case)
+
+I<$encoding> is the encoding the accented characters should be encoded to. If
+I<$encoding> not set, I<$result> is set to C<undef>. Nested accents and
+their content are passed with I<$text> and I<$stack>. I<$text> is the text
+appearing within nested accent commands. I<$stack> is an array reference
+holding the nested accents texinfo tree elements. In general, I<$text> is
+the formatted contents and I<$stack> the stack returned by
+L<Texinfo::Convert::Utils::find_innermost_accent_contents|Texinfo::Convert::Utils/(\@contents,
+\@accent_commands) = find_innermost_accent_contents($element)>. The function
+tries to convert as much as possible the accents to I<$encoding> starting from
the
+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
+converter object in I<$format_accent>.
+
+If I<$set_case> is positive, the result is upper-cased, while if it is
negative,
+the result is lower-cased.
+
=item $width = string_width($string)
Return the string width, taking into account the fact that some characters
have a zero width (like composing accents) while some have a width of 2
(most chinese characters, for example).
+=item $result = unicode_accent($text, $accent_command)
+
+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. The function returns the Unicode representation of the accented
+character.
+
+=item $is_decoded = unicode_point_decoded_in_encoding($encoding,
$unicode_point)
+
+Return true if the I<$unicode_point> will be encoded in the encoding
+I<$encoding>. The I<$unicode_point> should be specified as a four letter
+string describing an hexadecimal number with letters in upper case
+(such as C<201D>).
+
+If the encoding is not supported in Texinfo, the result will always be false.
+
+=item $result = unicode_text ($text, $in_code)
+
+Return I<$text> with dashes and quotes corresponding, for example to C<---> or
+C<'>, represented as Unicode code points. If I<$in_code> is set, the text is
+considered to be in code style.
+
=back
=head1 AUTHOR
diff --git a/tp/Texinfo/Convert/Utils.pm b/tp/Texinfo/Convert/Utils.pm
index bc2efa911e..0bfa149df9 100644
--- a/tp/Texinfo/Convert/Utils.pm
+++ b/tp/Texinfo/Convert/Utils.pm
@@ -137,10 +137,10 @@ sub definition_category($$)
}
# find the accent commands stack and the innermost text contents
-sub find_innermost_accent_contents($;$)
+sub find_innermost_accent_contents($)
{
my $current = shift;
- my $encoding = shift;
+
my @accent_commands = ();
my $debug = 0;
ACCENT:
@@ -170,8 +170,9 @@ sub find_innermost_accent_contents($;$)
my $text_contents = [];
foreach my $content (@{$arg->{'contents'}}) {
if (!($content->{'cmdname'} and ($content->{'cmdname'} eq 'c'
- or $content->{'cmdname'} eq 'comment'))) {
- if ($content->{'cmdname'} and
$Texinfo::Common::accent_commands{$content->{'cmdname'}}) {
+ or $content->{'cmdname'} eq
'comment'))) {
+ if ($content->{'cmdname'}
+ and $Texinfo::Common::accent_commands{$content->{'cmdname'}}) {
$current = $content;
next ACCENT;
} else {
@@ -313,6 +314,11 @@ Texinfo::Convert::Utils - miscellaneous functions usable
in all converters
my $verbatiminclude_tree
= expand_verbatiminclude(undef, $converter, $verbatiminclude);
+=head1 DISCLAIMER
+
+The Texinfo Perl module main purpose is to be used in C<texi2any> to convert
+Texinfo to other formats. There is no promise of API stability.
+
=head1 DESCRIPTION
miscellaneous methods that may be useful for backends converting texinfo
@@ -360,6 +366,14 @@ C<@verbatim> tree elements after finding the included file
and
reading it. If I<$registrar> is not defined, errors messages are
not registered.
+=item (\@contents, \@accent_commands) =
find_innermost_accent_contents($element)
+
+I<$element> should be an accent command Texinfo tree element. Returns
+an array reference containing the innermost accent command contents,
+normally a text element with one or two letter, and an array reference
+containing the accent commands nested in I<$element> (including
+I<$element>).
+
=item $result = numbered_heading ($converter, $heading_element, $heading_text,
$do_number)
The I<$converter> argument may be undef. I<$heading_element> is
diff --git a/tp/Texinfo/Encoding.pm b/tp/Texinfo/Encoding.pm
index cda0fa3513..1046bf872c 100644
--- a/tp/Texinfo/Encoding.pm
+++ b/tp/Texinfo/Encoding.pm
@@ -106,6 +106,11 @@ Texinfo::Encoding - Encodings and encoding aliases
my ($canonical_texinfo_encoding, $perl_encoding,
$canonical_output_encoding) = encoding_alias($encoding);
+=head1 DISCLAIMER
+
+The Texinfo Perl module main purpose is to be used in C<texi2any> to convert
+Texinfo to other formats. There is no promise of API stability.
+
=head1 DESCRIPTION
Texinfo::Encoding takes care of encoding definition and aliasing.
@@ -118,7 +123,7 @@ Texinfo::Encoding takes care of encoding definition and
aliasing.
Taking an encoding name as argument, the function returns the
corresponding canonical Texinfo encoding I<$canonical_texinfo_encoding>
-as described in the Texinfo manual (or undef), an encoding name suitable
+as described in the Texinfo manual (or C<undef>), an encoding name suitable
for perl I<$perl_encoding>, and an encoding name suitable for most
output formats, especially HTML, I<$canonical_output_encoding>.
diff --git a/tp/Texinfo/ParserNonXS.pm b/tp/Texinfo/ParserNonXS.pm
index 8278d83778..b2f73ab029 100644
--- a/tp/Texinfo/ParserNonXS.pm
+++ b/tp/Texinfo/ParserNonXS.pm
@@ -43,7 +43,7 @@ use Encode;
use File::Basename;
# Clone could be faster for small structures, which should be the case
-# here, but Clone is not in perl core modules, so we use Storable::dclone.
+# here, but Clone is not in Perl core modules, so we use Storable::dclone.
use Storable qw(dclone); # standard in 5.007003
# commands definitions
@@ -5975,7 +5975,10 @@ Texinfo::Parser - Parse Texinfo code into a Perl tree
use Texinfo::Parser;
my $parser = Texinfo::Parser::parser();
my $tree = $parser->parse_texi_file("somefile.texi");
- my ($errors, $errors_count) = $parser->errors();
+ # a Texinfo::Report object in which the errors and warnings
+ # encountered while parsing are registered.
+ my $registrar = $parser->registered_errors();
+ my ($errors, $errors_count) = $registrar->errors();
foreach my $error_message (@$errors) {
warn $error_message->{'error_line'};
}
@@ -5984,28 +5987,28 @@ Texinfo::Parser - Parse Texinfo code into a Perl tree
my $float_types_arrays = $parser->floats_information();
my $internal_references_array
= $parser->internal_references_information();
- # An hash reference on normalized node/float/anchor names
+ # $labels_information is an hash reference on normalized node/float/anchor
names.
my ($labels_information, $targets_list, $nodes_list) =
$parser->labels_information();
# A hash reference, keys are @-command names, value is an
# array reference holding all the corresponding @-commands.
my $global_commands_information = $parser->global_commands_information();
# a hash reference on document information (encodings,
- # input file name, dircategory and direntry list, for exampel).
+ # input file name, dircategory and direntry list, for example).
my $global_information = $parser->global_information();
- # a Texinfo::Report object in which the errors and warnings
- # encountered while parsing are registered.
- my $registrar = $parser->registered_errors();
+
+=head1 DISCLAIMER
+
+The Texinfo Perl module main purpose is to be used in C<texi2any> to convert
+Texinfo to other formats. There is no promise of API stability.
=head1 DESCRIPTION
-Texinfo::Parser will parse Texinfo text into a perl tree. In one pass
+Texinfo::Parser will parse Texinfo text into a Perl tree. In one pass
it expands user-defined @-commands, conditionals (@ifset, @ifinfo...)
and @value and constructs the tree. Some extra information is gathered
while doing the tree: for example, the block command associated with @end,
the number of rows in a multitable, or the node associated with a section.
-
-
=head1 METHODS
No method is exported in the default case. The module allows both
@@ -6104,7 +6107,7 @@ rooted at a C<document_root> type container.
=begin comment
The XS parser implements only part of the arguments and allows only a
-restricted set of arguments types compared to the perl parser. We want users
+restricted set of arguments types compared to the Perl parser. We want users
to use only what is in common, so document only what is in common.
=item $tree = parse_texi_line($parser, $text, $first_line_number, $file_name,
$macro_name, $fixed_line_number)
@@ -6137,7 +6140,7 @@ of a macro.
=begin comment
The XS parser implements only part of the arguments and allows only a
-restricted set of arguments types compared to the perl parser. We want users
+restricted set of arguments types compared to the Perl parser. We want users
to use only what is in common, so document only what is in common.
=item $tree = parse_texi_piece ($parser, $text, $line_numbers_specification,
$file_name, $macro_name, $fixed_line_number)
@@ -6168,7 +6171,7 @@ of a macro.
=begin comment
The XS parser implements only part of the arguments and allows only a
-restricted set of arguments types compared to the perl parser. We want users
+restricted set of arguments types compared to the Perl parser. We want users
to use only what is in common, so document only what is in common.
=item $tree = parse_texi_text ($parser, $text, $line_numbers_specification,
$file_name, $macro_name, $fixed_line_number)
@@ -6248,7 +6251,7 @@ in the document.
C<input_encoding_name> string is the encoding name used for the
Texinfo code.
-C<input_perl_encoding> string is a corresponding perl encoding name.
+C<input_perl_encoding> string is a corresponding Perl encoding name.
=item input_file_name
@@ -7183,7 +7186,7 @@ If in a C<@titlepage>, the titlepage is in I<titlepage>,
if in
C<@quotation> or C<@smallquotation>, the corresponding tree element
is in I<quotation>.
-The author tree element is in the I<author> array of the C<@titlepage>
+The author tree element is in the I<authors> array of the C<@titlepage>
or the C<@quotation> or C<@smallquotation> it is associated with.
=item C<@ifclear>
@@ -7200,7 +7203,7 @@ The corresponding @-command is in I<command>.
=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>.
+The corresponding Perl encoding name is in I<input_perl_encoding>.
=item C<@click>
diff --git a/tp/Texinfo/Report.pm b/tp/Texinfo/Report.pm
index 4888968125..49ffb66708 100644
--- a/tp/Texinfo/Report.pm
+++ b/tp/Texinfo/Report.pm
@@ -236,6 +236,11 @@ Texinfo::Report - Error storing for Texinfo modules
warn $error_message->{'error_line'};
}
+=head1 DISCLAIMER
+
+The Texinfo Perl module main purpose is to be used in C<texi2any> to convert
+Texinfo to other formats. There is no promise of API stability.
+
=head1 DESCRIPTION
The Texinfo::Report module helps with error handling. It is
diff --git a/tp/Texinfo/Structuring.pm b/tp/Texinfo/Structuring.pm
index b1f7c7df02..389db82149 100644
--- a/tp/Texinfo/Structuring.pm
+++ b/tp/Texinfo/Structuring.pm
@@ -1737,6 +1737,11 @@ Texinfo::Structuring - information on Texinfo::Parser
tree
}
+=head1 DISCLAIMER
+
+The Texinfo Perl module main purpose is to be used in C<texi2any> to convert
+Texinfo to other formats. There is no promise of API stability.
+
=head1 DESCRIPTION
Texinfo::Structuring first allows to collect information on a Texinfo tree.
@@ -1774,12 +1779,11 @@ with C<sort_indices>.
No method is exported in the default case.
-Most methods takes a Texinfo::Report C<$registrar> as argument
-for error reporting, see L<Texinfo::Report>. Most also require
-configuration information, which means an object implementing
-the get_conf() method, in practice the main program configuration
-or a converter. Other common input arguments such as parser information,
-labels or refs are obtained from a parser, see L<Texinfo::Parser>.
+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
+information, labels or refs are obtained from a parser, see L<Texinfo::Parser>.
=over
diff --git a/tp/Texinfo/Transformations.pm b/tp/Texinfo/Transformations.pm
index 5d40db3d0c..7ef2cbcff7 100644
--- a/tp/Texinfo/Transformations.pm
+++ b/tp/Texinfo/Transformations.pm
@@ -843,7 +843,7 @@ __END__
=head1 NAME
-Texinfo::Transformations - transformations of Texinfo::Parser.pm tree
+Texinfo::Transformations - transformations of Texinfo Perl tree
=head1 DISCLAIMER
@@ -930,7 +930,7 @@ and I<$configuration_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
+C<get_conf()>. If both I<$registrar> and I<$configuration_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.
diff --git a/tp/Texinfo/Translations.pm b/tp/Texinfo/Translations.pm
index 8b2d0eb7ae..97928b6550 100644
--- a/tp/Texinfo/Translations.pm
+++ b/tp/Texinfo/Translations.pm
@@ -413,6 +413,11 @@ Texinfo::Translations - Translations of output documents
strings for Texinfo mod
'book' => {'text' => $book_name}});
+=head1 DISCLAIMER
+
+The Texinfo Perl module main purpose is to be used in C<texi2any> to convert
+Texinfo to other formats. There is no promise of API stability.
+
=head1 DESCRIPTION
The Texinfo::Translations module helps with translations
diff --git a/tp/maintain/template.pod b/tp/maintain/template.pod
index dfb4f0ce05..a7838e555e 100644
--- a/tp/maintain/template.pod
+++ b/tp/maintain/template.pod
@@ -14,6 +14,11 @@ Texinfo::Convert::OUTFORMAT - Convert Texinfo tree to
OUTFORMAT
$converter->convert_tree($tree);
__HTML $converter->output_internal_links(); # HTML only
+=head1 DISCLAIMER
+
+The Texinfo Perl module main purpose is to be used in C<texi2any> to convert
+Texinfo to other formats. There is no promise of API stability.
+
=head1 DESCRIPTION
Texinfo::Convert::OUTFORMAT converts a Texinfo tree to OUTFORMAT.
@@ -42,8 +47,7 @@ described in the Texinfo manual.
=item $result = $converter->convert($tree)
-Convert a Texinfo tree I<$tree> or tree portion and return
-the resulting output.
+Convert a Texinfo tree I<$tree> and return the resulting output.
=item $result = $converter->convert_tree($tree)