Minor cleanups.

6 files changed, 119 insertions, 90 deletions

diff --git a/lispref/hash.texi b/lispref/hash.texi
index 3f4e4380be6..4b12160c603 100644
--- a/lispref/hash.texi
+++ b/lispref/hash.texi
@@ -107,13 +107,14 @@ values from being collected as garbage (if they are not referenced
 anywhere else); if a particular value does get collected, the
 corresponding association is removed from the hash table.
 
-If @var{weak} is @code{key-or-value}, associations are removed from the
-hash table when either their key or their value part would be collected
-as garbage, not counting references to the key and value from weak hash
-tables.  Likewise, if @var{weak} is @code{key-and-value}, associations
-are removed from the hash table when both their key and value would be
-collected as garbage, again not considering references to the key and
-value from weak hash tables.
+If @var{weak} is @code{key-or-value} or @code{t}, the hash table does
+not protect either keys or values from garbage collection; if either
+one is collected as garbage, the association is removed.
+
+If @var{weak} is @code{key-and-value}, associations are removed from
+the hash table when both their key and value would be collected as
+garbage, again not considering references to the key and value from
+weak hash tables.
 
 The default for @var{weak} is @code{nil}, so that all keys and values
 referenced in the hash table are preserved from garbage collection.  If
@@ -242,8 +243,24 @@ including negative integers.
 The specified functions are stored in the property list of @var{name}
 under the property @code{hash-table-test}; the property value's form is
 @code{(@var{test-fn} @var{hash-fn})}.
+@end defun
+
+@tindex sxhash
+@defun sxhash obj
+This function returns a hash code for Lisp object @var{obj}.
+This is an integer which reflects the contents of @var{obj}
+and the other Lisp objects it points to.
+
+If two objects @var{obj1} and @var{obj2} are equal, then @code{(sxhash
+@var{obj1})} and @code{(sxhash @var{obj2})} are the same integer.
+
+If the two objects are not equal, the values returned by @code{sxhash}
+are usually different, but not always; but once in a rare while, by
+luck, you will encounter two distinct-looking objects that give the same
+result from @code{sxhash}.
+@end defun
 
-This example creates a hash table whose keys are strings that are
+  This example creates a hash table whose keys are strings that are
 compared case-insensitively.
 
 @example
