branch master updated: Update documentation/comments related to text_root

[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 0d9f65a7c2 Update documentation/comments related to text_root
0d9f65a7c2 is described below

commit 0d9f65a7c2fc74ed219a0869894daee00e2b90b0
Author: Patrice Dumas <pertusus@free.fr>
AuthorDate: Fri Dec 31 12:23:56 2021 +0100

    Update documentation/comments related to text_root
---
 tp/Texinfo/ParserNonXS.pm       | 25 +++++++++++++------------
 tp/Texinfo/XS/parsetexi/close.c |  2 +-
 2 files changed, 14 insertions(+), 13 deletions(-)

diff --git a/tp/Texinfo/ParserNonXS.pm b/tp/Texinfo/ParserNonXS.pm
index fec12f6b70..6e57f0ae8c 100644
--- a/tp/Texinfo/ParserNonXS.pm
+++ b/tp/Texinfo/ParserNonXS.pm
@@ -1800,11 +1800,11 @@ sub _close_commands($$$;$$)
         # stop if the command is found
   while (!($closed_command and $current->{'cmdname'}
            and $current->{'cmdname'} eq $closed_command) 
-         # stop if at the root
+         # Stop if at the root
          and $current->{'parent'}
-         # stop if at a root type
+         # Stop if at a type at the root
          and not ($current->{'type'} and $current->{'type'} eq 'text_root')
-     # stop if in a root command
+     # Stop if in a root command
      # or in a context_brace_commands and searching for a specific 
      # end block command (with $closed_command set).  
      # This second condition means that a footnote is not closed when 
@@ -6037,8 +6037,7 @@ as an argument is used to parse into a tree.
 
 When C<parse_texi_line> is used, the resulting tree is rooted at
 a C<root_line> type container.  Otherwise, the resulting tree should be
-rooted at a C<text_root> type container if it does not contain nodes or
-sections, at a C<document_root> type container otherwise.
+rooted at a C<document_root> type container.
 
 =over
 
@@ -6659,18 +6658,20 @@ other elements appearing in their C<contents>.
 
 =over
 
-=item text_root
-
 =item document_root
 
 =item root_line
 
-These types correspond to document roots.  C<text_root> is the document
-root when there is no C<@node> or sectioning command.  When
-such a command appears, a new root container is used, C<document_root>,
-and C<text_root> becomes the first element in the contents of C<document_root>.
 C<root_line> is the type of the root tree when parsing Texinfo line
-fragments using C<parse_texi_line>.
+fragments using C<parse_texi_line>.  C<document_root> is the document
+root otherwise.
+
+C<document_root> first content should be C<text_root>, then nodes and
+sections @-commands elements, and also C<@bye> element.
+
+=item text_root
+
+Content before nodes and sectioning commands at the beginning of 
C<document_root>.
 
 =item preamble_before_beginning
 
diff --git a/tp/Texinfo/XS/parsetexi/close.c b/tp/Texinfo/XS/parsetexi/close.c
index ec4634a411..7ae9348c8d 100644
--- a/tp/Texinfo/XS/parsetexi/close.c
+++ b/tp/Texinfo/XS/parsetexi/close.c
@@ -374,7 +374,7 @@ close_commands (ELEMENT *current, enum command_id 
closed_command,
          && (!closed_command || current->cmd != closed_command)
      /* Stop if in a root command. */
          && !(current->cmd && command_flags(current) & CF_root)
-     /* stop if at a root type */
+     /* Stop if at a type at the root */
          && !(current->type == ET_text_root))
     {
       close_command_cleanup (current);