Update several Lisp manual chapters.

* doc/lispref/eval.texi (Intro Eval, Symbol Forms): Minor tweaks for
correctness with lexical scoping.
(Eval): Copyedits.

* doc/lispref/sequences.texi (Sequence Functions): Don't repeat the
introduction already given in the parent.
(Vectors): Copyedits.
(Rings): Move from lists.texi.  Note that this is specific to the
ring package.

* doc/lispref/lists.texi (Cons Cells): Copyedits.
(List Elements): Mention push.
(List Variables): Mention pop.
(Rings): Move to sequences.texi.

* doc/lispref/strings.texi (Text Comparison): Minor qualification.

* doc/lispref/symbols.texi (Definitions, Symbol Components): Mention variable
scoping issues.
(Plists and Alists): Copyedits.

9 files changed, 281 insertions, 269 deletions

diff --git a/admin/FOR-RELEASE b/admin/FOR-RELEASE
index 9335e5b1fbe..f704a3c9397 100644
--- a/admin/FOR-RELEASE
+++ b/admin/FOR-RELEASE
@@ -187,25 +187,25 @@ backups.texi
 buffers.texi      
 commands.texi     
 compile.texi      
-control.texi      
+control.texi      cyd
 customize.texi    
 debugging.texi    
 display.texi      
 edebug.texi
 elisp.texi
 errors.texi       
-eval.texi         
+eval.texi         cyd
 files.texi        
 frames.texi       
 functions.texi    
-hash.texi         
+hash.texi         cyd
 help.texi         
 hooks.texi        
 index.texi
 internals.texi    
 intro.texi        cyd
 keymaps.texi      
-lists.texi        
+lists.texi        cyd
 loading.texi      
 locals.texi       
 macros.texi       
@@ -214,17 +214,17 @@ markers.texi
 minibuf.texi      
 modes.texi        
 nonascii.texi     
-numbers.texi      
+numbers.texi      cyd
 objects.texi      cyd
 os.texi           
 package.texi
 positions.texi    
 processes.texi
 searching.texi    
-sequences.texi    
+sequences.texi    cyd
 streams.texi      
-strings.texi      
-symbols.texi      
+strings.texi      cyd
+symbols.texi      cyd
 syntax.texi       
 text.texi         
 tips.texi         
@@ -232,8 +232,7 @@ variables.texi
 windows.texi      
 
 * PLANNED ADDITIONS
-
-** pov-mode (probably not for Emacs-23: waiting for a Free POV-Ray).
+* pov-mode (probably not for Emacs-23: waiting for a Free POV-Ray).
 ** gas-mode ?
 
 
diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 3c18de96d72..b66f82c5738 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,26 @@
+2012-01-23  Chong Yidong  <cyd@gnu.org>
+
+        * strings.texi (Text Comparison): Minor qualification.
+
+        * lists.texi (Cons Cells): Copyedits.
+        (List Elements): Mention push.
+        (List Variables): Mention pop.
+        (Rings): Move to sequences.texi.
+
+        * sequences.texi (Sequence Functions): Don't repeat the
+        introduction already given in the parent.
+        (Vectors): Copyedits.
+        (Rings): Move from lists.texi.  Note that this is specific to the
+        ring package.
+
+        * symbols.texi (Definitions, Symbol Components): Mention variable
+        scoping issues.
+        (Plists and Alists): Copyedits.
+
+        * eval.texi (Intro Eval, Symbol Forms): Minor tweaks for
+        correctness with lexical scoping.
+        (Eval): Copyedits.
+
 2012-01-21  Chong Yidong  <cyd@gnu.org>
 
         * intro.texi (A Sample Function Description): Special notation
diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi
index e74f3e198bf..0511f21007d 100644
--- a/doc/lispref/control.texi
+++ b/doc/lispref/control.texi
@@ -8,11 +8,11 @@
 @cindex special forms for control structures
 @cindex control structures
 
-  A Lisp program consists of expressions or @dfn{forms} (@pxref{Forms}).
-We control the order of execution of these forms by enclosing them in
-@dfn{control structures}.  Control structures are special forms which
-control when, whether, or how many times to execute the forms they
-contain.
+  A Lisp program consists of a set of @dfn{expressions}, or
+@dfn{forms} (@pxref{Forms}).  We control the order of execution of
+these forms by enclosing them in @dfn{control structures}.  Control
+structures are special forms which control when, whether, or how many
+times to execute the forms they contain.
 
 @cindex textual order
   The simplest order of execution is sequential execution: first form
diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi
index 0b8d972c1d5..1555b98e7fb 100644
--- a/doc/lispref/elisp.texi
+++ b/doc/lispref/elisp.texi
@@ -326,7 +326,6 @@ Lists
 * Modifying Lists::         Storing new pieces into an existing list.
 * Sets And Lists::          A list can represent a finite mathematical set.
 * Association Lists::       A list can represent a finite relation or mapping.
-* Rings::                   Managing a fixed-size ring of objects.
 
 Modifying Existing List Structure
 
@@ -344,6 +343,7 @@ Sequences, Arrays, and Vectors
 * Vector Functions::        Functions specifically for vectors.
 * Char-Tables::             How to work with char-tables.
 * Bool-Vectors::            How to work with bool-vectors.
+* Rings::                   Managing a fixed-size ring of objects.
 
 Hash Tables
 
diff --git a/doc/lispref/eval.texi b/doc/lispref/eval.texi
index adb4841a82d..fc18e503543 100644
--- a/doc/lispref/eval.texi
+++ b/doc/lispref/eval.texi
@@ -64,8 +64,8 @@ evaluate a @dfn{function call} form such as @code{(car x)}, Emacs
 first evaluates the argument (the subform @code{x}).  After evaluating
 the argument, Emacs @dfn{executes} the function (@code{car}), and if
 the function is written in Lisp, execution works by evaluating the
-@dfn{body} of the function.  (In this example, however, @code{car} is
-not a Lisp function; it is a primitive function implemented in C.)
+@dfn{body} of the function (in this example, however, @code{car} is
+not a Lisp function; it is a primitive function implemented in C).
 @xref{Functions}, for more information about functions and function
 calls.
 
@@ -77,9 +77,8 @@ variables (@pxref{Variables}).@footnote{This definition of
 that can affect the result of a program.}  Whenever a form refers to a
 variable without creating a new binding for it, the variable evaluates
 to the value given by the current environment.  Evaluating a form may
-create a new environment for recursive evaluation, by binding
-variables (@pxref{Local Variables}).  Such environments are temporary,
-and vanish when the evaluation of the form is complete.
+also temporarily alter the environment by binding variables
+(@pxref{Local Variables}).
 
 @cindex side effect
   Evaluating a form may also make changes that persist; these changes
@@ -177,9 +176,9 @@ program.  Here is an example:
 @cindex symbol evaluation
 
   When a symbol is evaluated, it is treated as a variable.  The result
-is the variable's value, if it has one.  If it has none (if its value
-cell is void), an error is signaled.  For more information on the use of
-variables, see @ref{Variables}.
+is the variable's value, if it has one.  If the symbol has no value as
+a variable, the Lisp interpreter signals an error.  For more
+information on the use of variables, see @ref{Variables}.
 
   In the following example, we set the value of a symbol with
 @code{setq}.  Then we evaluate the symbol, and get back the value that
@@ -602,12 +601,13 @@ functions provides the ability to pass information to them as
 arguments.
 
 @defun eval form &optional lexical
-This is the basic function evaluating an expression.  It evaluates
+This is the basic function for evaluating an expression.  It evaluates
 @var{form} in the current environment and returns the result.  How the
 evaluation proceeds depends on the type of the object (@pxref{Forms}).
-@var{lexical} if non-nil means to evaluate @var{form} using lexical scoping
-rules (@pxref{Lexical Binding}) instead of the default dynamic scoping used
-historically in Emacs Lisp.
+
+The argument @var{lexical}, if non-@code{nil}, means to evaluate
+@var{form} using lexical scoping rules for variables, instead of the
+default dynamic scoping rules.  @xref{Lexical Binding}.
 
 Since @code{eval} is a function, the argument expression that appears
 in a call to @code{eval} is evaluated twice: once as preparation before
diff --git a/doc/lispref/lists.texi b/doc/lispref/lists.texi
index eb9ddf58603..c8433c79b54 100644
--- a/doc/lispref/lists.texi
+++ b/doc/lispref/lists.texi
@@ -23,7 +23,6 @@ the whole list.
 * Modifying Lists::     Storing new pieces into an existing list.
 * Sets And Lists::      A list can represent a finite mathematical set.
 * Association Lists::   A list can represent a finite relation or mapping.
-* Rings::               Managing a fixed-size ring of objects.
 @end menu
 
 @node Cons Cells
@@ -31,61 +30,56 @@ the whole list.
 @cindex lists and cons cells
 
   Lists in Lisp are not a primitive data type; they are built up from
