[no subject]

[Patrice Dumas]

branch: master
commit 296c1272ab2bcf8bd96c0d8817a9f3999a150a98
Author: Patrice Dumas <pertusus@free.fr>
AuthorDate: Tue Dec 26 18:49:35 2023 +0100

    * tp/Texinfo/Convert/Converter.pm: document functions in converter for
    error and warning messages registration.
    
    * doc/texi2any_api.texi (Converter Object and Conversion Functions)
    (Error Reporting in User Defined Functions): replace Texinfo::Report
    functions by Texinfo::Converter::Convert uses for error reporting.
---
 ChangeLog                       |  9 +++++++
 doc/texi2any_api.texi           | 55 +++++++++++++++++------------------------
 tp/Texinfo/Convert/Converter.pm | 48 +++++++++++++++++++++++++++++++++++
 3 files changed, 79 insertions(+), 33 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 566f855924..6fa544dbfc 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -8,6 +8,15 @@
        * tp/Texinfo/Convert/Plaintext.pm (_align_lines):
        Remove unused variable.
 
+2023-12-26  Patrice Dumas  <pertusus@free.fr>
+
+       * tp/Texinfo/Convert/Converter.pm: document functions in converter for
+       error and warning messages registration.
+
+       * doc/texi2any_api.texi (Converter Object and Conversion Functions)
+       (Error Reporting in User Defined Functions): replace Texinfo::Report
+       functions by Texinfo::Converter::Convert uses for error reporting.
+
 2023-12-26  Patrice Dumas  <pertusus@free.fr>
 
        * tp/Texinfo/XS/convert/get_html_perl_info.c,
diff --git a/doc/texi2any_api.texi b/doc/texi2any_api.texi
index 9b7c243007..db2b3acf45 100644
--- a/doc/texi2any_api.texi
+++ b/doc/texi2any_api.texi
@@ -1338,12 +1338,12 @@ object.  This object gives access to methods to get 
information on the
 conversion context and to methods useful for the conversion, both as an HTML
 converter and as a generic @code{Texinfo::Convert::Converter}
 (@pxref{Texinfo::Convert::Converter Helper methods,,,texi2any_internals}).  The
-converter can also be used for error reporting as it is also a
-@code{Texinfo::Report} object (@pxref{Texinfo::Report,,,texi2any_internals}),
-and for in-document strings translation as it is also a
-@code{Texinfo::Translations} object (@pxref{Texinfo::Translations,,,
-texi2any_internals}).  @xref{Error Reporting in User Defined Functions} on
-error reporting.
+converter can be used for error reporting by using
+@code{Texinfo::Convert::Converter} methods. @xref{Error
+Reporting in User Defined Functions} on error reporting.
+The converter can also be used for
+in-document strings translation as it is also a @code{Texinfo::Translations}
+object (@pxref{Texinfo::Translations,,, texi2any_internals}).
 
 
 @node Texinfo Tree Conversion Functions
@@ -1402,49 +1402,38 @@ a Texinfo tree conversion.
 @subsection Error Reporting in User Defined Functions
 
 @cindex Error reporting @subentry conversion
-@cindex @code{Texinfo::Report}
+@cindex @code{Texinfo::Convert::Converter} @subentry error reporting
 
 To report an error or a warning in a user defined function, use the methods
-of @code{Texinfo::Report} through a converter object
+of @code{Texinfo::Convert::Converter} through a converter object
 (@pxref{Converter Object and Conversion Functions}).
 
 To report a warning or an error not specific of an element conversion,
-use @code{document_warn} or @code{document_error}:
+use @code{converter_document_warn} or @code{converter_document_error}:
 
-@defun @var{$converter}->document_error ($text, $converter)
-@defunx @var{$converter}->document_warn ($text, $converter)
+@defun @var{$converter}->converter_document_error ($text, $continuation)
+@defunx @var{$converter}->converter_document_warn ($text, $continuation)
 Register a document-wide error or warning.  @var{$text} is the error
-or warning message.  The @var{$converter} object should be given
-as the second argument.
+or warning message.
+
+The optional @var{$continuation} argument, if set, conveys that the message
+is a continuation of the previous registered message.
 @end defun
 
 To report a warning or an error in element conversion, use
