branch master updated: Update Texinfo tree POD documentation

[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 e5d633e882 Update Texinfo tree POD documentation
e5d633e882 is described below

commit e5d633e882e989874acb3907745b841c81b07de3
Author: Patrice Dumas <pertusus@free.fr>
AuthorDate: Mon Nov 25 03:29:47 2024 +0100

    Update Texinfo tree POD documentation
---
 doc/tp_api/api_includes/Texinfo-Parser.texi | 259 ++++++++++++++++++++++++----
 doc/tp_api/texi2any_internals.texi          |  11 ++
 tp/Texinfo/ParserNonXS.pm                   | 244 ++++++++++++++++++++++----
 3 files changed, 451 insertions(+), 63 deletions(-)

diff --git a/doc/tp_api/api_includes/Texinfo-Parser.texi 
b/doc/tp_api/api_includes/Texinfo-Parser.texi
index 03d63946c5..811d6c2dd8 100644
--- a/doc/tp_api/api_includes/Texinfo-Parser.texi
+++ b/doc/tp_api/api_includes/Texinfo-Parser.texi
@@ -191,16 +191,219 @@ Finally, the last category is other elements, which in 
most cases have
 a @code{type} key holding their name.  Text fragments and @@-command elements
 may also have an associated type when such information is needed.
 
-The children of an @@-command or of other container element are in the array
-referred to with the @code{args} key or with the @code{contents} key.  The 
@code{args} key
-is for arguments of @@-commands, either in braces or on the rest of the line
-after the command, depending on the type of command.  The @code{contents} key 
array
-holds the contents of the texinfo code appearing within a block @@-command,
-within a container, or within a @code{@@node} or sectioning @@-command.
+The @code{contents} key holds an array reference for the children of @@-command
+tree elements and containers.  In particular for arguments of an @@-command,
+either in braces or on the rest of the line after the command, depending on
+the type of command. Also for content appearing within a block @@-command,
+within a container, or within a @code{@@node} or sectioning @@-command.  Text
+fragments do not have children.
+
+The @code{extra} and @code{info} keys are associated to hash references and 
hold
+information gathered during the parsing.
+
+@node Texinfo@asis{::}Parser Texinfo tree structure
+@subsection Texinfo tree structure
+
+@node Texinfo@asis{::}Parser Root and first level elements
+@subsubsection Root and first level elements
+
+A full Texinfo tree is rooted at a @emph{document_root} type element.
+@emph{document_root} first element in @code{contents} should be a
+@emph{before_node_section} container for content appearing before the first 
node or
+sectioning command.  Nodes and sections @@-commands elements follow.  The node
+or sectioning command elements @code{contents} hold all the elements 
corresponding
+to Texinfo code before the next node or sectioning command element or 
@code{@@bye}.
+If present in the Texinfo document, the @code{@@bye} element is next.  If 
there is
+content after @code{@@bye}, it is last in the @emph{postamble_after_end} 
container
+element.
+
+The content of @emph{before_node_section} depend on the presence of
+@code{@@setfilename} in the document before the first node or sectioning 
element:
 
-Another important key for the elements is the @code{extra} key which is
-associated to a hash reference and holds all kinds of information that
-is gathered during the parsing and may help with the conversion.
+@table @asis
+@item with @code{@@setfilename}
+@anchor{Texinfo@asis{::}Parser with @code{@@setfilename}}
+
+The first container in @emph{before_node_section} is
+@emph{preamble_before_setfilename}.  The first element in
+@emph{preamble_before_setfilename} is @emph{preamble_before_beginning}, which
+holds everything appearing before the first content, including
+the \input texinfo.tex line and following blank lines.  It may be
+followed by paragraphs and block commands elements, if any, although it is
+not recommended to have such content before @code{@@setfilename}.
+
+The second container in @emph{before_node_section} is
+@emph{preamble_before_content}, which begins with @code{@@setfilename}
+and contains everything appearing before the first formatted content,
+corresponding to the @emph{preamble} in the Texinfo documentation.
+
+The paragraphs and other contents follow up in @emph{before_node_section}
+@code{contents} until the first node or section.
+
+@item without @code{@@setfilename}
+@anchor{Texinfo@asis{::}Parser without @code{@@setfilename}}
+
+The first container in @emph{before_node_section} is 
@emph{preamble_before_beginning},
+which holds everything appearing before the first content, including
+the \input texinfo.tex line and following blank lines.
+
+It is followed by @emph{preamble_before_content}, which contains everything
+appearing before the first formatted content, corresponding to the 
@emph{preamble}
+in the Texinfo documentation.
+
+The paragraphs and other contents follow up in @emph{before_node_section}
+@code{contents} until the first node or section.
+
+@end table
+
+@emph{preamble_before_content} contains empty lines text elements,
+elements corresponding to line commands such as @code{@@documentlanguage} or
+@code{@@frenchspacing}, block commands such as @code{@@copying} that are not 
immediately
+output but also raw output block commands such as @code{@@html}.
+
+The first element of a node or sectioning command @code{contents}
+is an @emph{arguments_line} container holding the command arguments
+appearing on the @@-command line.  The @emph{arguments_line} in turn contains
+@emph{line_arg} containers for each of the node arguments separated by
+commas, or the unique sectioning command argument.  The node or
+sectioning command contents follow, including paragraphs, empty line
+text elements, all kind of block commands and line commands such as
+@code{@@center} or index commands such as @code{@@cindex} as well as 
@code{@@image}
+command elements out of paragraphs.
+
+@node Texinfo@asis{::}Parser Line command tree element
+@subsubsection Line command tree element
+
+There are three main types of line commands, regular line commands,
+@emph{lineraw} line commands and definition line commands.
+
+@table @asis
+@item @emph{lineraw} line commands
+@anchor{Texinfo@asis{::}Parser @emph{lineraw} line commands}
+
+@emph{lineraw} line commands arguments are not subject to the
+usual macro expansion.  @emph{lineraw} line commands with
+arguments are, for example, @code{@@set}, @code{@@clickstyle}, @code{@@unmacro}
+and @code{@@comment}.  @code{@@raisesections}, @code{@@contents} and 
@code{@@novalidate}
+are examples of @emph{lineraw} line commands without arguments.
+
+@emph{lineraw} line commands @code{contents} contains direclty 
@emph{rawline_arg}
+text elements holding the line arguments or the end of line if the
+@@-command do not have any argument.
+
+@item regular line commands
+@anchor{Texinfo@asis{::}Parser regular line commands}
+
+Most line commands with arguments that are not node or sectioning commands are
+regular line commands.  Regular line command @code{contents} holds 
@emph{line_arg}
+containers for each of the line arguments separated by commas.  @emph{line_arg}
+containers contain in turn text elements, elements of @@-commands without
+arguments, with empty braces, such as @code{@@equiv} and with braces such as
+@code{@@code} or @code{@@ref}.
+
+@item definition line commands
+@anchor{Texinfo@asis{::}Parser definition line commands}
+
+Definition line commands elements are elements associated to commands like
+@code{@@deffnx} or @code{@@defline}.  They contain a @emph{line_arg} 
container, which, in
+turn contains the specific definition line containers such as 
@emph{def_category},
+@emph{def_arg} and some special text elements such as @emph{space}.
+
+@end table
+
+@node Texinfo@asis{::}Parser Block command tree element
+@subsubsection Block command tree element
+
+The first element of most block command @code{contents} is an 
@emph{arguments_line}
+container holding the command arguments appearing on the @@-command line,
+similar to node and sectioning command elements.  The @emph{arguments_line} 
holds
+@emph{line_arg} containers for each of the arguments separated by commas, 
similar
+to line commands.  Definition block commands such as @code{@@deffn} do not 
follow
+the same rule and do not have an @emph{arguments_line} container.  
@code{@@defblock}
+command element, however, is like regular block commands, with an
+@emph{arguments_line} container as first @code{contents} element.
+
+The remaining elements in @code{contents} depend on the block command.  Block
+commands like @code{@@float}, @code{@@quotation} or @code{@@flushleft} 
remaining @code{contents}
+are paragraphs, empty line text elements, line commands and nested block
+commands, much like node and sectioning elements, appearing before the matching
+@code{@@end} commmand element.
+
+Block commands like @code{@@example} or @code{@@display} are similar except 
that they
+contain @emph{preformatted} containers instead of paragraphs and so do
+other block commands nested in those @@-commands.
+
+Other block commands contain specific containers depending on the block
+command.  Block commands with @code{@@item} may contain a @emph{before_item} 
container
+for contents before the first @code{@@item}.  @code{@@itemize} and 
@code{@@enumerate} block
+commands following contents are @code{@@item} commands holding the Texinfo
+code elements until the next @code{@@item} or @code{@@end}.  @code{@@table} 
and similar block
+commands elements in @code{contents} are @emph{table_entry} containers for 
each table
+line, that contain themselves specific containers.  @code{@@multitable} 
contains
+@emph{multitable_head} and @emph{multitable_body} containers.  @code{@@menu} 
@code{contents}
+hold @emph{menu_entry} and @emph{menu_comments} container elements.
+
+The definition commands such as @code{@@deffn} contain a @emph{def_line} 
container
+as first @code{contents}, may contain an @emph{inter_def_item} container, also 
contains
+@code{@@deffnx} line commands, and ends with a @emph{def_item} container for 
the main
+contents of the definition command.  The @code{@@defblock} commands 
@code{contents} may
+hold a @emph{before_defline} element after the line arguments, also contains
+line @@-commands such as @code{@@defline} and a @emph{def_item} container.  The
+@emph{def_line} container contains a @emph{block_line_arg} container,
+which, in turn contains the specific definition line containers such as
+@emph{def_category}, @emph{def_arg} and some special text elements such as 
@emph{space}.
+
+Raw block commands such as @code{@@verbatim}, @code{@@ignore} or @code{@@macro}
+contain directly @emph{raw} text elements.
+
+Lastly, raw output commands such as @code{@@html} element in @code{contents} 
after the
+@emph{arguments_line} is either an @emph{elided_rawpreformatted} element 
container
+containing @emph{raw} text elements if ignored, or a @emph{rawpreformatted} 
container
+containing directly text and @@-command elements if output.
+
+The @code{@@end} command element is a regular line command element and is the 
last
+element of all the block commands @code{contents}.
+
+@node Texinfo@asis{::}Parser Paragraphs and preformatted
+@subsubsection Paragraphs and preformatted
+
+@emph{paragraph} and @emph{preformatted} container @code{contents} are 
+text elements, elements of @@-commands without arguments, such as @code{@@@}}, 
with
+empty braces, such as @code{@@equiv} and with braces such as @code{@@code} or 
@code{@@ref}.
+They may also contain elements corresponding to the few line commands that do
+not stop a paragraph, such as index command elements.  @emph{preformatted}
+container may contain empty line text elements, while @emph{paragraph} 
containers
+do not.
+
+@node Texinfo@asis{::}Parser Brace commands
+@subsubsection Brace commands
+
+@code{@@footnote} and @code{@@caption} @@-command elements that start a new 
context and
+contain paragraphs and block commands contain a @emph{brace_command_context}
+container.  The @emph{brace_command_context} container contains 
@emph{paragraph},
+line command and block command elements, much like node, sectioning and block
+command elements.  @code{@@math} also contains a @emph{brace_command_context} 
container,
+which contains directly text and brace commands more similar to the
+@emph{preformatted} container.
+
+For commands taking arguments surrounded by braces when the whole text in the
+braces is in the argument, such as @code{@@u} or @code{@@code} the first and 
only
+@code{contents} element is a @emph{brace_container}.
+Other brace commands, in particular brace commands with arguments separated
+by commas contain @emph{brace_arg} containers, one for each of the arguments.
+The @emph{brace_container} and @emph{brace_arg} containers contain directly 
text
+elements some @@-commands without arguments and other @@-commands with braces,
+similar to @emph{line_arg} or @emph{paragraph} containers.
+
+@node Texinfo@asis{::}Parser Texinfo line tree
+@subsubsection Texinfo line tree
+
+When parsing Texinfo line fragments using @code{parse_texi_line}, a 
@emph{root_line}
+type element is the root element.  It should typically contain elements
+that appear in @emph{paragraph}, @emph{preformatted} or containers like 
@emph{line_arg}.
+
+@node Texinfo@asis{::}Parser Showing the tree structure
+@subsubsection Showing the tree structure
 
 You can see examples of the tree structure by running makeinfo like
 this:
