On Mon, Jun 23, 2025 at 12:20:05AM +0200, Patrice Dumas wrote: > > > I do not really understand the comment explaining why Getopt and argp > > > start at the @section level, I do not get what "enough room for their > > > internal hierarchy" means, so it is not clear to me why the Glibc people > > > want that structure. > > > > Getopt is listed in the menu for "Parsing Program Arguments" which is > > a @subsection. This means that Getopt should be a @subsubsection. Getopt > > itself has inferior nodes, like "Using Getopt". However, there is no > > sectioning command below @subsubsection (no "@subsubsubsection", etc.). > > That's what they mean with "not enough room." > > Ok, I get it, thanks. In that specific case, a possibility could > be to have something in the Texinfo language to get a correct > output, as having a node structure different from the sectioning > structurer is not really wanted as such, but used as a trick to get a > correct output. That being said, I can't see any obvious way to > do that in a way that would integrate well with the current language.
I've found a similar problem with the Python manual in Texinfo, which is automatically generated with Sphinx (the version I am testing states "Generated by Sphinx 8.2.1."). This is a huge file as far as Texinfo files go, and takes around 45 seconds to process to Info on my computer (for comparison, the glibc manual takes just over 5 seconds). With my current work, texi2any outputs 197 new warnings. Again, the issue is with deeply nested sections. Here is the first such warning: python.texi:18135: warning: node `Removed<2>' in menu where `Pending Removal in Python 3 14<4>' expected The `Pending Removal...' node is a @subsubsection and the `Removed<2>' node is also a @subsubsection, but `Pending Removal...' is actually subsidiary to the node that preceded `Removed<2>' (`Deprecated<2>'), it is just at the @subsubsection level because there is no lower level. All these nodes (in the Sphinx output) have explicit pointers on the node lines, just like the affected part of the libc manual. So I expect we will have to take some account of node pointers when generating these warnings. (We could still give 1 or 2 warnings if there is a simple way of doing so, but not 197.) As these warnings come from automatically generated input that is not originally a Texinfo source file, it is less relevant to advise users to rewrite their manual to have fewer sectioning levels. > If there were only @node that would be possible, but for sectioning > commands nothing seems easy. In DocBook, this kind of structure is > achieved by having the possibility to nest <section> recursively up to > unbounded depth. It could be possible to nest block commands in Texinfo > to obtain the same kind of effect, but that would be quite inconsistent > with the language usual design in which line commands (@node, sectioning > commands) rather than block commands delimitate sections. > > Maybe an option could be to have a line @-command like @xrefname that > would use the structure of th eassociated node to determine the > sectioning level rather than the other way around. The most immediate fix for a manual would seem to be to replace all affected sectioning commands by @xrefname and express the node structure with @menu blocks and explicit node pointers. > For example in the > following example, the @nodesection would be equivalent to a > @subsubsubsection: > > @node my node > @subsubsection subsub > > @menu > * down:: > @end menu > > @node down > @nodesection Down there > The problem with this is there is no formatting for a "subsubsubsection" defined in texinfo.tex. Other output formats may be similarly limited: HTML itself only goes from <h1> through to <h6>; there is no *<h7>.
