branch master updated: Add more documentation for Pod::Simple::Texinfo, change variable names, reindent.

[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 4ec62a390a Add more documentation for Pod::Simple::Texinfo, change 
variable names, reindent.
4ec62a390a is described below

commit 4ec62a390a4ab38ce170513c7c25c592248f8a3c
Author: Patrice Dumas <pertusus@free.fr>
AuthorDate: Tue Feb 8 11:36:46 2022 +0100

    Add more documentation for Pod::Simple::Texinfo, change variable names,
    reindent.
---
 Pod-Simple-Texinfo/lib/Pod/Simple/Texinfo.pm | 127 +++++++++++++++------------
 Pod-Simple-Texinfo/pod2texi.pl               |  27 +++---
 man/pod2texi.1                               |  15 ++--
 3 files changed, 92 insertions(+), 77 deletions(-)

diff --git a/Pod-Simple-Texinfo/lib/Pod/Simple/Texinfo.pm 
b/Pod-Simple-Texinfo/lib/Pod/Simple/Texinfo.pm
index 9f167cc5c4..7380a33752 100644
--- a/Pod-Simple-Texinfo/lib/Pod/Simple/Texinfo.pm
+++ b/Pod-Simple-Texinfo/lib/Pod/Simple/Texinfo.pm
@@ -1,6 +1,6 @@
 # Texinfo.pm: format Pod as Texinfo.
 #
-# Copyright 2011, 2012, 2013, 2014 Free Software Foundation, Inc.
+# Copyright 2011, 2012, 2013, 2014, 2022 Free Software Foundation, Inc.
 # 
 # This program is free software; you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -44,13 +44,13 @@ $VERSION = '0.01';
 
 #use UNIVERSAL ();
 
-# Allows being called from the comand line as
+# Allows being called from the command line as
 # perl -w -MPod::Simple::Texinfo -e Pod::Simple::Texinfo::go thingy.pod
 sub go { Pod::Simple::Texinfo->parse_from_file(@ARGV); exit 0 }
 
-my %head_commands_level;
+my %pod_head_commands_level;
 foreach my $level (1 .. 4) {
-  $head_commands_level{'head'.$level} = $level;
+  $pod_head_commands_level{'head'.$level} = $level;
 }
 
 my @numbered_sectioning_commands = ('part', 'chapter', 'section', 'subsection',
@@ -65,13 +65,13 @@ my @raw_formats = ('html', 'HTML', 'docbook', 'DocBook', 
'texinfo',
 
 # from other Pod::Simple modules.  Creates accessor subroutine.
 __PACKAGE__->_accessorize(
-  'texinfo_sectioning_base_level',
-  'texinfo_short_title',
-  'texinfo_man_url_prefix',
-  'texinfo_sectioning_style',
   'texinfo_add_upper_sectioning_command',
-  'texinfo_section_nodes',
   'texinfo_internal_pod_manuals',
+  'texinfo_man_url_prefix',
+  'texinfo_section_nodes',
+  'texinfo_sectioning_base_level',
+  'texinfo_sectioning_style',
+  'texinfo_short_title',
 );
 
 my $sectioning_style = 'numbered';
@@ -117,21 +117,22 @@ sub run
   } else {
     $self->{'texinfo_sectioning_commands'} = \@appendix_sectioning_commands;
   }
-  foreach my $heading_command (keys(%head_commands_level)) {
-    my $level = $head_commands_level{$heading_command} + $base_level -1;
-    if (!defined($self->{'texinfo_sectioning_commands'}->[$level])) {
+  foreach my $heading_command (keys(%pod_head_commands_level)) {
+    my $level = $pod_head_commands_level{$heading_command} + $base_level -1;
+    if (defined($self->{'texinfo_sectioning_commands'}->[$level])) {
       $self->{'texinfo_head_commands'}->{$heading_command}
-        = $self->{'texinfo_sectioning_commands'}->[-1];
+        = $self->{'texinfo_sectioning_commands'}->[$level];
     } else {
       $self->{'texinfo_head_commands'}->{$heading_command}
-        = $self->{'texinfo_sectioning_commands'}->[$level];
+        = $self->{'texinfo_sectioning_commands'}->[-1];
     }
   }
+  # contain all the manuals that are part of the same output
   $self->{'texinfo_internal_pod_manuals_hash'} = {};
   my $manuals = $self->texinfo_internal_pod_manuals();
   if ($manuals) {
     foreach my $manual (@$manuals) {
-       $self->{'texinfo_internal_pod_manuals_hash'}->{$manual} = 1;
+      $self->{'texinfo_internal_pod_manuals_hash'}->{$manual} = 1;
     }
   }
 
@@ -188,26 +189,26 @@ sub _preamble($)
     }
     print $fh "\@node Top\n";
     if (defined($self->texinfo_short_title())) {
-       print $fh "\@top "._protect_text($self->texinfo_short_title(), 
1)."\n\n";
+      print $fh "\@top "._protect_text($self->texinfo_short_title(), 1)."\n\n";
     }
   } elsif (defined($self->texinfo_short_title())
            and $self->texinfo_add_upper_sectioning_command()) {
-      my $level = $self->texinfo_sectioning_base_level() - 1;
-      my $name = _protect_text($self->texinfo_short_title(), 1);
-      my $node_name = _prepare_anchor($self, $name);
-
-      my $anchor = '';
-      my $node = '';
-      if ($node_name =~ /\S/) {
-        if (!$self->texinfo_section_nodes()
-            or $self->{'texinfo_sectioning_commands'}->[$level] eq 'part') {
-          $anchor = "\@anchor{$node_name}\n";
-        } else {
-          $node = "\@node $node_name\n";
-        }
+    my $level = $self->texinfo_sectioning_base_level() - 1;
+    my $name = _protect_text($self->texinfo_short_title(), 1);
+    my $node_name = _prepare_anchor($self, $name);
+
+    my $anchor = '';
+    my $node = '';
+    if ($node_name =~ /\S/) {
+      if (!$self->texinfo_section_nodes()
+          or $self->{'texinfo_sectioning_commands'}->[$level] eq 'part') {
+        $anchor = "\@anchor{$node_name}\n";
+      } else {
+        $node = "\@node $node_name\n";
       }
-      print $fh "$node\@$self->{'texinfo_sectioning_commands'}->[$level] "
-         ._protect_text($self->texinfo_short_title(), 1)."\n$anchor\n";
+    }
+    print $fh "$node\@$self->{'texinfo_sectioning_commands'}->[$level] "
+       ._protect_text($self->texinfo_short_title(), 1)."\n$anchor\n";
   }
 }
 
@@ -467,17 +468,16 @@ my %line_commands = (
 #  'encoding' => 'documentencoding'
 );
 
-foreach my $tag (keys(%head_commands_level)) {
-  $line_commands{$tag} = 1;
+foreach my $pod_head_command (keys(%pod_head_commands_level)) {
+  $line_commands{$pod_head_command} = 1;
 }
 
-my %tags_index_before;
 my %context_tags;
 foreach my $context_tag (keys(%line_commands), 'L', 'X', 'Para') {
   $context_tags{$context_tag} = 1;
 }
 
-# do not appear as parsed token
+# does not appear as parsed token
 # E entity/character
 sub _convert_pod($)
 {
@@ -641,13 +641,13 @@ sub _convert_pod($)
         if ($line_commands{$tagname}) {
 
           my ($command, $command_argument);
-          if ($head_commands_level{$tagname}) {
+          if ($pod_head_commands_level{$tagname}) {
             $command = $self->{'texinfo_head_commands'}->{$tagname};
           } elsif ($line_commands{$tagname}) {
             $command = $line_commands{$tagname};
           }
 
-          if ($head_commands_level{$tagname} or $tagname eq 'item-text') {
+          if ($pod_head_commands_level{$tagname} or $tagname eq 'item-text') {
             chomp ($result);
             $result =~ s/\n/ /g;
             $result =~ s/^\s*//;
@@ -797,25 +797,48 @@ 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.
+C<@documentencoding> is not output, which is consistent with outputting
+Texinfo in utf8 in the caller.
 
 =head1 METHODS
 
 =over
 
-=item texinfo_sectioning_base_level
+=item texinfo_add_upper_sectioning_command
 
-Sets the level of the head1 commands.  1 is for the @chapter/@unnumbered
-level.  If set to 0, the head1 commands level is still 1, but the output
-manual is considered to be a standalone manual.  If not 0, the pod file is
-rendered as a fragment of a Texinfo manual.
+If set (the default case), a sectioning command is added at the beginning
+of the output for the whole document, using the module name, at the level
+above the level set by L<texinfo_sectioning_base_level>.  So there will be
+a C<@part> if the level is equal to 1, a C<@chapter> if the level is equal
+to 2 and so on and so forth.  If the base level is 0, a C<@top> command is
+output instead.
+
+=item texinfo_internal_pod_manuals
+
+The argument should be a reference on an array containing the short
+titles (usually the module names) of all the pod documents that are
+converted together and should be internal in the Texinfo document obtained
+by including all those pod manuals.  References to those documents use
+the internal reference commands formatting in Texinfo.
+
+Corresponds to L<texinfo_sectioning_base_level> set to anything else than 0.
 
 =item texinfo_man_url_prefix
 
 String used as a prefix for man page urls.  Default
 is C<http://man.he.net/man>.
 
+=item texinfo_section_nodes
+
+If set, add C<@node> and not C<@anchor> for each sectioning command.
+
+=item texinfo_sectioning_base_level
+
+Sets the level of the head1 commands.  1 is for the @chapter/@unnumbered
+level.  If set to 0, the head1 commands level is still 1, but the output
+manual is considered to be a standalone manual.  If not 0, the pod file is
+rendered as a fragment of a Texinfo manual.
+
 =item texinfo_sectioning_style
 
 Default is C<numbered>, using the numbered sectioning Texinfo @-commands
@@ -823,18 +846,12 @@ Default is C<numbered>, using the numbered sectioning 
Texinfo @-commands
 sectioning command variants (@unnumbered...), and any other value would
 lead to using appendix sectioning command variants (@appendix...).
 
-=item texinfo_add_upper_sectioning_command
+=item texinfo_short_title
 
-If set (the default case), a sectioning command is added at the beginning
-of the output for the whole document, using the module name, at the level
-above the level set by L<texinfo_sectioning_base_level>.  So there will be
-a C<@part> if the level is equal to 1, a C<@chapter> if the level is equal
-to 2 and so on and so forth.  If the base level is 0, a C<@top> command is
-output instead.
-
-=item texinfo_section_nodes
-
-If set, add C<@node> and not C<@anchor> for each sectioning command.
+If set, used as short title.  Otherwise, set to the module name with
+L<<< Pod::Simple::PullParser->get_short_title|Pod::Simple::PullParser/my 
$title_string = $parser->get_short_title >>>.
+Can be accessed to get the module name associated with a 
C<Pod::Simple::Texinfo>
+parser.
 
 =back
 
diff --git a/Pod-Simple-Texinfo/pod2texi.pl b/Pod-Simple-Texinfo/pod2texi.pl
index 17a30a6178..0c0229bd3e 100755
--- a/Pod-Simple-Texinfo/pod2texi.pl
+++ b/Pod-Simple-Texinfo/pod2texi.pl
@@ -1,6 +1,6 @@
 #! /usr/bin/env perl
 # pod2texi -- convert Pod to Texinfo.
-# Copyright 2012-2021 Free Software Foundation, Inc.
+# Copyright 2012-2022 Free Software Foundation, Inc.
 # 
 # This program is free software; you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -107,10 +107,9 @@ sub pod2texi_help()
 basic modes of operation.  First, by default, each pod is translated to
 a standalone Texinfo manual.
 
-Second, if C<--base-level> is set higher than 0, each pod is translated
-to a file suitable for C<\@include>, and one more file with all the
-C<\@include>s is generated, intended to be C<\@include>d in turn within
-a hand-written top-level file.");
+Second, if --base-level is set higher than 0, each pod is translated
+to a file suitable for \@include, and one more file with a main menu
+and all the \@include is generated.");
   $pod2texi_help .= "\n\n";
   $pod2texi_help .= __("Options:
     --appendix-sections     use appendix-like sections")."\n";
@@ -121,7 +120,8 @@ a hand-written top-level file.");
   $pod2texi_help .= __("    --no-section-nodes      use anchors for sections 
instead of nodes")."\n";
   $pod2texi_help .= __("    --output=NAME           output to NAME for the 
first or main manual
                             instead of standard output")."\n";
-  $pod2texi_help .= __("    --preamble=STR          insert STR as beginning 
boilerplate")."\n";
+  $pod2texi_help .= __("    --preamble=STR          insert STR as beginning 
boilerplate.
+                            Defaults to a minimal Texinfo document 
beginning")."\n";
   $pod2texi_help .= __("    --subdir=NAME           put files included in the 
main manual in NAME")."\n";
   $pod2texi_help .= __("    --top                   top for the main 
manual")."\n";
   $pod2texi_help .= __("    --unnumbered-sections   do not number 
sections")."\n";
@@ -204,7 +204,7 @@ if ($base_level > 0) {
   foreach my $file (@input_files) {
     # we don't want to read from STDIN, as the input read would be lost
     # same with named pipe and socket...
-    # FIXME are there other file that have the same problem?
+    # FIXME are there other file types that have the same problem?
     next if ($file eq '-' or -p $file or -S $file);
     # not really used, only the manual name is used.
     my $parser = Pod::Simple::PullParserRun->new();
@@ -519,9 +519,8 @@ operation.  First, by default, each pod is translated to a 
standalone
 Texinfo manual.
 
 Second, if C<--base-level> is set higher than 0, each pod is translated
-to a file suitable for C<@include>, and one more file with all the
-C<@include>s is generated, intended to be C<@include>d in turn within a
-hand-written top-level file.
+to a file suitable for C<@include>, and one more file with a main menu
+and all the C<@include> is generated.
 
 =head1 OPTIONS
 
@@ -575,9 +574,9 @@ Ordinarily, it's good to keep the sectioning hierarchy 
intact.
 
 =item B<--preamble>=I<STR>
 
-Insert I<STR> as top boilerplate before includes.  If I<STR> is set to
-C<->, read the top boilerplate from the standard input.  The default
-top boilerplate is a minimal beginning for a Texinfo document.
+Insert I<STR> as top boilerplate before menu and includes.  If I<STR> is
+set to C<->, read the top boilerplate from the standard input.  The default top
+boilerplate is a minimal beginning for a Texinfo document.
 
 =item B<--subdir>=I<NAME>
 
@@ -607,7 +606,7 @@ Texinfo home page: L<http://www.gnu.org/software/texinfo/>
 
 =head1 COPYRIGHT
 
-Copyright 2021 Free Software Foundation, Inc.
+Copyright 2012-2022 Free Software Foundation, Inc.
 
 This program is free software; you can redistribute it and/or modify
 it under the terms of the GNU General Public License as published by
diff --git a/man/pod2texi.1 b/man/pod2texi.1
index 737fe822a6..8f76d938e6 100644
--- a/man/pod2texi.1
+++ b/man/pod2texi.1
@@ -133,7 +133,7 @@
 .\" ========================================================================
 .\"
 .IX Title "POD2TEXI 1"
-.TH POD2TEXI 1 "2022-02-07" "perl v5.32.1" "User Contributed Perl 
Documentation"
+.TH POD2TEXI 1 "2022-02-08" "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
@@ -152,9 +152,8 @@ operation.  First, by default, each pod is translated to a 
standalone
 Texinfo manual.
 .PP
 Second, if \f(CW\*(C`\-\-base\-level\*(C'\fR is set higher than 0, each pod is 
translated
-to a file suitable for \f(CW@include\fR, and one more file with all the
-\&\f(CW@include\fRs is generated, intended to be \f(CW@include\fRd in turn 
within a
-hand-written top-level file.
+to a file suitable for \f(CW@include\fR, and one more file with a main menu
+and all the \f(CW@include\fR is generated.
 .SH "OPTIONS"
 .IX Header "OPTIONS"
 .IP "\fB\-\-appendix\-sections\fR" 4
@@ -198,9 +197,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.  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.
+Insert \fI\s-1STR\s0\fR as top boilerplate before menu and 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
@@ -222,7 +221,7 @@ Pod::Simple::Texinfo.  perlpod.  The Texinfo manual.
 Texinfo home page: <http://www.gnu.org/software/texinfo/>
 .SH "COPYRIGHT"
 .IX Header "COPYRIGHT"
-Copyright 2021 Free Software Foundation, Inc.
+Copyright 2012\-2022 Free Software Foundation, Inc.
 .PP
 This program is free software; you can redistribute it and/or modify
 it under the terms of the \s-1GNU\s0 General Public License as published by