branch master updated: * tp/Texinfo/Convert/Converter.pm, tp/maintain/template.pod: remove document from converter argument. Add conversion_initialization, conversion_finalization and set_document documentation.

[Patrice Dumas]

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 cbe3ab29f9 * tp/Texinfo/Convert/Converter.pm, 
tp/maintain/template.pod: remove document from converter argument.  Add 
conversion_initialization, conversion_finalization and set_document 
documentation.
cbe3ab29f9 is described below

commit cbe3ab29f91b2c6e417ad00483bc2c43b6ee4aee
Author: Patrice Dumas <pertusus@free.fr>
AuthorDate: Fri Jan 19 21:20:23 2024 +0100

    * tp/Texinfo/Convert/Converter.pm, tp/maintain/template.pod: remove
    document from converter argument.  Add conversion_initialization,
    conversion_finalization and set_document documentation.
---
 ChangeLog                        |   6 +++
 tp/Texinfo/Convert/Converter.pm  | 112 ++++++++++++++++++++++++++++++++++-----
 tp/Texinfo/Convert/DocBook.pm    |  19 ++++---
 tp/Texinfo/Convert/HTML.pm       |  19 ++++---
 tp/Texinfo/Convert/Info.pm       |  19 ++++---
 tp/Texinfo/Convert/LaTeX.pm      |   1 +
 tp/Texinfo/Convert/Plaintext.pm  |  19 ++++---
 tp/Texinfo/Convert/TexinfoXML.pm |  19 ++++---
 tp/Texinfo/Convert/Text.pm       |   2 +-
 tp/maintain/template.pod         |  19 ++++---
 10 files changed, 162 insertions(+), 73 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 57ded8a65f..83af88389d 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2024-01-19  Patrice Dumas  <pertusus@free.fr>
+
+       * tp/Texinfo/Convert/Converter.pm, tp/maintain/template.pod: remove
+       document from converter argument.  Add conversion_initialization,
+       conversion_finalization and set_document documentation.
+
 2024-01-18  Patrice Dumas  <pertusus@free.fr>
 
        * tp/Texinfo/Convert/Converter.pm (set_document),
diff --git a/tp/Texinfo/Convert/Converter.pm b/tp/Texinfo/Convert/Converter.pm
index 87e4620a0a..beeb6e0213 100644
--- a/tp/Texinfo/Convert/Converter.pm
+++ b/tp/Texinfo/Convert/Converter.pm
@@ -2004,23 +2004,53 @@ Texinfo::Convert::Converter - Parent class for Texinfo 
tree converters
   }
   sub converter_initialize($) {
     my $self = shift;
+    ...
+  }
+
+  sub conversion_initialization($;$) {
+    my $self = shift;
+    my $document = shift;
+
+    if ($document) {
+      $self->set_document($document);
+    }
+
     $self->{'document_context'} = [{}];
+    ...
+  }
+
+  sub conversion_finalization($) {
+    my $self = shift;
   }
 
   sub convert($$) {
+    my $self = shift;
+    my $document = shift;
+
+    $self->conversion_initialization($document);
+
+    ...
+    $self->conversion_finalization();
     ...
   }
   sub convert_tree($$) {
     ...
   }
+
   sub output($$) {
+    my $self = shift;
+    my $document = shift;
+
+    $self->conversion_initialization($document);
+
+    ...
+    $self->conversion_finalization();
     ...
   }
 
   # end of Texinfo::Convert::MyConverter
 
-  my $converter = Texinfo::Convert::MyConverter->converter(
-                                               {'document' => $document});
+  my $converter = Texinfo::Convert::MyConverter->converter();
   $converter->output($texinfo_parsed_document);
 
 =head1 NOTES
@@ -2046,7 +2076,7 @@ The following methods can be defined too:
 X<C<convert_tree>>
 
 The C<convert_tree> method is mandatory and should convert portions of Texinfo
