From 34a02f46dce0136ef10deb0f632330c76babbd9c Mon Sep 17 00:00:00 2001
From: Martin Rudalics
Date: Thu, 19 Jan 2012 11:38:31 +0100
Subject: Fix handling of persistent window parameters.

* window.c (save_window_save, Fcurrent_window_configuration)
(Vwindow_persistent_parameters): Do not use Qstate.  Rewrite
doc-strings.
* window.el (window--state-get-1, window-state-get): Do not use
special state value for window-persistent-parameters.  Rename
argument IGNORE to WRITABLE.  Rewrite doc-string.
(window--state-put-2): Reset all window parameters to nil before
assigning values of persistent parameters.
* windows.texi (Window Configurations): Rewrite references to
persistent window parameters.
(Window Parameters): Fix description of persistent window
parameters.
---
 doc/lispref/ChangeLog    |  7 ++++++
 doc/lispref/windows.texi | 57 ++++++++++++++++++++----------------------------
 2 files changed, 31 insertions(+), 33 deletions(-)

(limited to 'doc/lispref')

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 4b9531c0e6c..44467d5f51b 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,10 @@
+2012-01-19  Martin Rudalics  <rudalics@gmx.at>
+
+	* windows.texi (Window Configurations): Rewrite references to
+	persistent window parameters.
+	(Window Parameters): Fix description of persistent window
+	parameters.
+
 2012-01-16  Juanma Barranquero  <lekktu@gmail.com>
 
 	* windows.texi (Window Parameters): Use @pxref.
diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index 1bff30e45e1..a0f8b61ddfe 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -3104,9 +3104,9 @@ window configuration; see @ref{Frame Configurations}.
 @defun current-window-configuration &optional frame
 This function returns a new object representing @var{frame}'s current
 window configuration.  The default for @var{frame} is the selected
-frame.  This function saves copies of window parameters listed by the
-variable @code{window-persistent-parameters}, see @ref{Window
-Parameters} for details.
+frame.  The variable @code{window-persistent-parameters} specifies
+whether and which window parameters are saved by this function, see
+@ref{Window Parameters} for details.
 @end defun
 
 @defun set-window-configuration configuration
@@ -3214,27 +3214,25 @@ to clone the state of a frame into an arbitrary live window
 (@code{set-window-configuration} effectively clones the windows of a
 frame into the root window of that very frame only).
 
-@defun window-state-get &optional window ignore
+@defun window-state-get &optional window writable
 This function returns the state of @var{window} as a Lisp object.  The
 argument @var{window} can be any window and defaults to the root window
 of the selected frame.
 
-If the optional argument @var{ignore} is non-@code{nil}, this means to
+If the optional argument @var{writable} is non-@code{nil}, this means to
 not use markers for sampling positions like @code{window-point} or
 @code{window-start}.  This argument should be non-@code{nil} when the
-state shall be written on disk and read back in another session.
+state shall be written to disk and read back in another session.
 
-The variable @code{window-persistent-parameters} specifies whether and
-which window parameters are saved by this function, see @ref{Window
-Parameters} for details.
+Together, the argument @var{writable} and the variable
+@code{window-persistent-parameters} specify which window parameters are
+saved by this function, see @ref{Window Parameters} for details.
 @end defun
 
-The value returned by @code{window-state-get} can be converted, using
-one of the functions defined by Desktop Save Mode (@pxref{Desktop Save
-Mode}), to an object that can be written to a file.  Such objects can be
-read back and converted to a Lisp object representing the state of the
-window.  That Lisp object can be used as argument for the following
-function in order to restore the state window in another window.
+The value returned by @code{window-state-get} can be used in the same
+session to make a clone of a window in another window.  It can be also
+written to disk and read back in another session.  In either case, use
+the function described next to restore the state of the window.
 
 @defun window-state-put state &optional window ignore
 This function puts the window state @var{state} into @var{window}.  The
@@ -3281,10 +3279,10 @@ states of windows (@pxref{Window Configurations}) do not care about
 window parameters.  This means, that when you change the value of a
 parameter within the body of a @code{save-window-excursion}, the
 previous value is not restored upon exit of that macro.  It also means
-that when you clone via @code{window-state-put} a window state saved
-earlier by @code{window-state-get}, the cloned windows come up with no
-parameters at all.  The following variable allows to override the
-standard behavior.
+that when you restore via @code{window-state-put} a window state saved
+earlier by @code{window-state-get}, all cloned windows have their
+parameters reset to @code{nil}.  The following variable allows to
+override the standard behavior.
 
 @defvar window-persistent-parameters
 This variable is an alist specifying which parameters get saved by
