branch master updated: Texinfo/Transformations.pm in tp_api. Changes doc, spaces, comments

[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 27cac4531c Texinfo/Transformations.pm in tp_api. Changes doc, spaces, 
comments
27cac4531c is described below

commit 27cac4531c97691712a137454e55e42c8e6527bc
Author: Patrice Dumas <pertusus@free.fr>
AuthorDate: Sat Feb 5 16:31:06 2022 +0100

    Texinfo/Transformations.pm in tp_api. Changes doc, spaces, comments
---
 doc/customization_api.texi    |  30 ++++-----
 doc/tp_api/Makefile.am        |   2 +-
 tp/Texinfo/Config.pm          |  14 +++--
 tp/Texinfo/Convert/HTML.pm    |  49 +++++++--------
 tp/Texinfo/Convert/LaTeX.pm   |  14 ++++-
 tp/Texinfo/ParserNonXS.pm     |   4 +-
 tp/Texinfo/Transformations.pm | 143 ++++++++++++++++++++++--------------------
 7 files changed, 136 insertions(+), 120 deletions(-)

diff --git a/doc/customization_api.texi b/doc/customization_api.texi
index 712270a77e..f33e9a0a5d 100644
--- a/doc/customization_api.texi
+++ b/doc/customization_api.texi
@@ -44,6 +44,9 @@ Texts.  A copy of the license is included in the section 
entitled
 @node Top
 @top @c @command{texi2any} Output Customization
 
+@node Overview
+@chapter Overview
+
 @cartouche
 @quotation Warning
 All of this information, with the exception of command-line options
@@ -58,20 +61,19 @@ not a promise.
 @end quotation
 @end cartouche
 
-This manual describes how to customize aspects of the
-@command{texi2any} HTML output.  Although some of the features here
-can technically be used with other output formats, it's not especially
-useful to do so, so we'll write the documentation as if HTML were the
-target format.  Most of the customizations are only available for
-HTML.
+This manual describes how to customize the @command{texi2any} HTML output.
+Although some of the features here can technically be used with other output
+formats, it's not especially useful to do so, so we'll write the documentation
+as if HTML were the target format.  Most of the customizations are only
+available for HTML.
 
 The conversion of Texinfo to HTML is done in two steps.  After reading
 command-line options and init files, input Texinfo code is parsed
 into a Texinfo Perl tree and information is gathered on the document
-structure.  This first step can only be customized to some extent, by setting
-customization variables.  The Texinfo Perl tree describes a Texinfo document 
in a
-structured way which makes it easy to go through the tree and format
-@@-commands and other containers.
+structure.  This first step can only be customized to a certain extent, by
+using the command-line options and setting customization variables.  The
+Texinfo Perl tree describes a Texinfo document in a structured way which makes
+it easy to go through the tree and format @@-commands and other containers.
 
 The second step is the @dfn{conversion} step done in a converter.  The HTML
 converter takes a Texinfo Perl tree as input and transforms it to HTML@.  The
@@ -174,7 +176,7 @@ distribution, and can serve as a good model for writing 
your own.  Another
 example is the @code{Texinfo::Convert::HTML} module which implements
 almost all the Texinfo HTML function described in this manual for the 
conversion
 to HTML@footnote{The @code{Texinfo::Convert::HTML} module also implements the
-HTML converter calling user defined functions during document conversion.}.
+HTML converter which go through the tree and call user defined functions.}.
 The Licenses conditions of the diverse files used as example should be taken
 into account when reusing code.
 
@@ -194,7 +196,7 @@ It is possible to start init files with:
 @example
 package Texinfo::Config;
 @end example
-It is not mandatory, but it may help some debugging tools determine in which
+It is not required, but it may help some debugging tools determine in which
 namespace the code is run.
 
 In the @code{Texinfo::Config} namespace, the functions names beginning with
@@ -214,8 +216,8 @@ functions to be called from the converter. @xref{User 
Defined Functions}.
 The basic operations on customization variables are to set and
 retrieve their values.  New variables can also be added.
 
-Customization variables also valid out of the HTML
-converter, in the main program, are handled differently if they are strings or
+The customization variables also valid in the main program out of the HTML
+converter are handled differently if they are strings or
 arrays.  The customization variables only relevant for the conversion phase
 are always set like string variables, in particular array or hash references.
 