@@ -246,16 +449,10 @@ give an information of the kind of text fragment, for 
example
 before a paragraph beginning.  Most @@-commands elements do not have
 a type associated.
 
-@item args
-@anchor{Texinfo@asis{::}Parser args}
-
-Arguments in braces or on @@-command line.  An array reference.
-
 @item contents
 @anchor{Texinfo@asis{::}Parser contents}
 
-The Texinfo appearing in the element.  For block commands, other
-containers, @code{@@node} and sectioning commands. An array reference.
+An array reference holding the list of children of the element. 
 
 @item parent
 @anchor{Texinfo@asis{::}Parser parent}
@@ -388,6 +585,13 @@ spaces appearing after an @@-command without braces that 
does not
 take argument on the line, but which is followed by ignorable
 spaces, such as @code{@@item} in @code{@@itemize} or @code{@@multitable}, or 
@code{@@noindent}.
 
+@item macro_line
+@anchor{Texinfo@asis{::}Parser macro_line}
+
+Text appearing on a @code{@@macro}, @code{@@linemacro} or @code{@@rmacro} line 
after
+the @@-command, including the leading space and the newline.  In the
+@emph{arguments_line} container @@-command.
+
 @item spaces_after_close_brace
 @anchor{Texinfo@asis{::}Parser spaces_after_close_brace}
 
