[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[no subject]
From: |
Patrice Dumas |
Date: |
Thu, 22 Feb 2024 15:19:56 -0500 (EST) |
branch: master
commit bb480e314e7bdc54f2b90b787236ab6036d8ecf9
Author: Patrice Dumas <pertusus@free.fr>
AuthorDate: Wed Feb 21 16:42:15 2024 +0100
Update POD documentation
---
tp/Texinfo/Convert/Converter.pm | 56 ++++++++++++++++++++++++-----------------
1 file changed, 33 insertions(+), 23 deletions(-)
diff --git a/tp/Texinfo/Convert/Converter.pm b/tp/Texinfo/Convert/Converter.pm
index f77cc58e6e..71f7f05412 100644
--- a/tp/Texinfo/Convert/Converter.pm
+++ b/tp/Texinfo/Convert/Converter.pm
@@ -2050,37 +2050,36 @@ Texinfo to other formats. There is no promise of API
stability.
C<Texinfo::Convert::Converter> is a super class that can be used to
simplify converters initialization. The class also provide some
-useful methods.
-
-In turn, the converter should define some methods. Two are
-optional, C<converter_defaults>, C<converter_initialize> and
-used for initialization, to give information to C<Texinfo::Convert::Converter>.
-
-The following methods can be defined too:
+useful methods. In turn, the converter should define some methods for
+conversion. In general C<convert_tree>, C<output> and C<convert> should be
+defined.
=over
-=item C<convert_tree>
+=item $result = $converter->convert_tree($tree)
X<C<convert_tree>>
The C<convert_tree> method is mandatory and should convert portions of Texinfo
-tree. Takes a converter and Texinfo tree in arguments.
+tree. Takes a I<$converter> and Texinfo tree I<$tree> in arguments. Returns
+the converted output.
+
+=item $result = $converter->output($document)
-=item C<output>
+=item $result = $converter->output_tree($document)
X<C<output>>X<C<output_tree>>
The C<output> method is used by converters as entry point for conversion
to a file with headers and so on. Although not called from other
modules, this method should in general be implemented by converters.
-C<output> is called from C<texi2any>. C<output> takes a converter and a
-Texinfo parsed document C<Texinfo::Document> in arguments.
+C<output> is called from C<texi2any>. C<output> takes a I<$converter> and a
+Texinfo parsed document C<Texinfo::Document> I<$document> as arguments.
C<Texinfo::Convert::Converter> implements a generic C<output_tree>
function suitable for conversion of the Texinfo tree, with the conversion
result output into a file or returned from the function. C<output_tree>
-takes a converter and a Texinfo parsed document C<Texinfo::Document> in
-arguments. In a converter that uses C<output_tree>, C<output> is in
-general defined as:
+takes a I<$converter> and a Texinfo parsed document C<Texinfo::Document>
+I<$document> as arguments. In a converter that uses C<output_tree>,
+C<output> is in general defined as:
sub output($$) {
my $self = shift;
@@ -2089,23 +2088,30 @@ general defined as:
return $self->output_tree($document);
}
+In general, C<output> and C<output_tree> output to files and return C<undef>.
+When the output file name is an empty string, however, it is customary
+for C<output> and C<output_tree> to return the output as a character string
+instead.
+
For output formats based on output units conversion, the
C<Texinfo::Convert::Plaintext> C<output> method could be a good starting
point.
-=item C<convert>
+=item $result = $converter->convert($document)
X<C<convert>>
-Optional entry point for the conversion of a Texinfo parsed document without
-the headers done when outputting to a file. C<convert> takes a converter
-and a Texinfo parsed document C<Texinfo::Document> in arguments. Used in the
-C<texi2any> test suite.
+Entry point for the conversion of a Texinfo parsed document without
+the headers done when outputting to a file. C<convert> takes a I<$converter>
+and a Texinfo parsed document C<Texinfo::Document> I<$document> as arguments.
+Returns the output as a character string. Not mandatory, not called from
+other modules nor from C<texi2any>, but used in the C<texi2any> test suite.
-=item C<convert_output_unit>
+=item $result = $converter->convert_output_unit($output_unit)
X<C<convert_output_unit>>
Can be used for the conversion of output units by converters.
-C<convert_output_unit> takes an output unit as argument. The implementation of
+C<convert_output_unit> takes a I<$converter> and an output unit
+I<$output_unit> as argument. The implementation of
C<convert_output_unit> of C<Texinfo::Convert::Converter> could be suitable in
many cases. Output units are typically returned by L<Texinfo::Structuring
split_by_section|Texinfo::Structuring/$output_units = split_by_section($tree)>
@@ -2117,6 +2123,10 @@ converted directly, in general by using C<output_tree>.
=back
+Two methods, C<converter_defaults> and C<converter_initialize> are
+used for initialization, to give information
+to C<Texinfo::Convert::Converter> and can be redefined in converters.
+
To help with the conversion, the C<set_document> function associates a
C<Texinfo::Document> to a converter. Other methods are called in default
implementations to be redefined to call code at specific moments of the
@@ -2421,7 +2431,7 @@ 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>
+and returns the argument as last resort. I<$use_numeric_entities>
is optional. If set, numerical entities are used instead of named entities
if possible.