Re: makeinfo 7.1 misses menu errors

[Gavin Smith]

On Thu, Jan 18, 2024 at 04:57:15PM -0700, Karl Berry wrote:
>     I believe this is an intentional feature in recent Texinfo versions.
>     To get the warnings back, you need to run makeinfo with the
>     command-line option "-c CHECK_NORMAL_MENU_STRUCTURE=1".
> 
> Thanks for the hint. I reported a similar thing in July 2023,
> https://lists.gnu.org/archive/html/help-texinfo/2023-07/msg00004.html
> 
> and my understanding of Patrice's reply is that the config setting
> was no longer intended to be needed in 7.1:
> https://lists.gnu.org/archive/html/help-texinfo/2023-07/msg00005.html

That reply pertained to the case of a missing menu entry.  Your case
is the opposite: a superfluous menu entry.

Here's the documentation, for reference:

‘CHECK_MISSING_MENU_ENTRY’
     When a ‘@menu’ block occurs in a node, check if there is a menu
     entry for all subordinate nodes in the document sectioning
     structure.  On by default.

‘CHECK_NORMAL_MENU_STRUCTURE’
     Warn if the node pointers (either explicitly or automatically set)
     are not consistent with the order of node menu entries.  This is a
     more thorough structure check than that provided by
     ‘CHECK_MISSING_MENU_ENTRY’.  Off by default.

In 7.1, the CHECK_MISSING_MENU_ENTRY setting was introduced and turned
on by default, but this doesn't check for extra entries, i.e. if all
the menu entries are to nodes that have the current node as "Up".

The problem as I remember it was that the error messages are awful:

amdisorder.texi:8791: warning: node `Flag Variables Ordering' is next for 
`Errors with distclean' in menu but not in sectioning
amdisorder.texi:8791: warning: node prev pointer for `Errors with distclean' is 
`distuninstallcheck' but prev is `Limitations on File Names' in menu
amdisorder.texi:8791: warning: node up pointer for `Errors with distclean' is 
`Checking the Distribution' but up is `FAQ' in menu
amdisorder.texi:12435: warning: node next pointer for `Limitations on File 
Names' is `Flag Variables Ordering' but next is `Errors with distclean' in menu
amdisorder.texi:12498: warning: node prev pointer for `Flag Variables Ordering' 
is `Limitations on File Names' but prev is `Errors with distclean' in menu

(with "texi2any amdisorder.texi -c CHECK_NORMAL_MENU_STRUCTURE=1").

There are five error messages here for one mistake.  They are not very
easy to make sense of, in my opinion.

The most relevant warning of these is this one:

amdisorder.texi:8791: warning: node up pointer for `Errors with distclean' is 
`Checking the Distribution' but up is `FAQ' in menu

but this could be better expressed.  The message refers to a "node up
pointer" for the "Errors with distclean" node, but the user has not
provided such a "node up pointer" - it is something that is inferred by
the program.  The line number does not refer to the real location of the
error: 8791 is the location of "@node Errors with distclean", whereas
the true error in the document is elsewhere, in the @menu block in the
"FAQ" node (line 12072).

Moreover, if a node is incorrectly referenced in multiple menus, this
warning about the "node up pointer" is not given for them all.  If I
add the entry to the menu in another node, only errors about "node next"
and "node prev" appear.  For example, adding it to the menu in the node
"Autotools Introduction",

@menu
* GNU Build System::            Introducing the GNU Build System
* Use Cases::                   Use Cases for the GNU Build System
* Why Autotools::               How Autotools Help
* Hello World::                 A Small Hello World Package
* Errors with distclean::       Files left in build directory after distclean   
@end menu

the warnings output are

amdisorder.texi:1129: warning: node `Errors with distclean' is next for `Hello 
World' in menu but not in sectioning
amdisorder.texi:8792: warning: node `Flag Variables Ordering' is next for 
`Errors with distclean' in menu but not in sectioning
amdisorder.texi:8792: warning: node prev pointer for `Errors with distclean' is 
`distuninstallcheck' but prev is `Limitations on File Names' in menu
amdisorder.texi:8792: warning: node up pointer for `Errors with distclean' is 
`Checking the Distribution' but up is `FAQ' in menu
amdisorder.texi:12436: warning: node next pointer for `Limitations on File 
Names' is `Flag Variables Ordering' but next is `Errors with distclean' in menu
amdisorder.texi:12499: warning: node prev pointer for `Flag Variables Ordering' 
is `Limitations on File Names' but prev is `Errors with distclean' in menu

Again, the line numbers given in the error (1129) is nowhere where
the real problem is (line 196).

Looking at the code in 'complete_node_tree_with_menus' in Structuring.pm,
it appears that the CHECK_NORMAL_MENU_STRUCTURE errors only have one
possibility for each direction (Next, Prev, Up) in the "menu directions".
However, this seems wrong, as a node could be referenced in more than
one menu.

It seems to me that the issue is with error checking of @menu blocks,
so it would make sense to find these errors by looping over all menus
in the document, and checking if they match the document structure.  It
seems that the CHECK_NORMAL_MENU_STRUCTURE errors are produced in a
somewhat roundabout way, where first the "menu directions" are set
by 'set_menus_node_directions' in Structuring.pm and then checked for
mismatch with "node directions", which is mostly set in 'nodes_tree'
(although there are some assignmnents to 'node_directions' in
'complete_node_tree_with_menus' too).

This said, I have not studied in detail how to restructure the code
to improve the warnings.