Re: Menus should be optional in Texinfo source

[Karl Berry]

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

Seems like a nice addition, in general.

    created for HTML or PDF output where the contents of @menu blocks are
    not propagated.

Menus are used in HTML output (as I'm sure you know).

    TREE_TRANSFORMATIONS=complete_tree_nodes_menus

It seems to me that this existing transformation already supports the
cases of no menus at all in the source, for just-PDF output, or when
authors don't want to write any node descriptions at all.  (This could
be further explicated in the manual.)

Thus, it further seems to me that the time that the new feature would be
most useful is if the author wanted to write some descriptions, e.g.,
for top-level menu(s), but not bother with every single submenu.  That
is plausible.

I think there needs to be a way to turn it off, for when authors really
do want a menu at every level.  In fact, I think I want to suggest that
the feature be off by default, so as to not change behavior after 30
years of precedent.

Maybe there should be a Texinfo-level way for an author to declare "not
all menus are present" in the document that would turn on the new
feature -- or turn on complete_tree_nodes_menus for that matter.  That
would be more convenient for authors than changing the invocation
arguments.

    Allowing menus to be missed out would make it easier to fix these
    error messages.

I don't understand.  How does your patch change the error messages in
the case of a missing menu item for a new node?  The new code doesn't
silently insert a missing entry in that case, does it?  I gathered that
a needed menu is synthesized only if the given node contains no menu at
all.

    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 disagree with the implicit suggestion that writing menus is something
to be eschewed by default.  (That would also imply rather a lot of
surgery on the manual, which has talked about menus as an integral part
of Texinfo since day one.)  As long as Texinfo manuals are fundamentally
a sequence of nodes, menus are useful as a way to provide additional
information about the nodes.

Instead, I would suggest that the manual describe when the new feature
is desirable, i.e., when an author does not want to write descriptions
at all levels.

    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.

I agree.

Thanks,
Karl