[PATCH 0/8] Make the BFD info manual a bit prettier

[PATCH 0/8] Make the BFD info manual a bit prettier

[Tom Tromey]

I noticed some oddities in the BFD info manual (see patch 7 and patch
8 for details).  While trying to fix these, I found a number of other
things that could be cleaned up a bit, and this series is the result.

I tested this by rebuilding with --enable-maintainer-mode and diffing
the header files to make sure they didn't change.  Then I inspected
the manual, well, manually.

Tom

[PATCH 1/8] Remove H_CFLAGS from doc/local.mk

[Tom Tromey]

I couldn't see that H_CFLAGS is defined anywhere, so remove it.

2023-02-07  Tom Tromey  <tom@tromey.com>

	* Makefile.in: Rebuild.
	* doc/local.mk (%D%/chew.stamp): Don't use H_CFLAGS.
---
 bfd/ChangeLog    | 5 +++++
 bfd/Makefile.in  | 2 +-
 bfd/doc/local.mk | 2 +-
 3 files changed, 7 insertions(+), 2 deletions(-)

diff --git a/bfd/Makefile.in b/bfd/Makefile.in
index 6fde8df6b06..82aa96f30e5 100644
--- a/bfd/Makefile.in
+++ b/bfd/Makefile.in
@@ -2460,7 +2460,7 @@ coff-tic54x.lo: coff-tic54x.c
 $(MKDOC): doc/chew.stamp ; @true
 doc/chew.stamp: $(srcdir)/doc/chew.c doc/$(am__dirstamp)
 	$(AM_V_CCLD)$(CC_FOR_BUILD) -o doc/chw$$$$$(EXEEXT_FOR_BUILD) $(CFLAGS_FOR_BUILD) \
-	  $(LDFLAGS_FOR_BUILD) $(H_CFLAGS) \
+	  $(LDFLAGS_FOR_BUILD) \
 	  -I. -I$(srcdir) -Idoc -I$(srcdir)/../include -I$(srcdir)/../intl -I../intl \
 	  $(srcdir)/doc/chew.c && \
 	$(SHELL) $(srcdir)/../move-if-change \
diff --git a/bfd/doc/local.mk b/bfd/doc/local.mk
index 41ab89fc6d8..d80f70416a3 100644
--- a/bfd/doc/local.mk
+++ b/bfd/doc/local.mk
@@ -83,7 +83,7 @@ MKDOC = %D%/chew$(EXEEXT_FOR_BUILD)
 $(MKDOC): %D%/chew.stamp ; @true
 %D%/chew.stamp: $(srcdir)/%D%/chew.c %D%/$(am__dirstamp)
 	$(AM_V_CCLD)$(CC_FOR_BUILD) -o %D%/chw$$$$$(EXEEXT_FOR_BUILD) $(CFLAGS_FOR_BUILD) \
-	  $(LDFLAGS_FOR_BUILD) $(H_CFLAGS) \
+	  $(LDFLAGS_FOR_BUILD) \
 	  -I. -I$(srcdir) -I%D% -I$(srcdir)/../include -I$(srcdir)/../intl -I../intl \
 	  $(srcdir)/%D%/chew.c && \
 	$(SHELL) $(srcdir)/../move-if-change \
-- 
2.39.1

[PATCH 2/8] Simplify @node use in BFD documentation

[Tom Tromey]

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(-)

diff --git a/bfd/doc/bfd.texi b/bfd/doc/bfd.texi
index f348710845f..d8cc1ecca48 100644
--- a/bfd/doc/bfd.texi
+++ b/bfd/doc/bfd.texi
@@ -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
 
diff --git a/bfd/doc/webassembly.texi b/bfd/doc/webassembly.texi
index ad650943a1a..5a05199d5f7 100644
--- a/bfd/doc/webassembly.texi
+++ b/bfd/doc/webassembly.texi
@@ -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}.
-- 
2.39.1

Re: [PATCH 2/8] Simplify @node use in BFD documentation

[Jan Beulich]

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

Re: [PATCH 2/8] Simplify @node use in BFD documentation

[Tom Tromey]

>>>>> "Jan" == Jan Beulich <jbeulich@suse.com> writes:

Jan> Does this change need to be accompanied by an update to configure, to
Jan> build BFD doc only with new enough makeinfo? This is what I get with
Jan> 4.12 (admittedly old, but apparently deemed acceptable right now):

I had no idea anyone was using a 10 year old makeinfo.  Does that work
for gdb's docs?  Or gcc's?

Jan> .../bfd/doc/bfd.texi:245: Node `Sections' requires a sectioning command (e.g., @unnumberedsubsec).

I guess that old version uses the full @node form as a workaround for
the lack of sectioning in bfd.texi.  If binutils wants to support this
then I think backing it out is probably the way to go.

Tom

Re: [PATCH 2/8] Simplify @node use in BFD documentation

[Jan Beulich]

On 04.03.2023 00:08, Tom Tromey wrote:
>>>>>> "Jan" == Jan Beulich <jbeulich@suse.com> writes:
> 
> Jan> Does this change need to be accompanied by an update to configure, to
> Jan> build BFD doc only with new enough makeinfo? This is what I get with
> Jan> 4.12 (admittedly old, but apparently deemed acceptable right now):
> 
> I had no idea anyone was using a 10 year old makeinfo.  Does that work
> for gdb's docs?  Or gcc's?

I didn't build gdb in a while, so I'm not sure there. Gcc is fine (with a
similar set of "unlikely character" warnings as seen in binutils).

> Jan> .../bfd/doc/bfd.texi:245: Node `Sections' requires a sectioning command (e.g., @unnumberedsubsec).
> 
> I guess that old version uses the full @node form as a workaround for
> the lack of sectioning in bfd.texi.  If binutils wants to support this
> then I think backing it out is probably the way to go.

Well, or - as said - raise the minimum makeinfo version requirement (looks
to be 4.7 right now, except libctf wanting 6.3) and simply skip doc
building otherwise.

Jan

[PATCH 3/8] Add copyright headers to the .str files

[Tom Tromey]

The .str script files don't have copyright headers, but I think they
should.  I used the same dates that chew.c uses, which I think makes
sense because these are inputs to chew.

2023-02-07  Tom Tromey  <tom@tromey.com>

	* doc/doc.str, doc/proto.str: Add copyright header.
---
 bfd/ChangeLog     |  4 ++++
 bfd/doc/doc.str   | 18 ++++++++++++++++++
 bfd/doc/proto.str | 17 +++++++++++++++++
 3 files changed, 39 insertions(+)