@@ -3293,32 +3291,25 @@ subsequently restored by @code{set-window-configuration} and
 @code{window-state-put}, see @ref{Window Configurations}.
 
 The @sc{car} of each entry of this alist is the symbol specifying the
-parameter.  The @sc{cdr} must be one of the following:
+parameter.  The @sc{cdr} should be one of the following:
 
 @table @asis
-@item @code{state}
-This value means the parameter is saved by @code{window-state-get}
-provided its @var{ignore} argument is @code{nil}.  The function
-@code{current-window-configuration} does not save this parameter.
-
 @item @code{nil}
+This value means the parameter is neither saved by
+@code{window-state-get} nor by @code{current-window-configuration}.
+
+@item @code{t}
 This value specifies that the parameter is saved by
-@code{current-window-configuration} and, provided its @var{ignore}
+@code{current-window-configuration} and, provided its @var{writable}
 argument is @code{nil}, by @code{window-state-get}.
 
-@item @code{t}
+@item @code{writable}
 This means that the parameter is saved unconditionally by both
 @code{current-window-configuration} and @code{window-state-get}.  This
 value should not be used for parameters whose values do not have a read
 syntax.  Otherwise, invoking @code{window-state-put} in another session
 may fail with an @code{invalid-read-syntax} error.
 @end table
-
-Parameters that have been saved are restored to their previous values by
-@code{set-window-configuration} respectively are installed by
-@code{window-state-put}.  Parameters that have not been saved are left
-alone by @code{set-window-configuration} respectively are not installed
-by @code{window-state-put}.
 @end defvar
 
 Some functions, notably @code{delete-window},
-- 
cgit v1.2.1


From 61086eb66b6a222124f302c197e14021711d29d3 Mon Sep 17 00:00:00 2001
From: Glenn Morris
Date: Fri, 20 Jan 2012 19:15:07 -0800
Subject: Document inhibit-local-variables-regexps in the lispref.

* doc/lispref/modes.texi (Auto Major Mode):
* doc/lispref/variables.texi (File Local Variables):
Mention inhibit-local-variables-regexps.

* etc/NEWS: Markup.
---
 doc/lispref/ChangeLog      |  6 ++++++
 doc/lispref/modes.texi     | 12 ++++++++++++
 doc/lispref/variables.texi |  7 +++++++
 3 files changed, 25 insertions(+)

(limited to 'doc/lispref')

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 44467d5f51b..872c4f564ac 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,9 @@
+2012-01-21  Glenn Morris  <rgm@gnu.org>
+
+	* modes.texi (Auto Major Mode):
+	* variables.texi (File Local Variables):
+	Mention inhibit-local-variables-regexps.
+
 2012-01-19  Martin Rudalics  <rudalics@gmx.at>
 
 	* windows.texi (Window Configurations): Rewrite references to
diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index 5d09b79748e..b3aac231d5b 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -588,6 +588,18 @@ Chosen, emacs, The GNU Emacs Manual}.  If @code{enable-local-variables}
 is @code{nil}, @code{set-auto-mode} does not check the @w{@samp{-*-}}
 line, or near the end of the file, for any mode tag.
 
+@vindex inhibit-local-variables-regexps
+There are some file types where it is not appropriate to scan the file
+contents for a mode specifier.  For example, a tar archive may happen to
+contain, near the end of the file, a member file that has a local
+variables section specifying a mode for that particular file.  This
+should not be applied to the containing tar file.  Similarly, a tiff
+image file might just happen to contain a first line that seems to
+match the @w{@samp{-*-}} pattern.  For these reasons, both these file
+extensions are members of the list @var{inhibit-local-variables-regexps}.
+Add patterns to this list to prevent Emacs searching them for local
+variables of any kind (not just mode specifiers).
+
 If @var{keep-mode-if-same} is non-@code{nil}, this function does not
 call the mode command if the buffer is already in the proper major
 mode.  For instance, @code{set-visited-file-name} sets this to
diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi
index b0a6795021b..a8f75f5a160 100644
--- a/doc/lispref/variables.texi
+++ b/doc/lispref/variables.texi
@@ -1660,6 +1660,13 @@ Query (once) about all the variables.
 @end table
 @end defopt
 