@@ -542,7 +746,7 @@ with items (@code{@@table}, @code{@@multitable}, 
@code{@@enumerate}...).
 @item following_arg
 @anchor{Texinfo@asis{::}Parser following_arg}
 
-Those containers occur within the @code{args} array of @@-commands taking an
+Those containers occur within the @code{contents} array of @@-commands taking 
an
 argument.  @emph{brace_container} is used for the argument to commands
 taking arguments surrounded by braces when the whole text in the braces
 is in the argument.  @emph{brace_arg} is used for the arguments to commands 
taking
@@ -552,9 +756,10 @@ commas.  @emph{brace_command_context} is used for 
@@-commands with braces that s
 a new context (@code{@@footnote}, @code{@@caption}, @code{@@math}).
 
 @emph{line_arg} is used for commands that take the texinfo code on the rest of 
the
-line as their argument, such as @code{@@settitle}, @code{@@node}, 
@code{@@section}.
-@emph{block_line_arg} is similar but is used for commands that start a new 
block
-(which is to be ended with @code{@@end}).
+line as their argument, such as @code{@@settitle}, or for @code{@@node}, 
@code{@@section}
+@emph{arguments_line} container.  @emph{block_line_arg} is similar but is used 
for
+@emph{arguments_line} container of commands that start a new block (which is 
to be
+ended with @code{@@end}).
 
 @emph{following_arg} is used for the accent @@-commands argument that did not 
