branch master updated: * tp/Texinfo/Convert/Converter.pm: changes in POD documentation and comment.

[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 552f59395f * tp/Texinfo/Convert/Converter.pm: changes in POD 
documentation and comment.
552f59395f is described below

commit 552f59395f0e668cc06b41213a8e7a7ea17971ed
Author: Patrice Dumas <pertusus@free.fr>
AuthorDate: Fri Aug 30 21:43:19 2024 +0200

    * tp/Texinfo/Convert/Converter.pm: changes in POD documentation and
    comment.
---
 ChangeLog                                          |  5 +++++
 .../api_includes/Texinfo-Convert-Converter.texi    | 20 +++++++++----------
 tp/Texinfo/Convert/Converter.pm                    | 23 +++++++++++-----------
 3 files changed, 27 insertions(+), 21 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 6bbfc697fe..078f6cd96d 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+2024-08-30  Patrice Dumas  <pertusus@free.fr>
+
+       * tp/Texinfo/Convert/Converter.pm: changes in POD documentation and
+       comment.
+
 2024-08-30  Patrice Dumas  <pertusus@free.fr>
 
        * tp/Texinfo/Convert/Converter.pm (%common_converters_defaults)
diff --git a/doc/tp_api/api_includes/Texinfo-Convert-Converter.texi 
b/doc/tp_api/api_includes/Texinfo-Convert-Converter.texi
index d46929664e..691c5ae93f 100644
--- a/doc/tp_api/api_includes/Texinfo-Convert-Converter.texi
+++ b/doc/tp_api/api_includes/Texinfo-Convert-Converter.texi
@@ -128,7 +128,7 @@ In general, @code{output} and @code{output_tree} output to 
files and return @cod
 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.  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}.
+@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),, 
@code{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)
@@ -149,10 +149,10 @@ Can be used for the conversion of output units by 
converters.
 @code{convert_output_unit} takes a @emph{$converter} and an output unit
 @emph{$output_unit} as argument.  The implementation of
 @code{convert_output_unit} of @code{Texinfo::Convert::Converter} could be 
suitable in
-many cases.  Output units are typically returned by 
@ref{Texinfo@asis{::}OutputUnits $output_units = split_by_section($document),, 
Texinfo::OutputUnits
-split_by_section}
+many cases.  Output units are typically returned by 
@ref{Texinfo@asis{::}OutputUnits $output_units = split_by_section($document),, 
@code{Texinfo::OutputUnits}
+@code{split_by_section}}
 or @ref{Texinfo@asis{::}OutputUnits $output_units =
-split_by_node($document),, Texinfo::OutputUnits split_by_node}.
+split_by_node($document),, @code{Texinfo::OutputUnits} @code{split_by_node}}.
 
 @end table
 
@@ -228,7 +228,7 @@ can define two methods:
 
 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
+options for the converter.  This method is called through a converter by 
@ref{Texinfo@asis{::}Convert@asis{::}Converter $converter = 
MyConverter->converter($options),, @code{converter}}, but it may also
 be called through a converter module class.
 
 @item converter_initialize
@@ -257,7 +257,7 @@ implementations.
 Associate @emph{$document} to @emph{$converter}.  Also set the encoding 
related customization
 options based on @emph{$converter} customization information and information on
 document encoding, and setup converter hash @code{convert_text_options} value 
that
-can be used to call @ref{Texinfo@asis{::}Convert@asis{::}Text $result = 
convert_to_text($tree@comma{} $text_options),, 
Texinfo::Convert::Text::convert_to_text}.
+can be used to call @ref{Texinfo@asis{::}Convert@asis{::}Text $result = 
convert_to_text($tree@comma{} $text_options),, 
@code{Texinfo::Convert::Text::convert_to_text}}.
 
 @end table
 
@@ -331,7 +331,7 @@ information expect an object implementing @code{get_conf} 
and/or
 such cases.
 
 Customization variables are typically setup when
-initializing a converter with @ref{Texinfo@asis{::}Convert@asis{::}Converter 
$converter = MyConverter->converter($options),, converter}
+initializing a converter with @ref{Texinfo@asis{::}Convert@asis{::}Converter 
$converter = MyConverter->converter($options),, @code{converter}}
 and completed by Texinfo informative @@-commands tree element values,
 for commands such as @code{@@frenchspacing} or @code{@@footnotestyle}.
 
