branch master updated: Document file name encoding functions in POD and customization_api.texi

[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 add50fe654 Document file name encoding functions in POD and 
customization_api.texi
add50fe654 is described below

commit add50fe654b830dd17e69247e5eb6303ed2060e3
Author: Patrice Dumas <pertusus@free.fr>
AuthorDate: Mon Mar 7 16:05:34 2022 +0100

    Document file name encoding functions in POD and customization_api.texi
---
 doc/customization_api.texi      | 69 ++++++++++++++++++++++++++++++++++++++---
 tp/TODO                         |  5 ++-
 tp/Texinfo/Common.pm            |  2 +-
 tp/Texinfo/Convert/Converter.pm | 17 ++++++++--
 tp/Texinfo/Convert/Utils.pm     | 11 ++++++-
 5 files changed, 95 insertions(+), 9 deletions(-)

diff --git a/doc/customization_api.texi b/doc/customization_api.texi
index 6329d15c5d..4876e805fa 100644
--- a/doc/customization_api.texi
+++ b/doc/customization_api.texi
@@ -1304,6 +1304,67 @@ documentation, in particular a list of types and of 
information in the elements
 @code{extra} hash (@pxref{Texinfo::Parser TEXINFO TREE,,,tp_api}).
 
 
+@node Encoding file path strings
+@section Encoding file path strings
+
+The strings in the customization functions are character strings.  For most 
purposes,
+this is right, and the encoding in output files is taken care of by the 
converter.
+Operations on directories and file names, however, such as the creation of a 
directory
+or the opening of a file require binary strings.
+
+To encode file names consistently with file name encoding used in the 
conversion to
+HTML, there is a function @code{encoded_output_file_name}:
+
+@deftypefun {$encoded_name, $encoding} $converter->encoded_output_file_name 
($character_string_name)
+Encode @var{$character_string_name} in the same way as other file name are
+encoded in the converter, based on @code{DOC_ENCODING_FOR_OUTPUT_FILE_NAME},
+and @code{LOCALE_OUTPUT_FILE_NAME_ENCODING} or on input file encoding
+(@pxref{Other Customization Variables,,, texinfo, Texinfo}).  Return the
+encoded name and the encoding used to encode the name.
+@end deftypefun
+
+There is also a similar function for the input file names encoding,
+@code{encoded_input_file_name}, which uses
+@code{DOC_ENCODING_FOR_INPUT_FILE_NAME} and
+@code{LOCALE_INPUT_FILE_NAME_ENCODING} and is less likely to be useful.
+
+When calling external commands, the command line arguments should also
+be encoded.  To do similarly with other codes, the customization variable
+@code{LOCALE_OUTPUT_ENCODING_NAME} should be used.  Already encoded file
+names may be used.  For example
+
+@example
+use Encode qw(encode);
+
+....
+
+my ($encoded_file_path, $encoding)
+  = $converter->encoded_output_file_name($file_name);
+
+my $fh = open($encoded_file_path);
+
+.....
+
+my $call_start = "command --set '$action' ";
+my $encoding = $converter->get_conf('LOCALE_OUTPUT_ENCODING_NAME');
+if (defined($encoding)) @{
+  $encoded_call_start = encode($encoding, $call_start);
+@} else @{
+  $encoded_call_start = $call_start;
+@}
+my $encoded_call = $encoded_call_start . $encoded_file_path;
+my $call = $call_start . $file_name;
+if (system($encoded_call)) @{
+ $converter->document_error($converter,
+     sprintf(__("command did not succeed: %s"),
+            $call));
+@}
+@end example
+
+More information on perl and encodings in
+@uref{https://perldoc.perl.org/perlunifaq, perlunifaq}.
+
+
 @node Setting the Context for Conversion
 @section Setting the Context for Conversion
 
@@ -2015,7 +2076,7 @@ The function used is:
 function. Returns the default formatting function reference.
 @end deftypefun
 
-The string that should be usedd to register or call each of the formatting 
functions
+The string that should be used to register or call each of the formatting 
functions
 and the call of the formatting functions are documented in the following 
sections of
 the manual, depending on where they are relevant.
 
@@ -2462,7 +2523,7 @@ done in the sectioning commands conversion function only.
 The function for registering opened section extent is
 @code{register_opened_section_level}:
 
-@defun $converter->register_opened_section_level($level, $closing_text)
+@defun $converter->register_opened_section_level ($level, $closing_text)
 @var{$level} is the sectioning command level.  It is typically
 obtained with @code{section->@{'structure'@}->@{'section_level'@}}
 (@pxref{Texinfo Tree Elements in User Defined Functions}).
@@ -2473,7 +2534,7 @@ section level @var{$level} is closed.
 The function for closing registered section extents is
 @code{close_registered_sections_level}:
 
-@deftypefun @@closing_texts $converter->close_registered_sections_level($level)
+@deftypefun @@closing_texts $converter->close_registered_sections_level 
($level)
 @var{$level} is the sectioning command level.  Opened section are closed
 down to section level @var{$level}.  The closing texts are returned in the
 @var{@@closing_texts} array in order.
@@ -2849,7 +2910,7 @@ functions formatting their argument elsewhere, two 
functions are available:
 @code{register_footnote} to be called where they appear in the document, and
 @code{get_pending_footnotes} to be called where they are formatted.
 
-@defun $converter->register_footnote(\%element, $footnote_id, @
+@defun $converter->register_footnote (\%element, $footnote_id, @
   $foot_in_doc_id, $number_in_doc, $footnote_location_filename, 
$multi_expanded_region)
 @var{\%element} is the footnote texinfo tree element. @var{$footnote_id} is the
 identifier for the location where the footnote arguments are expanded.
diff --git a/tp/TODO b/tp/TODO
index c20badebab..57d4cc5747 100644
--- a/tp/TODO
+++ b/tp/TODO
@@ -35,7 +35,7 @@ and @ref{Inserting Accents}.
 Texinfo input manual encoding?
 
 
-bytes.  document
+bytes.  document more somewhere?
 * texi2any.pl
  @input_files = @ARGV
   $input_file_arg
@@ -43,6 +43,9 @@ bytes.  document
  @css_files, CSS_FILES
  MACRO_EXPAND
  INTERNAL_LINKS
+* Parser:
+ $self->{'parser_info'}->{'input_file_name'}
+ $self->{'info'}->{'input_directory'}
 
 
 Bugs
diff --git a/tp/Texinfo/Common.pm b/tp/Texinfo/Common.pm
index bc9d9e3bfa..bc0a24d973 100644
--- a/tp/Texinfo/Common.pm
+++ b/tp/Texinfo/Common.pm
@@ -1535,7 +1535,7 @@ sub parse_node_manual($)
 # ASCII, as the name of the directory it is located within may contain
 # non-ASCII characters.
 #   Otherwise, the -e operator and similar may not work correctly.
-# TODO document.  Use configuration_information?
+# TODO Really use configuration_information?  Document when the API is final
 sub encode_file_name($$;$)
 {
   my $configuration_information = shift;
diff --git a/tp/Texinfo/Convert/Converter.pm b/tp/Texinfo/Convert/Converter.pm
index 9d60b428e4..67708e01b2 100644
--- a/tp/Texinfo/Convert/Converter.pm
+++ b/tp/Texinfo/Convert/Converter.pm
@@ -1032,7 +1032,6 @@ sub present_bug_message($$;$)
 }
 
 # Reverse the decoding of the file name from the input encoding.
-# TODO document
 sub encoded_input_file_name($$)
 {
   my $self = shift;
@@ -1051,7 +1050,6 @@ sub encoded_input_file_name($$)
   }
 }
 
-# TODO document
 # A wrapper around Texinfo::Utils::encoded_output_file_name() that
 # can be called in converters through an objet oriented syntax.
 sub encoded_output_file_name($$)
@@ -1792,6 +1790,21 @@ with the file name portion only (without directory).
 
 The strings returned are text strings.
 
+=item ($encoded_name, $encoding) = 
$converter->encoded_input_file_name($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 name are
+encoded in the converter, based on customization variables, and possibly
+on the input file encoding.  Return the encoded name and the encoding
+used to encode the name.  The C<encoded_input_file_name> and
+C<encoded_output_file_name> functions use different customization variables to
+determine the encoding.
+
+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) >>>.
+
 =item ($caption, $prepended) = $converter->float_name_caption($float)
 X<C<float_name_caption>>
 
diff --git a/tp/Texinfo/Convert/Utils.pm b/tp/Texinfo/Convert/Utils.pm
index 9f4fdf0b0c..a2052b74aa 100644
--- a/tp/Texinfo/Convert/Utils.pm
+++ b/tp/Texinfo/Convert/Utils.pm
@@ -308,7 +308,6 @@ sub numbered_heading($$$;$)
   return $result;
 }
 
-# TODO document
 # this requires a converter argument
 sub encoded_output_file_name($$)
 {
@@ -402,6 +401,16 @@ 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_output_file_name($converter, $character_string_name)
+X<C<encoded_output_file_name>>
+
+Encode I<$character_string_name> in the same way as other file name are
+encoded in converters, based on customization variables, and possibly
+on the input file encoding.  Return the encoded name and the encoding
+used to encode the name.  The I<$converter> argument is not optional
+and is used both to access to customization variables and to access to parser
+information.
+
 =item $tree = expand_today($converter)
 X<C<expand_today>>