+@defvar inhibit-local-variables-regexps
+This is a list of regular expressions.  If a file has a name
+matching an element of this list, then it is not scanned for
+any form of file-local variable.  For examples of why you might want
+to use this, @pxref{Auto Major Mode}.
+@end defvar
+
 @defun hack-local-variables &optional mode-only
 This function parses, and binds or evaluates as appropriate, any local
 variables specified by the contents of the current buffer.  The variable
-- 
cgit v1.2.1


From fead402dddeefba612ab1222b392d5bd0c636400 Mon Sep 17 00:00:00 2001
From: Chong Yidong
Date: Sun, 22 Jan 2012 00:04:55 +0800
Subject: Emacs Lisp manual updates.

* doc/lispref/intro.texi (A Sample Function Description): Special notation
used for macros too.

* doc/lispref/objects.texi (Ctl-Char Syntax, Other Char Bits): Copyedits.
(Symbol Type): Add xref for keyword symbols.
(Sequence Type): Clarify differences between sequence types.
(Cons Cell Type): Add "linked list" index entry.
(Non-ASCII in Strings): Copyedits.
(Equality Predicates): Symbols with same name need not be eq.

* doc/lispref/numbers.texi (Float Basics): Document isnan, copysign, frexp and
ldexp.  Move float-e and float-pi to Math Functions node.
---
 doc/lispref/ChangeLog    |  15 ++++
 doc/lispref/intro.texi   |  23 +++---
 doc/lispref/numbers.texi | 124 ++++++++++++++--------------
 doc/lispref/objects.texi | 207 ++++++++++++++++++++++++-----------------------
 4 files changed, 199 insertions(+), 170 deletions(-)

(limited to 'doc/lispref')

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 872c4f564ac..3c18de96d72 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,18 @@
+2012-01-21  Chong Yidong  <cyd@gnu.org>
+
+	* intro.texi (A Sample Function Description): Special notation
+	used for macros too.
+
+	* objects.texi (Ctl-Char Syntax, Other Char Bits): Copyedits.
+	(Symbol Type): Add xref for keyword symbols.
+	(Sequence Type): Clarify differences between sequence types.
+	(Cons Cell Type): Add "linked list" index entry.
+	(Non-ASCII in Strings): Copyedits.
+	(Equality Predicates): Symbols with same name need not be eq.
+
+	* numbers.texi (Float Basics): Document isnan, copysign, frexp and
+	ldexp.  Move float-e and float-pi to Math Functions node.
+
 2012-01-21  Glenn Morris  <rgm@gnu.org>
 
 	* modes.texi (Auto Major Mode):
diff --git a/doc/lispref/intro.texi b/doc/lispref/intro.texi
index 64c856d3ed4..a68bcfa0fe7 100644
--- a/doc/lispref/intro.texi
+++ b/doc/lispref/intro.texi
@@ -162,7 +162,7 @@ being described, are formatted like this: @var{first-number}.
 
 @cindex @code{nil}
 @cindex false
-  In Lisp, the symbol @code{nil} has three separate meanings: it
+  In Emacs Lisp, the symbol @code{nil} has three separate meanings: it
 is a symbol with the name @samp{nil}; it is the logical truth value
 @var{false}; and it is the empty list---the list of zero elements.
 When used as a variable, @code{nil} always has the value @code{nil}.
@@ -396,13 +396,14 @@ Form', respectively.  Commands are simply functions that may be called
 interactively; macros process their arguments differently from functions
 (the arguments are not evaluated), but are presented the same way.
 
-  Special form descriptions use a more complex notation to specify
-optional and repeated arguments because they can break the argument
-list down into separate arguments in more complicated ways.
-@samp{@r{[}@var{optional-arg}@r{]}} means that @var{optional-arg} is
-optional and @samp{@var{repeated-args}@dots{}} stands for zero or more
-arguments.  Parentheses are used when several arguments are grouped into
-additional levels of list structure.  Here is an example:
+  The descriptions of macros and special forms use a more complex
+notation to specify optional and repeated arguments, because they can
+break the argument list down into separate arguments in more
+complicated ways.  @samp{@r{[}@var{optional-arg}@r{]}} means that
+@var{optional-arg} is optional and @samp{@var{repeated-args}@dots{}}
+stands for zero or more arguments.  Parentheses are used when several
+arguments are grouped into additional levels of list structure.  Here
+is an example:
 
 @defspec count-loop (@var{var} [@var{from} @var{to} [@var{inc}]]) @var{body}@dots{}
 This imaginary special form implements a loop that executes the
