[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

silencing warnings of inconsistencies of directions with order in menu

From: Patrice Dumas
Subject: silencing warnings of inconsistencies of directions with order in menu
Date: Wed, 4 Nov 2020 01:40:02 +0100


Following Christopher report on constraints on menu, I though about the
issue, and I think that the warnings about order of nodes in menu not
following the node directions should at least be easily
silenced, and maybe not turned on in the default case.  In addition I 
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.

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
* 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.

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.
* 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

Would that be ok?

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.


reply via email to

[Prev in Thread] Current Thread [Next in Thread]