-@dfn{cons cells}.  A cons cell is a data object that represents an
-ordered pair.  That is, it has two slots, and each slot @dfn{holds}, or
-@dfn{refers to}, some Lisp object.  One slot is known as the @sc{car},
-and the other is known as the @sc{cdr}.  (These names are traditional;
-see @ref{Cons Cell Type}.)  @sc{cdr} is pronounced ``could-er.''
+@dfn{cons cells} (@pxref{Cons Cell Type}).  A cons cell is a data
+object that represents an ordered pair.  That is, it has two slots,
+and each slot @dfn{holds}, or @dfn{refers to}, some Lisp object.  One
+slot is known as the @sc{car}, and the other is known as the @sc{cdr}.
+(These names are traditional; see @ref{Cons Cell Type}.)  @sc{cdr} is
+pronounced ``could-er.''
 
   We say that ``the @sc{car} of this cons cell is'' whatever object
 its @sc{car} slot currently holds, and likewise for the @sc{cdr}.
 
   A list is a series of cons cells ``chained together,'' so that each
-cell refers to the next one.  There is one cons cell for each element of
-the list.  By convention, the @sc{car}s of the cons cells hold the
-elements of the list, and the @sc{cdr}s are used to chain the list: the
-@sc{cdr} slot of each cons cell refers to the following cons cell.  The
-@sc{cdr} of the last cons cell is @code{nil}.  This asymmetry between
-the @sc{car} and the @sc{cdr} is entirely a matter of convention; at the
-level of cons cells, the @sc{car} and @sc{cdr} slots have the same
-characteristics.
+cell refers to the next one.  There is one cons cell for each element
+of the list.  By convention, the @sc{car}s of the cons cells hold the
+elements of the list, and the @sc{cdr}s are used to chain the list
+(this asymmetry between @sc{car} and @sc{cdr} is entirely a matter of
+convention; at the level of cons cells, the @sc{car} and @sc{cdr}
+slots have similar properties).  Hence, the @sc{cdr} slot of each cons
+cell in a list refers to the following cons cell.
 
 @cindex true list
-  Since @code{nil} is the conventional value to put in the @sc{cdr} of
-the last cons cell in the list, we call that case a @dfn{true list}.
-
-  In Lisp, we consider the symbol @code{nil} a list as well as a
-symbol; it is the list with no elements.  For convenience, the symbol
+  Also by convention, the @sc{cdr} of the last cons cell in a list is
+@code{nil}.  We call such a @code{nil}-terminated structure a
+@dfn{true list}.  In Emacs Lisp, the symbol @code{nil} is both a
+symbol and a list with no elements.  For convenience, the symbol
 @code{nil} is considered to have @code{nil} as its @sc{cdr} (and also
-as its @sc{car}).  Therefore, the @sc{cdr} of a true list is always a
-true list.
+as its @sc{car}).
+
+  Hence, the @sc{cdr} of a true list is always a true list.  The
+@sc{cdr} of a nonempty true list is a true list containing all the
+elements except the first.
 
 @cindex dotted list
 @cindex circular list
-  If the @sc{cdr} of a list's last cons cell is some other value,
-neither @code{nil} nor another cons cell, we call the structure a
-@dfn{dotted list}, since its printed representation would use
-@samp{.}.  There is one other possibility: some cons cell's @sc{cdr}
-could point to one of the previous cons cells in the list.  We call
-that structure a @dfn{circular list}.
+  If the @sc{cdr} of a list's last cons cell is some value other than
+@code{nil}, we call the structure a @dfn{dotted list}, since its
+printed representation would use dotted pair notation (@pxref{Dotted
+Pair Notation}).  There is one other possibility: some cons cell's
+@sc{cdr} could point to one of the previous cons cells in the list.
+We call that structure a @dfn{circular list}.
 
   For some purposes, it does not matter whether a list is true,
-circular or dotted.  If the program doesn't look far enough down the
+circular or dotted.  If a program doesn't look far enough down the
 list to see the @sc{cdr} of the final cons cell, it won't care.
 However, some functions that operate on lists demand true lists and
 signal errors if given a dotted list.  Most functions that try to find
 the end of a list enter infinite loops if given a circular list.
 
 @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 @sc{cdr} of any nonempty true list @var{l} is a list containing all the
-elements of @var{l} except the first.
-
-  @xref{Cons Cell Type}, for the read and print syntax of cons cells and
-lists, and for ``box and arrow'' illustrations of lists.
+  Because most cons cells are used as part of lists, we refer to any
+structure made out of cons cells as a @dfn{list structure}.
 
 @node List-related Predicates
 @section Predicates on Lists
