[PATCH 0/4] More fixes to chew documentation

[PATCH 0/4] More fixes to chew documentation

[Tom Tromey]

I re-read the chew-generated BFD info pages, and found a few more
issues.  This series fixes the simpler ones.

For patch #3, I looked at adding a GLOBAL directive to chew, to make
it possible to document bfd_use_reserved_id using @deftypevar.
However, because chew doesn't really implement conditionals, this
turns out to be surprisingly tricky.  It would be simpler to just turn
this global into a setter function instead -- there's just one spot in
ld that sets it.

Alternatively, maybe adding conditionals to chew is the way to go, as
that would also let us improve the documentation for macros.

Tom

[PATCH 1/4] Fix formatting of long function description in chew output

[Tom Tromey]

Currently, if a function description spans a line, the resulting info
can look like this:

 -- Function: long bfd_canonicalize_reloc
     (bfd *abfd, asection *sec, arelent **loc, asymbol **syms); Call the
     back end associated with the open BFD ABFD and translate the
     external form of the relocation information attached to SEC into
     the internal canonical form.  Place the table into memory at LOC,

That is, the function prototype runs together with the text in an ugly
way.  This patch fixes this by introducing a new primitive, so that
the generated Texinfo can be a bit nicer.  Now this output looks like:

 -- Function: long bfd_canonicalize_reloc (bfd *abfd, asection *sec,
          arelent **loc, asymbol **syms);
     Call the back end associated with the open BFD ABFD and translate
     the external form of the relocation information attached to SEC

bfd/ChangeLog
2023-02-17  Tom Tromey  <tom@tromey.com>

	* doc/doc.str (SYNOPSIS): Use collapse_whitespace.
	* doc/chew.c (collapse_whitespace): New function.
	(main): Register collapse_whitespace.
---
 bfd/ChangeLog   |  6 ++++++
 bfd/doc/chew.c  | 33 +++++++++++++++++++++++++++++++++
 bfd/doc/doc.str |  2 ++
 3 files changed, 41 insertions(+)

diff --git a/bfd/doc/chew.c b/bfd/doc/chew.c
index 19e3781bdda..eca9305fee0 100644
--- a/bfd/doc/chew.c
+++ b/bfd/doc/chew.c
@@ -884,6 +884,38 @@ kill_bogus_lines (void)
 
 }
 
+static void
+collapse_whitespace (void)
+{
+  int last_was_ws = 0;
+  int idx;
+
+  string_type out;
+  init_string (&out);
+
+  for (idx = 0; at (tos, idx) != 0; ++idx)
+    {
+      char c = at (tos, idx);
+      if (isspace (c))
+	{
+	  if (!last_was_ws)
+	    {
+	      catchar (&out, ' ');
+	      last_was_ws = 1;
+	    }
+	}
+      else
+	{
+	  catchar (&out, c);
+	  last_was_ws = 0;
+	}
+    }
+
+  pc++;
+  delete_string (tos);
+  *tos = out;
+}
+
 static void
 indent (void)
 {
@@ -1479,6 +1511,7 @@ main (int ac, char *av[])
   add_intrinsic ("indent", indent);
   add_intrinsic ("print_stack_level", print_stack_level);
   add_intrinsic ("strip_trailing_newlines", strip_trailing_newlines);
+  add_intrinsic ("collapse_whitespace", collapse_whitespace);
 
   internal_mode = xmalloc (sizeof (intptr_t));
   *internal_mode = 0;
diff --git a/bfd/doc/doc.str b/bfd/doc/doc.str
index 2a0953a3ece..5077ada9812 100644
--- a/bfd/doc/doc.str
+++ b/bfd/doc/doc.str
@@ -55,8 +55,10 @@ variable synopsis_seen
 	"@deftypefn {Function} " catstr
 	get_stuff_in_command  
 	kill_bogus_lines
+	collapse_whitespace
 	indent
 	catstr
+	"\n" catstr
 	;
 
 : func
-- 
2.39.1

[PATCH 2/4] Don't use chew comments for static functions

[Tom Tromey]

I found a few static functions in the BFD manual.  These can't be
called by any user of the library, so I don't think it's useful to put
them in the manual.  This patch removes the chew markup from their
comments.

bfd/ChangeLog
2023-02-17  Tom Tromey  <tom@tromey.com>

	* opncls.c (bfd_get_debug_link_info_1, separate_debug_file_exists)
	(separate_alt_debug_file_exists, find_separate_debug_file)
	(get_build_id, get_build_id_name, check_build_id_file): Don't use
	chew comments.
---
 bfd/ChangeLog |   7 +++
 bfd/opncls.c  | 170 +++++++++++++++-----------------------------------
 2 files changed, 58 insertions(+), 119 deletions(-)

diff --git a/bfd/opncls.c b/bfd/opncls.c
index eeac5825dbf..95906526973 100644
--- a/bfd/opncls.c
+++ b/bfd/opncls.c
@@ -1165,29 +1165,20 @@ bfd_calc_gnu_debuglink_crc32 (unsigned long crc,
 }
 
 
-/*
-INTERNAL_FUNCTION
-	bfd_get_debug_link_info_1
-
-SYNOPSIS
-	char *bfd_get_debug_link_info_1 (bfd *abfd, void *crc32_out);
-
-DESCRIPTION
-	Extracts the filename and CRC32 value for any separate debug
-	information file associated with @var{abfd}.
+/* Extracts the filename and CRC32 value for any separate debug
+   information file associated with @var{abfd}.
 
-	The @var{crc32_out} parameter is an untyped pointer because
-	this routine is used as a @code{get_func_type} function, but it
-	is expected to be an unsigned long pointer.
+   The @var{crc32_out} parameter is an untyped pointer because
+   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.
-*/
+   The returned filename is allocated with @code{malloc}; freeing
+   it is the responsibility of the caller.  */
 
 static char *
 bfd_get_debug_link_info_1 (bfd *abfd, void *crc32_out)
@@ -1322,22 +1313,12 @@ bfd_get_alt_debug_link_info (bfd * abfd, bfd_size_type *buildid_len,
   return name;
 }
 
-/*
-INTERNAL_FUNCTION
-	separate_debug_file_exists
-
-SYNOPSIS
-	bool separate_debug_file_exists
-	  (char *name, void *crc32_p);
-
-DESCRIPTION
-	Checks to see if @var{name} is a file and if its contents
-	match @var{crc32}, which is a pointer to an @code{unsigned
-	long} containing a CRC32.
+/* Checks to see if @var{name} is a file and if its contents match
+   @var{crc32}, which is a pointer to an @code{unsigned long}
+   containing a CRC32.
 
-	The @var{crc32_p} parameter is an untyped pointer because
-	this routine is used as a @code{check_func_type} function.
-*/
+   The @var{crc32_p} parameter is an untyped pointer because this
+   routine is used as a @code{check_func_type} function.  */
 
 static bool
 separate_debug_file_exists (const char *name, void *crc32_p)
@@ -1365,17 +1346,7 @@ separate_debug_file_exists (const char *name, void *crc32_p)
   return crc == file_crc;
 }
 
