[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
branch master updated: Update POD documentation
|
From: |
Patrice Dumas |
|
Subject: |
branch master updated: Update POD documentation |
|
Date: |
Sat, 05 Oct 2024 05:33:30 -0400 |
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 12605814e1 Update POD documentation
12605814e1 is described below
commit 12605814e19414adc896deb48dcde2dde04280bf
Author: Patrice Dumas <pertusus@free.fr>
AuthorDate: Mon Aug 26 21:24:33 2024 +0200
Update POD documentation
---
.../api_includes/Texinfo-Convert-Converter.texi | 95 +++++++++---------
doc/tp_api/api_includes/Texinfo-Convert-Text.texi | 8 +-
.../api_includes/Texinfo-Convert-Unicode.texi | 4 +-
doc/tp_api/api_includes/Texinfo-Convert-Utils.texi | 8 +-
doc/tp_api/api_includes/Texinfo-Translations.texi | 6 +-
tp/Texinfo/Convert/Converter.pm | 106 +++++++++++----------
tp/Texinfo/Convert/Text.pm | 8 +-
tp/Texinfo/Convert/Unicode.pm | 4 +-
tp/Texinfo/Convert/Utils.pm | 4 +-
tp/Texinfo/Translations.pm | 6 +-
10 files changed, 131 insertions(+), 118 deletions(-)
diff --git a/doc/tp_api/api_includes/Texinfo-Convert-Converter.texi
b/doc/tp_api/api_includes/Texinfo-Convert-Converter.texi
index 142cbb0e11..d46929664e 100644
--- a/doc/tp_api/api_includes/Texinfo-Convert-Converter.texi
+++ b/doc/tp_api/api_includes/Texinfo-Convert-Converter.texi
@@ -103,10 +103,10 @@ the converted output.
@cindex @code{output_tree}
The @code{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.
-@code{output} is called from @code{texi2any}. @code{output} takes a
@emph{$converter} and a
-Texinfo parsed document @code{Texinfo::Document} @emph{$document} as arguments.
+to a file with headers and so on. This method should be implemented by
+converters. @code{output} is called from @code{texi2any}. @code{output}
takes a
+@emph{$converter} and a Texinfo parsed document @code{Texinfo::Document}
@emph{$document}
+as arguments.
@code{Texinfo::Convert::Converter} implements a generic @code{output_tree}
function suitable for conversion of the Texinfo tree, with the conversion
@@ -127,21 +127,19 @@ takes a @emph{$converter} and a Texinfo parsed document
@code{Texinfo::Document}
In general, @code{output} and @code{output_tree} output to files and return
@code{undef}.
When the output file name is an empty string, however, it is customary
for @code{output} and @code{output_tree} to return the output as a character
string
-instead.
-
-For output formats based on output units conversion, the
-@code{Texinfo::Convert::Plaintext} @code{output} method could be a good
starting
-point.
+instead. The output file name is obtained in @code{output_tree} through a
call to
+@ref{Texinfo@asis{::}Convert@asis{::}Converter ($output_file@comma{}
$destination_directory@comma{} $output_filename@comma{} $document_name@comma{}
$input_basefile) = $converter->determine_files_and_directory($output_format),,
determine_files_and_directory}.
+In general @code{determine_files_and_directory} is also used when
@code{output_tree} is not used.
@item $result = $converter->convert($document)
@anchor{Texinfo@asis{::}Convert@asis{::}Converter $result =
$converter->convert($document)}
@cindex @code{convert}
-Entry point for the conversion of a Texinfo parsed document without
-the headers done when outputting to a file. @code{convert} takes a
@emph{$converter}
-and a Texinfo parsed document @code{Texinfo::Document} @emph{$document} as
arguments.
-Returns the output as a character string. Not mandatory, not called from
-other modules nor from @code{texi2any}, but used in the @code{texi2any} test
suite.
+Entry point for the conversion of a Texinfo parsed document to an output
+format, without the headers usually done when outputting to a file.
@code{convert}
+takes a @emph{$converter} and a Texinfo parsed document
@code{Texinfo::Document}
+@emph{$document} as arguments. Returns the output as a character string. Not
+mandatory, not called from @code{texi2any}, but used in the @code{texi2any}
test suite.
@item $result = $converter->convert_output_unit($output_unit)
@anchor{Texinfo@asis{::}Convert@asis{::}Converter $result =
$converter->convert_output_unit($output_unit)}
@@ -156,9 +154,6 @@ split_by_section}
or @ref{Texinfo@asis{::}OutputUnits $output_units =
split_by_node($document),, Texinfo::OutputUnits split_by_node}.
-Output units are not relevant for all the formats, the Texinfo tree can also be
-converted directly, in general by using @code{output_tree}.
-
@end table
Two methods, @code{converter_defaults} and @code{converter_initialize} are
@@ -174,20 +169,26 @@ called at the beginning of @code{output},
@code{output_tree} and @code{convert}.
@code{output} and @code{convert}. @code{output_tree} also calls the
@code{conversion_output_begin} method before the Texinfo tree conversion to
obtain
the beginning of the output. @code{output_tree} calls the
-@code{conversion_output_begin} method after the Texinfo tree conversion to
obtain
+@code{conversion_output_end} method after the Texinfo tree conversion to obtain
the end of the output.
-Existing backends may be used as examples that implement and use those
-methods. @code{Texinfo::Convert::Texinfo} together with
-@code{Texinfo::Convert::PlainTexinfo}, as well as
-@code{Texinfo::Convert::TextContent} are trivial examples.
-@code{Texinfo::Convert::Text} is less trivial, although still simple,
-while @code{Texinfo::Convert::DocBook} is a real converter
-that is also not too complex.
+For output formats based on output units conversion, the
+@code{Texinfo::Convert::Plaintext} @code{output} method could be a good
starting
+point. HTML and Info output are also based on output units conversion.
+Output units are not relevant for all the formats, the Texinfo tree can also be
+converted directly, in general by using @code{output_tree}. This is how the
other
+Converters are implemented.
-The documentation of @ref{Texinfo@asis{::}Common NAME,, Texinfo::Common},
@ref{Texinfo@asis{::}Convert@asis{::}Unicode NAME,, Texinfo::Convert::Unicode}
-describes modules or additional function that may be useful for backends,
-while the parsed Texinfo tree is described in @ref{Texinfo@asis{::}Parser
NAME,, Texinfo::Parser}.
+Existing backends based on @code{output_tree} may be used as examples.
+@code{Texinfo::Convert::Texinfo} together with
@code{Texinfo::Convert::PlainTexinfo},
+as well as @code{Texinfo::Convert::TextContent} are trivial examples.
+@code{Texinfo::Convert::Text} is less trivial, although still simple, while
+@code{Texinfo::Convert::DocBook} is a real converter that is also not too
complex.
+
+The documentation of @ref{Texinfo@asis{::}Common NAME,, Texinfo::Common},
@ref{Texinfo@asis{::}OutputUnits NAME,, Texinfo::OutputUnits},
+@ref{Texinfo@asis{::}Convert@asis{::}Unicode NAME,, Texinfo::Convert::Unicode}
and @ref{Texinfo@asis{::}Convert@asis{::}Text NAME,, Texinfo::Convert::Text}
describes modules or
+additional function that may be useful for backends, while the parsed Texinfo
+tree is described in @ref{Texinfo@asis{::}Parser NAME,, Texinfo::Parser}.
@node Texinfo@asis{::}Convert@asis{::}Converter METHODS
@section Texinfo::Convert::Converter METHODS
@@ -208,18 +209,16 @@ the @code{converter} method that should be inherited from
@anchor{Texinfo@asis{::}Convert@asis{::}Converter $converter =
MyConverter->converter($options)}
The @emph{$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 or in the customization API manual.
-Those customization options, when appropriate, override the document content.
-@strong{TODO what about the other options?}
+These options should be Texinfo customization options. The
+customization options are described in the Texinfo manual or in the
+customization API manual.
The @code{converter} function returns a converter object (a blessed hash
reference) after checking the options and performing some initializations.
@end table
-To help with these initializations, the modules subclassing
@code{Texinfo::Convert::Converter}
+To help with the initializations, the modules subclassing
@code{Texinfo::Convert::Converter}
can define two methods:
@table @asis
@@ -227,9 +226,10 @@ can define two methods:
@anchor{Texinfo@asis{::}Convert@asis{::}Converter \%defaults =
$converter_or_class->converter_defaults($options)}
@cindex @code{converter_defaults}
-The module can provide the reference on a hash with defaults for converter
-customization options. The @emph{$options} hash reference holds options for
the
-converter. The function can be called both through a class or a converter.
+Returns a reference on a hash with defaults for the converter module
+customization options or @code{undef}. The @emph{$options} hash reference
holds
+options for the converter. This method is called through a converter by
@ref{Texinfo@asis{::}Convert@asis{::}Converter $converter =
MyConverter->converter($options),, converter}, but it may also
+be called through a converter module class.
@item converter_initialize
@anchor{Texinfo@asis{::}Convert@asis{::}Converter converter_initialize}
@@ -330,6 +330,11 @@ information expect an object implementing @code{get_conf}
and/or
@code{set_conf}. The converter itself can therefore be used in
such cases.
+Customization variables are typically setup when
+initializing a converter with @ref{Texinfo@asis{::}Convert@asis{::}Converter
$converter = MyConverter->converter($options),, converter}
+and completed by Texinfo informative @@-commands tree element values,
+for commands such as @code{@@frenchspacing} or @code{@@footnotestyle}.
+
@table @asis
@item $converter->force_conf($variable_name, $variable_value)
@anchor{Texinfo@asis{::}Convert@asis{::}Converter
$converter->force_conf($variable_name@comma{} $variable_value)}
@@ -441,7 +446,7 @@ some substitution to be done after the translation. The
key of the
In the string to be translated word in brace matching keys of
@emph{$replaced_substrings} are replaced.
For @code{cdt}, the value is a Texinfo tree that is substituted in the
-resulting texinfo tree. For @code{cdt_string}, the value is a string that
+resulting Texinfo tree. For @code{cdt_string}, the value is a string that
is replaced in the resulting string.
The @emph{$translation_context} is optional. If not @code{undef} this is a
translation
@@ -615,7 +620,7 @@ split, the directory where the files should be created.
@emph{$output_filename}
is, in general, the file name portion of @emph{$output_file} (without
directory)
but can also be set based on @code{@@setfilename}, in particular when
@emph{$output_file} is an empty string. @emph{$document_name} is
@emph{$output_filename}
-without extension. @emph{$input_basefile} is based on the input texinfo file
name,
+without extension. @emph{$input_basefile} is based on the input Texinfo file
name,
with the file name portion only (without directory).
The strings returned are text strings.
@@ -640,25 +645,25 @@ the input file encoding. It is useful if there is more
precise information
on the input file encoding where the file name appeared.
Note that @code{encoded_output_file_name} is a wrapper around the
-function with the same name in @ref{Texinfo@asis{::}Convert@asis{::}Utils
($encoded_name@comma{} $encoding) =
$converter->encoded_output_file_name($converter@comma{}
$character_string_name),, Texinfo::Convert::Utils::encoded_output_file_name},
+function with the same name in @ref{Texinfo@asis{::}Convert@asis{::}Utils
($encoded_name@comma{} $encoding) =
$converter->encoded_output_file_name($character_string_name),,
Texinfo::Convert::Utils::encoded_output_file_name},
and @code{encoded_input_file_name} is a wrapper around the
-function with the same name in @ref{Texinfo@asis{::}Convert@asis{::}Utils
($encoded_name@comma{} $encoding) =
$converter->encoded_input_file_name($converter@comma{}
$character_string_name@comma{} $input_file_encoding),,
Texinfo::Convert::Utils::encoded_input_file_name}.
+function with the same name in @ref{Texinfo@asis{::}Convert@asis{::}Utils
($encoded_name@comma{} $encoding) =
$converter->encoded_input_file_name($character_string_name@comma{}
$input_file_encoding),, Texinfo::Convert::Utils::encoded_input_file_name}.
@item ($caption, $prepended) = $converter->float_name_caption($float)
@anchor{Texinfo@asis{::}Convert@asis{::}Converter ($caption@comma{}
$prepended) = $converter->float_name_caption($float)}
@cindex @code{float_name_caption}
-@emph{$float} is a texinfo tree @code{@@float} element. This function
+@emph{$float} is a Texinfo tree @code{@@float} element. This function
returns the caption element that should be used for the float formatting
-and the @emph{$prepended} texinfo tree combining the type and label
+and the @emph{$prepended} Texinfo tree combining the type and label
of the float.
@item $tree = $converter->float_type_number($float)
@anchor{Texinfo@asis{::}Convert@asis{::}Converter $tree =
$converter->float_type_number($float)}
@cindex @code{float_type_number}
-@emph{$float} is a texinfo tree @code{@@float} element. This function
-returns the type and number of the float as a texinfo tree with
+@emph{$float} is a Texinfo tree @code{@@float} element. This function
+returns the type and number of the float as a Texinfo tree with
translations.
@item $end_line = $converter->format_comment_or_return_end_line($element)
diff --git a/doc/tp_api/api_includes/Texinfo-Convert-Text.texi
b/doc/tp_api/api_includes/Texinfo-Convert-Text.texi
index 8c75710346..ff054c5eab 100644
--- a/doc/tp_api/api_includes/Texinfo-Convert-Text.texi
+++ b/doc/tp_api/api_includes/Texinfo-Convert-Text.texi
@@ -40,7 +40,7 @@ The conversion is very simple, and, in the default case,
cannot handle
error handling nor some output strings translation.
Converters derived from @ref{Texinfo@asis{::}Convert@asis{::}Converter NAME,,
Texinfo::Convert::Converter} should have conversion
-text options associated to the @code{convert_text_options} key.
+text options preset associated to the @code{convert_text_options} key.
The main function is @code{convert_to_text}. The text conversion options
can be modified with the @code{set_*} functions before calling
@code{convert_to_text},
@@ -59,9 +59,9 @@ options. The converter is very simple, and has almost no
internal state
besides the options. It cannot handle as is output strings translation or
error storing.
-If the @emph{converter} option is set, some additional features may be
available
-for the conversion of some @@-commands, like output strings translation or
-error reporting.
+If the @emph{converter} option is set in @emph{$text_options}, some additional
features
+may be available for the conversion of some @@-commands, like output strings
+translation or error reporting.
The @code{NUMBER_SECTIONS}, @code{ASCII_GLYPH} and @code{TEST} options
corresponding to
customization variables may be set in @emph{$text_options}. The following
options
diff --git a/doc/tp_api/api_includes/Texinfo-Convert-Unicode.texi
b/doc/tp_api/api_includes/Texinfo-Convert-Unicode.texi
index cb0e34f276..39e6b198c6 100644
--- a/doc/tp_api/api_includes/Texinfo-Convert-Unicode.texi
+++ b/doc/tp_api/api_includes/Texinfo-Convert-Unicode.texi
@@ -91,8 +91,8 @@ conversion of the @emph{$stack}. @emph{$converter} is a
converter object option
used by @emph{$format_accent}. It may be @code{undef} if there is no need of
converter object in @emph{$format_accent}.
-If @emph{$set_case} is positive, the result is upper-cased, while if it is
negative,
-the result is lower-cased.
+The @emph{$set_case} argument is optional. If @emph{$set_case} is positive,
the result
+is upper-cased, while if it is negative, the result is lower-cased.
@item $width = string_width($string)
@anchor{Texinfo@asis{::}Convert@asis{::}Unicode $width = string_width($string)}
diff --git a/doc/tp_api/api_includes/Texinfo-Convert-Utils.texi
b/doc/tp_api/api_includes/Texinfo-Convert-Utils.texi
index 589661b2eb..2b877964ba 100644
--- a/doc/tp_api/api_includes/Texinfo-Convert-Utils.texi
+++ b/doc/tp_api/api_includes/Texinfo-Convert-Utils.texi
@@ -84,11 +84,11 @@ returns a Texinfo tree corresponding to the category of the
If @emph{$converter} is not defined, the resulting string won't be
translated.
-@item ($encoded_name, $encoding) =
$converter->encoded_input_file_name($converter, $character_string_name,
$input_file_encoding)
-@anchor{Texinfo@asis{::}Convert@asis{::}Utils ($encoded_name@comma{}
$encoding) = $converter->encoded_input_file_name($converter@comma{}
$character_string_name@comma{} $input_file_encoding)}
+@item ($encoded_name, $encoding) =
$converter->encoded_input_file_name($character_string_name,
$input_file_encoding)
+@anchor{Texinfo@asis{::}Convert@asis{::}Utils ($encoded_name@comma{}
$encoding) = $converter->encoded_input_file_name($character_string_name@comma{}
$input_file_encoding)}
-@item ($encoded_name, $encoding) =
$converter->encoded_output_file_name($converter, $character_string_name)
-@anchor{Texinfo@asis{::}Convert@asis{::}Utils ($encoded_name@comma{}
$encoding) = $converter->encoded_output_file_name($converter@comma{}
$character_string_name)}
+@item ($encoded_name, $encoding) =
$converter->encoded_output_file_name($character_string_name)
+@anchor{Texinfo@asis{::}Convert@asis{::}Utils ($encoded_name@comma{}
$encoding) = $converter->encoded_output_file_name($character_string_name)}
@cindex @code{encoded_input_file_name}
@cindex @code{encoded_output_file_name}
diff --git a/doc/tp_api/api_includes/Texinfo-Translations.texi
b/doc/tp_api/api_includes/Texinfo-Translations.texi
index c511f47779..3d60e777fd 100644
--- a/doc/tp_api/api_includes/Texinfo-Translations.texi
+++ b/doc/tp_api/api_includes/Texinfo-Translations.texi
@@ -84,8 +84,8 @@ some substitution to be done after the translation. The key
of the
@emph{$replaced_substrings} hash reference identifies what is to be
substituted.
In the string to be translated word in brace matching keys of
@emph{$replaced_substrings} are replaced.
-For @code{gdt}, the value is a Texinfo tree that is substituted in the
-resulting texinfo tree. For @code{gdt_string}, the value is a string that
+For @code{gdt}, the value is a Texinfo tree element that is substituted in the
+resulting Texinfo tree. For @code{gdt_string}, the value is a string that
is replaced in the resulting string.
@emph{$debug_level} is an optional debugging level supplied to @code{gdt},
similar to
@@ -100,7 +100,7 @@ For example, in the following call, the string
@code{See @{reference@} in @@cite@{@{book@}@}} is translated, then
parsed as a Texinfo string, with @emph{@{reference@}} substituted by
@emph{$tree_reference} in the resulting tree, and @emph{@{book@}}
-replaced by the associated texinfo tree text element:
+replaced by the associated Texinfo tree text element:
@verbatim
$tree = gdt('See {reference} in @cite{{book}}', "ca",
diff --git a/tp/Texinfo/Convert/Converter.pm b/tp/Texinfo/Convert/Converter.pm
index 8ce3e3cd61..eb29c61480 100644
--- a/tp/Texinfo/Convert/Converter.pm
+++ b/tp/Texinfo/Convert/Converter.pm
@@ -313,6 +313,7 @@ sub _generic_converter_init($$;$)
}
# this function is designed so as to be used in specific Converters
+# and not redefined.
sub converter($;$)
{
my $class = shift;
@@ -343,6 +344,7 @@ sub convert_output_unit($$)
return $result;
}
+# should be redefined by specific converters
sub conversion_output_begin($;$$)
{
my $self = shift;
@@ -426,12 +428,12 @@ sub output_tree($$)
return $result;
}
-# Nothing to do in perl. XS function resets converter
+# Nothing to do in Perl. XS function resets converter
sub reset_converter($)
{
}
-# Nothing to do in perl. XS function frees memory
+# Nothing to do in Perl. XS function frees memory
sub destroy($)
{
}
@@ -642,7 +644,7 @@ sub determine_files_and_directory($$)
my ($directories, $suffix);
($input_basefile, $directories, $suffix) = fileparse($input_file_name);
} else {
- # This could happen if called on a piece of texinfo
+ # This could happen if called on a piece of Texinfo and not a full manual.
$input_basefile = '';
}
@@ -1107,7 +1109,7 @@ sub set_output_units_files($$$$$$)
if (!exists($self->{'file_counters'}->{$output_unit_filename}));
$self->{'file_counters'}->{$output_unit_filename}++;
print STDERR 'Page '
- # uncomment for perl object name
+ # uncomment for Perl object name
#."$output_unit "
.Texinfo::OutputUnits::output_unit_texi($output_unit)
.":
$output_unit_filename($self->{'file_counters'}->{$output_unit_filename})\n"
@@ -2061,10 +2063,10 @@ the converted output.
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 I<$converter> and a
-Texinfo parsed document C<Texinfo::Document> I<$document> as arguments.
+to a file with headers and so on. This method should be implemented by
+converters. 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
@@ -2083,20 +2085,18 @@ C<output> is in general defined as:
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.
+instead. The output file name is obtained in C<output_tree> through a call to
+L<<< determine_files_and_directory|/($output_file, $destination_directory,
$output_filename, $document_name, $input_basefile) =
$converter->determine_files_and_directory($output_format) >>>.
+In general C<determine_files_and_directory> is also used when C<output_tree>
is not used.
=item $result = $converter->convert($document)
X<C<convert>>
-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.
+Entry point for the conversion of a Texinfo parsed document to an output
+format, without the headers usually 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 C<texi2any>, but used in the C<texi2any> test suite.
=item $result = $converter->convert_output_unit($output_unit)
X<C<convert_output_unit>>
@@ -2110,9 +2110,6 @@ split_by_section|Texinfo::OutputUnits/$output_units =
split_by_section($document
or L<Texinfo::OutputUnits split_by_node|Texinfo::OutputUnits/$output_units =
split_by_node($document)>.
-Output units are not relevant for all the formats, the Texinfo tree can also be
-converted directly, in general by using C<output_tree>.
-
=back
Two methods, C<converter_defaults> and C<converter_initialize> are
@@ -2128,20 +2125,26 @@ C<conversion_finalization> is generally called at the
end of C<output_tree>,
C<output> and C<convert>. C<output_tree> also calls the
C<conversion_output_begin> method before the Texinfo tree conversion to obtain
the beginning of the output. C<output_tree> calls the
-C<conversion_output_begin> method after the Texinfo tree conversion to obtain
+C<conversion_output_end> method after the Texinfo tree conversion to obtain
the end of the output.
-Existing backends may be used as examples that implement and use those
-methods. C<Texinfo::Convert::Texinfo> together with
-C<Texinfo::Convert::PlainTexinfo>, as well as
-C<Texinfo::Convert::TextContent> are trivial examples.
-C<Texinfo::Convert::Text> is less trivial, although still simple,
-while C<Texinfo::Convert::DocBook> is a real converter
-that is also not too complex.
+For output formats based on output units conversion, the
+C<Texinfo::Convert::Plaintext> C<output> method could be a good starting
+point. HTML and Info output are also based on output units conversion.
+Output units are not relevant for all the formats, the Texinfo tree can also be
+converted directly, in general by using C<output_tree>. This is how the other
+Converters are implemented.
+
+Existing backends based on C<output_tree> may be used as examples.
+C<Texinfo::Convert::Texinfo> together with C<Texinfo::Convert::PlainTexinfo>,
+as well as C<Texinfo::Convert::TextContent> are trivial examples.
+C<Texinfo::Convert::Text> is less trivial, although still simple, while
+C<Texinfo::Convert::DocBook> is a real converter that is also not too complex.
-The documentation of L<Texinfo::Common>, L<Texinfo::Convert::Unicode>
-describes modules or additional function that may be useful for backends,
-while the parsed Texinfo tree is described in L<Texinfo::Parser>.
+The documentation of L<Texinfo::Common>, L<Texinfo::OutputUnits>,
+L<Texinfo::Convert::Unicode> and L<Texinfo::Convert::Text> describes modules or
+additional function that may be useful for backends, while the parsed Texinfo
+tree is described in L<Texinfo::Parser>.
=head1 METHODS
@@ -2160,18 +2163,16 @@ C<Texinfo::Convert::Converter>.
=item $converter = MyConverter->converter($options)
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 or in the customization API manual.
-Those customization options, when appropriate, override the document content.
-B<TODO what about the other options?>
+These options should be Texinfo customization options. The
+customization options are described in the Texinfo manual or in the
+customization API manual.
The C<converter> function returns a converter object (a blessed hash
reference) after checking the options and performing some initializations.
=back
-To help with these initializations, the modules subclassing
C<Texinfo::Convert::Converter>
+To help with the initializations, the modules subclassing
C<Texinfo::Convert::Converter>
can define two methods:
=over
@@ -2179,9 +2180,11 @@ can define two methods:
=item \%defaults = $converter_or_class->converter_defaults($options)
X<C<converter_defaults>>
-The module can provide the reference on a hash with defaults for converter
-customization options. The I<$options> hash reference holds options for the
-converter. The function can be called both through a class or a converter.
+Returns a reference on a hash with defaults for the converter module
+customization options or C<undef>. The I<$options> hash reference holds
+options for the converter. This method is called through a converter by L<<<
+converter|/$converter = MyConverter->converter($options) >>>, but it may also
+be called through a converter module class.
=item converter_initialize
X<C<converter_initialize>>
@@ -2275,6 +2278,11 @@ information expect an object implementing C<get_conf>
and/or
C<set_conf>. The converter itself can therefore be used in
such cases.
+Customization variables are typically setup when
+initializing a converter with L<<< converter|/$converter =
MyConverter->converter($options) >>>
+and completed by Texinfo informative @-commands tree element values,
+for commands such as C<@frenchspacing> or C<@footnotestyle>.
+
=over
=item $converter->force_conf($variable_name, $variable_value)
@@ -2375,7 +2383,7 @@ I<$replaced_substrings> hash reference identifies what is
to be substituted.
In the string to be translated word in brace matching keys of
I<$replaced_substrings> are replaced.
For C<cdt>, the value is a Texinfo tree that is substituted in the
-resulting texinfo tree. For C<cdt_string>, the value is a string that
+resulting Texinfo tree. For C<cdt_string>, the value is a string that
is replaced in the resulting string.
The I<$translation_context> is optional. If not C<undef> this is a translation
@@ -2534,7 +2542,7 @@ split, the directory where the files should be created.
I<$output_filename>
is, in general, the file name portion of I<$output_file> (without directory)
but can also be set based on C<@setfilename>, in particular when
I<$output_file> is an empty string. I<$document_name> is I<$output_filename>
-without extension. I<$input_basefile> is based on the input texinfo file name,
+without extension. I<$input_basefile> is based on the input Texinfo file name,
with the file name portion only (without directory).
The strings returned are text strings.
@@ -2556,23 +2564,23 @@ the input file encoding. It is useful if there is more
precise information
on the input file encoding where the file name appeared.
Note that C<encoded_output_file_name> is a wrapper around the
-function with the same name in L<<<
Texinfo::Convert::Utils::encoded_output_file_name|Texinfo::Convert::Utils/($encoded_name,
$encoding) = $converter->encoded_output_file_name($converter,
$character_string_name) >>>,
+function with the same name in L<<<
Texinfo::Convert::Utils::encoded_output_file_name|Texinfo::Convert::Utils/($encoded_name,
$encoding) = $converter->encoded_output_file_name($character_string_name) >>>,
and C<encoded_input_file_name> is a wrapper around the
-function with the same name in L<<<
Texinfo::Convert::Utils::encoded_input_file_name|Texinfo::Convert::Utils/($encoded_name,
$encoding) = $converter->encoded_input_file_name($converter,
$character_string_name, $input_file_encoding) >>>.
+function with the same name in L<<<
Texinfo::Convert::Utils::encoded_input_file_name|Texinfo::Convert::Utils/($encoded_name,
$encoding) = $converter->encoded_input_file_name($character_string_name,
$input_file_encoding) >>>.
=item ($caption, $prepended) = $converter->float_name_caption($float)
X<C<float_name_caption>>
-I<$float> is a texinfo tree C<@float> element. This function
+I<$float> is a Texinfo tree C<@float> element. This function
returns the caption element that should be used for the float formatting
-and the I<$prepended> texinfo tree combining the type and label
+and the I<$prepended> Texinfo tree combining the type and label
of the float.
=item $tree = $converter->float_type_number($float)
X<C<float_type_number>>
-I<$float> is a texinfo tree C<@float> element. This function
-returns the type and number of the float as a texinfo tree with
+I<$float> is a Texinfo tree C<@float> element. This function
+returns the type and number of the float as a Texinfo tree with
translations.
=item $end_line = $converter->format_comment_or_return_end_line($element)
diff --git a/tp/Texinfo/Convert/Text.pm b/tp/Texinfo/Convert/Text.pm
index ced2961966..86cdadc36d 100644
--- a/tp/Texinfo/Convert/Text.pm
+++ b/tp/Texinfo/Convert/Text.pm
@@ -1132,7 +1132,7 @@ The conversion is very simple, and, in the default case,
cannot handle
error handling nor some output strings translation.
Converters derived from L<Texinfo::Convert::Converter> should have conversion
-text options associated to the C<convert_text_options> key.
+text options preset 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>,
@@ -1150,9 +1150,9 @@ options. The converter is very simple, and has almost no
internal state
besides the options. It cannot handle as is output strings translation or
error storing.
-If the I<converter> option is set, some additional features may be available
-for the conversion of some @-commands, like output strings translation or
-error reporting.
+If the I<converter> option is set in I<$text_options>, some additional features
+may be available for the conversion of some @-commands, like output strings
+translation or error reporting.
The C<NUMBER_SECTIONS>, C<ASCII_GLYPH> and C<TEST> options corresponding to
customization variables may be set in I<$text_options>. The following options
diff --git a/tp/Texinfo/Convert/Unicode.pm b/tp/Texinfo/Convert/Unicode.pm
index 1034b4e6d4..aeacdf93fb 100644
--- a/tp/Texinfo/Convert/Unicode.pm
+++ b/tp/Texinfo/Convert/Unicode.pm
@@ -1818,8 +1818,8 @@ conversion of the I<$stack>. I<$converter> is a
converter object optionaly
used by I<$format_accent>. It may be C<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.
+The I<$set_case> argument is optional. 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)
X<C<string_width>>
diff --git a/tp/Texinfo/Convert/Utils.pm b/tp/Texinfo/Convert/Utils.pm
index 2303f4abba..ecc2469781 100644
--- a/tp/Texinfo/Convert/Utils.pm
+++ b/tp/Texinfo/Convert/Utils.pm
@@ -751,9 +751,9 @@ 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.
-=item ($encoded_name, $encoding) =
$converter->encoded_input_file_name($converter, $character_string_name,
$input_file_encoding)
+=item ($encoded_name, $encoding) =
$converter->encoded_input_file_name($character_string_name,
$input_file_encoding)
-=item ($encoded_name, $encoding) =
$converter->encoded_output_file_name($converter, $character_string_name)
+=item ($encoded_name, $encoding) =
$converter->encoded_output_file_name($character_string_name)
X<C<encoded_input_file_name>> X<C<encoded_output_file_name>>
Encode I<$character_string_name> in the same way as other file names are
diff --git a/tp/Texinfo/Translations.pm b/tp/Texinfo/Translations.pm
index 46e7e26111..2d4ac68cf7 100644
--- a/tp/Texinfo/Translations.pm
+++ b/tp/Texinfo/Translations.pm
@@ -567,8 +567,8 @@ some substitution to be done after the translation. The
key of the
I<$replaced_substrings> hash reference identifies what is to be substituted.
In the string to be translated word in brace matching keys of
I<$replaced_substrings> are replaced.
-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
+For C<gdt>, the value is a Texinfo tree element 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 C<gdt>, similar to
@@ -583,7 +583,7 @@ 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:
+replaced by the associated Texinfo tree text element:
$tree = gdt('See {reference} in @cite{{book}}', "ca",
{'reference' => $tree_reference,
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- branch master updated: Update POD documentation,
Patrice Dumas <=