@@ -485,9 +486,9 @@ giving a prefix argument makes @var{here} non-@code{nil}.
 @end deffn
 
 @defvar emacs-build-time
-The value of this variable indicates the time at which Emacs was built
-at the local site.  It is a list of three integers, like the value
-of @code{current-time} (@pxref{Time of Day}).
+The value of this variable indicates the time at which Emacs was
+built.  It is a list of three integers, like the value of
+@code{current-time} (@pxref{Time of Day}).
 
 @example
 @group
diff --git a/doc/lispref/numbers.texi b/doc/lispref/numbers.texi
index 6768ecece9c..77db0f86c26 100644
--- a/doc/lispref/numbers.texi
+++ b/doc/lispref/numbers.texi
@@ -168,34 +168,37 @@ character codepoint.
 @node Float Basics
 @section Floating Point Basics
 
+@cindex @acronym{IEEE} floating point
   Floating point numbers are useful for representing numbers that are
 not integral.  The precise range of floating point numbers is
 machine-specific; it is the same as the range of the C data type
-@code{double} on the machine you are using.
+@code{double} on the machine you are using.  Emacs uses the
+@acronym{IEEE} floating point standard where possible (the standard is
+supported by most modern computers).
 
-  The read-syntax for floating point numbers requires either a decimal
+  The read syntax for floating point numbers requires either a decimal
 point (with at least one digit following), an exponent, or both.  For
 example, @samp{1500.0}, @samp{15e2}, @samp{15.0e2}, @samp{1.5e3}, and
 @samp{.15e4} are five ways of writing a floating point number whose
-value is 1500.  They are all equivalent.  You can also use a minus sign
-to write negative floating point numbers, as in @samp{-1.0}.
+value is 1500.  They are all equivalent.  You can also use a minus
+sign to write negative floating point numbers, as in @samp{-1.0}.
+
+  Emacs Lisp treats @code{-0.0} as equal to ordinary zero (with
+respect to @code{equal} and @code{=}), even though the two are
+distinguishable in the @acronym{IEEE} floating point standard.
 
-@cindex @acronym{IEEE} floating point
 @cindex positive infinity
 @cindex negative infinity
 @cindex infinity
 @cindex NaN
-  Most modern computers support the @acronym{IEEE} floating point standard,
-which provides for positive infinity and negative infinity as floating point
-values.  It also provides for a class of values called NaN or
-``not-a-number''; numerical functions return such values in cases where
-there is no correct answer.  For example, @code{(/ 0.0 0.0)} returns a
-NaN.  For practical purposes, there's no significant difference between
-different NaN values in Emacs Lisp, and there's no rule for precisely
-which NaN value should be used in a particular case, so Emacs Lisp
-doesn't try to distinguish them (but it does report the sign, if you
-print it).  Here are the read syntaxes for these special floating
-point values:
+  The @acronym{IEEE} floating point standard supports positive
+infinity and negative infinity as floating point values.  It also
+provides for a class of values called NaN or ``not-a-number'';
+numerical functions return such values in cases where there is no
+correct answer.  For example, @code{(/ 0.0 0.0)} returns a NaN.  (NaN
+values can also carry a sign, but for practical purposes there's no
+significant difference between different NaN values in Emacs Lisp.)
+Here are the read syntaxes for these special floating point values:
 
 @table @asis
 @item positive infinity
@@ -206,16 +209,37 @@ point values:
 @samp{0.0e+NaN} or @samp{-0.0e+NaN}.
 @end table
 
-  To test whether a floating point value is a NaN, compare it with
-itself using @code{=}.  That returns @code{nil} for a NaN, and
-@code{t} for any other floating point value.
+@defun isnan number
+This predicate tests whether its argument is NaN, and returns @code{t}
+if so, @code{nil} otherwise.  The argument must be a number.
+@end defun
+
+  The following functions are specialized for handling floating point
+numbers:
+
+@defun frexp x
+This function returns a cons cell @code{(@var{sig} . @var{exp})},
+where @var{sig} and @var{exp} are respectively the significand and
+exponent of the floating point number @var{x}:
+
+@smallexample
+@var{x} = @var{sig} * 2^@var{exp}
+@end smallexample
+
+@var{sig} is a floating point number between 0.5 (inclusive) and 1.0
+(exclusive).  If @var{x} is zero, the return value is @code{(0 . 0)}.
+@end defun
 