use
 braces but instead followed the @@-command, possibly after a space, as
@@ -678,17 +883,6 @@ call is expanded.  The name of the macro, rmacro or 
linemacro is the the info
 @emph{command_name} value.  The @emph{macro_call_line} or 
@emph{rmacro_call_line} elements
 are used when there are no braces and the whole line is the argument.
 
-@item macro_name
-@anchor{Texinfo@asis{::}Parser macro_name}
-
-@item macro_arg
-@anchor{Texinfo@asis{::}Parser macro_arg}
-
-Taken from @code{@@macro} definition and put in the @code{args} key array of
-the macro, @emph{macro_name} is the type of the text fragment corresponding
-to the macro name, @emph{macro_arg} is the type of the text fragments
-corresponding to macro formal arguments.
-
 @item menu_comment
 @anchor{Texinfo@asis{::}Parser menu_comment}
 
@@ -822,8 +1016,7 @@ and @code{@@itemx}, in a @emph{table_term}.
 @anchor{Texinfo@asis{::}Parser arg_line}
 
 The string correspond to the line after the @@-command
-for @@-commands that have special arguments on their line,
-and for @code{@@macro} line.
+for @@-commands that have special arguments on their line.
 
 @item command_name
 @anchor{Texinfo@asis{::}Parser command_name}
