From b8e81f19cbbe978c7376795129ee90ee8e73cf0a Mon Sep 17 00:00:00 2001 From: Tom Tromey Date: Tue, 7 Feb 2023 21:40:53 -0700 Subject: [PATCH] Use @deftypefn in chew output 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. 2023-02-07 Tom Tromey * 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/ChangeLog b/bfd/ChangeLog index 6e8888d2364..6a8d5b1612a 100644 --- a/bfd/ChangeLog +++ b/bfd/ChangeLog @@ -1,3 +1,14 @@ +2023-02-07 Tom Tromey + + * 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. + 2023-02-07 Tom Tromey * doc/proto.str (external, internal, ifinternal, ENUMEQ, ENUMDOC): 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: : ; + 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