-@code{line_warn} or @code{line_error}
-@defun @var{$converter}->line_error ($text, $converter, $location_info, 
$continuation, $silent)
-@defunx @var{$converter}->line_warn ($text, $converter, $location_info, 
$continuation, $silent)
+@code{converter_line_warn} or @code{converter_line_error}
+@defun @var{$converter}->converter_line_error ($text, $location_info, 
$continuation)
+@defunx @var{$converter}->converter_line_warn ($text, $location_info, 
$continuation)
 Register a warning or an error.  @var{$text} is the text of the
-error or warning.  The @var{$converter} object should be given
-as the second argument.  The optional
-@var{$location_info} holds the information on the error or
-warning location.  The @var{$location_info} reference on hash may be
+error or warning.  The @var{$location_info} holds the information on the
+error or warning location.  The @var{$location_info} reference on hash may be
 obtained from Texinfo elements @code{source_info} keys.
 
 The optional @var{$continuation} argument, if set, conveys that the message
-is a continuation of the previous registered message.  The optional
-@var{$silent} argument, if set, suppresses the immediate output of a message
-if the @code{DEBUG} customization variable is set.
+is a continuation of the previous registered message.
 @end defun
 
-In general, registering an error does not stop the processing, in
-particular it does not stop the main conversion of the Texinfo tree.
-Write initialization files as if the conversion always continued
-after registering the error.
-
-@xref{Texinfo::Report,,,texi2any_internals} for more on
-@code{Texinfo::Report}.
-@c @xref{Init File Calling at Different Stages} for information on how
-@c to stop the processing from user defined functions called at different
-@c stages.
+Note that registering an error does not stop the processing of the Texinfo 
tree.
 
 
 @node Texinfo Tree Elements in User Defined Functions
diff --git a/tp/Texinfo/Convert/Converter.pm b/tp/Texinfo/Convert/Converter.pm
index 966ae2685b..1693d22a32 100644
--- a/tp/Texinfo/Convert/Converter.pm
+++ b/tp/Texinfo/Convert/Converter.pm
@@ -2123,6 +2123,54 @@ was not set.
 
 =back
 
+=head2 Registering error and warning messages
+
+C<Texinfo::Convert::Converter> implements an interface to register error and
+warning messages in the converter, that can be retrieved later on, in general
+to be given to C<Texinfo::Report::add_formatted_message>.  Underneath,
+C<Texinfo::Report> is used to setup the messages data structure.
+
+=over
+
+=item $converter->converter_document_error($text, $continuation)
+
+=item $converter->converter_document_warn($text, $continuation)
+X<C<converter_document_error>>X<C<converter_document_warn>>
+
+Register a warning or an error.  The I<$text> is the text of the error or
+warning.
+
+The I<$continuation> optional arguments, if true, conveys that the line is a
+continuation line of a message.
+
+=item $converter->converter_line_error($text, $error_location_info, 
$continuation)
+
+=item $converter->converter_line_warn($text, $error_location_info, 
$continuation)
+X<C<converter_line_error>>X<C<converter_line_warn>>
+
+Register a warning or an error with a line information.  The I<$text> is the
+text of the error or warning.  The I<$error_location_info> argument holds the
+information on the error or warning location.  The I<$error_location_info>
+reference on hash may be obtained from Texinfo elements I<source_info> keys.
+It may also be setup to point to a file name, using the C<file_name> key and to
+a line number, using the C<line_nr> key.  The C<file_name> key value should be
+a binary string.
+
+The I<$continuation> optional arguments, if true, conveys that
+the line is a continuation line of a message.
+
+=item \@error_warning_messages = $converter->get_converter_errors()
+X<C<get_converter_errors>>
+
+Return a reference on an array containing the error or warning messages
+registered in the converter.  Error and warning messages are hash references as
+described in L<Texinfo::Report::errors|Texinfo::Report/($error_warnings_list,
+$error_count) = errors($registrar)> and can be used in input of L<<
+Texinfo::Report::add_formatted_message|Texinfo::Report/$registrar->add_formatted_message
+($msg) >>.
+
+=back
+
 =head2 Conversion to XML
 
 Some C<Texinfo::Convert::Converter> methods target conversion to XML.