diff --git a/doc/tp_api/texi2any_internals.texi 
b/doc/tp_api/texi2any_internals.texi
index 16a142811f..77c03b5698 100644
--- a/doc/tp_api/texi2any_internals.texi
+++ b/doc/tp_api/texi2any_internals.texi
@@ -92,11 +92,22 @@ Texinfo::Parser METHODS
 
 TEXINFO TREE
 
+* Texinfo@asis{::}Parser Texinfo tree structure::
 * Texinfo@asis{::}Parser Element keys::
 * Texinfo@asis{::}Parser Element types::
 * Texinfo@asis{::}Parser Information available in the @code{info} key::
 * Texinfo@asis{::}Parser Information available in the @code{extra} key::
 
+Texinfo tree structure
+
+* Texinfo@asis{::}Parser Root and first level elements::
+* Texinfo@asis{::}Parser Line command tree element::
+* Texinfo@asis{::}Parser Block command tree element::
+* Texinfo@asis{::}Parser Paragraphs and preformatted::
+* Texinfo@asis{::}Parser Brace commands::
+* Texinfo@asis{::}Parser Texinfo line tree::
+* Texinfo@asis{::}Parser Showing the tree structure::
+
 Element types
 
 * Texinfo@asis{::}Parser Types for command elements::
diff --git a/tp/Texinfo/ParserNonXS.pm b/tp/Texinfo/ParserNonXS.pm
index 5d73e360da..860b5e70f4 100644
--- a/tp/Texinfo/ParserNonXS.pm
+++ b/tp/Texinfo/ParserNonXS.pm
@@ -8483,16 +8483,208 @@ Finally, the last category is other elements, which in 
most cases have
 a C<type> key holding their name.  Text fragments and @-command elements
 may also have an associated type when such information is needed.
 
-The children of an @-command or of other container element are in the array
-referred to with the C<args> key or with the C<contents> key.  The C<args> key
-is for arguments of @-commands, either in braces or on the rest of the line
-after the command, depending on the type of command.  The C<contents> key array
-holds the contents of the texinfo code appearing within a block @-command,
-within a container, or within a C<@node> or sectioning @-command.
+The C<contents> key holds an array reference for the children of @-command
+tree elements and containers.  In particular for arguments of an @-command,
+either in braces or on the rest of the line after the command, depending on
+the type of command. Also for content appearing within a block @-command,
+within a container, or within a C<@node> or sectioning @-command.  Text
+fragments do not have children.
 
