branch master updated: Pod-Simple-Texinfo information updates, 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 90dd98111d Pod-Simple-Texinfo information updates, reindent
90dd98111d is described below

commit 90dd98111d0c369409b0b02bc69b9430055fbb33
Author: Patrice Dumas <pertusus@free.fr>
AuthorDate: Sat Nov 19 01:16:38 2022 +0100

    Pod-Simple-Texinfo information updates, reindent
    
    Update README, used only with Makefile.PL.  Change in comments
    and reindent Pod-Simple-Texinfo/lib/Pod/Simple/Texinfo.pm.
---
 Pod-Simple-Texinfo/README                    | 16 +++++-
 Pod-Simple-Texinfo/lib/Pod/Simple/Texinfo.pm | 77 +++++++++++++++++++---------
 Pod-Simple-Texinfo/pod2texi.pl               |  1 +
 3 files changed, 69 insertions(+), 25 deletions(-)

diff --git a/Pod-Simple-Texinfo/README b/Pod-Simple-Texinfo/README
index cac61e5bd5..7f04e4341e 100644
--- a/Pod-Simple-Texinfo/README
+++ b/Pod-Simple-Texinfo/README
@@ -18,9 +18,23 @@ This module requires these other modules and libraries:
 
 Pod::Simple::PullParser, Texinfo::Parser.  
 
+DISTRIBUTION SETUP
+
+This module is usually distributed as part of GNU Texinfo, using Autoconf
+and Automake for the build system.  Alternatively, it is possible to
+distribute the module using Makefile.PL as described here.
+
+The pod2texi script is usually set up using the Autoconf and Automake
+built environment from pod2texi.pl.  When using Makefile.PL, the
+pod2texi.pl file can be copied instead.  In that case, the Texinfo::Parser
+modules will not be searched for as in the GNU Texinfo usual case, only
+in the perl paths, as in other perl modules.
+
+   cp pod2texi.pl pod2texi
+
 COPYRIGHT AND LICENCE
 
-Copyright (C) 2011, 2012 Free Software Foundation, Inc.
+Copyright (C) 2011-2022 Free Software Foundation, Inc.
 
 This library 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/Pod-Simple-Texinfo/lib/Pod/Simple/Texinfo.pm 
b/Pod-Simple-Texinfo/lib/Pod/Simple/Texinfo.pm
index 3130357c06..9adcf1139b 100644
--- a/Pod-Simple-Texinfo/lib/Pod/Simple/Texinfo.pm
+++ b/Pod-Simple-Texinfo/lib/Pod/Simple/Texinfo.pm
@@ -1,20 +1,20 @@
 # Texinfo.pm: format Pod as Texinfo.
 #
 # 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
 # the Free Software Foundation; either version 3 of the License,
 # or (at your option) any later version.
-# 
+#
 # This program is distributed in the hope that it will be useful,
 # but WITHOUT ANY WARRANTY; without even the implied warranty of
 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 # GNU General Public License for more details.
-# 
+#
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
-# 
+#
 # Original author: Patrice Dumas <pertusus@free.fr>
 # Parts from L<Pod::Simple::HTML>.
 #
@@ -26,6 +26,9 @@
 # We prefer a Pod::Simple::PullParser subclassing to be able to use
 # get_short_title().
 #
+# bare_output flag described in Pod::Simple::Subclassing is taken into
+# account.
+#
 #
 # TODO: it could be relevant to convert L<...> referring to external modules to
 # urls to Metacpan, or similar websites, using @url instead of @ref, which
@@ -61,8 +64,6 @@ use vars qw(
 @ISA = ('Pod::Simple::PullParser');
 $VERSION = '0.01';
 
-#use UNIVERSAL ();
-
 # 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 }
@@ -127,10 +128,11 @@ sub new
   $new->texinfo_man_url_prefix($man_url_prefix);
   $new->texinfo_sectioning_style($sectioning_style);
   $new->texinfo_add_upper_sectioning_command(1);
-  #$new->{'texinfo_nodes'} = {};
   return $new;
 }
 