-/*
-INTERNAL_FUNCTION
-	separate_alt_debug_file_exists
-
-SYNOPSIS
-	bool separate_alt_debug_file_exists
-	  (char *name, void *unused);
-
-DESCRIPTION
-	Checks to see if @var{name} is a file.
-*/
+/* Checks to see if @var{name} is a file.  */
 
 static bool
 separate_alt_debug_file_exists (const char *name, void *unused ATTRIBUTE_UNUSED)
@@ -1393,33 +1364,22 @@ separate_alt_debug_file_exists (const char *name, void *unused ATTRIBUTE_UNUSED)
   return true;
 }
 
-/*
-INTERNAL_FUNCTION
-	find_separate_debug_file
+/* Searches for a debug information file corresponding to @var{abfd}.
 
-SYNOPSIS
-	char *find_separate_debug_file
-	  (bfd *abfd, const char *dir, bool include_dirs,
-	   get_func_type get, check_func_type check, void *data);
+   The name of the separate debug info file is returned by the
+   @var{get} function.  This function scans various fixed locations
+   in the filesystem, including the file tree rooted at @var{dir}.
+   If the @var{include_dirs} parameter is true then the directory
+   components of @var{abfd}'s filename will be included in the
+   searched locations.
 
-DESCRIPTION
-	Searches for a debug information file corresponding to @var{abfd}.
-
-	The name of the separate debug info file is returned by the
-	@var{get} function.  This function scans various fixed locations
-	in the filesystem, including the file tree rooted at @var{dir}.
-	If the @var{include_dirs} parameter is true then the directory
-	components of @var{abfd}'s filename will be included in the
-	searched locations.
-
-	@var{data} is passed unmodified to the @var{get} and @var{check}
-	functions.  It is generally used to implement build-id-like
-	matching in the callback functions.
-
-	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.
-*/
+   @var{data} is passed unmodified to the @var{get} and @var{check}
+   functions.  It is generally used to implement build-id-like
+   matching in the callback functions.
+
+   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.  */
 
 typedef char * (*get_func_type) (bfd *, void *);
 typedef bool (*check_func_type) (const char *, void *);
@@ -1818,23 +1778,14 @@ bfd_fill_in_gnu_debuglink_section (bfd *abfd,
   return true;
 }
 
-/*
-INTERNAL_FUNCTION
-	get_build_id
-
-SYNOPSIS
-	struct bfd_build_id * get_build_id (bfd *abfd);
+/* Finds the build-id associated with @var{abfd}.  If the build-id is
+   extracted from the note section then a build-id structure is built
+   for it, using memory allocated to @var{abfd}, and this is then
+   attached to the @var{abfd}.
 
-DESCRIPTION
-	Finds the build-id associated with @var{abfd}.  If the build-id is
-	extracted from the note section then a build-id structure is built
-	for it, using memory allocated to @var{abfd}, and this is then
-	attached to the @var{abfd}.
-
-	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.
-*/
+   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.  */
 
 static struct bfd_build_id *
 get_build_id (bfd *abfd)