diff --git a/doc/tp_api/Makefile.am b/doc/tp_api/Makefile.am
index 27efbd3b83..dbb8a53876 100644
--- a/doc/tp_api/Makefile.am
+++ b/doc/tp_api/Makefile.am
@@ -37,7 +37,6 @@ BUILT_SOURCES = tp_api.texi
 #DISTCLEANFILES = tp_api.info
 
 # FIXME add?
-# $(top_srcdir)/tp/Texinfo/Transformations.pm
 tp_api_dependencies = \
   $(top_srcdir)/tp/Texinfo/Common.pm \
   $(top_srcdir)/tp/Texinfo/Encoding.pm \
@@ -45,6 +44,7 @@ tp_api_dependencies = \
   $(top_srcdir)/tp/Texinfo/Structuring.pm \
   $(top_srcdir)/tp/Texinfo/Report.pm \
   $(top_srcdir)/tp/Texinfo/Translations.pm \
+  $(top_srcdir)/tp/Texinfo/Transformations.pm \
   $(top_srcdir)/tp/Texinfo/Convert/Texinfo.pm \
   $(top_srcdir)/tp/Texinfo/Convert/Utils.pm \
   $(top_srcdir)/tp/Texinfo/Convert/Unicode.pm \
diff --git a/tp/Texinfo/Config.pm b/tp/Texinfo/Config.pm
index fb31cf4a96..97b1a4c89e 100644
--- a/tp/Texinfo/Config.pm
+++ b/tp/Texinfo/Config.pm
@@ -17,12 +17,14 @@
 # 
 # Original author: Patrice Dumas <pertusus@free.fr>
 #
-# functions that should not be called by user init files codes are
-# prefixed by GNUT_ while functions that can be called by user init
-# files codes are prefixed by texinfo_.
-# 
-# TODO document all texinfo_ in a pod section, but wait for stabilization.
-# Document that GNUT_, _GNUT_ and texinfo_ are reserved prefixes.
+# functions that should not be called by user init files codes, but
+# are called by the main program are prefixed by GNUT_ while functions that can
+# be called by user init files codes are prefixed by texinfo_.
+# Functions prefixed by _GNUT_ are private.
+#
+# This package is documented in the customization_api Texinfo manual.  The
+# public functions defined here cannot and should not be documented separately
+# from the texinfo main program and HTML modules documentation.
 
 package Texinfo::Config;
 
diff --git a/tp/Texinfo/Convert/HTML.pm b/tp/Texinfo/Convert/HTML.pm
index 7e4bf148f3..e865b401fc 100644
--- a/tp/Texinfo/Convert/HTML.pm
+++ b/tp/Texinfo/Convert/HTML.pm
@@ -16,31 +16,16 @@
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 #
 #
-# The following categories of formatting functions can be replaced
-# by the user.  The associated hash with defaults is also shown:
-#  * command tree element formatting functions defaults in
-#    %default_commands_conversion
-#  * command tree element opening functions defaults in
-#    %default_commands_open
-#  * type tree element (element without @-command) formatting
-#    functions, defaults in %default_types_conversion
-#  * type tree element opening functions defaults in
-#    %default_types_open
-#  * other formatting functions, defaults in
-#    %default_formatting_references
+# The documentation of the HTML customization API which is both
+# used and implemented in the current file is in the customization_api
+# Texinfo manual.
 #
-# The functions used in the default case for all the functions
-# that may be replaced should not have side effects, such that
-# users can overrides them independently without risking unwanted
-# results.  Also in formatting functions, the state of the
-# converter should only be accessed through functions, such
-# as in_math, in_preformatted, preformatted_classes_stack and
-# similar functions.
-#
-# In most formatting functions, the case where $self->in_string() is
-# true should be handled explicitely and the simplest formatting should be
-# done in that case, without any HTML element such that the result
-# can be in an attribute or in a comment.
+# Formatting and conversion functions that can be replaced by user-defined
+# functions should only use documented functions to pass information
+# and formatted content, such that users can overrides them independently
+# without risking unwanted results.  Also in formatting functions, the state of
+# the converter should only be accessed through functions, such as in_math,
+# in_preformatted, preformatted_classes_stack and similar functions.
 #
 # Original author: Patrice Dumas <pertusus@free.fr>
 
@@ -75,7 +60,10 @@ use Texinfo::Structuring;
 use Texinfo::Convert::Converter;
 
 # used to convert Texinfo to LaTeX math in @math and @displaymath
-# for further conversion by softwares that only convert LaTeX
+# for further conversion by softwares that only convert LaTeX.
+# NOTE mathjax does not implement some constructs output by the
+# Texinfo::Convert::LaTeX converter.  Examples in 2022:
+# \mathord{\text{}} \textsl{} \copyright{} \mathsterling{}
 use Texinfo::Convert::LaTeX;
 
 
