branch master updated: Do not output node menus with pod2texi in the default case

[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 8cbdc5188a Do not output node menus with pod2texi in the default case
8cbdc5188a is described below

commit 8cbdc5188ab8b5a90f37b2d996aa9e96d21fb9f6
Author: Patrice Dumas <pertusus@free.fr>
AuthorDate: Sat Aug 13 15:23:39 2022 +0200

    Do not output node menus with pod2texi in the default case
    
    * Pod-Simple-Texinfo/pod2texi.pl (_fix_texinfo_tree)
    (_fix_texinfo_manual): do not output menus in the default
    case, except for the main file created to include the other files,
    for the master menu.  Add a corresponding argument to _fix_texinfo_tree
    and _fix_texinfo_manual.
    (_parsed_manual_tree): excerpt from _fix_texinfo_tree to be able to
    redo a tree with a different option for menus, to be able to create
    menus if $do_master_menu is set but menus are not created.
---
 ChangeLog                      | 15 ++++++-
 Pod-Simple-Texinfo/pod2texi.pl | 89 +++++++++++++++++++++++++++++++++++-------
 doc/pod2texi.texi              | 10 ++++-
 man/pod2texi.1                 | 10 +++--
 4 files changed, 104 insertions(+), 20 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 1f8a5e1839..376e64abb8 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,16 @@
+2022-08-13  Patrice Dumas  <pertusus@free.fr>
+
+       Do not output node menus with pod2texi in the default case
+
+       * Pod-Simple-Texinfo/pod2texi.pl (_fix_texinfo_tree)
+       (_fix_texinfo_manual): do not output menus in the default
+       case, except for the main file created to include the other files,
+       for the master menu.  Add a corresponding argument to _fix_texinfo_tree
+       and _fix_texinfo_manual.
+       (_parsed_manual_tree): excerpt from _fix_texinfo_tree to be able to
+       redo a tree with a different option for menus, to be able to create
+       menus if $do_master_menu is set but menus are not created.
+
 2022-08-13  Gavin Smith  <gavinsmith0123@gmail.com>
 
        * doc/texinfo.tex (\smartitaliccorrection): Incorporate checking
@@ -25,7 +38,7 @@
 2022-08-13  Gavin Smith  <gavinsmith0123@gmail.com>
 
        * doc/texinfo.texi (Optional Arguments):
-       Revert change stating that use of square brackets for optional  
+       Revert change stating that use of square brackets for optional
        arguments is convenient, as this is presupposing users' experiences.
 
 2022-08-13  Gavin Smith  <gavinsmith0123@gmail.com>
diff --git a/Pod-Simple-Texinfo/pod2texi.pl b/Pod-Simple-Texinfo/pod2texi.pl
index 95c40e8d10..7072727f44 100755
--- a/Pod-Simple-Texinfo/pod2texi.pl
+++ b/Pod-Simple-Texinfo/pod2texi.pl
@@ -119,6 +119,7 @@ and all the \@include is generated.");
   $pod2texi_help .= __("    --help                  display this help and 
exit")."\n";
   $pod2texi_help .= __("    --no-fill-section-gaps  do not fill sectioning 
gaps")."\n";
   $pod2texi_help .= __("    --no-section-nodes      use anchors for sections 
instead of nodes")."\n";
+  $pod2texi_help .= __("    --menus                 generate node menus")."\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.
@@ -140,6 +141,7 @@ my $base_level = 0;
 my $unnumbered_sections = 0;
 my $appendix_sections = 0;
 my $headings_as_sections = 0;
+my $generate_node_menus = 0;
 my $output = '-';
 my $top = 'top';
 my $setfilename = undef;
@@ -167,16 +169,17 @@ There is NO WARRANTY, to the extent permitted by 
law.\n"), "2021";
                    $real_command_name);
      }
    },
-  'unnumbered-sections!' => \$unnumbered_sections,
   'appendix-sections!' => \$appendix_sections,
+  'fill-section-gaps!' => \$fill_sectioning_gaps,
   'headings-as-sections!' => \$headings_as_sections,
+  'menus!' => \$generate_node_menus,
   'output|o=s' => \$output,
   'preamble=s' => \$preamble,
   'setfilename=s' => \$setfilename,
   'subdir=s' => \$subdir,
   'top=s' => \$top,
   'section-nodes!' => \$section_nodes,
-  'fill-section-gaps!' => \$fill_sectioning_gaps,
+  'unnumbered-sections!' => \$unnumbered_sections,
   'debug=i' => \$debug,
 );
 