diff --git a/bfd/doc/doc.str b/bfd/doc/doc.str
index 7a276fe59e6..6019b7ccfdb 100644
--- a/bfd/doc/doc.str
+++ b/bfd/doc/doc.str
@@ -1,3 +1,21 @@
+- Documentation extraction program for chew.
+-  Copyright (C) 1990-2023 Free Software Foundation, Inc.
+-  This file is part of BFD, the Binary File Descriptor library.
+
+-  This program is free software; you can redistribute it and/or modify
+-  it under the terms of the GNU General Public License as published by
+-  the Free Software Foundation; either version 3 of the License, or
+-  (at your option) any later version.
+
+-  This program is distributed in the hope that it will be useful,
+-  but WITHOUT ANY WARRANTY; without even the implied warranty of
+-  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+-  GNU General Public License for more details.
+
+-  You should have received a copy of the GNU General Public License
+-  along with this program; if not, write to the Free Software
+-  Foundation, Inc., 51 Franklin Street - Fifth Floor, Boston, MA 02110-1301, USA.
+
 : DOCDD
 	skip_past_newline
 	get_stuff_in_command kill_bogus_lines catstr
diff --git a/bfd/doc/proto.str b/bfd/doc/proto.str
index 702d9f540ce..a9533526d6c 100644
--- a/bfd/doc/proto.str
+++ b/bfd/doc/proto.str
@@ -1,3 +1,20 @@
+- Source extraction program for chew.
+-  Copyright (C) 1990-2023 Free Software Foundation, Inc.
+-  This file is part of BFD, the Binary File Descriptor library.
+
+-  This program is free software; you can redistribute it and/or modify
+-  it under the terms of the GNU General Public License as published by
+-  the Free Software Foundation; either version 3 of the License, or
+-  (at your option) any later version.
+
+-  This program is distributed in the hope that it will be useful,
+-  but WITHOUT ANY WARRANTY; without even the implied warranty of
+-  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+-  GNU General Public License for more details.
+
+-  You should have received a copy of the GNU General Public License
+-  along with this program; if not, write to the Free Software
+-  Foundation, Inc., 51 Franklin Street - Fifth Floor, Boston, MA 02110-1301, USA.
 
 : SYNOPSIS
 	skip_past_newline
-- 
2.39.1

[PATCH 4/8] Remove the paramstuff word

[Tom Tromey]

The chew "paramstuff" word has been a no-op since:

    commit c58b95236ce4c9345c4fa76e7ef16762e5229380
    Author: Alan Modra <amodra@gmail.com>
    Date:   Sun Jun 29 10:06:40 2003 +0000

	Convert to C90 and a few tweaks.

Remove it and its one use.

2023-02-07  Tom Tromey  <tom@tromey.com>

	* doc/proto.str (SYNOPSIS): Don't use paramstuff.
	* doc/chew.c (paramstuff): Remove.
	(main): Don't add paramstuff intrinsic.
---
 bfd/ChangeLog     |  6 ++++
 bfd/doc/chew.c    | 80 -----------------------------------------------
 bfd/doc/proto.str |  1 -
 3 files changed, 6 insertions(+), 81 deletions(-)

diff --git a/bfd/doc/chew.c b/bfd/doc/chew.c
index 8ada35fdcec..df522225b3f 100644
--- a/bfd/doc/chew.c
+++ b/bfd/doc/chew.c
@@ -65,7 +65,6 @@
 	exit - fn chew_exit
 	swap
 	outputdots - strip out lines without leading dots
-	paramstuff - convert full declaration into "PARAMS" form if not already
 	maybecatstr - do catstr if internal_mode == internal_wanted, discard
 		value in any case
 	translatecomments - turn {* and *} into comment delimiters
@@ -453,84 +452,6 @@ print_stack_level (void)
   pc++;
 }
 
-/* turn:
-     foobar name(stuff);
-   into:
-     foobar
-     name PARAMS ((stuff));
-   and a blank line.
- */
-
-static void
-paramstuff (void)
-{
-  unsigned int openp;
-  unsigned int fname;
-  unsigned int idx;
-  unsigned int len;
-  string_type out;
-  init_string (&out);
-
-#define NO_PARAMS 1
-
-  /* Make sure that it's not already param'd or proto'd.  */
-  if (NO_PARAMS
-      || find (tos, "PARAMS") || find (tos, "PROTO") || !find (tos, "("))
-    {
-      catstr (&out, tos);
-    }
-  else
-    {
-      /* Find the open paren.  */
-      for (openp = 0; at (tos, openp) != '(' && at (tos, openp); openp++)
-	;
-
-      fname = openp;
-      /* Step back to the fname.  */
-      fname--;
-      while (fname && isspace ((unsigned char) at (tos, fname)))
-	fname--;
-      while (fname
-	     && !isspace ((unsigned char) at (tos,fname))
-	     && at (tos,fname) != '*')
-	fname--;
-
-      fname++;
-
-      /* Output type, omitting trailing whitespace character(s), if
-         any.  */
-      for (len = fname; 0 < len; len--)
-	{
-	  if (!isspace ((unsigned char) at (tos, len - 1)))
-	    break;
-	}
-      for (idx = 0; idx < len; idx++)
-	catchar (&out, at (tos, idx));
-
-      cattext (&out, "\n");	/* Insert a newline between type and fnname */
-
-      /* Output function name, omitting trailing whitespace
-         character(s), if any.  */
-      for (len = openp; 0 < len; len--)
-	{
-	  if (!isspace ((unsigned char) at (tos, len - 1)))
-	    break;
-	}
-      for (idx = fname; idx < len; idx++)
-	catchar (&out, at (tos, idx));
-
-      cattext (&out, " PARAMS (");
-
-      for (idx = openp; at (tos, idx) && at (tos, idx) != ';'; idx++)
-	catchar (&out, at (tos, idx));
-
-      cattext (&out, ");\n\n");
-    }
-  overwrite_string (tos, &out);
-  pc++;
-
-}
-
 /* turn {*
    and *} into comments */
 
@@ -1504,7 +1425,6 @@ main (int ac, char *av[])
   add_intrinsic ("exit", chew_exit);
   add_intrinsic ("swap", swap);
   add_intrinsic ("outputdots", outputdots);
-  add_intrinsic ("paramstuff", paramstuff);
   add_intrinsic ("maybecatstr", maybecatstr);
   add_intrinsic ("translatecomments", translatecomments);
   add_intrinsic ("kill_bogus_lines", kill_bogus_lines);