-tree. Takes a Texinfo tree in argument.
+tree. Takes a converter and Texinfo tree in arguments.
 
 =item C<output>
 X<C<output>>
@@ -2056,7 +2086,8 @@ to a file with headers and so on.  Although not called 
from other
 modules, this method should in general be implemented by converters.
 C<Texinfo::Convert::Converter> implements a generic C<output> suitable
 for simple output formats.  C<output> is called from C<texi2any>.
-C<output> takes a Texinfo parsed document C<Texinfo::Document> in argument.
+C<output> takes a converter and Texinfo parsed document C<Texinfo::Document>
+in arguments.
 
 =item C<convert>
 X<C<convert>>
@@ -2064,8 +2095,8 @@ X<C<convert>>
 Optional entry point for the conversion of a Texinfo parsed document without
 the headers done when outputting to a file and can also be used to output
 simple documents.  It could be called from the C<Texinfo::Convert::Converter>
-C<output> implementation.  C<convert> takes a Texinfo parsed document
-C<Texinfo::Document> in argument.
+C<output> implementation.  C<convert> takes a converter and a Texinfo parsed
+document C<Texinfo::Document> in arguments.
 
 =item C<convert_output_unit>
 X<C<convert_output_unit>>
@@ -2099,7 +2130,7 @@ described in L<Texinfo::Parser>.
 
 =head1 METHODS
 
-=head2 Initialization
+=head2 Converter Initialization
 
 X<C<converter>>
 X<C<Texinfo::Convert::Converter> initialization>
@@ -2115,12 +2146,10 @@ C<Texinfo::Convert::Converter>.
 The I<$options> hash reference holds options for the converter.
 These 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.
+are described in the Texinfo manual or in the customization API manual.
 Those customization options, when appropriate, override the document content.