-Another important key for the elements is the C<extra> key which is
-associated to a hash reference and holds all kinds of information that
-is gathered during the parsing and may help with the conversion.
+The C<extra> and C<info> keys are associated to hash references and hold
+information gathered during the parsing.
+
+=head2 Texinfo tree structure
+
+=head3 Root and first level elements
+
+A full Texinfo tree is rooted at a I<document_root> type element.
+I<document_root> first element in C<contents> should be a
+I<before_node_section> container for content appearing before the first node or
+sectioning command.  Nodes and sections @-commands elements follow.  The node
+or sectioning command elements C<contents> hold all the elements corresponding
+to Texinfo code before the next node or sectioning command element or C<@bye>.
+If present in the Texinfo document, the C<@bye> element is next.  If there is
+content after C<@bye>, it is last in the I<postamble_after_end> container
+element.
+
+The content of I<before_node_section> depend on the presence of
+C<@setfilename> in the document before the first node or sectioning element:
+
+=over
+
+=item with C<@setfilename>
+
+The first container in I<before_node_section> is
+I<preamble_before_setfilename>.  The first element in
+I<preamble_before_setfilename> is I<preamble_before_beginning>, which
+holds everything appearing before the first content, including
+the \input texinfo.tex line and following blank lines.  It may be
+followed by paragraphs and block commands elements, if any, although it is
+not recommended to have such content before C<@setfilename>.
+
+The second container in I<before_node_section> is
+I<preamble_before_content>, which begins with C<@setfilename>
+and contains everything appearing before the first formatted content,
+corresponding to the I<preamble> in the Texinfo documentation.
+
+The paragraphs and other contents follow up in I<before_node_section>
+C<contents> until the first node or section.
+
+=item without C<@setfilename>
+
+The first container in I<before_node_section> is I<preamble_before_beginning>,
+which holds everything appearing before the first content, including
+the \input texinfo.tex line and following blank lines.
+
+It is followed by I<preamble_before_content>, which contains everything
+appearing before the first formatted content, corresponding to the I<preamble>
+in the Texinfo documentation.
+
+The paragraphs and other contents follow up in I<before_node_section>
+C<contents> until the first node or section.
+
+=back
+
+I<preamble_before_content> contains empty lines text elements,
+elements corresponding to line commands such as C<@documentlanguage> or
+C<@frenchspacing>, block commands such as C<@copying> that are not immediately
+output but also raw output block commands such as C<@html>.
+
+The first element of a node or sectioning command C<contents>
+is an I<arguments_line> container holding the command arguments
+appearing on the @-command line.  The I<arguments_line> in turn contains
+I<line_arg> containers for each of the node arguments separated by
+commas, or the unique sectioning command argument.  The node or
+sectioning command contents follow, including paragraphs, empty line
+text elements, all kind of block commands and line commands such as
+C<@center> or index commands such as C<@cindex> as well as C<@image>
+command elements out of paragraphs.
+
+=head3 Line command tree element
+
+There are three main types of line commands, regular line commands,
+I<lineraw> line commands and definition line commands.
+
+=over
+
+=item I<lineraw> line commands
+
+I<lineraw> line commands arguments are not subject to the
+usual macro expansion.  I<lineraw> line commands with
+arguments are, for example, C<@set>, C<@clickstyle>, C<@unmacro>
+and C<@comment>.  C<@raisesections>, C<@contents> and C<@novalidate>
+are examples of I<lineraw> line commands without arguments.
+
+I<lineraw> line commands C<contents> contains direclty I<rawline_arg>
+text elements holding the line arguments or the end of line if the
+@-command do not have any argument.
+
+=item regular line commands
+
+Most line commands with arguments that are not node or sectioning commands are
+regular line commands.  Regular line command C<contents> holds I<line_arg>
+containers for each of the line arguments separated by commas.  I<line_arg>
+containers contain in turn text elements, elements of @-commands without
+arguments, with empty braces, such as C<@equiv> and with braces such as
+C<@code> or C<@ref>.
+
+=item definition line commands
+
+Definition line commands elements are elements associated to commands like
+C<@deffnx> or C<@defline>.  They contain a I<line_arg> container, which, in
+turn contains the specific definition line containers such as I<def_category>,
+I<def_arg> and some special text elements such as I<space>.
+
+=back
+
+=head3 Block command tree element
+
+The first element of most block command C<contents> is an I<arguments_line>
+container holding the command arguments appearing on the @-command line,
+similar to node and sectioning command elements.  The I<arguments_line> holds
+I<line_arg> containers for each of the arguments separated by commas, similar
+to line commands.  Definition block commands such as C<@deffn> do not follow
+the same rule and do not have an I<arguments_line> container.  C<@defblock>
+command element, however, is like regular block commands, with an
+I<arguments_line> container as first C<contents> element.
+
+The remaining elements in C<contents> depend on the block command.  Block
+commands like C<@float>, C<@quotation> or C<@flushleft> remaining C<contents>
+are paragraphs, empty line text elements, line commands and nested block
+commands, much like node and sectioning elements, appearing before the matching
+C<@end> commmand element.
+
+Block commands like C<@example> or C<@display> are similar except that they
+contain I<preformatted> containers instead of paragraphs and so do
+other block commands nested in those @-commands.
+
+Other block commands contain specific containers depending on the block
+command.  Block commands with C<@item> may contain a I<before_item> container
+for contents before the first C<@item>.  C<@itemize> and C<@enumerate> block
+commands following contents are C<@item> commands holding the Texinfo
+code elements until the next C<@item> or C<@end>.  C<@table> and similar block
+commands elements in C<contents> are I<table_entry> containers for each table
+line, that contain themselves specific containers.  C<@multitable> contains
+I<multitable_head> and I<multitable_body> containers.  C<@menu> C<contents>
+hold I<menu_entry> and I<menu_comments> container elements.
+
+The definition commands such as C<@deffn> contain a I<def_line> container
+as first C<contents>, may contain an I<inter_def_item> container, also contains
+C<@deffnx> line commands, and ends with a I<def_item> container for the main
+contents of the definition command.  The C<@defblock> commands C<contents> may
+hold a I<before_defline> element after the line arguments, also contains
+line @-commands such as C<@defline> and a I<def_item> container.  The
+I<def_line> container contains a I<block_line_arg> container,
+which, in turn contains the specific definition line containers such as
+I<def_category>, I<def_arg> and some special text elements such as I<space>.
+
+Raw block commands such as C<@verbatim>, C<@ignore> or C<@macro>
+contain directly I<raw> text elements.
+
+Lastly, raw output commands such as C<@html> element in C<contents> after the
+I<arguments_line> is either an I<elided_rawpreformatted> element container
+containing I<raw> text elements if ignored, or a I<rawpreformatted> container
+containing directly text and @-command elements if output.
+
+The C<@end> command element is a regular line command element and is the last
+element of all the block commands C<contents>.
+
+=head3 Paragraphs and preformatted
+
+I<paragraph> and I<preformatted> container C<contents> are 
+text elements, elements of @-commands without arguments, such as C<@}>, with
+empty braces, such as C<@equiv> and with braces such as C<@code> or C<@ref>.
+They may also contain elements corresponding to the few line commands that do
+not stop a paragraph, such as index command elements.  I<preformatted>
+container may contain empty line text elements, while I<paragraph> containers
+do not.
+
+=head3 Brace commands
+
+C<@footnote> and C<@caption> @-command elements that start a new context and
+contain paragraphs and block commands contain a I<brace_command_context>
+container.  The I<brace_command_context> container contains I<paragraph>,
+line command and block command elements, much like node, sectioning and block
+command elements.  C<@math> also contains a I<brace_command_context> container,
+which contains directly text and brace commands more similar to the
+I<preformatted> container.
+
+For commands taking arguments surrounded by braces when the whole text in the
+braces is in the argument, such as C<@u> or C<@code> the first and only
+C<contents> element is a I<brace_container>.
+Other brace commands, in particular brace commands with arguments separated
+by commas contain I<brace_arg> containers, one for each of the arguments.
+The I<brace_container> and I<brace_arg> containers contain directly text
+elements some @-commands without arguments and other @-commands with braces,
+similar to I<line_arg> or I<paragraph> containers.
+
+=head3 Texinfo line tree
+
+When parsing Texinfo line fragments using C<parse_texi_line>, a I<root_line>
+type element is the root element.  It should typically contain elements
+that appear in I<paragraph>, I<preformatted> or containers like I<line_arg>.
+
+=head3 Showing the tree structure
 
 You can see examples of the tree structure by running makeinfo like
 this:
@@ -8530,14 +8722,9 @@ I<spaces_before_paragraph> is associated to spaces 
appearing
 before a paragraph beginning.  Most @-commands elements do not have
 a type associated.
 
-=item args
-
-Arguments in braces or on @-command line.  An array reference.
-
 =item contents
 
-The Texinfo appearing in the element.  For block commands, other
-containers, C<@node> and sectioning commands. An array reference.
+An array reference holding the list of children of the element. 
 
 =item parent
 
@@ -8653,6 +8840,12 @@ spaces appearing after an @-command without braces that 
does not
 take argument on the line, but which is followed by ignorable
 spaces, such as C<@item> in C<@itemize> or C<@multitable>, or C<@noindent>.
 
+=item macro_line
+
+Text appearing on a C<@macro>, C<@linemacro> or C<@rmacro> line after
+the @-command, including the leading space and the newline.  In the
+I<arguments_line> container @-command.
+
 =item spaces_after_close_brace
 
 Spaces appearing after a closing brace, for some rare commands for which
@@ -8783,7 +8976,7 @@ with items (C<@table>, C<@multitable>, C<@enumerate>...).
 
 =item following_arg
 
-Those containers occur within the C<args> array of @-commands taking an
+Those containers occur within the C<contents> array of @-commands taking an
 argument.  I<brace_container> is used for the argument to commands
 taking arguments surrounded by braces when the whole text in the braces
 is in the argument.  I<brace_arg> is used for the arguments to commands taking