diff --git a/bfd/doc/proto.str b/bfd/doc/proto.str
index a9533526d6c..7bebbc26f8f 100644
--- a/bfd/doc/proto.str
+++ b/bfd/doc/proto.str
@@ -19,7 +19,6 @@
 : SYNOPSIS
 	skip_past_newline
 	get_stuff_in_command	
-	paramstuff
 	indent
 	maybecatstr
 ;
-- 
2.39.1

[PATCH 5/8] Use intptr_t rather than long in chew

[Tom Tromey]

To implement variables in chew, it's convenient to have a
pointer-sized integer on the stack.  To this end, use intptr_t rather
than long.

2023-02-07  Tom Tromey  <tom@tromey.com>

	* doc/chew.c (pcu) <l>: Now intptr_t.
	(internal_mode, istack, isp): Likewise.
	(bang, atsign): Use intptr_t.
---
 bfd/ChangeLog  |  6 ++++++
 bfd/doc/chew.c | 13 +++++++------
 2 files changed, 13 insertions(+), 6 deletions(-)

diff --git a/bfd/doc/chew.c b/bfd/doc/chew.c
index df522225b3f..510a8e968c5 100644
--- a/bfd/doc/chew.c
+++ b/bfd/doc/chew.c
@@ -85,6 +85,7 @@
 #include <ctype.h>
 #include <stdlib.h>
 #include <string.h>
+#include <stdint.h>
 
 #define DEF_SIZE 5000
 #define STACK 50
@@ -105,7 +106,7 @@ typedef union
   void (*f) (void);
   struct dict_struct *e;
   char *s;
-  long l;
+  intptr_t l;
 } pcu;
 
 typedef struct dict_struct
@@ -118,7 +119,7 @@ typedef struct dict_struct
 } dict_type;
 
 int internal_wanted;
-int internal_mode;
+intptr_t internal_mode;
 
 int warning;
 
@@ -128,8 +129,8 @@ string_type *tos;
 unsigned int idx = 0; /* Pos in input buffer */
 string_type *ptr; /* and the buffer */
 
-long istack[STACK];
-long *isp = &istack[0];
+intptr_t istack[STACK];
+intptr_t *isp = &istack[0];
 
 dict_type *root;
 
