Re: makeinfo 7.1 misses menu errors

[Patrice Dumas]

On Fri, Jan 19, 2024 at 10:16:06PM +0000, Gavin Smith wrote:
> 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.

To me, the manual with an entry leading to a node that do not
corresponds to the sectioning structure is perfectly acceptable.  I
still do not see any issue in having the need to set
CHECK_NORMAL_MENU_STRUCTURE to get warnings.  I can't see why the user
would not want to have a menu that do not follow the sectioning
structure.

To me it was true before, menus were/are as much a list of links as
structuring commands, and it is even more so today, as now fully
automatic menus can be obtained with descriptions with @nodedescription.
Explicit menus are now needed only if one want a structure not following
the sectioning structure.

> 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

I do not know about the wording of the messages, but to me most of these
messages point to different issues regarding differences between menus and
sectionning.  To me, the next, prev, and up issues are different issues
and need to be there.  There could be redundancy, still, as having an
error for the a node next direction could be redundant with an error on
the prev direction of the following node in the menu.  So the following
messages could be redundant (remains to be sure that they are always
redundant):
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

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

I think that it could be possible to change the error location to be the
menu, but it is not clear that it indeed is the menu, the error could be
in the choice of the sectioning command, I think that we cannot really
know where the real error is, the user need to have a look and decide if
the menu or the sectioning is right.

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

As I said above, the real proble could also be the sectioning command of
'GNU Build System', we cannot really know.

> 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 is not necessarily wrong, it does not check that menus are ok, it
checks that menus are consistent with sectioning structure, so the code
follows the sectioning structure and finds if the menu structure
corresponds.  The issue may be more that, if a node appears in more than
one menu, its menu structure is 'multiply' instead of 'uniquely'
determined.  There is no check that a node menu direction is not set
more than once.

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

I think that a way to change the code would be, if
CHECK_NORMAL_MENU_STRUCTURE is set, to determine, in
set_menus_node_directions, when node directions are reset and warn at
that time, indeed, for a menu structure following the sectioning
structure, a node can only appear in one menu.

-- 
Pat