@@ -258,22 +275,16 @@ compared case-insensitively.
 
 (make-hash-table :test 'case-fold)
 @end example
-@end defun
 
-@tindex sxhash
-@defun sxhash obj
-This function returns a hash code for Lisp object @var{obj}.
-This is an integer which reflects the contents of @var{obj}
-and the other Lisp objects it points to.
+  Here is how you could define a hash table test equivalent to the
+predefined test value @code{equal}.  The keys can be any Lisp object,
+and equal-looking objects are considered the same key.
 
-If two objects @var{obj1} and @var{obj2} are equal, then @code{(sxhash
-@var{obj1})} and @code{(sxhash @var{obj2})} are the same integer.
+@example
+(define-hash-table-test 'contents-hash 'equal 'sxhash)
 
-If the two objects are not equal, the values returned by @code{sxhash}
-are usually different, but not always; but once in a rare while, by
-luck, you will encounter two distinct-looking objects that give the same
-result from @code{sxhash}.
-@end defun
+(make-hash-table :test 'contents-hash)
+@end example
 
 @node Other Hash
 @section Other Hash Table Functions
diff --git a/lispref/lists.texi b/lispref/lists.texi
index b0a3a1f6b85..5f16394ae12 100644
--- a/lispref/lists.texi
+++ b/lispref/lists.texi
@@ -384,7 +384,7 @@ If @var{n} is zero or negative, @code{nthcdr} returns all of
 @end defun
 
 @defun last list &optional n
-This function reruns the last link of the given @var{list}.  The
+This function returns the last link of @var{list}.  The
 @code{car} of this link is the list's last element.  If @var{list} is
 null, @code{nil} is returned.  If @var{n} is non-nil the
 @var{n}-th-to-last link is returned instead, or the whole @var{list} if
@@ -496,6 +496,15 @@ any symbol can serve both purposes.
 This macro provides an alternative way to write
 @code{(setq @var{listname} (cons @var{newelt} @var{listname}))}.
 It is new in Emacs 21.
+
+@example
+(setq l '(a b)) 
+     @result{} (a b)
+(push 'c l)
+     @result{} (c a b)
+l
+     @result{} (c a b)
+@end example
 @end defmac
 
 @defun list &rest objects
@@ -520,9 +529,9 @@ are given, the empty list is returned.
 @end defun
 
 @defun make-list length object
-This function creates a list of length @var{length}, in which all the
-elements have the identical value @var{object}.  Compare
-@code{make-list} with @code{make-string} (@pxref{Creating Strings}).
+This function creates a list of @var{length} elements, in which each
+element is @var{object}.  Compare @code{make-list} with
+@code{make-string} (@pxref{Creating Strings}).
 
 @example
 @group
@@ -533,6 +542,12 @@ elements have the identical value @var{object}.  Compare
 (make-list 0 'pigs)
      @result{} nil
 @end group
+@group
+(setq l (make-list 3 '(a b))
+     @result{} ((a b) (a b) (a b))
+(eq (car l) (cadr l))
+     @result{} t
+@end group
 @end example
 @end defun
 
@@ -1064,19 +1079,19 @@ value.
 
 @example
 @group
-(setq x '(1 2 3 4))
-     @result{} (1 2 3 4)
+(setq x '(a b c))
+     @result{} (a b c)
 @end group
 @group
 x
-     @result{} (1 2 3 4)
+     @result{} (a b c)
 (nreverse x)
-     @result{} (4 3 2 1)
+     @result{} (c b a)
 @end group
 @group
 ;; @r{The cons cell that was first is now last.}
 x
-     @result{} (1)
+     @result{} (a)
 @end group
 @end example
 
@@ -1379,9 +1394,9 @@ the value @code{cones}; the key @code{oak} is associated with
 
 @example
 @group
-'((pine . cones)
-  (oak . acorns)
-  (maple . seeds))
+((pine . cones)
+ (oak . acorns)
+ (maple . seeds))
 @end group
 @end example
 
@@ -1397,10 +1412,10 @@ the alist element:
 
   Sometimes it is better to design an alist to store the associated
 value in the @sc{car} of the @sc{cdr} of the element.  Here is an
-example:
+example of such an alist:
 
 @example
-'((rose red) (lily white) (buttercup yellow))
+((rose red) (lily white) (buttercup yellow))
 @end example
 
 @noindent
@@ -1549,7 +1564,7 @@ becomes clearer if the association is written in dotted pair notation:
 @end smallexample
 @end defun
 
-@defun assoc-default key alist test default
+@defun assoc-default key alist &optional test default
 This function searches @var{alist} for a match for @var{key}.  For each
 element of @var{alist}, it compares the element (if it is an atom) or
 the element's @sc{car} (if it is a cons) against @var{key}, by calling
@@ -1622,7 +1637,9 @@ the associations of one copy without affecting the other:
 @defun assq-delete-all key alist
 @tindex assq-delete-all
 This function deletes from @var{alist} all the elements whose @sc{car}
-is @code{eq} to @var{key}.  It returns the modified alist.
+is @code{eq} to @var{key}.  It returns @var{alist}, modified
+in this way.  Note that it modifies the original list structure
+of @var{alist}.
 
 @example
 (assq-delete-all 'foo
diff --git a/man/mark.texi b/man/mark.texi
index e153cb74761..33f4434bbb6 100644
--- a/man/mark.texi
+++ b/man/mark.texi
@@ -17,8 +17,8 @@ Transient Mark mode (@pxref{Transient Mark}).
   Certain Emacs commands set the mark; other editing commands do not
 affect it, so the mark remains where you set it last.  Each Emacs
 buffer has its own mark, and setting the mark in one buffer has no
-effect on other buffers' marks.  When you return to a buffer that had
-been selected previously, its mark is at the same place as before.
+effect on other buffers' marks.  When you return to a buffer that was
+current earlier, its mark is at the same place as before.
 
   The ends of the region are always point and the mark.  It doesn't
 matter which of them was put in its current place first, or which one
@@ -155,8 +155,9 @@ the mode.
 @itemize @bullet
 @item
 To set the mark, type @kbd{C-@key{SPC}} (@code{set-mark-command}).
-This makes the mark active; as you move point, you will see the
-highlighted region grow and shrink.
+This makes the mark active and thus begins highlighting of the region.
+As you move point, you will see the highlighted region grow and
+shrink.
 
 @item 
 The mouse commands for specifying the mark also make it active.  So do
@@ -175,7 +176,7 @@ on a region will get an error and refuse to operate.  You can make the
 region active again by typing @kbd{C-x C-x}.
 
 @item
-Commands like @kbd{M->} and @kbd{C-s} that ``leave the mark behind'' in
+Commands like @kbd{M->} and @kbd{C-s}, that ``leave the mark behind'' in
 addition to some other primary purpose, do not activate the new mark.
 You can activate the new region by executing @kbd{C-x C-x}
 (@code{exchange-point-and-mark}).
@@ -206,7 +207,7 @@ all share one common mark position).  Ordinarily, only the selected
 window highlights its region (@pxref{Windows}).  However, if the
 variable @code{highlight-nonselected-windows} is non-@code{nil}, then
 each window highlights its own region (provided that Transient Mark mode
-is enabled and the mark in the buffer's window is active).
+is enabled and the mark in the window's buffer is active).
 
   When Transient Mark mode is not enabled, every command that sets the
 mark also activates it, and nothing ever deactivates it.
@@ -261,18 +262,18 @@ object such as a word, list, paragraph or page.
 
 @table @kbd
 @item M-@@
-Set mark after the end of next word (@code{mark-word}).  This command and
+Set mark after end of next word (@code{mark-word}).  This command and
 the following one do not move point.
 @item C-M-@@
-Set mark after the end of following balanced expression (@code{mark-sexp}).
+Set mark after end of following balanced expression (@code{mark-sexp}).
 @item M-h
-Put region around the current paragraph (@code{mark-paragraph}).
+Put region around current paragraph (@code{mark-paragraph}).
 @item C-M-h
-Put region around the current defun (@code{mark-defun}).
+Put region around current defun (@code{mark-defun}).
 @item C-x h
 Put region around the entire buffer (@code{mark-whole-buffer}).
 @item C-x C-p
-Put region around the current page (@code{mark-page}).
+Put region around current page (@code{mark-page}).
 @end table
 
 @kbd{M-@@} (@code{mark-word}) puts the mark at the end of the next
@@ -289,14 +290,14 @@ the mark at the end of that paragraph (@pxref{Paragraphs}).  It prepares
 the region so you can indent, case-convert, or kill a whole paragraph.
 
   @kbd{C-M-h} (@code{mark-defun}) similarly puts point before, and the
-mark after, the current or following major top-level definition, or
+mark after, the current (or following) major top-level definition, or
 defun (@pxref{Moving by Defuns}).  @kbd{C-x C-p} (@code{mark-page})
 puts point before the current page, and mark at the end
 (@pxref{Pages}).  The mark goes after the terminating page delimiter
-(to include it), while point goes after the preceding page delimiter
-(to exclude it).  A numeric argument specifies a later page (if
-positive) or an earlier page (if negative) instead of the current
-page.
+(to include it in the region), while point goes after the preceding
+page delimiter (to exclude it).  A numeric argument specifies a later
+page (if positive) or an earlier page (if negative) instead of the
+current page.
 
   Finally, @kbd{C-x h} (@code{mark-whole-buffer}) sets up the entire
 buffer as the region, by putting point at the beginning and the mark at
diff --git a/man/mini.texi b/man/mini.texi
index 7b557fbbce9..da4262bb789 100644
--- a/man/mini.texi
+++ b/man/mini.texi
@@ -147,13 +147,12 @@ with @kbd{C-x ^}.
 
 @vindex resize-mini-windows
   The minibuffer window expands vertically as necessary to hold the
-text that you put in the minibuffer if @code{resize-mini-windows} is
+text that you put in the minibuffer, if @code{resize-mini-windows} is
 non-@code{nil}.  If @code{resize-mini-windows} is @code{t}, the window
 is always resized to fit the size of the text it displays.  If
 @code{resize-mini-windows} is the symbol @code{grow-only}, the window
-is enlarged when the size of displayed text grows, but never reduced
-in size until it becomes empty, at which point it shrinks back to its
-normal size.
+grows when the size of displayed text increases, but shrinks (back to
+the normal size) only when the minibuffer becomes inactive.
 
 @vindex max-mini-window-height
   The variable @code{max-mini-window-height} controls the maximum
@@ -165,8 +164,8 @@ window automatically.  The default value is 0.25.
   If while in the minibuffer you issue a command that displays help text
 of any sort in another window, you can use the @kbd{C-M-v} command while
 in the minibuffer to scroll the help text.  This lasts until you exit
-the minibuffer.  This feature is especially useful if the
-minibuffer gives you a list of possible completions.  @xref{Other Window}.
+the minibuffer.  This feature is especially useful when you display
+a buffer listing possible completions.  @xref{Other Window}.
 
 @vindex enable-recursive-minibuffers
   Emacs normally disallows most commands that use the minibuffer while
@@ -266,9 +265,8 @@ next hyphen or space.  If you have @samp{auto-f} in the minibuffer and
 type @key{SPC}, it finds that the completion is @samp{auto-fill-mode},
 but it stops completing after @samp{fill-}.  This gives
 @samp{auto-fill-}.  Another @key{SPC} at this point completes all the
-way to @samp{auto-fill-mode}.  Typing @key{SPC} in the minibuffer when
-completion is available runs the command
-@code{minibuffer-complete-word}.
+way to @samp{auto-fill-mode}.  The command that implements this
+behavior is called @code{minibuffer-complete-word}.
 
   Here are some commands you can use to choose a completion from a
 window that displays a list of completions:
@@ -366,11 +364,11 @@ strings, then they are not ignored.  Ignored extensions do not apply to
 lists of completions---those always mention all possible completions.
 
 @vindex completion-auto-help
-  Normally, a completion command that finds that the next character is
-undetermined automatically displays a list of all possible
+  Normally, a completion command that cannot determine even one
+additional character automatically displays a list of all possible
 completions.  If the variable @code{completion-auto-help} is set to
-@code{nil}, this does not happen, and you must type @kbd{?} to display
-the possible completions.
+@code{nil}, this automatic display is disabled, so you must type
+@kbd{?} to display the list of completions.
 
 @cindex Partial Completion mode
 @vindex partial-completion-mode
diff --git a/man/misc.texi b/man/misc.texi
index 8a7f5222a3d..df1ca152b6b 100644
--- a/man/misc.texi
+++ b/man/misc.texi
@@ -366,7 +366,7 @@ normally creates the file @file{foo} and produces no terminal output.
   A numeric argument, as in @kbd{M-1 M-!}, says to insert terminal
 output into the current buffer instead of a separate buffer.  It puts
 point before the output, and sets the mark after the output.  For
-instance, @kbd{M-1 M-!  gunzip < foo.gz @key{RET}} would insert the
+instance, @kbd{M-1 M-! gunzip < foo.gz @key{RET}} would insert the
 uncompressed equivalent of @file{foo.gz} into the current buffer.
 
   If the shell command line ends in @samp{&}, it runs asynchronously.
@@ -442,10 +442,13 @@ for time to elapse.
 face @code{comint-highlight-prompt}.  This makes it easier to see
 previous input lines in the buffer.  @xref{Faces}.
 
-  To make multiple subshells invoke @kbd{M-x shell} with a prefix
-argument (e.g. @kbd{C-u M-x shell}), which will cause it to prompt for
-a buffer name, and create (or reuse) a subshell in that buffer.  All
-subshells in different buffers run independently and in parallel.
+  To make multiple subshells, you can invoke @kbd{M-x shell} with a
+prefix argument (e.g. @kbd{C-u M-x shell}), which will read a buffer
+name and create (or reuse) a subshell in that buffer.  You can also
+rename the @samp{*shell*} buffer using @kbd{M-x rename-uniquely}, then
+then create a new @samp{*shell*} buffer using plain @kbd{M-x shell}.
+All the subshells in different buffers run independently and in
+parallel.
 
 @vindex explicit-shell-file-name
 @cindex environment variables for subshells
@@ -1247,8 +1250,8 @@ emacsclient @r{@{}@r{[}+@var{line}@r{[}@var{column}@r{]}@r{]} @var{filename}@r{@
 @noindent
 This tells Emacs to visit each of the specified files; if you specify a
 line number for a certain file, Emacs moves to that line in the file.
-If you specify a column number for a file, Emacs moves to that column
-in the file.
+If you specify a column number as well, Emacs puts point on that column
+in the line.
 
   Ordinarily, @code{emacsclient} does not return until you use the
 @kbd{C-x #} command on each of these buffers.  When that happens,
diff --git a/man/mule.texi b/man/mule.texi
index cd811722add..c9dc4a5bdab 100644
--- a/man/mule.texi
+++ b/man/mule.texi
@@ -302,7 +302,7 @@ preferred coding system as needed for the locale.
 
   If you modify the @env{LC_ALL}, @env{LC_CTYPE}, or @env{LANG}
 environment variables while running Emacs, you may want to invoke the
-@code{set-locale-environment} function afterwards to re-adjust the
+@code{set-locale-environment} function afterwards to readjust the
 language environment from the new locale.
 
 @vindex locale-preferred-coding-systems
@@ -363,9 +363,9 @@ characters can share one input method.  A few languages support several
 input methods.
 
   The simplest kind of input method works by mapping ASCII letters
-into another alphabet; this allows you to type characters that your
-keyboard doesn't support directly.  This is how the Greek and Russian
-input methods work.
+into another alphabet; this allows you to use one other alphabet
+instead of ASCII.  The Greek and Russian input methods
+work this way.
 
   A more powerful technique is composition: converting sequences of
 characters into one letter.  Many European input methods use composition
@@ -385,8 +385,8 @@ mapped into one syllable sign.
 methods, first you enter the phonetic spelling of a Chinese word (in
 input method @code{chinese-py}, among others), or a sequence of
 portions of the character (input methods @code{chinese-4corner} and
-@code{chinese-sw}, and others).  One phonetic spelling typically
-corresponds to many different Chinese characters.  You select the one
+@code{chinese-sw}, and others).  One input sequence typically
+corresponds to many possible Chinese characters.  You select the one
 you mean using keys such as @kbd{C-f}, @kbd{C-b}, @kbd{C-n},
 @kbd{C-p}, and digits, which have special meanings in this situation.
 
@@ -408,9 +408,9 @@ alternative of the current row and uses it as input.
   @key{TAB} in these Chinese input methods displays a buffer showing
 all the possible characters at once; then clicking @kbd{Mouse-2} on
 one of them selects that alternative.  The keys @kbd{C-f}, @kbd{C-b},
-@kbd{C-n}, @kbd{C-p}, and digits continue to work also.  When this
-buffer is visible, @kbd{C-n} and @kbd{C-p} move the current
-alternative to a different row.
+@kbd{C-n}, @kbd{C-p}, and digits continue to work as usual, but they
+do the highlighting in the buffer showing the possible characters,
+rather than in the echo area.
 
   In Japanese input methods, first you input a whole word using
 phonetic spelling; then, after the word is in the buffer, Emacs
@@ -740,7 +740,7 @@ list.
   If you use a coding system that specifies the end-of-line conversion
 type, such as @code{iso-8859-1-dos}, what this means is that Emacs
 should attempt to recognize @code{iso-8859-1} with priority, and should
-use DOS end-of-line conversion if it recognizes @code{iso-8859-1}.
+use DOS end-of-line conversion when it does recognize @code{iso-8859-1}.
 
 @vindex file-coding-system-alist
   Sometimes a file name indicates which coding system to use for the
@@ -801,9 +801,9 @@ escape sequence detection.
 local variables list at the end (@pxref{File Variables}).  You do this
 by defining a value for the ``variable'' named @code{coding}.  Emacs
 does not really have a variable @code{coding}; instead of setting a
-variable, it uses the specified coding system for the file.  For
+variable, this uses the specified coding system for the file.  For
 example, @samp{-*-mode: C; coding: latin-1;-*-} specifies use of the
-Latin-1 coding system, as well as C mode.  If you specify the coding
+Latin-1 coding system, as well as C mode.  When you specify the coding
 explicitly in the file, that overrides
 @code{file-coding-system-alist}.
 
@@ -844,11 +844,10 @@ This means that it is possible for you to insert characters that
 cannot be encoded with the coding system that will be used to save the
 buffer.  For example, you could start with an ASCII file and insert a
 few Latin-1 characters into it, or you could edit a text file in
-Polish encoded in @code{iso-8859-2} and add to it translations of
-several Polish words into Russian.  When you save the buffer, Emacs
-cannot use the current value of @code{buffer-file-coding-system},
-because the characters you added cannot be encoded by that coding
-system.
+Polish encoded in @code{iso-8859-2} and add some Russian words to it.
+When you save the buffer, Emacs cannot use the current value of
+@code{buffer-file-coding-system}, because the characters you added
+cannot be encoded by that coding system.
 
   When that happens, Emacs tries the most-preferred coding system (set
 by @kbd{M-x prefer-coding-system} or @kbd{M-x