From: Tom Tromey <tom@tromey.com>
To: binutils@sourceware.org
Cc: Tom Tromey <tom@tromey.com>
Subject: [PATCH 7/8] Use @deftypefn in chew output
Date: Wed, 8 Feb 2023 00:17:24 -0700 [thread overview]
Message-ID: <20230208071725.3668898-8-tom@tromey.com> (raw)
In-Reply-To: <20230208071725.3668898-1-tom@tromey.com>
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
next prev parent reply other threads:[~2023-02-08 7:17 UTC|newest]
Thread overview: 19+ messages / expand[flat|nested] mbox.gz Atom feed top
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-03-03 8:20 ` Jan Beulich
2023-03-03 23:08 ` Tom Tromey
2023-03-06 7:07 ` Jan Beulich
2023-02-08 7:17 ` [PATCH 3/8] Add copyright headers to the .str files Tom Tromey
2023-02-08 7:17 ` [PATCH 4/8] Remove the paramstuff word Tom Tromey
2023-02-08 7:17 ` [PATCH 5/8] Use intptr_t rather than long in chew Tom Tromey
2023-02-08 7:17 ` [PATCH 6/8] Change internalmode to be an intrinsic variable Tom Tromey
2023-02-08 7:17 ` Tom Tromey [this message]
2023-02-15 17:55 ` [PATCH 7/8] Use @deftypefn in chew output Simon Marchi
2023-02-15 23:11 ` Tom Tromey
2023-02-16 1:29 ` Simon Marchi
2023-02-19 3:46 ` Alan Modra
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
2023-02-15 21:51 ` Tom Tromey
2023-02-16 9:40 ` Nick Clifton
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20230208071725.3668898-8-tom@tromey.com \
--to=tom@tromey.com \
--cc=binutils@sourceware.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).