On Fri, May 30, 2025 at 05:38:11PM +0100, Gavin Smith wrote:
> > In the next two or three days, I'll try to do the corresponding change
> > in the C code. Then I'll look at splitting out the structure-checking
> > code into its own function...
>
> I've done this. I noticed that complete_node_tree_with_menus it was
> not run from C/texi2any.c, but some of this looks quite different to
> perl/texi2any.pl so presumably it is on purpose.
>
> > ... before looking at how this code could be
> > reformed or rewritten.
>
> I haven't done this yet.
I'm still in the middle of doing this. I've got more changes I'm in the
middle of writing that I haven't committed yet.
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.
This can be seen on the current version of the libc manual on the web:
https://www.gnu.org/software/libc/manual/html_node/Getopt.html
This is headed "25.2 Parsing program options using getopt". The up link
goes to:
"25.1.2 Parsing Program Arguments"
https://www.gnu.org/software/libc/manual/html_node/Parsing-Program-Arguments.html
Because the HTML output doesn't show the menus anymore, there isn't a link
back to the Getop node. You have to click "Up" two more times to get
to the "Program Basics" node, in which "Getopt" is referenced as an inferior
node.
https://www.gnu.org/software/libc/manual/html_node/Program-Basics.html
I expect the warnings were not reported before because the direction pointers
are given explicity for Getopt on the @node line. 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.
This could be an example of incorrect sectioning levels being the problem,
rather than an issue with menus. At the moment the only idea I have is
to also warn about the node up pointer mismatch at the same time.
The concern is that users start getting a lot of error messages without
an easy way to fix them. There is not a command below @subsubsection.
There is no room for a section number like '25.1.2.2.2.1.1' which would
be used for a deep node like "Argp Option Flags".
Top > Program Basics > Program Arguments > Parsing Program Arguments
> Argp > Argp Parsers > Argp Option Vectors > Argp Option Flags
One argument is that such deep sectioning structures shouldn't be used
because they are confusing for readers of the manual and make it hard
to navigate.