-B<TODO what about the other options (all are used in converters>
-B<TODO document this associated information
-(..., most available
-in HTML converter, either through $converter-E<gt>get_info('document') or 
label_command())>
+B<TODO what about the other options (all are used in converters). Describe
+in converter_defaults?>
 
 The C<converter> function returns a converter object (a blessed hash
 reference) after checking the options and performing some initializations.
@@ -2146,6 +2175,65 @@ converter initialization.
 
 =back
 
+=head2 Conversion
+
+For conversion with C<output> and C<convert> a document to convert should be
+associated to the converter, in general the document passed in argument of
+C<output> or C<convert>.  The C<set_document> function associates a
+C<Texinfo::Document> to a converter.  This function is used in the default
+implementations.
+
+=over
+
+=item $converter->set_document($document)
+X<C<set_document>>
+
+Associate I<$document> to I<$converter>.  Also set the encoding related 
customization
+options based on I<$converter> customization information and information on
+document encoding, and setup converter hash C<convert_text_options> value that
+can be used to call 
L<Texinfo::Convert::Text::convert_to_text|Texinfo::Convert::Text/$result = 
convert_to_text($tree, $text_options)>
+
+=back
+
+In default implementations a function is called at the beginning of C<output> 
and
+C<convert>, C<conversion_initialization> and another function,
+C<conversion_finalization>, is called at the end of C<output> and C<convert>.
+In turn, C<set_document> is called in the default C<conversion_initialization>
+implementation.  A subclass converter redefining C<conversion_initialization>
+should in general call C<set_document> in the redefined function too to
+associate the converted document to the converter.
+
+=over
+
+=item $converter->conversion_initialization($document)
+
+=item $converter->conversion_finalization()
+X<C<conversion_initialization>>X<C<conversion_finalization>>
+
+C<conversion_initialization> is called at the beginning of the default
+C<output> and C<convert> functions, and C<conversion_finalization>
+is called at the end of the default C<output> and C<convert> functions.
+These functions should be redefined to run code just before a document
+conversion and right after the end of the document conversion.
+
+In the default case, C<conversion_initialization> calls
+L<< set_document|/$converter->set_document($document) >> to associate the 
C<Texinfo::Document>
+document passed in argument to the converter.
+
+=back
+
+Calling C<conversion_initialization> and, if needed, C<conversion_finalization>
+in redefined C<output> and C<convert> methods is not mandated, but it is
+recommended to have similar converter codes.  In subclassed converters that do
+not need to define C<conversion_initialization>, calling the default
+C<Texinfo::Convert::Converter> C<conversion_initialization> implementation is
+also recommended to avoid having to explictely call C<set_document>.
+If C<conversion_initialization> is defined in a converter subclass it is
+recommended to call C<set_document> at the very beginning of the function to
+have the document associated to the converter.
+
+
+
 =head2 Getting and setting customization variables
 
 C<Texinfo::Convert::Converter> implements a simple interface to
diff --git a/tp/Texinfo/Convert/DocBook.pm b/tp/Texinfo/Convert/DocBook.pm
index 8fe5068c56..a631a1e5e8 100644
--- a/tp/Texinfo/Convert/DocBook.pm
+++ b/tp/Texinfo/Convert/DocBook.pm
@@ -1882,7 +1882,7 @@ Texinfo::Convert::DocBook - Convert Texinfo tree to 
DocBook
 =head1 SYNOPSIS
 
   my $converter
-    = Texinfo::Convert::DocBook->converter({'document' => $document});
+    = Texinfo::Convert::DocBook->converter({'NUMBER_SECTIONS' => 0});
 
   $converter->output($document);
   $converter->convert($document);
@@ -1905,15 +1905,11 @@ 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 L<document|Texinfo::Document>
-may be associated with the I<document> key.  The document should not
-be available directly anymore after getting the associated information.
-
-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 I<$options> hash reference holds Texinfo customization options for the
+converter.  These options should be Texinfo customization options
+that can be passed to the converter.  Most of the customization options are
+described in the Texinfo manual or in the customization API manual.  Those
+customization options, when appropriate, override the document content.
 
 See L<Texinfo::Convert::Converter> for more information.
 
@@ -1932,6 +1928,9 @@ Convert a Texinfo tree portion I<$tree> and return the 
resulting
 output.  This function does not try to output a full document but only
 portions.  For a full document use C<convert>.
 
+In general, this function should be called after the converter has been
+associated to a document by a call to C<output> or C<convert>.
+
 =back
 
 =head1 AUTHOR
diff --git a/tp/Texinfo/Convert/HTML.pm b/tp/Texinfo/Convert/HTML.pm
index 63cf4dfcd4..6507917107 100644
--- a/tp/Texinfo/Convert/HTML.pm
+++ b/tp/Texinfo/Convert/HTML.pm
@@ -13444,7 +13444,7 @@ Texinfo::Convert::HTML - Convert Texinfo tree to HTML
 =head1 SYNOPSIS
 
   my $converter
-    = Texinfo::Convert::HTML->converter({'document' => $document});
+    = Texinfo::Convert::HTML->converter({'NUMBER_SECTIONS' => 0});
 
   $converter->output($document);
   $converter->convert($document);
@@ -13468,15 +13468,11 @@ 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 L<document|Texinfo::Document>
-may be associated with the I<document> key.  The document should not
-be available directly anymore after getting the associated information.
-
-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 I<$options> hash reference holds Texinfo customization options for the
+converter.  These options should be Texinfo customization options
+that can be passed to the converter.  Most of the customization options are
+described in the Texinfo manual or in the customization API manual.  Those
+customization options, when appropriate, override the document content.
 
 See L<Texinfo::Convert::Converter> for more information.
 
@@ -13495,6 +13491,9 @@ Convert a Texinfo tree portion I<$tree> and return the 
resulting
 output.  This function does not try to output a full document but only
 portions.  For a full document use C<convert>.
 
+In general, this function should be called after the converter has been
+associated to a document by a call to C<output> or C<convert>.
+
 =item $result = $converter->output_internal_links()
 X<C<output_internal_links>>
 
diff --git a/tp/Texinfo/Convert/Info.pm b/tp/Texinfo/Convert/Info.pm
index a78132bd2b..b2167eafe6 100644
--- a/tp/Texinfo/Convert/Info.pm
+++ b/tp/Texinfo/Convert/Info.pm
@@ -702,7 +702,7 @@ Texinfo::Convert::Info - Convert Texinfo tree to Info
 =head1 SYNOPSIS
 
   my $converter
-    = Texinfo::Convert::Info->converter({'document' => $document});
+    = Texinfo::Convert::Info->converter({'NUMBER_SECTIONS' => 0});
 
   $converter->output($document);
   $converter->convert($document);
@@ -725,15 +725,11 @@ 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 L<document|Texinfo::Document>
-may be associated with the I<document> key.  The document should not
-be available directly anymore after getting the associated information.
-
-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 I<$options> hash reference holds Texinfo customization options for the
+converter.  These options should be Texinfo customization options
+that can be passed to the converter.  Most of the customization options are
+described in the Texinfo manual or in the customization API manual.  Those
+customization options, when appropriate, override the document content.
 
 See L<Texinfo::Convert::Converter> for more information.
 
@@ -752,6 +748,9 @@ Convert a Texinfo tree portion I<$tree> and return the 
resulting
 output.  This function does not try to output a full document but only
 portions.  For a full document use C<convert>.
 
+In general, this function should be called after the converter has been
+associated to a document by a call to C<output> or C<convert>.
+
 =back
 
 =head1 AUTHOR
diff --git a/tp/Texinfo/Convert/LaTeX.pm b/tp/Texinfo/Convert/LaTeX.pm
index 5522e8be6d..a2ace096d6 100644
--- a/tp/Texinfo/Convert/LaTeX.pm
+++ b/tp/Texinfo/Convert/LaTeX.pm
@@ -1241,6 +1241,7 @@ sub copy_options_for_convert_to_latex_math($)
 # generated by the LaTeX conversion are few and not relevant for math tree
 # fragments.  Relevant errors should be generated when parsing the Texinfo,
 # or when converting the final LaTeX.
+# Document could be passed to conversion_initialization if needed.
 sub convert_to_latex_math($$;$$)
 {
   my $self = shift;
diff --git a/tp/Texinfo/Convert/Plaintext.pm b/tp/Texinfo/Convert/Plaintext.pm
index 5f839aa847..3d1c18b2c1 100644
--- a/tp/Texinfo/Convert/Plaintext.pm
+++ b/tp/Texinfo/Convert/Plaintext.pm
@@ -4164,7 +4164,7 @@ Texinfo::Convert::Plaintext - Convert Texinfo tree to 
Plaintext
 =head1 SYNOPSIS
 
   my $converter
-    = Texinfo::Convert::Plaintext->converter({'document' => $document});
+    = Texinfo::Convert::Plaintext->converter({'NUMBER_SECTIONS' => 0});
 
   $converter->output($document);
   $converter->convert($document);
@@ -4187,15 +4187,11 @@ 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 L<document|Texinfo::Document>
-may be associated with the I<document> key.  The document should not
-be available directly anymore after getting the associated information.
-
-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 I<$options> hash reference holds Texinfo customization options for the
+converter.  These options should be Texinfo customization options
+that can be passed to the converter.  Most of the customization options are
+described in the Texinfo manual or in the customization API manual.  Those
+customization options, when appropriate, override the document content.
 
 See L<Texinfo::Convert::Converter> for more information.
 
@@ -4214,6 +4210,9 @@ Convert a Texinfo tree portion I<$tree> and return the 
resulting
 output.  This function does not try to output a full document but only
 portions.  For a full document use C<convert>.
 
+In general, this function should be called after the converter has been
+associated to a document by a call to C<output> or C<convert>.
+
 =back
 
 =head1 AUTHOR
diff --git a/tp/Texinfo/Convert/TexinfoXML.pm b/tp/Texinfo/Convert/TexinfoXML.pm
index e8f46bf87e..276f496f99 100644
--- a/tp/Texinfo/Convert/TexinfoXML.pm
+++ b/tp/Texinfo/Convert/TexinfoXML.pm
@@ -262,7 +262,7 @@ Texinfo::Convert::TexinfoXML - Convert Texinfo tree to 
TexinfoXML
 =head1 SYNOPSIS
 
   my $converter
-    = Texinfo::Convert::TexinfoXML->converter({'document' => $document});
+    = Texinfo::Convert::TexinfoXML->converter({'NUMBER_SECTIONS' => 0});
 
   $converter->output($document);
   $converter->convert($document);
@@ -285,15 +285,11 @@ 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 L<document|Texinfo::Document>
-may be associated with the I<document> key.  The document should not
-be available directly anymore after getting the associated information.
-
-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 I<$options> hash reference holds Texinfo customization options for the
+converter.  These options should be Texinfo customization options
+that can be passed to the converter.  Most of the customization options are
+described in the Texinfo manual or in the customization API manual.  Those
+customization options, when appropriate, override the document content.
 
 See L<Texinfo::Convert::Converter> for more information.
 
@@ -312,6 +308,9 @@ Convert a Texinfo tree portion I<$tree> and return the 
resulting
 output.  This function does not try to output a full document but only
 portions.  For a full document use C<convert>.
 
+In general, this function should be called after the converter has been
+associated to a document by a call to C<output> or C<convert>.
+
 =back
 
 =head1 AUTHOR
diff --git a/tp/Texinfo/Convert/Text.pm b/tp/Texinfo/Convert/Text.pm
index 46949ce610..8d4271b701 100644
--- a/tp/Texinfo/Convert/Text.pm
+++ b/tp/Texinfo/Convert/Text.pm
@@ -1138,7 +1138,7 @@ text options associated to the C<convert_text_options> 
key.
 
 The main function is C<convert_to_text>.  The text conversion options
 can be modified with the C<set_*> functions before calling C<convert_to_text>,
-and reset aterwards with the corresponding C<reset_*> functions.
+and reset afterwards with the corresponding C<reset_*> functions.
 
 =head1 METHODS
 
diff --git a/tp/maintain/template.pod b/tp/maintain/template.pod
index 003534036a..3e19b32f54 100644
--- a/tp/maintain/template.pod
+++ b/tp/maintain/template.pod
@@ -7,7 +7,7 @@ Texinfo::Convert::OUTFORMAT - Convert Texinfo tree to OUTFORMAT
 =head1 SYNOPSIS
 
   my $converter
-    = Texinfo::Convert::OUTFORMAT->converter({'document' => $document});
+    = Texinfo::Convert::OUTFORMAT->converter({'NUMBER_SECTIONS' => 0});
 
   $converter->output($document);
   $converter->convert($document);
@@ -31,15 +31,11 @@ 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 L<document|Texinfo::Document>
-may be associated with the I<document> key.  The document should not
-be available directly anymore after getting the associated information.
-
-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 I<$options> hash reference holds Texinfo customization options for the
+converter.  These options should be Texinfo customization options
+that can be passed to the converter.  Most of the customization options are
+described in the Texinfo manual or in the customization API manual.  Those
+customization options, when appropriate, override the document content.
 
 See L<Texinfo::Convert::Converter> for more information.
 
@@ -58,6 +54,9 @@ Convert a Texinfo tree portion I<$tree> and return the 
resulting
 output.  This function does not try to output a full document but only
 portions.  For a full document use C<convert>.
 
+In general, this function should be called after the converter has been
+associated to a document by a call to C<output> or C<convert>.
+
 __HTML =item $result = $converter->output_internal_links()
 __HTML X<C<output_internal_links>>
 __HTML