Re: makeinfo 7.1 misses menu errors
On Mon, Jan 22, 2024 at 10:50:07PM +0100, pertu...@free.fr wrote: > On Sun, Jan 21, 2024 at 03:13:25PM -0700, Karl Berry wrote: > > Hi Patrice, > > > > I understand the principle, but for me the lossage in practice is even > > more unfortunate (by far). It sure seems to me that the "rare" case > > should be the one to have to make the config file setting. Indeed, the > > very fact of making that config file setting would helpfully alert > > contributors and builders that "this is not a normally-structured > > manual". > > > > I dearly hope you will reconsider. --thanks, karl. > > I am not sure that I can change my mind, to me, when there is a doubt, > correctness in principle is more important than usability. However, I > understand the arguments, which are sound. > > Maybe Gavin, you could decide? I had in mind at least to set CHECK_NORMAL_MENU_STRUCTURE before the next release to get the warnings that were output before, if the warnings cannot be improved. Perhaps this could change in the future if more manuals stop using @menu blocks following the "normal" structure.
Re: makeinfo 7.1 misses menu errors
Patrice: sure, I understand. Gavin: let me add one more point: if the warning is not reenabled by default, you are essentially forcing every maintainer of every manual to add a new flag to their makeinfo invocation, conditional on the makeinfo version. This seems ... bad. --thanks, karl.
Re: makeinfo 7.1 misses menu errors
On Sun, Jan 21, 2024 at 03:13:25PM -0700, Karl Berry wrote: > Hi Patrice, > > I understand the principle, but for me the lossage in practice is even > more unfortunate (by far). It sure seems to me that the "rare" case > should be the one to have to make the config file setting. Indeed, the > very fact of making that config file setting would helpfully alert > contributors and builders that "this is not a normally-structured > manual". > > I dearly hope you will reconsider. --thanks, karl. I am not sure that I can change my mind, to me, when there is a doubt, correctness in principle is more important than usability. However, I understand the arguments, which are sound. Maybe Gavin, you could decide? -- Pat
Re: makeinfo 7.1 misses menu errors
Hi Patrice, then they can set CHECK_NORMAL_MENU_STRUCTURE on explicitely. It's easy to say that, but it creates an incompatibility for the 99.99% case. I can't set it for makeinfo 7.x without giving people using 6.x (which is most everyone, downstream) a useless warning. Nor can I omit it without great chance of messing up the manual. Also, it feels painful to have to set a config file variable at all to get a useful feature which has always been enabled by default. Indeed, having better error messages was one of the primary advantages of C makeinfo over Elisp texinfo-format-buffer, umpteen years ago. My point is that some users may want to have menus that do not follow the sectioning structure, it is perfectly correct, I understand. But my point is that, although it can be correct in theory, in practice it is 99.99% (at least) caused by a mistake, not intentional. Therefore it sure seems to me that makeinfo should follow the 99.99% case, not the .001% case, just because of some theoretical possibility. The new features to support normally-structured manuals are great, but because they are so new, they can't yet be used for manuals intended to be widely distributed. I could not use them for automake, for example, without causing tremendous trouble with all the distros and users using older makeinfos. Which will be the case for many years yet. I agree that setting CHECK_NORMAL_MENU_STRUCTURE on is best for most manuals. However, it would lead to emitting warnings for correct, even if rare cases, which I find very unfortunate. I understand the principle, but for me the lossage in practice is even more unfortunate (by far). It sure seems to me that the "rare" case should be the one to have to make the config file setting. Indeed, the very fact of making that config file setting would helpfully alert contributors and builders that "this is not a normally-structured manual". I dearly hope you will reconsider. --thanks, karl.
Re: makeinfo 7.1 misses menu errors
On Sat, Jan 20, 2024 at 07:06:44PM +, Gavin Smith wrote: > On Sat, Jan 20, 2024 at 06:45:06PM +0100, Patrice Dumas wrote: > > > 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. > > I have difficulty following the last sentence here. Users may want > to have menus that follow the menu structure if they have existing > Texinfo documents that are structured that way, and they are not > ready or willing to delete all of their @menu blocks to generate all > menus automatically. Of course, but then they can set CHECK_NORMAL_MENU_STRUCTURE on explicitely. My point is that some users may want to have menus that do not follow the sectioning structure, it is perfectly correct, and it seems to me wrong to have warnings, in the default case, for a correct use of @menu. > > 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. > > This goes against the practice of the vast majority of existing Texinfo > manuals, so this existing practice should be well supported. I agree that setting CHECK_NORMAL_MENU_STRUCTURE on is best for most manuals. However, it would lead to emitting warnings for correct, even if rare cases, which I find very unfortunate. If a user knows that its manual menus are supposed to follow the sectioning structure, then he/she can set CHECK_NORMAL_MENU_STRUCTURE on. -- Pat
Re: makeinfo 7.1 misses menu errors
This goes against the practice of the vast majority of existing Texinfo manuals, so this existing practice should be well supported. Indeed. That is the crucial point. Those warnings are needed in well over 99% of existing manuals, as far as I've seen :). I think that it could be possible to change the error location to be the To my mind, the precise message is not critical. The existing messages work well enough to let the manual author find what needs to be fixed. Sure, they could be improved, but let's not have "perfect" be the enemy of "good enough". --thanks, karl.
Re: makeinfo 7.1 misses menu errors
On Sat, Jan 20, 2024 at 06:45:06PM +0100, Patrice Dumas wrote: > > 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. I have difficulty following the last sentence here. Users may want to have menus that follow the menu structure if they have existing Texinfo documents that are structured that way, and they are not ready or willing to delete all of their @menu blocks to generate all menus automatically. > 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. This goes against the practice of the vast majority of existing Texinfo manuals, so this existing practice should be well supported. It seems to me that we should warn about the extra menu entry in some way, either by turning CHECK_NORMAL_MENU_STRUCTURE on, or by devising better warnings. > 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. I suppose it's possible the choice of section command could be wrong, e.g. @section instead of @subsection etc. generating errors. If we change the error messages we should think about what are some common mistakes a user might make in editing a document.
Re: makeinfo 7.1 misses menu errors
On Fri, Jan 19, 2024 at 10:16:06PM +, 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/msg4.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/msg5.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:
Re: makeinfo 7.1 misses menu errors
> Date: Fri, 19 Jan 2024 16:30:33 -0700 > From: Karl Berry > > Hi Gavin, > > The problem as I remember it was that the error messages are awful: > > No argument, but having any message at all is infinitely better than > silence. I urge you to restore them by default, suboptimal as they are. > > It's true that those msgs as such have never made a great deal of sense > to me (including in the old C makeinfo). But they indicate perfectly > well "there is a problem with the sectioning+menus related to node XYZ". > It was not hard to figure it out once I knew that. I had no clue there > was a problem until someone using makeinfo 6.x told me. I agree. Perhaps by default makeinfo should just display a general warning about "some problem with sectioning vs menus", with a pointer to the offending @menu command, and the warning text should advise to use "-c CHECK_NORMAL_MENU_STRUCTURE=1" to get the details. WDYT?
Re: makeinfo 7.1 misses menu errors
Hi Gavin, The problem as I remember it was that the error messages are awful: No argument, but having any message at all is infinitely better than silence. I urge you to restore them by default, suboptimal as they are. It's true that those msgs as such have never made a great deal of sense to me (including in the old C makeinfo). But they indicate perfectly well "there is a problem with the sectioning+menus related to node XYZ". It was not hard to figure it out once I knew that. I had no clue there was a problem until someone using makeinfo 6.x told me. This said, I have not studied in detail how to restructure the code to improve the warnings. Not critical, it seems to me. The critical thing, IMHO, is to give us back the warnings as they stand by default, so bad manuals don't get unwittingly distributed. Which is what is surely happening and will continue to happen. --thanks, karl.
Re: makeinfo 7.1 misses menu errors
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/msg4.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/msg5.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
Re: makeinfo 7.1 misses menu errors
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/msg4.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/msg5.html And in fact my example document from 2023 does get a warning in 7.1. So that is good. My new report is about a similar, but not identical, case which still does not get a warning in 7.1. I presume(d) it should (i.e., a bug). Thanks, Karl
Re: makeinfo 7.1 misses menu errors
> Date: Wed, 17 Jan 2024 14:55:33 -0700 > From: Karl Berry > > I recently learned that some @menu vs. sectioning discrepancies in the > automake manual were found with makeinfo 6.7, but not 7.1. > > In essence, I moved a subsection (Errors with distclean) from one > section to another, but forgot to remove the menu entry from the old one. > (Surely not an uncommon error.) > > Running the attached on 7.1, there are no errors or warnings. > 6.7 correctly reports various problems resulting from this: 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".