@@ -645,9 +645,9 @@ 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($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),, 
@code{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($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),, 
@code{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)}
@@ -739,7 +739,7 @@ variable value, no @@-command side effects are run, no 
associated customization
 variables are set.
 
 For more information on the function used to set the value for each of the 
command, see
-@ref{Texinfo@asis{::}Common $element = 
set_global_document_command($customization_information@comma{} 
$global_commands_information@comma{} $cmdname@comma{} $command_location),, 
Texinfo::Common set_global_document_command}.
+@ref{Texinfo@asis{::}Common $element = 
set_global_document_command($customization_information@comma{} 
$global_commands_information@comma{} $cmdname@comma{} $command_location),, 
@code{Texinfo::Common} @code{set_global_document_command}}.
 
 @item $table_item_tree = $converter->table_item_content_tree($element)
 @anchor{Texinfo@asis{::}Convert@asis{::}Converter $table_item_tree = 
$converter->table_item_content_tree($element)}
diff --git a/tp/Texinfo/Convert/Converter.pm b/tp/Texinfo/Convert/Converter.pm
index a5e11efdfc..fc24000803 100644
--- a/tp/Texinfo/Convert/Converter.pm
+++ b/tp/Texinfo/Convert/Converter.pm
@@ -139,7 +139,8 @@ my $common_defaults = 
Texinfo::Options::get_converter_regular_options('common');
 # as "configuration/customization". It is not available through get_conf()
 # but is available directly in the converter as a hash key.
 # FIXME separate the two types of information and check that those
-# items are not valid customization options?
+# items are not valid customization options?  Or make them customization
+# variables that can only be set from init files, like buttons or icons?
 # NOTE converters for now only set customization variables.
 # It would be good to keep it that way.
 my %common_converters_defaults = (
@@ -2086,7 +2087,7 @@ 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.  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) >>>.
+L<<< C<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)
@@ -2105,9 +2106,9 @@ Can be used for the conversion of output units by 
converters.
 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::OutputUnits
-split_by_section|Texinfo::OutputUnits/$output_units = 
split_by_section($document)>
-or L<Texinfo::OutputUnits split_by_node|Texinfo::OutputUnits/$output_units =
+many cases.  Output units are typically returned by L<C<Texinfo::OutputUnits>
+C<split_by_section>|Texinfo::OutputUnits/$output_units = 
split_by_section($document)>
+or L<C<Texinfo::OutputUnits> 
C<split_by_node>|Texinfo::OutputUnits/$output_units =
 split_by_node($document)>.
 
 =back
@@ -2183,7 +2184,7 @@ X<C<converter_defaults>>
 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
+C<converter>|/$converter = MyConverter->converter($options) >>>, but it may 
also
 be called through a converter module class.
 
 =item converter_initialize
@@ -2210,7 +2211,7 @@ 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)>.
+can be used to call 
L<C<Texinfo::Convert::Text::convert_to_text>|Texinfo::Convert::Text/$result = 
convert_to_text($tree, $text_options)>.
 
 =back
 
@@ -2279,7 +2280,7 @@ 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) >>>
+initializing a converter with L<<< C<converter>|/$converter = 
MyConverter->converter($options) >>>
 and completed by Texinfo informative @-commands tree element values,
 for commands such as C<@frenchspacing> or C<@footnotestyle>.
 
@@ -2564,9 +2565,9 @@ 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($character_string_name) >>>,
+function with the same name in L<<< 
C<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($character_string_name, 
$input_file_encoding) >>>.
+function with the same name in L<<< 
C<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>>
@@ -2648,7 +2649,7 @@ variable value, no @-command side effects are run, no 
associated customization
 variables are set.
 
 For more information on the function used to set the value for each of the 
command, see
-L<Texinfo::Common set_global_document_command|Texinfo::Common/$element = 
set_global_document_command($customization_information, 
$global_commands_information, $cmdname, $command_location)>.
+L<C<Texinfo::Common> C<set_global_document_command>|Texinfo::Common/$element = 
set_global_document_command($customization_information, 
$global_commands_information, $cmdname, $command_location)>.
 
 =item $table_item_tree = $converter->table_item_content_tree($element)
 X<C<table_item_content_tree>>