*** empty log message ***

3 files changed, 252 insertions, 198 deletions

diff --git a/lispref/lists.texi b/lispref/lists.texi
index 8253063d2ce..1ec45ab20ca 100644
--- a/lispref/lists.texi
+++ b/lispref/lists.texi
@@ -31,10 +31,10 @@ the whole list.
 @cindex @code{nil} and lists
 
   Lists in Lisp are not a primitive data type; they are built up from
-@dfn{cons cells}.  A cons cell is a data object which represents an ordered
-pair.  It records two Lisp objects, one labeled as the @sc{car}, and the
-other labeled as the @sc{cdr}.  These names are traditional; @sc{cdr} is
-pronounced ``could-er.''
+@dfn{cons cells}.  A cons cell is a data object that represents an
+ordered pair.  It records two Lisp objects, one labeled as the @sc{car},
+and the other labeled as the @sc{cdr}.  These names are traditional; see
+@ref{Cons Cell Type}.  @sc{cdr} is pronounced ``could-er.''
 
   A list is a series of cons cells chained together, one cons cell per
 element of the list.  By convention, the @sc{car}s of the cons cells are
@@ -45,6 +45,11 @@ of the last cons cell is @code{nil}.  This asymmetry between the
 level of cons cells, the @sc{car} and @sc{cdr} slots have the same
 characteristics.
 
