Menu structure check reform proposal

[Gavin Smith]

On Fri, May 30, 2025 at 06:16:30PM +0100, Gavin Smith wrote:
> On Wed, May 28, 2025 at 09:23:15AM +0200, Patrice Dumas wrote:
> > > It could be possible to write completely new code just checking for
> > > faults, which doesn't rely on "menu directions" at all.  (It may not be
> > > clear to the user what "menu directions" are as these are an abstraction
> > > created internally by texi2any.)  For example, we could record structural
> > > flaws that involve groups of nodes, and then output all the warnings in
> > > one go, rather than reporting the warnings node-by-node.
> > 
> > I would be more cautious about not using "menu directions".  To me menu
> > directions are a useful abstraction, which is not internal to texi2any,
> > it is a representation of the tree obtained with menus, it is a property
> > of the Texinfo manual.  The checks can probably be done without the menu
> > directions, but my feeling is that it is easier with menu directions.
> 
> Well, node directions are not uniquely determined from menus, as a node can be
> referred to in more than one menu.

I've thought about this more and considered three different types of
structural flaws with menus that could easily occur through the editing of a
Texinfo file:

  (A) Node missing from menu.  This could happen if a new section is added to
  a chapter, and not added to the menu for that chapter.
  
  (B) Node in wrong menu.  This could happen if a section is moved between
  chapters without the menus being updated.
  
  (C) Menu out of order.  This could happen if the sections within a chapter
  are reordered, but stay in the same chapter.
  
(Obviously, in theory a wide variety of menu and node structure is possible
as input as texi2any, but I think the three flaws above are a good start
for considering what errors might be reported.  Another class of error, as
mentioned in previous discussions, is that the menus are as intended, but
a wrong structuring command is used, for example @chapter instead of
@section.)

I would like to split node/menu structure checking into two phases:

  * Phase 1 "menu-node subordination": checking which nodes appear in
  which menus.  These errors would be grouped by the node that appears
  in the menu(s), not by the node that contains the menu.  For example,
  if a node appears in the wrong menu, the absence from one menu would
  be linked to the presence in the other menu.

  This is like a "menu up" mismatch that is currently reported (but more
  detail could be given if a node occurs in multiple menus, and the location
  of the menu(s) could be reported).  This deals with flaws (A) and (B) above.

  * Phase 2 "menu sequencing": checking the sequence of menu items within
  a single menu, and whether this matches the sequence of sections.  These 
errors
  would be grouped by the node *containing* the menu.  This deals with
  flaw (C) above.

  This is like the "menu next" and "menu prev" errors that can be currently
  reported.  If a node was already reported on in phase 1 as being in
  the wrong menu, it would not be reported on in phase 2 for that menu.

Old discussions:

"silencing warnings of inconsistencies of directions with order in menu"
https://lists.gnu.org/archive/html/bug-texinfo/2020-11/msg00032.html

(I wrote: "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.")

"makeinfo no longer validates the menu structure"
https://lists.gnu.org/archive/html/bug-texinfo/2023-06/msg00014.html

"warning about missing menu items?"
https://lists.gnu.org/archive/html/help-texinfo/2023-07/msg00004.html

"makeinfo 7.1 misses menu errors"
https://lists.gnu.org/archive/html/bug-texinfo/2024-01/msg00011.html

(Following that last discussion, we turned all the errors back on, and
they were on in texi2any 7.2, released in December 2024.)