> From: Gavin Smith <[email protected]> > Date: Sun, 22 Jun 2025 18:53:42 +0100 > > I've found an issue with the libc.texi manual (in the version I downloaded > in the past). Warnings are reported that weren't previously: > > $ ../tta/perl/texi2any.pl ../../libc/libc.texi > startup.texi:1: warning: node `Program Basics' lacks menu item for `Getopt' > but is abov > startup.texi:1: warning: node `Program Basics' lacks menu item for `Argp' but > is above > argp.texi:1: warning: node `Argp' lacks menu item for `Argp Option Vectors' > but is abov > argp.texi:1: warning: node `Argp' lacks menu item for `Argp Parser Functions' > but is ab > argp.texi:1: warning: node `Argp' lacks menu item for `Argp Children' but is > above it i > argp.texi:1: warning: node `Argp' lacks menu item for `Argp Help Filtering' > but is abov > argp.texi:1: warning: node `Argp' lacks menu item for `Argp Help Flags' but > is above it > argp.texi:1: warning: node `Argp' lacks menu item for `Suboptions Example' > but is above > creature.texi:309: warning: `.' or `,' must follow @xref, not f > > > The issue: "Getopt" should be subsidiary to "Parsing Program Arguments", but > is > at a different sectioning level: > > ---- > @node Parsing Program Arguments, , Argument Syntax, Program Arguments > @subsection Parsing Program Arguments > > @cindex program arguments, parsing > @cindex command arguments, parsing > @cindex parsing program arguments > If the syntax for the command line arguments to your program is simple > enough, you can simply pick the arguments off from @var{argv} by hand. > But unless your program takes a fixed number of arguments, or all of the > arguments are interpreted in the same way (as file names, for example), > you are usually better off using @code{getopt} (@pxref{Getopt}) or > @code{argp_parse} (@pxref{Argp}) to do the parsing. > > @code{getopt} is more standard (the short-option only version of it is a > part of the POSIX standard), but using @code{argp_parse} is often > easier, both for very simple and very complex option structures, because > it does more of the dirty work for you. > > @menu > * Getopt:: Parsing program options using @code{getopt}. > * Argp:: Parsing program options using > @code{argp_parse}. > * Suboptions:: Some programs need more detailed options. > * Suboptions Example:: This shows how it could be done for > @code{mount}. > @end menu > > @c Getopt and argp start at the @section level so that there's > @c enough room for their internal hierarchy (mostly a problem with > @c argp). -Miles > > @include getopt.texi > @include argp.texi > ---- > > As the comment says, "Getopt" is a @section although its superior node > is a @subsection.
The automatic calculation of Prev/Next/Up node pointers assume a strict tree-like structure of a manual, and it also assumes that the @menu item for a node appears in its parent node. If these conditions are not fulfilled, then the Texinfo source should explicitly specify the Prev/Next/Up pointers on the @node line, because it is unreasonable to expect makeinfo to figure out what the author meant by such an irregular structure. So I don't think you should try fixing this problem. It is something to be fixed by the authors of the glibc manual. > I expect the warnings were not reported before because the direction pointers > are given explicity for Getopt on the @node line. Which is expected in this case. > However, the output is badly structured, especially for any output > format other than Info, so I guess that the warnings (or similar) > should be kept. 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.