@@ -233,13 +236,14 @@ if ($base_level > 0) {
   }
 }
 
-sub _fix_texinfo_tree($$$$;$)
+# return a parser and parsed tree
+sub _parsed_manual_tree($$$$$)
 {
   my $self = shift;
   my $manual_texi = shift;
   my $section_nodes = shift;
   my $fill_gaps_in_sectioning = shift;
-  my $do_master_menu = shift;
+  my $do_node_menus = shift;
 
   my $texi_parser = Texinfo::Parser::parser();
   my $tree = $texi_parser->parse_texi_text($manual_texi);
@@ -302,28 +306,73 @@ sub _fix_texinfo_tree($$$$;$)
   Texinfo::Structuring::associate_internal_references($registrar, $texi_parser,
                                   $parser_information, $updated_labels, $refs);
   Texinfo::Transformations::complete_tree_nodes_menus($tree)
-    if ($section_nodes);
-  Texinfo::Transformations::regenerate_master_menu($texi_parser, 
$updated_labels)
-     if ($do_master_menu);
+    if ($section_nodes and $do_node_menus);
+  return ($texi_parser, $tree, $updated_labels);
+}
+
+sub _fix_texinfo_tree($$$$;$$)
+{
+  my $self = shift;
+  my $manual_texi = shift;
+  my $section_nodes = shift;
+  my $fill_gaps_in_sectioning = shift;
+  my $do_node_menus = shift;
+  my $do_master_menu = shift;
+
+  my ($texi_parser, $tree, $updated_labels)
+    = _parsed_manual_tree($self, $manual_texi, $section_nodes,
+                          $fill_gaps_in_sectioning,
+                          $do_node_menus);
+  if ($do_master_menu) {
+    if ($do_node_menus) {
+      Texinfo::Transformations::regenerate_master_menu($texi_parser,
+                                                       $updated_labels);
+    } else {
+      # 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_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.
+
+      # setup another tree with menus to do the master menu as menus are
+      # not done for the main tree
+      my ($texi_parser_menus, $tree_menus, $updated_labels_menus)
+       = _parsed_manual_tree($self, $manual_texi, $section_nodes,
+                             $fill_gaps_in_sectioning, 1);
+      my $top_node_menus = $updated_labels_menus->{'Top'};
+      if ($top_node_menus and $top_node_menus->{'extra'}->{'menus'}
+          and scalar(@{$top_node_menus->{'extra'}->{'menus'}})) {
+        my $top_node_menus_menu = $top_node_menus->{'extra'}->{'menus'}->[0];
+        my $top_node = $updated_labels->{'Top'};
+        $top_node_menus_menu->{'parent'} = $top_node;
+        push @{$top_node->{'contents'}}, $top_node_menus_menu;
+        push @{$top_node->{'extra'}->{'menus'}}, $top_node_menus_menu;
+      }
+    }
+  }
   return ($texi_parser, $tree);
 }
 
-sub _fix_texinfo_manual($$$$;$)
+sub _fix_texinfo_manual($$$$;$$)
 {
   my $self = shift;
   my $manual_texi = shift;
   my $section_nodes = shift;
   my $fill_gaps_in_sectioning = shift;
+  my $do_node_menus = shift;
   my $do_master_menu = shift;
-  my ($texi_parser, $tree) = _fix_texinfo_tree($self, $manual_texi, 
$section_nodes,
-                                    $fill_gaps_in_sectioning, $do_master_menu);
+  my ($texi_parser, $tree)
+      = _fix_texinfo_tree($self, $manual_texi, $section_nodes,
+                          $fill_gaps_in_sectioning, $do_node_menus,
+                          $do_master_menu);
   return Texinfo::Convert::Texinfo::convert_to_texinfo($tree);
 }
 
 sub _do_top_node_menu($)
 {
   my $manual_texi = shift;
-  my ($texi_parser, $tree) = _fix_texinfo_tree(undef, $manual_texi, 1, 0, 1);
+  my ($texi_parser, $tree) = _fix_texinfo_tree(undef, $manual_texi, 1, 0, 1, 
1);
   my ($labels, $targets_list, $nodes_list) = 
$texi_parser->labels_information();
   my $top_node_menu = $labels->{'Top'}->{'extra'}->{'menus'}->[0];
   if ($top_node_menu) {
@@ -417,7 +466,8 @@ foreach my $file (@input_files) {
       print DBGFILE $manual_texi;
     }
     $manual_texi = _fix_texinfo_manual($new, $manual_texi, $section_nodes,
-                                             $fill_sectioning_gaps);
+                                       $fill_sectioning_gaps,
+                                       $generate_node_menus);
     $full_manual .= $manual_texi if ($section_nodes);
   }
   print $fh $manual_texi;