@@ -257,6 +251,10 @@ x
 x
      @result{} (b c)
 @end example
+
+@noindent
+For the @code{pop} macro, which removes an element from a list,
+@xref{List Variables}.
 @end defmac
 
 @defun nth n list
@@ -695,6 +693,10 @@ This macro provides an alternative way to write
 l
      @result{} (c a b)
 @end example
+
+@noindent
+For the @code{pop} macro, which removes the first element from a list,
+@xref{List Elements}.
 @end defmac
 
   Two functions modify lists that are the values of variables.
@@ -1800,90 +1802,3 @@ often modifies the original list structure of @var{alist}.
 compares the @sc{cdr} of each @var{alist} association instead of the
 @sc{car}.
 @end defun
-
-@node Rings
-@section Managing a Fixed-Size Ring of Objects
-
-@cindex ring data structure
-  This section describes functions for operating on rings.  A
-@dfn{ring} is a fixed-size data structure that supports insertion,
-deletion, rotation, and modulo-indexed reference and traversal.
-
-@defun make-ring size
-This returns a new ring capable of holding @var{size} objects.
-@var{size} should be an integer.
-@end defun
-
-@defun ring-p object
-This returns @code{t} if @var{object} is a ring, @code{nil} otherwise.
-@end defun
-
-@defun ring-size ring
-This returns the maximum capacity of the @var{ring}.
-@end defun
-
-@defun ring-length ring
-This returns the number of objects that @var{ring} currently contains.
-The value will never exceed that returned by @code{ring-size}.
-@end defun
-
-@defun ring-elements ring
-This returns a list of the objects in @var{ring}, in order, newest first.
-@end defun
-
-@defun ring-copy ring
-This returns a new ring which is a copy of @var{ring}.
-The new ring contains the same (@code{eq}) objects as @var{ring}.
-@end defun
-
-@defun ring-empty-p ring
-This returns @code{t} if @var{ring} is empty, @code{nil} otherwise.
-@end defun
-
-  The newest element in the ring always has index 0.  Higher indices
-correspond to older elements.  Indices are computed modulo the ring
-length.  Index @minus{}1 corresponds to the oldest element, @minus{}2
-to the next-oldest, and so forth.
-
-@defun ring-ref ring index
-This returns the object in @var{ring} found at index @var{index}.
-@var{index} may be negative or greater than the ring length.  If
-@var{ring} is empty, @code{ring-ref} signals an error.
-@end defun
-
-@defun ring-insert ring object
-This inserts @var{object} into @var{ring}, making it the newest
-element, and returns @var{object}.
-
-If the ring is full, insertion removes the oldest element to
-make room for the new element.
-@end defun
-
-@defun ring-remove ring &optional index
-Remove an object from @var{ring}, and return that object.  The
-argument @var{index} specifies which item to remove; if it is
-@code{nil}, that means to remove the oldest item.  If @var{ring} is
-empty, @code{ring-remove} signals an error.
-@end defun
-
-@defun ring-insert-at-beginning ring object
-This inserts @var{object} into @var{ring}, treating it as the oldest
-element.  The return value is not significant.
-
-If the ring is full, this function removes the newest element to make
-room for the inserted element.
-@end defun
-
-@cindex fifo data structure
-  If you are careful not to exceed the ring size, you can
-use the ring as a first-in-first-out queue.  For example:
-
-@lisp
-(let ((fifo (make-ring 5)))
-  (mapc (lambda (obj) (ring-insert fifo obj))
-        '(0 one "two"))
-  (list (ring-remove fifo) t
-        (ring-remove fifo) t
-        (ring-remove fifo)))
-     @result{} (0 t one t "two")
-@end lisp
diff --git a/doc/lispref/sequences.texi b/doc/lispref/sequences.texi
index 0ea32f99e12..94f1bf666d2 100644
--- a/doc/lispref/sequences.texi
+++ b/doc/lispref/sequences.texi
@@ -8,10 +8,10 @@
 @chapter Sequences, Arrays, and Vectors
 @cindex sequence
 
-  Recall that the @dfn{sequence} type is the union of two other Lisp
-types: lists and arrays.  In other words, any list is a sequence, and
-any array is a sequence.  The common property that all sequences have is
-that each is an ordered collection of elements.
+  The @dfn{sequence} type is the union of two other Lisp types: lists
+and arrays.  In other words, any list is a sequence, and any array is
+a sequence.  The common property that all sequences have is that each
+is an ordered collection of elements.
 
   An @dfn{array} is a fixed-length object with a slot for each of its
 elements.  All the elements are accessible in constant time.  The four
@@ -54,19 +54,17 @@ But it is possible to add elements to the list, or remove elements.
 * Vector Functions::      Functions specifically for vectors.
 * Char-Tables::           How to work with char-tables.
 * Bool-Vectors::          How to work with bool-vectors.
+* Rings::                 Managing a fixed-size ring of objects.
 @end menu
 
 @node Sequence Functions
 @section Sequences
 
-  In Emacs Lisp, a @dfn{sequence} is either a list or an array.  The
-common property of all sequences is that they are ordered collections of
-elements.  This section describes functions that accept any kind of
-sequence.
+  This section describes functions that accept any kind of sequence.
 
 @defun sequencep object
-Returns @code{t} if @var{object} is a list, vector, string,
-bool-vector, or char-table, @code{nil} otherwise.
+This function returns @code{t} if @var{object} is a list, vector,
+string, bool-vector, or char-table, @code{nil} otherwise.
 @end defun
 
 @defun length sequence
@@ -149,8 +147,9 @@ This function generalizes @code{aref} (@pxref{Array Functions}) and
 
 @defun copy-sequence sequence
 @cindex copying sequences
-Returns a copy of @var{sequence}.  The copy is the same type of object
-as the original sequence, and it has the same elements in the same order.
+This function returns a copy of @var{sequence}.  The copy is the same
+type of object as the original sequence, and it has the same elements
+in the same order.
 
 Storing a new element into the copy does not affect the original
 @var{sequence}, and vice versa.  However, the elements of the new
@@ -394,8 +393,8 @@ symbol-lookup tables (@pxref{Creating Symbols}), as part of the
 representation of a byte-compiled function (@pxref{Byte Compilation}),
 and more.
 
-  In Emacs Lisp, the indices of the elements of a vector start from zero
-and count up from there.
+  Like other arrays, vectors use zero-origin indexing: the first
+element has index 0.
 
   Vectors are printed with square brackets surrounding the elements.
 Thus, a vector whose elements are the symbols @code{a}, @code{b} and
@@ -728,3 +727,96 @@ bv
 @noindent
 These results make sense because the binary codes for control-_ and
 control-W are 11111 and 10111, respectively.
+
+@node Rings
+@section Managing a Fixed-Size Ring of Objects
+
+@cindex ring data structure
+  A @dfn{ring} is a fixed-size data structure that supports insertion,
+deletion, rotation, and modulo-indexed reference and traversal.  An
+efficient ring data structure is implemented by the @code{ring}
+package.  It provides the functions listed in this section.
+
+  Note that several ``rings'' in Emacs, like the kill ring and the
+mark ring, are actually implemented as simple lists, @emph{not} using
+the @code{ring} package; thus the following functions won't work on
+them.
+
+@defun make-ring size
+This returns a new ring capable of holding @var{size} objects.
+@var{size} should be an integer.
+@end defun
+
+@defun ring-p object
+This returns @code{t} if @var{object} is a ring, @code{nil} otherwise.
+@end defun
+
+@defun ring-size ring
+This returns the maximum capacity of the @var{ring}.
+@end defun
+
+@defun ring-length ring
+This returns the number of objects that @var{ring} currently contains.
+The value will never exceed that returned by @code{ring-size}.
+@end defun
+
+@defun ring-elements ring
+This returns a list of the objects in @var{ring}, in order, newest first.
+@end defun
+
+@defun ring-copy ring
+This returns a new ring which is a copy of @var{ring}.
+The new ring contains the same (@code{eq}) objects as @var{ring}.
+@end defun
+
+@defun ring-empty-p ring
+This returns @code{t} if @var{ring} is empty, @code{nil} otherwise.
+@end defun
+
+  The newest element in the ring always has index 0.  Higher indices
+correspond to older elements.  Indices are computed modulo the ring
+length.  Index @minus{}1 corresponds to the oldest element, @minus{}2
+to the next-oldest, and so forth.
+
+@defun ring-ref ring index
+This returns the object in @var{ring} found at index @var{index}.
+@var{index} may be negative or greater than the ring length.  If
+@var{ring} is empty, @code{ring-ref} signals an error.
+@end defun
+
+@defun ring-insert ring object
+This inserts @var{object} into @var{ring}, making it the newest
+element, and returns @var{object}.
+
+If the ring is full, insertion removes the oldest element to
+make room for the new element.
+@end defun
+
+@defun ring-remove ring &optional index
+Remove an object from @var{ring}, and return that object.  The
+argument @var{index} specifies which item to remove; if it is
+@code{nil}, that means to remove the oldest item.  If @var{ring} is
+empty, @code{ring-remove} signals an error.
+@end defun
+
+@defun ring-insert-at-beginning ring object
+This inserts @var{object} into @var{ring}, treating it as the oldest
+element.  The return value is not significant.
+
+If the ring is full, this function removes the newest element to make
+room for the inserted element.
+@end defun
+
+@cindex fifo data structure
+  If you are careful not to exceed the ring size, you can
+use the ring as a first-in-first-out queue.  For example:
+
+@lisp
+(let ((fifo (make-ring 5)))
+  (mapc (lambda (obj) (ring-insert fifo obj))
+        '(0 one "two"))
+  (list (ring-remove fifo) t
+        (ring-remove fifo) t
+        (ring-remove fifo)))
+     @result{} (0 t one t "two")
+@end lisp
diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi
index 49199d3e32f..bbb75f1474d 100644
--- a/doc/lispref/strings.texi
+++ b/doc/lispref/strings.texi
@@ -410,8 +410,13 @@ in case if @code{case-fold-search} is non-@code{nil}.
 @defun string= string1 string2
 This function returns @code{t} if the characters of the two strings
 match exactly.  Symbols are also allowed as arguments, in which case
-their print names are used.
-Case is always significant, regardless of @code{case-fold-search}.
+the symbol names are used.  Case is always significant, regardless of
+@code{case-fold-search}.
+
+This function is equivalent to @code{equal} for comparing two strings
+(@pxref{Equality Predicates}).  In particular, the text properties of
+the two strings are ignored.  But if either argument is not a string
+or symbol, an error is signaled.
 
 @example
 (string= "abc" "abc")
@@ -422,10 +427,6 @@ Case is always significant, regardless of @code{case-fold-search}.
      @result{} nil
 @end example
 
-The function @code{string=} ignores the text properties of the two
-strings.  When @code{equal} (@pxref{Equality Predicates}) compares two
-strings, it uses @code{string=}.
-
 For technical reasons, a unibyte and a multibyte string are
 @code{equal} if and only if they contain the same sequence of
 character codes and all these codes are either in the range 0 through
diff --git a/doc/lispref/symbols.texi b/doc/lispref/symbols.texi
index 866a63c4cd9..0ee22b905b6 100644
--- a/doc/lispref/symbols.texi
+++ b/doc/lispref/symbols.texi
@@ -41,62 +41,58 @@ references another object:
 @table @asis
 @item Print name
 @cindex print name cell
-The @dfn{print name cell} holds a string that names the symbol for
-reading and printing.  See @code{symbol-name} in @ref{Creating Symbols}.
+The symbol's name.
 
 @item Value
 @cindex value cell
-The @dfn{value cell} holds the current value of the symbol as a
-variable.  When a symbol is used as a form, the value of the form is the
-contents of the symbol's value cell.  See @code{symbol-value} in
-@ref{Accessing Variables}.
+The symbol's current value as a variable.
 
 @item Function
 @cindex function cell
-The @dfn{function cell} holds the function definition of the symbol.
-When a symbol is used as a function, its function definition is used in
-its place.  This cell is also used to make a symbol stand for a keymap
-or a keyboard macro, for editor command execution.  Because each symbol
-has separate value and function cells, variables names and function names do
-not conflict.  See @code{symbol-function} in @ref{Function Cells}.
+The symbol's function definition.  It can also hold a symbol, a
+keymap, or a keyboard macro.
 
 @item Property list
 @cindex property list cell
-The @dfn{property list cell} holds the property list of the symbol.  See
-@code{symbol-plist} in @ref{Property Lists}.
+The symbol's property list.
 @end table
 
-  The print name cell always holds a string, and cannot be changed.  The
-other three cells can be set individually to any specified Lisp object.
-
-  The print name cell holds the string that is the name of the symbol.
-Since symbols are represented textually by their names, it is important
-not to have two symbols with the same name.  The Lisp reader ensures
-this: every time it reads a symbol, it looks for an existing symbol with
-the specified name before it creates a new one.  (In GNU Emacs Lisp,
-this lookup uses a hashing algorithm and an obarray; see @ref{Creating
-Symbols}.)
-
-  The value cell holds the symbol's value as a variable
-(@pxref{Variables}).  That is what you get if you evaluate the symbol as
-a Lisp expression (@pxref{Evaluation}).  Any Lisp object is a legitimate
-value.  Certain symbols have values that cannot be changed; these
-include @code{nil} and @code{t}, and any symbol whose name starts with
-@samp{:} (those are called @dfn{keywords}).  @xref{Constant Variables}.
-
-  We often refer to ``the function @code{foo}'' when we really mean
-the function stored in the function cell of the symbol @code{foo}.  We
-make the distinction explicit only when necessary.  In normal
-usage, the function cell usually contains a function
-(@pxref{Functions}) or a macro (@pxref{Macros}), as that is what the
-Lisp interpreter expects to see there (@pxref{Evaluation}).  Keyboard
-macros (@pxref{Keyboard Macros}), keymaps (@pxref{Keymaps}) and
-autoload objects (@pxref{Autoloading}) are also sometimes stored in
-the function cells of symbols.
+@noindent
+The print name cell always holds a string, and cannot be changed.
+Each of the other three cells can be set to any Lisp object.
+
+  The print name cell holds the string that is the name of a symbol.
+Since symbols are represented textually by their names, it is
+important not to have two symbols with the same name.  The Lisp reader
+ensures this: every time it reads a symbol, it looks for an existing
+symbol with the specified name before it creates a new one.  To get a
+symbol's name, use the function @code{symbol-name} (@pxref{Creating
+Symbols}).
+
+  The value cell holds a symbol's value as a variable, which is what
+you get if the symbol itself is evaluated as a Lisp expression.
+@xref{Variables}, for details about how values are set and retrieved,
+including complications such as @dfn{local bindings} and @dfn{scoping
+rules}.  Most symbols can have any Lisp object as a value, but certain
+special symbols have values that cannot be changed; these include
+@code{nil} and @code{t}, and any symbol whose name starts with
+@samp{:} (those are called @dfn{keywords}).  @xref{Constant
+Variables}.
+
+  The function cell holds a symbol's function definition.  Often, we
+refer to ``the function @code{foo}'' when we really mean the function
+stored in the function cell of @code{foo}; we make the distinction
+explicit only when necessary.  Typically, the function cell is used to
+hold a function (@pxref{Functions}) or a macro (@pxref{Macros}).
+However, it can also be used to hold a symbol (@pxref{Function
+Indirection}), keyboard macro (@pxref{Keyboard Macros}), keymap
+(@pxref{Keymaps}), or autoload object (@pxref{Autoloading}).  To get
+the contents of a symbol's function cell, use the function
+@code{symbol-function} (@pxref{Function Cells}).
 
   The property list cell normally should hold a correctly formatted