@@ -423,7 +411,7 @@ sub html_convert_css_string_for_list_mark($$;$)
   return $result;
 }
 
-# API to access converter state for customization code
+# API to access converter state for conversion
 
 sub in_math($)
 {
@@ -615,7 +603,7 @@ sub _get_target($$)
   return $target;
 }
 
-# API for elements directions formatting
+# API for links and elements directions formatting
 
 # This returns the id specific of the $COMMAND tree element
 sub command_id($$)
@@ -1272,7 +1260,7 @@ sub from_element_direction($$$;$$)
   }
 }
 
-# API for misc useful functions for customization files
+# API for misc conversion and formatting functions
 
 # it is considered 'top' only if element corresponds to @top or
 # element is a node
@@ -10171,6 +10159,11 @@ sub _set_variables_texi2html()
 
 1;
 
+# The documentation of the customization API is in the customization_api
+# Texinfo manual.  POD format is not suitable for such a documentation, because
+# of the module documentation style, the language limitations, and also because
+# the customization API involves multiple modules as well as the main program.
+
 __END__
 # Automatically generated from maintain/template.pod
 
diff --git a/tp/Texinfo/Convert/LaTeX.pm b/tp/Texinfo/Convert/LaTeX.pm
index 8dae6bf9c9..9e87f94321 100644
--- a/tp/Texinfo/Convert/LaTeX.pm
+++ b/tp/Texinfo/Convert/LaTeX.pm
@@ -63,14 +63,24 @@
 #
 # @dmn is not implemented
 #
+# LaTeX seems to always break at -, and never at _.  If @allowcodebreaks
+# is true \_ should be set to be a possible break point.  Seems that it
+# may be done with something like:
+#
+#   \let\underscore\_
+#   \newcommand{\myunderscore}{\renewcommand{\_}{\underscore\hspace{0pt}}}
+#
+# If @allowcodebreaks is false, - should be set such that it is not a
+# breaking point anymore.  Maybe one way to do it:
+#
+#   \mbox{-}\nobreak\hspace{0pt}
+#
 #
 # RELEVANT BUT NOT DECISIVE
 #
 # breaking in urls is not implemented, maybe there is some support already in
 # hyperref.  @urefbreakstyle, @/
 #
-# Breaking in _ or - in @code is not implemented, as well as @allowcodebreaks.
-#
 # Translations
 #
 # Need thinking.  In texi2any?  In LaTeX?  If in
diff --git a/tp/Texinfo/ParserNonXS.pm b/tp/Texinfo/ParserNonXS.pm
index e67d559e28..3e729a332b 100644
--- a/tp/Texinfo/ParserNonXS.pm
+++ b/tp/Texinfo/ParserNonXS.pm
@@ -6075,7 +6075,7 @@ It overrides the document C<@documentlanguage> 
information, if present.
 
 =item registrar
 
-Texinfo::Report object reused by the parser to register errors.
+L<Texinfo::Report> object reused by the parser to register errors.
 
 =item values
 
@@ -6215,7 +6215,7 @@ described in 
L<errors|Texinfo::Report/($error_warnings_list, $error_count) = err
 
 =item $registrar = registered_errors($parser)
 
-I<$registrar> is a C<Texinfo::Report> object in which the errors
+I<$registrar> is a L<Texinfo::Report> object in which the errors
 and warnings encountered while parsing are registered.  If a I<registrar>
 passed to the parser initialization options, it is reused, otherwise
 a new one is created.
diff --git a/tp/Texinfo/Transformations.pm b/tp/Texinfo/Transformations.pm
index d6569ff448..3166b88f08 100644
--- a/tp/Texinfo/Transformations.pm
+++ b/tp/Texinfo/Transformations.pm
@@ -115,7 +115,7 @@ sub fill_gaps_in_sectioning($)
             
$Texinfo::Common::level_to_structuring_command{'unnumbered'}->[$current_section_level],
             'parent' => $root,
           };
