Re: silencing warnings of inconsistencies of directions with order in menu

[Gavin Smith]

On Wed, Nov 04, 2020 at 01:40:02AM +0100, Patrice Dumas wrote:
> see no reason to avoid producing those warnings when the node containing
> the menu has explicit directions, as the menu directions are more for
> the children nodes.

OK, makes sense.

> I think that there are many legitimate reasons for menu node entries
> order not to correspond to the Next and Prev directions of the nodes 
> in menu.  Here are a few cases
> * anchor in menu.  For example, if a node has reasons to be long and 
>   one want to have a direct access to an anchor in the middle of the 
>   node from the menu
> * nodes omitted from menu, for instance if it doesn't make sense
>   to go directly to such a node but going through the previous node
>   would be better
> * subnode appearing directly in menu.  This is actually covered
>   by @detailmenu, but @detailmenu is supposed to be for master node
>   only
> * use a node entry that points to another nodes for additional/detailed
>   material that could be in unrelated locations of the manual.
>   In that case a @*ref could be used too, but if producing
>   Info it is better to have the @menu at the end of the @node.
> 
> There are probably other cases I do not have thought about.  So, in
> general the Next/Prev relations (be them autogenerated or manually set)
> do not need to match the menu order, nor would all the nodes need to
> appear in the menu of their up node.


These are all possible, although probably hardly used in real
documents.  Since they should be supported anyway, and there's no
good way to mark them as valid in documents, then I tend to agree the
errors/warnings should be off by default, especially since the menus
are not required, unusual structures are more likely to be intentional.

> That being said for the vast majority of manuals the @menu structure
> follows the structure of the nodes directions, as it is a classical 
> structure with a logic (going deeper in a subject when going down) and
> is consistent with the sectioning structure tree.  So being able to find
> when the menu structure does not follow the document tree from node
> directions (itself in general based on sectioning tree) could be
> usefull.  This may not be so usefull when menus are automatically
> created, which should become the norm, except when a user wants to use
> specific menu entre name or description.
> 
> 
> I propose 
> * to add a customization variable with name like
>   WARN_MENU_ORDER_NOT_DIRECTIONS such that the warnings are only on
>   if it is set.

Yes, sounds OK.  SHOW_MENU/FORMAT_MENU would no longer be used for this
purpose.

Some suggestions for the name:
ENFORCE_NORMAL_MENU_STRUCTURE, CHECK_CANONICAL_MENU_STRUCTURE,
WARN_NONSTANDARD_MENU, ERROR_IRREGULAR_MENU, or some combination.


> * to remove the condition of warning only if a node has automatic 
>   directions and instead warn for all nodes if WARN_MENU_ORDER_NOT_DIRECTIONS
>   is set

Yes, there is no reason why implicit node directions have to be the
condition for menu warnings.

> About the default for WARN_MENU_ORDER_NOT_DIRECTIONS, I have no
> definitive opinion, as I said above.  So if you have arguments for or
> against a case, that could be usefull.

I think it should be off by default.

The biggest issue I have found is when moving sections around a manual,
it is very easy not to update all the menus properly and then be
deluged with error messages.

There could still be a warning for unreferenced nodes if not referenced
in either the menus or by directions (possibly implicitly).  This would
lead to at most one warning per node.