-property list (@pxref{Property Lists}), as a number of functions expect
-to see a property list there.
+property list.  To get a symbol's function cell, use the function
+@code{symbol-plist}.  @xref{Property Lists}.
 
   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
@@ -104,57 +100,43 @@ thing as holding the symbol @code{void}, nor the same as holding the
 symbol @code{nil}.)  Examining a function or value 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},
-@code{symbol-plist}, and @code{symbol-function} return the contents of
-the four cells of a symbol.  Here as an example we show the contents of
-the four cells of the symbol @code{buffer-file-name}:
+  Because each symbol has separate value and function cells, variables
+names and function names do not conflict.  For example, the symbol
+@code{buffer-file-name} has a value (the name of the file being
+visited in the current buffer) as well as a function definition (a
+primitive function that returns the name of the file):
 
 @example
-(symbol-name 'buffer-file-name)
-     @result{} "buffer-file-name"
-(symbol-value 'buffer-file-name)
+buffer-file-name
      @result{} "/gnu/elisp/symbols.texi"
 (symbol-function 'buffer-file-name)
      @result{} #<subr buffer-file-name>
-(symbol-plist 'buffer-file-name)
-     @result{} (variable-documentation 29529)
 @end example
 
-@noindent
-Because this symbol is the variable which holds the name of the file
-being visited in the current buffer, the value cell contents we see are
-the name of the source file of this chapter of the Emacs Lisp Manual.
-The property list cell contains the list @code{(variable-documentation
-29529)} which tells the documentation functions where to find the
-documentation string for the variable @code{buffer-file-name} in the
-@file{DOC-@var{version}} file.  (29529 is the offset from the beginning
-of the @file{DOC-@var{version}} file to where that documentation string
-begins---see @ref{Documentation Basics}.)  The function cell contains
-the function for returning the name of the file.
-@code{buffer-file-name} names a primitive function, which has no read
-syntax and prints in hash notation (@pxref{Primitive Function Type}).  A
-symbol naming a function written in Lisp would have a lambda expression
-(or a byte-code object) in this cell.
-
 @node Definitions, Creating Symbols, Symbol Components, Symbols
 @section Defining Symbols
 @cindex definitions of symbols
 
-  A @dfn{definition} in Lisp is a special form that announces your
-intention to use a certain symbol in a particular way.  In Emacs Lisp,
-you can define a symbol as a variable, or define it as a function (or
-macro), or both independently.
-
-  A definition construct typically specifies a value or meaning for the
-symbol for one kind of use, plus documentation for its meaning when used
-in this way.  Thus, when you define a symbol as a variable, you can
-supply an initial value for the variable, plus documentation for the
-variable.
+  A @dfn{definition} is a special kind of Lisp expression that
+announces your intention to use a symbol in a particular way.  It
+typically specifies a value or meaning for the symbol for one kind of
+use, plus documentation for its meaning when used in this way.  Thus,
+when you define a symbol as a variable, you can supply an initial
+value for the variable, plus documentation for the variable.
 
   @code{defvar} and @code{defconst} are special forms that define a
-symbol as a global variable.  They are documented in detail in
-@ref{Defining Variables}.  For defining user option variables that can
-be customized, use @code{defcustom} (@pxref{Customization}).
+symbol as a @dfn{global variable}---a variable that can be accessed at
+any point in a Lisp program.  @xref{Variables}, for details about
+variables.  To define a customizable variable, use the
+@code{defcustom} macro, which also calls @code{defvar} as a subroutine
+(@pxref{Customization}).
+
+  In principle, you can assign a variable value to any symbol with
+@code{setq}, whether not it has first been defined as a variable.
+However, you ought to write a variable definition for each global
+variable that you want to use; otherwise, your Lisp program may not
+act correctly if it is evaluated with lexical scoping enabled
+(@pxref{Variable Scoping}).
 
   @code{defun} defines a symbol as a function, creating a lambda
 expression and storing it in the function cell of the symbol.  This
@@ -171,15 +153,14 @@ both macro and function definitions are kept in the function cell, and
 that cell can hold only one Lisp object at any given time.
 @xref{Macros}.
 
-  In Emacs Lisp, a definition is not required in order to use a symbol
-as a variable or function.  Thus, you can make a symbol a global
-variable with @code{setq}, whether you define it first or not.  The real
-purpose of definitions is to guide programmers and programming tools.
-They inform programmers who read the code that certain symbols are
-@emph{intended} to be used as variables, or as functions.  In addition,
-utilities such as @file{etags} and @file{make-docfile} recognize
-definitions, and add appropriate information to tag tables and the
-@file{DOC-@var{version}} file.  @xref{Accessing Documentation}.
+  As previously noted, Emacs Lisp allows the same symbol to be defined
+both as a variable (e.g.@: with @code{defvar}) and as a function or
+macro (e.g.@: with @code{defun}).  Such definitions do not conflict.
+
+  These definition also act as guides for programming tools.  For
+example, the @kbd{C-h f} and @kbd{C-h v} commands create help buffers
+containing links to the relevant variable, function, or macro
+definitions.  @xref{Name Help,,, emacs, The GNU Emacs Manual}.
 
 @node Creating Symbols, Property Lists, Definitions, Symbols
 @section Creating and Interning Symbols
@@ -254,8 +235,8 @@ not work---only @code{intern} can enter a symbol in an obarray properly.
 
 @cindex CL note---symbol in obarrays
 @quotation
-@b{Common Lisp note:} In Common Lisp, a single symbol may be interned in
-several obarrays.
+@b{Common Lisp note:} Unlike Common Lisp, Emacs Lisp does not provide
+for interning a single symbol in several obarrays.
 @end quotation
 
   Most of the functions below take a name and sometimes an obarray as
@@ -448,12 +429,13 @@ must be distinct.
 
   Property lists are better than association lists for attaching
 information to various Lisp function names or variables.  If your
-program keeps all of its associations in one association list, it will
+program keeps all such information in one association list, it will
 typically need to search that entire list each time it checks for an
-association.  This could be slow.  By contrast, if you keep the same
-information in the property lists of the function names or variables
-themselves, each search will scan only the length of one property list,
-which is usually short.  This is why the documentation for a variable is
+association for a particular Lisp function name or variable, which
+could be slow.  By contrast, if you keep the same information in the
+property lists of the function names or variables themselves, each
+search will scan only the length of one property list, which is
+usually short.  This is why the documentation for a variable is
 recorded in a property named @code{variable-documentation}.  The byte
 compiler likewise uses properties to record those functions needing
 special treatment.