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
