[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