* [PATCH 1/8] Remove H_CFLAGS from doc/local.mk
2023-02-08 7:17 [PATCH 0/8] Make the BFD info manual a bit prettier Tom Tromey
@ 2023-02-08 7:17 ` Tom Tromey
2023-02-08 7:17 ` [PATCH 2/8] Simplify @node use in BFD documentation Tom Tromey
` (7 subsequent siblings)
8 siblings, 0 replies; 19+ messages in thread
From: Tom Tromey @ 2023-02-08 7:17 UTC (permalink / raw)
To: binutils; +Cc: 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
^ permalink raw reply [flat|nested] 19+ messages in thread
* [PATCH 2/8] Simplify @node use in BFD documentation
2023-02-08 7:17 [PATCH 0/8] Make the BFD info manual a bit prettier Tom Tromey
2023-02-08 7:17 ` [PATCH 1/8] Remove H_CFLAGS from doc/local.mk Tom Tromey
@ 2023-02-08 7:17 ` Tom Tromey
2023-03-03 8:20 ` Jan Beulich
2023-02-08 7:17 ` [PATCH 3/8] Add copyright headers to the .str files Tom Tromey
` (6 subsequent siblings)
8 siblings, 1 reply; 19+ messages in thread
From: Tom Tromey @ 2023-02-08 7:17 UTC (permalink / raw)
To: binutils; +Cc: 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
^ permalink raw reply [flat|nested] 19+ messages in thread
* Re: [PATCH 2/8] Simplify @node use in BFD documentation
2023-02-08 7:17 ` [PATCH 2/8] Simplify @node use in BFD documentation Tom Tromey
@ 2023-03-03 8:20 ` Jan Beulich
2023-03-03 23:08 ` Tom Tromey
0 siblings, 1 reply; 19+ messages in thread
From: Jan Beulich @ 2023-03-03 8:20 UTC (permalink / raw)
To: Tom Tromey; +Cc: binutils
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
^ permalink raw reply [flat|nested] 19+ messages in thread
* Re: [PATCH 2/8] Simplify @node use in BFD documentation
2023-03-03 8:20 ` Jan Beulich
@ 2023-03-03 23:08 ` Tom Tromey
2023-03-06 7:07 ` Jan Beulich
0 siblings, 1 reply; 19+ messages in thread
From: Tom Tromey @ 2023-03-03 23:08 UTC (permalink / raw)
To: Jan Beulich; +Cc: Tom Tromey, binutils
>>>>> "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
^ permalink raw reply [flat|nested] 19+ messages in thread
* Re: [PATCH 2/8] Simplify @node use in BFD documentation
2023-03-03 23:08 ` Tom Tromey
@ 2023-03-06 7:07 ` Jan Beulich
0 siblings, 0 replies; 19+ messages in thread
From: Jan Beulich @ 2023-03-06 7:07 UTC (permalink / raw)
To: Tom Tromey; +Cc: binutils
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
^ permalink raw reply [flat|nested] 19+ messages in thread
* [PATCH 3/8] Add copyright headers to the .str files
2023-02-08 7:17 [PATCH 0/8] Make the BFD info manual a bit prettier Tom Tromey
2023-02-08 7:17 ` [PATCH 1/8] Remove H_CFLAGS from doc/local.mk Tom Tromey
2023-02-08 7:17 ` [PATCH 2/8] Simplify @node use in BFD documentation Tom Tromey
@ 2023-02-08 7:17 ` Tom Tromey
2023-02-08 7:17 ` [PATCH 4/8] Remove the paramstuff word Tom Tromey
` (5 subsequent siblings)
8 siblings, 0 replies; 19+ messages in thread
From: Tom Tromey @ 2023-02-08 7:17 UTC (permalink / raw)
To: binutils; +Cc: 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
^ permalink raw reply [flat|nested] 19+ messages in thread
* [PATCH 4/8] Remove the paramstuff word
2023-02-08 7:17 [PATCH 0/8] Make the BFD info manual a bit prettier Tom Tromey
` (2 preceding siblings ...)
2023-02-08 7:17 ` [PATCH 3/8] Add copyright headers to the .str files Tom Tromey
@ 2023-02-08 7:17 ` Tom Tromey
2023-02-08 7:17 ` [PATCH 5/8] Use intptr_t rather than long in chew Tom Tromey
` (4 subsequent siblings)
8 siblings, 0 replies; 19+ messages in thread
From: Tom Tromey @ 2023-02-08 7:17 UTC (permalink / raw)
To: binutils; +Cc: 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
^ permalink raw reply [flat|nested] 19+ messages in thread
* [PATCH 5/8] Use intptr_t rather than long in chew
2023-02-08 7:17 [PATCH 0/8] Make the BFD info manual a bit prettier Tom Tromey
` (3 preceding siblings ...)
2023-02-08 7:17 ` [PATCH 4/8] Remove the paramstuff word Tom Tromey
@ 2023-02-08 7:17 ` Tom Tromey
2023-02-08 7:17 ` [PATCH 6/8] Change internalmode to be an intrinsic variable Tom Tromey
` (3 subsequent siblings)
8 siblings, 0 replies; 19+ messages in thread
From: Tom Tromey @ 2023-02-08 7:17 UTC (permalink / raw)
To: binutils; +Cc: 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
^ permalink raw reply [flat|nested] 19+ messages in thread
* [PATCH 6/8] Change internalmode to be an intrinsic variable
2023-02-08 7:17 [PATCH 0/8] Make the BFD info manual a bit prettier Tom Tromey
` (4 preceding siblings ...)
2023-02-08 7:17 ` [PATCH 5/8] Use intptr_t rather than long in chew Tom Tromey
@ 2023-02-08 7:17 ` Tom Tromey
2023-02-08 7:17 ` [PATCH 7/8] Use @deftypefn in chew output Tom Tromey
` (2 subsequent siblings)
8 siblings, 0 replies; 19+ messages in thread
From: Tom Tromey @ 2023-02-08 7:17 UTC (permalink / raw)
To: binutils; +Cc: 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
^ permalink raw reply [flat|nested] 19+ messages in thread
* [PATCH 7/8] Use @deftypefn in chew output
2023-02-08 7:17 [PATCH 0/8] Make the BFD info manual a bit prettier Tom Tromey
` (5 preceding siblings ...)
2023-02-08 7:17 ` [PATCH 6/8] Change internalmode to be an intrinsic variable Tom Tromey
@ 2023-02-08 7:17 ` Tom Tromey
2023-02-15 17:55 ` Simon Marchi
2023-02-08 7:17 ` [PATCH 8/8] Remove RETURNS from BFD chew comments Tom Tromey
2023-02-15 9:54 ` [PATCH 0/8] Make the BFD info manual a bit prettier Nick Clifton
8 siblings, 1 reply; 19+ messages in thread
From: Tom Tromey @ 2023-02-08 7:17 UTC (permalink / raw)
To: binutils; +Cc: 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
^ permalink raw reply [flat|nested] 19+ messages in thread
* Re: [PATCH 7/8] Use @deftypefn in chew output
2023-02-08 7:17 ` [PATCH 7/8] Use @deftypefn in chew output Tom Tromey
@ 2023-02-15 17:55 ` Simon Marchi
2023-02-15 23:11 ` Tom Tromey
0 siblings, 1 reply; 19+ messages in thread
From: Simon Marchi @ 2023-02-15 17:55 UTC (permalink / raw)
To: Tom Tromey, binutils
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
^ permalink raw reply [flat|nested] 19+ messages in thread
* Re: [PATCH 7/8] Use @deftypefn in chew output
2023-02-15 17:55 ` Simon Marchi
@ 2023-02-15 23:11 ` Tom Tromey
2023-02-16 1:29 ` Simon Marchi
0 siblings, 1 reply; 19+ messages in thread
From: Tom Tromey @ 2023-02-15 23:11 UTC (permalink / raw)
To: Simon Marchi; +Cc: Tom Tromey, binutils
>>>>> "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
^ permalink raw reply [flat|nested] 19+ messages in thread
* Re: [PATCH 7/8] Use @deftypefn in chew output
2023-02-15 23:11 ` Tom Tromey
@ 2023-02-16 1:29 ` Simon Marchi
2023-02-19 3:46 ` Alan Modra
0 siblings, 1 reply; 19+ messages in thread
From: Simon Marchi @ 2023-02-16 1:29 UTC (permalink / raw)
To: Tom Tromey; +Cc: binutils
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
^ permalink raw reply [flat|nested] 19+ messages in thread
* Re: [PATCH 7/8] Use @deftypefn in chew output
2023-02-16 1:29 ` Simon Marchi
@ 2023-02-19 3:46 ` Alan Modra
0 siblings, 0 replies; 19+ messages in thread
From: Alan Modra @ 2023-02-19 3:46 UTC (permalink / raw)
To: Simon Marchi; +Cc: Tom Tromey, binutils
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
^ permalink raw reply [flat|nested] 19+ messages in thread
* [PATCH 8/8] Remove RETURNS from BFD chew comments
2023-02-08 7:17 [PATCH 0/8] Make the BFD info manual a bit prettier Tom Tromey
` (6 preceding siblings ...)
2023-02-08 7:17 ` [PATCH 7/8] Use @deftypefn in chew output Tom Tromey
@ 2023-02-08 7:17 ` Tom Tromey
2023-02-15 9:54 ` [PATCH 0/8] Make the BFD info manual a bit prettier Nick Clifton
8 siblings, 0 replies; 19+ messages in thread
From: Tom Tromey @ 2023-02-08 7:17 UTC (permalink / raw)
To: binutils; +Cc: 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
^ permalink raw reply [flat|nested] 19+ messages in thread
* Re: [PATCH 0/8] Make the BFD info manual a bit prettier
2023-02-08 7:17 [PATCH 0/8] Make the BFD info manual a bit prettier Tom Tromey
` (7 preceding siblings ...)
2023-02-08 7:17 ` [PATCH 8/8] Remove RETURNS from BFD chew comments Tom Tromey
@ 2023-02-15 9:54 ` Nick Clifton
2023-02-15 21:51 ` Tom Tromey
8 siblings, 1 reply; 19+ messages in thread
From: Nick Clifton @ 2023-02-15 9:54 UTC (permalink / raw)
To: Tom Tromey, binutils
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
^ permalink raw reply [flat|nested] 19+ messages in thread
* Re: [PATCH 0/8] Make the BFD info manual a bit prettier
2023-02-15 9:54 ` [PATCH 0/8] Make the BFD info manual a bit prettier Nick Clifton
@ 2023-02-15 21:51 ` Tom Tromey
2023-02-16 9:40 ` Nick Clifton
0 siblings, 1 reply; 19+ messages in thread
From: Tom Tromey @ 2023-02-15 21:51 UTC (permalink / raw)
To: Nick Clifton; +Cc: Tom Tromey, binutils
>> 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
^ permalink raw reply [flat|nested] 19+ messages in thread
* Re: [PATCH 0/8] Make the BFD info manual a bit prettier
2023-02-15 21:51 ` Tom Tromey
@ 2023-02-16 9:40 ` Nick Clifton
0 siblings, 0 replies; 19+ messages in thread
From: Nick Clifton @ 2023-02-16 9:40 UTC (permalink / raw)
To: Tom Tromey; +Cc: binutils
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
^ permalink raw reply [flat|nested] 19+ messages in thread