branch master updated: Changes in comments/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 6b0c5eeb93 Changes in comments/documentation.
6b0c5eeb93 is described below

commit 6b0c5eeb93c9301de8a827994c437a0257d22530
Author: Patrice Dumas <pertusus@free.fr>
AuthorDate: Mon Feb 7 23:35:57 2022 +0100

    Changes in comments/documentation.
---
 Pod-Simple-Texinfo/Makefile.PL               |  7 +++++++
 Pod-Simple-Texinfo/lib/Pod/Simple/Texinfo.pm | 13 ++++++++++---
 Pod-Simple-Texinfo/pod2texi.pl               | 10 ++++++++--
 doc/customization_api.texi                   |  2 ++
 man/pod2texi.1                               |  8 ++++----
 5 files changed, 31 insertions(+), 9 deletions(-)

diff --git a/Pod-Simple-Texinfo/Makefile.PL b/Pod-Simple-Texinfo/Makefile.PL
index 42eebefd85..df3a02ce88 100644
--- a/Pod-Simple-Texinfo/Makefile.PL
+++ b/Pod-Simple-Texinfo/Makefile.PL
@@ -2,6 +2,12 @@ use 5.000;
 use ExtUtils::MakeMaker;
 # See lib/ExtUtils/MakeMaker.pm for details of how to influence
 # the contents of the Makefile that is written.
+
+# FIXME no idea how to change @INC for make test
+
+my $tpdir = '../tp';
+# "-I$tpdir -I$tpdir/maintain/lib/Unicode-EastAsianWidth/lib/ 
-I$tpdir/maintain/lib/libintl-perl/lib  
-I$tpdir/maintain/lib/Text-Unidecode/lib/"
+
 WriteMakefile(
     NAME              => 'Pod::Simple::Texinfo',
     VERSION_FROM      => 'lib/Pod/Simple/Texinfo.pm', # finds $VERSION
@@ -11,6 +17,7 @@ WriteMakefile(
                            "Getopt::Long" => 0,
                            "File::Spec" => 0,
                            "File::Basename" => 0, }, # e.g., Module::Name => 
1.1
+#    FULLPERLRUN       => '$(FULLPERL) '."-I$tpdir 
-I$tpdir/maintain/lib/Unicode-EastAsianWidth/lib/ 
-I$tpdir/maintain/lib/libintl-perl/lib  
-I$tpdir/maintain/lib/Text-Unidecode/lib/",
     ($] >= 5.005 ?     ## Add these new keywords supported since 5.005
       (ABSTRACT_FROM  => 'lib/Pod/Simple/Texinfo.pm', # retrieve abstract from 
module
        AUTHOR         => 'Patrice Dumas <pertusus@free.fr>') : ()),
diff --git a/Pod-Simple-Texinfo/lib/Pod/Simple/Texinfo.pm 
b/Pod-Simple-Texinfo/lib/Pod/Simple/Texinfo.pm
index e7ff2d749d..9f167cc5c4 100644
--- a/Pod-Simple-Texinfo/lib/Pod/Simple/Texinfo.pm
+++ b/Pod-Simple-Texinfo/lib/Pod/Simple/Texinfo.pm
@@ -181,8 +181,6 @@ sub _preamble($)
       $setfilename .= '.info';
       print $fh "\@setfilename $setfilename\n\n"
     }