-  The value @code{-0.0} is distinguishable from ordinary zero in
-@acronym{IEEE} floating point, but Emacs Lisp @code{equal} and
-@code{=} consider them equal values.
+@defun ldexp sig &optional exp
+This function returns a floating point number corresponding to the
+significand @var{sig} and exponent @var{exp}.
+@end defun
 
-  You can use @code{logb} to extract the binary exponent of a floating
-point number (or estimate the logarithm of an integer):
+@defun copysign x1 x2
+This function copies the sign of @var{x2} to the value of @var{x1},
+and returns the result.  @var{x1} and @var{x2} must be floating point
+numbers.
+@end defun
 
 @defun logb number
 This function returns the binary exponent of @var{number}.  More
@@ -230,14 +254,6 @@ down to an integer.
 @end example
 @end defun
 
-@defvar float-e
-The mathematical constant @math{e} (2.71828@dots{}).
-@end defvar
-
-@defvar float-pi
-The mathematical constant @math{pi} (3.14159@dots{}).
-@end defvar
-
 @node Predicates on Numbers
 @section Type Predicates for Numbers
 @cindex predicates for numbers
@@ -1122,35 +1138,15 @@ angle in radians between the vector @code{[@var{x}, @var{y}]} and the
 @end defun
 
 @defun exp arg
-This is the exponential function; it returns
-@tex
-@math{e}
-@end tex
-@ifnottex
-@i{e}
-@end ifnottex
-to the power @var{arg}.
-@tex
-@math{e}
-@end tex
-@ifnottex
-@i{e}
-@end ifnottex
-is a fundamental mathematical constant also called the base of natural
-logarithms.
+This is the exponential function; it returns @math{e} to the power
+@var{arg}.
 @end defun
 
 @defun log arg &optional base
-This function returns the logarithm of @var{arg}, with base @var{base}.
-If you don't specify @var{base}, the base
-@tex
-@math{e}
-@end tex
-@ifnottex
-@i{e}
-@end ifnottex
-is used.  If @var{arg} is negative, it signals a @code{domain-error}
-error.
+This function returns the logarithm of @var{arg}, with base
+@var{base}.  If you don't specify @var{base}, the natural base
+@math{e} is used.  If @var{arg} is negative, it signals a
+@code{domain-error} error.
 @end defun
 
 @ignore
@@ -1185,6 +1181,17 @@ This returns the square root of @var{arg}.  If @var{arg} is negative,
 it signals a @code{domain-error} error.
 @end defun
 
+In addition, Emacs defines the following common mathematical
+constants:
+
+@defvar float-e
+The mathematical constant @math{e} (2.71828@dots{}).
+@end defvar
+
+@defvar float-pi
+The mathematical constant @math{pi} (3.14159@dots{}).
+@end defvar
+
 @node Random Numbers
 @section Random Numbers
 @cindex random numbers
@@ -1218,7 +1225,6 @@ nonnegative and less than @var{limit}.
 
 If @var{limit} is @code{t}, it means to choose a new seed based on the
 current time of day and on Emacs's process @acronym{ID} number.
-@c "Emacs'" is incorrect usage!
 
 On some machines, any integer representable in Lisp may be the result
 of @code{random}.  On other machines, the result can never be larger
diff --git a/doc/lispref/objects.texi b/doc/lispref/objects.texi
index 3fb676edcd4..87bcc20daba 100644
--- a/doc/lispref/objects.texi
+++ b/doc/lispref/objects.texi
@@ -427,10 +427,10 @@ codes for these non-@acronym{ASCII} control characters include the
 @ifnottex
 2**26
 @end ifnottex
-bit as well as the code for the corresponding non-control
-character.  Ordinary terminals have no way of generating non-@acronym{ASCII}
-control characters, but you can generate them straightforwardly using X
-and other window systems.
+bit as well as the code for the corresponding non-control character.
+Ordinary text terminals have no way of generating non-@acronym{ASCII}
+control characters, but you can generate them straightforwardly using
+X and other window systems.
 
   For historical reasons, Emacs treats the @key{DEL} character as
 the control equivalent of @kbd{?}:
@@ -501,10 +501,10 @@ character is upper case or lower case.  Emacs uses the
 @end ifnottex
 bit to indicate that the shift key was used in typing a control
 character.  This distinction is possible only when you use X terminals
