[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[no subject]
|
From: |
Patrice Dumas |
|
Date: |
Wed, 10 Apr 2024 05:13:32 -0400 (EDT) |
branch: master
commit 8c87fd10b38a2a2b77432e9793f26597052661be
Author: Patrice Dumas <pertusus@free.fr>
AuthorDate: Wed Apr 10 11:13:09 2024 +0200
* tp/Texinfo/Report.pm (new): remove the possibility to reuse an
object.
Update POD documentation.
---
ChangeLog | 7 ++++
tp/Texinfo/Convert/TexinfoMarkup.pm | 4 +--
tp/Texinfo/Convert/Unicode.pm | 5 +--
tp/Texinfo/Convert/Utils.pm | 8 ++---
tp/Texinfo/Document.pm | 7 ++++
tp/Texinfo/Indices.pm | 32 ++++++++++--------
tp/Texinfo/Report.pm | 66 ++++++++++++++-----------------------
tp/Texinfo/Transformations.pm | 5 +--
tp/Texinfo/Translations.pm | 43 +++++++++++++++++-------
9 files changed, 100 insertions(+), 77 deletions(-)
diff --git a/ChangeLog b/ChangeLog
index a969677044..94b3ff03da 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,10 @@
+2024-04-10 Patrice Dumas <pertusus@free.fr>
+
+ * tp/Texinfo/Report.pm (new): remove the possibility to reuse an
+ object.
+
+ Update POD documentation.
+
2024-04-09 Patrice Dumas <pertusus@free.fr>
* tp/texi2any.pl: call Texinfo::Convert::Texinfo->import(). Move code
diff --git a/tp/Texinfo/Convert/TexinfoMarkup.pm
b/tp/Texinfo/Convert/TexinfoMarkup.pm
index d6bd26adef..4d4c0c83d7 100644
--- a/tp/Texinfo/Convert/TexinfoMarkup.pm
+++ b/tp/Texinfo/Convert/TexinfoMarkup.pm
@@ -1690,7 +1690,7 @@ called by C<Texinfo::Convert::TexinfoMarkup>.
The Texinfo Markup Language elements and attributes are not documented,
but the Texinfo XML output by the C<Texinfo::Convert::TexinfoXML> subclass
(L<Texinfo::Convert::TexinfoXML>) is a straightforward formatting as XML,
-and is described by the texinfo DTD. Therefore the texinfo DTD can be
+and is described by the Texinfo DTD. Therefore the Texinfo DTD can be
used as a description of the structure of both Texinfo XML and of the
more abstract Texinfo Markup Language.
@@ -1741,7 +1741,7 @@ Called to format a header at the beginning of output
files.
=item $result = $converter->txi_markup_protect_text($string)
Protect special character in text for text fragments out of text
-texinfo tree elements. For example, for spaces at end of line that
+Texinfo tree elements. For example, for spaces at end of line that
are ignorable in most output formats, for C<@set> or C<@macro>
arguments.
diff --git a/tp/Texinfo/Convert/Unicode.pm b/tp/Texinfo/Convert/Unicode.pm
index 5048d0e511..cd16fbec45 100644
--- a/tp/Texinfo/Convert/Unicode.pm
+++ b/tp/Texinfo/Convert/Unicode.pm
@@ -1757,8 +1757,9 @@ Texinfo to other formats. There is no promise of API
stability.
=head1 DESCRIPTION
-C<Texinfo::Convert::Unicode> provides methods dealing with Unicode
representation
-and conversion of Unicode code points, to be used in converters.
+C<Texinfo::Convert::Unicode> provides methods dealing with Unicode
+representation and conversion of Unicode code points, to be used in Texinfo
+converters.
When an encoding supported in Texinfo is given as argument of a method of the
module, the accented letters or characters returned by the method should only
diff --git a/tp/Texinfo/Convert/Utils.pm b/tp/Texinfo/Convert/Utils.pm
index cb66a01b93..cec41ca5d6 100644
--- a/tp/Texinfo/Convert/Utils.pm
+++ b/tp/Texinfo/Convert/Utils.pm
@@ -560,7 +560,7 @@ Texinfo to other formats. There is no promise of API
stability.
=head1 DESCRIPTION
-miscellaneous methods that may be useful for backends converting texinfo
+Miscellaneous methods that may be useful for backends converting Texinfo
trees. This module contains the methods that can be used in converters
which do not inherit from L<Texinfo::Convert::Converter>.
@@ -608,8 +608,8 @@ will be C<undef>.
X<C<definition_category_tree>>
The I<$converter> argument may be undef. I<$def_line> is a
-C<def_line> texinfo tree container. This function
-returns a texinfo tree corresponding to the category of the
+C<def_line> Texinfo tree container. This function
+returns a Texinfo tree corresponding to the category of the
I<$def_line> taking the class into account, if there is one.
If I<$converter> is not defined, the resulting string won't be
translated.
@@ -635,7 +635,7 @@ on the input file encoding where the file name appeared.
=item $tree = expand_today($converter)
X<C<expand_today>>
-Expand today's date, as a texinfo tree with translations. The I<$converter>
+Expand today's date, as a Texinfo tree with translations. The I<$converter>
argument is not optional and is used both to retrieve customization information
and to translate strings.
diff --git a/tp/Texinfo/Document.pm b/tp/Texinfo/Document.pm
index 73318940cc..3966fcee71 100644
--- a/tp/Texinfo/Document.pm
+++ b/tp/Texinfo/Document.pm
@@ -805,6 +805,13 @@ the best to use for output.
When simply sorting, the array of the sorted index entries is associated
with the index name.
+The optional I<$customization_information> argument is used for
+error reporting, both to find the L<Texinfo::Report> object to use for error
+reporting and Texinfo customization variables information. In general, it
+should be a converter (L<Texinfo::Convert::Converter/Getting and setting
+customization variables>) or a document L<Texinfo::Document/Getting
+customization options values registered in document>).
+
L<<
C<Texinfo::Indices::sort_indices_by_index>|Texinfo::Indices/$index_entries_sorted
= sort_indices_by_index($document, $registrar, $customization_information,
$use_unicode_collation, $locale_lang) >>
and L<<
C<Texinfo::Indices::sort_indices_by_letter>|Texinfo::Indices/$index_entries_sorted
= sort_indices_by_letter($document, $registrar, $customization_information,
$use_unicode_collation, $locale_lang) >>
are used to sort the indices, if needed.
diff --git a/tp/Texinfo/Indices.pm b/tp/Texinfo/Indices.pm
index 0f824d79c1..c7e4908243 100644
--- a/tp/Texinfo/Indices.pm
+++ b/tp/Texinfo/Indices.pm
@@ -761,15 +761,19 @@ X<C<index_entry_element_sort_string>>
Return a string suitable as a sort string, for index entries.
I<$document_info> is used by C code to retrieve the document data,
using the C<document_descriptor> key. I<$document_info> can be a
-converter based on L<Texinfo::Convert::Converter>, otherwise
-C<document_descriptor> need, in general, to be set up explicitely.
+converter based on L<Texinfo::Convert::Converter>, a L<Texinfo::Document>
+document, otherwise C<document_descriptor> need, in general, to be
+set up explicitely.
+
The tree element index entry processed is I<$index_entry_element>,
and can be a C<@subentry>. I<$main_entry> is the main index entry
-that can be used to gather information. The I<$options> are options
-used for Texinfo to text conversion for the generation of the sort
-string. If the sort string is supposed to be output, the I<$options>
-are typically obtained from
+that can be used to gather information.
+
+The I<$options> are options used for Texinfo to text conversion for the
+generation of the sort string. If the sort string is supposed to be output,
+the I<$options> are typically obtained from
L<setup_index_entry_keys_formatting|/$option =
setup_index_entry_keys_formatting($customization_information)>.
+
If I<$prefer_reference_element> is set, prefer an untranslated
element for the formatting as sort string.
@@ -840,14 +844,14 @@ When simply sorting, the array of the sorted index
entries is associated
with the index name.
The I<$registrar> argument can be set to a L<Texinfo::Report> object.
-Error reporting 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>) as I<$customization_information> argument.
-If the C<$registrar> argument is not set, the object used to
-get customization information is assumed to be a converter, and the
-error reporting uses converters error messages reporting functions
+Error reporting also requires Texinfo customization variables
+information, which means an object implementing the C<get_conf> method, a
+converter (L<Texinfo::Convert::Converter/Getting and setting customization
+variables>) or a document L<Texinfo::Document/Getting customization options
+values registered in document>) as I<$customization_information> argument. If
+the C<$registrar> argument is not set, the object used to get customization
+information is assumed to be a converter, and the error reporting uses
+converters error messages reporting functions
(L<Texinfo::Convert::Converter/Registering error and warning messages>).
In general, those methods should not be called directly, instead
diff --git a/tp/Texinfo/Report.pm b/tp/Texinfo/Report.pm
index 274f1e3ddf..e5b4c5015c 100644
--- a/tp/Texinfo/Report.pm
+++ b/tp/Texinfo/Report.pm
@@ -45,20 +45,11 @@ sub __p($$) {
return Locale::Messages::dpgettext($messages_textdomain, $context, $msgid);
}
-
-
-sub new(;$)
+sub new()
{
- my $self = shift;
- # if there is no argument, setup a separate Texinfo::Report object,
- # otherwise the structure is added to the converter, nothing is "blessed".
- if (not defined($self)) {
- $self = {};
- bless $self;
- }
- $self->{'errors_warnings'} = [];
- #print STDERR "REPORT NEW $self $self->{'errors_warnings'}\n";
- $self->{'errors_nrs'} = 0;
+ my $self = {'errors_warnings' => [],
+ 'errors_nrs' => 0,};
+ bless $self;
return $self;
}
@@ -80,6 +71,7 @@ sub add_formatted_message($$)
push @{$self->{'errors_warnings'}}, $message;
}
+# TODO document? Or consider that this method is internal?
sub format_line_message($$$$;$)
{
my $type = shift;
@@ -273,37 +265,25 @@ Texinfo to other formats. There is no promise of API
stability.
=head1 DESCRIPTION
-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 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
-other methods to store errors (and warnings).
+The C<Texinfo::Report> module helps with error handling. Errors
+and warnings can be setup, stored and retrieved later on.
+This module is used by the Texinfo modules L<Texinfo::Parser> and
+L<Texinfo::Convert::Converter>.
=head1 METHODS
No method is exported in the default case.
-The C<new> method initializes C<Texinfo::Report> related fields.
+The C<new> method initializes a C<Texinfo::Report> object.
The errors collected are available through the C<errors> method, the other
methods allow registering errors and warnings.
=over
=item my $registrar = Texinfo::Report::new()
-
-=item $object->Texinfo::Report::new()
X<C<Texinfo::Report::new>>
-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 an object C<$object>, the C<$object> is initialized itself
-such as to be able to call C<Texinfo::Report> methods.
+Return an initialized C<Texinfo::Report> object.
=item ($error_warnings_list, $error_count) = errors($registrar)
X<C<errors>>
@@ -315,31 +295,35 @@ the following keys:
=over
-=item type
+=item continuation
-May be C<warning>, or C<error>.
-
-=item text
-
-The text of the error.
+If set, the line is a continuation line of a message.
=item error_line
The text of the error formatted with the macro name, as needed.
-=item line_nr
-
-The line number of the error or warning.
-
=item file_name
The file name where the error or warning occurs.
+=item line_nr
+
+The line number of the error or warning.
+
=item macro
The user macro name that is expanded at the location of
the error or warning.
+=item text
+
+The text of the error.
+
+=item type
+
+May be C<warning>, or C<error>.
+
=back
=item $registrar->add_formatted_message ($msg)
diff --git a/tp/Texinfo/Transformations.pm b/tp/Texinfo/Transformations.pm
index e88f0e8b6a..c24d6d9168 100644
--- a/tp/Texinfo/Transformations.pm
+++ b/tp/Texinfo/Transformations.pm
@@ -939,7 +939,7 @@ __END__
=head1 NAME
-Texinfo::Transformations - transformations of Texinfo Perl tree
+Texinfo::Transformations - transformations of Texinfo tree
=head1 NOTES
@@ -1027,7 +1027,8 @@ errors and warnings encountered while parsing are
registered. If defined,
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.
+be protected because it appeared in a raw formatted environment (C<@tex>,
+C<@html>...).
=item $modified_tree = reference_to_arg_in_tree($tree)
X<C<reference_to_arg_in_tree>>
diff --git a/tp/Texinfo/Translations.pm b/tp/Texinfo/Translations.pm
index 8571c6daff..fb9ed212ab 100644
--- a/tp/Texinfo/Translations.pm
+++ b/tp/Texinfo/Translations.pm
@@ -556,32 +556,33 @@ For C<gdt>, the value is a Texinfo tree that is
substituted in the
resulting texinfo tree. For C<gdt_string>, the value is a string that
is replaced in the resulting string.
-I<$debug_level> is an optional debugging level supplied to gdt, similar to the
-C<DEBUG> customization variable. If set, the debug level minus one is passed
to
-the parser.
+I<$debug_level> is an optional debugging level supplied to C<gdt>, similar to
+the C<DEBUG> customization variable. If set, the debug level minus one is
+passed to the Texinfo string parser called in C<gdt>.
The I<$translation_context> is optional. If not C<undef> this is a translation
context string for I<$string>. It is the first argument of C<pgettext>
in the C API of Gettext.
-The I<$translate_string_method> is optional. If not undef it should be a
-reference on a function that is called instead of C<translate_string>. It
-allows to customize string translation. The I<$object> is passed as first
-argument of the <$translate_string_method>.
-
For example, in the following call, the string
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:
- $tree = gdt('See {reference} in @cite{{book}}',
- $converter->get_conf('documentlanguage'),
+ $tree = gdt('See {reference} in @cite{{book}}', "ca",
{'reference' => $tree_reference,
'book' => {'text' => $book_name}});
-C<gdt> uses a gettext-like infrastructure to retrieve the
-translated strings, using the I<texinfo_document> domain.
+By default, C<gdt> and C<gdt_string> call C<translate_string> to use a
+gettext-like infrastructure to retrieve the translated strings, using the
+I<texinfo_document> domain. You can change the method used to retrieve the
+translated strings by providing a I<$translate_string_method> argument. If not
+undef it should be a reference on a function that is called instead of
+C<translate_string>. The I<$object> is passed as first argument of the
+I<$translate_string_method>, the other arguments are the same as
+L<< C<translate_string>|/$translated_string = translate_string($string, $lang,
$translation_context) >>
+arguments.
=item $tree = pgdt($translation_context, $string, $lang, $replaced_substrings,
$debug_level)
X<C<pgdt>>
@@ -593,6 +594,24 @@ in the Gettext C API.
=back
+By default, in C<gdt>, C<gdt_string> and C<pgdt> a string is translated with
+C<translate_string>.
+
+=over
+
+=item $translated_string = translate_string($string, $lang,
$translation_context)
+X<C<translate_string>>
+
+The I<$string> is a string to be translated. I<$lang> is the language used for
+the translation. The I<$translation_context> is optional. If not C<undef>
+this is a translation context string for I<$string>. It is the first argument
+of C<pgettext> in the C API of Gettext.
+
+C<translate_string> uses a gettext-like infrastructure to retrieve the
+translated strings, using the I<texinfo_document> domain.
+
+=back
+
=head1 SEE ALSO
L<GNU gettext utilities manual|https://www.gnu.org/software/gettext/manual/>.