+@cindex list structure
+  Because most cons cells are used as part of lists, the phrase
+@dfn{list structure} has come to mean any structure made out of cons
+cells.
+
   The symbol @code{nil} is considered a list as well as a symbol; it is
 the list with no elements.  For convenience, the symbol @code{nil} is
 considered to have @code{nil} as its @sc{cdr} (and also as its
@@ -134,8 +139,8 @@ two-element list:
 @end group
 @end example
 
-  @xref{List Type}, for the read and print syntax of lists, and for more
-``box and arrow'' illustrations of lists.
+  @xref{Cons Cell Type}, for the read and print syntax of cons cells and
+lists, and for more ``box and arrow'' illustrations of lists.
 
 @node List-related Predicates
 @section Predicates on Lists
@@ -155,7 +160,7 @@ otherwise.  @code{nil} is not a cons cell, although it @emph{is} a list.
 This function returns @code{t} if @var{object} is an atom, @code{nil}
 otherwise.  All objects except cons cells are atoms.  The symbol
 @code{nil} is an atom and is also a list; it is the only Lisp object
-which is both.
+that is both.
 
 @example
 (atom @var{object}) @equiv{} (not (consp @var{object}))
@@ -433,15 +438,22 @@ elements have the identical value @var{object}.  Compare
 @defun append &rest sequences
 @cindex copying lists
 This function returns a list containing all the elements of
-@var{sequences}.  The @var{sequences} may be lists, vectors, or strings.
-All arguments except the last one are copied, so none of them are
-altered.
+@var{sequences}.  The @var{sequences} may be lists, vectors, or strings,
+but the last one should be a list.  All arguments except the last one
+are copied, so none of them are altered.
+
+More generally, the final argument to @code{append} may be any Lisp
+object.  The final argument is not copied or converted; it becomes the
+@sc{cdr} of the last cons cell in the new list.  If the final argument
+is itself a list, then its elements become in effect elements of the
+result list.  If the final element is not a list, the result is a
+``dotted list'' since its final @sc{cdr} is not @code{nil} as required
+in a true list.
 
-  The final argument to @code{append} may be any object but it is
-typically a list.  The final argument is not copied or converted; it
-becomes part of the structure of the new list.
+See @code{nconc} in @ref{Rearrangement}, for a way to join lists with no
+copying.
 
-  Here is an example:
+Here is an example of using @code{append}:
 
 @example
 @group
@@ -463,11 +475,11 @@ more-trees
 @end group
 @end example
 
-You can see what happens by looking at a box diagram.  The variable
-@code{trees} is set to the list @code{(pine oak)} and then the variable
-@code{more-trees} is set to the list @code{(maple birch pine oak)}.
-However, the variable @code{trees} continues to refer to the original
-list:
+You can see how @code{append} works by looking at a box diagram.  The
+variable @code{trees} is set to the list @code{(pine oak)} and then the
+variable @code{more-trees} is set to the list @code{(maple birch pine
+oak)}.  However, the variable @code{trees} continues to refer to the
+original list:
 
 @smallexample
 @group
@@ -527,8 +539,20 @@ If no @var{sequences} are given, @code{nil} is returned:
 @end group
 @end example
 
-See @code{nconc} in @ref{Rearrangement}, for a way to join lists with no
-copying.
+Here are some examples where the final argument is not a list:
+
+@example
+(append '(x y) 'z)
+     @result{} (x y z)
+(append '(x y) [z])
+     @result{} (x y [z])
+@end example
+
+@noindent
+The second example shows that when the final argument is a sequence but
+not a list, the sequence's elements do not become elements of the
+resulting list.  Instead, the sequence becomes the final @sc{cdr}, like
+any other non-list final argument.
 
 Integers are also allowed as arguments to @code{append}.  They are
 converted to strings of digits making up the decimal print
@@ -606,8 +630,9 @@ new @sc{car} or @sc{cdr}.
 @node Setcar
 @subsection Altering List Elements with @code{setcar}
 
-  Changing the @sc{car} of a cons cell is done with @code{setcar}, which
-replaces one element of a list with a different element.
+  Changing the @sc{car} of a cons cell is done with @code{setcar}.  When
+used on a list, @code{setcar} replaces one element of a list with a
+different element.
 
 @defun setcar cons object
 This function stores @var{object} as the new @sc{car} of @var{cons},
@@ -710,8 +735,8 @@ x2:              |
   The lowest-level primitive for modifying a @sc{cdr} is @code{setcdr}:
 
 @defun setcdr cons object
-This function stores @var{object} into the @sc{cdr} of @var{cons}.  The
-value returned is @var{object}, not @var{cons}.
+This function stores @var{object} as the new @sc{cdr} of @var{cons},
+replacing its previous @sc{cdr}.  It returns the value @var{object}.
 @end defun
 
   Here is an example of replacing the @sc{cdr} of a list with a
@@ -813,6 +838,15 @@ modifying the @sc{cdr}s of their component cons cells.  We call these
 functions ``destructive'' because they chew up the original lists passed
 to them as arguments, to produce a new list that is the returned value.
 
+@ifinfo
+  See @code{delq}, in @ref{Sets And Lists}, for another function
+that modifies cons cells.
+@end ifinfo
+@iftex
+   The function @code{delq} in the following section is another example
+of destructive list manipulation.
+@end iftex
+
 @defun nconc &rest lists
 @cindex concatenating lists
 @cindex joining lists
@@ -895,10 +929,10 @@ each time you run it!  Here is what happens:
 @defun nreverse list
 @cindex reversing a list
   This function reverses the order of the elements of @var{list}.
-Unlike @code{reverse}, @code{nreverse} alters its argument destructively
-by reversing the @sc{cdr}s in the cons cells forming the list.  The cons
-cell which used to be the last one in @var{list} becomes the first cell
-of the value.
+Unlike @code{reverse}, @code{nreverse} alters its argument by reversing
+the @sc{cdr}s in the cons cells forming the list.  The cons cell that
+used to be the last one in @var{list} becomes the first cell of the
+value.
 
   For example:
 
@@ -966,6 +1000,11 @@ sorted order.  If you wish to make a sorted copy without destroying the
 original, copy it first with @code{copy-sequence} and then sort.
 
 Sorting does not change the @sc{car}s of the cons cells in @var{list};
+each cons cell in the result contains the same element that it contained
+before.  The result differs from the argument @var{list} because the
+cells themselves have been reordered.
+
+Sorting does not change the @sc{car}s of the cons cells in @var{list};
 the cons cell that originally contained the element @code{a} in
 @var{list} still has @code{a} in its @sc{car} after sorting, but it now
 appears in a different position in the list due to the change of
@@ -1003,15 +1042,6 @@ See @code{documentation} in @ref{Accessing Documentation}, for a
 useful example of @code{sort}.
 @end defun
 
-@ifinfo
-  See @code{delq}, in @ref{Sets And Lists}, for another function
-that modifies cons cells.
-@end ifinfo
-@iftex
-   The function @code{delq} in the following section is another example
-of destructive list manipulation.
-@end iftex
-
 @node Sets And Lists
 @section Using Lists as Sets
 @cindex lists as sets
@@ -1042,8 +1072,8 @@ compare @var{object} against the elements of the list.  For example:
 
 @example
 @group
-(memq 2 '(1 2 3 2 1))
-     @result{} (2 3 2 1)
+(memq 'b '(a b c b a))
+     @result{} (b c b a)
 @end group
 @group
 (memq '(2) '((1) (2)))    ; @r{@code{(2)} and @code{(2)} are not @code{eq}.}
@@ -1075,29 +1105,29 @@ removing it involves changing the @sc{cdr}s (@pxref{Setcdr}).
 
 @example
 @group
-(setq sample-list '(1 2 3 (4)))
-     @result{} (1 2 3 (4))
+(setq sample-list '(a b c (4)))
+     @result{} (a b c (4))
 @end group
 @group
-(delq 1 sample-list)
-     @result{} (2 3 (4))
+(delq 'a sample-list)
+     @result{} (b c (4))
 @end group
 @group
 sample-list
-     @result{} (1 2 3 (4))
+     @result{} (a b c (4))
 @end group
 @group
-(delq 2 sample-list)
-     @result{} (1 3 (4))
+(delq 'c sample-list)
+     @result{} (a c (4))
 @end group
 @group
 sample-list
-     @result{} (1 3 (4))
+     @result{} (a c (4))
 @end group
 @end example
 
-Note that @code{(delq 2 sample-list)} modifies @code{sample-list} to
-splice out the second element, but @code{(delq 1 sample-list)} does not
+Note that @code{(delq 'b sample-list)} modifies @code{sample-list} to
+splice out the second element, but @code{(delq 'a sample-list)} does not
 splice anything---it just returns a shorter list.  Don't assume that a
 variable which formerly held the argument @var{list} now has fewer
 elements, or that it still holds the original list!  Instead, save the
@@ -1114,7 +1144,7 @@ and the @code{(4)} in the @code{sample-list} are not @code{eq}:
 @example
 @group
 (delq '(4) sample-list)
-     @result{} (1 3 (4))
+     @result{} (a c (4))
 @end group
 @end example
 
@@ -1258,7 +1288,7 @@ For example:
      @result{} nil
 @end smallexample
 
-Here is another example in which the keys and values are not symbols:
+Here is another example, in which the keys and values are not symbols:
 
 @smallexample
 (setq needles-per-cluster
@@ -1353,18 +1383,18 @@ the new alist without changing the old one.
 @group
 (setq needles-per-cluster
       '((2 . ("Austrian Pine" "Red Pine"))
-        (3 . "Pitch Pine")
-        (5 . "White Pine")))
+        (3 . ("Pitch Pine"))
+        (5 . ("White Pine"))))
 @result{}
 ((2 "Austrian Pine" "Red Pine")
- (3 . "Pitch Pine")
- (5 . "White Pine"))
+ (3 "Pitch Pine")
+ (5 "White Pine"))
 
 (setq copy (copy-alist needles-per-cluster))
 @result{}
 ((2 "Austrian Pine" "Red Pine")
- (3 . "Pitch Pine")
- (5 . "White Pine"))
+ (3 "Pitch Pine")
+ (5 "White Pine"))
 
 (eq needles-per-cluster copy)
      @result{} nil
@@ -1373,11 +1403,23 @@ the new alist without changing the old one.
 (eq (car needles-per-cluster) (car copy))
      @result{} nil
 (cdr (car (cdr needles-per-cluster)))
-     @result{} "Pitch Pine"
+     @result{} ("Pitch Pine")
 (eq (cdr (car (cdr needles-per-cluster)))
     (cdr (car (cdr copy))))
      @result{} t
 @end group
+@end example
+
+  This example shows how @code{copy-alist} makes it possible to change
+the associations of one copy without affecting the other:
+
+@example
+@group
+(setcdr (assq 3 needles-per-cluster)
+        '("Martian Vacuum Pine"))
+(cdr (assq 3 needles-per-cluster))
+     @result{} ("Pitch Pine")
+@end group
 @end smallexample
 @end defun
 
diff --git a/lispref/objects.texi b/lispref/objects.texi
index ab2fe39a10c..6dd8912671c 100644
--- a/lispref/objects.texi
+++ b/lispref/objects.texi
@@ -3,7 +3,7 @@
 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. 
 @c See the file elisp.texi for copying conditions.
 @setfilename ../info/objects
-@node Types of Lisp Object, Numbers, Introduction, Top
+@node Lisp Data Types, Numbers, Introduction, Top
 @chapter Lisp Data Types
 @cindex object
 @cindex Lisp object
@@ -40,8 +40,8 @@ it as a number; Lisp knows it is a vector, not a number.
   In most languages, the programmer must declare the data type of each
 variable, and the type is known by the compiler but not represented in
 the data.  Such type declarations do not exist in Emacs Lisp.  A Lisp
-variable can have any type of value, and remembers the type of any value
-you store in it.
+variable can have any type of value, and it remembers whatever value
+you store in it, type and all.
 
   This chapter describes the purpose, printed representation, and read
 syntax of each of the standard types in GNU Emacs Lisp.  Details on how
@@ -132,7 +132,7 @@ latter are unique to Emacs Lisp.
 * Character Type::      The representation of letters, numbers and
                         control characters.
 * Sequence Type::       Both lists and arrays are classified as sequences.
-* List Type::           Lists gave Lisp its name (not to mention reputation).
+* Cons Cell Type::      Cons cells, and lists (which are made from cons cells).
 * Array Type::          Arrays include strings and vectors.
 * String Type::         An (efficient) array of characters.
 * Vector Type::         One-dimensional arrays.
@@ -170,7 +170,7 @@ to note that the Emacs Lisp arithmetic functions do not check for
 overflow.  Thus @code{(1+ 8388607)} is @minus{}8388608 on 24-bit
 implementations.@refill
 
-  The read syntax for numbers is a sequence of (base ten) digits with an
+  The read syntax for integers is a sequence of (base ten) digits with an
 optional sign at the beginning and an optional period at the end.  The
 printed representation produced by the Lisp interpreter never has a
 leading @samp{+} or a final @samp{.}.
@@ -242,10 +242,10 @@ character @kbd{a}.
 @end example
 
   You can use the same syntax for punctuation characters, but it is
-often a good idea to add a @samp{\} to prevent Lisp mode from getting
-confused.  For example, @samp{?\ } is the way to write the space
-character.  If the character is @samp{\}, you @emph{must} use a second
-@samp{\} to quote it: @samp{?\\}.
+often a good idea to add a @samp{\} so that the Emacs commands for
+editing Lisp code don't get confused.  For example, @samp{?\ } is the
+way to write the space character.  If the character is @samp{\}, you
+@emph{must} use a second @samp{\} to quote it: @samp{?\\}.
 
 @cindex whitespace
 @cindex bell character
@@ -336,10 +336,10 @@ outside of strings as well.)
 
   The read syntax for meta characters uses @samp{\M-}.  For example,
 @samp{?\M-A} stands for @kbd{M-A}.  You can use @samp{\M-} together with
-octal codes, @samp{\C-}, or any other syntax for a character.  Thus, you
-can write @kbd{M-A} as @samp{?\M-A}, or as @samp{?\M-\101}.  Likewise,
-you can write @kbd{C-M-b} as @samp{?\M-\C-b}, @samp{?\C-\M-b}, or
-@samp{?\M-\002}.
+octal character codes (see below), with @samp{\C-}, or with any other
+syntax for a character.  Thus, you can write @kbd{M-A} as @samp{?\M-A},
+or as @samp{?\M-\101}.  Likewise, you can write @kbd{C-M-b} as
+@samp{?\M-\C-b}, @samp{?\C-\M-b}, or @samp{?\M-\002}.
 
   The case of an ordinary letter is indicated by its character code as
 part of @sc{ASCII}, but @sc{ASCII} has no way to represent whether a
@@ -388,6 +388,74 @@ space, tab, newline and formfeed.  However, it is cleaner to use one of
 the easily readable escape sequences, such as @samp{\t}, instead of an
 actual whitespace character such as a tab.
 
+@node Symbol Type
+@subsection Symbol Type
+
+  A @dfn{symbol} in GNU Emacs Lisp is an object with a name.  The symbol
+name serves as the printed representation of the symbol.  In ordinary
+use, the name is unique---no two symbols have the same name.
+
+  A symbol can serve as a variable, as a function name, or to hold a
+property list.  Or it may serve only to be distinct from all other Lisp
+objects, so that its presence in a data structure may be recognized
+reliably.  In a given context, usually only one of these uses is
+intended.  But you can use one symbol in all of these ways,
+independently.
+
+@cindex @samp{\} in symbols
+@cindex backslash in symbols
+  A symbol name can contain any characters whatever.  Most symbol names
+are written with letters, digits, and the punctuation characters
+@samp{-+=*/}.  Such names require no special punctuation; the characters
+of the name suffice as long as the name does not look like a number.
+(If it does, write a @samp{\} at the beginning of the name to force
+interpretation as a symbol.)  The characters @samp{_~!@@$%^&:<>@{@}} are
+less often used but also require no special punctuation.  Any other
+characters may be included in a symbol's name by escaping them with a
+backslash.  In contrast to its use in strings, however, a backslash in
+the name of a symbol simply quotes the single character that follows the
+backslash.  For example, in a string, @samp{\t} represents a tab
+character; in the name of a symbol, however, @samp{\t} merely quotes the
+letter @kbd{t}.  To have a symbol with a tab character in its name, you
+must actually use a tab (preceded with a backslash).  But it's rare to
+do such a thing.
+
+@cindex CL note---case of letters
+@quotation
+@b{Common Lisp note:} in Common Lisp, lower case letters are always
+``folded'' to upper case, unless they are explicitly escaped.  This is
+in contrast to Emacs Lisp, in which upper case and lower case letters
+are distinct.
+@end quotation
+
+  Here are several examples of symbol names.  Note that the @samp{+} in
+the fifth example is escaped to prevent it from being read as a number.
+This is not necessary in the last example because the rest of the name
+makes it invalid as a number.
+
+@example
+@group
+foo                 ; @r{A symbol named @samp{foo}.}
+FOO                 ; @r{A symbol named @samp{FOO}, different from @samp{foo}.}
+char-to-string      ; @r{A symbol named @samp{char-to-string}.}
+@end group
+@group
+1+                  ; @r{A symbol named @samp{1+}}
+                    ;   @r{(not @samp{+1}, which is an integer).}
+@end group
+@group
+\+1                 ; @r{A symbol named @samp{+1}}
+                    ;   @r{(not a very readable name).}
+@end group
+@group
+\(*\ 1\ 2\)         ; @r{A symbol named @samp{(* 1 2)} (a worse name).}
+@c the @'s in this next line use up three characters, hence the
+@c apparent misalignment of the comment.
++-*/_~!@@$%^&=:<>@{@}  ; @r{A symbol named @samp{+-*/_~!@@$%^&=:<>@{@}}.}
+                    ;   @r{These characters need not be escaped.}
+@end group
+@end example
+
 @node Sequence Type
 @subsection Sequence Types
 
@@ -399,8 +467,9 @@ considered a sequence.
   Arrays are further subdivided into strings and vectors.  Vectors can
 hold elements of any type, but string elements must be characters in the
 range from 0 to 255.  However, the characters in a string can have text
-properties; vectors do not support text properties even when their
-elements happen to be characters.
+properties like characters in a buffer (@pxref{Text Properties});
+vectors do not support text properties even when their elements happen
+to be characters.
 
   Lists, strings and vectors are different, but they have important
 similarities.  For example, all have a length @var{l}, and all have
@@ -416,16 +485,19 @@ sequence twice, you get two sequences with equal contents.  There is one
 exception: the empty list @code{()} always stands for the same object,
 @code{nil}.
 
-@node List Type
-@subsection List Type
+@node Cons Cell Type
+@subsection Cons Cell and List Types
 @cindex address field of register
 @cindex decrement field of register
 
-  A @dfn{list} is a series of cons cells, linked together.  A @dfn{cons
-cell} is an object comprising two pointers named the @sc{car} and the
-@sc{cdr}.  Each of them can point to any Lisp object, but when the cons
-cell is part of a list, the @sc{cdr} points either to another cons cell
-or to the empty list.  @xref{Lists}, for functions that work on lists.
+  A @dfn{cons cell} is an object comprising two pointers named the
+@sc{car} and the @sc{cdr}.  Each of them can point to any Lisp object.
+
+  A @dfn{list} is a series of cons cells, linked together so that the
+@sc{cdr} of each cons cell points either to another cons cell or to the
+empty list.  @xref{Lists}, for functions that work on lists.  Because
+most cons cells are used as part of lists, the phrase @dfn{list
+structure} has come to refer to any structure made out of cons cells.
 
   The names @sc{car} and @sc{cdr} have only historical meaning now.  The
 original Lisp implementation ran on an @w{IBM 704} computer which
@@ -449,16 +521,16 @@ right parenthesis.
    Upon reading, each object inside the parentheses becomes an element
 of the list.  That is, a cons cell is made for each element.  The
 @sc{car} of the cons cell points to the element, and its @sc{cdr} points
-to the next cons cell which holds the next element in the list.  The
-@sc{cdr} of the last cons cell is set to point to @code{nil}.
+to the next cons cell of the list, which holds the next element in the
+list.  The @sc{cdr} of the last cons cell is set to point to @code{nil}.
 
 @cindex box diagrams, for lists
 @cindex diagrams, boxed, for lists
   A list can be illustrated by a diagram in which the cons cells are
 shown as pairs of boxes.  (The Lisp reader cannot read such an
-illustration; unlike the textual notation, which can be understood both
-humans and computers, the box illustrations can only be understood by
-humans.)  The following represents the three-element list @code{(rose
+illustration; unlike the textual notation, which can be understood by
+both humans and computers, the box illustrations can be understood only
+by humans.)  The following represents the three-element list @code{(rose
 violet buttercup)}:
 
 @example
@@ -642,7 +714,7 @@ functions that work on alists.
 
   An @dfn{array} is composed of an arbitrary number of slots for
 referring to other Lisp objects, arranged in a contiguous block of
-memory.  Accessing any element of an array takes a the same amount of
+memory.  Accessing any element of an array takes the same amount of
 time.  In contrast, accessing an element of a list requires time
 proportional to the position of the element in the list.  (Elements at
 the end of a list take longer to access than elements at the beginning
@@ -694,14 +766,20 @@ string constant, this sets the 2**7 bit of the character in the string.
 This is not the same representation that the meta modifier has in a
 character on its own (not inside a string).  @xref{Character Type}.
 
-  Strings cannot hold characters that have the hyper, super or alt
+  Strings cannot hold characters that have the hyper, super, or alt
 modifiers; they can hold @sc{ASCII} control characters, but no others.
 They do not distinguish case in @sc{ASCII} control characters.
 
-  In contrast with the C programming language, Emacs Lisp allows
-newlines in string literals.  But an escaped newline---one that is
-preceded by @samp{\}---does not become part of the string; i.e., the
-Lisp reader ignores an escaped newline in a string literal.
+  The printed representation of a string consists of a double-quote, the
+characters it contains, and another double-quote.  However, you must
+escape any backslash or double-quote characters in the string with a
+backslash, like this: @code{"this \" is an embedded quote"}.
+
+  The newline character is not special in the read syntax for strings;
+if you write a new line between the double-quotes, it becomes a
+character in the string.  But an escaped newline---one that is preceded
+by @samp{\}---does not become part of the string; i.e., the Lisp reader
+ignores an escaped newline while reading a string.
 @cindex newline in strings
 
 @example
@@ -714,11 +792,6 @@ in documentation strings,
 but the newline is ignored if escaped."
 @end example
 
-  The printed representation of a string consists of a double-quote, the
-characters it contains, and another double-quote.  However, any
-backslash or double-quote characters in the string are preceded with a
-backslash like this: @code{"this \" is an embedded quote"}.
-
   A string can hold properties of the text it contains, in addition to
 the characters themselves.  This enables programs that copy text between
 strings and buffers to preserve the properties with no special effort.
@@ -764,76 +837,8 @@ for evaluation.
 
   @xref{Vectors}, for functions that work with vectors.
 
-@node Symbol Type
-@subsection Symbol Type
-
-  A @dfn{symbol} in GNU Emacs Lisp is an object with a name.  The symbol
-name serves as the printed representation of the symbol.  In ordinary
-use, the name is unique---no two symbols have the same name.
-
-  A symbol can serve as a variable, as a function name, or to hold a
-property list.  Or it may serve only to be distinct from all other Lisp
-objects, so that its presence in a data structure may be recognized
-reliably.  In a given context, usually only one of these uses is
-intended.  But you can use one symbol in all of these ways,
-independently.
-
-@cindex @samp{\} in symbols
-@cindex backslash in symbols
-  A symbol name can contain any characters whatever.  Most symbol names
-are written with letters, digits, and the punctuation characters
-@samp{-+=*/}.  Such names require no special punctuation; the characters
-of the name suffice as long as the name does not look like a number.
-(If it does, write a @samp{\} at the beginning of the name to force
-interpretation as a symbol.)  The characters @samp{_~!@@$%^&:<>@{@}} are
-less often used but also require no special punctuation.  Any other
-characters may be included in a symbol's name by escaping them with a
-backslash.  In contrast to its use in strings, however, a backslash in
-the name of a symbol quotes the single character that follows the
-backslash, without conversion.  For example, in a string, @samp{\t}
-represents a tab character; in the name of a symbol, however, @samp{\t}
-merely quotes the letter @kbd{t}.  To have a symbol with a tab character
-in its name, you must actually use a tab (preceded with a backslash).
-But it's rare to do such a thing.
-
-@cindex CL note---case of letters
-@quotation
-@b{Common Lisp note:} in Common Lisp, lower case letters are always
-``folded'' to upper case, unless they are explicitly escaped.  This is
-in contrast to Emacs Lisp, in which upper case and lower case letters
-are distinct.
-@end quotation
-
-  Here are several examples of symbol names.  Note that the @samp{+} in
-the fifth example is escaped to prevent it from being read as a number.
-This is not necessary in the last example because the rest of the name
-makes it invalid as a number.
-
-@example
-@group
-foo                 ; @r{A symbol named @samp{foo}.}
-FOO                 ; @r{A symbol named @samp{FOO}, different from @samp{foo}.}
-char-to-string      ; @r{A symbol named @samp{char-to-string}.}
-@end group
-@group
-1+                  ; @r{A symbol named @samp{1+}}
-                    ;   @r{(not @samp{+1}, which is an integer).}
-@end group
-@group
-\+1                 ; @r{A symbol named @samp{+1}}
-                    ;   @r{(not a very readable name).}
-@end group
-@group
-\(*\ 1\ 2\)         ; @r{A symbol named @samp{(* 1 2)} (a worse name).}
-@c the @'s in this next line use up three characters, hence the
-@c apparent misalignment of the comment.
-+-*/_~!@@$%^&=:<>@{@}  ; @r{A symbol named @samp{+-*/_~!@@$%^&=:<>@{@}}.}
-                    ;   @r{These characters need not be escaped.}
-@end group
-@end example
-
-@node Lisp Function Type
-@subsection Lisp Function Type
+@node Function Type
+@subsection Function Type
 
   Just as functions in other programming languages are executable,
 @dfn{Lisp function} objects are pieces of executable code.  However,
@@ -853,8 +858,8 @@ Lisp expressions in Lisp programs.  However, you can construct or obtain
 a function object at run time and then call it with the primitive
 functions @code{funcall} and @code{apply}.  @xref{Calling Functions}.
 
-@node Lisp Macro Type
-@subsection Lisp Macro Type
+@node Macro Type
+@subsection Macro Type
 
   A @dfn{Lisp macro} is a user-defined construct that extends the Lisp
 language.  It is represented as an object much like a function, but with
@@ -887,8 +892,8 @@ Calls to the redefined function from Lisp will use the new definition,
 but calls from C code may still use the built-in definition.
 
   The term @dfn{function} refers to all Emacs functions, whether written
-in Lisp or C.  @xref{Lisp Function Type}, for information about the
-functions written in Lisp.@refill
+in Lisp or C.  @xref{Function Type}, for information about the
+functions written in Lisp.
 
   Primitive functions have no read syntax and print in hash notation
 with the name of the subroutine.
@@ -977,9 +982,10 @@ object.
   Each buffer has a designated position called @dfn{point}
 (@pxref{Positions}).  At any time, one buffer is the @dfn{current
 buffer}.  Most editing commands act on the contents of the current
-buffer in the neighborhood of point.  Many other functions manipulate or
-test the characters in the current buffer; a whole chapter in this
-manual is devoted to describing these functions (@pxref{Text}).
+buffer in the neighborhood of point.  Many of the standard Emacs
+functions manipulate or test the characters in the current buffer; a
+whole chapter in this manual is devoted to describing these functions
+(@pxref{Text}).
 
   Several other data structures are associated with each buffer:
 
@@ -995,7 +1001,7 @@ a local variable binding list (@pxref{Buffer-Local Variables}).
 @end itemize
 
 @noindent
-The local keymap and variable list contain entries which individually
+The local keymap and variable list contain entries that individually
 override global bindings or values.  These are used to customize the
 behavior of programs in different buffers, without actually changing the
 programs.
@@ -1144,8 +1150,8 @@ Area}).
   Streams have no special printed representation or read syntax, and
 print as whatever primitive type they are.
 
-  @xref{Streams}, for a description of various functions related to
-streams, including various parsing and printing functions.
+  @xref{Streams, Reading and Printing}, for a description of functions
+related to streams, including parsing and printing functions.
 
 @node Keymap Type
 @subsection Keymap Type
@@ -1167,7 +1173,7 @@ character is punctuation, but in Lisp mode it is a valid character in a
 symbol.  These modes specify different interpretations by changing the
 syntax table entry for @samp{+}, at index 43 in the syntax table.
 
-  Syntax tables are only used for scanning text in buffers, not for
+  Syntax tables are used only for scanning text in buffers, not for
 reading Lisp expressions.  The table the Lisp interpreter uses to read
 expressions is built into the Emacs source code and cannot be changed;
 thus, to change the list delimiters to be @samp{@{} and @samp{@}}
@@ -1212,7 +1218,7 @@ a type that the function can use.
   All built-in functions do check the types of their actual arguments
 when appropriate, and signal a @code{wrong-type-argument} error if an
 argument is of the wrong type.  For example, here is what happens if you
-pass an argument to @code{+} which it cannot handle:
+pass an argument to @code{+} that it cannot handle:
 
 @example
 @group
@@ -1279,8 +1285,8 @@ with references to further information.
 @item markerp
 @xref{Predicates on Markers, markerp}.
 
-@item natnump
-@xref{Predicates on Numbers, natnump}.
+@item wholenump
+@xref{Predicates on Numbers, wholenump}.
 
 @item nlistp
 @xref{List-related Predicates, nlistp}.
@@ -1334,8 +1340,8 @@ with references to further information.
 
   Here we describe two functions that test for equality between any two
 objects.  Other functions test equality between objects of specific
-types, e.g., strings.  See the appropriate chapter describing the data
-type for these predicates.
+types, e.g., strings.  For these predicates, see the appropriate chapter
+describing the data type.
 
 @defun eq object1 object2
 This function returns @code{t} if @var{object1} and @var{object2} are
diff --git a/lispref/symbols.texi b/lispref/symbols.texi
index 39f1bbcb80c..7d7825d88fc 100644
--- a/lispref/symbols.texi
+++ b/lispref/symbols.texi
@@ -41,7 +41,7 @@ references another object:
 @table @asis
 @item Print name
 @cindex print name cell
-The @dfn{print name cell} holds a string which names the symbol for
+The @dfn{print name cell} holds a string that names the symbol for
 reading and printing.  See @code{symbol-name} in @ref{Creating Symbols}.
 
 @item Value
@@ -93,7 +93,7 @@ to see a property list there.
   The function cell or the value cell may be @dfn{void}, which means
 that the cell does not reference any object.  (This is not the same
 thing as holding the symbol @code{void}, nor the same as holding the
-symbol @code{nil}.)  Examining a cell which is void results in an error,
+symbol @code{nil}.)  Examining a cell that is void results in an error,
 such as @samp{Symbol's value as variable is void}.
 
   The four functions @code{symbol-name}, @code{symbol-value},
@@ -194,18 +194,24 @@ given hash code; to look for a given name, it is sufficient to look
 through all the symbols in the bucket for that name's hash code.
 
 @cindex interning
-  If a symbol with the desired name is found, then it is used.  If no
-such symbol is found, then a new symbol is created and added to the
-obarray bucket.  Adding a symbol to an obarray is called @dfn{interning}
-it, and the symbol is then called an @dfn{interned symbol}.
+  If a symbol with the desired name is found, the reader uses that
+symbol.  If the obarray does not contain a symbol with that name, the
+reader makes a new symbol and adds it to the obarray.  Finding or adding
+a symbol with a certain name is called @dfn{interning} it, and the
+symbol is then called an @dfn{interned symbol}.
+
+  Interning ensures that each obarray has just one symbol with any
+particular name.  Other like-named symbols may exist, but not in the
+same obarray.  Thus, the reader gets the same symbols for the same
+names, as long as you keep reading with the same obarray.
 
 @cindex symbol equality
 @cindex uninterned symbol
-  If a symbol is not in the obarray, then there is no way for Lisp to
-find it when its name is read.  Such a symbol is called an
-@dfn{uninterned symbol} relative to the obarray.  An uninterned symbol
-has all the other characteristics of interned symbols; it has the same
-four cells and they work in the usual way.
+  No obarray contains all symbols; in fact, some symbols are not in any
+obarray.  They are called @dfn{uninterned symbols}.  An uninterned
+symbol has the same four cells as other symbols; however, the only way
+to gain access to it is by finding it in some other object or as the
+value of a variable.
 
   In Emacs Lisp, an obarray is actually a vector.  Each element of the
 vector is a bucket; its value is either an interned symbol whose name
@@ -323,7 +329,7 @@ This variable is the standard obarray for use by @code{intern} and
 @end defvar
 
 @defun mapatoms function &optional obarray
-This function call @var{function} for each symbol in the obarray
+This function calls @var{function} for each symbol in the obarray
 @var{obarray}.  It returns @code{nil}.  If @var{obarray} is omitted, it
 defaults to the value of @code{obarray}, the standard obarray for
 ordinary symbols.
@@ -353,9 +359,9 @@ example using @code{mapatoms}.
 elements stored in the property list cell of a symbol.  Each of the
 pairs associates a property name (usually a symbol) with a property or
 value.  Property lists are generally used to record information about a
-symbol, such as how to compile it, the name of the file where it was
-defined, or perhaps even the grammatical class of the symbol
-(representing a word) in a language understanding system.
+symbol, such as its documentation as a variable, the name of the file
+where it was defined, or perhaps even the grammatical class of the
+symbol (representing a word) in a language-understanding system.
 
   Character positions in a string or buffer can also have property lists.
 @xref{Text Properties}.