-or other special terminals; ordinary terminals do not report the
-distinction to the computer in any way.  The Lisp syntax for
-the shift bit is @samp{\S-}; thus, @samp{?\C-\S-o} or @samp{?\C-\S-O}
-represents the shifted-control-o character.
+or other special terminals; ordinary text terminals do not report the
+distinction.  The Lisp syntax for the shift bit is @samp{\S-}; thus,
+@samp{?\C-\S-o} or @samp{?\C-\S-O} represents the shifted-control-o
+character.
 
 @cindex hyper characters
 @cindex super characters
@@ -541,9 +541,9 @@ intended.  But you can use one symbol in all of these ways,
 independently.
 
   A symbol whose name starts with a colon (@samp{:}) is called a
-@dfn{keyword symbol}.  These symbols automatically act as constants, and
-are normally used only by comparing an unknown symbol with a few
-specific alternatives.
+@dfn{keyword symbol}.  These symbols automatically act as constants,
+and are normally used only by comparing an unknown symbol with a few
+specific alternatives.  @xref{Constant Variables}.
 
 @cindex @samp{\} in symbols
 @cindex backslash in symbols
@@ -617,26 +617,28 @@ all symbols; @pxref{Creating Symbols}.)
 @subsection Sequence Types
 
   A @dfn{sequence} is a Lisp object that represents an ordered set of
-elements.  There are two kinds of sequence in Emacs Lisp, lists and
-arrays.  Thus, an object of type list or of type array is also
-considered a sequence.
-
-  Arrays are further subdivided into strings, vectors, char-tables and
-bool-vectors.  Vectors can hold elements of any type, but string
-elements must be characters, and bool-vector elements must be @code{t}
-or @code{nil}.  Char-tables are like vectors except that they are
-indexed by any valid character code.  The characters in a string can
-have text properties like characters in a buffer (@pxref{Text
-Properties}), but vectors do not support text properties, even when
-their elements happen to be characters.
-
-  Lists, strings and the other array types are different, but they have
-important similarities.  For example, all have a length @var{l}, and all
-have elements which can be indexed from zero to @var{l} minus one.
-Several functions, called sequence functions, accept any kind of
-sequence.  For example, the function @code{elt} can be used to extract
-an element of a sequence, given its index.  @xref{Sequences Arrays
-Vectors}.
+elements.  There are two kinds of sequence in Emacs Lisp: @dfn{lists}
+and @dfn{arrays}.
+
+  Lists are the most commonly-used sequences.  A list can hold
+elements of any type, and its length can be easily changed by adding
+or removing elements.  See the next subsection for more about lists.
+
+  Arrays are fixed-length sequences.  They are further subdivided into
+strings, vectors, char-tables and bool-vectors.  Vectors can hold
+elements of any type, whereas string elements must be characters, and
+bool-vector elements must be @code{t} or @code{nil}.  Char-tables are
+like vectors except that they are indexed by any valid character code.
+The characters in a string can have text properties like characters in
+a buffer (@pxref{Text Properties}), but vectors do not support text
+properties, even when their elements happen to be characters.
+
+  Lists, strings and the other array types also share important
+similarities.  For example, all have a length @var{l}, and all have
+elements which can be indexed from zero to @var{l} minus one.  Several
+functions, called sequence functions, accept any kind of sequence.
+For example, the function @code{length} reports the length of any kind
+of sequence.  @xref{Sequences Arrays Vectors}.
 
   It is generally impossible to read the same sequence twice, since
 sequences are always created anew upon reading.  If you read the read
@@ -650,24 +652,27 @@ same object, @code{nil}.
 @cindex decrement field of register
 @cindex pointers
 
-  A @dfn{cons cell} is an object that consists of two slots, called the
-@sc{car} slot and the @sc{cdr} slot.  Each slot can @dfn{hold} or
-@dfn{refer to} any Lisp object.  We also say that ``the @sc{car} of
-this cons cell is'' whatever object its @sc{car} slot currently holds,
-and likewise for the @sc{cdr}.
-
-@quotation
-A note to C programmers: in Lisp, we do not distinguish between
-``holding'' a value and ``pointing to'' the value, because pointers in
-Lisp are implicit.
-@end quotation
+  A @dfn{cons cell} is an object that consists of two slots, called
+the @sc{car} slot and the @sc{cdr} slot.  Each slot can @dfn{hold} any
+Lisp object.  We also say that ``the @sc{car} of this cons cell is''
+whatever object its @sc{car} slot currently holds, and likewise for
+the @sc{cdr}.
 