+# This needs to be defined so that users can call parse_file and other
+# similar Pod::Simple/Pod::Simple::PullParser methods.
 sub run
 {
   my $self = shift;
@@ -616,13 +618,14 @@ sub _texinfo_handle_element_start($$$)
           # it is unlikely that there is a comma because of _url_escape
           # but to be sure there is still a call to _protect_comma.
           $url_arg = _protect_comma(_protect_text(
-                                       $self->texinfo_man_url_prefix()
-                                          ."$section/"._url_escape($page), 0, 
1));
+                                     $self->texinfo_man_url_prefix()
+                                        ."$section/"._url_escape($page), 0, 
1));
         } else {
           $url_arg = '';
         }
         $replacement_arg = _protect_text($replacement_arg);
-        _output($fh, $self->{'texinfo_accumulated'}, "\@url{$url_arg,, 
$replacement_arg}");
+        _output($fh, $self->{'texinfo_accumulated'},
+                                         "\@url{$url_arg,, $replacement_arg}");
       } elsif ($linktype eq 'url') {
         # NOTE: the .'' is here to force the $token->attr to be a real
         # string and not an object.
@@ -636,9 +639,9 @@ sub _texinfo_handle_element_start($$$)
         # on the cases, to 'name', or '"section" in name' (based on 
perlpodspec)
         # which is not practical for conversion to Texinfo as section and
         # name should be available separately, both converted to Texinfo.
-        # It is possible to get the equivalent parsing in term of pod strings 
with
-        # parselink(), which returns the same as the pullparser argument as
-        # text, but also returns separately the section and name.
+        # It is possible to get the equivalent parsing in term of pod strings
+        # with parselink(), which returns the same as the pullparser argument
+        # as text, but also returns separately the section and name.
         # However, it is not possible to simply convert the section or
         # name string with the Texinfo pullparser parser, as a full pod text is
         # expected, starting whith a =head* while we would want to parse a
@@ -656,6 +659,7 @@ sub _texinfo_handle_element_start($$$)
           $self->_convert_pod_simple_tree($section);
           ($section_texi, $section_out)
             = _end_context($self->{'texinfo_accumulated'});
+
           # coerce to string
           $section_text = $section.'';
         }
@@ -666,6 +670,7 @@ sub _texinfo_handle_element_start($$$)
           $self->_convert_pod_simple_tree($manual);
           ($manual_texi, $manual_out)
             = _end_context($self->{'texinfo_accumulated'});
+
           # coerce to string
           $manual_text = $manual.'';
         }
@@ -692,6 +697,7 @@ sub _texinfo_handle_element_start($$$)
             # use plain text string without formatting to match with what 
should
             # be given through texinfo_internal_pod_manuals().
             if ($self->{'texinfo_internal_pod_manuals_hash'}->{$manual_text}) {
+              # should always be the first section in pods
               $section_texi = 'NAME';
               # use the manual name as texinfo section name, otherwise
               # it will be the section associated with the node, which is
@@ -749,13 +755,15 @@ sub _texinfo_handle_element_start($$$)
     _output($fh, $self->{'texinfo_accumulated'}, 
"\@$tag_commands{$tagname}\{");
     if ($Texinfo::Commands::brace_code_commands{$tag_commands{$tagname}}) {
       if (@{$self->{'texinfo_stack'}} and ref($self->{'texinfo_stack'}->[-1]) 
eq ''
-          and 
defined($self->{'texinfo_raw_format_commands'}->{$self->{'texinfo_stack'}->[-1]}))
 {
+          and defined($self->{'texinfo_raw_format_commands'}
+                                        ->{$self->{'texinfo_stack'}->[-1]})) {
         cluck "in $self->{'texinfo_stack'}->[-1]: $tagname 
$tag_commands{$tagname}";
       }
       push @{$self->{'texinfo_stack'}}, 'in_code';
     }
   } elsif ($environment_commands{$tagname}) {
-    _output($fh, $self->{'texinfo_accumulated'}, 
"\@$environment_commands{$tagname}\n");
+    _output($fh, $self->{'texinfo_accumulated'},
+                                         
"\@$environment_commands{$tagname}\n");
     if ($tagname eq 'Verbatim') {
       push @{$self->{'texinfo_stack'}}, 'verbatim';
     }
@@ -786,26 +794,31 @@ sub _texinfo_handle_text($$)
   }
   my $result_text;
   if (@{$self->{'texinfo_stack'}} and ref($self->{'texinfo_stack'}->[-1]) eq ''
-      and 
((defined($self->{'texinfo_raw_format_commands'}->{$self->{'texinfo_stack'}->[-1]})
-            and 
!$self->{'texinfo_raw_format_commands'}->{$self->{'texinfo_stack'}->[-1]})
+      and ((defined($self->{'texinfo_raw_format_commands'}
+                                           ->{$self->{'texinfo_stack'}->[-1]})
+            and !$self->{'texinfo_raw_format_commands'}
+                                           ->{$self->{'texinfo_stack'}->[-1]})
            or ($self->{'texinfo_stack'}->[-1] eq 'verbatim'))) {
     $result_text = $text;
   } else {
     if (@{$self->{'texinfo_stack'}} and ref($self->{'texinfo_stack'}->[-1]) eq 
''
         and 
($self->{'texinfo_raw_format_commands'}->{$self->{'texinfo_stack'}->[-1]})) {
       $result_text = _protect_text($text, 0, 1);
-      $result_text =~ s/^(\s*)#(\s*(line)? (\d+)(( 
"([^"]+)")(\s+\d+)*)?\s*)$/$1\@hashchar{}$2/mg;
+      $result_text
+  =~ s/^(\s*)#(\s*(line)? (\d+)(( 
"([^"]+)")(\s+\d+)*)?\s*)$/$1\@hashchar{}$2/mg;
     } else {
       $result_text = _protect_text($text, 0,
-                (@{$self->{'texinfo_stack'}} and 
$self->{'texinfo_stack'}->[-1] eq 'in_code'));
+                           (@{$self->{'texinfo_stack'}}
+                            and $self->{'texinfo_stack'}->[-1] eq 'in_code'));
     }
   }
   #print STDERR "T: !$text!->!$result_text!\n";
   _output($fh, $self->{'texinfo_accumulated'}, $result_text);
 }
 
