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