+@cindex list structure
   A @dfn{list} is a series of cons cells, linked together so that the
 @sc{cdr} slot of each cons cell holds either the next cons cell or the
 empty list.  The empty list is actually the symbol @code{nil}.
-@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.
+@xref{Lists}, for details.  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}.
+
+@cindex linked list
+@quotation
+A note to C programmers: a Lisp list thus works as a @dfn{linked list}
+built up of cons cells.  Because pointers in Lisp are implicit, we do
+not distinguish between a cons cell slot ``holding'' a value versus
+``pointing to'' the value.
+@end quotation
 
 @cindex atoms
   Because cons cells are so central to Lisp, we also have a word for
@@ -1025,40 +1030,40 @@ but the newline is ignored if escaped."
 @node Non-ASCII in Strings
 @subsubsection Non-@acronym{ASCII} Characters in Strings
 
-  You can include a non-@acronym{ASCII} international character in a string
-constant by writing it literally.  There are two text representations
-for non-@acronym{ASCII} characters in Emacs strings (and in buffers): unibyte
-and multibyte.  If the string constant is read from a multibyte source,
-such as a multibyte buffer or string, or a file that would be visited as
-multibyte, then the character is read as a multibyte character, and that
-makes the string multibyte.  If the string constant is read from a
-unibyte source, then the character is read as unibyte and that makes the
-string unibyte.
-
-  You can also represent a multibyte non-@acronym{ASCII} character with its
-character code: use a hex escape, @samp{\x@var{nnnnnnn}}, with as many
-digits as necessary.  (Multibyte non-@acronym{ASCII} character codes are all
-greater than 256.)  Any character which is not a valid hex digit
-terminates this construct.  If the next character in the string could be
-interpreted as a hex digit, write @w{@samp{\ }} (backslash and space) to
-terminate the hex escape---for example, @w{@samp{\xe0\ }} represents
-one character, @samp{a} with grave accent.  @w{@samp{\ }} in a string
-constant is just like backslash-newline; it does not contribute any
-character to the string, but it does terminate the preceding hex escape.
+  You can include a non-@acronym{ASCII} international character in a
+string constant by writing it literally.  There are two text
+representations for non-@acronym{ASCII} characters in Emacs strings
+(and in buffers): unibyte and multibyte (@pxref{Text
+Representations}).  If the string constant is read from a multibyte
+source, such as a multibyte buffer or string, or a file that would be
+visited as multibyte, then Emacs reads the non-@acronym{ASCII}
+character as a multibyte character and automatically makes the string
+a multibyte string.  If the string constant is read from a unibyte
+source, then Emacs reads the non-@acronym{ASCII} character as unibyte,
+and makes the string unibyte.
+
+  Instead of writing a non-@acronym{ASCII} character literally into a
+multibyte string, you can write it as its character code using a hex
+escape, @samp{\x@var{nnnnnnn}}, with as many digits as necessary.
+(Multibyte non-@acronym{ASCII} character codes are all greater than
+256.)  You can also specify a character in a multibyte string using
+the @samp{\u} or @samp{\U} Unicode escape syntax (@pxref{General
+Escape Syntax}).  In either case, any character which is not a valid
+hex digit terminates the construct.  If the next character in the
+string could be interpreted as a hex digit, write @w{@samp{\ }}
+(backslash and space) to terminate the hex escape---for example,
+@w{@samp{\xe0\ }} represents one character, @samp{a} with grave
+accent.  @w{@samp{\ }} in a string constant is just like
+backslash-newline; it does not contribute any character to the string,
+but it does terminate the preceding hex escape.  Using any hex escape
+in a string (even for an @acronym{ASCII} character) automatically
+forces the string to be multibyte.
 
   You can represent a unibyte non-@acronym{ASCII} character with its
 character code, which must be in the range from 128 (0200 octal) to
 255 (0377 octal).  If you write all such character codes in octal and
 the string contains no other characters forcing it to be multibyte,
-this produces a unibyte string.  However, using any hex escape in a
-string (even for an @acronym{ASCII} character) forces the string to be
-multibyte.
-
-  You can also specify characters in a string by their numeric values
-in Unicode, using @samp{\u} and @samp{\U} (@pxref{Character Type}).
-
-  @xref{Text Representations}, for more information about the two
-text representations.
+this produces a unibyte string.
 
 @node Nonprinting Characters
 @subsubsection Nonprinting Characters in Strings