-    # FIXME depend on =encoding
-    print $fh '@documentencoding utf-8'."\n\n";
 
     my $title = $self->get_title();
     if (defined($title) and $title =~ m/\S/) {
@@ -460,7 +458,13 @@ my %line_commands = (
   'item-bullet' => 'item',
   'item-text' => 'item',
   'item-number' => 'item',
-  'encoding' => 'documentencoding'
+# =encoding is not emitted by Pod::Simple.  We get decoded characters here and
+# assume that the callers always output utf8.
+# It is ok, as it is right to use utf8 as encoding, and it matches the default
+# of Texinfo, removing the need to set @documentencoding.  Even if =encoding 
was
+# emitted, it would still be best to avoid @documentencoding and assume utf8 is
+# output.
+#  'encoding' => 'documentencoding'
 );
 
 foreach my $tag (keys(%head_commands_level)) {
@@ -793,6 +797,9 @@ methods (and options).
 It supports producing a standalone manual per Pod (the default) or
 render the Pod as a chapter, see L</texinfo_sectioning_base_level>.
 
+C<@@documentencoding> is not output, which is consistent with outputting
+the Texinfo output in utf8 in the caller.
+
 =head1 METHODS
 
 =over
diff --git a/Pod-Simple-Texinfo/pod2texi.pl b/Pod-Simple-Texinfo/pod2texi.pl
index 03d578943e..17a30a6178 100755
--- a/Pod-Simple-Texinfo/pod2texi.pl
+++ b/Pod-Simple-Texinfo/pod2texi.pl
@@ -362,9 +362,14 @@ foreach my $file (@processed_files) {
                                           $real_command_name, $outfile, $!);
     $fh = *OUT;
   }
-  # FIXME should use =encoding
+  # The Texinfo output from Pod::Simple::Texinfo does not contain
+  # @documentencoding.  We output utf8 as it is consistent with no
+  # @documentencoding, and it also because is the best choice or encoding.
+  # The =encoding information is not available anyway, but even if it
+  # was it would still be better to output utf8.
   binmode($fh, ':encoding(utf8)');
 
+  # this sets the string that $parser's output will be sent to
   $new->output_string(\$manual_texi);
 
   $new->texinfo_sectioning_base_level($base_level);
@@ -445,7 +450,8 @@ if ($base_level > 0) {
     $fh = *STDOUT;
   }
 
-  # FIXME should use =encoding
+  # We output utf8 as it is default for Texinfo and is consistent with no
+  # @documentencoding, and it also because is the best choice or encoding.
   binmode($fh, ':encoding(utf8)');
 
   my $outfile_name = $output;
diff --git a/doc/customization_api.texi b/doc/customization_api.texi
index f33e9a0a5d..be4a345689 100644
--- a/doc/customization_api.texi
+++ b/doc/customization_api.texi
@@ -1230,6 +1230,8 @@ $converter->convert_tree($converter->gdt(
 @end example
 
 @xref{Texinfo::Translations,,,tp_api} for more on @code{Texinfo::Translations}.
+@xref{Internationalization of Document Strings,,, texinfo, Texinfo} for an
+overview.
 
 
 @node Texinfo Tree Elements in User Defined Functions
diff --git a/man/pod2texi.1 b/man/pod2texi.1
index e0a543d043..737fe822a6 100644
--- a/man/pod2texi.1
+++ b/man/pod2texi.1
@@ -133,7 +133,7 @@
 .\" ========================================================================
 .\"
 .IX Title "POD2TEXI 1"
-.TH POD2TEXI 1 "2022-01-14" "perl v5.32.1" "User Contributed Perl 
Documentation"
+.TH POD2TEXI 1 "2022-02-07" "perl v5.32.1" "User Contributed Perl 
Documentation"
 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 .\" way too many mistakes in technical documents.
 .if n .ad l
@@ -198,9 +198,9 @@ Do not fill sectioning gaps with empty \f(CW@unnumbered\fR 
files.
 Ordinarily, it's good to keep the sectioning hierarchy intact.
 .IP "\fB\-\-preamble\fR=\fI\s-1STR\s0\fR" 4
 .IX Item "--preamble=STR"
-Insert \fI\s-1STR\s0\fR as top boilerplate before includes.  The default is a
-minimal beginning for a Texinfo document, and sets \f(CW@documentencoding\fR
-to \f(CW\*(C`utf\-8\*(C'\fR (because the output is written that way).
+Insert \fI\s-1STR\s0\fR as top boilerplate before includes.  If 
\fI\s-1STR\s0\fR is set to
+\&\f(CW\*(C`\-\*(C'\fR, read the top boilerplate from the standard input.  The 
default
+top boilerplate is a minimal beginning for a Texinfo document.
 .IP "\fB\-\-subdir\fR=\fI\s-1NAME\s0\fR" 4
 .IX Item "--subdir=NAME"
 If there is a main manual with include files (each corresponding to