@@ -8793,9 +8986,10 @@ commas.  I<brace_command_context> is used for @-commands 
with braces that start
 a new context (C<@footnote>, C<@caption>, C<@math>).
 
 I<line_arg> is used for commands that take the texinfo code on the rest of the
-line as their argument, such as C<@settitle>, C<@node>, C<@section>.
-I<block_line_arg> is similar but is used for commands that start a new block
-(which is to be ended with C<@end>).
+line as their argument, such as C<@settitle>, or for C<@node>, C<@section>
+I<arguments_line> container.  I<block_line_arg> is similar but is used for
+I<arguments_line> container of commands that start a new block (which is to be
+ended with C<@end>).
 
 I<following_arg> is used for the accent @-commands argument that did not use
 braces but instead followed the @-command, possibly after a space, as
@@ -8895,15 +9089,6 @@ call is expanded.  The name of the macro, rmacro or 
linemacro is the the info
 I<command_name> value.  The I<macro_call_line> or I<rmacro_call_line> elements
 are used when there are no braces and the whole line is the argument.
 
-=item macro_name
-
-=item macro_arg
-
-Taken from C<@macro> definition and put in the C<args> key array of
-the macro, I<macro_name> is the type of the text fragment corresponding
-to the macro name, I<macro_arg> is the type of the text fragments
-corresponding to macro formal arguments.
-
 =item menu_comment
 
 The I<menu_comment> container holds what is between menu entries
@@ -9011,8 +9196,7 @@ and C<@itemx>, in a I<table_term>.
 =item arg_line
 
 The string correspond to the line after the @-command
-for @-commands that have special arguments on their line,
-and for C<@macro> line.
+for @-commands that have special arguments on their line.
 
 =item command_name