@@ -578,8 +628,13 @@ above the C<--base-level> value.  Therefore, to make each 
Pod file a
 chapter in a large manual, you should use C<section> as the base level.
 
 For an example of making Texinfo out of the Perl documentation itself,
-see C<contrib/perldoc-all> in the Texinfo source distribution, with
-output available at L<http://www.gnu.org/software/perl/manual>.
+see C<contrib/perldoc-all> in the Texinfo source distribution.
+
+=begin comment
+
+with output available at L<http://www.gnu.org/software/perl/manual>.
+
+=end comment
 
 =item B<--debug>=I<NUM>
 
@@ -597,6 +652,12 @@ numbered command.
 
 Display help and exit.
 
+=item B<--menus>
+
+Output node menus. If there is a main manual, its Top node menu
+is always output, since a master menu is generated. Other nodes
+menus are not output in the default case.
+
 =item B<--output>=I<NAME>
 
 Name for the first manual, or the main manual if there is a main manual.
diff --git a/doc/pod2texi.texi b/doc/pod2texi.texi
index 178de3040b..8cfa0782e2 100644
--- a/doc/pod2texi.texi
+++ b/doc/pod2texi.texi
@@ -51,8 +51,7 @@ above the @code{--base-level} value.  Therefore, to make each 
Pod file a
 chapter in a large manual, you should use @code{section} as the base level.
 
 For an example of making Texinfo out of the Perl documentation itself,
-see @code{contrib/perldoc-all} in the Texinfo source distribution, with
-output available at @url{http://www.gnu.org/software/perl/manual}.
+see @code{contrib/perldoc-all} in the Texinfo source distribution.
 
 @item @strong{@asis{}-@asis{}-@asis{}debug}=@emph{NUM}
 @anchor{pod2texi @strong{@asis{}-@asis{}-@asis{}debug}=@emph{NUM}}
@@ -73,6 +72,13 @@ numbered command.
 
 Display help and exit.
 
+@item @strong{@asis{}-@asis{}-@asis{}menus}
+@anchor{pod2texi @strong{@asis{}-@asis{}-@asis{}menus}}
+
+Output node menus. If there is a main manual, its Top node menu
+is always output, since a master menu is generated. Other nodes
+menus are not output in the default case.
+
 @item @strong{@asis{}-@asis{}-@asis{}output}=@emph{NAME}
 @anchor{pod2texi @strong{@asis{}-@asis{}-@asis{}output}=@emph{NAME}}
 
diff --git a/man/pod2texi.1 b/man/pod2texi.1
index 41c92650e7..2801ebb50c 100644
--- a/man/pod2texi.1
+++ b/man/pod2texi.1
@@ -133,7 +133,7 @@
 .\" ========================================================================
 .\"
 .IX Title "POD2TEXI 1"
-.TH POD2TEXI 1 "2022-07-17" "perl v5.34.0" "User Contributed Perl 
Documentation"
+.TH POD2TEXI 1 "2022-08-13" "perl v5.34.0" "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
@@ -176,8 +176,7 @@ above the \f(CW\*(C`\-\-base\-level\*(C'\fR value.  
Therefore, to make each Pod
 chapter in a large manual, you should use \f(CW\*(C`section\*(C'\fR as the 
base level.
 .Sp
 For an example of making Texinfo out of the Perl documentation itself,
-see \f(CW\*(C`contrib/perldoc\-all\*(C'\fR in the Texinfo source distribution, 
with
-output available at <http://www.gnu.org/software/perl/manual>.
+see \f(CW\*(C`contrib/perldoc\-all\*(C'\fR in the Texinfo source distribution.
 .IP "\fB\-\-debug\fR=\fI\s-1NUM\s0\fR" 4
 .IX Item "--debug=NUM"
 Set debugging level to \fI\s-1NUM\s0\fR.
@@ -191,6 +190,11 @@ numbered command.
 .IP "\fB\-\-help\fR" 4
 .IX Item "--help"
 Display help and exit.
+.IP "\fB\-\-menus\fR" 4
+.IX Item "--menus"
+Output node menus. If there is a main manual, its Top node menu
+is always output, since a master menu is generated. Other nodes
+menus are not output in the default case.
 .IP "\fB\-\-output\fR=\fI\s-1NAME\s0\fR" 4
 .IX Item "--output=NAME"
 Name for the first manual, or the main manual if there is a main manual.