Subject: Patches to improve variable name usage in docstrings
From: Bake Timmons <[email-masked]>
To: [email-masked]
Date: Thu, 12 Jan 2012 00:07:32 -0500
List-Id: <debbugs-submit.debbugs.gnu.org>

Attached are patches to improve variable name usage in docstrings.
These patches cover simple, blatant inconsistencies.

From da3279f7ca6acac841b84311f14db5825b3d33f6 Mon Sep 17 00:00:00 2001
From: Bake Timmons <[email-masked]>
Date: Wed, 11 Jan 2012 23:33:01 -0500
Subject: [PATCH] Improve the usage of variable names in C docstrings.

* libguile/alist.c:
* libguile/array-map.c:
* libguile/arrays.c:
* libguile/bitvectors.c:
* libguile/filesys.c:
* libguile/foreign.c:
* libguile/generalized-arrays.c:
* libguile/hashtab.c:
* libguile/ioext.c:
* libguile/load.c:
* libguile/numbers.c:
* libguile/ports.c:
* libguile/posix.c:
* libguile/print.c:
* libguile/procprop.c:
* libguile/promises.c:
* libguile/simpos.c:
* libguile/socket.c:
* libguile/srfi-1.c:
* libguile/srfi-13.c:
* libguile/srfi-14.c:
* libguile/stacks.c:
* libguile/stime.c:
* libguile/strings.c:
* libguile/struct.c:
* libguile/symbols.c:
* libguile/threads.c:
* libguile/weak-table.c:
* libguile/weak-vector.c: Make the variable names in the C docstrings more
  consistent.  Replace a few instances of @var with @code when appropriate.
---
 libguile/alist.c              |    4 +-
 libguile/array-map.c          |   27 +++++++++++-----------
 libguile/arrays.c             |   37 ++++++++++++++++---------------
 libguile/bitvectors.c         |    2 +-
 libguile/filesys.c            |   49 +++++++++++++++++++++--------------------
 libguile/foreign.c            |    6 ++--
 libguile/generalized-arrays.c |    7 +++--
 libguile/hashtab.c            |   10 ++++----
 libguile/ioext.c              |   10 ++++----
 libguile/load.c               |    4 +-
 libguile/numbers.c            |    4 +-
 libguile/ports.c              |   24 +++++++++++---------
 libguile/posix.c              |   40 +++++++++++++++++----------------
 libguile/print.c              |    2 +-
 libguile/procprop.c           |    2 +-
 libguile/promises.c           |    4 +-
 libguile/simpos.c             |    2 +-
 libguile/socket.c             |    8 +++---
 libguile/srfi-1.c             |    8 +++---
 libguile/srfi-13.c            |    6 ++--
 libguile/srfi-14.c            |    6 ++--
 libguile/stacks.c             |    6 ++--
 libguile/stime.c              |   17 +++++++------
 libguile/strings.c            |    2 +-
 libguile/struct.c             |   24 ++++++++++++-------
 libguile/symbols.c            |    9 ++++---
 libguile/threads.c            |   17 +++++++------
 libguile/weak-table.c         |    6 ++--
 libguile/weak-vector.c        |    2 +-
 29 files changed, 181 insertions(+), 164 deletions(-)