@@ -1300,7 +1301,7 @@ compile (char *string)
 static void
 bang (void)
 {
-  *(long *) ((isp[0])) = isp[-1];
+  *(intptr_t *) ((isp[0])) = isp[-1];
   isp -= 2;
   icheck_range ();
   pc++;
@@ -1309,7 +1310,7 @@ bang (void)
 static void
 atsign (void)
 {
-  isp[0] = *(long *) (isp[0]);
+  isp[0] = *(intptr_t *) (isp[0]);
   pc++;
 }
 
-- 
2.39.1

[PATCH 6/8] Change internalmode to be an intrinsic variable

[Tom Tromey]

Currently, internalmode is a special word to set an internal state
variable.  Because this series adds variables anyway, change this to
be a variable instead.

I saw some commits in the history that made sure that chew did not
leak memory, so I put some extra effort into trying to handle this for
variables as well.

2023-02-07  Tom Tromey  <tom@tromey.com>

	* doc/proto.str (external, internal, ifinternal, ENUMEQ, ENUMDOC):
	Update.
	* doc/chew.c (internalmode): Remove.
	(add_intrinsic_variable): New function.
	(main): Add internalmode as intrinsic.
	(internal_mode): Remove global.
	(maybecatstr): Update.
	(free_words): Free variables.
---
 bfd/ChangeLog     | 11 +++++++++++
 bfd/doc/chew.c    | 46 +++++++++++++++++++++++++++++++++-------------
 bfd/doc/proto.str | 12 ++++++------
 3 files changed, 50 insertions(+), 19 deletions(-)

diff --git a/bfd/doc/chew.c b/bfd/doc/chew.c
index 510a8e968c5..b17b20a183f 100644
--- a/bfd/doc/chew.c
+++ b/bfd/doc/chew.c
@@ -70,12 +70,13 @@
 	translatecomments - turn {* and *} into comment delimiters
 	kill_bogus_lines - get rid of extra newlines
 	indent
-	internalmode - pop from integer stack, set `internalmode' to that value
 	print_stack_level - print current stack depth to stderr
 	strip_trailing_newlines - go ahead, guess...
 	[quoted string] - push string onto string stack
 	[word starting with digit] - push atol(str) onto integer stack
 
+	internalmode - the internalmode variable (evaluates to address)
+
    A command must be all upper-case, and alone on a line.
 
    Foo.  */
@@ -119,7 +120,7 @@ typedef struct dict_struct
 } dict_type;
 
 int internal_wanted;
-intptr_t internal_mode;
+intptr_t *internal_mode;
 
 int warning;
 
@@ -376,6 +377,14 @@ push_number (void)
   pc++;
 }
 
+/* This is a wrapper for push_number just so we can correctly free the
+   variable at the end.  */
+static void
+push_variable (void)
+{
+  push_number ();
+}
+
 static void
 push_text (void)
 {
@@ -993,19 +1002,10 @@ skip_past_newline (void)
   pc++;
 }
 
-static void
-internalmode (void)
-{
-  internal_mode = *(isp);
-  isp--;
-  icheck_range ();
-  pc++;
-}
-
 static void
 maybecatstr (void)
 {
-  if (internal_wanted == internal_mode)
+  if (internal_wanted == *internal_mode)
     {
       catstr (tos - 1, tos);
     }
@@ -1138,6 +1138,11 @@ free_words (void)
 		free (ptr->code[i + 1].s - 1);
 		++i;
 	      }
+	    else if (ptr->code[i].f == push_variable)
+	      {
+		free ((void *) ptr->code[i + 1].l);
+		++i;
+	      }
 	  free (ptr->code);
 	}
       next = ptr->next;
@@ -1217,6 +1222,18 @@ add_intrinsic (char *name, void (*func) (void))
   add_to_definition (new_d, p);
 }
 
+static void
+add_intrinsic_variable (char *name, intptr_t *loc)
+{
+  dict_type *new_d = newentry (xstrdup (name));
+  pcu p = { push_variable };
+  add_to_definition (new_d, p);
+  p.l = (intptr_t) loc;
+  add_to_definition (new_d, p);
+  p.f = 0;
+  add_to_definition (new_d, p);
+}
+
 void
 compile (char *string)
 {
@@ -1430,10 +1447,13 @@ main (int ac, char *av[])
   add_intrinsic ("translatecomments", translatecomments);
   add_intrinsic ("kill_bogus_lines", kill_bogus_lines);
   add_intrinsic ("indent", indent);
-  add_intrinsic ("internalmode", internalmode);
   add_intrinsic ("print_stack_level", print_stack_level);
   add_intrinsic ("strip_trailing_newlines", strip_trailing_newlines);
 
+  internal_mode = xmalloc (sizeof (intptr_t));
+  *internal_mode = 0;
+  add_intrinsic_variable ("internalmode", internal_mode);
+
   /* Put a nl at the start.  */
   catchar (&buffer, '\n');
 
diff --git a/bfd/doc/proto.str b/bfd/doc/proto.str
index 7bebbc26f8f..5206f7f3877 100644
--- a/bfd/doc/proto.str
+++ b/bfd/doc/proto.str
@@ -34,16 +34,16 @@
 	ignore ;
 
 : external
-	0 internalmode ignore ;
+	0 internalmode ! ignore ;
 
 : internal 
-	1 internalmode ignore ;
+	1 internalmode ! ignore ;
 
 - input stack { a b } output b if internal, a if external
 : ifinternal
-	"" swap 1 internalmode maybecatstr
+	"" swap 1 internalmode ! maybecatstr
 	swap
-	"" swap 0 internalmode maybecatstr
+	"" swap 0 internalmode ! maybecatstr
 	catstr
 	;
 
@@ -123,7 +123,7 @@
 	catstr
 	copy_past_newline
 	catstr
-	"" swap 0 internalmode maybecatstr
+	"" swap 0 internalmode ! maybecatstr
 	;
 : ENUMEQX ENUMEQ catstr ;
 : ENUMDOC
@@ -133,7 +133,7 @@
 	"\n{* " swap catstr "  *}\n" catstr
 	translatecomments
 	- discard it if we're doing internal mode
-	"" swap 0 internalmode maybecatstr
+	"" swap 0 internalmode ! maybecatstr
 	swap
 	catstr catstr
 	;
-- 
2.39.1

[PATCH 7/8] Use @deftypefn in chew output

[Tom Tromey]

When reading the BFD info manual, function definitions looked very
strange to me:

    *Synopsis*
	 long bfd_get_mtime (bfd *abfd);
       *Description*
    Return the file modification time (as read from the file system, or from
    the archive header for archive members).

The *Synopsis* and *Description* text in particular is very un-info-like.

To fix this, I tried removing the *Synopsis* text and having FUNCTION
use @deftypefn instead.  However, this ended up requiring some new
state, because SYNOPSIS can appear without FUNCTION.  This in turn
required "catstrif" (I considered adding FORTH-style if-else-then, but
in the end decided on an ad hoc approach).

After this the result looks like:

 -- Function: long bfd_get_mtime (bfd *abfd);
     Return the file modification time (as read from the file system, or
     from the archive header for archive members).

This patch also reorders a few documentation comments to ensure that
SYNOPSIS comes before DESCRIPTION.  This is the more common style and
is also now required by doc.str.

bfd/ChangeLog
2023-02-07  Tom Tromey  <tom@tromey.com>

	* syms.c (bfd_decode_symclass, bfd_is_undefined_symclass)
	(bfd_symbol_info): Reorder documentation comment.
	* doc/doc.str (synopsis_seen): New variable.
	(SYNOPSIS): Set synopsis_seen.  Emit @deftypefn.
	(DESCRIPTION): Use synopsis_seen.
	* doc/chew.c (catstrif): New function.
	(main): Add catstrif intrinsic.
	(compile): Recognize "variable" command.
---
 bfd/ChangeLog   | 11 +++++++++++
 bfd/doc/chew.c  | 30 ++++++++++++++++++++++++++++++
 bfd/doc/doc.str | 14 +++++++++-----
 bfd/syms.c      | 18 +++++++++---------
 4 files changed, 59 insertions(+), 14 deletions(-)

diff --git a/bfd/doc/chew.c b/bfd/doc/chew.c
index b17b20a183f..19e3781bdda 100644
--- a/bfd/doc/chew.c
+++ b/bfd/doc/chew.c
@@ -31,6 +31,9 @@
    You define new words thus:
    : <newword> <oldwords> ;
 
+   Variables are defined using:
+   variable NAME
+
 */
 
 /* Primitives provided by the program:
@@ -67,6 +70,7 @@
 	outputdots - strip out lines without leading dots
 	maybecatstr - do catstr if internal_mode == internal_wanted, discard
 		value in any case
+	catstrif - do catstr if top of integer stack is nonzero
 	translatecomments - turn {* and *} into comment delimiters
 	kill_bogus_lines - get rid of extra newlines
 	indent
@@ -1015,6 +1019,20 @@ maybecatstr (void)
   pc++;
 }
 
+static void
+catstrif (void)
+{
+  int cond = isp[0];
+  isp--;
+  icheck_range ();
+  if (cond)
+    catstr (tos - 1, tos);
+  delete_string (tos);
+  tos--;
+  check_range ();
+  pc++;
+}
+
 char *
 nextword (char *string, char **word)
 {
@@ -1307,6 +1325,17 @@ compile (char *string)
 	  free (word);
 	  string = nextword (string, &word);
 	}
+      else if (strcmp (word, "variable") == 0)
+	{
+	  free (word);
+	  string = nextword (string, &word);
+	  if (!string)
+	    continue;
+	  intptr_t *loc = xmalloc (sizeof (intptr_t));
+	  *loc = 0;
+	  add_intrinsic_variable (word, loc);
+	  string = nextword (string, &word);
+	}
       else
 	{
 	  fprintf (stderr, "syntax error at %s\n", string - 1);
@@ -1444,6 +1473,7 @@ main (int ac, char *av[])
   add_intrinsic ("swap", swap);
   add_intrinsic ("outputdots", outputdots);
   add_intrinsic ("maybecatstr", maybecatstr);
+  add_intrinsic ("catstrif", catstrif);
   add_intrinsic ("translatecomments", translatecomments);
   add_intrinsic ("kill_bogus_lines", kill_bogus_lines);
   add_intrinsic ("indent", indent);
diff --git a/bfd/doc/doc.str b/bfd/doc/doc.str
index 6019b7ccfdb..4576d497521 100644
--- a/bfd/doc/doc.str
+++ b/bfd/doc/doc.str
@@ -16,6 +16,9 @@
 -  along with this program; if not, write to the Free Software
 -  Foundation, Inc., 51 Franklin Street - Fifth Floor, Boston, MA 02110-1301, USA.
 
+-  True if SYNOPSIS was seen.
+variable synopsis_seen
+
 : DOCDD
 	skip_past_newline
 	get_stuff_in_command kill_bogus_lines catstr
@@ -48,14 +51,12 @@
 
 : SYNOPSIS
 	skip_past_newline
-	"@strong{Synopsis}\n" catstr
-	"@example\n" catstr
+	1 synopsis_seen !
+	"@deftypefn {Function} " catstr
 	get_stuff_in_command  
 	kill_bogus_lines
 	indent
 	catstr
-	"@end example\n" catstr
-
 	;
 
 : func
@@ -118,7 +119,10 @@
 
 	
 : DESCRIPTION 
-	"@strong{Description}@*\n" catstr subhead ;
+	subhead
+	"@end deftypefn\n" synopsis_seen @ catstrif
+	0 synopsis_seen !
+	;
 
 : RETURNS
 	"@strong{Returns}@*\n" catstr subhead ;
diff --git a/bfd/syms.c b/bfd/syms.c
index a26aeb4cb8b..c460e377723 100644
--- a/bfd/syms.c
+++ b/bfd/syms.c
@@ -642,12 +642,12 @@ decode_section_type (const struct bfd_section *section)
 FUNCTION
 	bfd_decode_symclass
 
+SYNOPSIS
+	int bfd_decode_symclass (asymbol *symbol);
+
 DESCRIPTION
 	Return a character corresponding to the symbol
 	class of @var{symbol}, or '?' for an unknown class.
-
-SYNOPSIS
-	int bfd_decode_symclass (asymbol *symbol);
 */
 int
 bfd_decode_symclass (asymbol *symbol)
@@ -725,13 +725,13 @@ bfd_decode_symclass (asymbol *symbol)
 FUNCTION
 	bfd_is_undefined_symclass
 
+SYNOPSIS
+	bool bfd_is_undefined_symclass (int symclass);
+
 DESCRIPTION
 	Returns non-zero if the class symbol returned by
 	bfd_decode_symclass represents an undefined symbol.
 	Returns zero otherwise.
-
-SYNOPSIS
-	bool bfd_is_undefined_symclass (int symclass);
 */
 
 bool
@@ -744,13 +744,13 @@ bfd_is_undefined_symclass (int symclass)
 FUNCTION
 	bfd_symbol_info
 
+SYNOPSIS
+	void bfd_symbol_info (asymbol *symbol, symbol_info *ret);
+
 DESCRIPTION
 	Fill in the basic info about symbol that nm needs.
 	Additional info may be added by the back-ends after
 	calling this function.
-
-SYNOPSIS
-	void bfd_symbol_info (asymbol *symbol, symbol_info *ret);
 */
 
 void
-- 
2.39.1

Re: [PATCH 7/8] Use @deftypefn in chew output

[Simon Marchi]

On 2/8/23 02:17, Tom Tromey wrote:
> When reading the BFD info manual, function definitions looked very
> strange to me:
> 
>     *Synopsis*
> 	 long bfd_get_mtime (bfd *abfd);
>        *Description*
>     Return the file modification time (as read from the file system, or from
>     the archive header for archive members).
> 
> The *Synopsis* and *Description* text in particular is very un-info-like.
> 
> To fix this, I tried removing the *Synopsis* text and having FUNCTION
> use @deftypefn instead.  However, this ended up requiring some new
> state, because SYNOPSIS can appear without FUNCTION.  This in turn
> required "catstrif" (I considered adding FORTH-style if-else-then, but
> in the end decided on an ad hoc approach).
> 
> After this the result looks like:
> 
>  -- Function: long bfd_get_mtime (bfd *abfd);
>      Return the file modification time (as read from the file system, or
>      from the archive header for archive members).
> 
> This patch also reorders a few documentation comments to ensure that
> SYNOPSIS comes before DESCRIPTION.  This is the more common style and
> is also now required by doc.str.
> 
> bfd/ChangeLog
> 2023-02-07  Tom Tromey  <tom@tromey.com>
> 
> 	* syms.c (bfd_decode_symclass, bfd_is_undefined_symclass)
> 	(bfd_symbol_info): Reorder documentation comment.
> 	* doc/doc.str (synopsis_seen): New variable.
> 	(SYNOPSIS): Set synopsis_seen.  Emit @deftypefn.
> 	(DESCRIPTION): Use synopsis_seen.
> 	* doc/chew.c (catstrif): New function.
> 	(main): Add catstrif intrinsic.
> 	(compile): Recognize "variable" command.

Hi Tom,

Starting with this commit, I see this when building (with ASan enabled):

  GEN      doc/aoutx.stamp

=================================================================
==45648==ERROR: LeakSanitizer: detected memory leaks

Direct leak of 14 byte(s) in 1 object(s) allocated from:
    #0 0x7f193eebfa89 in __interceptor_malloc /usr/src/debug/gcc/gcc/libsanitizer/asan/asan_malloc_linux.cpp:69
    #1 0x55a292052ba0 in xmalloc /home/smarchi/src/binutils-gdb/bfd/doc/chew.c:158
    #2 0x55a29205678a in nextword /home/smarchi/src/binutils-gdb/bfd/doc/chew.c:1090
    #3 0x55a292057c1e in compile /home/smarchi/src/binutils-gdb/bfd/doc/chew.c:1331
    #4 0x55a292058b8b in main /home/smarchi/src/binutils-gdb/bfd/doc/chew.c:1511
    #5 0x7f193ec3c78f  (/usr/lib/libc.so.6+0x2378f)

Simon

Re: [PATCH 7/8] Use @deftypefn in chew output

[Tom Tromey]

>>>>> "Simon" == Simon Marchi <simon.marchi@polymtl.ca> writes:

Simon> Starting with this commit, I see this when building (with ASan enabled):

Oops, sorry about that.  This patch should fix it.  Let me know what you
think.

Tom

commit 482e9a3e3a3aee643d671d2594be709446cef065
Author: Tom Tromey <tom@tromey.com>
Date:   Wed Feb 15 16:09:35 2023 -0700

    Avoid memory leak in chew
    
    An earlier patch of mine introduced a memory leak in chew.  The bug
    was that the new "variable" word didn't free the following word.  This
    patch fixes it by arranging to transfer ownership of the name to the
    variable itself.
    
    bfd/ChangeLog
    2023-02-15  Tom Tromey  <tom@tromey.com>
    
            * doc/chew.c (add_variable): New function, from
            add_intrinsic_variable.
            (add_intrinsic_variable): Call add_variable.
            (compile): Call add_variable.

diff --git a/bfd/ChangeLog b/bfd/ChangeLog
index e160e4472df..5bf3e9f0919 100644
--- a/bfd/ChangeLog
+++ b/bfd/ChangeLog
@@ -1,3 +1,10 @@
+2023-02-15  Tom Tromey  <tom@tromey.com>
+
+	* doc/chew.c (add_variable): New function, from
+	add_intrinsic_variable.
+	(add_intrinsic_variable): Call add_variable.
+	(compile): Call add_variable.
+
 2023-02-07  Tom Tromey  <tom@tromey.com>
 
 	* bfd.c, cache.c, compress.c, opncls.c: Remove RETURNS from
diff --git a/bfd/doc/chew.c b/bfd/doc/chew.c
index 19e3781bdda..cd399697abd 100644
--- a/bfd/doc/chew.c
+++ b/bfd/doc/chew.c
@@ -1241,9 +1241,9 @@ add_intrinsic (char *name, void (*func) (void))
 }
 
 static void
-add_intrinsic_variable (char *name, intptr_t *loc)
+add_variable (char *name, intptr_t *loc)
 {
-  dict_type *new_d = newentry (xstrdup (name));
+  dict_type *new_d = newentry (name);
   pcu p = { push_variable };
   add_to_definition (new_d, p);
   p.l = (intptr_t) loc;
@@ -1252,6 +1252,12 @@ add_intrinsic_variable (char *name, intptr_t *loc)
   add_to_definition (new_d, p);
 }
 
+static void
+add_intrinsic_variable (const char *name, intptr_t *loc)
+{
+  add_variable (xstrdup (name), loc);
+}
+
 void
 compile (char *string)
 {
@@ -1333,7 +1339,7 @@ compile (char *string)
 	    continue;
 	  intptr_t *loc = xmalloc (sizeof (intptr_t));
 	  *loc = 0;
-	  add_intrinsic_variable (word, loc);
+	  add_variable (word, loc);
 	  string = nextword (string, &word);
 	}
       else

Re: [PATCH 7/8] Use @deftypefn in chew output

[Simon Marchi]

On 2/15/23 18:11, Tom Tromey wrote:
>>>>>> "Simon" == Simon Marchi <simon.marchi@polymtl.ca> writes:
> 
> Simon> Starting with this commit, I see this when building (with ASan enabled):
> 
> Oops, sorry about that.  This patch should fix it.  Let me know what you
> think.
> 
> Tom

It works for me, thanks!

Simon

Re: [PATCH 7/8] Use @deftypefn in chew output

[Alan Modra]

On Wed, Feb 15, 2023 at 08:29:55PM -0500, Simon Marchi via Binutils wrote:
> 
> 
> On 2/15/23 18:11, Tom Tromey wrote:
> >>>>>> "Simon" == Simon Marchi <simon.marchi@polymtl.ca> writes:
> > 
> > Simon> Starting with this commit, I see this when building (with ASan enabled):
> > 
> > Oops, sorry about that.  This patch should fix it.  Let me know what you
> > think.
> > 
> > Tom
> 
> It works for me, thanks!
> 
> Simon

I've pushed the patch now.

-- 
Alan Modra
Australia Development Lab, IBM

[PATCH 8/8] Remove RETURNS from BFD chew comments

[Tom Tromey]

When reading the BFD manual, I noticed text like this:

     -- Function: bool bfd_close (bfd *abfd);
	 Close a BFD. If the BFD was open for writing, then pending
	 operations are completed and the file written out and closed.  If
    ...
       *Returns*
    'TRUE' is returned if all is ok, otherwise 'FALSE'.

The *Returns*, like the *Synopsis* in the earlier patch, is
un-info-like.  It's also used inconsistently.

This patch removes all the uses of the RETURNS word and removes it
entirely from the chew scripts.  Now this example reads:

     -- Function: bool bfd_close (bfd *abfd);
	 Close a BFD. If the BFD was open for writing, then pending
	 operations are completed and the file written out and closed.  If
    ...
	 'TRUE' is returned if all is ok, otherwise 'FALSE'.

In a few cases I had to slightly reword the comment.  There were also
a couple of cases where there was redundant text.  In these cases I
just dropped the RETURNS copy.

2023-02-07  Tom Tromey  <tom@tromey.com>

	* bfd.c, cache.c, compress.c, opncls.c: Remove RETURNS from
	documentation comments.
	* doc/doc.str, doc/proto.str (RETURNS): Remove.
---
 bfd/ChangeLog     |  6 ++++++
 bfd/bfd.c         |  9 --------
 bfd/cache.c       |  2 --
 bfd/compress.c    |  3 ---
 bfd/doc/doc.str   |  3 ---
 bfd/doc/proto.str |  1 -
 bfd/opncls.c      | 53 ++++++++++++++++++-----------------------------
 7 files changed, 26 insertions(+), 51 deletions(-)

diff --git a/bfd/bfd.c b/bfd/bfd.c
index c59e31d99e2..3624bfbc9a5 100644
--- a/bfd/bfd.c
+++ b/bfd/bfd.c
@@ -1841,7 +1841,6 @@ DESCRIPTION
 	header.  Use bfd_arch_bits_per_address for number of bits in
 	the architecture address.
 
-RETURNS
 	Returns the arch size in bits if known, <<-1>> otherwise.
 */
 
@@ -1869,7 +1868,6 @@ DESCRIPTION
 	return an address sign extended to fill a bfd_vma when this is
 	the case.
 
-RETURNS
 	Returns <<1>> if the target architecture is known to sign
 	extend addresses, <<0>> if the target architecture is known to
 	not sign extend addresses, and <<-1>> otherwise.
@@ -1921,7 +1919,6 @@ SYNOPSIS
 DESCRIPTION
 	Make @var{vma} the entry point of output BFD @var{abfd}.
 
-RETURNS
 	Returns <<TRUE>> on success, <<FALSE>> otherwise.
 */
 
@@ -2485,9 +2482,6 @@ SYNOPSIS
 DESCRIPTION
 	Returns the maximum page size, in bytes, as determined by
 	emulation.
-
-RETURNS
-	Returns the maximum page size in bytes for ELF, 0 otherwise.
 */
 
 bfd_vma
@@ -2513,9 +2507,6 @@ SYNOPSIS
 DESCRIPTION
 	Returns the common page size, in bytes, as determined by
 	emulation.
-
-RETURNS
-	Returns the common page size in bytes for ELF, 0 otherwise.
 */
 
 bfd_vma
diff --git a/bfd/cache.c b/bfd/cache.c
index b64b9744c4b..ab36c8506bd 100644
--- a/bfd/cache.c
+++ b/bfd/cache.c
@@ -521,7 +521,6 @@ DESCRIPTION
 	Remove the BFD @var{abfd} from the cache. If the attached file is open,
 	then close it too.
 
-RETURNS
 	<<FALSE>> is returned if closing the file fails, <<TRUE>> is
 	returned if all is well.
 */
@@ -550,7 +549,6 @@ DESCRIPTION
 	Remove all BFDs from the cache. If the attached file is open,
 	then close it too.
 
-RETURNS
 	<<FALSE>> is returned if closing one of the file fails, <<TRUE>> is
 	returned if all is well.
 */
diff --git a/bfd/compress.c b/bfd/compress.c
index 2cf8a6c28c9..43bdb9ebf44 100644
--- a/bfd/compress.c
+++ b/bfd/compress.c
@@ -263,9 +263,6 @@ SYNOPSIS
 
 DESCRIPTION
 	Return the size of the compression header of SEC in ABFD.
-
-RETURNS
-	Return the size of the compression header in bytes.
 */
 
 int
diff --git a/bfd/doc/doc.str b/bfd/doc/doc.str
index 4576d497521..2a0953a3ece 100644
--- a/bfd/doc/doc.str
+++ b/bfd/doc/doc.str
@@ -124,9 +124,6 @@ variable synopsis_seen
 	0 synopsis_seen !
 	;
 
-: RETURNS
-	"@strong{Returns}@*\n" catstr subhead ;
-
 : INTERNAL_FUNCTION
 	func ;
 
diff --git a/bfd/doc/proto.str b/bfd/doc/proto.str
index 5206f7f3877..3b776736067 100644
--- a/bfd/doc/proto.str
+++ b/bfd/doc/proto.str
@@ -144,7 +144,6 @@
 : INTERNAL_DEFINITION internal ;
 : DESCRIPTION ignore ;
 : FUNCTION external ;
-: RETURNS ignore ;
 : TYPEDEF external ;
 : INTERNAL_FUNCTION internal ;
 : INTERNAL internal ;
diff --git a/bfd/opncls.c b/bfd/opncls.c
index 6ae3af054e4..9ee032c4ac5 100644
--- a/bfd/opncls.c
+++ b/bfd/opncls.c
@@ -798,7 +798,6 @@ DESCRIPTION
 	The file descriptor associated with the BFD is closed (even
 	if it was passed in to BFD by <<bfd_fdopenr>>).
 
-RETURNS
 	<<TRUE>> is returned if all is ok, otherwise <<FALSE>>.
 */
 
@@ -829,7 +828,6 @@ DESCRIPTION
 
 	All memory attached to the BFD is released.
 
-RETURNS
 	<<TRUE>> is returned if all is ok, otherwise <<FALSE>>.
 */
 
@@ -903,7 +901,6 @@ DESCRIPTION
 	by converting the BFD to BFD_IN_MEMORY.  It's assumed that
 	you will call <<bfd_make_readable>> on this bfd later.
 
-RETURNS
 	<<TRUE>> is returned if all is ok, otherwise <<FALSE>>.
 */
 
@@ -949,7 +946,6 @@ DESCRIPTION
 	contents out to the memory buffer, then reversing the
 	direction.
 
-RETURNS
 	<<TRUE>> is returned if all is ok, otherwise <<FALSE>>.  */
 
 bool
@@ -1096,7 +1092,6 @@ DESCRIPTION
 	Advances the previously computed @var{crc} value by computing
 	and adding in the crc32 for @var{len} bytes of @var{buf}.
 
-RETURNS
 	Return the updated CRC32 value.
 */
 
@@ -1184,11 +1179,10 @@ DESCRIPTION
 	this routine is used as a @code{get_func_type} function, but it
 	is expected to be an unsigned long pointer.
 
-RETURNS
-	The filename of the associated debug information file, or NULL
-	if there is no such file.  If the filename was found then the
-	contents of @var{crc32_out} are updated to hold the corresponding
-	CRC32 value for the file.
+	Returns the filename of the associated debug information file,
+	or NULL if there is no such file.  If the filename was found
+	then the contents of @var{crc32_out} are updated to hold the
+	corresponding CRC32 value for the file.
 
 	The returned filename is allocated with @code{malloc}; freeing
 	it is the responsibility of the caller.
@@ -1250,11 +1244,10 @@ DESCRIPTION
 	Extracts the filename and CRC32 value for any separate debug
 	information file associated with @var{abfd}.
 
-RETURNS
-	The filename of the associated debug information file, or NULL
-	if there is no such file.  If the filename was found then the
-	contents of @var{crc32_out} are updated to hold the corresponding
-	CRC32 value for the file.
+	Returns the filename of the associated debug information file,
+	or NULL if there is no such file.  If the filename was found
+	then the contents of @var{crc32_out} are updated to hold the
+	corresponding CRC32 value for the file.
 
 	The returned filename is allocated with @code{malloc}; freeing
 	it is the responsibility of the caller.
@@ -1422,7 +1415,6 @@ DESCRIPTION
 	functions.  It is generally used to implement build-id-like
 	matching in the callback functions.
 
-RETURNS
 	Returns the filename of the first file to be found which
 	receives a TRUE result from the @var{check} function.
 	Returns NULL if no valid file could be found.
@@ -1606,10 +1598,10 @@ DESCRIPTION
 	If @var{dir} is NULL, the search will take place starting at
 	the current directory.
 
-RETURNS
-	<<NULL>> on any errors or failure to locate the .debug file,
-	otherwise a pointer to a heap-allocated string containing the
-	filename.  The caller is responsible for freeing this string.
+	Returns <<NULL>> on any errors or failure to locate the .debug
+	file, otherwise a pointer to a heap-allocated string
+	containing the filename.  The caller is responsible for
+	freeing this string.
 */
 
 char *
@@ -1655,10 +1647,10 @@ DESCRIPTION
 	If @var{dir} is NULL, the search will take place starting at
 	the current directory.
 
-RETURNS
-	<<NULL>> on any errors or failure to locate the debug file,
-	otherwise a pointer to a heap-allocated string containing the
-	filename.  The caller is responsible for freeing this string.
+	Returns <<NULL>> on any errors or failure to locate the debug
+	file, otherwise a pointer to a heap-allocated string
+	containing the filename.  The caller is responsible for
+	freeing this string.
 */
 
 char *
@@ -1683,7 +1675,6 @@ DESCRIPTION
 	section is sized to be big enough to contain a link to the specified
 	@var{filename}.
 
-RETURNS
 	A pointer to the new section is returned if all is ok.  Otherwise
 	<<NULL>> is returned and bfd_error is set.
 */
@@ -1751,7 +1742,6 @@ DESCRIPTION
 	specified @var{filename}.  The filename should be relative to the
 	current directory.
 
-RETURNS
 	<<TRUE>> is returned if all is ok.  Otherwise <<FALSE>> is returned
 	and bfd_error is set.
 */
@@ -1840,7 +1830,6 @@ DESCRIPTION
 	for it, using memory allocated to @var{abfd}, and this is then
 	attached to the @var{abfd}.
 
-RETURNS
 	Returns a pointer to the build-id structure if a build-id could be
 	found.  If no build-id is found NULL is returned and error code is
 	set.
@@ -1941,7 +1930,6 @@ DESCRIPTION
 	from it.  The path is computed as .build-id/NN/NN+NN.debug where
 	NNNN+NN is the build-id value as a hexadecimal string.
 
-RETURNS
 	Returns the constructed filename or NULL upon error.
 	It is the caller's responsibility to free the memory used to hold the
 	filename.
@@ -2003,7 +1991,6 @@ DESCRIPTION
 	Checks to see if @var{name} is a readable file and if its build-id
 	matches @var{buildid}.
 
-RETURNS
 	Returns TRUE if the file exists, is readable, and contains a
 	build-id which matches the build-id pointed at by
 	@var{build_id_p} (which is really a @code{struct bfd_build_id **}).
@@ -2070,10 +2057,10 @@ DESCRIPTION
 	If @var{dir} is NULL, the search will take place starting at
 	the current directory.
 
-RETURNS
-	<<NULL>> on any errors or failure to locate the debug file,
-	otherwise a pointer to a heap-allocated string containing the
-	filename.  The caller is responsible for freeing this string.
+	Returns <<NULL>> on any errors or failure to locate the debug
+	file, otherwise a pointer to a heap-allocated string
+	containing the filename.  The caller is responsible for
+	freeing this string.
 */
 
 char *
-- 
2.39.1

Re: [PATCH 0/8] Make the BFD info manual a bit prettier

[Nick Clifton]

Hi Tom,

> I noticed some oddities in the BFD info manual (see patch 7 and patch
> 8 for details).  While trying to fix these, I found a number of other
> things that could be cleaned up a bit, and this series is the result.
> 
> I tested this by rebuilding with --enable-maintainer-mode and diffing
> the header files to make sure they didn't change.  Then I inspected
> the manual, well, manually.

Patch series approved - please apply.

Thanks for fixing these issues.

Cheers
   Nick

Re: [PATCH 0/8] Make the BFD info manual a bit prettier

[Tom Tromey]

>> I noticed some oddities in the BFD info manual (see patch 7 and patch
>> 8 for details).  While trying to fix these, I found a number of other
>> things that could be cleaned up a bit, and this series is the result.
>> I tested this by rebuilding with --enable-maintainer-mode and diffing
>> the header files to make sure they didn't change.  Then I inspected
>> the manual, well, manually.

Nick> Patch series approved - please apply.

Nick> Thanks for fixing these issues.

Thanks for the review.  I've checked these in now.

There are still a few other issues to solve here.  Those don't look so
difficult, but I was wondering about making bigger changes here.  I have
a few queries in case you have a moment to respond.

While I like FORTH well enough, I suspect it might be nicer to just
rewrite chew in Python.  Over in gdb, we've standardized on that for all
our maintainer scripts; the main benefits are that a lot of people know
it and there are plenty of libraries, etc, to use.  What do you think of
this?

(Another option here would be to change the syntax a bit so it's more
FORTH-like... it'd be nice to be able to use some pre-existing Emacs
mode for this code, but chew is FORTH-ish without really following FORTH
syntax.)

Finally, it seems to me that it would be nicer if chew were merely a
documentation extractor.  Having it also generate source files seems
unfortunate.  For example, things like 'tags' don't work, because the
primary source code is actually in some comment somewhere.  It seems
like this could be changed so that code is just code, comments (and
maybe snippets of code) are extracted into the manual, and some of the
generated headers are turned into ordinary headers.  WDYT?

thanks,
Tom

Re: [PATCH 0/8] Make the BFD info manual a bit prettier

[Nick Clifton]

Hi Tom,

> While I like FORTH well enough, I suspect it might be nicer to just
> rewrite chew in Python. 

My first thought is - "if it ain't broke, don't fix it" - as in, what
do you gain from rewriting chew ?  Is it just so that it is easier to
maintain in the future, should bugs be encountered, or to make it easier
to add new features, or what ?

Don't get me wrong.  If there are good reasons for rewriting chew then
I am willing to listen, but if it is working as-is then I would prefer
to leave well enough alone.


> Over in gdb, we've standardized on that for all
> our maintainer scripts; the main benefits are that a lot of people know
> it and there are plenty of libraries, etc, to use.  What do you think of
> this?

It would add a new dependency for the binutils.  Currently there are no
python scripts being used to build or test the binutils.  Not that this
is necessarily a bad thing.  But if there are alternatives to using python
that would work just as well (bash scipts ?) then maybe that would be
better.


> Finally, it seems to me that it would be nicer if chew were merely a
> documentation extractor.  Having it also generate source files seems
> unfortunate.  For example, things like 'tags' don't work, because the
> primary source code is actually in some comment somewhere.  It seems
> like this could be changed so that code is just code, comments (and
> maybe snippets of code) are extracted into the manual, and some of the
> generated headers are turned into ordinary headers.  WDYT?

I am ambivalent.  I do not use 'tags' myself, so not having it work on
the generated source files is not a big deal for me.  But I can see that
it would be annoying for people who do use it.  I do worry that rewriting
this code will introduce new bugs into an area of the binutils that is
currently working just fine.

If you are passionate about this idea, then please go ahead.  But if you
have 10 other projects clamouring for your attention, then maybe leave this
one on the back-burner.

Cheers
   Nick