bug#10481: Simple patches to Texinfo docs

bug#10481: Simple patches to Texinfo docs

[Bake Timmons]

[-- Attachment #1: Type: text/plain, Size: 1035 bytes --]

Hi,

Months ago I proposed some improvements to the manual.  With a gentle
reminder from Andy Wingo, I have finally started breaking up my original
giant patch into some manageable patches.  The first patch is nearly
trivial, and the second is simple changes to many files.

The second patch tries to make the usage of variable names more
consistent and goes after simple, blatant cases.  A hypothetical
example is

@deffn {Scheme Procedure} bitvector-ref vec idx
@deffnx {C Function} scm_bitvector_ref (vec, idx)
Return the element at index @var{idx} of the bit vector
@var{vector}.
@end deffn

We change "vector" to "vec" or vice versa.  There are a few cases where
names that are consistently used *within* a definition are still changed
to conform with usage in surrounding function definitions.

One way I plan to shorten patches is based on the kind of files to be
patched, .texinfo, .scm, .c, etc.  Thus, the next patches I will send
will be similar changes for docstrings in .scm and .c files.

Thanks for any comments!

Bake


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: Fix unbalanced parentheses in Texinfo docs --]
[-- Type: text/x-diff, Size: 1254 bytes --]

From 6ead0b10889e2446e563b2bb434fb20982e9dac9 Mon Sep 17 00:00:00 2001
From: Bake Timmons <b3timmons@speedymail.org>
Date: Wed, 11 Jan 2012 09:30:57 -0500
Subject: [PATCH] Fix unbalanced parentheses in docs.

* doc/ref/sxml-match.texi (sxml-match-let, sxml-match-let*): Remove
  extraneous parenthesis at end of Texinfo function definition header.
---
 doc/ref/sxml-match.texi |    4 ++--
 1 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/doc/ref/sxml-match.texi b/doc/ref/sxml-match.texi
index 7b82e11..cf5c5d3 100644
--- a/doc/ref/sxml-match.texi
+++ b/doc/ref/sxml-match.texi
@@ -356,8 +356,8 @@ transformation that formats a ``TV Guide'' into HTML.
 
 @unnumberedsubsec @code{sxml-match-let} and @code{sxml-match-let*}
 
-@deffn {Scheme Syntax} sxml-match-let ((pat expr) ...) expression0 expression ...)
-@deffnx {Scheme Syntax} sxml-match-let* ((pat expr) ...) expression0 expression ...)
+@deffn {Scheme Syntax} sxml-match-let ((pat expr) ...) expression0 expression ...
+@deffnx {Scheme Syntax} sxml-match-let* ((pat expr) ...) expression0 expression ...
 These forms generalize the @code{let} and @code{let*} forms of Scheme to allow
 an XML pattern in the binding position, rather than a simple variable.
 @end deffn
-- 
1.7.8.3


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #3: Make variable name usage more consistent in Texinfo docs --]
[-- Type: text/x-diff, Size: 60050 bytes --]

From 827aeffa7332c59178d006072f08d278c2e5179e Mon Sep 17 00:00:00 2001
From: Bake Timmons <b3timmons@speedymail.org>
Date: Wed, 11 Jan 2012 12:02:57 -0500
Subject: [PATCH] Make consistent the usage of variable names in the function
 definitions found in the Texinfo docs.

* doc/r5rs/r5rs.texi:
* doc/ref/api-compound.texi:
* doc/ref/api-data.texi:
* doc/ref/api-debug.texi:
* doc/ref/api-evaluation.texi:
* doc/ref/api-io.texi:
* doc/ref/api-modules.texi:
* doc/ref/api-procedures.texi:
* doc/ref/api-scheduling.texi:
* doc/ref/api-smobs.texi:
* doc/ref/compiler.texi:
* doc/ref/misc-modules.texi:
* doc/ref/posix.texi:
* doc/ref/scheme-using.texi:
* doc/ref/srfi-modules.texi:
* doc/ref/vm.texi:
* doc/ref/web.texi:
* doc/sources/env.texi: Make usage of variable names of function definitions
  more consistent.
---
 doc/r5rs/r5rs.texi          |   43 +++++++++++++--------------
 doc/ref/api-compound.texi   |   66 +++++++++++++++++++++---------------------
 doc/ref/api-data.texi       |   18 ++++++------
 doc/ref/api-debug.texi      |    6 ++--
 doc/ref/api-evaluation.texi |    6 ++--
 doc/ref/api-io.texi         |   56 ++++++++++++++++++------------------
 doc/ref/api-modules.texi    |    4 +-
 doc/ref/api-procedures.texi |    4 +-
 doc/ref/api-scheduling.texi |   39 ++++++++++++-------------
 doc/ref/api-smobs.texi      |   10 +++---
 doc/ref/compiler.texi       |    4 +-
 doc/ref/misc-modules.texi   |    6 ++--
 doc/ref/posix.texi          |   66 +++++++++++++++++++++---------------------
 doc/ref/scheme-using.texi   |    6 ++--
 doc/ref/srfi-modules.texi   |   10 +++---
 doc/ref/vm.texi             |    6 ++--
 doc/ref/web.texi            |    8 ++--
 doc/sources/env.texi        |    4 +-
 18 files changed, 180 insertions(+), 182 deletions(-)

diff --git a/doc/r5rs/r5rs.texi b/doc/r5rs/r5rs.texi
index b7722c1..a71755b 100644
--- a/doc/r5rs/r5rs.texi
+++ b/doc/r5rs/r5rs.texi
@@ -4615,7 +4615,7 @@ implementation-dependent range.  See section @ref{Implementation restrictions}.
 @deffn {procedure} number->string  z
 @deffnx {procedure} number->string  z radix
 
-@var{Radix} must be an exact integer, either 2, 8, 10, or 16.  If omitted,
+@var{radix} must be an exact integer, either 2, 8, 10, or 16.  If omitted,
 @var{radix} defaults to 10.
 The procedure @samp{number->string} takes a
 number and a radix and returns as a string an external representation of
@@ -4674,7 +4674,7 @@ allows for infinities, NaNs, and non-flonum representations.
 @c  for the third argument.
 
 Returns a number of the maximally precise representation expressed by the
-given @var{string}.  @var{Radix} must be an exact integer, either 2, 8, 10,
+given @var{string}.  @var{radix} must be an exact integer, either 2, 8, 10,
 or 16.  If supplied, @var{radix} is a default radix that may be overridden
 by an explicit radix prefix in @var{string} (e.g. @t{"#o177"}).  If @var{radix}
 is not supplied, then the default radix is 10.  If @var{string} is not
@@ -5381,7 +5381,7 @@ returned.  @samp{Memq} uses @samp{eq?} to compare @var{obj} with the elements of
 @deffnx {library procedure} assv  obj alist
 @deffnx {library procedure} assoc  obj alist
 
