On 08.02.2023 08:17, Tom Tromey wrote:
> The BFD docs currently specify all the parameters to @node. However,
> this results in bad navigation in certain nodes -- the "space" command
> in info doesn't know how to find the next node.
>
> I think this style of @node is a leftover from ancient times.
> Makeinfo can figure out the node structure on its own now, so simplify
> everything to a single-argument @node.
>
> 2023-02-07 Tom Tromey <tom@tromey.com>
>
> * doc/webassembly.texi (File layout): Remove second argument from
> @node.
> * doc/bfd.texi: Use single-argument @node everywhere.
> ---
> bfd/ChangeLog | 6 +++++
> bfd/doc/bfd.texi | 56 ++++++++++++++++++++--------------------
> bfd/doc/webassembly.texi | 2 +-
> 3 files changed, 35 insertions(+), 29 deletions(-)
Does this change need to be accompanied by an update to configure, to
build BFD doc only with new enough makeinfo? This is what I get with
4.12 (admittedly old, but apparently deemed acceptable right now):
.../bfd/doc/bfd.texi:245: Node `Sections' requires a sectioning command (e.g., @unnumberedsubsec).
.../bfd/doc/bfd.texi:248: Node `Symbols' requires a sectioning command (e.g., @unnumberedsubsubsec).
.../bfd/doc/bfd.texi:251: Node `Archives' requires a sectioning command (e.g., @unnumberedsubsubsec).
.../bfd/doc/bfd.texi:254: Node `Formats' requires a sectioning command (e.g., @unnumberedsubsubsec).
.../bfd/doc/bfd.texi:257: Node `Relocations' requires a sectioning command (e.g., @unnumberedsubsubsec).
.../bfd/doc/bfd.texi:260: Node `Core Files' requires a sectioning command (e.g., @unnumberedsubsubsec).
.../bfd/doc/bfd.texi:263: Node `Targets' requires a sectioning command (e.g., @unnumberedsubsubsec).
.../bfd/doc/bfd.texi:266: Node `Architectures' requires a sectioning command (e.g., @unnumberedsubsubsec).
.../bfd/doc/bfd.texi:269: Node `Opening and Closing' requires a sectioning command (e.g., @unnumberedsubsubsec).
.../bfd/doc/bfd.texi:272: Node `Internal' requires a sectioning command (e.g., @unnumberedsubsubsec).
.../bfd/doc/bfd.texi:275: Node `File Caching' requires a sectioning command (e.g., @unnumberedsubsubsec).
.../bfd/doc/bfd.texi:278: Node `Linker Functions' requires a sectioning command (e.g., @unnumberedsubsubsec).
.../bfd/doc/bfd.texi:281: Node `Hash Tables' requires a sectioning command (e.g., @top).
.../bfd/doc/bfd.texi:300: Node `aout' requires a sectioning command (e.g., @unnumberedsubsec).
.../bfd/doc/bfd.texi:303: Node `coff' requires a sectioning command (e.g., @unnumberedsubsec).
.../bfd/doc/bfd.texi:306: Node `elf' requires a sectioning command (e.g., @unnumberedsubsec).
.../bfd/doc/bfd.texi:311: Node `mmo' requires a sectioning command (e.g., @unnumberedsubsec).
.../bfd/doc/bfd.texi:314: Node `GNU Free Documentation License' requires a sectioning command (e.g., @unnumberedsubsubsec).
.../bfd/doc/bfd.texi:317: `BFD Index' has no Up field (perhaps incorrect sectioning?).
.../bfd/doc/bfd.texi:314: `GNU Free Documentation License' has no Up field (perhaps incorrect sectioning?).
.../bfd/doc/bfd.texi:311: `mmo' has no Up field (perhaps incorrect sectioning?).
.../bfd/doc/bfd.texi:306: `elf' has no Up field (perhaps incorrect sectioning?).
.../bfd/doc/bfd.texi:303: `coff' has no Up field (perhaps incorrect sectioning?).
.../bfd/doc/bfd.texi:300: `aout' has no Up field (perhaps incorrect sectioning?).
.../bfd/doc/bfd.texi:296: Next field of node `What to Put Where' not pointed to (perhaps incorrect sectioning?).
.../bfd/doc/bfd.texi:300: This node (aout) has the bad Prev.
.../bfd/doc/bfd.texi:284: `BFD back ends' has no Up field (perhaps incorrect sectioning?).
.../bfd/doc/bfd.texi:281: `Hash Tables' has no Up field (perhaps incorrect sectioning?).
.../bfd/doc/bfd.texi:278: `Linker Functions' has no Up field (perhaps incorrect sectioning?).
.../bfd/doc/bfd.texi:275: `File Caching' has no Up field (perhaps incorrect sectioning?).
.../bfd/doc/bfd.texi:272: `Internal' has no Up field (perhaps incorrect sectioning?).
.../bfd/doc/bfd.texi:269: `Opening and Closing' has no Up field (perhaps incorrect sectioning?).
.../bfd/doc/bfd.texi:266: `Architectures' has no Up field (perhaps incorrect sectioning?).
.../bfd/doc/bfd.texi:263: `Targets' has no Up field (perhaps incorrect sectioning?).
.../bfd/doc/bfd.texi:260: `Core Files' has no Up field (perhaps incorrect sectioning?).
.../bfd/doc/bfd.texi:257: `Relocations' has no Up field (perhaps incorrect sectioning?).
.../bfd/doc/bfd.texi:254: `Formats' has no Up field (perhaps incorrect sectioning?).
.../bfd/doc/bfd.texi:251: `Archives' has no Up field (perhaps incorrect sectioning?).
.../bfd/doc/bfd.texi:248: `Symbols' has no Up field (perhaps incorrect sectioning?).
.../bfd/doc/bfd.texi:245: `Sections' has no Up field (perhaps incorrect sectioning?).
.../bfd/doc/bfd.texi:222: Next field of node `Memory Usage' not pointed to (perhaps incorrect sectioning?).
.../bfd/doc/bfd.texi:245: This node (Sections) has the bad Prev.
.../bfd/doc/bfd.texi:195: `BFD front end' has no Up field (perhaps incorrect sectioning?).
.../bfd/doc/bfd.texi:91: `Overview' has no Up field (perhaps incorrect sectioning?).
.../bfd/doc/bfd.texi:78: Next field of node `Top' not pointed to (perhaps incorrect sectioning?).
.../bfd/doc/bfd.texi:91: This node (Overview) has the bad Prev.
I have no insight yet what else in the series may cause further issues.
Jan
@@ -75,7 +75,7 @@ Copyright @copyright{} 1991-2023 Free Software Foundation, Inc.
@end iftex
@contents
-@node Top, Overview, (dir), (dir)
+@node Top
@ifinfo
This file documents the binary file descriptor library libbfd.
@end ifinfo
@@ -88,7 +88,7 @@ This file documents the binary file descriptor library libbfd.
* BFD Index:: BFD Index
@end menu
-@node Overview, BFD front end, Top, Top
+@node Overview
@chapter Introduction
@cindex BFD
@cindex what is it?
@@ -114,7 +114,7 @@ their own use, for greater efficiency.
* What BFD Version 2 Can Do:: What BFD Version 2 Can Do
@end menu
-@node History, How It Works, Overview, Overview
+@node History
@section History
One spur behind BFD was the desire, on the part of the GNU 960 team at
@@ -137,7 +137,7 @@ and David Henkel-Wallace (@code{gumby@@cygnus.com}).
-@node How It Works, What BFD Version 2 Can Do, History, Overview
+@node How It Works
@section How To Use BFD
To use the library, include @file{bfd.h} and link with @file{libbfd.a}.
@@ -188,11 +188,11 @@ and contain subordinate BFDs. This approach is fine for a.out and coff,
but loses efficiency when applied to formats such as S-records and
IEEE-695.
-@node What BFD Version 2 Can Do, , How It Works, Overview
+@node What BFD Version 2 Can Do
@section What BFD Version 2 Can Do
@include bfdsumm.texi
-@node BFD front end, BFD back ends, Overview, Top
+@node BFD front end
@chapter BFD Front End
@menu
@@ -219,7 +219,7 @@ IEEE-695.
@include bfdt.texi
@include bfdio.texi
-@node Memory Usage, Sections, Miscellaneous, BFD front end
+@node Memory Usage
@section Memory Usage
BFD keeps all of its internal structures in obstacks. There is one obstack
per open BFD file, into which the current state is stored. When a BFD is
@@ -242,46 +242,46 @@ select the greediest open BFD, close it to reclaim the memory, perform
some operation and reopen the BFD again, to get a fresh copy of the data
structures.
-@node Sections, Symbols, Memory Usage, BFD front end
+@node Sections
@include section.texi
-@node Symbols, Archives, Sections, BFD front end
+@node Symbols
@include syms.texi
-@node Archives, Formats, Symbols, BFD front end
+@node Archives
@include archive.texi
-@node Formats, Relocations, Archives, BFD front end
+@node Formats
@include format.texi
-@node Relocations, Core Files, Formats, BFD front end
+@node Relocations
@include reloc.texi
-@node Core Files, Targets, Relocations, BFD front end
+@node Core Files
@include corefile.texi
-@node Targets, Architectures, Core Files, BFD front end
+@node Targets
@include targets.texi
-@node Architectures, Opening and Closing, Targets, BFD front end
+@node Architectures
@include archures.texi
-@node Opening and Closing, Internal, Architectures, BFD front end
+@node Opening and Closing
@include opncls.texi
-@node Internal, File Caching, Opening and Closing, BFD front end
+@node Internal
@include libbfd.texi
-@node File Caching, Linker Functions, Internal, BFD front end
+@node File Caching
@include cache.texi
-@node Linker Functions, Hash Tables, File Caching, BFD front end
+@node Linker Functions
@include linker.texi
-@node Hash Tables, , Linker Functions, BFD front end
+@node Hash Tables
@include hash.texi
-@node BFD back ends, GNU Free Documentation License, BFD front end, Top
+@node BFD back ends
@chapter BFD back ends
@menu
* What to Put Where::
@@ -293,28 +293,28 @@ structures.
* srecord :: s-record backend
@end ignore
@end menu
-@node What to Put Where, aout, BFD back ends, BFD back ends
+@node What to Put Where
@section What to Put Where
All of BFD lives in one directory.
-@node aout, coff, What to Put Where, BFD back ends
+@node aout
@include aoutx.texi
-@node coff, elf, aout, BFD back ends
+@node coff
@include coffcode.texi
-@node elf, mmo, coff, BFD back ends
+@node elf
@include elf.texi
@c Leave this out until the file has some actual contents...
@c @include elfcode.texi
-@node mmo, , elf, BFD back ends
+@node mmo
@include mmo.texi
-@node GNU Free Documentation License, BFD Index, BFD back ends, Top
+@node GNU Free Documentation License
@include fdl.texi
-@node BFD Index, , GNU Free Documentation License, Top
+@node BFD Index
@unnumbered BFD Index
@printindex cp
@@ -27,7 +27,7 @@ in some malformed WebAssembly modules being treated as valid.
* File layout::
@end menu
-@node File layout, WebAssembly
+@node File layout
@subsection File layout
For a description of the WebAssembly file format, see
@url{https://github.com/WebAssembly/design/blob/master/BinaryEncoding.md}.