> From: Gavin Smith <[email protected]> > Date: Mon, 23 Jun 2025 21:46:08 +0100 > Cc: [email protected], [email protected] > > > I'm not sure I understand what is the bad structure. If you allude to > > the lack of link back to Getopt's node, then that's expected with such > > a structure. Users could perhaps click ""BACK" to go back to the > > Getopt page. If a warning is preferred in this case, then I think > > this: > > > > startup.texi:1: warning: node `Program Basics' lacks menu item for > > `Getopt' but is above it... > > > > already fits the bill, IMO. > > The bad structure is that the Info file has a menu in "Parsing Program > Arguments" that lists Getopt, but this is not listed as a subsection in > the HTML manual. As Patrice says, this is not so bad, as it is there > as a link anyway. > > However, it appears that the "Suboptions" node is incorrectly "adopted" > in the sectioning structure by the last node given in argp.texi, > "Argp User Customization", which is a @subsection: > > @include getopt.texi > @include argp.texi > > @node Suboptions, Suboptions Example, Argp, Parsing Program Arguments > @c This is a @section so that it's at the same level as getopt and argp > @subsubsection Parsing of Suboptions > > The comment contradicts the fact that it is a @subsubsection. > > I haven't checked the latest sources to see if this is still the case, but > this can be seen in the current web documentation: > > https://www.gnu.org/software/libc/manual/html_node/Argp-User-Customization.html > > There is a link at the end to the "Suboptions" node, titled "Parsing of > Suboptions". > > Likewise, "Suboptions Example" is adopted by "Argp" and appears at the > end of the list of subsections in the HTML output: > > https://www.gnu.org/software/libc/manual/html_node/Argp.html > > Neither "Suboptions" nor "Suboptions Examples" is referenced in the > HTML output for "Parsing Program Arguments", even though they are listed > in the @menu in that node. > > So while the Info output is basically fine, output that doesn't use > menus, including the default HTML output and output with TeX, has > problems. Hence I believe we should keep the new warnings with > CHECK_NORMAL_MENU_STRUCTURE, even though the authors have provided > explicit node pointers that match the intended document structure, as > you describe.
I think there are two separate issues here. One is the actual structure of the glibc manual wrt these subsections. Any such problems can only be addressed by the authors of the manual, since we cannot expect makeinfo to understand which structure is good and which isn't. The other issue is what kind of warnings, if any, should makeinfo issue in these cases. My comment was only about this second issue, because I think that's the only issue that should be your bother while you reimplement this stuff. As an example of a manual whose structure is not a tree, but is well-thought out, see info.texi. I'd expect to see such warnings there as well (unless the few explicit node pointers it has will avoid that), although the structure of that manual is fine.
