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  <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.

diff --git a/bfd/ChangeLog b/bfd/ChangeLog
index 6e8888d23649ed88ac38c493a31de92a561b1655..6a8d5b1612a28d44f841743964bb1fccac6572a4 100644 (file)
--- a/bfd/ChangeLog
+++ b/bfd/ChangeLog
@@ -1,3 +1,14 @@
+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.
+
 2023-02-07  Tom Tromey  <tom@tromey.com>
 
        * doc/proto.str (external, internal, ifinternal, ENUMEQ, ENUMDOC):

diff --git a/bfd/doc/chew.c b/bfd/doc/chew.c
index b17b20a183fea219b02c593362b8de835ccef776..19e3781bdda1fc9da19c0c3338b4640d3e4f03b1 100644 (file)
--- 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 6019b7ccfdb7ddee919fe5a4669cb094e11abdb4..4576d497521558a005e8f305e77d3051c67715c9 100644 (file)
--- 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 a26aeb4cb8bb98ed3d056b381879f7449ed8825c..c460e377723351fa9b9b00694bc607cdb1afa03f 100644 (file)
--- 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