-# tp remain compatible with PullParser, the $attr_hash should not be
-# used, and everything passed through the stack.
+# to remain compatible with PullParser, the $attr_hash should not be
+# used, information should be gathered at the start of the tag,
+# and passed through the stack $self->{'texinfo_stack'}.
 sub _texinfo_handle_element_end($$$)
 {
   my $self = shift;
@@ -1048,12 +1061,28 @@ 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
-Texinfo in utf8 in the caller.
+Texinfo in UTF-8 in the caller.
 
 =head1 METHODS
 
 =over
 
+=item new
+
+Initialize a parser object.
+
+=item run
+
+Run the parser.  In general, you should not use this method directly,
+but instead use C<parse_file> or similar methods from L<Pod::Simple>.
+
+=back
+
+You can set these attributes on the parser object before you call
+C<parse_file> (or a similar method) on it:
+
+=over
+
 =item texinfo_add_upper_sectioning_command
 
 If set (the default case), a sectioning command is added at the beginning
@@ -1079,7 +1108,7 @@ Corresponds to L<texinfo_sectioning_base_level> set to 
anything else than 0.
 Sectioning style for the main command appearing at the beginning of the output
 file if L<texinfo_sectioning_base_level> is anything else than 0.  Unset in the
 default case.  If unset, use L<texinfo_sectioning_style>, except for style
-C<heading>, for which the C<number> style is used in the default case.
+C<heading>, for which the C<numbered> style is used in the default case.
 
 =item texinfo_man_url_prefix
 
@@ -1121,7 +1150,7 @@ L<Pod::Simple>. L<Pod::Simple::PullParser>. The Texinfo 
manual.
 
 =head1 COPYRIGHT AND LICENSE
 
-Copyright (C) 2011, 2012 Free Software Foundation, Inc.
+Copyright (C) 2011-2022 Free Software Foundation, Inc.
 
 This library 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/Pod-Simple-Texinfo/pod2texi.pl b/Pod-Simple-Texinfo/pod2texi.pl
index 057ebe5062..04936327ff 100755
--- a/Pod-Simple-Texinfo/pod2texi.pl
+++ b/Pod-Simple-Texinfo/pod2texi.pl
@@ -338,6 +338,7 @@ sub _fix_texinfo_tree($$$$;$$)
       # note that that situation cannot happen with the code as it
       # is now.  When _fix_texinfo_tree is called from _do_top_node_menu
       # both $do_master_menu and $do_node_menus are set.
+      # _fix_texinfo_tree can also be called from _fix_texinfo_manual, but
       # _fix_texinfo_manual is never called with a $do_master_menu argument,
       # so when _fix_texinfo_tree is called from _fix_texinfo_manual,
       # $do_master_menu cannot be set.