-          $new_section->{'contents'} = [{'type' => 'empty_line', 
+          $new_section->{'contents'} = [{'type' => 'empty_line',
                                          'text' => "\n",
                                          'parent' => $new_section}];
           $new_section->{'args'} = [{'type' => 'line_arg',
@@ -148,17 +148,17 @@ sub fill_gaps_in_sectioning($)
   return (\@contents, \@added_sections);
 }
 
-# This converts a reference @-command to simple text using one of the 
-# arguments.  This is used to remove reference @-command from 
+# This converts a reference @-command to simple text using one of the
+# arguments.  This is used to remove reference @-command from
 # constructed node names trees, as node names cannot contain
-# reference @-command while there could be some in the tree used in 
+# reference @-command while there could be some in the tree used in
 # input for the node name tree.
 sub _reference_to_arg($$$)
 {
   my $type = shift;
   my $current = shift;
 
-  if ($current->{'cmdname'} and 
+  if ($current->{'cmdname'} and
       $Texinfo::Common::ref_commands{$current->{'cmdname'}}
       and $current->{'args'}) {
     my @args_try_order;
@@ -203,12 +203,12 @@ sub _new_node($$$$)
   my $labels = shift;
 
   $node_tree = Texinfo::Common::protect_comma_in_tree($node_tree);
-  $node_tree->{'contents'} 
+  $node_tree->{'contents'}
      = Texinfo::Common::protect_first_parenthesis($node_tree->{'contents'});
   $node_tree = reference_to_arg_in_tree($node_tree);
 
   my $empty_node = 0;
-  if (!$node_tree->{'contents'} 
+  if (!$node_tree->{'contents'}
       or !scalar(@{$node_tree->{'contents'}})) {
     $node_tree->{'contents'} = [{'text' => ''}];
     $empty_node = 1;
@@ -219,14 +219,14 @@ sub _new_node($$$$)
             or $node_tree->{'contents'}->[-1]->{'cmdname'} eq 'comment'))
       or (defined($node_tree->{'contents'}->[-1]->{'text'})
           and $node_tree->{'contents'}->[-1]->{'text'} =~ /\n/)) {
-    push @{$node_tree->{'contents'}}, 
+    push @{$node_tree->{'contents'}},
            {'type' => 'spaces_at_end', 'text' => "\n"};
   }
 
   my $appended_number = 0 +$empty_node;
   my ($node, $parsed_node);
 
-  while (!defined($node) 
+  while (!defined($node)
          or ($labels
             and $labels->{$parsed_node->{'normalized'}})) {
     $node = {'cmdname' => 'node', 'args' => [{}]};
@@ -296,7 +296,7 @@ sub _reassociate_to_node($$$$)
     }
     push @{$new_node->{'extra'}->{'menus'}}, $current;
   } elsif ($current->{'extra'} and $current->{'extra'}->{'index_entry'}) {
-    if ($previous_node 
+    if ($previous_node
         and (!$current->{'extra'}->{'index_entry'}->{'node'}
              or $current->{'extra'}->{'index_entry'}->{'node'} ne 
$previous_node)) {
       print STDERR "Bug: index entry $current (".
@@ -333,13 +333,13 @@ sub insert_nodes_for_sectioning_commands($$$$)
     if ($content->{'cmdname'} and $content->{'cmdname'} ne 'node'
         and $content->{'cmdname'} ne 'part'
         and $Texinfo::Common::root_commands{$content->{'cmdname'}}
-        and not ($content->{'extra'} 
+        and not ($content->{'extra'}
                  and $content->{'extra'}->{'associated_node'})) {
       my $new_node_tree;
       if ($content->{'cmdname'} eq 'top') {
         $new_node_tree = {'contents' => [{'text' => 'Top'}]};
       } else {
-        $new_node_tree = Texinfo::Common::copy_tree({'contents' 
+        $new_node_tree = Texinfo::Common::copy_tree({'contents'
           => $content->{'args'}->[0]->{'contents'}});
       }
       my $new_node = _new_node($new_node_tree, $nodes_list,
@@ -356,8 +356,8 @@ sub insert_nodes_for_sectioning_commands($$$$)
       }
     }
     # check normalized to avoid erroneous nodes, such as duplicates
-    $previous_node = $content 
-      if ($content->{'cmdname'} 
+    $previous_node = $content
+      if ($content->{'cmdname'}
           and $content->{'cmdname'} eq 'node'
           and $content->{'extra'}->{'normalized'});
     push @contents, $content;
@@ -397,7 +397,7 @@ sub complete_node_menu($;$)
             my $entry_node = $entry->{'extra'}->{'menu_entry_node'};
             if (! $entry_node->{'manual_content'}
                 and defined($entry_node->{'normalized'})) {
-              $existing_entries{$entry_node->{'normalized'}} 
+              $existing_entries{$entry_node->{'normalized'}}
                 = [$menu, $entry];
             }
           }
@@ -410,7 +410,7 @@ sub complete_node_menu($;$)
     foreach my $node_entry (@node_childs) {
       if ($existing_entries{$node_entry->{'extra'}->{'normalized'}}) {
         my $entry;
-        ($current_menu, $entry) 
+        ($current_menu, $entry)
          = @{$existing_entries{$node_entry->{'extra'}->{'normalized'}}};
         if (@pending) {
           my $index;
@@ -460,7 +460,7 @@ sub _get_non_automatic_nodes_with_sections($)
   foreach my $content (@{$root->{'contents'}}) {
     if ($content->{'cmdname'} and $content->{'cmdname'} eq 'node'
         and (scalar(@{$content->{'extra'}->{'nodes_manuals'}}) == 1)
-        and $content->{'extra'} 
+        and $content->{'extra'}
         and $content->{'extra'}->{'associated_section'}) {
       push @non_automatic_nodes, $content;
     }
@@ -626,7 +626,7 @@ sub regenerate_master_menu($$)
       if ($entry->{'cmdname'} and $entry->{'cmdname'} eq 'detailmenu') {
         # replace existing detailmenu by the master menu
         $new_master_menu->{'parent'} = $menu;
-        splice (@{$menu->{'contents'}}, $detailmenu_index, 1, 
+        splice (@{$menu->{'contents'}}, $detailmenu_index, 1,
                 $new_master_menu);
         return 1;
       }
@@ -805,7 +805,7 @@ sub _protect_hashchar_at_line_beginning($$$)
         if ($parent->{'cmdname'} and $parent->{'line_nr'}) {
           if ($registrar) {
             $registrar->line_warn($configuration_information, sprintf(__(
-                "could not protect hash character in \@%s"), 
+                "could not protect hash character in \@%s"),
                            $parent->{'cmdname'}), $parent->{'line_nr'});
           }
           last;
@@ -845,106 +845,115 @@ __END__
 
 Texinfo::Transformations - transformations of Texinfo::Parser.pm tree
 
-=head1 SYNOPSIS
+=head1 DISCLAIMER
+
+The Texinfo Perl module main purpose is to be used in C<texi2any> to convert
+Texinfo to other formats.  There no promise of API stability.
 
-  use Texinfo:Transformations;
-  
-  
 =head1 DESCRIPTION
 
 Includes miscellaneous methods C<set_menus_to_simple_menu> and
 C<menu_to_simple_menu> to change the menu texinfo tree, as well
-as C<insert_nodes_for_sectioning_commands> that adds nodes for 
+as C<insert_nodes_for_sectioning_commands> that adds nodes for
 sectioning commands without nodes and C<complete_tree_nodes_menus>
-and C<complete_tree_nodes_missing_menu> that completes the 
+and C<complete_tree_nodes_missing_menu> that completes the
 node menus based on the sectioning tree.
 
-
-
 =head1 METHODS
 
 No method is exported in the default case.
 
-Most of those function references takes a Texinfo::Parser object
-as argument, see L<Texinfo::Parser>.
-
 =over
 
+=item complete_tree_nodes_menus ($tree, $add_section_names_in_entries)
+
+Add menu entries or whole menus for nodes associated with sections,
+based on the sectioning tree.  If the optional
+C<$add_section_names_in_entries> argument is set, a menu entry
+name is added using the section name.  This function should be
+called after L<sectioning_structure|Texinfo::Structuring/$sections_root, 
$sections_list = sectioning_structure($registrar, $configuration_information, 
$tree)>.
 
-=item ($root_content, $added_sections) = fill_gaps_in_sectioning ($root)
+=item complete_tree_nodes_missing_menu ($tree, $use_section_names_in_entries)
+
+Add whole menus for nodes associated with sections and without menu,
+based on the sectioning tree.  If the optional
+C<$add_section_names_in_entries> argument is set, a menu entry
+name is added using the section name.  This function should be
+called after L<sectioning_structure|Texinfo::Structuring/$sections_root, 
$sections_list = sectioning_structure($registrar, $configuration_information, 
$tree)>.
+
+=item ($root_content, $added_sections) = fill_gaps_in_sectioning ($tree)
 
 This function adds empty C<@unnumbered> and similar commands in a tree
-to fill gaps in sectioning.  This may be used, for example, when converting 
-from a format that can handle gaps in sectioning.  I<$root> is the tree
+to fill gaps in sectioning.  This may be used, for example, when converting
+from a format that can handle gaps in sectioning.  I<$tree> is the tree
 root.  An array reference is returned, containing the root contents
-with added sectioning commands, as well as an array reference containing 
+with added sectioning commands, as well as an array reference containing
 the added sectioning commands.
 
 If the sectioning commands are lowered or raised (with C<@raisesections>,
 C<@lowersection>) the tree may be modified with C<@raisesections> or
 C<@lowersection> added to some tree elements.
 
-=item menu_to_simple_menu ($menu)
-
-=item set_menus_to_simple_menu ($nodes_list)
-
-C<menu_to_simple_menu> transforms the tree of a menu tree element.  
-C<set_menus_to_simple_menu> calls C<menu_to_simple_menu> for all the
-menus of the nodes in C<$nodes_list>.
-
-A simple menu has no I<menu_comment>, I<menu_entry> or 
I<menu_entry_description>
-container anymore, their content are merged directly in the menu in 
-I<preformatted> container.
-
-=item ($root_content, $added_nodes) = insert_nodes_for_sectioning_commands 
($parser, $tree, $nodes_list, $targets_list, $labels)
+=item ($root_content, $added_nodes) = insert_nodes_for_sectioning_commands 
($tree, $nodes_list, $targets_list, $labels)
 
 Insert nodes for sectioning commands without node in C<$tree>.
 Add nodes to the labels used as targets for references C<$labels>
 and C<$targets_list> and to C<$nodes_list>.
 
 An array reference is returned, containing the root contents
-with added nodes, as well as an array reference containing the 
+with added nodes, as well as an array reference containing the
 added nodes.
 
-=item complete_tree_nodes_menus ($tree, $add_section_names_in_entries)
+=item menu_to_simple_menu ($menu)
 
-Add menu entries or whole menus for nodes associated with sections,
-based on the sectioning tree.  If the optional 
-C<$add_section_names_in_entries> argument is set, a menu entry 
-name is added using the section name.  This function should be
-called after L<sectioning_structure>.
+=item set_menus_to_simple_menu ($nodes_list)
 
-=item complete_tree_nodes_missing_menu ($tree, $use_section_names_in_entries)
+C<menu_to_simple_menu> transforms the tree of a menu tree element.
+C<set_menus_to_simple_menu> calls C<menu_to_simple_menu> for all the
+menus of the nodes in C<$nodes_list>.
 
-Add whole menus for nodes associated with sections and without menu,
-based on the sectioning tree.  If the optional 
-C<$add_section_names_in_entries> argument is set, a menu entry 
-name is added using the section name.  This function should be
-called after L<sectioning_structure>.
+A simple menu has no I<menu_comment>, I<menu_entry> or 
I<menu_entry_description>
+container anymore, their content are merged directly in the menu in
+I<preformatted> container.
 
-=item protect_hashchar_at_line_beginning($registrar, 
$configuration_information, $tree)
+=item $detailmenu = new_master_menu ($translations, $labels)
 
-Protect hash (#) character at the beginning of line such that they would
-not be considered as lines to be processed by the CPP processor.
+Returns a detailmenu tree element formatted as a master node.
+I<$translations>, if defined, should be a L<Texinfo::Translations> object and
+should also hold configuration information.
 
-=item $detailmenu = new_master_menu ($parser, $labels)
+=item protect_hashchar_at_line_beginning ($registrar, 
$configuration_information, $tree)
 
-Returns a detailmenu tree element formatted as a master node.
+Protect hash (#) character at the beginning of line such that they would
+not be considered as lines to be processed by the CPP processor.
+I<$registrar> is a L<Texinfo::Report> in which the errors
+and warnings encountered while parsing are registered.
 
-=item regenerate_master_menu ($parser, $labels)
+=item regenerate_master_menu ($translations, $labels)
 
 Regenerate the Top node master menu, replacing the first detailmenu
 in Top node menus or appending at the end of the Top node menu.
+I<$translations>, if defined, should be a L<Texinfo::Translations> object and
+should also hold configuration information.
 
 =back
 
 =head1 SEE ALSO
 
-L<Texinfo manual|http://www.gnu.org/s/texinfo/manual/texinfo/>, 
+L<Texinfo manual|http://www.gnu.org/s/texinfo/manual/texinfo/>,
 L<Texinfo::Parser>.
 
 =head1 AUTHOR
 
 Patrice Dumas, E<lt>pertusus@free.frE<gt>
 
+=head1 COPYRIGHT AND LICENSE
+
+Copyright 2016 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
+the Free Software Foundation; either version 3 of the License, or (at
+your option) any later version.
+
 =cut