@@ -1922,23 +1927,24 @@ This function returns a symbol naming the primitive type of
 @section Equality Predicates
 @cindex equality
 
-  Here we describe functions that test for equality between any two
-objects.  Other functions test equality of contents between objects of specific
-types, e.g., strings.  For these predicates, see the appropriate chapter
-describing the data type.
+  Here we describe functions that test for equality between two
+objects.  Other functions test equality of contents between objects of
+specific 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
-the same object, @code{nil} otherwise.
-
-@code{eq} returns @code{t} if @var{object1} and @var{object2} are
-integers with the same value.  Also, since symbol names are normally
-unique, if the arguments are symbols with the same name, they are
-@code{eq}.  For other types (e.g., lists, vectors, strings), two
-arguments with the same contents or elements are not necessarily
-@code{eq} to each other: they are @code{eq} only if they are the same
-object, meaning that a change in the contents of one will be reflected
-by the same change in the contents of the other.
+the same object, and @code{nil} otherwise.
+
+If @var{object1} and @var{object2} are integers with the same value,
+they are considered to be the same object (i.e.@: @code{eq} returns
+@code{t}).  If @var{object1} and @var{object2} are symbols with the
+same name, they are normally the same object---but see @ref{Creating
+Symbols} for exceptions.  For other types (e.g.@: lists, vectors,
+strings), two arguments with the same contents or elements are not
+necessarily @code{eq} to each other: they are @code{eq} only if they
+are the same object, meaning that a change in the contents of one will
+be reflected by the same change in the contents of the other.
 
 @example
 @group
@@ -1988,6 +1994,7 @@ by the same change in the contents of the other.
 @end group
 @end example
 
+@noindent
 The @code{make-symbol} function returns an uninterned symbol, distinct
 from the symbol that is used if you write the name in a Lisp expression.
 Distinct symbols with the same name are not @code{eq}.  @xref{Creating
@@ -2003,11 +2010,11 @@ Symbols}.
 
 @defun equal object1 object2
 This function returns @code{t} if @var{object1} and @var{object2} have
-equal components, @code{nil} otherwise.  Whereas @code{eq} tests if its
-arguments are the same object, @code{equal} looks inside nonidentical
-arguments to see if their elements or contents are the same.  So, if two
-objects are @code{eq}, they are @code{equal}, but the converse is not
-always true.
+equal components, and @code{nil} otherwise.  Whereas @code{eq} tests
+if its arguments are the same object, @code{equal} looks inside
+nonidentical arguments to see if their elements or contents are the
+same.  So, if two objects are @code{eq}, they are @code{equal}, but
+the converse is not always true.
 
 @example
 @group
@@ -2059,13 +2066,13 @@ always true.
 @end example
 
 Comparison of strings is case-sensitive, but does not take account of
-text properties---it compares only the characters in the strings.  Use
-@code{equal-including-properties} to also compare text properties.  For
-technical reasons, a unibyte string 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
-127 (@acronym{ASCII}) or 160 through 255 (@code{eight-bit-graphic}).
-(@pxref{Text Representations}).
+text properties---it compares only the characters in the strings.
+@xref{Text Properties}.  Use @code{equal-including-properties} to also
+compare text properties.  For technical reasons, a unibyte string 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 127 (@acronym{ASCII}) or 160 through 255
+(@code{eight-bit-graphic}).  (@pxref{Text Representations}).
 
 @example
 @group
-- 
cgit v1.2.1


From 31cbea1d3d3c548025f70551514bd1a370301ccf Mon Sep 17 00:00:00 2001
From: Chong Yidong
Date: Mon, 23 Jan 2012 12:23:50 +0800
Subject: 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.
---
 doc/lispref/ChangeLog      |  23 ++++++
 doc/lispref/control.texi   |  10 +--
 doc/lispref/elisp.texi     |   2 +-
 doc/lispref/eval.texi      |  24 +++----
 doc/lispref/lists.texi     | 163 ++++++++++-------------------------------
 doc/lispref/sequences.texi | 120 +++++++++++++++++++++++++++----
 doc/lispref/strings.texi   |  13 ++--
 doc/lispref/symbols.texi   | 176 ++++++++++++++++++++-------------------------
 8 files changed, 272 insertions(+), 259 deletions(-)

(limited to 'doc/lispref')

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.
-- 
cgit v1.2.1