diff --git a/libguile/alist.c b/libguile/alist.c
index 799e9f1..82c70a0 100644
--- a/libguile/alist.c
+++ b/libguile/alist.c
@@ -255,9 +255,9 @@ SCM_DEFINE (scm_assq_set_x, "assq-set!", 3, 0, 0,
             (SCM alist, SCM key, SCM val),
 	    "@deffnx {Scheme Procedure} assv-set! alist key value\n"
 	    "@deffnx {Scheme Procedure} assoc-set! alist key value\n"
-	    "Reassociate @var{key} in @var{alist} with @var{value}: find any existing\n"
+	    "Reassociate @var{key} in @var{alist} with @var{val}: find any existing\n"
 	    "@var{alist} entry for @var{key} and associate it with the new\n"
-	    "@var{value}.  If @var{alist} does not contain an entry for @var{key},\n"
+	    "@var{val}.  If @var{alist} does not contain an entry for @var{key},\n"
 	    "add a new one.  Return the (possibly new) alist.\n\n"
 	    "These functions do not attempt to verify the structure of @var{alist},\n"
 	    "and so may cause unusual results if passed an object that is not an\n"
diff --git a/libguile/array-map.c b/libguile/array-map.c
index acd167d..c0f0f00 100644
--- a/libguile/array-map.c
+++ b/libguile/array-map.c
@@ -320,8 +320,8 @@ scm_ramapc (void *cproc_ptr, SCM data, SCM ra0, SCM lra, const char *what)
 
 SCM_DEFINE (scm_array_fill_x, "array-fill!", 2, 0, 0,
 	    (SCM ra, SCM fill),
-	    "Store @var{fill} in every element of @var{array}.  The value returned\n"
-	    "is unspecified.")
+	    "Store @var{fill} in every element of array @var{ra}.  The value\n"
+	    "returned is unspecified.")
 #define FUNC_NAME s_scm_array_fill_x
 {
   scm_ramapc (scm_array_fill_int, fill, ra, SCM_EOL, FUNC_NAME);
@@ -374,9 +374,9 @@ SCM_REGISTER_PROC(s_array_copy_in_order_x, "array-copy-in-order!", 2, 0, 0, scm_
 SCM_DEFINE (scm_array_copy_x, "array-copy!", 2, 0, 0,
 	    (SCM src, SCM dst),
 	    "@deffnx {Scheme Procedure} array-copy-in-order! src dst\n"
-	    "Copy every element from vector or array @var{source} to the\n"
-	    "corresponding element of @var{destination}.  @var{destination} must have\n"
-	    "the same rank as @var{source}, and be at least as large in each\n"
+	    "Copy every element from vector or array @var{src} to the\n"
+	    "corresponding element of @var{dst}.  @var{dst} must have the\n"
+	    "same rank as @var{src}, and be at least as large in each\n"
 	    "dimension.  The order is unspecified.")
 #define FUNC_NAME s_scm_array_copy_x
 {
@@ -670,12 +670,13 @@ SCM_SYMBOL (sym_b, "b");
 SCM_DEFINE (scm_array_map_x, "array-map!", 2, 0, 1,
 	    (SCM ra0, SCM proc, SCM lra),
 	    "@deffnx {Scheme Procedure} array-map-in-order! ra0 proc . lra\n"
-	    "@var{array1}, @dots{} must have the same number of dimensions as\n"
-	    "@var{array0} and have a range for each index which includes the range\n"
-	    "for the corresponding index in @var{array0}.  @var{proc} is applied to\n"
-	    "each tuple of elements of @var{array1} @dots{} and the result is stored\n"
-	    "as the corresponding element in @var{array0}.  The value returned is\n"
-	    "unspecified.  The order of application is unspecified.")
+	    "@var{array1}, @dots{} must have the same number of dimensions\n"
+	    "as @var{ra0} and have a range for each index which includes the\n"
+	    "range for the corresponding index in @var{ra0}.  @var{proc} is\n"
+	    "applied to each tuple of elements of @var{array1}, @dots{} and\n"
+	    "the result is stored as the corresponding element in @var{ra0}.\n"
+	    "The value returned is unspecified.  The order of application is\n"
+	    "unspecified.")
 #define FUNC_NAME s_scm_array_map_x
 {
   SCM_VALIDATE_PROC (2, proc);
@@ -722,7 +723,7 @@ rafe (SCM ra0, SCM proc, SCM ras)
 
 SCM_DEFINE (scm_array_for_each, "array-for-each", 2, 0, 1,
 	    (SCM proc, SCM ra0, SCM lra),
-	    "Apply @var{proc} to each tuple of elements of @var{array0} @dots{}\n"
+	    "Apply @var{proc} to each tuple of elements of @var{ra0} @dots{}\n"
 	    "in row-major order.  The value returned is unspecified.")
 #define FUNC_NAME s_scm_array_for_each
 {
@@ -735,7 +736,7 @@ SCM_DEFINE (scm_array_for_each, "array-for-each", 2, 0, 1,
 
 SCM_DEFINE (scm_array_index_map_x, "array-index-map!", 2, 0, 0,
 	    (SCM ra, SCM proc),
-	    "Apply @var{proc} to the indices of each element of @var{array} in\n"
+	    "Apply @var{proc} to the indices of each element of @var{ra} in\n"
 	    "turn, storing the result in the corresponding element.  The value\n"
 	    "returned and the order of application are unspecified.\n\n"
 	    "One can implement @var{array-indexes} as\n"
diff --git a/libguile/arrays.c b/libguile/arrays.c
index 935d6f3..f0f9012 100644
--- a/libguile/arrays.c
+++ b/libguile/arrays.c
@@ -326,11 +326,12 @@ scm_i_ra_set_contp (SCM ra)
 
 SCM_DEFINE (scm_make_shared_array, "make-shared-array", 2, 0, 1,
            (SCM oldra, SCM mapfunc, SCM dims),
-	    "@code{make-shared-array} can be used to create shared subarrays of other\n"
-	    "arrays.  The @var{mapper} is a function that translates coordinates in\n"
-	    "the new array into coordinates in the old array.  A @var{mapper} must be\n"
-	    "linear, and its range must stay within the bounds of the old array, but\n"
-	    "it can be otherwise arbitrary.  A simple example:\n"
+	    "@code{make-shared-array} can be used to create shared subarrays\n"
+	    "of other arrays.  The @var{mapfunc} is a function that\n"
+	    "translates coordinates in the new array into coordinates in the\n"
+	    "old array.  A @var{mapfunc} must be linear, and its range must\n"
+	    "stay within the bounds of the old array, but it can be\n"
+	    "otherwise arbitrary.  A simple example:\n"
 	    "@lisp\n"
 	    "(define fred (make-array #f 8 8))\n"
 	    "(define freds-diagonal\n"
@@ -444,18 +445,18 @@ SCM_DEFINE (scm_make_shared_array, "make-shared-array", 2, 0, 1,
 /* args are RA . DIMS */
 SCM_DEFINE (scm_transpose_array, "transpose-array", 1, 0, 1, 
            (SCM ra, SCM args),
-	    "Return an array sharing contents with @var{array}, but with\n"
+	    "Return an array sharing contents with @var{ra}, but with\n"
 	    "dimensions arranged in a different order.  There must be one\n"
-	    "@var{dim} argument for each dimension of @var{array}.\n"
+	    "@var{dim} argument for each dimension of @var{ra}.\n"
 	    "@var{dim0}, @var{dim1}, @dots{} should be integers between 0\n"
 	    "and the rank of the array to be returned.  Each integer in that\n"
 	    "range must appear at least once in the argument list.\n"
 	    "\n"
 	    "The values of @var{dim0}, @var{dim1}, @dots{} correspond to\n"
 	    "dimensions in the array to be returned, their positions in the\n"
-	    "argument list to dimensions of @var{array}.  Several @var{dim}s\n"
+	    "argument list to dimensions of @var{ra}.  Several @var{dim}s\n"
 	    "may have the same value, in which case the returned array will\n"
-	    "have smaller rank than @var{array}.\n"
+	    "have smaller rank than @var{ra}.\n"
 	    "\n"
 	    "@lisp\n"
 	    "(transpose-array '#2((a b) (c d)) 1 0) @result{} #2((a c) (b d))\n"
@@ -546,15 +547,15 @@ SCM_DEFINE (scm_transpose_array, "transpose-array", 1, 0, 1,
 		     wouldn't have contiguous elements.  */
 SCM_DEFINE (scm_array_contents, "array-contents", 1, 1, 0,
            (SCM ra, SCM strict),
-	    "If @var{array} may be @dfn{unrolled} into a one dimensional shared array\n"
-	    "without changing their order (last subscript changing fastest), then\n"
-	    "@code{array-contents} returns that shared array, otherwise it returns\n"
-	    "@code{#f}.  All arrays made by @var{make-array} and\n"
-	    "@var{make-uniform-array} may be unrolled, some arrays made by\n"
-	    "@var{make-shared-array} may not be.\n\n"
-	    "If the optional argument @var{strict} is provided, a shared array will\n"
-	    "be returned only if its elements are stored internally contiguous in\n"
-	    "memory.")
+	    "If @var{ra} may be @dfn{unrolled} into a one dimensional shared\n"
+	    "array without changing their order (last subscript changing\n"
+	    "fastest), then @code{array-contents} returns that shared array,\n"
+	    "otherwise it returns @code{#f}.  All arrays made by\n"
+	    "@code{make-array} and @code{make-uniform-array} may be unrolled,\n"
+	    "some arrays made by @code{make-shared-array} may not be.  If\n"
+	    "the optional argument @var{strict} is provided, a shared array\n"
+	    "will be returned only if its elements are stored internally\n"
+	    "contiguous in memory.")
 #define FUNC_NAME s_scm_array_contents
 {
   SCM sra;
diff --git a/libguile/bitvectors.c b/libguile/bitvectors.c
index bc273a3..ffea6d1 100644
--- a/libguile/bitvectors.c
+++ b/libguile/bitvectors.c
@@ -497,7 +497,7 @@ SCM_DEFINE (scm_bit_position, "bit-position", 3, 0, 0,
 	    "Return the index of the first occurrence of @var{item} in bit\n"
 	    "vector @var{v}, starting from @var{k}.  If there is no\n"
 	    "@var{item} entry between @var{k} and the end of\n"
-	    "@var{bitvector}, then return @code{#f}.  For example,\n"
+	    "@var{v}, then return @code{#f}.  For example,\n"
 	    "\n"
 	    "@example\n"
 	    "(bit-position #t #*000101 0)  @result{} 3\n"
diff --git a/libguile/filesys.c b/libguile/filesys.c
index 3856b44..8bef7ae 100644
--- a/libguile/filesys.c
+++ b/libguile/filesys.c
@@ -487,7 +487,7 @@ static int fstat_Win32 (int fdes, struct stat *buf)
 SCM_DEFINE (scm_stat, "stat", 1, 1, 0, 
             (SCM object, SCM exception_on_error),
 	    "Return an object containing various information about the file\n"
-	    "determined by @var{obj}.  @var{obj} can be a string containing\n"
+	    "determined by @var{object}.  @var{object} can be a string containing\n"
 	    "a file name or a port or integer file descriptor which is open\n"
 	    "on a file (in which case @code{fstat} is used as the underlying\n"
 	    "system call).\n"
@@ -608,7 +608,7 @@ SCM_DEFINE (scm_lstat, "lstat", 1, 0, 0,
             (SCM str),
 	    "Similar to @code{stat}, but does not follow symbolic links, i.e.,\n"
 	    "it will return information about a symbolic link itself, not the\n"
-	    "file it points to.  @var{path} must be a string.")
+	    "file it points to.  @var{str} must be a string.")
 #define FUNC_NAME s_scm_lstat
 {
   int rv;
@@ -662,7 +662,7 @@ SCM_DEFINE (scm_link, "link", 2, 0, 0,
 
 SCM_DEFINE (scm_chdir, "chdir", 1, 0, 0, 
             (SCM str),
-	    "Change the current working directory to @var{path}.\n"
+	    "Change the current working directory to @var{str}.\n"
 	    "The return value is unspecified.")
 #define FUNC_NAME s_scm_chdir
 {
@@ -964,10 +964,10 @@ SCM_DEFINE (scm_select, "select", 3, 2, 0,
 #ifdef HAVE_FCNTL
 SCM_DEFINE (scm_fcntl, "fcntl", 2, 1, 0,
             (SCM object, SCM cmd, SCM value),
-	    "Apply @var{command} to the specified file descriptor or the underlying\n"
+	    "Apply @var{cmd} to the specified file descriptor or the underlying\n"
 	    "file descriptor of the specified port.  @var{value} is an optional\n"
 	    "integer argument.\n\n"
-	    "Values for @var{command} are:\n\n"
+	    "Values for @var{cmd} are:\n\n"
 	    "@table @code\n"
 	    "@item F_DUPFD\n"
 	    "Duplicate a file descriptor\n"
@@ -1015,9 +1015,9 @@ SCM_DEFINE (scm_fcntl, "fcntl", 2, 1, 0,
 
 SCM_DEFINE (scm_fsync, "fsync", 1, 0, 0, 
             (SCM object),
-	    "Copies any unwritten data for the specified output file descriptor to disk.\n"
-	    "If @var{port/fd} is a port, its buffer is flushed before the underlying\n"
-	    "file descriptor is fsync'd.\n"
+	    "Copies any unwritten data for the specified output file\n"
+	    "descriptor to disk.  If @var{object} is a port, its buffer is\n"
+	    "flushed before the underlying file descriptor is fsync'd.\n"
 	    "The return value is unspecified.")
 #define FUNC_NAME s_scm_fsync
 {
@@ -1042,8 +1042,9 @@ SCM_DEFINE (scm_fsync, "fsync", 1, 0, 0,
 #ifdef HAVE_SYMLINK
 SCM_DEFINE (scm_symlink, "symlink", 2, 0, 0,
             (SCM oldpath, SCM newpath),
-	    "Create a symbolic link named @var{path-to} with the value (i.e., pointing to)\n"
-	    "@var{path-from}.  The return value is unspecified.")
+	    "Create a symbolic link named @var{oldpath} with the value\n"
+	    "(i.e., pointing to) @var{newpath}.  The return value is\n"
+	    "unspecified.")
 #define FUNC_NAME s_scm_symlink
 {
   int val;
@@ -1101,7 +1102,7 @@ SCM_DEFINE (scm_readlink, "readlink", 1, 0, 0,
 
 SCM_DEFINE (scm_copy_file, "copy-file", 2, 0, 0,
             (SCM oldfile, SCM newfile),
-	    "Copy the file specified by @var{path-from} to @var{path-to}.\n"
+	    "Copy the file specified by @var{oldfile} to @var{newfile}.\n"
 	    "The return value is unspecified.")
 #define FUNC_NAME s_scm_copy_file
 {
@@ -1279,7 +1280,7 @@ SCM_DEFINE (scm_rename, "rename-file", 2, 0, 0,
 
 SCM_DEFINE (scm_delete_file, "delete-file", 1, 0, 0, 
            (SCM str),
-	    "Deletes (or \"unlinks\") the file specified by @var{path}.")
+	    "Deletes (or \"unlinks\") the file specified by @var{str}.")
 #define FUNC_NAME s_scm_delete_file
 {
   int ans;
@@ -1347,12 +1348,12 @@ SCM_DEFINE (scm_access, "access?", 2, 0, 0,
 
 SCM_DEFINE (scm_chmod, "chmod", 2, 0, 0,
             (SCM object, SCM mode),
-	    "Changes the permissions of the file referred to by @var{obj}.\n"
-	    "@var{obj} can be a string containing a file name or a port or integer file\n"
-	    "descriptor which is open on a file (in which case @code{fchmod} is used\n"
-	    "as the underlying system call).\n"
-	    "@var{mode} specifies\n"
-	    "the new permissions as a decimal number, e.g., @code{(chmod \"foo\" #o755)}.\n"
+	    "Changes the permissions of the file referred to by\n"
+	    "@var{object}.  @var{object} can be a string containing a file\n"
+	    "name or a port or integer file descriptor which is open on a\n"
+	    "file (in which case @code{fchmod} is used as the underlying\n"
+	    "system call).  @var{mode} specifies the new permissions as a\n"
+	    "decimal number, e.g., @code{(chmod \"foo\" #o755)}.\n"
 	    "The return value is unspecified.")
 #define FUNC_NAME s_scm_chmod
 {
@@ -1510,7 +1511,7 @@ SCM_DEFINE (scm_basename, "basename", 1, 1, 0,
 	    "Return the base name of the file name @var{filename}. The\n"
 	    "base name is the file name without any directory components.\n"
 	    "If @var{suffix} is provided, and is equal to the end of\n"
-	    "@var{basename}, it is removed also.")
+	    "@var{filename}, it is removed also.")
 #define FUNC_NAME s_scm_basename
 {
   int i, j, len, end;
@@ -1647,7 +1648,7 @@ scm_t_bits scm_tc16_dir;
 
 SCM_DEFINE (scm_directory_stream_p, "directory-stream?", 1, 0, 0,
 	    (SCM obj),
-	    "Return a boolean indicating whether @var{object} is a directory\n"
+	    "Return a boolean indicating whether @var{obj} is a directory\n"
 	    "stream as returned by @code{opendir}.")
 #define FUNC_NAME s_scm_directory_stream_p
 {
@@ -1658,7 +1659,7 @@ SCM_DEFINE (scm_directory_stream_p, "directory-stream?", 1, 0, 0,
 
 SCM_DEFINE (scm_opendir, "opendir", 1, 0, 0,
 	    (SCM dirname),
-	    "Open the directory specified by @var{path} and return a directory\n"
+	    "Open the directory specified by @var{dirname} and return a directory\n"
 	    "stream.")
 #define FUNC_NAME s_scm_opendir
 {
@@ -1680,7 +1681,7 @@ SCM_DEFINE (scm_opendir, "opendir", 1, 0, 0,
 SCM_DEFINE (scm_readdir, "readdir", 1, 0, 0,
 	    (SCM port),
 	    "Return (as a string) the next directory entry from the directory stream\n"
-	    "@var{stream}.  If there is no remaining entry to be read then the\n"
+	    "@var{port}.  If there is no remaining entry to be read then the\n"
 	    "end of file object is returned.")
 #define FUNC_NAME s_scm_readdir
 {
@@ -1754,7 +1755,7 @@ SCM_DEFINE (scm_readdir, "readdir", 1, 0, 0,
 
 SCM_DEFINE (scm_rewinddir, "rewinddir", 1, 0, 0,
 	    (SCM port),
-	    "Reset the directory port @var{stream} so that the next call to\n"
+	    "Reset the directory port @var{port} so that the next call to\n"
 	    "@code{readdir} will return the first directory entry.")
 #define FUNC_NAME s_scm_rewinddir
 {
@@ -1771,7 +1772,7 @@ SCM_DEFINE (scm_rewinddir, "rewinddir", 1, 0, 0,
 
 SCM_DEFINE (scm_closedir, "closedir", 1, 0, 0,
 	    (SCM port),
-	    "Close the directory stream @var{stream}.\n"
+	    "Close the directory stream @var{port}.\n"
 	    "The return value is unspecified.")
 #define FUNC_NAME s_scm_closedir
 {
diff --git a/libguile/foreign.c b/libguile/foreign.c
index a734f2d..5c21be8 100644
--- a/libguile/foreign.c
+++ b/libguile/foreign.c
@@ -1139,11 +1139,11 @@ invoke_closure (ffi_cif *cif, void *ret, void **args, void *data)
 
 SCM_DEFINE (scm_procedure_to_pointer, "procedure->pointer", 3, 0, 0,
 	    (SCM return_type, SCM proc, SCM arg_types),
-	    "Return a pointer to a C function of type @var{return-type}\n"
-	    "taking arguments of types @var{arg-types} (a list) and\n"
+	    "Return a pointer to a C function of type @var{return_type}\n"
+	    "taking arguments of types @var{arg_types} (a list) and\n"
 	    "behaving as a proxy to procedure @var{proc}.  Thus\n"
 	    "@var{proc}'s arity, supported argument types, and return\n"
-	    "type should match @var{return-type} and @var{arg-types}.\n")
+	    "type should match @var{return_type} and @var{arg_types}.\n")
 #define FUNC_NAME s_scm_procedure_to_pointer
 {
   SCM cif_pointer, pointer;
diff --git a/libguile/generalized-arrays.c b/libguile/generalized-arrays.c
index a04b5fa..3a0ce25 100644
--- a/libguile/generalized-arrays.c
+++ b/libguile/generalized-arrays.c
@@ -198,7 +198,7 @@ SCM_DEFINE (scm_array_in_bounds_p, "array-in-bounds?", 1, 0, 1,
 SCM_DEFINE (scm_array_ref, "array-ref", 1, 0, 1,
            (SCM v, SCM args),
 	    "Return the element at the @code{(index1, index2)} element in\n"
-	    "@var{array}.")
+	    "array @var{v}.")
 #define FUNC_NAME s_scm_array_ref
 {
   scm_t_array_handle handle;
@@ -214,8 +214,9 @@ SCM_DEFINE (scm_array_ref, "array-ref", 1, 0, 1,
 
 SCM_DEFINE (scm_array_set_x, "array-set!", 2, 0, 1, 
            (SCM v, SCM obj, SCM args),
-	    "Set the element at the @code{(index1, index2)} element in @var{array} to\n"
-	    "@var{new-value}.  The value returned by array-set! is unspecified.")
+	    "Set the element at the @code{(index1, index2)} element in array\n"
+	    "@var{v} to @var{obj}.  The value returned by @code{array-set!}\n"
+	    "is unspecified.")
 #define FUNC_NAME s_scm_array_set_x           
 {
   scm_t_array_handle handle;
diff --git a/libguile/hashtab.c b/libguile/hashtab.c
index 4091afe..09314be 100644
--- a/libguile/hashtab.c
+++ b/libguile/hashtab.c
@@ -401,7 +401,7 @@ SCM_DEFINE (scm_hashq_ref, "hashq-ref", 2, 1, 0,
             (SCM table, SCM key, SCM dflt),
 	    "Look up @var{key} in the hash table @var{table}, and return the\n"
 	    "value (if any) associated with it.  If @var{key} is not found,\n"
-	    "return @var{default} (or @code{#f} if no @var{default} argument\n"
+	    "return @var{dflt} (or @code{#f} if no @var{dflt} argument\n"
 	    "is supplied).  Uses @code{eq?} for equality testing.")
 #define FUNC_NAME s_scm_hashq_ref
 {
@@ -423,7 +423,7 @@ SCM_DEFINE (scm_hashq_ref, "hashq-ref", 2, 1, 0,
 SCM_DEFINE (scm_hashq_set_x, "hashq-set!", 3, 0, 0,
             (SCM table, SCM key, SCM val),
 	    "Find the entry in @var{table} associated with @var{key}, and\n"
-	    "store @var{value} there. Uses @code{eq?} for equality testing.")
+	    "store @var{val} there. Uses @code{eq?} for equality testing.")
 #define FUNC_NAME s_scm_hashq_set_x
 {
   if (SCM_WEAK_TABLE_P (table))
@@ -498,7 +498,7 @@ SCM_DEFINE (scm_hashv_ref, "hashv-ref", 2, 1, 0,
             (SCM table, SCM key, SCM dflt),
 	    "Look up @var{key} in the hash table @var{table}, and return the\n"
 	    "value (if any) associated with it.  If @var{key} is not found,\n"
-	    "return @var{default} (or @code{#f} if no @var{default} argument\n"
+	    "return @var{dflt} (or @code{#f} if no @var{dflt} argument\n"
 	    "is supplied).  Uses @code{eqv?} for equality testing.")
 #define FUNC_NAME s_scm_hashv_ref
 {
@@ -603,7 +603,7 @@ SCM_DEFINE (scm_hash_ref, "hash-ref", 2, 1, 0,
             (SCM table, SCM key, SCM dflt),
 	    "Look up @var{key} in the hash table @var{table}, and return the\n"
 	    "value (if any) associated with it.  If @var{key} is not found,\n"
-	    "return @var{default} (or @code{#f} if no @var{default} argument\n"
+	    "return @var{dflt} (or @code{#f} if no @var{dflt} argument\n"
 	    "is supplied).  Uses @code{equal?} for equality testing.")
 #define FUNC_NAME s_scm_hash_ref
 {
@@ -626,7 +626,7 @@ SCM_DEFINE (scm_hash_ref, "hash-ref", 2, 1, 0,
 SCM_DEFINE (scm_hash_set_x, "hash-set!", 3, 0, 0,
             (SCM table, SCM key, SCM val),
 	    "Find the entry in @var{table} associated with @var{key}, and\n"
-	    "store @var{value} there. Uses @code{equal?} for equality\n"
+	    "store @var{val} there. Uses @code{equal?} for equality\n"
 	    "testing.")
 #define FUNC_NAME s_scm_hash_set_x
 {
diff --git a/libguile/ioext.c b/libguile/ioext.c
index b1addf4..94b0f4f 100644
--- a/libguile/ioext.c
+++ b/libguile/ioext.c
@@ -49,7 +49,7 @@
 SCM_DEFINE (scm_ftell, "ftell", 1, 0, 0, 
             (SCM fd_port),
 	    "Return an integer representing the current position of\n"
-	    "@var{fd/port}, measured from the beginning.  Equivalent to:\n"
+	    "@var{fd_port}, measured from the beginning.  Equivalent to:\n"
 	    "\n"
 	    "@lisp\n"
 	    "(seek port 0 SEEK_CUR)\n"
@@ -63,8 +63,8 @@ SCM_DEFINE (scm_ftell, "ftell", 1, 0, 0,
 SCM_DEFINE (scm_redirect_port, "redirect-port", 2, 0, 0,
             (SCM old, SCM new),
 	    "This procedure takes two ports and duplicates the underlying file\n"
-	    "descriptor from @var{old-port} into @var{new-port}.  The\n"
-	    "current file descriptor in @var{new-port} will be closed.\n"
+	    "descriptor from @var{old} into @var{new}.  The\n"
+	    "current file descriptor in @var{new} will be closed.\n"
 	    "After the redirection the two ports will share a file position\n"
 	    "and file status flags.\n\n"
 	    "The return value is unspecified.\n\n"
@@ -236,7 +236,7 @@ SCM_DEFINE (scm_fdopen, "fdopen", 2, 0, 0,
 SCM_DEFINE (scm_primitive_move_to_fdes, "primitive-move->fdes", 2, 0, 0,
             (SCM port, SCM fd),
 	    "Moves the underlying file descriptor for @var{port} to the integer\n"
-	    "value @var{fdes} without changing the revealed count of @var{port}.\n"
+	    "value @var{fd} without changing the revealed count of @var{port}.\n"
 	    "Any other ports already using this descriptor will be automatically\n"
 	    "shifted to new descriptors and their revealed counts reset to zero.\n"
 	    "The return value is @code{#f} if the file descriptor already had the\n"
@@ -284,7 +284,7 @@ get_matching_port (void *closure, SCM port, SCM result)
 /* Return a list of ports using a given file descriptor.  */
 SCM_DEFINE (scm_fdes_to_ports, "fdes->ports", 1, 0, 0, 
            (SCM fd),
-	    "Return a list of existing ports which have @var{fdes} as an\n"
+	    "Return a list of existing ports which have @var{fd} as an\n"
 	    "underlying file descriptor, without changing their revealed\n"
 	    "counts.")
 #define FUNC_NAME s_scm_fdes_to_ports
diff --git a/libguile/load.c b/libguile/load.c
index 135a621..1c3603f 100644
--- a/libguile/load.c
+++ b/libguile/load.c
@@ -571,9 +571,9 @@ SCM_DEFINE (scm_search_path, "search-path", 2, 0, 1,
 	    "@var{filename}. The file must be readable, and not a directory.\n"
 	    "If we find one, return its full filename; otherwise, return\n"
 	    "@code{#f}.  If @var{filename} is absolute, return it unchanged.\n"
-	    "If given, @var{extensions} is a list of strings; for each\n"
+	    "If given, @var{rest} is a list of extension strings; for each\n"
 	    "directory in @var{path}, we search for @var{filename}\n"
-	    "concatenated with each @var{extension}.")
+	    "concatenated with each extension.")
 #define FUNC_NAME s_scm_search_path
 {
   SCM extensions, require_exts;
diff --git a/libguile/numbers.c b/libguile/numbers.c
index 46a195a..cb457d1 100644
--- a/libguile/numbers.c
+++ b/libguile/numbers.c
@@ -8704,8 +8704,8 @@ scm_c_make_rectangular (double re, double im)
 
 SCM_DEFINE (scm_make_rectangular, "make-rectangular", 2, 0, 0,
             (SCM real_part, SCM imaginary_part),
-	    "Return a complex number constructed of the given @var{real-part} "
-	    "and @var{imaginary-part} parts.")
+	    "Return a complex number constructed of the given @var{real_part} "
+	    "and @var{imaginary_part} parts.")
 #define FUNC_NAME s_scm_make_rectangular
 {
   SCM_ASSERT_TYPE (scm_is_real (real_part), real_part,
diff --git a/libguile/ports.c b/libguile/ports.c
index c0e13f3..d9289d8 100644
--- a/libguile/ports.c
+++ b/libguile/ports.c
@@ -1992,10 +1992,11 @@ SCM_DEFINE (scm_peek_char, "peek-char", 0, 1, 0,
 
 SCM_DEFINE (scm_unread_char, "unread-char", 1, 1, 0,
             (SCM cobj, SCM port),
-	    "Place @var{char} in @var{port} so that it will be read by the\n"
-	    "next read operation.  If called multiple times, the unread characters\n"
-	    "will be read again in last-in first-out order.  If @var{port} is\n"
-	    "not supplied, the current input port is used.")
+	    "Place character @var{cobj} in @var{port} so that it will be\n"
+	    "read by the next read operation.  If called multiple times, the\n"
+	    "unread characters will be read again in last-in first-out\n"
+	    "order.  If @var{port} is not supplied, the current input port\n"
+	    "is used.")
 #define FUNC_NAME s_scm_unread_char
 {
   int c;
@@ -2407,7 +2408,7 @@ SCM_DEFINE (scm_char_ready_p, "char-ready?", 0, 1, 0,
 
 SCM_DEFINE (scm_seek, "seek", 3, 0, 0,
             (SCM fd_port, SCM offset, SCM whence),
-	    "Sets the current position of @var{fd/port} to the integer\n"
+	    "Sets the current position of @var{fd_port} to the integer\n"
 	    "@var{offset}, which is interpreted according to the value of\n"
 	    "@var{whence}.\n"
 	    "\n"
@@ -2422,7 +2423,7 @@ SCM_DEFINE (scm_seek, "seek", 3, 0, 0,
 	    "@defvar SEEK_END\n"
 	    "Seek from the end of the file.\n"
 	    "@end defvar\n"
-	    "If @var{fd/port} is a file descriptor, the underlying system\n"
+	    "If @var{fd_port} is a file descriptor, the underlying system\n"
 	    "call is @code{lseek}.  @var{port} may be a string port.\n"
 	    "\n"
 	    "The value returned is the new position in the file.  This means\n"
@@ -2496,8 +2497,9 @@ truncate (const char *file, off_t length)
 
 SCM_DEFINE (scm_truncate_file, "truncate-file", 1, 1, 0,
             (SCM object, SCM length),
-	    "Truncate @var{file} to @var{length} bytes.  @var{file} can be a\n"
-	    "filename string, a port object, or an integer file descriptor.\n"
+	    "Truncate file @var{object} to @var{length} bytes.  @var{object}\n"
+	    "can be a filename string, a port object, or an integer file\n"
+	    "descriptor.\n"
 	    "The return value is unspecified.\n"
 	    "\n"
 	    "For a port or file descriptor @var{length} can be omitted, in\n"
@@ -2732,9 +2734,9 @@ SCM_DEFINE (scm_port_for_each, "port-for-each", 1, 0, 0,
 	    "Apply @var{proc} to each port in the Guile port table\n"
 	    "in turn.  The return value is unspecified.  More specifically,\n"
 	    "@var{proc} is applied exactly once to every port that exists\n"
-	    "in the system at the time @var{port-for-each} is invoked.\n"
-	    "Changes to the port table while @var{port-for-each} is running\n"
-	    "have no effect as far as @var{port-for-each} is concerned.") 
+	    "in the system at the time @code{port-for-each} is invoked.\n"
+	    "Changes to the port table while @code{port-for-each} is running\n"
+	    "have no effect as far as @code{port-for-each} is concerned.") 
 #define FUNC_NAME s_scm_port_for_each
 {
   SCM_VALIDATE_PROC (1, proc);
diff --git a/libguile/posix.c b/libguile/posix.c
index ea406ae..154d26a 100644
--- a/libguile/posix.c
+++ b/libguile/posix.c
@@ -285,7 +285,7 @@ SCM_DEFINE (scm_getgroups, "getgroups", 0, 0, 0,
 SCM_DEFINE (scm_setgroups, "setgroups", 1, 0, 0,
             (SCM group_vec),
 	    "Set the current set of supplementary group IDs to the integers\n"
-	    "in the given vector @var{vec}.  The return value is\n"
+	    "in the given vector @var{group_vec}.  The return value is\n"
 	    "unspecified.\n"
 	    "\n"
 	    "Generally only the superuser can set the process group IDs.")
@@ -335,9 +335,10 @@ SCM_DEFINE (scm_setgroups, "setgroups", 1, 0, 0,
 #ifdef HAVE_GETPWENT
 SCM_DEFINE (scm_getpwuid, "getpw", 0, 1, 0,
             (SCM user),
-	    "Look up an entry in the user database.  @var{obj} can be an integer,\n"
-	    "a string, or omitted, giving the behaviour of getpwuid, getpwnam\n"
-	    "or getpwent respectively.")
+	    "Look up an entry in the user database.  @var{user} can be an\n"
+	    "integer, a string, or omitted, giving the behaviour of\n"
+	    "@code{getpwuid}, @code{getpwnam} or @code{getpwent}\n"
+	    "respectively.")
 #define FUNC_NAME s_scm_getpwuid
 {
   struct passwd *entry;
@@ -404,9 +405,10 @@ SCM_DEFINE (scm_setpwent, "setpw", 0, 1, 0,
 /* Combines getgrgid and getgrnam.  */
 SCM_DEFINE (scm_getgrgid, "getgr", 0, 1, 0,
             (SCM name),
-	    "Look up an entry in the group database.  @var{obj} can be an integer,\n"
-	    "a string, or omitted, giving the behaviour of getgrgid, getgrnam\n"
-	    "or getgrent respectively.")
+	    "Look up an entry in the group database.  @var{name} can be an\n"
+	    "integer, a string, or omitted, giving the behaviour of\n"
+	    "@code{getgrgid}, @code{getgrnam} or @code{getgrent}\n"
+	    "respectively.")
 #define FUNC_NAME s_scm_getgrgid
 {
   struct group *entry;
@@ -698,7 +700,7 @@ SCM_DEFINE (scm_waitpid, "waitpid", 1, 1, 0,
 	    "group.\n"
 	    "@item @var{pid} less than -1\n"
 	    "Request status information for any child process whose process group ID\n"
-	    "is -@var{PID}.\n"
+	    "is -@var{pid}.\n"
 	    "@end table\n\n"
 	    "The @var{options} argument, if supplied, should be the bitwise OR of the\n"
 	    "values of zero or more of the following variables:\n\n"
@@ -1122,10 +1124,10 @@ SCM_DEFINE (scm_tcsetpgrp, "tcsetpgrp", 2, 0, 0,
 
 SCM_DEFINE (scm_execl, "execl", 1, 0, 1, 
             (SCM filename, SCM args),
-	    "Executes the file named by @var{path} as a new process image.\n"
+	    "Executes the file named by @var{filename} as a new process image.\n"
 	    "The remaining arguments are supplied to the process; from a C program\n"
 	    "they are accessible as the @code{argv} argument to @code{main}.\n"
-	    "Conventionally the first @var{arg} is the same as @var{path}.\n"
+	    "Conventionally the first @var{arg} is the same as @var{filename}.\n"
 	    "All arguments must be strings.\n\n"
 	    "If @var{arg} is missing, @var{path} is executed with a null\n"
 	    "argument list, which may have system-dependent side-effects.\n\n"
@@ -1359,7 +1361,7 @@ SCM_DEFINE (scm_utime, "utime", 1, 5, 0,
             (SCM pathname, SCM actime, SCM modtime, SCM actimens, SCM modtimens,
              SCM flags),
 	    "@code{utime} sets the access and modification times for the\n"
-	    "file named by @var{path}.  If @var{actime} or @var{modtime} is\n"
+	    "file named by @var{pathname}.  If @var{actime} or @var{modtime} is\n"
 	    "not supplied, then the current time is used.  @var{actime} and\n"
 	    "@var{modtime} must be integer time values as returned by the\n"
 	    "@code{current-time} procedure.\n\n"
@@ -1461,14 +1463,14 @@ SCM_DEFINE (scm_getpid, "getpid", 0, 0, 0,
 
 SCM_DEFINE (scm_putenv, "putenv", 1, 0, 0, 
             (SCM str),
-	    "Modifies the environment of the current process, which is\n"
-	    "also the default environment inherited by child processes.\n\n"
-	    "If @var{string} is of the form @code{NAME=VALUE} then it will be written\n"
-	    "directly into the environment, replacing any existing environment string\n"
-	    "with\n"
-	    "name matching @code{NAME}.  If @var{string} does not contain an equal\n"
-	    "sign, then any existing string with name matching @var{string} will\n"
-	    "be removed.\n\n"
+	    "Modifies the environment of the current process, which is also\n"
+	    "the default environment inherited by child processes.  If\n"
+	    "@var{str} is of the form @code{NAME=VALUE} then it will be\n"
+	    "written directly into the environment, replacing any existing\n"
+	    "environment string with name matching @code{NAME}.  If\n"
+	    "@var{str} does not contain an equal sign, then any existing\n"
+	    "string with name matching @var{str} will be removed.\n"
+	    "\n"
 	    "The return value is unspecified.")
 #define FUNC_NAME s_scm_putenv
 {
diff --git a/libguile/print.c b/libguile/print.c
index a1c36eb..2e9da93 100644
--- a/libguile/print.c
+++ b/libguile/print.c
@@ -1342,7 +1342,7 @@ SCM_DEFINE (scm_simple_format, "simple-format", 2, 0, 1,
 	    "@var{message} can contain @code{~A} (was @code{%s}) and\n"
 	    "@code{~S} (was @code{%S}) escapes.  When printed,\n"
 	    "the escapes are replaced with corresponding members of\n"
-	    "@var{ARGS}:\n"
+	    "@var{args}:\n"
 	    "@code{~A} formats using @code{display} and @code{~S} formats\n"
 	    "using @code{write}.\n"
 	    "If @var{destination} is @code{#t}, then use the current output\n"
diff --git a/libguile/procprop.c b/libguile/procprop.c
index 93ee7f0..56bd389 100644
--- a/libguile/procprop.c
+++ b/libguile/procprop.c
@@ -125,7 +125,7 @@ SCM_DEFINE (scm_procedure_minimum_arity, "procedure-minimum-arity", 1, 0, 0,
 
 SCM_DEFINE (scm_procedure_properties, "procedure-properties", 1, 0, 0, 
            (SCM proc),
-	    "Return @var{obj}'s property list.")
+	    "Return @var{proc}'s property list.")
 #define FUNC_NAME s_scm_procedure_properties
 {
   SCM ret;
diff --git a/libguile/promises.c b/libguile/promises.c
index 57a2081..dcd0ac3 100644
--- a/libguile/promises.c
+++ b/libguile/promises.c
@@ -98,8 +98,8 @@ promise_print (SCM exp, SCM port, scm_print_state *pstate)
 
 SCM_DEFINE (scm_force, "force", 1, 0, 0, 
 	    (SCM promise),
-	    "If the promise @var{x} has not been computed yet, compute and\n"
-	    "return @var{x}, otherwise just return the previously computed\n"
+	    "If @var{promise} has not been computed yet, compute and\n"
+	    "return @var{promise}, otherwise just return the previously computed\n"
 	    "value.")
 #define FUNC_NAME s_scm_force
 {
diff --git a/libguile/simpos.c b/libguile/simpos.c
index 84b8b9d..5c8fe96 100644
--- a/libguile/simpos.c
+++ b/libguile/simpos.c
@@ -169,7 +169,7 @@ SCM_DEFINE (scm_system_star, "system*", 0, 0, 1,
 
 SCM_DEFINE (scm_getenv, "getenv", 1, 0, 0, 
             (SCM nam),
-	    "Looks up the string @var{name} in the current environment.  The return\n"
+	    "Looks up the string @var{nam} in the current environment.  The return\n"
 	    "value is @code{#f} unless a string of the form @code{NAME=VALUE} is\n"
 	    "found, in which case the string @code{VALUE} is returned.")
 #define FUNC_NAME s_scm_getenv
diff --git a/libguile/socket.c b/libguile/socket.c
index d085d33..149ec00 100644
--- a/libguile/socket.c
+++ b/libguile/socket.c
@@ -515,10 +515,10 @@ SCM_DEFINE (scm_getsockopt, "getsockopt", 3, 0, 0,
 	    "@end defvar\n"
 	    "\n"
 	    "@defvar SO_LINGER\n"
-	    "The @var{value} returned is a pair of integers\n"
-	    "@code{(@var{ENABLE} . @var{TIMEOUT})}.  On old systems without\n"
+	    "The value returned is a pair of integers\n"
+	    "@code{(@var{enable} . @var{timeout})}.  On old systems without\n"
 	    "timeout support (ie.@: without @code{struct linger}), only\n"
-	    "@var{ENABLE} has an effect but the value in Guile is always a\n"
+	    "@var{enable} has an effect but the value in Guile is always a\n"
 	    "pair.\n"
 	    "@end defvar")
 #define FUNC_NAME s_scm_getsockopt
@@ -1560,7 +1560,7 @@ SCM_DEFINE (scm_sendto, "sendto", 3, 1, 1,
             (SCM sock, SCM message, SCM fam_or_sockaddr, SCM address, SCM args_and_flags),
 	    "Transmit bytevector @var{message} on socket port\n"
 	    "@var{sock}.  The\n"
-	    "destination address is specified using the @var{fam},\n"
+	    "destination address is specified using the @var{fam_or_sockaddr},\n"
 	    "@var{address} and\n"
 	    "@var{args_and_flags} arguments, or just a socket address object "
 	    "returned by @code{make-socket-address}, in a similar way to the\n"
diff --git a/libguile/srfi-1.c b/libguile/srfi-1.c
index ed6d3d9..54c7e2a 100644
--- a/libguile/srfi-1.c
+++ b/libguile/srfi-1.c
@@ -714,8 +714,8 @@ SCM_DEFINE (scm_srfi1_lset_difference_x, "lset-difference!", 2, 0, 1,
 
 SCM_DEFINE (scm_srfi1_assoc, "assoc", 2, 1, 0,
 	    (SCM key, SCM alist, SCM pred),
-	    "Behaves like @code{assq} but uses third argument @var{pred?}\n"
-	    "for key comparison.  If @var{pred?} is not supplied,\n"
+	    "Behaves like @code{assq} but uses third argument @var{pred}\n"
+	    "for key comparison.  If @var{pred} is not supplied,\n"
 	    "@code{equal?} is used.  (Extended from R5RS.)\n")
 #define FUNC_NAME s_scm_srfi1_assoc
 {
@@ -844,9 +844,9 @@ SCM_DEFINE (scm_srfi1_partition_x, "partition!", 2, 0, 0,
 
 SCM_DEFINE (scm_srfi1_remove, "remove", 2, 0, 0,
 	    (SCM pred, SCM list),
-	    "Return a list containing all elements from @var{lst} which do\n"
+	    "Return a list containing all elements from @var{list} which do\n"
 	    "not satisfy the predicate @var{pred}.  The elements in the\n"
-	    "result list have the same order as in @var{lst}.  The order in\n"
+	    "result list have the same order as in @var{list}.  The order in\n"
 	    "which @var{pred} is applied to the list elements is not\n"
 	    "specified.")
 #define FUNC_NAME s_scm_srfi1_remove
diff --git a/libguile/srfi-13.c b/libguile/srfi-13.c
index 92d4a9d..75feae3 100644
--- a/libguile/srfi-13.c
+++ b/libguile/srfi-13.c
@@ -375,7 +375,7 @@ SCM_SYMBOL (scm_sym_prefix, "prefix");
 SCM_DEFINE (scm_string_join, "string-join", 1, 2, 0,
             (SCM ls, SCM delimiter, SCM grammar),
 	    "Append the string in the string list @var{ls}, using the string\n"
-	    "@var{delim} as a delimiter between the elements of @var{ls}.\n"
+	    "@var{delimiter} as a delimiter between the elements of @var{ls}.\n"
 	    "@var{grammar} is a symbol which specifies how the delimiter is\n"
 	    "placed between the strings, and defaults to the symbol\n"
 	    "@code{infix}.\n"
@@ -1356,7 +1356,7 @@ SCM_DEFINE (scm_string_ci_ge, "string-ci>=", 2, 4, 0,
 
 SCM_DEFINE (scm_substring_hash, "string-hash", 1, 3, 0,
 	    (SCM s, SCM bound, SCM start, SCM end),
-	    "Compute a hash value for @var{S}.  the optional argument "
+	    "Compute a hash value for @var{s}.  the optional argument "
 	    "@var{bound} is a non-negative exact "
             "integer specifying the range of the hash function. "
 	    "A positive value restricts the return value to the "
@@ -1373,7 +1373,7 @@ SCM_DEFINE (scm_substring_hash, "string-hash", 1, 3, 0,
 
 SCM_DEFINE (scm_substring_hash_ci, "string-hash-ci", 1, 3, 0,
 	    (SCM s, SCM bound, SCM start, SCM end),
-	    "Compute a hash value for @var{S}.  the optional argument "
+	    "Compute a hash value for @var{s}.  the optional argument "
 	    "@var{bound} is a non-negative exact "
             "integer specifying the range of the hash function. "
 	    "A positive value restricts the return value to the "
diff --git a/libguile/srfi-14.c b/libguile/srfi-14.c
index 0932370..bf95ce9 100644
--- a/libguile/srfi-14.c
+++ b/libguile/srfi-14.c
@@ -698,8 +698,8 @@ SCM_DEFINE (scm_char_set_eq, "char-set=", 0, 0, 1,
 
 SCM_DEFINE (scm_char_set_leq, "char-set<=", 0, 0, 1,
 	    (SCM char_sets),
-	    "Return @code{#t} if every character set @var{cs}i is a subset\n"
-	    "of character set @var{cs}i+1.")
+	    "Return @code{#t} if every character set @var{char_set}i is a subset\n"
+	    "of character set @var{char_set}i+1.")
 #define FUNC_NAME s_scm_char_set_leq
 {
   int argnum = 1;
@@ -732,7 +732,7 @@ SCM_DEFINE (scm_char_set_hash, "char-set-hash", 1, 1, 0,
 	    (SCM cs, SCM bound),
 	    "Compute a hash value for the character set @var{cs}.  If\n"
 	    "@var{bound} is given and non-zero, it restricts the\n"
-	    "returned value to the range 0 @dots{} @var{bound - 1}.")
+	    "returned value to the range 0 @dots{} @var{bound} - 1.")
 #define FUNC_NAME s_scm_char_set_hash
 {
   const unsigned long default_bnd = 871;
diff --git a/libguile/stacks.c b/libguile/stacks.c
index d0e82f7..9599554 100644
--- a/libguile/stacks.c
+++ b/libguile/stacks.c
@@ -225,7 +225,7 @@ SCM_DEFINE (scm_make_stack, "make-stack", 1, 0, 1,
 	    "@code{(@var{inner_cut_1} @var{outer_cut_1} @var{inner_cut_2}\n"
 	    "@var{outer_cut_2} @dots{})}.\n"
             "\n"
-	    "Each @var{inner_cut_N} can be @code{#t}, an integer, a prompt\n"
+	    "Each @var{inner_cut_i} can be @code{#t}, an integer, a prompt\n"
             "tag, or a procedure.  @code{#t} means to cut away all frames up\n"
             "to but excluding the first user module frame.  An integer means\n"
             "to cut away exactly that number of frames.  A prompt tag means\n"
@@ -234,14 +234,14 @@ SCM_DEFINE (scm_make_stack, "make-stack", 1, 0, 1,
             "excluding the application frame whose procedure matches the\n"
             "specified one.\n"
             "\n"
-	    "Each @var{outer_cut_N} can be an integer, a prompt tag, or a\n"
+	    "Each @var{outer_cut_i} can be an integer, a prompt tag, or a\n"
             "procedure.  An integer means to cut away that number of frames.\n"
             "A prompt tag means to cut away all frames that are outside a\n"
             "prompt with the given tag. A procedure means to cut away\n"
             "frames down to but excluding the application frame whose\n"
             "procedure matches the specified one.\n"
             "\n"
-	    "If the @var{outer_cut_N} of the last pair is missing, it is\n"
+	    "If the @var{outer_cut_i} of the last pair is missing, it is\n"
 	    "taken as 0.")
 #define FUNC_NAME s_scm_make_stack
 {
diff --git a/libguile/stime.c b/libguile/stime.c
index dda82e7..7fdbba9 100644
--- a/libguile/stime.c
+++ b/libguile/stime.c
@@ -551,13 +551,14 @@ bdtime2c (SCM sbd_time, struct tm *lt, int pos, const char *subr)
 
 SCM_DEFINE (scm_mktime, "mktime", 1, 1, 0,
             (SCM sbd_time, SCM zone),
-	    "@var{bd-time} is an object representing broken down time and @code{zone}\n"
-	    "is an optional time zone specifier (otherwise the TZ environment variable\n"
-	    "or the system default is used).\n\n"
-	    "Returns a pair: the car is a corresponding\n"
-	    "integer time value like that returned\n"
-	    "by @code{current-time}; the cdr is a broken down time object, similar to\n"
-	    "as @var{bd-time} but with normalized values.")
+	    "@var{sbd_time} is an object representing broken down time and\n"
+	    "@code{zone} is an optional time zone specifier (otherwise the\n"
+	    "TZ environment variable or the system default is used).\n"
+	    "\n"
+	    "Returns a pair: the car is a corresponding integer time value\n"
+	    "like that returned by @code{current-time}; the cdr is a broken\n"
+	    "down time object, similar to as @var{sbd_time} but with\n"
+	    "normalized values.")
 #define FUNC_NAME s_scm_mktime
 {
   timet itime;
@@ -763,7 +764,7 @@ SCM_DEFINE (scm_strptime, "strptime", 2, 0, 0,
             (SCM format, SCM string),
 	    "Performs the reverse action to @code{strftime}, parsing\n"
 	    "@var{string} according to the specification supplied in\n"
-	    "@var{template}.  The interpretation of month and day names is\n"
+	    "@var{format}.  The interpretation of month and day names is\n"
 	    "dependent on the current locale.  The value returned is a pair.\n"
 	    "The car has an object with time components\n"
 	    "in the form returned by @code{localtime} or @code{gmtime},\n"
diff --git a/libguile/strings.c b/libguile/strings.c
index cb883fa..34dd413 100644
--- a/libguile/strings.c
+++ b/libguile/strings.c
@@ -1128,7 +1128,7 @@ SCM_DEFINE (scm_make_string, "make-string", 1, 1, 0,
 	    "Return a newly allocated string of\n"
             "length @var{k}.  If @var{chr} is given, then all elements of\n"
 	    "the string are initialized to @var{chr}, otherwise the contents\n"
-	    "of the @var{string} are all set to @var{#\nul}.")
+	    "of the string are all set to @code{#\nul}.")
 #define FUNC_NAME s_scm_make_string
 {
   return scm_c_make_string (scm_to_size_t (k), chr);
diff --git a/libguile/struct.c b/libguile/struct.c
index d022cce..13fe209 100644
--- a/libguile/struct.c
+++ b/libguile/struct.c
@@ -528,9 +528,9 @@ scm_c_make_struct (SCM vtable, size_t n_tail, size_t n_init, scm_t_bits init, ..
 SCM_DEFINE (scm_make_struct, "make-struct", 2, 0, 1, 
             (SCM vtable, SCM tail_array_size, SCM init),
 	    "Create a new structure.\n\n"
-	    "@var{type} must be a vtable structure (@pxref{Vtables}).\n\n"
-	    "@var{tail-elts} must be a non-negative integer.  If the layout\n"
-	    "specification indicated by @var{type} includes a tail-array,\n"
+	    "@var{vtable} must be a vtable structure (@pxref{Vtables}).\n\n"
+	    "@var{tail_array_size} must be a non-negative integer.  If the layout\n"
+	    "specification indicated by @var{vtable} includes a tail-array,\n"
 	    "this is the number of elements allocated to that array.\n\n"
 	    "The @var{init1}, @dots{} are optional arguments describing how\n"
 	    "successive fields of the structure should be initialized.  Only fields\n"
@@ -578,7 +578,7 @@ SCM_DEFINE (scm_make_vtable_vtable, "make-vtable-vtable", 2, 0, 1,
 	    "@var{user-fields} is a string describing user defined fields of the\n"
 	    "vtable beginning at index @code{vtable-offset-user}\n"
 	    "(see @code{make-struct-layout}).\n\n"
-	    "@var{tail-size} specifies the size of the tail-array (if any) of\n"
+	    "@var{tail_array_size} specifies the size of the tail-array (if any) of\n"
 	    "this vtable.\n\n"
 	    "@var{init1}, @dots{} are the optional initializers for the fields of\n"
 	    "the vtable.\n\n"
@@ -771,10 +771,15 @@ scm_i_struct_equalp (SCM s1, SCM s2)
 
 SCM_DEFINE (scm_struct_ref, "struct-ref", 2, 0, 0,
             (SCM handle, SCM pos),
-	    "Access the @var{n}th field of @var{struct}.\n\n"
-	    "If the field is of type 'p', then it can be set to an arbitrary value.\n\n"
-	    "If the field is of type 'u', then it can only be set to a non-negative\n"
-	    "integer value small enough to fit in one machine word.")
+	    "Access the @var{pos}th field of struct associated with\n"
+	    "@var{handle}.\n"
+	    "\n"
+	    "If the field is of type 'p', then it can be set to an arbitrary\n"
+	    "value.\n"
+	    "\n"
+	    "If the field is of type 'u', then it can only be set to a\n"
+	    "non-negative integer value small enough to fit in one machine\n"
+	    "word.")
 #define FUNC_NAME s_scm_struct_ref
 {
   SCM vtable, answer = SCM_UNDEFINED;
@@ -943,7 +948,8 @@ SCM_DEFINE (scm_struct_set_x, "struct-set!", 3, 0, 0,
 
 SCM_DEFINE (scm_struct_vtable, "struct-vtable", 1, 0, 0, 
             (SCM handle),
-	    "Return the vtable structure that describes the type of @var{struct}.")
+	    "Return the vtable structure that describes the type of struct\n"
+	    "associated with @var{handle}.")
 #define FUNC_NAME s_scm_struct_vtable
 {
   SCM_VALIDATE_STRUCT (1, handle);
diff --git a/libguile/symbols.c b/libguile/symbols.c
index 9cb300a..fd7e214 100644
--- a/libguile/symbols.c
+++ b/libguile/symbols.c
@@ -422,7 +422,7 @@ SCM_DEFINE (scm_symbol_hash, "symbol-hash", 1, 0, 0,
 
 SCM_DEFINE (scm_symbol_fref, "symbol-fref", 1, 0, 0, 
            (SCM s),
-	    "Return the contents of @var{symbol}'s @dfn{function slot}.")
+	    "Return the contents of the symbol @var{s}'s @dfn{function slot}.")
 #define FUNC_NAME s_scm_symbol_fref
 {
   SCM_VALIDATE_SYMBOL (1, s);
@@ -433,7 +433,8 @@ SCM_DEFINE (scm_symbol_fref, "symbol-fref", 1, 0, 0,
 
 SCM_DEFINE (scm_symbol_pref, "symbol-pref", 1, 0, 0, 
            (SCM s),
-	    "Return the @dfn{property list} currently associated with @var{symbol}.")
+	    "Return the @dfn{property list} currently associated with the\n"
+	    "symbol @var{s}.")
 #define FUNC_NAME s_scm_symbol_pref
 {
   SCM_VALIDATE_SYMBOL (1, s);
@@ -444,7 +445,7 @@ SCM_DEFINE (scm_symbol_pref, "symbol-pref", 1, 0, 0,
 
 SCM_DEFINE (scm_symbol_fset_x, "symbol-fset!", 2, 0, 0, 
            (SCM s, SCM val),
-	    "Change the binding of @var{symbol}'s function slot.")
+	    "Change the binding of the symbol @var{s}'s function slot.")
 #define FUNC_NAME s_scm_symbol_fset_x
 {
   SCM_VALIDATE_SYMBOL (1, s);
@@ -456,7 +457,7 @@ SCM_DEFINE (scm_symbol_fset_x, "symbol-fset!", 2, 0, 0,
 
 SCM_DEFINE (scm_symbol_pset_x, "symbol-pset!", 2, 0, 0,
            (SCM s, SCM val),
-	    "Change the binding of @var{symbol}'s property slot.")
+	    "Change the binding of the symbol @var{s}'s property slot.")
 #define FUNC_NAME s_scm_symbol_pset_x
 {
   SCM_VALIDATE_SYMBOL (1, s);
diff --git a/libguile/threads.c b/libguile/threads.c
index 0dba50f..469806e 100644
--- a/libguile/threads.c
+++ b/libguile/threads.c
@@ -1469,11 +1469,12 @@ SCM scm_lock_mutex (SCM mx)
 
 SCM_DEFINE (scm_lock_mutex_timed, "lock-mutex", 1, 2, 0,
 	    (SCM m, SCM timeout, SCM owner),
-"Lock @var{mutex}. If the mutex is already locked, the calling thread "
-"blocks until the mutex becomes available. The function returns when "
-"the calling thread owns the lock on @var{mutex}.  Locking a mutex that "
-"a thread already owns will succeed right away and will not block the "
-"thread.  That is, Guile's mutexes are @emph{recursive}. ")
+	    "Lock mutex @var{m}. If the mutex is already locked, the calling\n"
+	    "thread blocks until the mutex becomes available. The function\n"
+	    "returns when the calling thread owns the lock on @var{m}.\n"
+	    "Locking a mutex that a thread already owns will succeed right\n"
+	    "away and will not block the thread.  That is, Guile's mutexes\n"
+	    "are @emph{recursive}.")
 #define FUNC_NAME s_scm_lock_mutex_timed
 {
   SCM exception;
@@ -1782,9 +1783,9 @@ SCM_DEFINE (scm_make_condition_variable, "make-condition-variable", 0, 0, 0,
 
 SCM_DEFINE (scm_timed_wait_condition_variable, "wait-condition-variable", 2, 1, 0,
 	    (SCM cv, SCM mx, SCM t),
-"Wait until @var{cond-var} has been signalled.  While waiting, "
-"@var{mutex} is atomically unlocked (as with @code{unlock-mutex}) and "
-"is locked again when this function returns.  When @var{time} is given, "
+"Wait until condition variable @var{cv} has been signalled.  While waiting, "
+"mutex @var{mx} is atomically unlocked (as with @code{unlock-mutex}) and "
+"is locked again when this function returns.  When @var{t} is given, "
 "it specifies a point in time where the waiting should be aborted.  It "
 "can be either a integer as returned by @code{current-time} or a pair "
 "as returned by @code{gettimeofday}.  When the waiting is aborted the "
diff --git a/libguile/weak-table.c b/libguile/weak-table.c
index 47d65e6..990f7ef 100644
--- a/libguile/weak-table.c
+++ b/libguile/weak-table.c
@@ -1058,7 +1058,7 @@ SCM_DEFINE (scm_make_weak_key_hash_table, "make-weak-key-hash-table", 0, 1, 0,
 	    (SCM n),
 	    "@deffnx {Scheme Procedure} make-weak-value-hash-table size\n"
 	    "@deffnx {Scheme Procedure} make-doubly-weak-hash-table size\n"
-	    "Return a weak hash table with @var{size} buckets.\n"
+	    "Return a weak hash table with @var{n} buckets.\n"
 	    "\n"
 	    "You can modify weak hash tables in exactly the same way you\n"
 	    "would modify regular hash tables. (@pxref{Hash Tables})")
@@ -1072,7 +1072,7 @@ SCM_DEFINE (scm_make_weak_key_hash_table, "make-weak-key-hash-table", 0, 1, 0,
 
 SCM_DEFINE (scm_make_weak_value_hash_table, "make-weak-value-hash-table", 0, 1, 0, 
             (SCM n),
-	    "Return a hash table with weak values with @var{size} buckets.\n"
+	    "Return a hash table with weak values with @var{n} buckets.\n"
 	    "(@pxref{Hash Tables})")
 #define FUNC_NAME s_scm_make_weak_value_hash_table
 {
@@ -1084,7 +1084,7 @@ SCM_DEFINE (scm_make_weak_value_hash_table, "make-weak-value-hash-table", 0, 1,
 
 SCM_DEFINE (scm_make_doubly_weak_hash_table, "make-doubly-weak-hash-table", 1, 0, 0, 
             (SCM n),
-	    "Return a hash table with weak keys and values with @var{size}\n"
+	    "Return a hash table with weak keys and values with @var{n}\n"
 	    "buckets.  (@pxref{Hash Tables})")
 #define FUNC_NAME s_scm_make_doubly_weak_hash_table
 {
diff --git a/libguile/weak-vector.c b/libguile/weak-vector.c
index f829d36..0d3bd91 100644
--- a/libguile/weak-vector.c
+++ b/libguile/weak-vector.c
@@ -87,7 +87,7 @@ SCM_DEFINE (scm_weak_vector, "weak-vector", 0, 0, 1,
 	    "@deffnx {Scheme Procedure} list->weak-vector lst\n"
 	    "Construct a weak vector from a list: @code{weak-vector} uses\n"
 	    "the list of its arguments while @code{list->weak-vector} uses\n"
-	    "its only argument @var{l} (a list) to construct a weak vector\n"
+	    "its only argument @var{lst} (a list) to construct a weak vector\n"
 	    "the same way @code{list->vector} would.")
 #define FUNC_NAME s_scm_weak_vector
 {
-- 
1.7.8.3

From b7b9b2b37a2f5bb4928505fe271767f89c851d08 Mon Sep 17 00:00:00 2001
From: Bake Timmons <[email-masked]>
Date: Wed, 11 Jan 2012 23:55:18 -0500
Subject: [PATCH] Improve the usage of variable names in Scheme docstrings.

* module/ice-9/boot-9.scm:
* module/ice-9/popen.scm:
* module/ice-9/pretty-print.scm:
* module/ice-9/r4rs.scm:
* module/rnrs/io/ports.scm:
* module/texinfo/string-utils.scm:
* module/web/http.scm:
* module/web/request.scm:
* module/web/response.scm:
* test-suite/vm/run-vm-tests.scm: Make the variable names in Scheme docstrings more
  consistent.  Replace a few instances of @var with @code when appropriate.
---
 module/ice-9/boot-9.scm         |    2 +-
 module/ice-9/popen.scm          |    4 ++--
 module/ice-9/pretty-print.scm   |    2 +-
 module/ice-9/r4rs.scm           |   10 +++++-----
 module/rnrs/io/ports.scm        |    2 +-
 module/texinfo/string-utils.scm |    4 ++--
 module/web/http.scm             |    2 +-
 module/web/request.scm          |    2 +-
 module/web/response.scm         |    2 +-
 test-suite/vm/run-vm-tests.scm  |    2 +-
 10 files changed, 16 insertions(+), 16 deletions(-)

diff --git a/module/ice-9/boot-9.scm b/module/ice-9/boot-9.scm
index 1de5edf..e220db2 100644
--- a/module/ice-9/boot-9.scm
+++ b/module/ice-9/boot-9.scm
@@ -161,7 +161,7 @@ non-locally, that exit determines the continuation."
   (set! with-throw-handler
         (lambda (k thunk pre-unwind-handler)
           "Add @var{handler} to the dynamic context as a throw handler
-for key @var{key}, then invoke @var{thunk}."
+for key @var{k}, then invoke @var{thunk}."
           (if (not (or (symbol? k) (eqv? k #t)))
               (scm-error "with-throw-handler" 'wrong-type-arg
                          "Wrong type argument in position ~a: ~a"
diff --git a/module/ice-9/popen.scm b/module/ice-9/popen.scm
index b3def4a..b9debd4 100644
--- a/module/ice-9/popen.scm
+++ b/module/ice-9/popen.scm
@@ -136,7 +136,7 @@
   "Executes the program @var{command} with optional arguments
 @var{args} (all strings) in a subprocess.
 A port to the process (based on pipes) is created and returned.
-@var{modes} specifies whether an input, an output or an input-output
+@var{mode} specifies whether an input, an output or an input-output
 port to the process is created: it should be the value of
 @code{OPEN_READ}, @code{OPEN_WRITE} or @code{OPEN_BOTH}."
   (let* ((port/pid (apply open-process mode command args))
@@ -148,7 +148,7 @@ port to the process is created: it should be the value of
 (define (open-pipe command mode)
   "Executes the shell command @var{command} (a string) in a subprocess.
 A port to the process (based on pipes) is created and returned.
-@var{modes} specifies whether an input, an output or an input-output
+@var{mode} specifies whether an input, an output or an input-output
 port to the process is created: it should be the value of
 @code{OPEN_READ}, @code{OPEN_WRITE} or @code{OPEN_BOTH}."
   (open-pipe* mode "/bin/sh" "-c" command))
diff --git a/module/ice-9/pretty-print.scm b/module/ice-9/pretty-print.scm
index 5ea66c7..8a0c0b8 100644
--- a/module/ice-9/pretty-print.scm
+++ b/module/ice-9/pretty-print.scm
@@ -298,7 +298,7 @@ port directly after OBJ, like (pretty-print OBJ PORT)."
                           (width 79)
                           (display? #f)
                           (breadth-first? #f))
-  "Print @var{obj}, truncating the output, if necessary, to make it fit
+  "Print @var{x}, truncating the output, if necessary, to make it fit
 into @var{width} characters. By default, @var{x} will be printed using
 @code{write}, though that behavior can be overriden via the
 @var{display?} keyword argument.
diff --git a/module/ice-9/r4rs.scm b/module/ice-9/r4rs.scm
index 86b6e94..072c8c6 100644
--- a/module/ice-9/r4rs.scm
+++ b/module/ice-9/r4rs.scm
@@ -39,14 +39,14 @@
   (@call-with-values producer consumer))
 (define (dynamic-wind in thunk out)
   "All three arguments must be 0-argument procedures.
-@var{in_guard} is called, then @var{thunk}, then
-@var{out_guard}.
+Guard @var{in} is called, then @var{thunk}, then
+guard @var{out}.
 
 If, any time during the execution of @var{thunk}, the
 continuation of the @code{dynamic_wind} expression is escaped
-non-locally, @var{out_guard} is called.  If the continuation of
-the dynamic-wind is re-entered, @var{in_guard} is called.  Thus
-@var{in_guard} and @var{out_guard} may be called any number of
+non-locally, @var{out} is called.  If the continuation of
+the dynamic-wind is re-entered, @var{in} is called.  Thus
+@var{in} and @var{out} may be called any number of
 times.
 @lisp
  (define x 'normal-binding)
diff --git a/module/rnrs/io/ports.scm b/module/rnrs/io/ports.scm
index 246e46b..fddb491 100644
--- a/module/rnrs/io/ports.scm
+++ b/module/rnrs/io/ports.scm
@@ -237,7 +237,7 @@ if the port has no transcoder."
   (not (port-encoding port)))
 
 (define (textual-port? port)
-  "Always returns @var{#t}, as all ports can be used for textual I/O in
+  "Always returns @code{#t}, as all ports can be used for textual I/O in
 Guile."
   #t)
 
diff --git a/module/texinfo/string-utils.scm b/module/texinfo/string-utils.scm
index eff9143..7675149 100644
--- a/module/texinfo/string-utils.scm
+++ b/module/texinfo/string-utils.scm
@@ -160,7 +160,7 @@ characters.  Any needed padding is done by character @var{chr}, which
 defaults to @samp{#\\space}.  If @var{rchr} is provided, then the
 padding to the right will use it instead.  See the examples below.
 left and @var{rchr} on the right.  The default @var{width} is 80.  The
-default @var{lchr} and @var{rchr} is @samp{#\\space}.  The string is
+default @var{chr} and @var{rchr} is @samp{#\\space}.  The string is
 never truncated.
 @lisp
  (center-string \"Richard Todd\" 24)
@@ -392,7 +392,7 @@ in @code{make-text-wrapper}."
 
 (define (fill-string str . kwargs)
   "Wraps the text given in string @var{str} according to the parameters
-provided in @var{keywds}, or the default setting if they are not
+provided in @var{kwargs}, or the default setting if they are not
 given.  Returns a single string with the wrapped text.  Valid keyword
 arguments are discussed in @code{make-text-wrapper}."
   (string-join (apply string->wrapped-lines str kwargs)
diff --git a/module/web/http.scm b/module/web/http.scm
index b060af9..c15bc3e 100644
--- a/module/web/http.scm
+++ b/module/web/http.scm
@@ -205,7 +205,7 @@ header with name @var{sym}."
 (define (write-header sym val port)
   "Writes the given header name and value to @var{port}.  If @var{sym}
 is a known header, uses the specific writer registered for that header.
-Otherwise the value is written using @var{display}."
+Otherwise the value is written using @code{display}."
   (display (header->string sym) port)
   (display ": " port)
   ((header-writer sym) val port)
diff --git a/module/web/request.scm b/module/web/request.scm
index c9204a4..8259887 100644
--- a/module/web/request.scm
+++ b/module/web/request.scm
@@ -217,7 +217,7 @@ on @var{port}, perhaps using some transfer encoding."
                             (bytevector-length bv) nbytes))))))
 
 (define (write-request-body r bv)
-  "Write @var{body}, a bytevector, to the port corresponding to the HTTP
+  "Write @var{bv}, a bytevector, to the port corresponding to the HTTP
 request @var{r}."
   (put-bytevector (request-port r) bv))
 
diff --git a/module/web/response.scm b/module/web/response.scm
index 6283772..f49a602 100644
--- a/module/web/response.scm
+++ b/module/web/response.scm
@@ -226,7 +226,7 @@ on @var{port}, perhaps using some transfer encoding."
                             (bytevector-length bv) nbytes))))))
 
 (define (write-response-body r bv)
-  "Write @var{body}, a bytevector, to the port corresponding to the HTTP
+  "Write @var{bv}, a bytevector, to the port corresponding to the HTTP
 response @var{r}."
   (put-bytevector (response-port r) bv))
 
diff --git a/test-suite/vm/run-vm-tests.scm b/test-suite/vm/run-vm-tests.scm
index f23dff6..9304e81 100644
--- a/test-suite/vm/run-vm-tests.scm
+++ b/test-suite/vm/run-vm-tests.scm
@@ -67,7 +67,7 @@ it succeeded."
 (define (run-vm-tests files)
   "For each file listed in @var{files}, load it and run it through both the
 interpreter and the VM (after having it compiled).  Both results must be
-equal in the sense of @var{equal?}."
+equal in the sense of @code{equal?}."
   (let* ((res (map (lambda (file)
 		     (format #t "running `~a'...  " file)
 		     (if (catch #t
-- 
1.7.8.3