branch master updated: * doc/texinfo.texi (Menus): Advertise the benefits of not using @menu in Texinfo sources.

[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 67912459d5 * doc/texinfo.texi (Menus): Advertise the benefits of not 
using @menu in Texinfo sources.
67912459d5 is described below

commit 67912459d5960b86f89114c41195e407238dba1b
Author: Gavin Smith <gavinsmith0123@gmail.com>
AuthorDate: Thu Aug 3 23:06:41 2023 +0100

    * doc/texinfo.texi (Menus): Advertise the benefits of not using
    @menu in Texinfo sources.
---
 ChangeLog        |  5 +++++
 doc/texinfo.texi | 13 ++++++++-----
 2 files changed, 13 insertions(+), 5 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index d92113103e..267faf4341 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+2023-08-03  Gavin Smith <gavinsmith0123@gmail.com>
+
+       * doc/texinfo.texi (Menus): Advertise the benefits of not using
+       @menu in Texinfo sources.
+
 2023-08-03  Gavin Smith <gavinsmith0123@gmail.com>
 
        * doc/texinfo.texi (Node Descriptions): New node to document
diff --git a/doc/texinfo.texi b/doc/texinfo.texi
index c668dd9a19..048d8f1b19 100644
--- a/doc/texinfo.texi
+++ b/doc/texinfo.texi
@@ -3432,16 +3432,19 @@ a menu as follows:
 @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 role in printed
-manuals and other output formats.
+manuals or other output formats.
 
 Menus are automatically generated by @command{texi2any} when outputting
 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.
+It is often more convenient to let @command{texi2any} generate
+menus for you, as you do not then have the burden of updating menu
+blocks in your Texinfo source when you add, remove, or relocate nodes.
+In the usual case of a hierarchically organized manual with sectioning
+commands associated with nodes, and with node pointers left out, you
+should only write menus if you want exact control over the contents
+and formatting of menus in Info.
 
 
 @node Writing a Menu