branch master updated: * doc/texinfo.texi (Node Descriptions): New node to document @nodedescription and @nodedescriptionblock. (Menus): Edit slightly.

[Gavin D. Smith]

This is an automated email from the git hooks/post-receive script.

gavin pushed a commit to branch master
in repository texinfo.

The following commit(s) were added to refs/heads/master by this push:
     new fbfddcf5f7 * doc/texinfo.texi (Node Descriptions): New node to 
document @nodedescription and @nodedescriptionblock. (Menus): Edit slightly.
fbfddcf5f7 is described below

commit fbfddcf5f7b2382a8d3ce4fb3454ed14bb72a7d9
Author: Gavin Smith <gavinsmith0123@gmail.com>
AuthorDate: Thu Aug 3 22:35:14 2023 +0100

    * doc/texinfo.texi (Node Descriptions): New node to document
    @nodedescription and @nodedescriptionblock.
    (Menus): Edit slightly.
---
 ChangeLog        |  6 +++++
 doc/texinfo.texi | 69 ++++++++++++++++++++++++++++++++++++++++++++++++++++----
 2 files changed, 71 insertions(+), 4 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index c29ed4330a..d92113103e 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2023-08-03  Gavin Smith <gavinsmith0123@gmail.com>
+
+       * doc/texinfo.texi (Node Descriptions): New node to document
+       @nodedescription and @nodedescriptionblock.
+       (Menus): Edit slightly.
+
 2023-08-03  Gavin Smith <gavinsmith0123@gmail.com>
 
        * NEWS: reword slightly
diff --git a/doc/texinfo.texi b/doc/texinfo.texi
index b92bb4c73a..c668dd9a19 100644
--- a/doc/texinfo.texi
+++ b/doc/texinfo.texi
@@ -3364,6 +3364,65 @@ Texinfo File''.  This shows a @code{@@node} line 
followed by a
 @end example
 
 
+@node Node Descriptions
+@nodedescriptionblock
+@code{@@nodedescription} and @code{@@nodedescriptionblock}.
+@end nodedescriptionblock
+@section Node Descriptions
+
+You can provide a short description of the purpose of a node by using
+the @code{@@nodedescription} command following the @code{@@node} line.
+Such a description might elaborate on or extend the information in the
+node name itself.
+
+You can also use a @code{@@nodedescriptionblock} environment to
+provide a node description. This may be useful for longer descriptions.
+
+@command{texi2any} uses the content you provide with these commands
+when outputing menus for Info output format (and, optionally,
+for HTML).  @command{texi2any} uses the description after a menu
+entry for the node if it is generating the menu automatically, or
+if no description for the menu entry was provided in an explicit
+@code{@@menu} block. (@xref{Menus}).
+
+Here is an example of using these commands:
+
+@example
+@@node Tools
+@@chapter Tools
+
+This chapter is on different tools you can use.
+
+@@node Screwdrivers
+@@nodedescription Flathead and Phillips.
+@@section Screwdrivers
+
+This section is about screwdrivers.
+
+@@node Drills
+@@nodedescriptionblock
+Making holes in things with power screwdrivers, drill drivers, combi
+drills, impact drivers, hammer drills, breakers and demolition drills.
+@@end nodedescriptionblock
+@@section Drills
+
+This section is about drills.
+@end example
+
+In Info output, @command{texi2any} would output the @samp{Tools} node with
+a menu as follows:
+
+@example
+* Menu:
+
+* Screwdrivers::          Flathead and Phillips.
+* Drills::                Making holes in things with power
+                          screwdrivers, drill drivers, combi
+                          drills, impact drivers, hammer drills,
+                          breakers and demolition drills.
+@end example
+
+
 @node Menus
 @nodedescription Listing subordinate nodes.
 @section Menus
@@ -3372,12 +3431,14 @@ Texinfo File''.  This shows a @code{@@node} line 
followed by a
 
 @dfn{Menus} contain pointers to subordinate nodes.  In Info output,
 you use menus to go to such nodes.  Menus can be used in HTML output
-but are not used in the default case.  Menus have no effect in printed
-manuals and do not appear in them.  Menus are ignored in DocBook output.
+but are not used in the default case.  Menus have no role in printed
+manuals and other output formats.
 
 Menus are automatically generated by @command{texi2any} when outputting
-Info for nodes followed by a sectioning command, without menu, and with
-automatic pointers.  In a hierarchically organized manual with sectioning
+Info for nodes followed by a sectioning command, without an explicit
+@code{@@menu} block, and with automatic pointers.
+
+In a hierarchically organized manual with sectioning
 commands associated with nodes and with node pointers left out, you should
 only write menus if you want to have descriptions especially formatted
 in Info.