Menus should be optional in Texinfo source

[Gavin Smith]

Here's a patch to make menus optional in Texinfo source files.

I based this on the code for the existing option "-c
TREE_TRANSFORMATIONS=complete_tree_nodes_menus".

makeinfo will now add a menu to nodes that don't have one already and
output it for Info output.

This simplifies the creation of Texinfo source files, especially those
created for HTML or PDF output where the contents of @menu blocks are
not propagated.

It would save updating menus manually, or else using specialized Emacs
modes to edit Texinfo files. It would allow someone to miss out menus
in the source file, if they didn't want to give menu entry
descriptions.

Adding a new section can give lots of errors if the menu of the parent
node isn't updated. For example, if "Chapter Three" is missing in:

@menu
* Chapter One::
* Chapter Two::
* Chapter Four::
@end menu

the error messages look like:

tp/structure.texi:17: warning: node next `Chapter Two' in menu
`Chapter Four' and in sectioning `Chapter Three' differ
tp/structure.texi:20: warning: unreferenced node `Chapter Three'
tp/structure.texi:20: warning: node `Chapter Four' is next for
`Chapter Three' in sectioning but not in menu
tp/structure.texi:20: warning: node `Chapter Two' is prev for `Chapter
Three' in sectioning but not in menu
tp/structure.texi:20: warning: node `Top' is up for `Chapter Three' in
sectioning but not in menu
tp/structure.texi:3: node `Top' lacks menu item for `Chapter Three'
despite being its Up target
tp/structure.texi:23: warning: node prev `Chapter Four' in menu
`Chapter Two' and in sectioning `Chapter Three' differ

which can be hard to make sense of. Allowing menus to be missed out
would make it easier to fix these error messages.

I suggest we change the manual to explain why someone might want to
explicitly give a menu, for example if they want topic names to be
different to node names or give more explanation of what a node is
about other than its name.

I haven't suggested just turning on 'complete_tree_nodes_menus' by
default because that would be less strict and allow incomplete menus,
which are probably not what the author of the document wants in their
source file.

make-menus-optional.patch
Description: Text Data