-@var{Alist} (for ``association list'') must be a list of
+@var{alist} (for ``association list'') must be a list of
 pairs.  These procedures find the first pair in @var{alist} whose car field is @var{obj},
 and returns that pair.  If no pair in @var{alist} has @var{obj} as its
 car, then @t{#f} (not the empty list) is returned.  @samp{Assq} uses
@@ -5830,10 +5830,9 @@ Returns @t{#t} if @var{obj} is a string, otherwise returns @t{#f}.
 
 @c \domain{\vr{k} must be a non-negative integer, and \var{char} must be
 @c a character.}  
-@samp{Make-string} returns a newly allocated string of
-length @var{k}.  If @var{char} is given, then all elements of the string
-are initialized to @var{char}, otherwise the contents of the
-@var{string} are unspecified.
+@samp{Make-string} returns a newly allocated string of length @var{k}.
+If @var{char} is given, then all elements of the string are initialized
+to @var{char}, otherwise the contents of the string are unspecified.
 
 @end deffn
 
@@ -5927,7 +5926,7 @@ the corresponding numerical predicates.
 
 @deffn {library procedure} substring  string start end
 
-@var{String} must be a string, and @var{start} and @var{end}
+@var{string} must be a string, and @var{start} and @var{end}
 must be exact integers satisfying
 
 
@@ -6194,7 +6193,7 @@ Returns @t{#t} if @var{obj} is a procedure, otherwise returns @t{#f}.
 
 @deffn {procedure} apply  proc arg1 @dots{} args
 
-@var{Proc} must be a procedure and @var{args} must be a list.
+@var{proc} must be a procedure and @var{args} must be a list.
 Calls @var{proc} with the elements of the list
 @samp{(append (list @var{arg1} @dots{},) @var{args})} as the actual
 arguments.
@@ -6466,7 +6465,7 @@ and @samp{+}:
 
 @deffn {procedure} call-with-current-continuation  proc
 
- @var{Proc} must be a procedure of one
+ @var{proc} must be a procedure of one
 argument. The procedure @samp{call-with-current-continuation} packages
 up the current continuation (see the rationale below) as an ``escape
 procedure'' and passes it as an argument to
@@ -6616,11 +6615,11 @@ continuation of the call to @t{call-with-values}.
 @deffn {procedure} dynamic-wind  before thunk after
 
 Calls @var{thunk} without arguments, returning the result(s) of this call.
-@var{Before} and @var{after} are called, also without arguments, as required
+@var{before} and @var{after} are called, also without arguments, as required
 by the following rules (note that in the absence of calls to continuations
 captured using @code{call-with-current-continuation} the three arguments are
 @vindex @w{call-with-current-continuation}
-called once each, in order).  @var{Before} is called whenever execution
+called once each, in order).  @var{before} is called whenever execution
 enters the dynamic extent of the call to @var{thunk} and @var{after} is called
 whenever it exits that dynamic extent.  The dynamic extent of a procedure
 call is the period between when the call is initiated and when it
@@ -6703,7 +6702,7 @@ extent of a call to @var{before} or @var{after} is undefined.
 @deffn {procedure} eval  expression environment-specifier
 
 Evaluates @var{expression} in the specified environment and returns its value.
-@var{Expression} must be a valid Scheme expression represented as data,
+@var{expression} must be a valid Scheme expression represented as data,
 and @var{environment-specifier} must be a value returned by one of the
 three procedures described below.
 Implementations may extend @samp{eval} to allow non-expression programs
@@ -6731,7 +6730,7 @@ allowed to create new bindings in the environments associated with
 @deffn {procedure} scheme-report-environment  version
 @deffnx {procedure} null-environment  version
 
-@var{Version} must be the exact integer @samp{5},
+@var{version} must be the exact integer @samp{5},
 corresponding to this revision of the Scheme report (the
 Revised^5 Report on Scheme).
 @samp{Scheme-report-environment} returns a specifier for an
@@ -6797,7 +6796,7 @@ Haase: Mention that there are alternatives to files?
 @deffn {library procedure} call-with-input-file  string proc
 @deffnx {library procedure} call-with-output-file  string proc
 
-@var{String} should be a string naming a file, and
+@var{string} should be a string naming a file, and
 @var{proc} should be a procedure that accepts one argument.
 For @samp{call-with-input-file},
 the file should already exist; for
@@ -6862,8 +6861,8 @@ Returns the current default input or output port.
 @deffn {optional procedure} with-input-from-file  string thunk
 @deffnx {optional procedure} with-output-to-file  string thunk
 
-@var{String} should be a string naming a file, and
-@var{proc} should be a procedure of no arguments.
+@var{string} should be a string naming a file, and
+@var{thunk} should be a procedure of no arguments.
 For @samp{with-input-from-file},
 the file should already exist; for
 @samp{with-output-to-file},
@@ -6999,7 +6998,7 @@ a closed port.
 
 Returns the next character available from the input @var{port}, updating
 the @var{port} to point to the following character.  If no more characters
-are available, an end of file object is returned.  @var{Port} may be
+are available, an end of file object is returned.  @var{port} may be
 omitted, in which case it defaults to the value returned by @samp{current-input-port}.
 
 @end deffn
@@ -7012,7 +7011,7 @@ omitted, in which case it defaults to the value returned by @samp{current-input-
 Returns the next character available from the input @var{port},
 @emph{without} updating
 the @var{port} to point to the following character.  If no more characters
-are available, an end of file object is returned.  @var{Port} may be
+are available, an end of file object is returned.  @var{port} may be
 omitted, in which case it defaults to the value returned by @samp{current-input-port}.
 
 
@@ -7050,7 +7049,7 @@ Returns @t{#t} if a character is ready on the input @var{port} and
 returns @t{#f} otherwise.  If @samp{char-ready} returns @t{#t} then
 the next @samp{read-char} operation on the given @var{port} is guaranteed
 not to hang.  If the @var{port} is at end of file then @samp{char-ready?}
-returns @t{#t}.  @var{Port} may be omitted, in which case it defaults to
+returns @t{#t}.  @var{port} may be omitted, in which case it defaults to
 the value returned by @samp{current-input-port}.
 
 
@@ -7163,7 +7162,7 @@ Fix
 
 @c \domain{\var{Filename} should be a string naming an existing file
 @c containing Scheme source code.} The {\cf load} procedure reads
-@var{Filename} should be a string naming an existing file
+@var{filename} should be a string naming an existing file
 containing Scheme source code.  The @samp{load} procedure reads
 expressions and definitions from the file and evaluates them
 sequentially.  It is unspecified whether the results of the expressions
@@ -7186,7 +7185,7 @@ implementations.
 @deffn {optional procedure} transcript-on  filename
 @deffnx {optional procedure} transcript-off 
 
-@var{Filename} must be a string naming an output file to be
+@var{filename} must be a string naming an output file to be
 created. The effect of @samp{transcript-on} is to open the named file
 for output, and to cause a transcript of subsequent interaction between
 the user and the Scheme system to be written to the file.  The
diff --git a/doc/ref/api-compound.texi b/doc/ref/api-compound.texi
index 03891fa..765d5d4 100644
--- a/doc/ref/api-compound.texi
+++ b/doc/ref/api-compound.texi
@@ -779,15 +779,15 @@ in the vector.
 Return the number of elements in @var{vector} as an exact integer.
 @end deffn
 
-@deftypefn {C Function} size_t scm_c_vector_length (SCM v)
-Return the number of elements in @var{vector} as a @code{size_t}.
+@deftypefn {C Function} size_t scm_c_vector_length (SCM vec)
+Return the number of elements in @var{vec} as a @code{size_t}.
 @end deftypefn
 
 @rnindex vector-ref
-@deffn {Scheme Procedure} vector-ref vector k
-@deffnx {C Function} scm_vector_ref vector k
-Return the contents of position @var{k} of @var{vector}.
-@var{k} must be a valid index of @var{vector}.
+@deffn {Scheme Procedure} vector-ref vec k
+@deffnx {C Function} scm_vector_ref vec k
+Return the contents of position @var{k} of @var{vec}.
+@var{k} must be a valid index of @var{vec}.
 @lisp
 (vector-ref '#(1 1 2 3 5 8 13 21) 5) @result{} 8
 (vector-ref '#(1 1 2 3 5 8 13 21)
@@ -798,9 +798,9 @@ Return the contents of position @var{k} of @var{vector}.
 @end lisp
 @end deffn
 
-@deftypefn {C Function} SCM scm_c_vector_ref (SCM v, size_t k)
+@deftypefn {C Function} SCM scm_c_vector_ref (SCM vec, size_t k)
 Return the contents of position @var{k} (a @code{size_t}) of
-@var{vector}.
+@var{vec}.
 @end deftypefn
 
 A vector created by one of the dynamic vector constructor procedures
@@ -813,10 +813,10 @@ considered as constants.  Currently, however, Guile does not detect this
 error.
 
 @rnindex vector-set!
-@deffn {Scheme Procedure} vector-set! vector k obj
-@deffnx {C Function} scm_vector_set_x vector k obj
-Store @var{obj} in position @var{k} of @var{vector}.
-@var{k} must be a valid index of @var{vector}.
+@deffn {Scheme Procedure} vector-set! vec k obj
+@deffnx {C Function} scm_vector_set_x vec k obj
+Store @var{obj} in position @var{k} of @var{vec}.
+@var{k} must be a valid index of @var{vec}.
 The value returned by @samp{vector-set!} is unspecified.
 @lisp
 (let ((vec (vector 0 '(2 2 2 2) "Anna")))
@@ -825,14 +825,14 @@ The value returned by @samp{vector-set!} is unspecified.
 @end lisp
 @end deffn
 
-@deftypefn {C Function} void scm_c_vector_set_x (SCM v, size_t k, SCM obj)
-Store @var{obj} in position @var{k} (a @code{size_t}) of @var{v}.
+@deftypefn {C Function} void scm_c_vector_set_x (SCM vec, size_t k, SCM obj)
+Store @var{obj} in position @var{k} (a @code{size_t}) of @var{vec}.
 @end deftypefn
 
 @rnindex vector-fill!
-@deffn {Scheme Procedure} vector-fill! v fill
-@deffnx {C Function} scm_vector_fill_x (v, fill)
-Store @var{fill} in every position of @var{vector}.  The value
+@deffn {Scheme Procedure} vector-fill! vec fill
+@deffnx {C Function} scm_vector_fill_x (vec, fill)
+Store @var{fill} in every position of @var{vec}.  The value
 returned by @code{vector-fill!} is unspecified.
 @end deffn
 
@@ -1031,7 +1031,7 @@ Return the element at index @var{idx} of the bitvector
 @var{vec}.
 @end deffn
 
-@deftypefn {C Function} SCM scm_c_bitvector_ref (SCM obj, size_t idx)
+@deftypefn {C Function} SCM scm_c_bitvector_ref (SCM vec, size_t idx)
 Return the element at index @var{idx} of the bitvector
 @var{vec}.
 @end deftypefn
@@ -1042,7 +1042,7 @@ Set the element at index @var{idx} of the bitvector
 @var{vec} when @var{val} is true, else clear it.
 @end deffn
 
-@deftypefn {C Function} SCM scm_c_bitvector_set_x (SCM obj, size_t idx, SCM val)
+@deftypefn {C Function} SCM scm_c_bitvector_set_x (SCM vec, size_t idx, SCM val)
 Set the element at index @var{idx} of the bitvector
 @var{vec} when @var{val} is true, else clear it.
 @end deftypefn
@@ -1427,8 +1427,8 @@ stored in the variable @code{*unspecified*} so that for example
 @code{(make-typed-array 'u32 *unspecified* 4)} creates a uninitialized
 @code{u32} vector of length 4.
 
-Each @var{bound} may be a positive non-zero integer @var{N}, in which
-case the index for that dimension can range from 0 through @var{N-1}; or
+Each @var{bound} may be a positive non-zero integer @var{n}, in which
+case the index for that dimension can range from 0 through @var{n}-1; or
 an explicit index range specifier in the form @code{(LOWER UPPER)},
 where both @var{lower} and @var{upper} are integers, possibly less than
 zero, and possibly the same number (however, @var{lower} cannot be
@@ -1512,8 +1512,8 @@ For example,
 @end example
 @end deffn
 
-@deffn {Scheme Procedure} array-rank obj
-@deffnx {C Function} scm_array_rank (obj)
+@deffn {Scheme Procedure} array-rank array
+@deffnx {C Function} scm_array_rank (array)
 Return the rank of @var{array}.
 @end deffn
 
@@ -1625,10 +1625,10 @@ $\left(\matrix{%
 
 @deffn {Scheme Procedure} uniform-array-read! ra [port_or_fd [start [end]]]
 @deffnx {C Function} scm_uniform_array_read_x (ra, port_or_fd, start, end)
-Attempt to read all elements of @var{ura}, in lexicographic order, as
-binary objects from @var{port-or-fdes}.
+Attempt to read all elements of array @var{ra}, in lexicographic order, as
+binary objects from @var{port_or_fd}.
 If an end of file is encountered,
-the objects up to that point are put into @var{ura}
+the objects up to that point are put into @var{ra}
 (starting at the beginning) and the remainder of the array is
 unchanged.
 
@@ -1637,21 +1637,21 @@ a specified region of a vector (or linearized array) to be read,
 leaving the remainder of the vector unchanged.
 
 @code{uniform-array-read!} returns the number of objects read.
-@var{port-or-fdes} may be omitted, in which case it defaults to the value
+@var{port_or_fd} may be omitted, in which case it defaults to the value
 returned by @code{(current-input-port)}.
 @end deffn
 
-@deffn {Scheme Procedure} uniform-array-write v [port_or_fd [start [end]]]
-@deffnx {C Function} scm_uniform_array_write (v, port_or_fd, start, end)
-Writes all elements of @var{ura} as binary objects to
-@var{port-or-fdes}.
+@deffn {Scheme Procedure} uniform-array-write ra [port_or_fd [start [end]]]
+@deffnx {C Function} scm_uniform_array_write (ra, port_or_fd, start, end)
+Writes all elements of @var{ra} as binary objects to
+@var{port_or_fd}.
 
 The optional arguments @var{start}
 and @var{end} allow
 a specified region of a vector (or linearized array) to be written.
 
 The number of objects actually written is returned.
-@var{port-or-fdes} may be
+@var{port_or_fd} may be
 omitted, in which case it defaults to the value returned by
 @code{(current-output-port)}.
 @end deffn
@@ -1663,7 +1663,7 @@ omitted, in which case it defaults to the value returned by
 @deffnx {C Function} scm_make_shared_array (oldarray, mapfunc, boundlist)
 Return a new array which shares the storage of @var{oldarray}.
 Changes made through either affect the same underlying storage.  The
-@var{bound@dots{}} arguments are the shape of the new array, the same
+@var{bound} @dots{} arguments are the shape of the new array, the same
 as @code{make-array} (@pxref{Array Procedures}).
 
 @var{mapfunc} translates coordinates from the new array to the
diff --git a/doc/ref/api-data.texi b/doc/ref/api-data.texi
index f2450ce..ced5ad3 100644
--- a/doc/ref/api-data.texi
+++ b/doc/ref/api-data.texi
@@ -695,10 +695,10 @@ value, including the special values @samp{+nan.0}, @samp{+inf.0} and
 
 @deffn {Scheme Procedure} complex? z
 @deffnx {C Function} scm_complex_p (z)
-Return @code{#t} if @var{x} is a complex number, @code{#f}
+Return @code{#t} if @var{z} is a complex number, @code{#f}
 otherwise.  Note that the sets of real, rational and integer
 values form subsets of the set of complex numbers, i.e.@: the
-predicate will also be fulfilled if @var{x} is a real,
+predicate will also be fulfilled if @var{z} is a real,
 rational or integer number.
 @end deffn
 
@@ -2337,8 +2337,8 @@ Return @code{#t} if all given character sets are equal.
 
 @deffn {Scheme Procedure} char-set<= . char_sets
 @deffnx {C Function} scm_char_set_leq (char_sets)
-Return @code{#t} if every character set @var{cs}i is a subset
-of character set @var{cs}i+1.
+Return @code{#t} if every character set @var{char_set}i is a subset
+of character set @var{char_set}i+1.
 @end deffn
 
 @deffn {Scheme Procedure} char-set-hash cs [bound]
@@ -3105,7 +3105,7 @@ reverse order.
 Return a newly allocated string of
 length @var{k}.  If @var{chr} is given, then all elements of
 the string are initialized to @var{chr}, otherwise the contents
-of the @var{string} are unspecified.
+of the string are unspecified.
 @end deffn
 
 @deftypefn {C Function} SCM scm_c_make_string (size_t len, SCM chr)
@@ -3124,7 +3124,7 @@ produce the corresponding string element.  The order in which
 @deffn {Scheme Procedure} string-join ls [delimiter [grammar]]
 @deffnx {C Function} scm_string_join (ls, delimiter, grammar)
 Append the string in the string list @var{ls}, using the string
-@var{delim} as a delimiter between the elements of @var{ls}.
+@var{delimiter} as a delimiter between the elements of @var{ls}.
 @var{grammar} is a symbol which specifies how the delimiter is
 placed between the strings, and defaults to the symbol
 @code{infix}.
@@ -3285,7 +3285,7 @@ Return all but the last @var{n} characters of @var{s}.
 @deffnx {C Function} scm_string_pad (s, len, chr, start, end)
 @deffnx {C Function} scm_string_pad_right (s, len, chr, start, end)
 Take characters @var{start} to @var{end} from the string @var{s} and
-either pad with @var{char} or truncate them to give @var{len}
+either pad with @var{chr} or truncate them to give @var{len}
 characters.
 
 @code{string-pad} pads or truncates on the left, so for example
@@ -3593,12 +3593,12 @@ case-insensitively.
 
 @deffn {Scheme Procedure} string-hash s [bound [start [end]]]
 @deffnx {C Function} scm_substring_hash (s, bound, start, end)
-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 range [0,bound).
+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 range [0,bound).
 @end deffn
 
 @deffn {Scheme Procedure} string-hash-ci s [bound [start [end]]]
 @deffnx {C Function} scm_substring_hash_ci (s, bound, start, end)
-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 range [0,bound).
+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 range [0,bound).
 @end deffn
 
 Because the same visual appearance of an abstract Unicode character can 
diff --git a/doc/ref/api-debug.texi b/doc/ref/api-debug.texi
index bdb6166..8ba1bc9 100644
--- a/doc/ref/api-debug.texi
+++ b/doc/ref/api-debug.texi
@@ -96,7 +96,7 @@ stack frames from the top and bottom of the stack that
 @code{(@var{inner_cut_1} @var{outer_cut_1} @var{inner_cut_2}
 @var{outer_cut_2} @dots{})}.
 
-Each @var{inner_cut_N} can be @code{#t}, an integer, a prompt
+Each @var{inner_cut_i} can be @code{#t}, an integer, a prompt
 tag, or a procedure.  @code{#t} means to cut away all frames up
 to but excluding the first user module frame.  An integer means
 to cut away exactly that number of frames.  A prompt tag means
@@ -105,14 +105,14 @@ tag. A procedure means to cut away all frames up to but
 excluding the application frame whose procedure matches the
 specified one.
 
-Each @var{outer_cut_N} can be an integer, a prompt tag, or a
+Each @var{outer_cut_i} can be an integer, a prompt tag, or a
 procedure.  An integer means to cut away that number of frames.
 A prompt tag means to cut away all frames that are outside a
 prompt with the given tag. A procedure means to cut away
 frames down to but excluding the application frame whose
 procedure matches the specified one.
 
-If the @var{outer_cut_N} of the last pair is missing, it is
+If the @var{outer_cut_i} of the last pair is missing, it is
 taken as 0.
 @end deffn
 
diff --git a/doc/ref/api-evaluation.texi b/doc/ref/api-evaluation.texi
index 6a09bef..79fec78 100644
--- a/doc/ref/api-evaluation.texi
+++ b/doc/ref/api-evaluation.texi
@@ -439,10 +439,10 @@ it as code.
 @deffn {Scheme Procedure} eval exp module_or_state
 @deffnx {C Function} scm_eval (exp, module_or_state)
 Evaluate @var{exp}, a list representing a Scheme expression,
-in the top-level environment specified by @var{module}.
+in the top-level environment specified by @var{module_or_state}.
 While @var{exp} is evaluated (using @code{primitive-eval}),
-@var{module} is made the current module.  The current module
-is reset to its previous value when @var{eval} returns.
+@var{module_or_state} is made the current module.  The current module
+is reset to its previous value when @code{eval} returns.
 XXX - dynamic states.
 Example: (eval '(+ 1 2) (interaction-environment))
 @end deffn
diff --git a/doc/ref/api-io.texi b/doc/ref/api-io.texi
index 9799c31..9b52766 100644
--- a/doc/ref/api-io.texi
+++ b/doc/ref/api-io.texi
@@ -251,7 +251,7 @@ sequence when the error is raised.
 
 @deffn {Scheme Procedure} unread-char cobj [port]
 @deffnx {C Function} scm_unread_char (cobj, port)
-Place @var{char} in @var{port} so that it will be read by the
+Place character @var{cobj} in @var{port} so that it will be read by the
 next read operation.  If called multiple times, the unread characters
 will be read again in last-in first-out order.  If @var{port} is
 not supplied, the current input port is used.
@@ -343,7 +343,7 @@ the current output port.
 @var{message} can contain @code{~A} (was @code{%s}) and
 @code{~S} (was @code{%S}) escapes.  When printed,
 the escapes are replaced with corresponding members of
-@var{ARGS}:
+@var{args}:
 @code{~A} formats using @code{display} and @code{~S} formats
 using @code{write}.
 If @var{destination} is @code{#t}, then use the current output
@@ -426,7 +426,7 @@ open.
 
 @deffn {Scheme Procedure} seek fd_port offset whence
 @deffnx {C Function} scm_seek (fd_port, offset, whence)
-Sets the current position of @var{fd/port} to the integer
+Sets the current position of @var{fd_port} to the integer
 @var{offset}, which is interpreted according to the value of
 @var{whence}.
 
@@ -441,7 +441,7 @@ Seek from the current position.
 @defvar SEEK_END
 Seek from the end of the file.
 @end defvar
-If @var{fd/port} is a file descriptor, the underlying system
+If @var{fd_port} is a file descriptor, the underlying system
 call is @code{lseek}.  @var{port} may be a string port.
 
 The value returned is the new position in the file.  This means
@@ -454,7 +454,7 @@ that the current position of a port can be obtained using:
 @deffn {Scheme Procedure} ftell fd_port
 @deffnx {C Function} scm_ftell (fd_port)
 Return an integer representing the current position of
-@var{fd/port}, measured from the beginning.  Equivalent to:
+@var{fd_port}, measured from the beginning.  Equivalent to:
 
 @lisp
 (seek port 0 SEEK_CUR)
@@ -922,7 +922,7 @@ of the respective current port is restored.
 The current port setting is managed with @code{dynamic-wind}, so the
 previous value is restored no matter how @var{thunk} exits (eg.@: an
 exception), and if @var{thunk} is re-entered (via a captured
-continuation) then it's set again to the @var{FILENAME} port.
+continuation) then it's set again to the @var{filename} port.
 
 The port is closed when @var{thunk} returns normally, but not when
 exited via an exception or new continuation.  This ensures it's still
@@ -1414,7 +1414,7 @@ This condition type could be defined by
 An exception with this type is raised when one of the operations for
 textual output to a port encounters a character that cannot be
 translated into bytes by the output direction of the port's transcoder.
-@var{Char} is the character that could not be encoded.
+@var{char} is the character that could not be encoded.
 @end deffn
 
 @deffn {Scheme Syntax} error-handling-mode @var{error-handling-mode-symbol}
@@ -1430,7 +1430,7 @@ symbol acceptable as a @var{handling-mode} argument to
 raised.
 
 @quotation Note
-  Only the name of @var{error-handling-style-symbol} is significant.
+  Only the name of @var{error-handling-mode-symbol} is significant.
 @end quotation
 
 The error-handling mode of a transcoder specifies the behavior
@@ -1470,7 +1470,7 @@ symbol; and @var{handling-mode}, if present, an error-handling-mode
 symbol.
 
 @var{eol-style} may be omitted, in which case it defaults to the native
-end-of-line style of the underlying platform.  @var{Handling-mode} may
+end-of-line style of the underlying platform.  @var{handling-mode} may
 be omitted, in which case it defaults to @code{replace}.  The result is
 a transcoder with the behavior specified by its arguments.
 @end deffn
@@ -1566,11 +1566,11 @@ encoding.  Likewise, Guile does not prevent use of
 @end deffn
 
 @deffn {Scheme Procedure} textual-port? port
-Always return @var{#t}, as all ports can be used for textual I/O in
+Always return @code{#t}, as all ports can be used for textual I/O in
 Guile.
 @end deffn
 
-@deffn {Scheme Procedure} transcoded-port obj
+@deffn {Scheme Procedure} transcoded-port binary-port transcoder
 The @code{transcoded-port} procedure
 returns a new textual port with the specified @var{transcoder}.
 Otherwise the new textual port's state is largely the same as
@@ -1629,12 +1629,12 @@ of @var{proc}.  Return the return values of @var{proc}.
 @node R6RS Input Ports
 @subsubsection Input Ports
 
-@deffn {Scheme Procedure} input-port? obj@
+@deffn {Scheme Procedure} input-port? obj
 Returns @code{#t} if the argument is an input port (or a combined input
 and output port), and returns @code{#f} otherwise.
 @end deffn
 
-@deffn {Scheme Procedure} port-eof? port
+@deffn {Scheme Procedure} port-eof? input-port
 Returns @code{#t}
 if the @code{lookahead-u8} procedure (if @var{input-port} is a binary port)
 or the @code{lookahead-char} procedure (if @var{input-port} is a textual port)
@@ -1648,7 +1648,7 @@ but the port cannot be determined to be at end of file.
 @deffnx {Scheme Procedure} open-file-input-port filename file-options
 @deffnx {Scheme Procedure} open-file-input-port filename file-options buffer-mode
 @deffnx {Scheme Procedure} open-file-input-port filename file-options buffer-mode maybe-transcoder
-@var{Maybe-transcoder} must be either a transcoder or @code{#f}.
+@var{maybe-transcoder} must be either a transcoder or @code{#f}.
 
 The @code{open-file-input-port} procedure returns an
 input port for the named file. The @var{file-options} and
@@ -1718,13 +1718,13 @@ indicating the number of bytes read, or @code{0} to indicate the
 end-of-file.
 
 Optionally, if @var{get-position} is not @code{#f}, it must be a thunk
-that will be called when @var{port-position} is invoked on the custom
+that will be called when @code{port-position} is invoked on the custom
 binary port and should return an integer indicating the position within
 the underlying data stream; if @var{get-position} was not supplied, the
-returned port does not support @var{port-position}.
+returned port does not support @code{port-position}.
 
 Likewise, if @var{set-position!} is not @code{#f}, it should be a
-one-argument procedure.  When @var{set-port-position!} is invoked on the
+one-argument procedure.  When @code{set-port-position!} is invoked on the
 custom binary input port, @var{set-position!} is passed an integer
 indicating the position of the next byte is to read.
 
@@ -1806,7 +1806,7 @@ end-of-file object (if no data were available).
 @node R6RS Textual Input
 @subsubsection Textual Input
 
-@deffn {Scheme Procedure} get-char port
+@deffn {Scheme Procedure} get-char textual-input-port
 Reads from @var{textual-input-port}, blocking as necessary, until a
 complete character is available from @var{textual-input-port},
 or until an end of file is reached.
@@ -1817,14 +1817,14 @@ point past the character. If an end of file is reached before any
 character is read, @code{get-char} returns the end-of-file object.
 @end deffn
 
-@deffn {Scheme Procedure} lookahead-char port
+@deffn {Scheme Procedure} lookahead-char textual-input-port
 The @code{lookahead-char} procedure is like @code{get-char}, but it does
 not update @var{textual-input-port} to point past the character.
 @end deffn
 
-@deffn {Scheme Procedure} get-string-n port count
+@deffn {Scheme Procedure} get-string-n textual-input-port count
 
-@var{Count} must be an exact, non-negative integer object, representing
+@var{count} must be an exact, non-negative integer object, representing
 the number of characters to be read.
 
 The @code{get-string-n} procedure reads from @var{textual-input-port},
@@ -1840,11 +1840,11 @@ to point just past the characters read. If no characters can be read
 before an end of file, the end-of-file object is returned.
 @end deffn
 
-@deffn {Scheme Procedure} get-string-n! port string start count
+@deffn {Scheme Procedure} get-string-n! textual-input-port string start count
 
-@var{Start} and @var{count} must be exact, non-negative integer objects,
+@var{start} and @var{count} must be exact, non-negative integer objects,
 with @var{count} representing the number of characters to be read.
-@var{String} must be a string with at least $@var{start} + @var{count}$
+@var{string} must be a string with at least $@var{start} + @var{count}$
 characters.
 
 The @code{get-string-n!} procedure reads from @var{textual-input-port}
@@ -1858,7 +1858,7 @@ exact integer object. If no characters can be read before an end of
 file, the end-of-file object is returned.
 @end deffn
 
-@deffn {Scheme Procedure} get-string-all port count
+@deffn {Scheme Procedure} get-string-all textual-input-port count
 Reads from @var{textual-input-port} until an end of file, decoding
 characters in the same manner as @code{get-string-n} and
 @code{get-string-n!}.
@@ -1868,7 +1868,7 @@ all the characters decoded from that data are returned. If no character
 precedes the end of file, the end-of-file object is returned.
 @end deffn
 
-@deffn {Scheme Procedure} get-line port
+@deffn {Scheme Procedure} get-line textual-input-port
 Reads from @var{textual-input-port} up to and including the linefeed
 character or end of file, decoding characters in the same manner as
 @code{get-string-n} and @code{get-string-n!}.
@@ -1887,7 +1887,7 @@ any characters are read, the end-of-file object is returned.
 @end quotation
 @end deffn
 
-@deffn {Scheme Procedure} get-datum port count
+@deffn {Scheme Procedure} get-datum textual-input-port count
 Reads an external representation from @var{textual-input-port} and returns the
 datum it represents.  The @code{get-datum} procedure returns the next
 datum that can be parsed from the given @var{textual-input-port}, updating
@@ -2048,7 +2048,7 @@ Writes @var{char} to the port. The @code{put-char} procedure returns
 @code{put-string} procedure returns an unspecified value.
 @end deffn
 
-@deffn {Scheme Procedure} put-datum port datum
+@deffn {Scheme Procedure} put-datum textual-output-port datum
 @var{datum} should be a datum value.  The @code{put-datum} procedure
 writes an external representation of @var{datum} to
 @var{textual-output-port}.  The specific external representation is
diff --git a/doc/ref/api-modules.texi b/doc/ref/api-modules.texi
index 9830cfd..f95d90a 100644
--- a/doc/ref/api-modules.texi
+++ b/doc/ref/api-modules.texi
@@ -962,7 +962,7 @@ SCM my_eval_string (SCM str)
 Like @code{scm_public_lookup} or @code{scm_private_lookup}, but
 additionally dereferences the variable.  If the variable object is
 unbound, signals an error.  Returns the value bound to @var{name} in
-@var{module}.
+@var{module_name}.
 @end deftypefn
 
 In addition, there are a number of other lookup-related procedures.  We
@@ -1009,7 +1009,7 @@ module is used instead of the current one.
 @end deftypefn
 
 @deftypefn {C Function} SCM scm_module_reverse_lookup (SCM @var{module}, SCM @var{variable})
-Find the symbol that is bound to @var{variable} in @var{module}.  When no such binding is found, return @var{#f}.
+Find the symbol that is bound to @var{variable} in @var{module}.  When no such binding is found, return @code{#f}.
 @end deftypefn
 
 @deftypefn {C Function} SCM scm_c_define_module ({const char *}@var{name}, void (*@var{init})(void *), void *@var{data})
diff --git a/doc/ref/api-procedures.texi b/doc/ref/api-procedures.texi
index 2b4a05e..82ad184 100644
--- a/doc/ref/api-procedures.texi
+++ b/doc/ref/api-procedures.texi
@@ -103,7 +103,7 @@ useful mechanism, combining the process of registration
 (@code{scm_c_make_gsubr}) and definition (@code{scm_define}).
 
 @deftypefun SCM scm_c_make_gsubr (const char *name, int req, int opt, int rst, fcn)
-Register a C procedure @var{FCN} as a ``subr'' --- a primitive
+Register a C procedure @var{fcn} as a ``subr'' --- a primitive
 subroutine that can be called from Scheme.  It will be associated with
 the given @var{name} but no environment binding will be created.  The
 arguments @var{req}, @var{opt} and @var{rst} specify the number of
@@ -115,7 +115,7 @@ to @var{fcn}, but may not exceed 10.  The number of rest arguments should be 0 o
 @end deftypefun
 
 @deftypefun SCM scm_c_define_gsubr (const char *name, int req, int opt, int rst, fcn)
-Register a C procedure @var{FCN}, as for @code{scm_c_make_gsubr}
+Register a C procedure @var{fcn}, as for @code{scm_c_make_gsubr}
 above, and additionally create a top-level Scheme binding for the
 procedure in the ``current environment'' using @code{scm_define}.
 @code{scm_c_define_gsubr} returns a handle for the procedure in the
diff --git a/doc/ref/api-scheduling.texi b/doc/ref/api-scheduling.texi
index f107cbf..da2c285 100644
--- a/doc/ref/api-scheduling.texi
+++ b/doc/ref/api-scheduling.texi
@@ -315,10 +315,10 @@ Higher level thread procedures are available by loading the
 @code{(ice-9 threads)} module.  These provide standardized
 thread creation.
 
-@deffn macro make-thread proc [args@dots{}]
-Apply @var{proc} to @var{args} in a new thread formed by
+@deffn macro make-thread proc arg @dots{}
+Apply @var{proc} to @var{arg} @dots{} in a new thread formed by
 @code{call-with-new-thread} using a default error handler that display
-the error to the current error port.  The @var{args@dots{}}
+the error to the current error port.  The @var{arg} @dots{}
 expressions are evaluated in the new thread.
 @end deffn
 
@@ -748,12 +748,12 @@ set/restored when control enter or leaves the established dynamic
 extent.
 @end deffn
 
-@deffn {Scheme Macro} with-fluids ((fluid value) ...) body...
-Execute @var{body...} while each @var{fluid} is set to the
-corresponding @var{value}.  Both @var{fluid} and @var{value} are
-evaluated and @var{fluid} must yield a fluid.  @var{body...} is
-executed inside a @code{dynamic-wind} and the fluids are set/restored
-when control enter or leaves the established dynamic extent.
+@deffn {Scheme Macro} with-fluids ((fluid value) @dots{}) body1 body2 @dots{}
+Execute body @var{body1} @var{body2} @dots{}  while each @var{fluid} is
+set to the corresponding @var{value}.  Both @var{fluid} and @var{value}
+are evaluated and @var{fluid} must yield a fluid.  The body is executed
+inside a @code{dynamic-wind} and the fluids are set/restored when
+control enter or leaves the established dynamic extent.
 @end deffn
 
 @deftypefn {C Function} SCM scm_c_with_fluids (SCM fluids, SCM vals, SCM (*cproc)(void *), void *data)
@@ -927,16 +927,16 @@ are implemented in terms of futures (@pxref{Futures}).  Thus they are
 relatively cheap as they re-use existing threads, and portable, since
 they automatically use one thread per available CPU core.
 
-@deffn syntax parallel expr1 @dots{} exprN
+@deffn syntax parallel expr @dots{}
 Evaluate each @var{expr} expression in parallel, each in its own thread.
-Return the results as a set of @var{N} multiple values
-(@pxref{Multiple Values}).
+Return the results of @var{n} expressions as a set of @var{n} multiple
+values (@pxref{Multiple Values}).
 @end deffn
 
-@deffn syntax letpar ((var1 expr1) @dots{} (varN exprN)) body@dots{}
+@deffn syntax letpar ((var expr) @dots{}) body1 body2 @dots{}
 Evaluate each @var{expr} in parallel, each in its own thread, then bind
-the results to the corresponding @var{var} variables and evaluate
-@var{body}.
+the results to the corresponding @var{var} variables, and then evaluate
+@var{body1} @var{body2} @enddots{}
 
 @code{letpar} is like @code{let} (@pxref{Local Bindings}), but all the
 expressions for the bindings are evaluated in parallel.
@@ -949,11 +949,10 @@ returns a list comprising the return values from @var{proc}.
 @code{par-for-each} returns an unspecified value, but waits for all
 calls to complete.
 
-The @var{proc} calls are @code{(@var{proc} @var{elem1} @dots{}
-@var{elemN})}, where each @var{elem} is from the corresponding
-@var{lst}.  Each @var{lst} must be the same length.  The calls are
-potentially made in parallel, depending on the number of CPU cores
-available.
+The @var{proc} calls are @code{(@var{proc} @var{elem1} @var{elem2}
+@dots{})}, where each @var{elem} is from the corresponding @var{lst} .
+Each @var{lst} must be the same length.  The calls are potentially made
+in parallel, depending on the number of CPU cores available.
 
 These functions are like @code{map} and @code{for-each} (@pxref{List
 Mapping}), but make their @var{proc} calls in parallel.
diff --git a/doc/ref/api-smobs.texi b/doc/ref/api-smobs.texi
index db8161c..6b04236 100644
--- a/doc/ref/api-smobs.texi
+++ b/doc/ref/api-smobs.texi
@@ -22,8 +22,8 @@ If @var{size} is 0, the default @emph{free} function will do nothing.
 
 If @var{size} is not 0, the default @emph{free} function will
 deallocate the memory block pointed to by @code{SCM_SMOB_DATA} with
-@code{scm_gc_free}.  The @var{WHAT} parameter in the call to
-@code{scm_gc_free} will be @var{NAME}.
+@code{scm_gc_free}.  The @var{what} parameter in the call to
+@code{scm_gc_free} will be @var{name}.
 
 Default values are provided for the @emph{mark}, @emph{free},
 @emph{print}, and @emph{equalp} functions, as described in
@@ -43,7 +43,7 @@ a @dfn{finalizer}) for the smob type specified by the tag
 @var{tc}. @var{tc} is the tag returned by @code{scm_make_smob_type}.
 
 The @var{free} procedure must deallocate all resources that are
-directly associated with the smob instance @var{OBJ}.  It must assume
+directly associated with the smob instance @var{obj}.  It must assume
 that all @code{SCM} values that it references have already been freed
 and are thus invalid.
 
@@ -107,14 +107,14 @@ with @code{scm_display}, @code{scm_write}, @code{scm_simple_format},
 and @code{scm_puts}.
 @end deftypefn
 
-@deftypefn {C Function} void scm_set_smob_equalp (scm_t_bits tc, SCM (*equalp) (SCM obj1, SCM obj1))
+@deftypefn {C Function} void scm_set_smob_equalp (scm_t_bits tc, SCM (*equalp) (SCM obj1, SCM obj2))
 This function sets the smob equality-testing predicate for the smob
 type specified by the tag @var{tc}. @var{tc} is the tag returned by
 @code{scm_make_smob_type}.
 
 The @var{equalp} procedure should return @code{SCM_BOOL_T} when
 @var{obj1} is @code{equal?} to @var{obj2}.  Else it should return
-@var{SCM_BOOL_F}.  Both @var{obj1} and @var{obj2} are instances of the
+@code{SCM_BOOL_F}.  Both @var{obj1} and @var{obj2} are instances of the
 smob type @var{tc}.
 @end deftypefn
 
diff --git a/doc/ref/compiler.texi b/doc/ref/compiler.texi
index 3d6dbf3..692cb36 100644
--- a/doc/ref/compiler.texi
+++ b/doc/ref/compiler.texi
@@ -437,9 +437,9 @@ any, then the rest argument if any, then all of the keyword arguments.
 
 @var{body} is the body of the clause. If the procedure is called with
 an appropriate number of arguments, @var{body} is evaluated in tail
-position. Otherwise, if there is a @var{consequent}, it should be a
+position. Otherwise, if there is an @var{alternate}, it should be a
 @code{<lambda-case>} expression, representing the next clause to try.
-If there is no @var{consequent}, a wrong-number-of-arguments error is
+If there is no @var{alternate}, a wrong-number-of-arguments error is
 signaled.
 @end deftp
 @deftp {Scheme Variable} <let> src names gensyms vals exp
diff --git a/doc/ref/misc-modules.texi b/doc/ref/misc-modules.texi
index 00354ac..2a6630c 100644
--- a/doc/ref/misc-modules.texi
+++ b/doc/ref/misc-modules.texi
@@ -90,13 +90,13 @@ dots.}, or in the worst case, displayed as @nicode{#}.
 
 @deffn {Scheme Procedure} truncated-print obj [port] [keyword-options]
 Print @var{obj}, truncating the output, if necessary, to make it fit
-into @var{width} characters. By default, @var{x} will be printed using
+into @var{width} characters. By default, @var{obj} will be printed using
 @code{write}, though that behavior can be overridden via the
 @var{display?} keyword argument.
 
 The default behaviour is to print depth-first, meaning that the entire
-remaining width will be available to each sub-expression of @var{x} --
-e.g., if @var{x} is a vector, each member of @var{x}. One can attempt to
+remaining width will be available to each sub-expression of @var{obj} --
+e.g., if @var{obj} is a vector, each member of @var{obj}. One can attempt to
 ``ration'' the available width, trying to allocate it equally to each
 sub-expression, via the @var{breadth-first?} keyword argument.
 
diff --git a/doc/ref/posix.texi b/doc/ref/posix.texi
index 1dc5a80..0defc3f 100644
--- a/doc/ref/posix.texi
+++ b/doc/ref/posix.texi
@@ -211,8 +211,8 @@ initialized to zero.  The @var{modes} string is the same as that
 accepted by @code{open-file} (@pxref{File Ports, open-file}).
 @end deffn
 
-@deffn {Scheme Procedure} fdes->ports fd
-@deffnx {C Function} scm_fdes_to_ports (fd)
+@deffn {Scheme Procedure} fdes->ports fdes
+@deffnx {C Function} scm_fdes_to_ports (fdes)
 Return a list of existing ports which have @var{fdes} as an
 underlying file descriptor, without changing their revealed
 counts.
@@ -230,8 +230,8 @@ descriptor, if one exists, and increments its revealed count.
 Otherwise, returns a new output port with a revealed count of 1.
 @end deffn
 
-@deffn {Scheme Procedure} primitive-move->fdes port fd
-@deffnx {C Function} scm_primitive_move_to_fdes (port, fd)
+@deffn {Scheme Procedure} primitive-move->fdes port fdes
+@deffnx {C Function} scm_primitive_move_to_fdes (port, fdes)
 Moves the underlying file descriptor for @var{port} to the integer
 value @var{fdes} without changing the revealed count of @var{port}.
 Any other ports already using this descriptor will be automatically
@@ -252,10 +252,10 @@ The return value is unspecified.
 Decrements the revealed count for a port.
 @end deffn
 
-@deffn {Scheme Procedure} fsync object
-@deffnx {C Function} scm_fsync (object)
+@deffn {Scheme Procedure} fsync port_or_fd
+@deffnx {C Function} scm_fsync (port_or_fd)
 Copies any unwritten data for the specified output file descriptor to disk.
-If @var{port/fd} is a port, its buffer is flushed before the underlying
+If @var{port_or_fd} is a port, its buffer is flushed before the underlying
 file descriptor is fsync'd.
 The return value is unspecified.
 @end deffn
@@ -402,11 +402,11 @@ port.
 This procedure is equivalent to @code{(dup->port @var{port} @var{modes})}.
 @end deffn
 
-@deffn {Scheme Procedure} redirect-port old new
-@deffnx {C Function} scm_redirect_port (old, new)
+@deffn {Scheme Procedure} redirect-port old_port new_port
+@deffnx {C Function} scm_redirect_port (old_port, new_port)
 This procedure takes two ports and duplicates the underlying file
-descriptor from @var{old-port} into @var{new-port}.  The
-current file descriptor in @var{new-port} will be closed.
+descriptor from @var{old_port} into @var{new_port}.  The
+current file descriptor in @var{new_port} will be closed.
 After the redirection the two ports will share a file position
 and file status flags.
 
@@ -648,7 +648,7 @@ The GNU C Library Reference Manual}.
 @deffn {Scheme Procedure} stat object
 @deffnx {C Function} scm_stat (object)
 Return an object containing various information about the file
-determined by @var{obj}.  @var{obj} can be a string containing
+determined by @var{object}.  @var{object} can be a string containing
 a file name or a port or integer file descriptor which is open
 on a file (in which case @code{fstat} is used as the underlying
 system call).
@@ -728,8 +728,8 @@ An integer representing the access permission bits.
 @end deffn
 @end deffn
 
-@deffn {Scheme Procedure} lstat str
-@deffnx {C Function} scm_lstat (str)
+@deffn {Scheme Procedure} lstat path
+@deffnx {C Function} scm_lstat (path)
 Similar to @code{stat}, but does not follow symbolic links, i.e.,
 it will return information about a symbolic link itself, not the
 file it points to.  @var{path} must be a string.
@@ -762,8 +762,8 @@ as @code{-1}, then that ID is not changed.
 @findex fchmod
 @deffn {Scheme Procedure} chmod object mode
 @deffnx {C Function} scm_chmod (object, mode)
-Changes the permissions of the file referred to by @var{obj}.
-@var{obj} can be a string containing a file name or a port or integer file
+Changes the permissions of the file referred to by @var{object}.
+@var{object} can be a string containing a file name or a port or integer file
 descriptor which is open on a file (in which case @code{fchmod} is used
 as the underlying system call).
 @var{mode} specifies
@@ -774,7 +774,7 @@ The return value is unspecified.
 @deffn {Scheme Procedure} utime pathname [actime [modtime [actimens [modtimens [flags]]]]]
 @deffnx {C Function} scm_utime (pathname, actime, modtime, actimens, modtimens, flags)
 @code{utime} sets the access and modification times for the
-file named by @var{path}.  If @var{actime} or @var{modtime} is
+file named by @var{pathname}.  If @var{actime} or @var{modtime} is
 not supplied, then the current time is used.  @var{actime} and
 @var{modtime} must be integer time values as returned by the
 @code{current-time} procedure.
@@ -1055,7 +1055,7 @@ stream.  Otherwise, close the stream.  The @code{setpwent} and
 
 @deffn {Scheme Procedure} getpw [user]
 @deffnx {C Function} scm_getpwuid (user)
-Look up an entry in the user database.  @var{obj} can be an integer,
+Look up an entry in the user database.  @var{user} can be an integer,
 a string, or omitted, giving the behaviour of getpwuid, getpwnam
 or getpwent respectively.
 @end deffn
@@ -1108,9 +1108,9 @@ stream.  Otherwise, close the stream.  The @code{setgrent} and
 @code{endgrent} procedures are implemented on top of this.
 @end deffn
 
-@deffn {Scheme Procedure} getgr [name]
-@deffnx {C Function} scm_getgrgid (name)
-Look up an entry in the group database.  @var{obj} can be an integer,
+@deffn {Scheme Procedure} getgr [group]
+@deffnx {C Function} scm_getgrgid (group)
+Look up an entry in the group database.  @var{group} can be an integer,
 a string, or omitted, giving the behaviour of getgrgid, getgrnam
 or getgrent respectively.
 @end deffn
@@ -1284,7 +1284,7 @@ names are from the current locale and in the locale character set.
 @cindex time parsing
 Performs the reverse action to @code{strftime}, parsing
 @var{string} according to the specification supplied in
-@var{template}.  The interpretation of month and day names is
+@var{format}.  The interpretation of month and day names is
 dependent on the current locale.  The value returned is a pair.
 The @acronym{CAR} has an object with time components
 in the form returned by @code{localtime} or @code{gmtime},
@@ -1411,8 +1411,8 @@ The given strings are all copied, so the C data is not accessed again
 once @code{scm_set_program_arguments} returns.
 @end deftypefn
 
-@deffn {Scheme Procedure} getenv nam
-@deffnx {C Function} scm_getenv (nam)
+@deffn {Scheme Procedure} getenv name
+@deffnx {C Function} scm_getenv (name)
 @cindex environment
 Looks up the string @var{name} in the current environment.  The return
 value is @code{#f} unless a string of the form @code{NAME=VALUE} is
@@ -1442,8 +1442,8 @@ If @var{env} is omitted, return the current environment (in the
 Unix sense) as a list of strings.  Otherwise set the current
 environment, which is also the default environment for child
 processes, to the supplied list of strings.  Each member of
-@var{env} should be of the form @var{NAME}=@var{VALUE} and values of
-@var{NAME} should not be duplicated.  If @var{env} is supplied
+@var{env} should be of the form @var{name}=@var{value} and values of
+@var{name} should not be duplicated.  If @var{env} is supplied
 then the return value is unspecified.
 @end deffn
 
@@ -1452,11 +1452,11 @@ then the return value is unspecified.
 Modifies the environment of the current process, which is
 also the default environment inherited by child processes.
 
-If @var{string} is of the form @code{NAME=VALUE} then it will be written
+If @var{str} is of the form @code{NAME=VALUE} then it will be written
 directly into the environment, replacing any existing environment string
 with
-name matching @code{NAME}.  If @var{string} does not contain an equal
-sign, then any existing string with name matching @var{string} will
+name matching @code{NAME}.  If @var{str} does not contain an equal
+sign, then any existing string with name matching @var{str} will
 be removed.
 
 The return value is unspecified.
@@ -1472,7 +1472,7 @@ The return value is unspecified.
 @deffn {Scheme Procedure} chdir str
 @deffnx {C Function} scm_chdir (str)
 @cindex current directory
-Change the current working directory to @var{path}.
+Change the current working directory to @var{str}.
 The return value is unspecified.
 @end deffn
 
@@ -1745,13 +1745,13 @@ in the child would upset the protocol in the parent, so
 
 @deffn {Scheme Procedure} execl filename . args
 @deffnx {C Function} scm_execl (filename, args)
-Executes the file named by @var{path} as a new process image.
+Executes the file named by @var{filename} as a new process image.
 The remaining arguments are supplied to the process; from a C program
 they are accessible as the @code{argv} argument to @code{main}.
-Conventionally the first @var{arg} is the same as @var{path}.
+Conventionally the first @var{arg} is the same as @var{filename}.
 All arguments must be strings.
 
-If @var{arg} is missing, @var{path} is executed with a null
+If @var{arg} is missing, @var{filename} is executed with a null
 argument list, which may have system-dependent side-effects.
 
 This procedure is currently implemented using the @code{execv} system
diff --git a/doc/ref/scheme-using.texi b/doc/ref/scheme-using.texi
index 73e1a5d..7720a85 100644
--- a/doc/ref/scheme-using.texi
+++ b/doc/ref/scheme-using.texi
@@ -311,7 +311,7 @@ they do not work at the top level.
 @deffn {REPL Command} backtrace [count] [#:width w] [#:full? f]
 Print a backtrace.
 
-Print a backtrace of all stack frames, or innermost @var{COUNT} frames.
+Print a backtrace of all stack frames, or innermost @var{count} frames.
 If @var{count} is negative, the last @var{count} frames will be shown.
 @end deffn
 
@@ -406,11 +406,11 @@ reenter the REPL.
 @node Inspect Commands
 @subsubsection Inspect Commands
 
-@deffn {REPL Command} inspect EXP
+@deffn {REPL Command} inspect exp
 Inspect the result(s) of evaluating @var{exp}.
 @end deffn
 
-@deffn {REPL Command} pretty-print EXP
+@deffn {REPL Command} pretty-print exp
 Pretty-print the result(s) of evaluating @var{exp}.
 @end deffn
 
diff --git a/doc/ref/srfi-modules.texi b/doc/ref/srfi-modules.texi
index 1e0ba2b..d9383ba 100644
--- a/doc/ref/srfi-modules.texi
+++ b/doc/ref/srfi-modules.texi
@@ -2322,7 +2322,7 @@ any) will be stored for later retrieval via a call to
 Wait for @var{thread} to terminate and return its exit value.  When a 
 time value @var{timeout} is given, it specifies a point in time where
 the waiting should be aborted.  When the waiting is aborted, 
-@var{timeoutval} is returned if it is specified; otherwise, a
+@var{timeout-val} is returned if it is specified; otherwise, a
 @code{join-timeout-exception} exception is raised 
 (@pxref{SRFI-18 Exceptions}).  Exceptions may also be raised if the 
 thread was terminated by a call to @code{thread-terminate!} 
@@ -2430,8 +2430,8 @@ replaces a procedure of the same name in the core library.
 @end defun
 
 @defun condition-variable-name condition-variable
-Returns the name assigned to @var{thread} at the time of its creation,
-or @code{#f} if it was not given a name.
+Returns the name assigned to @var{condition-variable} at the time of its
+creation, or @code{#f} if it was not given a name.
 @end defun
 
 @defun condition-variable-specific condition-variable
@@ -3533,7 +3533,7 @@ Return the value of the field named @var{field-name} from condition @var{c}.
 If @var{c} is a compound condition and several underlying condition
 types contain a field named @var{field-name}, then the value of the
 first such field is returned, using the order in which conditions were
-passed to @var{make-compound-condition}.
+passed to @code{make-compound-condition}.
 @end deffn
 
 @deffn {Scheme Procedure} extract-condition c type
@@ -3978,7 +3978,7 @@ dynamically with @code{parameterize}.
 @defun with-parameters* param-list value-list thunk
 Establish a new dynamic scope, as per @code{parameterize} above,
 taking parameters from @var{param-list} and corresponding values from
-@var{values-list}.  A call @code{(@var{thunk})} is made in the new
+@var{value-list}.  A call @code{(@var{thunk})} is made in the new
 scope and the result from that @var{thunk} is the return from
 @code{with-parameters*}.
 
diff --git a/doc/ref/vm.texi b/doc/ref/vm.texi
index cf4e135..e799456 100644
--- a/doc/ref/vm.texi
+++ b/doc/ref/vm.texi
@@ -432,7 +432,7 @@ then @code{local-set}, used when binding boxed variables.
 @end deffn
 
 @deffn Instruction empty-box index
-Set the @var{indext}h local variable to a box containing a variable
+Set the @var{index}th local variable to a box containing a variable
 whose value is unbound. Used when compiling some @code{letrec}
 expressions.
 @end deffn
@@ -918,13 +918,13 @@ Jump to @var{offset} if the object on the stack is false.
 
 @deffn Instruction br-if-eq offset
 Jump to @var{offset} if the two objects located on the stack are
-equal in the sense of @var{eq?}.  Note that, for this instruction, the
+equal in the sense of @code{eq?}.  Note that, for this instruction, the
 stack pointer is decremented by two Scheme objects instead of only
 one.
 @end deffn
 
 @deffn Instruction br-if-not-eq offset
-Same as @var{br-if-eq} for non-@code{eq?} objects.
+Same as @code{br-if-eq} for non-@code{eq?} objects.
 @end deffn
 
 @deffn Instruction br-if-null offset
diff --git a/doc/ref/web.texi b/doc/ref/web.texi
index a08cd2c..81c77dd 100644
--- a/doc/ref/web.texi
+++ b/doc/ref/web.texi
@@ -1116,7 +1116,7 @@ if there was no request body.
 @end deffn
 
 @deffn {Scheme Procedure} 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}.
 @end deffn
 
@@ -1212,7 +1212,7 @@ As a side effect, sets the encoding on @var{port} to ISO-8859-1
 discussion of character sets in @ref{Responses}, for more information.
 @end deffn
 
-@deffn {Scheme Procedure} build-response [#:version='(1 . 1)] [#:code=200] [#:reason-phrase=#f] [#:headers='()] [#:port=#f] [#:validate-headers=#t]
+@deffn {Scheme Procedure} build-response [#:version='(1 . 1)] [#:code=200] [#:reason-phrase=#f] [#:headers='()] [#:port=#f] [#:validate-headers?=#t]
 Construct an HTTP response object. If @var{validate-headers?} is true,
 the headers are each run through their respective validators.
 @end deffn
@@ -1241,7 +1241,7 @@ if there was no response body.
 @end deffn
 
 @deffn {Scheme Procedure} 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}.
 @end deffn
 
@@ -1291,7 +1291,7 @@ the lower-level HTTP, request, and response modules.
 @deffn {Scheme Procedure} open-socket-for-uri uri
 @end deffn
 
-@deffn {Scheme Procedure} http-get uri [#:port=(open-socket-for-uri uri)] [#:version='(1 . 1)] [#:keep-alive?=#f] [#:extra-headers='()] [#:decode-body=#t]
+@deffn {Scheme Procedure} http-get uri [#:port=(open-socket-for-uri uri)] [#:version='(1 . 1)] [#:keep-alive?=#f] [#:extra-headers='()] [#:decode-body?=#t]
 Connect to the server corresponding to @var{uri} and ask for the
 resource, using the @code{GET} method.  If you already have a port open,
 pass it as @var{port}.  The port will be closed at the end of the
diff --git a/doc/sources/env.texi b/doc/sources/env.texi
index 7a37b76..4f20afd 100644
--- a/doc/sources/env.texi
+++ b/doc/sources/env.texi
@@ -691,7 +691,7 @@ and locations in the new environment are mutable.
 @end deffn
 
 @deffn Primitive leaf-environment? object
-Return @code{#t} if @var{object} is a leaf environment, or @var{#f}
+Return @code{#t} if @var{object} is a leaf environment, or @code{#f}
 otherwise.
 @end deffn
 
@@ -815,7 +815,7 @@ Return a new environment @var{exp} containing only those bindings in
 The environment @var{exp} binds @var{symbol} to @var{location} when
 @var{env} does, and @var{symbol} is exported by @var{signature}.
 
-@var{Signature} is a list specifying which of the bindings in
+@var{signature} is a list specifying which of the bindings in
 @var{private} should be visible in @var{exp}.  Each element of
 @var{signature} should be a list of the form:
 @example
-- 
1.7.8.3

bug#10481: Simple patches to Texinfo docs

[Andy Wingo]

On Wed 11 Jan 2012 19:08, Bake Timmons <b3timmons@speedymail.org> writes:

> Months ago I proposed some improvements to the manual.  With a gentle
> reminder from Andy Wingo, I have finally started breaking up my original
> giant patch into some manageable patches.

Thank you!  I applied both of these patches.  Sorry we didn't get around
to it until after the release; things were a bit hectic.

Cheers,

Andy
-- 
http://wingolog.org/

bug#10481: Simple patches to Texinfo docs

[Mark H Weaver]

Andy Wingo <wingo@pobox.com> writes:

> On Wed 11 Jan 2012 19:08, Bake Timmons <b3timmons@speedymail.org> writes:
>
>> Months ago I proposed some improvements to the manual.  With a gentle
>> reminder from Andy Wingo, I have finally started breaking up my original
>> giant patch into some manageable patches.
>
> Thank you!  I applied both of these patches.  Sorry we didn't get around
> to it until after the release; things were a bit hectic.

Note that according to the R5RS, identifiers are not case sensitive, so
e.g. 'Radix' is no less correct than 'radix'.  In that context, it does
not make sense to say "the identifier starts with a lowercase letter".
Also, as Andy noted elsewhere, the R5RS is an historical document.

I would advocate reverting the R5RS portion of this patch.

The rest of the patch looks great, many thanks! :)

      Mark

bug#10481: Simple patches to Texinfo docs

[Andy Wingo]

On Thu 02 Feb 2012 15:37, Mark H Weaver <mhw@netris.org> writes:

> I would advocate reverting the R5RS portion of this patch.

Reverted.  Thanks for the feedback :)

Andy
-- 
http://wingolog.org/