@@ -1919,25 +1870,15 @@ get_build_id (bfd *abfd)
   return build_id;
 }
 
-/*
-INTERNAL_FUNCTION
-	get_build_id_name
-
-SYNOPSIS
-	char * get_build_id_name (bfd *abfd, void *build_id_out_p)
+/* Searches @var{abfd} for a build-id, and then constructs a pathname
+   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.
 
-DESCRIPTION
-	Searches @var{abfd} for a build-id, and then constructs a pathname
-	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 the constructed filename or NULL upon error.
-	It is the caller's responsibility to free the memory used to hold the
-	filename.
-	If a filename is returned then the @var{build_id_out_p}
-	parameter (which points to a @code{struct bfd_build_id}
-	pointer) is set to a pointer to the build_id structure.
-*/
+   Returns the constructed filename or NULL upon error.  It is the
+   caller's responsibility to free the memory used to hold the
+   filename.  If a filename is returned then the @var{build_id_out_p}
+   parameter (which points to a @code{struct bfd_build_id} pointer) is
+   set to a pointer to the build_id structure.  */
 
 static char *
 get_build_id_name (bfd *abfd, void *build_id_out_p)
@@ -1981,21 +1922,12 @@ get_build_id_name (bfd *abfd, void *build_id_out_p)
   return name;
 }
 
-/*
-INTERNAL_FUNCTION
-	check_build_id_file
+/* Checks to see if @var{name} is a readable file and if its build-id
+   matches @var{buildid}.
 
-SYNOPSIS
-	bool check_build_id_file (char *name, void *buildid_p);
-
-DESCRIPTION
-	Checks to see if @var{name} is a readable file and if its build-id
-	matches @var{buildid}.
-
-	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 **}).
-*/
+   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 **}).  */
 
 static bool
 check_build_id_file (const char *name, void *buildid_p)
-- 
2.39.1

[PATCH 3/4] Hoist the SECTION comment in opncls.c

[Tom Tromey]

The opening and closing node in BFD starts:

    File: bfd.info, [...]

	 /* Set to N to open the next N BFDs using an alternate id space.  */
	 extern unsigned int bfd_use_reserved_id;

    2.13 Opening and closing BFDs
    =============================

That is, there's a stray C comment and declaration before any other
text or subsections.

This occurs because the code fragment for bfd_use_reserved_id comes
before the SECTION comment.  Hoisting it makes this a little nicer.

bfd/ChangeLog
2023-02-17  Tom Tromey  <tom@tromey.com>

	* opncls.c: Hoist the SECTION comment.
---
 bfd/ChangeLog |  4 ++++
 bfd/opncls.c  | 16 ++++++++--------
 2 files changed, 12 insertions(+), 8 deletions(-)

diff --git a/bfd/opncls.c b/bfd/opncls.c
index 95906526973..15ee4f7f44e 100644
--- a/bfd/opncls.c
+++ b/bfd/opncls.c
@@ -37,6 +37,14 @@
 #define S_IXOTH 0001	/* Execute by others.  */
 #endif
 
+/*
+SECTION
+	Opening and closing BFDs
+
+SUBSECTION
+	Functions for opening and closing
+*/
+
 /* Counters used to initialize the bfd identifier.  */
 
 static unsigned int bfd_id_counter = 0;
@@ -179,14 +187,6 @@ _bfd_free_cached_info (bfd *abfd)
   return true;
 }
 
-/*
-SECTION
-	Opening and closing BFDs
-
-SUBSECTION
-	Functions for opening and closing
-*/
-
 /*
 FUNCTION
 	bfd_fopen
-- 
2.39.1

[PATCH 4/4] Redefine FUNCTION in doc.str

[Tom Tromey]

FUNCTION is identical to func, so simplify doc.str.

2023-02-17  Tom Tromey  <tom@tromey.com>

	* doc/doc.str (FUNCTION): Call func.
---
 bfd/ChangeLog   |  4 ++++
 bfd/doc/doc.str | 10 +---------
 2 files changed, 5 insertions(+), 9 deletions(-)

diff --git a/bfd/doc/doc.str b/bfd/doc/doc.str
index 5077ada9812..f59ff2edd6e 100644
--- a/bfd/doc/doc.str
+++ b/bfd/doc/doc.str
@@ -74,15 +74,7 @@ variable synopsis_seen
 	;
 
 : FUNCTION
-	"@findex "	- a
-	skip_past_newline
-	copy_past_newline
-	dup		- a x x 
-	"@subsubsection @code{" - a x x b 
-	swap
-	remchar
-	"}\n" - a x b x c
-	catstr 	catstr 	catstr 	catstr 	catstr 
+	func
 	;
 
 : bodytext
-- 
2.39.1

Re: [PATCH 0/4] More fixes to chew documentation

[Nick Clifton]

Hi Tom,

   Approved - please apply.

Cheers
   Nick