*** empty log message ***

45 files changed, 3570 insertions, 2889 deletions

diff --git a/lispref/abbrevs.texi b/lispref/abbrevs.texi
index 175bfb6824f..674082b6289 100644
--- a/lispref/abbrevs.texi
+++ b/lispref/abbrevs.texi
@@ -54,7 +54,7 @@ of abbrevs when their abbreviations are inserted into a buffer.
 If the value is @code{nil}, abbrevs may be defined, but they are not
 expanded automatically.
 
-This variable automatically becomes local when set in any fashion.
+This variable automatically becomes buffer-local when set in any fashion.
 @end defvar
 
 @defvar default-abbrev-mode
@@ -337,10 +337,6 @@ it is the local abbrev table in all buffers in Fundamental mode.
 This is the local abbrev table used in Text mode.
 @end defvar
 
-@defvar c-mode-abbrev-table
-This is the local abbrev table used in C mode.
-@end defvar
-
 @defvar lisp-mode-abbrev-table
 This is the local abbrev table used in Lisp mode and Emacs Lisp mode.
 @end defvar
diff --git a/lispref/anti.texi b/lispref/anti.texi
index dcd8be78987..df81194f29d 100644
--- a/lispref/anti.texi
+++ b/lispref/anti.texi
@@ -144,6 +144,9 @@ This means that if you insert text with text properties into the minibuffer,
 the minibuffer value really will contain text properties.
 
 @item
+Only the simple menu item format is supported (@pxref{Simple Menu Items}).
+
+@item
 You can still bind @code{x-resource-class} around a call to
 @code{x-get-resource}, but it won't do anything special.
 
@@ -225,7 +228,7 @@ special events.  If you want to hold a party in Emacs, please let us
 know.
 
 @item
-You can't do date arithmentic with @code{encode-time} any more.
+You can't do date arithmetic with @code{encode-time} any more.
 
 @item
 The functions @code{command-execute} and @code{call-interactively} no
diff --git a/lispref/backups.texi b/lispref/backups.texi
index 3a8221bab4f..9707ade9eef 100644
--- a/lispref/backups.texi
+++ b/lispref/backups.texi
@@ -294,8 +294,7 @@ The standard definition of this function is as follows:
 @smallexample
 @group
 (defun make-backup-file-name (file)
-  "Create the non-numeric backup file name for FILE.
-@dots{}"
+  "Create the non-numeric backup file name for FILE@enddots{}"
   (concat file "~"))
 @end group
 @end smallexample
@@ -442,8 +441,7 @@ The standard definition of this function is as follows:
 @group
 (defun make-auto-save-file-name ()
   "Return file name to use for auto-saves \
-of current buffer.
-@dots{}"
+of current buffer@enddots{}"
   (if buffer-file-name
 @end group
 @group
@@ -550,7 +548,7 @@ buffer as of the last time it was read in, saved, or auto-saved.  This is
 used to detect a substantial decrease in size, and turn off auto-saving
 in response.
 
-If it is -1, that means auto-saving is temporarily shut off in this
+If it is @minus{}1, that means auto-saving is temporarily shut off in this
 buffer due to a substantial deletion.  Explicitly saving the buffer
 stores a positive value in this variable, thus reenabling auto-saving.
 Turning auto-save mode off or on also alters this variable.
diff --git a/lispref/buffers.texi b/lispref/buffers.texi
index 8597305116b..600ff3e54b5 100644
--- a/lispref/buffers.texi
+++ b/lispref/buffers.texi
@@ -130,11 +130,11 @@ string abridged):
 @end example
 
 @noindent
-This function binds a local variable to the current buffer, and then
-@code{save-current-buffer} records which buffer that was.  Next,
-@code{set-buffer} makes another buffer current.  Finally,
+This function binds a local variable to record the current buffer, and
+then @code{save-current-buffer} arranges to make it current again.
+Next, @code{set-buffer} makes the specified buffer current.  Finally,
 @code{insert-buffer-substring} copies the string from the original
-current buffer to the new current buffer.
+current buffer to the specified (and now current) buffer.
 
   If the buffer appended to happens to be displayed in some window, 
 the next redisplay will show how its text has changed.  Otherwise, you
@@ -204,10 +204,10 @@ existing buffer.
 @tindex save-current-buffer
 @defmac save-current-buffer body...
 The @code{save-current-buffer} macro saves the identity of the current
-buffer, evaluates the @var{body} forms, and finally restores the buffer.
-The return value is the value of the last form in @var{body}.  The
-current buffer is restored even in case of an abnormal exit via
-@code{throw} or error (@pxref{Nonlocal Exits}).
+buffer, evaluates the @var{body} forms, and finally restores that buffer
+as current.  The return value is the value of the last form in
+@var{body}.  The current buffer is restored even in case of an abnormal
+exit via @code{throw} or error (@pxref{Nonlocal Exits}).
 
 If the buffer that used to be current has been killed by the time of
 exit from @code{save-current-buffer}, then it is not made current again,
@@ -383,10 +383,10 @@ buffer-file-name
 @end example
 
 It is risky to change this variable's value without doing various other
-things.  See the definition of @code{set-visited-file-name} in
-@file{files.el}; some of the things done there, such as changing the
-buffer name, are not strictly necessary, but others are essential to
-avoid confusing Emacs.
+things.  Normally it is better to use @code{set-visited-file-name} (see
+below); some of the things done there, such as changing the buffer name,
+are not strictly necessary, but others are essential to avoid confusing
+Emacs.
 @end defvar
 
 @defvar buffer-file-truename
@@ -399,7 +399,7 @@ local, unaffected by @code{kill-local-variables}.  @xref{Truenames}.
 This buffer-local variable holds the file number and directory device
 number of the file visited in the current buffer, or @code{nil} if no
 file or a nonexistent file is visited.  It is a permanent local,
-unaffected by @code{kill-local-variables}.  @xref{Truenames}.
+unaffected by @code{kill-local-variables}.
 
 The value is normally a list of the form @code{(@var{filenum}
 @var{devnum})}.  This pair of numbers uniquely identifies the file among
@@ -443,9 +443,6 @@ the buffer as having no visited file.
 @c Wordy to avoid overfull hbox.  --rjc 16mar92
 When the function @code{set-visited-file-name} is called interactively, it
 prompts for @var{filename} in the minibuffer.
-
-See also @code{clear-visited-file-modtime} and
-@code{verify-visited-file-modtime} in @ref{Buffer Modification}.
 @end deffn
 
 @defvar list-buffers-directory
@@ -669,19 +666,23 @@ buried (see @code{bury-buffer}, below).  Several functions, notably
 @code{other-buffer}, use this ordering.  A buffer list displayed for the
 user also follows this order.
 
-@defun buffer-list &optional frame
-This function returns a list of all buffers, including those whose names
-begin with a space.  The elements are actual buffers, not their names.
+  In addition to the fundamental Emacs buffer list, each frame has its
+own version of the buffer list, in which the buffers that have been
+selected in that frame come first, starting with the buffers most
+recently selected @emph{in that frame}.  (This order is recorded in
+@var{frame}'s @code{buffer-list} frame parameter; see @ref{Window Frame
+Parameters}.)  The buffers that were never selected in @var{frame} come
+afterward, ordered according to the fundamental Emacs buffer list.
 
-If @var{frame} is @code{nil}, all the buffers appear in order of most
-recent selection, regardless of which frames they were selected in.
+@defun buffer-list &optional frame
+This function returns the buffer list, including all buffers, even those
+whose names begin with a space.  The elements are actual buffers, not
+their names.
 
-If @var{frame} is a frame, then the buffers that have been selected in
-@var{frame} all come at the front of the list, ordered by most recent
-selection in @var{frame}.  (This order is recorded in @var{frame}'s
-@code{buffer-list} frame parameter; see @ref{X Frame Parameters}.)  The
-buffers that were never selected in @var{frame} come afterward, ordered
-according to most recent selection in other frames.
+If @var{frame} is a frame, this returns @var{frame}'s buffer list.  If
+@var{frame} is @code{nil}, the fundamental Emacs buffer list is used:
+all the buffers appear in order of most recent selection, regardless of
+which frames they were selected in.
 
 @example
 @group
@@ -735,7 +736,7 @@ buffer list that is not now visible in any window in a visible frame.
 If the selected frame has a non-@code{nil} @code{buffer-predicate}
 parameter, then @code{other-buffer} uses that predicate to decide which
 buffers to consider.  It calls the predicate once for each buffer, and
-if the value is @code{nil}, that buffer is ignored.  @xref{X Frame
+if the value is @code{nil}, that buffer is ignored.  @xref{Window Frame
 Parameters}.
 
 @c Emacs 19 feature
@@ -946,7 +947,7 @@ themselves.
 completely separate.  They have different names, different values of
 point, different narrowing, different markers and overlays (though
 inserting or deleting text in either buffer relocates the markers and
-overlays for both), different major modes, and different local
+overlays for both), different major modes, and different buffer-local
 variables.
 
   An indirect buffer cannot visit a file, but its base buffer can.  If
diff --git a/lispref/calendar.texi b/lispref/calendar.texi
index bae0543b5e7..ff1fec3cffc 100644
--- a/lispref/calendar.texi
+++ b/lispref/calendar.texi
@@ -2,7 +2,7 @@
 @c This is part of the GNU Emacs Lisp Reference Manual.
 @c Copyright (C) 1990, 1991, 1992, 1993, 1995, 1998 Free Software Foundation, Inc. 
 @c See the file elisp.texi for copying conditions.
-@node Calendar, Tips, Display, Top
+@node Calendar, System Interface, Display, Top
 @chapter Customizing the Calendar and Diary
 
   There are many customizations that you can use to make the calendar and
diff --git a/lispref/commands.texi b/lispref/commands.texi
index 90d8cecbe4e..29e43d4dfc7 100644
--- a/lispref/commands.texi
+++ b/lispref/commands.texi
@@ -385,7 +385,7 @@ one.  No I/O.
 @item s
 Arbitrary text, read in the minibuffer and returned as a string
 (@pxref{Text from Minibuffer}).  Terminate the input with either
-@key{LFD} or @key{RET}.  (@kbd{C-q} may be used to include either of
+@kbd{C-j} or @key{RET}.  (@kbd{C-q} may be used to include either of
 these characters in the input.)  Prompt.
 
 @item S
@@ -401,7 +401,7 @@ Completion, Prompt.
 
 @item x
 A Lisp object, specified with its read syntax, terminated with a
-@key{LFD} or @key{RET}.  The object is not evaluated.  @xref{Object from
+@kbd{C-j} or @key{RET}.  The object is not evaluated.  @xref{Object from
 Minibuffer}.  Prompt.
 
 @item X
@@ -482,7 +482,7 @@ expressions, autoload objects that are declared as interactive
 (non-@code{nil} fourth argument to @code{autoload}), and some of the
 primitive functions.
 
-A symbol is @code{commandp} if its function definition is
+A symbol satisfies @code{commandp} if its function definition satisfies
 @code{commandp}.
 
 Keys and keymaps are not commands.  Rather, they are used to look up
@@ -507,7 +507,7 @@ Otherwise, the command is added only if it uses the minibuffer to read
 an argument.  @xref{Command History}.
 
 The argument @var{keys}, if given, specifies the sequence of events to
-use if the command inquires which events were used to invoke it.
+supply if the command inquires which events were used to invoke it.
 @end defun
 
 @defun command-execute command &optional record-flag keys
@@ -527,7 +527,7 @@ definition is handled by loading the specified library and then
 rechecking the definition of the symbol.
 
 The argument @var{keys}, if given, specifies the sequence of events to
-use if the command inquires which events were used to invoke it.
+supply if the command inquires which events were used to invoke it.
 @end defun
 
 @deffn Command execute-extended-command prefix-argument
@@ -571,21 +571,22 @@ no difference whether @code{call-interactively} was called from Lisp or
 directly from the editor command loop.)  If the containing function was
 called by Lisp evaluation (or with @code{apply} or @code{funcall}), then
 it was not called interactively.
+@end defun
 
-The most common use of @code{interactive-p} is for deciding whether to
+  The most common use of @code{interactive-p} is for deciding whether to
 print an informative message.  As a special exception,
 @code{interactive-p} returns @code{nil} whenever a keyboard macro is
 being run.  This is to suppress the informative messages and speed
 execution of the macro.
 
-For example:
+  For example:
 
 @example
 @group
 (defun foo ()
   (interactive)
-  (and (interactive-p)
-       (message "foo")))
+  (when (interactive-p)
+    (message "foo")))
      @result{} foo
 @end group
 
@@ -611,7 +612,20 @@ foobar
      @result{} (nil t)
 @end group
 @end example
-@end defun
+
+  The other way to do this sort of job is to make the command take an
+argument @code{print-message} which should be non-@code{nil} in an
+interactive call, and use the @code{interactive} spec to make sure it is
+non-@code{nil}.  Here's how:
+
+@example
+(defun foo (&optional print-message)
+  (interactive "p")
+  (when print-message
+    (message "foo")))
+@end example
+
+  The numeric prefix argument, provided by @samp{p}, is never @code{nil}.
 
 @node Command Loop Info
 @comment  node-name,  next,  previous,  up
@@ -687,12 +701,19 @@ if all those events were characters.  @xref{Input Events}.
 @end example
 @end defun
 
+@defun this-command-keys-vector
+Like @code{this-command-keys}, except that it always returns
+the events in a vector, so you do never need to deal with the complexities
+of storing input events in a string (@pxref{Strings of Events}).
+@end defun
+
 @defvar last-nonmenu-event
-This variable holds the last input event read as part of a key
-sequence, not counting events resulting from mouse menus.
+This variable holds the last input event read as part of a key sequence,
+not counting events resulting from mouse menus.
 
 One use of this variable is for telling @code{x-popup-menu} where to pop
-up a menu.
+up a menu.  It is also used internally by @code{y-or-n-p}
+(@pxref{Yes-or-No Queries}).
 @end defvar
 
 @defvar last-command-event
@@ -765,10 +786,9 @@ A symbol
 
 There are two kinds of input you can get from the keyboard: ordinary
 keys, and function keys.  Ordinary keys correspond to characters; the
-events they generate are represented in Lisp as characters.  In Emacs
-versions 18 and earlier, characters were the only events.  The event
-type of a character event is the character itself (an integer); 
-see @ref{Classifying Events}.
+events they generate are represented in Lisp as characters.  The event
+type of a character event is the character itself (an integer); see
+@ref{Classifying Events}.
 
 @cindex modifier bits (of input character)
 @cindex basic code (of input character)
@@ -778,9 +798,9 @@ An input character event consists of a @dfn{basic code} between 0 and
 @table @asis
 @item meta
 The
-@iftex
+@tex
 $2^{27}$
-@end iftex
+@end tex
 @ifinfo
 2**27
 @end ifinfo
@@ -789,9 +809,9 @@ typed with the meta key held down.
 
 @item control
 The
-@iftex
+@tex
 $2^{26}$
-@end iftex
+@end tex
 @ifinfo
 2**26
 @end ifinfo
@@ -805,9 +825,9 @@ Thus, the code for @kbd{C-a} is just 1.
 But if you type a control combination not in @sc{ASCII}, such as
 @kbd{%} with the control key, the numeric value you get is the code
 for @kbd{%} plus
-@iftex
+@tex
 $2^{26}$
-@end iftex
+@end tex
 @ifinfo
 2**26
 @end ifinfo
@@ -816,9 +836,9 @@ control characters).
 
 @item shift
 The
-@iftex
+@tex
 $2^{25}$
-@end iftex
+@end tex
 @ifinfo
 2**25
 @end ifinfo
@@ -829,9 +849,9 @@ For letters, the basic code itself indicates upper versus lower case;
 for digits and punctuation, the shift key selects an entirely different
 character with a different basic code.  In order to keep within the
 @sc{ASCII} character set whenever possible, Emacs avoids using the
-@iftex
+@tex
 $2^{25}$
-@end iftex
+@end tex
 @ifinfo
 2**25
 @end ifinfo
@@ -839,9 +859,9 @@ bit for those characters.
 
 However, @sc{ASCII} provides no way to distinguish @kbd{C-A} from
 @kbd{C-a}, so Emacs uses the
-@iftex
+@tex
 $2^{25}$
-@end iftex
+@end tex
 @ifinfo
 2**25
 @end ifinfo
@@ -850,9 +870,9 @@ bit in @kbd{C-A} and not in
 
 @item hyper
 The
-@iftex
+@tex
 $2^{24}$
-@end iftex
+@end tex
 @ifinfo
 2**24
 @end ifinfo
@@ -861,9 +881,9 @@ typed with the hyper key held down.
 
 @item super
 The
-@iftex
+@tex
 $2^{23}$
-@end iftex
+@end tex
 @ifinfo
 2**23
 @end ifinfo
@@ -872,9 +892,9 @@ typed with the super key held down.
 
 @item alt
 The
-@iftex
+@tex
 $2^{22}$
-@end iftex
+@end tex
 @ifinfo
 2**22
 @end ifinfo
@@ -1119,12 +1139,13 @@ events (@pxref{Click Events}), except that the @var{event-type} symbol
 name contains the prefix @samp{down-}.  The @samp{down-} prefix follows
 modifier key prefixes such as @samp{C-} and @samp{M-}.
 
-The function @code{read-key-sequence}, and therefore the Emacs command
-loop as well, ignore any button-down events that don't have command
-bindings.  This means that you need not worry about defining button-down
-events unless you want them to do something.  The usual reason to define
-a button-down event is so that you can track mouse motion (by reading
-motion events) until the button is released.  @xref{Motion Events}.
+The function @code{read-key-sequence} ignores any button-down events
+that don't have command bindings; therefore, the Emacs command loop
+ignores them too.  This means that you need not worry about defining
+button-down events unless you want them to do something.  The usual
+reason to define a button-down event is so that you can track mouse
+motion (by reading motion events) until the button is released.
+@xref{Motion Events}.
 
 @node Repeat Events
 @subsection Repeat Events
@@ -1220,8 +1241,7 @@ of the mouse without any button activity.  Mouse motion events are
 represented by lists that look like this:
 
 @example
-(mouse-movement
- (@var{window} @var{buffer-pos} (@var{x} . @var{y}) @var{timestamp}))
+(mouse-movement (@var{window} @var{buffer-pos} (@var{x} . @var{y}) @var{timestamp}))
 @end example
 
 The second element of the list describes the current position of the
@@ -1230,17 +1250,7 @@ mouse, just as in a click event (@pxref{Click Events}).
 The special form @code{track-mouse} enables generation of motion events
 within its body.  Outside of @code{track-mouse} forms, Emacs does not
 generate events for mere motion of the mouse, and these events do not
-appear.
-
-@defspec track-mouse body@dots{}
-This special form executes @var{body}, with generation of mouse motion
-events enabled.  Typically @var{body} would use @code{read-event}
-to read the motion events and modify the display accordingly.
-
-When the user releases the button, that generates a click event.
-Typically, @var{body} should return when it sees the click event, and
-discard that event.
-@end defspec
+appear.  @xref{Mouse Tracking}.
 
 @node Focus Events
 @subsection Focus Events
@@ -1454,7 +1464,7 @@ to an event type which specifies all of them.  For example,
 a mouse button or motion event.
 
   These two functions return the starting or ending position of a
-mouse-button event.  The position is a list of this form:
+mouse-button event, as a list of this form:
 
 @example
 (@var{window} @var{buffer-position} (@var{x} . @var{y}) @var{timestamp})
@@ -1477,8 +1487,8 @@ event, the value is actually the starting position, which is the only
 position such events have.
 @end defun
 
-  These five functions take a position as described above, and return
-various parts of it.
+  These five functions take a position list as described above, and
+return various parts of it.
 
 @defun posn-window position
 Return the window that @var{position} is in.
@@ -1503,6 +1513,8 @@ a cons cell @code{(@var{col} . @var{row})}.  These are computed from the
 Return the timestamp in @var{position}.
 @end defun
 
+  These functions are useful for decoding scroll bar events.
+
 @defun scroll-bar-event-ratio event
 This function returns the fractional vertical position of a scroll bar
 event within the scroll bar.  The value is a cons cell
@@ -1537,28 +1549,59 @@ of a pair of x and y coordinates.
 string as containing text characters---the same kind of characters found
 in buffers or files.  Occasionally Lisp programs use strings that
 conceptually contain keyboard characters; for example, they may be key
-sequences or keyboard macro definitions.  There are special rules for
-how to put keyboard characters into a string, because they are not
-limited to the range of 0 to 255 as text characters are.
+sequences or keyboard macro definitions.  However, storing keyboard
+characters in a string is a complex matter, for reasons of historical
+compatibility, and it is not always possible.
+
+  We recommend that new programs avoid dealing with these complexities
+by not storing keyboard events in strings.  Here is how to do that:
+
+@itemize @bullet
+@item
+Use vectors instead of strings for key sequences, when you plan to use
+them for anything other than as arguments @code{lookup-key} and
+@code{define-key}.  For example, you can use
+@code{read-key-sequence-vector} instead of @code{read-key-sequence}, and
+@code{this-command-keys-vector} instead of @code{this-command-keys}.
+
+@item
+Use vectors to write key sequence constants containing meta characters,
+even when passing them directly to @code{define-key}.
+
+@item
+When you have to look at the contents of a key sequence that might be a
+string, use @code{listify-key-sequence} (@pxref{Event Input Misc})
+first, to convert it to a list.
+@end itemize
 
-  A keyboard character typed using the @key{META} key is called a
-@dfn{meta character}.  The numeric code for such an event includes the
-@iftex
+  The complexities stem from the modifier bits that keyboard input
+characters can include.  Aside from the Meta modifier, none of these
+modifier bits can be included in a string, and the Meta modifier is
+allowed only in special cases.
+
+  The earliest GNU Emacs versions represented meta characters as codes
+in the range of 128 to 255.  At that time, the basic character codes
+ranged from 0 to 127, so all keyboard character codes did fit in a
+string.  Many Lisp programs used @samp{\M-} in string constants to stand
+for meta characters, especially in arguments to @code{define-key} and
+similar functions, and key sequences and sequences of events were always
+represented as strings.
+
+  When we added support for larger basic character codes beyond 127, and
+additional modifier bits, we had to change the representation of meta
+characters.  Now the flag that represents the Meta modifier in a
+character is
+@tex
 $2^{27}$
-@end iftex
+@end tex
 @ifinfo
 2**27
 @end ifinfo
-bit; it does not even come close to fitting in a string.  However,
-earlier Emacs versions used a different representation for these
-characters, which gave them codes in the range of 128 to 255.  That did
-fit in a string, and many Lisp programs contain string constants that
-use @samp{\M-} to express meta characters, especially as the argument to
-@code{define-key} and similar functions.
+and such numbers cannot be included in a string.
 
-  We provide backward compatibility to run those programs using special
-rules for how to put a keyboard character event in a string.  Here are
-the rules:
+  To support programs with @samp{\M-} in string constants, there are
+special rules for including certain meta characters in a string.
+Here are the rules for interpreting keyboard
 
 @itemize @bullet
 @item
@@ -1567,36 +1610,39 @@ in the string unchanged.
 
 @item
 The meta variants of those characters, with codes in the range of
-@iftex
+@tex
 $2^{27}$
-@end iftex
+@end tex
 @ifinfo
 2**27
 @end ifinfo
 to
-@iftex
+@tex
 $2^{27} + 127$,
-@end iftex
+@end tex
 @ifinfo
 2**27+127,
 @end ifinfo
 can also go in the string, but you must change their
 numeric values.  You must set the
-@iftex
+@tex
 $2^{7}$
-@end iftex
+@end tex
 @ifinfo
 2**7
 @end ifinfo
 bit instead of the
-@iftex
+@tex
 $2^{27}$
-@end iftex
+@end tex
 @ifinfo
 2**27
 @end ifinfo
-bit,
-resulting in a value between 128 and 255.
+bit, resulting in a value between 128 and 255.  Only a unibyte string
+can include these codes.
+
+@item
+Non-@sc{ASCII} characters above 256 can be included in a multibyte string.
 
 @item
 Other keyboard character events cannot fit in a string.  This includes
@@ -1613,31 +1659,18 @@ modify the corresponding keyboard event to put it in the string.  Thus,
 meta events in strings work consistently regardless of how they get into
 the strings.
 
-  The reason we changed the representation of meta characters as
-keyboard events is to make room for basic character codes beyond 127,
-and support meta variants of such larger character codes.
-
-  New programs can avoid dealing with these special compatibility rules
-by using vectors instead of strings for key sequences when there is any
-possibility that they might contain meta characters, and by using
-@code{listify-key-sequence} to access a string of events.
-
-@defun listify-key-sequence key
-This function converts the string or vector @var{key} to a list of
-events, which you can put in @code{unread-command-events}.  Converting a
-vector is simple, but converting a string is tricky because of the
-special representation used for meta characters in a string.
-@end defun
+  However, most programs would do well to avoid these issues by
+following the recommendations at the beginning of this section.
 
 @node Reading Input
 @section Reading Input
 
-  The editor command loop reads keyboard input using the function
+  The editor command loop reads key sequences using the function
 @code{read-key-sequence}, which uses @code{read-event}.  These and other
-functions for keyboard input are also available for use in Lisp
-programs.  See also @code{momentary-string-display} in @ref{Temporary
-Displays}, and @code{sit-for} in @ref{Waiting}.  @xref{Terminal Input},
-for functions and variables for controlling terminal input modes and
+functions for event input are also available for use in Lisp programs.
+See also @code{momentary-string-display} in @ref{Temporary Displays},
+and @code{sit-for} in @ref{Waiting}.  @xref{Terminal Input}, for
+functions and variables for controlling terminal input modes and
 debugging terminal input.  @xref{Translating Input}, for features you
 can use for translating or modifying input events while reading them.
 
@@ -1671,10 +1704,6 @@ Otherwise, it returns a vector, since a vector can hold all kinds of
 events---characters, symbols, and lists.  The elements of the string or
 vector are the events in the key sequence.
 
-The function @code{read-key-sequence} suppresses quitting: @kbd{C-g}
-typed while reading with this function works like any other character,
-and does not set @code{quit-flag}.  @xref{Quitting}.
-
 The argument @var{prompt} is either a string to be displayed in the echo
 area as a prompt, or @code{nil}, meaning not to display a prompt.
 
@@ -1692,6 +1721,16 @@ and the user types @kbd{C-x C-f}.
      @result{} "^X^F"
 @end group
 @end example
+
+The function @code{read-key-sequence} suppresses quitting: @kbd{C-g}
+typed while reading with this function works like any other character,
+and does not set @code{quit-flag}.  @xref{Quitting}.
+@end defun
+
+@defun read-key-sequence-vector prompt
+This is like @code{read-key-sequence} except that it always
+returns the key sequence as a vector, never as a string.
+@xref{Strings of Events}.
 @end defun
 
 @cindex upper case key sequence
@@ -1819,9 +1858,9 @@ The command @code{quoted-insert} uses this function.
 @cindex control characters, reading
 @cindex nonprinting characters, reading
 This function is like @code{read-char}, except that if the first
-character read is an octal digit (0-7), it reads up to two more octal digits
-(but stopping if a non-octal digit is found) and returns the
-character represented by those digits in octal.
+character read is an octal digit (0-7), it reads any number of octal
+digits (but stopping if a non-octal digit is found), and returns the
+character represented by that numeric character code.
 
 Quitting is suppressed when the first character is read, so that the
 user can enter a @kbd{C-g}.  @xref{Quitting}.
@@ -1882,6 +1921,11 @@ Normally you add events to the front of this list, so that the events
 most recently unread will be reread first.
 @end defvar
 
+@defun listify-key-sequence key
+This function converts the string or vector @var{key} to a list of
+individual events, which you can put in @code{unread-command-events}.
+@end defun
+
 @defvar unread-command-char
 This variable holds a character to be read as command input.
 A value of -1 means ``empty''.
@@ -1900,6 +1944,7 @@ may return @code{t} when no input is available.
 @end defun
 
 @defvar last-input-event
+@defvarx last-input-char
 This variable records the last terminal input event read, whether
 as part of a command or explicitly by a Lisp program.
 
@@ -1919,7 +1964,6 @@ this expression) remains the value of @code{last-command-event}.
 @end group
 @end example
 
-@vindex last-input-char
 The alias @code{last-input-char} exists for compatibility with
 Emacs version 18.
 @end defvar
@@ -2049,9 +2093,9 @@ innermost active command loop.
 does not cause a quit; it acts as an ordinary input character.  In the
 simplest case, you cannot tell the difference, because @kbd{C-g}
 normally runs the command @code{keyboard-quit}, whose effect is to quit.
-However, when @kbd{C-g} follows a prefix key, the result is an undefined
-key.  The effect is to cancel the prefix key as well as any prefix
-argument.
+However, when @kbd{C-g} follows a prefix key, they combine to form an
+undefined key.  The effect is to cancel the prefix key as well as any
+prefix argument.
 
   In the minibuffer, @kbd{C-g} has a different definition: it aborts out
 of the minibuffer.  This means, in effect, that it exits the minibuffer
@@ -2104,15 +2148,15 @@ normal quitting is permitted after the first character of input.
 @example
 (defun read-quoted-char (&optional prompt)
   "@dots{}@var{documentation}@dots{}"
-  (let ((count 0) (code 0) char)
-    (while (< count 3)
-      (let ((inhibit-quit (zerop count))
-            (help-form nil))
-        (and prompt (message "%s-" prompt))
-        (setq char (read-char))
-        (if inhibit-quit (setq quit-flag nil)))
-      @dots{})
-    (logand 255 code)))
+  (let ((message-log-max nil) done (first t) (code 0) char)
+    (while (not done)
+      (let ((inhibit-quit first)
+            @dots{})
+        (and prompt (message "%s-" prompt))
+        (setq char (read-event))
+        (if inhibit-quit (setq quit-flag nil)))
+      @r{@dots{}set the variable @code{code}@dots{}})
+    code))
 @end example
 
 @defvar quit-flag
diff --git a/lispref/compile.texi b/lispref/compile.texi
index 0ccdd568b1c..007a4a6b094 100644
--- a/lispref/compile.texi
+++ b/lispref/compile.texi
@@ -3,12 +3,12 @@
 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. 
 @c See the file elisp.texi for copying conditions.
 @setfilename ../info/compile
-@node Byte Compilation, Debugging, Loading, Top
+@node Byte Compilation, Advising, Loading, Top
 @chapter Byte Compilation
 @cindex byte-code
 @cindex compilation
 
-  GNU Emacs Lisp has a @dfn{compiler} that translates functions written
+  Emacs Lisp has a @dfn{compiler} that translates functions written
 in Lisp into a special representation called @dfn{byte-code} that can be
 executed more efficiently.  The compiler replaces Lisp function
 definitions with byte-code.  When a byte-code function is called, its
@@ -21,15 +21,17 @@ transportable from machine to machine without recompilation.  It is not,
 however, as fast as true compiled code.
 
   In general, any version of Emacs can run byte-compiled code produced
-by recent earlier versions of Emacs, but the reverse is not true.  In
-particular, if you compile a program with Emacs 19.29, the compiled
-code does not run in earlier versions.
+by recent earlier versions of Emacs, but the reverse is not true.  A
+major incompatible change was introduced in Emacs version 19.29, and
+files compiled with versions since that one will definitely not run
+in earlier versions unless you specify a special option.
 @iftex
 @xref{Docs and Compilation}.
 @end iftex
-Files compiled in versions before 19.29 may not work in 19.29 if they
-contain character constants with modifier bits, because the bits were
-renumbered in Emacs 19.29.
+In addition, the modifier bits in keyboard characters were renumbered in
+Emacs 19.29; as a result, files compiled in versions before 19.29 will
+not work in subsequent versions if they contain character constants with
+modifier bits.
 
   @xref{Compilation Errors}, for how to investigate errors occurring in
 byte compilation.
@@ -99,9 +101,10 @@ in a buffer called @samp{*Compile-Log*}.  These report things in your
 program that suggest a problem but are not necessarily erroneous.
 
 @cindex macro compilation
-  Be careful when byte-compiling code that uses macros.  Macro calls are
-expanded when they are compiled, so the macros must already be defined
-for proper compilation.  For more details, see @ref{Compiling Macros}.
+  Be careful when writing macro calls in files that you may someday
+byte-compile.  Macro calls are expanded when they are compiled, so the
+macros must already be defined for proper compilation.  For more
+details, see @ref{Compiling Macros}.
 
   Normally, compiling a file does not evaluate the file's contents or
 load the file.  But it does execute any @code{require} calls at top
@@ -200,10 +203,9 @@ This function recompiles every @samp{.el} file in @var{directory} that
 needs recompilation.  A file needs recompilation if a @samp{.elc} file
 exists but is older than the @samp{.el} file.
 
-When a @samp{.el} file has no corresponding @samp{.elc} file, then
-@var{flag} says what to do.  If it is @code{nil}, these files are
-ignored.  If it is non-@code{nil}, the user is asked whether to compile
-each such file.
+When a @samp{.el} file has no corresponding @samp{.elc} file, @var{flag}
+says what to do.  If it is @code{nil}, these files are ignored.  If it
+is non-@code{nil}, the user is asked whether to compile each such file.
 
 The returned value of this command is unpredictable.
 @end deffn
@@ -225,12 +227,13 @@ status code.
 @cindex byte-code interpreter
 This function actually interprets byte-code.  A byte-compiled function
 is actually defined with a body that calls @code{byte-code}.  Don't call
-this function yourself.  Only the byte compiler knows how to generate
+this function yourself---only the byte compiler knows how to generate
 valid calls to this function.
 
-In newer Emacs versions (19 and up), byte-code is usually executed as
-part of a byte-code function object, and only rarely due to an explicit
-call to @code{byte-code}.
+In Emacs version 18, byte-code was always executed by way of a call to
+the function @code{byte-code}.  Nowadays, byte-code is usually executed
+as part of a byte-code function object, and only rarely through an
+explicit call to @code{byte-code}.
 @end defun
 
 @node Docs and Compilation
@@ -269,13 +272,14 @@ directory where you built it, you will experience this problem
 occasionally if you edit and recompile Lisp files.  When it happens, you
 can cure the problem by reloading the file after recompiling it.
 
-  Byte-compiled files made with Emacs 19.29 will not load into older
-versions because the older versions don't support this feature.  You can
-turn off this feature by setting @code{byte-compile-dynamic-docstrings}
-to @code{nil}.  Once this is done, you can compile files that will load
-into older Emacs versions.  You can do this globally, or for one source
-file by specifying a file-local binding for the variable.  Here's one
-way to do that:
+  Byte-compiled files made with recent versions of Emacs (since 19.29)
+will not load into older versions because the older versions don't
+support this feature.  You can turn off this feature at compile time by
+setting @code{byte-compile-dynamic-docstrings} to @code{nil}; then you
+can compile files that will load into older Emacs versions.  You can do
+this globally, or for one source file by specifying a file-local binding
+for the variable.  One way to do that is by adding this string to the
+file's first line:
 
 @example
 -*-byte-compile-dynamic-docstrings: nil;-*-
@@ -292,7 +296,9 @@ that are set up for dynamic loading of documentation strings.
 use a special Lisp reader construct, @samp{#@@@var{count}}.  This
 construct skips the next @var{count} characters.  It also uses the
 @samp{#$} construct, which stands for ``the name of this file, as a
-string.''  It is best not to use these constructs in Lisp source files.
+string.''  It is usually best not to use these constructs in Lisp source
+files, since they are not designed to be clear to humans reading the
+file.
 
 @node Dynamic Loading
 @section Dynamic Loading of Individual Functions
@@ -309,10 +315,10 @@ replace the place-holder.
 
   The advantage of dynamic function loading is that loading the file
 becomes much faster.  This is a good thing for a file which contains
-many separate commands, provided that using one of them does not imply
-you will soon (or ever) use the rest.  A specialized mode which provides
-many keyboard commands often has that usage pattern: a user may invoke
-the mode, but use only a few of the commands it provides.
+many separate user-callable functions, if using one of them does not
+imply you will probably also use the rest.  A specialized mode which
+provides many keyboard commands often has that usage pattern: a user may
+invoke the mode, but use only a few of the commands it provides.
 
   The dynamic loading feature has certain disadvantages:
 
@@ -323,19 +329,21 @@ longer load the remaining function definitions not already loaded.
 
 @item
 If you alter the compiled file (such as by compiling a new version),
-then trying to load any function not already loaded will get nonsense
+then trying to load any function not already loaded will yield nonsense
 results.
 @end itemize
 
-  If you compile a new version of the file, the best thing to do is
-immediately load the new compiled file.  That will prevent any future
-problems.
+  These problems will never happen in normal circumstances with
+installed Emacs files.  But they are quite likely to happen with Lisp
+files that you are changing.  The easiest way to prevent these problems
+is to reload the new compiled file immediately after each recompilation.
 
   The byte compiler uses the dynamic function loading feature if the
 variable @code{byte-compile-dynamic} is non-@code{nil} at compilation
 time.  Do not set this variable globally, since dynamic loading is
 desirable only for certain files.  Instead, enable the feature for
-specific source files with file-local variable bindings, like this:
+specific source files with file-local variable bindings.  For example,
+you could do it by writing this text in the source file's first line:
 
 @example
 -*-byte-compile-dynamic: t;-*-
@@ -363,9 +371,8 @@ This form marks @var{body} to be evaluated both when you compile the
 containing code and when you run it (whether compiled or not).
 
 You can get a similar result by putting @var{body} in a separate file
-and referring to that file with @code{require}.  Using @code{require} is
-preferable if there is a substantial amount of code to be executed in
-this way.
+and referring to that file with @code{require}.  That method is
+preferable when @var{body} is large.
 @end defspec
 
 @defspec eval-when-compile body
@@ -375,10 +382,10 @@ compiler becomes a constant which appears in the compiled program.  If
 you load the source file, rather than compiling it, @var{body} is
 evaluated normally.
 
-At top level, this is analogous to the Common Lisp idiom
-@code{(eval-when (compile eval) @dots{})}.  Elsewhere, the Common Lisp
-@samp{#.} reader macro (but not when interpreting) is closer to what
-@code{eval-when-compile} does.
+@strong{Common Lisp Note:} At top level, this is analogous to the Common
+Lisp idiom @code{(eval-when (compile eval) @dots{})}.  Elsewhere, the
+Common Lisp @samp{#.} reader macro (but not when interpreting) is closer
+to what @code{eval-when-compile} does.
 @end defspec
 
 @node Byte-Code Objects
@@ -395,12 +402,8 @@ as a function to be called.  The printed representation for a byte-code
 function object is like that for a vector, with an additional @samp{#}
 before the opening @samp{[}.
 
-  In Emacs version 18, there was no byte-code function object data type;
-compiled functions used the function @code{byte-code} to run the byte
-code.
-
   A byte-code function object must have at least four elements; there is
-no maximum number, but only the first six elements are actually used.
+no maximum number, but only the first six elements have any normal use.
 They are:
 
 @table @var
diff --git a/lispref/control.texi b/lispref/control.texi
index 19d82fe7c08..1fbb668da0f 100644
--- a/lispref/control.texi
+++ b/lispref/control.texi
@@ -460,8 +460,8 @@ first argument of @code{while}, as shown here:
 
 @noindent
 This moves forward one line and continues moving by lines until it
-reaches an empty.  It is unusual in that the @code{while} has no body,
-just the end test (which also does the real work of moving point).
+reaches an empty line.  It is peculiar in that the @code{while} has no
+body, just the end test (which also does the real work of moving point).
 @end defspec
 
 @node Nonlocal Exits
@@ -718,15 +718,13 @@ These examples show typical uses of @code{error}:
 
 @example
 @group
-(error "You have committed an error.  
-        Try something else.")
-     @error{} You have committed an error.  
-        Try something else.
+(error "That is an error -- try something else")
+     @error{} That is an error -- try something else
 @end group
 
 @group
-(error "You have committed %d errors." 10)
-     @error{} You have committed 10 errors.  
+(error "You have committed %d errors" 10)
+     @error{} You have committed 10 errors
 @end group
 @end example
 
@@ -752,7 +750,7 @@ errors.
 
 The number and significance of the objects in @var{data} depends on
 @var{error-symbol}.  For example, with a @code{wrong-type-arg} error,
-there are two objects in the list: a predicate that describes the type
+there should be two objects in the list: a predicate that describes the type
 that was expected, and the object that failed to fit that type.
 @xref{Error Symbols}, for a description of error symbols.
 
@@ -772,8 +770,8 @@ it could sometimes return).
 @end group
 
 @group
-(signal 'no-such-error '("My unknown error condition."))
-     @error{} peculiar error: "My unknown error condition."
+(signal 'no-such-error '("My unknown error condition"))
+     @error{} peculiar error: "My unknown error condition"
 @end group
 @end smallexample
 @end defun
@@ -876,8 +874,8 @@ execution at the point of the error, nor can it examine variable
 bindings that were made within the protected form.  All it can do is
 clean up and proceed.
 
-  @code{condition-case} is often used to trap errors that are
-predictable, such as failure to open a file in a call to
+  The @code{condition-case} construct is often used to trap errors that
+are predictable, such as failure to open a file in a call to
 @code{insert-file-contents}.  It is also used to trap errors that are
 totally unpredictable, such as when the program evaluates an expression
 read from the user.
@@ -1159,7 +1157,12 @@ You might think that we could just as well write @code{(kill-buffer
 However, the way shown above is safer, if @var{body} happens to get an
 error after switching to a different buffer!  (Alternatively, you could
 write another @code{save-excursion} around the body, to ensure that the
-temporary buffer becomes current in time to kill it.)
+temporary buffer becomes current again in time to kill it.)
+
+  Emacs includes a standard macro called @code{with-temp-buffer} which
+expands into more or less the code shown above (@pxref{Current Buffer}).
+Several of the macros defined in this manual use @code{unwind-protect}
+in this way.
 
 @findex ftp-login
   Here is an actual example taken from the file @file{ftp.el}.  It
@@ -1188,18 +1191,3 @@ quit, and the quit happens immediately after the function
 @code{ftp-setup-buffer} returns but before the variable @code{process} is
 set, the process will not be killed.  There is no easy way to fix this bug,
 but at least it is very unlikely.
-
-  Here is another example which uses @code{unwind-protect} to make sure
-to kill a temporary buffer.  In this example, the value returned by
-@code{unwind-protect} is used.
-
-@smallexample
-(defun shell-command-string (cmd)
-  "Return the output of the shell command CMD, as a string."
-  (save-excursion
-    (set-buffer (generate-new-buffer " OS*cmd"))
-    (shell-command cmd t)
-    (unwind-protect
-        (buffer-string)
-      (kill-buffer (current-buffer)))))
-@end smallexample
diff --git a/lispref/customize.texi b/lispref/customize.texi
index 738734fe7c4..2b61848d643 100644
--- a/lispref/customize.texi
+++ b/lispref/customize.texi
@@ -6,30 +6,29 @@
 @node Customization, Loading, Macros, Top
 @chapter Writing Customization Definitions
 
-This chapter describes how to declare customization groups, variables,
-and faces.  We use the term @dfn{customization item} to include all
-three of those.  This has few examples, but please look at the file
-@file{cus-edit.el}, which contains many declarations you can learn from.
+  This chapter describes how to declare user options for customization,
+and also customization groups for classifying them.  We use the term
+@dfn{customization item} to include both kinds of customization
+definitions---as well as face definitions (@pxref{Defining Faces}).
 
 @menu
 * Common Keywords::
 * Group Definitions::            
 * Variable Definitions::         
-* Face Definitions::             
 * Customization Types::
 @end menu
 
 @node Common Keywords
 @section Common Keywords for All Kinds of Items
 
-All three kinds of customization declarations (for groups, variables,
-and faces) accept keyword arguments for specifying various information.
-This section describes some keywords that apply to all three.
+  All kinds of customization declarations (for variables and groups, and
+for faces) accept keyword arguments for specifying various information.
+This section describes some keywords that apply to all kinds.
 
-All of these keywords, except @code{:tag}, can be used more than once in
-a given item.  Each use of the keyword has an independent effect.  The
-keyword @code{:tag} is an exception because any given item can only
-display one name item.
+  All of these keywords, except @code{:tag}, can be used more than once
+in a given item.  Each use of the keyword has an independent effect.
+The keyword @code{:tag} is an exception because any given item can only
+display one name.
 
 @table @code
 @item :group @var{group}
@@ -49,6 +48,10 @@ other documentation.
 There are three alternatives you can use for @var{link-data}:
 
 @table @code
+@item :tag @var{name}
+Use @var{name}, a string, instead of the item's name, to label the item
+in customization menus and buffers.
+
 @item (custom-manual @var{info-node})
 Link to an Info node; @var{info-node} is a string which specifies the
 node name, as in @code{"(emacs)Top"}.  The link appears as
@@ -59,8 +62,8 @@ Like @code{custom-manual} except that the link appears
 in the customization buffer with the Info node name.
 
 @item (url-link @var{url})
-Link to a web page; @var{url} is a string which specifies the URL.  The
-link appears in the customization buffer as @var{url}.
+Link to a web page; @var{url} is a string which specifies the @sc{url}.
+The link appears in the customization buffer as @var{url}.
 @end table
 
 You can specify the text to use in the customization buffer by adding
@@ -84,30 +87,27 @@ feature.  This is done by calling @code{require}.
 The most common reason to use @code{:require} is when a variable enables
 a feature such as a minor mode, and just setting the variable won't have
 any effect unless the code which implements the mode is loaded.
-
-@item :tag @var{name}
-Use @var{name}, a string, instead of the item's name, to label the item
-in customization menus and buffers.
 @end table
 
 @node Group Definitions
 @section Defining Custom Groups
 
-Each Emacs Lisp package should have one main customization group which
+  Each Emacs Lisp package should have one main customization group which
 contains all the options, faces and other groups in the package.  If the
 package has a small number of options and faces, use just one group and
 put everything in it.  When there are more than twelve or so options and
 faces, then you should structure them into subgroups, and put the
-subgroups under the package's main customization group.  It is ok to
-have some of the options and faces in the package's main group alongside
+subgroups under the package's main customization group.  It is OK to
+put some of the options and faces in the package's main group alongside
 the subgroups.
 
-The package's main or only group should be a member of one or more of
-the standard customization groups.  Type press @kbd{C-h p} to display a
-list of finder keywords; them choose some of them add your group to each
-of them, using the @code{:group} keyword.
+  The package's main or only group should be a member of one or more of
+the standard customization groups.  (To display the full list of them,
+use @kbd{M-x customize}.)  Choose one or more of them (but not too
+many), and add your group to each of them using the @code{:group}
+keyword.
 
-The way to declare new customization groups is with @code{defgroup}.
+  The way to declare new customization groups is with @code{defgroup}.
 
 @tindex defgroup
 @defmac defgroup group members doc [keyword value]...
@@ -116,9 +116,9 @@ Do not quote the symbol @var{group}.  The argument @var{doc} specifies
 the documentation string for the group.
 
 The arguments @var{members} can be an alist whose elements specify
-members of the group; however, normally @var{members} is @code{nil}, and
-you specify the group's members by using the @code{:group} keyword when
-defining those members.
+customization items to be members of the group; however, normally
+@var{members} is @code{nil}, and you specify the group's members by
+using the @code{:group} keyword when defining those members.
 
 @ignore
 @code{(@var{name} @var{widget})}.  Here @var{name} is a symbol, and
@@ -139,40 +139,40 @@ One group can have any number of prefixes.
 @end table
 @end defmac
 
-The @code{:prefix} feature is currently turned off, which means that
-@code{:prefix} currently has no effect.  We did this because we found
-that discarding the specified prefixes often led to confusing names for
-options.  This happened because the people who wrote the @code{defgroup}
-definitions for various groups added @code{:prefix} keywords whenever
-they make logical sense---that is, whenever they say that there was a
-common prefix for the option names in a library.
-
-In order to obtain good results with @code{:prefix}, it is necessary to
-check the specific effects of discarding a particular prefix, given the
-specific items in a group and their names and documentation.  If the
-resulting text is not clear, then @code{:prefix} should not be used in
-that case.
-
-It should be possible to recheck all the customization groups, delete
+  The prefix-discarding feature is currently turned off, which means
+that @code{:prefix} currently has no effect.  We did this because we
+found that discarding the specified prefixes often led to confusing
+names for options.  This happened because the people who wrote the
+@code{defgroup} definitions for various groups added @code{:prefix}
+keywords whenever they make logical sense---that is, whenever the
+variables in the library have a common prefix.
+
+  In order to obtain good results with @code{:prefix}, it would be
+necessary to check the specific effects of discarding a particular
+prefix, given the specific items in a group and their names and
+documentation.  If the resulting text is not clear, then @code{:prefix}
+should not be used in that case.
+
+  It should be possible to recheck all the customization groups, delete
 the @code{:prefix} specifications which give unclear results, and then
 turn this feature back on, if someone would like to do the work.
 
 @node Variable Definitions
 @section Defining Customization Variables
 
-  Use @code{defcustom} to declare user editable variables.
+  Use @code{defcustom} to declare user-editable variables.
 
 @tindex defcustom
-@defmac defcustom option value doc [keyword value]...
-Declare @var{option} as a customizable user option variable that
-defaults to @var{value}.  Do not quote @var{option}.  @var{value} should
-be an expression to compute the value; it will be be evaluated on more
+@defmac defcustom option default doc [keyword value]...
+Declare @var{option} as a customizable user option variable.  Do not
+quote @var{option}.  The argument @var{doc} specifies the documentation
+string for the variable.
+
+If @var{option} is void, @code{defcustom} initializes it to
+@var{default}.  @var{default} should be an expression to compute the
+value; be careful in writing it, because it can be be evaluated on more
 than one occasion.
 
-If @var{option} is void, @code{defcustom} initializes it to @var{value}.
-
-The argument @var{doc} specifies the documentation string for the variable.
-
 The following additional keywords are defined:
 
 @table @code
@@ -185,11 +185,10 @@ values are legitimate, and how to display the value.
 Specify @var{list} as the list of reasonable values for use in this
 option.
 
-Currently this is meaningful only when type is @code{hook}.  The
-elements of @var{list} are functions that you might likely want to use
-as elements of the hook value.  The user is not actually restricted to
-using only these functions, but they are offered as convenient
-alternatives.
+Currently this is meaningful only when the type is @code{hook}.  In that
+case, the elements of @var{list} should be functions that are useful as
+elements of the hook value.  The user is not restricted to using only
+these functions, but they are offered as convenient alternatives.
 
 @item :version @var{version}
 This option specifies that the variable's default value was changed in
@@ -226,35 +225,47 @@ this way:
 
 @table @code
 @item custom-initialize-set
-Use the variable's @code{:set} function to initialize the variable.  Do
-not reinitialize it if it is already non-void.  This is the default
+Use the variable's @code{:set} function to initialize the variable, but
+do not reinitialize it if it is already non-void.  This is the default
 @code{:initialize} function.
 
 @item custom-initialize-default
-Always use @code{set-default} to initialize the variable, even if some
-other @code{:set} function has been specified.
+Like @code{custom-initialize-set}, but use the function
+@code{set-default} to set the variable, instead of the variable's
+@code{:set} function.  This is the usual choice for a variable whose
+@code{:set} function enables or disables a minor mode; with this choice,
+defining the variable will not call the minor mode function, but
+customizing the variable will do so.
 
 @item custom-initialize-reset
-Even if the variable is already non-void, reset it by calling the
-@code{:set} function using the current value (returned by the
-@code{:get} method).
+Always use the @code{:set} function to initialize the variable.  If the
+variable is already non-void, reset it by calling the @code{:set}
+function using the current value (returned by the @code{:get} method).
 
 @item custom-initialize-changed
-Like @code{custom-initialize-reset}, except use @code{set-default}
-(rather than the @code{:set} function) to initialize the variable if it
-is not bound and has not been set already.
+Use the @code{:set} function to initialize the variable, if it is
+already set or has been customized; otherwise, just use
+@code{set-default}.
 @end table
+@end table
+@end defmac
 
-@item :require @var{feature}
-If the user saves a customized value for this item, them Emacs should do
-@code{(require @var{feature})} after installing the saved value.
-
-The place to use this feature is for an option that turns on the
+  The @code{:require} option is useful for an option that turns on the
 operation of a certain feature.  Assuming that the package is coded to
 check the value of the option, you still need to arrange for the package
-to be loaded.  That is what @code{:require} is for.
-@end table
-@end defmac
+to be loaded.  You can do that with @code{:require}.  @xref{Common
+Keywords}.  Here is an example, from the library @file{paren.el}:
+
+@example
+(defcustom show-paren-mode nil
+  "Toggle Show Paren mode@enddots{}"
+  :set (lambda (symbol value)
+         (show-paren-mode (or value 0)))
+  :initialize 'custom-initialize-default
+  :type 'boolean
+  :group 'paren-showing
+  :require 'paren)
+@end example
 
 @ignore
 Use @code{custom-add-option} to specify that a specific function is
@@ -274,103 +285,37 @@ and @code{saved-value} to record the value saved by the user with the
 customization buffer.  The @code{saved-value} property is actually a
 list whose car is an expression which evaluates to the value.
 
-@node Face Definitions
-@section Defining Faces
-
-Faces are declared with @code{defface}.
-
-@tindex defface
-@defmac defface face spec doc [keyword value]... 
-Declare @var{face} as a customizable face that defaults according to
-@var{spec}.  Do not quote the symbol @var{face}.
-
-@var{doc} is the face documentation.
-
-@var{spec} should be an alist whose elements have the form
-@code{(@var{display} @var{atts})} (see below).  When @code{defface}
-executes, it defines the face according to @var{spec}, then uses any
-customizations saved in the @file{.emacs} file to override that
-specification.
-
-In each element of @var{spec}, @var{atts} is a list of face attributes
-and their values.  The possible attributes are defined in the variable
-@code{custom-face-attributes}.
-
-The @var{display} part of an element of @var{spec} determines which
-frames the element applies to.  If more than one element of @var{spec}
-matches a given frame, the first matching element is the only one used
-for that frame.
-
-If @var{display} is @code{t} in a @var{spec} element, that element
-matches all frames.  (This means that any subsequent elements of
-@var{spec} are never used.)
-
-Alternatively, @var{display} can be an alist whose elements have the
-form @code{(@var{characteristic} @var{value}@dots{})}.  Here
-@var{characteristic} specifies a way of classifying frames, and the
-@var{value}s are possible classifications which @var{display} should
-apply to.  Here are the possible values of @var{characteristic}:
-
-@table @code
-@item type
-The kind of window system the frame uses---either @code{x}, @code{pc}
-(for the MS-DOS console), @code{w32} (for MS Windows 9X/NT), or
-@code{tty}.
-
-@item class
-What kinds of colors the frame supports---either @code{color},
-@code{grayscale}, or @code{mono}.
-
-@item background
-The kind of background--- either @code{light} or @code{dark}.
-@end table
-
-If an element of @var{display} specifies more than one
-@var{value} for a given @var{characteristic}, any of those values
-is acceptable.  If an element of @var{display} has elements for
-more than one @var{characteristic}, then @var{each} characteristic
-of the frame must match one of the values specified for it.
-@end defmac
-
-Internally, @code{defface} uses the symbol property
-@code{face-defface-spec} to record the face attributes specified in
-@code{defface}, @code{saved-face} for the attributes saved by the user
-with the customization buffer, and @code{face-documentation} for the
-documentation string.
-
 @node Customization Types
 @section Customization Types
 
   When you define a user option with @code{defcustom}, you must specify
-its @dfn{customization type}.  That is a Lisp object which indictaes (1)
+its @dfn{customization type}.  That is a Lisp object which describes (1)
 which values are legitimate and (2) how to display the value in the
 customization buffer for editing.
 
   You specify the customization type in @code{defcustom} with the
 @code{:type} keyword.  The argument of @code{:type} is evaluated; since
-types that vary at run time are rarely useful, normally it is a quoted
+types that vary at run time are rarely useful, normally you use a quoted
 constant.  For example:
 
 @example
 (defcustom diff-command "diff"
   "*The command to use to run diff."
-  :type 'string
+  :type '(string)
   :group 'diff)
 @end example
 
-  In general, a customization type appears is a list whose first element
-is a symbol, one of the customization type names defined in the
-following sections.  After this symbol come a number of arguments,
-depending on the symbol.  Some of the type symbols do not use any
-arguments; those are called @dfn{simple types}.
-
-  In between the type symbol and its arguments, you can optionally
-write keyword-value pairs.  @xref{Type Keywords}.
+  In general, a customization type is a list whose first element is a
+symbol, one of the customization type names defined in the following
+sections.  After this symbol come a number of arguments, depending on
+the symbol.  Between the type symbol and its arguments, you can
+optionally write keyword-value pairs (@pxref{Type Keywords}).
 
-  For a simple type, if you do not use any keyword-value pairs, you can
-omit the parentheses around the type symbol.  The above example does
-this, using just @code{string} as the customization type.
-But @code{(string)} would mean the same thing.
+  Some of the type symbols do not use any arguments; those are called
+@dfn{simple types}.  For a simple type, if you do not use any
+keyword-value pairs, you can omit the parentheses around the type
+symbol.  For example just @code{string} as a customization type is
+equivalent to @code{(string)}.
 
 @menu
 * Simple Types::
@@ -400,10 +345,12 @@ customization buffer.
 
 @item string
 The value must be a string, and the customization buffer shows just the
-contents, with no @samp{"} characters or quoting with @samp{\}.
+contents, with no delimiting @samp{"} characters and no quoting with
+@samp{\}.
 
 @item regexp
-The value must be a string which is a valid regular expression.
+Like @code{string} except that the string must be a valid regular
+expression.
 
 @item character
 The value must be a character code.  A character code is actually an
@@ -435,15 +382,19 @@ The value must be a variable name, and you can do completion with
 @kbd{M-@key{TAB}}.
 
 @item boolean
-The value is boolean---either @code{nil} or @code{t}.
+The value is boolean---either @code{nil} or @code{t}.  Note that by
+using @code{choice} and @code{const} together (see the next section),
+you can specify that the value must be @code{nil} or @code{t}, but also
+specify the text to describe each value in a way that fits the specific
+meaning of the alternative.
 @end table
 
 @node Composite Types
 @subsection Composite Types
 
   When none of the simple types is appropriate, you can use composite
-types, which build from simple types.  Here are several ways of doing
-that:
+types, which build new types from other types.  Here are several ways of
+doing that:
 
 @table @code
 @item (restricted-sexp :match-alternatives @var{criteria})
@@ -459,7 +410,7 @@ are acceptable.
 
 @item
 A quoted constant---that is, @code{'@var{object}}.  This means that
-@var{object} is an acceptable value.
+@var{object} itself is an acceptable value.
 @end itemize
 
 For example,
@@ -480,7 +431,7 @@ its @sc{cdr} must fit @var{cdr-type}.  For example, @code{(const string
 symbol)} is a customization type which matches values such as
 @code{("foo" . foo)}.
 
-In the customization buffeer, the @sc{car} and the @sc{cdr} are
+In the customization buffer, the @sc{car} and the @sc{cdr} are
 displayed and edited separately, each according to the type
 that you specify for it.
 
@@ -493,7 +444,7 @@ For example, @code{(list integer string function)} describes a list of
 three elements; the first element must be an integer, the second a
 string, and the third a function.
 
-In the customization buffeer, the each element is displayed and edited
+In the customization buffer, the each element is displayed and edited
 separately, according to the type specified for it.
 
 @item (vector @var{element-types}@dots{})
@@ -523,22 +474,37 @@ verbatim, you might write the customization type this way,
 @noindent
 so that the menu offers @samp{Number of spaces} and @samp{Literal Text}.
 
+In any alternative for which @code{nil} is not a valid value, other than
+a @code{const}, you should specify a valid default for that alternative
+using the @code{:value} keyword.  @xref{Type Keywords}.
+
 @item (const @var{value})
 The value must be @var{value}---nothing else is allowed.
 
 The main use of @code{const} is inside of @code{choice}.  For example,
 @code{(choice integer (const nil))} allows either an integer or
-@code{nil}.  @code{:tag} is often used with @code{const}.
+@code{nil}.
+
+@code{:tag} is often used with @code{const}, inside of @code{choice}.
+For example,
+
+@smallexample
+(choice (const :tag "Yes" t)
+        (const :tag "No" nil)
+        (const :tag "Ask" foo))
+@end smallexample
 
 @item (function-item @var{function})
 Like @code{const}, but used for values which are functions.  This
-displays the documentation string of the function @var{function}
-as well as its name.
+displays the documentation string as well as the function name.
+The documentation string is either the one you specify with
+@code{:doc}, or @var{function}'s own documentation string.
 
 @item (variable-item @var{variable})
 Like @code{const}, but used for values which are variable names.  This
-displays the documentation string of the variable @var{variable} as well
-as its name.
+displays the documentation string as well as the variable name.  The
+documentation string is either the one you specify with @code{:doc}, or
+@var{variable}'s own documentation string.
 
 @item (set @var{elements}@dots{})
 The value must be a list and each element of the list must be one of the
@@ -611,20 +577,22 @@ meanings:
 @table @code
 @item :value @var{default}
 This is used for a type that appears as an alternative inside of
-@code{:choice}; it specifies the default value to use, at first, if and
+@code{choice}; it specifies the default value to use, at first, if and
 when the user selects this alternative with the menu in the
 customization buffer.
 
 Of course, if the actual value of the option fits this alternative, it
 will appear showing the actual value, not @var{default}.
 
+If @code{nil} is not a valid value for the alternative, then it is
+essential to specify a valid default with @code{:value}.
+
 @item :format @var{format-string}
 This string will be inserted in the buffer to represent the value
 corresponding to the type.  The following @samp{%} escapes are available
 for use in @var{format-string}:
 
 @table @samp
-@ignore
 @item %[@var{button}%]
 Display the text @var{button} marked as a button.  The @code{:action}
 attribute specifies what the button will do if the user invokes it;
@@ -632,8 +600,7 @@ its value is a function which takes two arguments---the widget which
 the button appears in, and the event.
 
 There is no way to specify two different buttons with different
-actions; but perhaps there is no need for one.
-@end ignore
+actions.
 
 @item %@{@var{sample}%@}
 Show @var{sample} in a special face specified by @code{:sample-face}.
@@ -658,11 +625,15 @@ keyword.
 Display a literal @samp{%}. 
 @end table
 
+@item :action @var{action}
+Perform @var{action} if the user clicks on a button.
+
 @item :button-face @var{face}
-Use face @var{face} for text displayed with @samp{%[@dots{}%]}.
+Use the face @var{face} (a face name or a list of face names) for button
+text displayed with @samp{%[@dots{}%]}.
 
-@item :button-prefix
-@itemx :button-suffix
+@item :button-prefix @var{prefix}
+@itemx :button-suffix @var{suffix}
 These specify the text to display before and after a button.
 Each can be:
 
@@ -677,11 +648,19 @@ The string is inserted literally.
 The symbol's value is used.
 @end table
 
+@item :tag @var{tag}
+Use @var{tag} (a string) as the tag for the value (or part of the value)
+that corresponds to this type.
+
 @item :doc @var{doc}
-Use @var{doc} as the documentation string for this item.
+Use @var{doc} as the documentation string for this value (or part of the
+value) that corresponds to this type.  In order for this to work, you
+must specify a value for @code{:format}, and use @samp{%d} or @samp{%h}
+in that value.
 
-@item :tag @var{tag}
-Use @var{tag} (a string) as the tag for this item.
+The usual reason to specify a documentation string for a type is to
+provide more information about the meanings of alternatives inside a
+@code{:choice} type or the parts of some other composite type.
 
 @item :help-echo @var{motion-doc}
 When you move to this item with @code{widget-forward} or
@@ -689,9 +668,10 @@ When you move to this item with @code{widget-forward} or
 in the echo area.
 
 @item :match @var{function}
-Specify how to decide whether a value matches the type.  @var{function}
-should be a function that accepts two arguments, a widget and a value;
-it should return non-@code{nil} if the value is acceptable.
+Specify how to decide whether a value matches the type.  The
+corresponding value, @var{function}, should be a function that accepts
+two arguments, a widget and a value; it should return non-@code{nil} if
+the value is acceptable.
 
 @ignore
 @item :indent @var{columns}
diff --git a/lispref/debugging.texi b/lispref/debugging.texi
index 99e5e034358..9c7a4fd7be7 100644
--- a/lispref/debugging.texi
+++ b/lispref/debugging.texi
@@ -3,7 +3,7 @@
 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998 Free Software Foundation, Inc. 
 @c See the file elisp.texi for copying conditions.
 @setfilename ../info/debugging
-@node Debugging, Read and Print, Byte Compilation, Top
+@node Debugging, Read and Print, Advising, Top
 @chapter Debugging Lisp Programs
 
   There are three ways to investigate a problem in an Emacs Lisp program,
@@ -104,14 +104,18 @@ that error does not enter the debugger, regardless of the value of
 @code{debug-on-error}.
 
 The normal value of this variable lists several errors that happen often
-during editing but rarely result from bugs in Lisp programs.
+during editing but rarely result from bugs in Lisp programs.  However,
+``rarely'' is not ``never''; if your program fails with an error that
+matches this list, you will need to change this list in order to debug
+the error.  The easiest way is usually to set
+@code{debug-ignored-errors} to @code{nil}.
 @end defopt
 
 @defopt debug-on-signal
 Normally, errors that are caught by @code{condition-case} never run the
 debugger, even if @code{debug-on-error} is non-@code{nil}.  In other
-words, @code{condition-case} gets a chance to catch the error before the
-debugger gets a chance.
+words, @code{condition-case} gets a chance to handle the error before
+the debugger gets a chance.
 
 If you set @code{debug-on-signal} non-@code{nil}, then the debugger gets
 first chance at every error; an error will invoke the debugger
@@ -119,7 +123,7 @@ regardless of any @code{condition-case}, if the fits the criterion
 specified by the values of @code{debug-on-error} and
 @code{debug-ignored-errors}.
 
-@strong{Warning:} This variable is strong medecine!  Various parts of
+@strong{Warning:} This variable is strong medicine!  Various parts of
 Emacs handle errors in the normal course of affairs, and you may not
 even realize that errors happen there.  If you set
 @code{debug-on-signal} to a non-@code{nil} value, those errors will
@@ -132,7 +136,7 @@ enter the debugger.
   To debug an error that happens during loading of the @file{.emacs}
 file, use the option @samp{-debug-init}, which binds
 @code{debug-on-error} to @code{t} while @file{.emacs} is loaded and
-inhibits use of @code{condition-case} to catch init file errors.
+inhibits use of @code{condition-case} to catch init-file errors.
 
   If your @file{.emacs} file sets @code{debug-on-error}, the effect may
 not last past the end of loading @file{.emacs}.  (This is an undesirable
@@ -190,26 +194,25 @@ called shortly before the problem, step quickly over the call to that
 function, and then step through its caller.
 
 @deffn Command debug-on-entry function-name
-  This function requests @var{function-name} to invoke the debugger each time
+This function requests @var{function-name} to invoke the debugger each time
 it is called.  It works by inserting the form @code{(debug 'debug)} into
 the function definition as the first form.
 
-  Any function defined as Lisp code may be set to break on entry,
+Any function defined as Lisp code may be set to break on entry,
 regardless of whether it is interpreted code or compiled code.  If the
 function is a command, it will enter the debugger when called from Lisp
 and when called interactively (after the reading of the arguments).  You
 can't debug primitive functions (i.e., those written in C) this way.
 
-  When @code{debug-on-entry} is called interactively, it prompts
-for @var{function-name} in the minibuffer.
+When @code{debug-on-entry} is called interactively, it prompts for
+@var{function-name} in the minibuffer.  If the function is already set
+up to invoke the debugger on entry, @code{debug-on-entry} does nothing.
+@code{debug-on-entry} always returns @var{function-name}.
 
-  If the function is already set up to invoke the debugger on entry,
-@code{debug-on-entry} does nothing.
-
-  @strong{Note:} if you redefine a function after using
-@code{debug-on-entry} on it, the code to enter the debugger is lost.
-
-  @code{debug-on-entry} returns @var{function-name}.
+@strong{Note:} if you redefine a function after using
+@code{debug-on-entry} on it, the code to enter the debugger is discarded
+by the redefinition.  In effect, redefining the function cancels
+the break-on-entry feature for that function.
 
 @example
 @group
@@ -252,11 +255,12 @@ Entering:
 This function undoes the effect of @code{debug-on-entry} on
 @var{function-name}.  When called interactively, it prompts for
 @var{function-name} in the minibuffer.  If @var{function-name} is
-@code{nil} or the empty string, it cancels debugging for all functions.
+@code{nil} or the empty string, it cancels break-on-entry for all
+functions.
 
-If @code{cancel-debug-on-entry} is called more than once on the same
-function, the second call does nothing.  @code{cancel-debug-on-entry}
-returns @var{function-name}.
+Calling @code{cancel-debug-on-entry} does nothing to a function which is
+not currently set up to break on entry.  It always returns
+@var{function-name}.
 @end deffn
 
 @node Explicit Debug
@@ -326,8 +330,8 @@ code, so that you can see how control flows.  The debugger can step
 through the control structures of an interpreted function, but cannot do
 so in a byte-compiled function.  If you would like to step through a
 byte-compiled function, replace it with an interpreted definition of the
-same function.  (To do this, visit the source file for the function and
-type @kbd{C-M-x} on its definition.)
+same function.  (To do this, visit the source for the function and type
+@kbd{C-M-x} on its definition.)
 
   Here is a list of Debugger mode commands:
 
@@ -360,7 +364,8 @@ in the backtrace buffer.
 
 @item u
 Don't enter the debugger when the current frame is exited.  This
-cancels a @kbd{b} command on that frame.
+cancels a @kbd{b} command on that frame.  The visible effect is to
+remove the star from the line in the backtrace buffer.
 
 @item e
 Read a Lisp expression in the minibuffer, evaluate it, and print the
@@ -371,6 +376,10 @@ examine them.  This makes the debugger more transparent.  By contrast,
 @kbd{M-:} does nothing special in the debugger; it shows you the
 variable values within the debugger.
 
+@item R
+Like @kbd{e}, but also save the result of evaluation in the
+buffer @samp{*Debugger-record*}.
+
 @item q
 Terminate the program being debugged; return to top-level Emacs
 command execution.
@@ -383,11 +392,11 @@ Return a value from the debugger.  The value is computed by reading an
 expression with the minibuffer and evaluating it.
 
 The @kbd{r} command is useful when the debugger was invoked due to exit
-from a Lisp call frame (as requested with @kbd{b}); then the value
-specified in the @kbd{r} command is used as the value of that frame.  It
-is also useful if you call @code{debug} and use its return value.
-Otherwise, @kbd{r} has the same effect as @kbd{c}, and the specified
-return value does not matter.
+from a Lisp call frame (as requested with @kbd{b} or by entering the
+frame with @kbd{d}); then the value specified in the @kbd{r} command is
+used as the value of that frame.  It is also useful if you call
+@code{debug} and use its return value.  Otherwise, @kbd{r} has the same
+effect as @kbd{c}, and the specified return value does not matter.
 
 You can't use @kbd{r} when the debugger was entered due to an error.
 @end table
@@ -448,11 +457,11 @@ Beginning evaluation of function call form:
 @end smallexample
 
 @item exit
-When the first argument is @code{exit}, it indicates the exit of a
-stack frame previously marked to invoke the debugger on exit.  The
-second argument given to @code{debug} in this case is the value being
-returned from the frame.  The debugger displays @samp{Return value:} on
-the top line of the buffer, followed by the value being returned.
+When the first argument is @code{exit}, it indicates the exit of a stack
+frame previously marked to invoke the debugger on exit.  The second
+argument given to @code{debug} in this case is the value being returned
+from the frame.  The debugger displays @samp{Return value:} in the top
+line of the buffer, followed by the value being returned.
 
 @item error
 @cindex @code{error} in debug
@@ -605,8 +614,8 @@ bound to @code{nil}.  The debugger can set this variable to leave
 information for future debugger invocations during the same command
 invocation.
 
-The advantage, for the debugger, of using this variable rather than
-another global variable is that the data will never carry over to a
+The advantage, for the debugger, of using this variable rather than an
+ordinary global variable is that the data will never carry over to a
 subsequent command invocation.
 @end defvar
 
@@ -671,7 +680,8 @@ close parenthesis, and finally return to the mark.)
 way to be sure of this except by studying the program, but often the
 existing indentation is a clue to where the parentheses should have
 been.  The easiest way to use this clue is to reindent with @kbd{C-M-q}
-and see what moves.
+and see what moves.  @strong{But don't do this yet!}  Keep reading,
+first.
 
   Before you do this, make sure the defun has enough close parentheses.
 Otherwise, @kbd{C-M-q} will get an error, or will reindent all the rest
@@ -702,7 +712,7 @@ parenthesis at the beginning of the file, back up over it, and type
 insertion of the open parenthesis, and finally return to the mark.)
 
   Then find the actual matching close parenthesis by typing @kbd{C-M-f}
-at the beginning of the defun.  This will leave you somewhere short of
+at the beginning of that defun.  This will leave you somewhere short of
 the place where the defun ought to end.  It is possible that you will
 find a spurious close parenthesis in that vicinity.
 
diff --git a/lispref/display.texi b/lispref/display.texi
index 6a8c477e451..59782034ca6 100644
--- a/lispref/display.texi
+++ b/lispref/display.texi
@@ -3,7 +3,7 @@
 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc. 
 @c See the file elisp.texi for copying conditions.
 @setfilename ../info/display
-@node Display, Calendar, System Interface, Top
+@node Display, Calendar, Processes, Top
 @chapter Emacs Display
 
   This chapter describes a number of features related to the display
@@ -62,7 +62,7 @@ resumption.
 @cindex resume (cf. @code{no-redraw-on-reenter})
 This variable controls whether Emacs redraws the entire screen after it
 has been suspended and resumed.  Non-@code{nil} means there is no need
-to redraw, @code{nil} means redrawing is needed.
+to redraw, @code{nil} means redrawing is needed.  The default is @code{nil}.
 @end defvar
 
 @node Screen Size
@@ -136,9 +136,9 @@ line can either be continued on the next screen line, or truncated to
 one screen line.  The additional screen lines used to display a long
 text line are called @dfn{continuation} lines.  Normally, a @samp{$} in
 the rightmost column of the window indicates truncation; a @samp{\} on
-the rightmost column indicates a line that ``wraps'' or is continued
-onto the next line.  (The display table can specify alternative
-indicators; see @ref{Display Tables}.)
+the rightmost column indicates a line that ``wraps'' onto the next line,
+which is also called @dfn{continuing} the line.  (The display table can
+specify alternative indicators; see @ref{Display Tables}.)
 
   Note that continuation is different from filling; continuation happens
 on the screen only, not in the buffer contents, and it breaks a line
@@ -157,7 +157,7 @@ frame) regardless of the value of @code{truncate-lines}.
 
 @defopt default-truncate-lines
 This variable is the default value for @code{truncate-lines}, for
-buffers that do not have local values for it.
+buffers that do not have buffer-local values for it.
 @end defopt
 
 @defopt truncate-partial-width-windows
@@ -184,7 +184,7 @@ unless they are modified.
 
 Turning on the cache slows down processing of short lines somewhat.
 
-This variable is automatically local in every buffer.
+This variable is automatically buffer-local in every buffer.
 @end defvar
 
 @node The Echo Area
@@ -242,6 +242,16 @@ This function returns the message currently being displayed in the
 echo area, or @code{nil} if there is none.
 @end defun
 
+@defvar cursor-in-echo-area
+This variable controls where the cursor appears when a message is
+displayed in the echo area.  If it is non-@code{nil}, then the cursor
+appears at the end of the message.  Otherwise, the cursor appears at
+point---not in the echo area at all.
+
+The value is normally @code{nil}; Lisp programs bind it to @code{t}
+for brief periods of time.
+@end defvar
+
 @tindex echo-area-clear-hook
 @defvar echo-area-clear-hook
 This normal hook is run whenever the echo area is cleared---either by
@@ -274,16 +284,6 @@ characters in the same command will be echoed as well.
 If the value is zero, then command input is not echoed.
 @end defvar
 
-@defvar cursor-in-echo-area
-This variable controls where the cursor appears when a message is
-displayed in the echo area.  If it is non-@code{nil}, then the cursor
-appears at the end of the message.  Otherwise, the cursor appears at
-point---not in the echo area at all.
-
-The value is normally @code{nil}; Lisp programs bind it to @code{t}
-for brief periods of time.
-@end defvar
-
 @node Invisible Text
 @section Invisible Text
 
@@ -295,8 +295,7 @@ text property or a property of an overlay.
 In the simplest case, any non-@code{nil} @code{invisible} property makes
 a character invisible.  This is the default case---if you don't alter
 the default value of @code{buffer-invisibility-spec}, this is how the
-@code{invisibility} property works.  This feature is much like selective
-display (@pxref{Selective Display}), but more general and cleaner.
+@code{invisible} property works.
 
 More generally, you can use the variable @code{buffer-invisibility-spec}
 to control which values of the @code{invisible} property make text
@@ -322,17 +321,17 @@ A character is invisible if its @code{invisible} property is
 non-@code{nil}.  This is the default.
 
 @item a list
-Each element of the list makes certain characters invisible.
-Ultimately, a character is invisible if any of the elements of this list
-applies to it.  The list can have two kinds of elements:
+Each element of the list specifies a criterion for invisibility; if a
+character's @code{invisible} property fits any one of these criteria,
+the character is invisible.  The list can have two kinds of elements:
 
 @table @code
 @item @var{atom}
-A character is invisible if its @code{invisible} propery value
+A character is invisible if its @code{invisible} property value
 is @var{atom} or if it is a list with @var{atom} as a member.
 
 @item (@var{atom} . t)
-A character is invisible if its @code{invisible} propery value
+A character is invisible if its @code{invisible} property value
 is @var{atom} or if it is a list with @var{atom} as a member.
 Moreover, if this character is at the end of a line and is followed
 by a visible newline, it displays an ellipsis.
@@ -360,17 +359,17 @@ that a major mode should use the mode's own name as an element of
 property:
 
 @example
-;; If we want to display an ellipsis:
+;; @r{If you want to display an ellipsis:}
 (add-to-invisibility-spec '(my-symbol . t)) 
-;; If you don't want ellipsis:
+;; @r{If you don't want ellipsis:}
 (add-to-invisibility-spec 'my-symbol) 
 
 (overlay-put (make-overlay beginning end)
              'invisible 'my-symbol)
 
-;; When done with the overlays:
+;; @r{When done with the overlays:}
 (remove-from-invisibility-spec '(my-symbol . t))
-;; Or respectively:
+;; @r{Or respectively:}
 (remove-from-invisibility-spec 'my-symbol)
 @end example
 
@@ -401,14 +400,13 @@ it invisible again.
 @section Selective Display
 @cindex selective display
 
-  @dfn{Selective display} is a pair of features that hide certain
-lines on the screen.
+  @dfn{Selective display} refers to a pair of related features for
+hiding certain lines on the screen.
 
   The first variant, explicit selective display, is designed for use in
-a Lisp program.  The program controls which lines are hidden by altering
-the text.  Outline mode has traditionally used this variant.  It has
-been partially replaced by the invisible text feature (@pxref{Invisible
-Text}); there is a new version of Outline mode which uses that instead.
+a Lisp program: it controls which lines are hidden by altering the text.
+The invisible text feature (@pxref{Invisible Text}) has partially
+replaced this feature.
 
   In the second variant, the choice of lines to hide is made
 automatically based on indentation.  This variant is designed to be a
@@ -441,7 +439,8 @@ lines, or portions of lines, may be made invisible.
 @itemize @bullet
 @item
 If the value of @code{selective-display} is @code{t}, then any portion
-of a line that follows a control-m is not displayed.
+of a line that follows a control-m is not displayed.  This is explicit
+selective display.
 
 @item
 If the value of @code{selective-display} is a positive integer, then
@@ -543,15 +542,15 @@ given time.
 @c now.  Is it?
 @end defvar
 
-  You can do the same job by creating an overlay with a
+  You can do a similar job by creating an overlay with a
 @code{before-string} property.  @xref{Overlay Properties}.
 
 @node Temporary Displays
 @section Temporary Displays
 
-  Temporary displays are used by commands to put output into a buffer
-and then present it to the user for perusal rather than for editing.
-Many of the help commands use this feature.
+  Temporary displays are used by Lisp programs to put output into a
+buffer and then present it to the user for perusal rather than for
+editing.  Many help commands use this feature.
 
 @defspec with-output-to-temp-buffer buffer-name forms@dots{}
 This function executes @var{forms} while arranging to insert any
@@ -599,9 +598,6 @@ The value of the last form in @var{forms} is returned.
 If this variable is non-@code{nil}, @code{with-output-to-temp-buffer}
 calls it as a function to do the job of displaying a help buffer.  The
 function gets one argument, which is the buffer it should display.
-
-In Emacs versions 18 and earlier, this variable was called
-@code{temp-buffer-show-hook}.
 @end defvar
 
 @defun momentary-string-display string position &optional char message
@@ -620,8 +616,9 @@ the display and later (presumably) move point forward.  The argument
 The return value of @code{momentary-string-display} is not meaningful.
 
 If the string @var{string} does not contain control characters, you can
-do the same job in a more general way by creating an overlay with a
-@code{before-string} property.  @xref{Overlay Properties}.
+do the same job in a more general way by creating (and then subsequently
+deleting) an overlay with a @code{before-string} property.
+@xref{Overlay Properties}.
 
 If @var{message} is non-@code{nil}, it is displayed in the echo area
 while @var{string} is displayed in the buffer.  If it is @code{nil}, a
@@ -685,7 +682,7 @@ not to be part of the text.  Thus, copying text between various buffers
 and strings preserves text properties, but does not try to preserve
 overlays.  Changing a buffer's text properties marks the buffer as
 modified, while moving an overlay or changing its properties does not.
-Unlike text propery changes, overlay changes are not recorded in the
+Unlike text property changes, overlay changes are not recorded in the
 buffer's undo list.
 
 @table @code
@@ -803,8 +800,8 @@ If this property is non-@code{nil}, the overlay is deleted automatically
 if it ever becomes empty (i.e., if it spans no characters).
 
 @item local-map
-@cindex keymap of character
-@kindex local-map @r{(text property)}
+@cindex keymap of character (and overlays)
+@kindex local-map @r{(overlay property)}
 If this property is non-@code{nil}, it specifies a keymap for a portion
 of the text.  The property's value replaces the buffer's local map, when
 the character after point is within the overlay.  @xref{Active Keymaps}.
@@ -912,10 +909,8 @@ end of an overlay, before @var{pos}.
 @section Width
 
 Since not all characters have the same width, these functions let you
-check the width of a character.  @ref{Primitive Indent}
-
-@xref{Screen Lines}, for related
-functions.
+check the width of a character.  @xref{Primitive Indent}, and
+@ref{Screen Lines}, for related functions.
 
 @tindex char-width
 @defun char-width char
@@ -970,7 +965,7 @@ foreground color, background color, and optional underlining.  Faces
 control the display of text on the screen.
 
 @cindex face id
-Each face has its own @dfn{face id number} which distinguishes faces at
+Each face has its own @dfn{face number}, which distinguishes faces at
 low levels within Emacs.  However, for most purposes, you can refer to
 faces in Lisp programs by their names.
 
@@ -986,6 +981,7 @@ face name a special meaning in one frame if you wish.
 
 @menu
 * Standard Faces::      The faces Emacs normally comes with.
+* Defining Faces::      How to define a face with @code{defface}.
 * Merging Faces::       How Emacs decides which face to use for a character.
 * Face Functions::      How to define and examine faces.
 @end menu
@@ -1036,6 +1032,90 @@ This face uses the bold italic variant of the frame's font, if it has
 one.
 @end table
 
+@node Defining Faces
+@section Defining Faces
+
+  The way to define a new face is with @code{defface}.  This creates a
+kind of customization item (@pxref{Customization}) which the user can
+customize using the Customization buffer (@pxref{Easy Customization,,,
+emacs, The GNU Emacs Manual}).
+
+@tindex defface
+@defmac defface face spec doc [keyword value]... 
+Declare @var{face} as a customizable face that defaults according to
+@var{spec}.  Do not quote the symbol @var{face}.  The argument @var{doc}
+specifies the face documentation.
+
+When @code{defface} executes, it defines the face according to
+@var{spec}, then uses any customizations saved in the @file{.emacs} file
+to override that specification.
+
+The purpose of @var{spec} is to specify how the face should appear on
+different kinds of terminals.  It should be an alist whose elements have
+the form @code{(@var{display} @var{atts})}.  The element's @sc{car},
+@var{display}, specifies a class of terminals.  The @sc{cdr},
+@var{atts}, is a list of face attributes and their values; it specifies
+what the face should look like on that kind of terminal.  The possible
+attributes are defined in the value of @code{custom-face-attributes}.
+
+The @var{display} part of an element of @var{spec} determines which
+frames the element applies to.  If more than one element of @var{spec}
+matches a given frame, the first matching element is the only one used
+for that frame.  There are two possibilities for @var{display}:
+
+@table @asis
+@item @code{t}
+This element of @var{spec} matches all frames.  Therefore, any
+subsequent elements of @var{spec} are never used.  Normally
+@code{t} is used in the last (or only) element of @var{spec}.
+
+@item an list
+If @var{display} is alist, each elements should have the form
+@code{(@var{characteristic} @var{value}@dots{})}.  Here
+@var{characteristic} specifies a way of classifying frames, and the
+@var{value}s are possible classifications which @var{display} should
+apply to.  Here are the possible values of @var{characteristic}:
+
+@table @code
+@item type
+The kind of window system the frame uses---either @code{x}, @code{pc}
+(for the MS-DOS console), @code{w32} (for MS Windows 9X/NT), or
+@code{tty}.
+
+@item class
+What kinds of colors the frame supports---either @code{color},
+@code{grayscale}, or @code{mono}.
+
+@item background
+The kind of background--- either @code{light} or @code{dark}.
+@end table
+
+If an element of @var{display} specifies more than one @var{value} for a
+given @var{characteristic}, any of those values is acceptable.  If
+@var{display} has more than one element, each element should specify a
+different @var{characteristic}; then @emph{each} characteristic of the
+frame must match one of the @var{value}s specified for it in
+@var{display}.
+@end table
+@end defmac
+
+  Here's how the standard face @code{region} could be defined
+with @code{defface}:
+
+@example
+(defface region
+         ((((class color) (background dark))
+           (:background "blue"))
+          (t (:background "gray")))
+  "Used for displaying the region.")
+@end example
+
+  Internally, @code{defface} uses the symbol property
+@code{face-defface-spec} to record the face attributes specified in
+@code{defface}, @code{saved-face} for the attributes saved by the user
+with the customization buffer, and @code{face-documentation} for the
+documentation string.
+
 @node Merging Faces
 @subsection Merging Faces for Display
 
@@ -1043,9 +1123,9 @@ one.
 
 @itemize @bullet
 @item
-With defaults.  Each frame has a @dfn{default face}, whose id number is
-zero, which is used for all text that doesn't somehow specify another
-face.
+With defaults.  Each frame has a @dfn{default face}, which is used for
+all text that doesn't somehow specify another face.  (We may change this
+in a forthcoming Emacs version to serve as a default for all text.)
 
 @item
 With text properties.  A character may have a @code{face} property; if so,
@@ -1064,7 +1144,7 @@ With a region that is active.  In Transient Mark mode, the region is
 highlighted with a particular face (see @code{region-face}, below).
 
 @item
-With special glyphs.  Each glyph can specify a particular face id
+With special glyphs.  Each glyph can specify a particular face 
 number.  @xref{Glyphs}.
 @end itemize
 
@@ -1147,11 +1227,6 @@ and italic attributes cease to have any effect, because the precise font
 that you specified is always used.
 @end defun
 
-@defun set-face-underline-p face underline-p &optional frame
-This function sets the underline attribute of face @var{face}.
-Non-@code{nil} means do underline; @code{nil} means don't.
-@end defun
-
 @tindex set-face-bold-p
 @defun set-face-bold-p face bold-p &optional frame
 This function sets the bold attribute of face @var{face}.
@@ -1164,6 +1239,11 @@ This function sets the italic attribute of face @var{face}.
 Non-@code{nil} means italic; @code{nil} means non-italic.
 @end defun
 
+@defun set-face-underline-p face underline-p &optional frame
+This function sets the underline attribute of face @var{face}.
+Non-@code{nil} means do underline; @code{nil} means don't.
+@end defun
+
 @defun invert-face face &optional frame
 Swap the foreground and background colors of face @var{face}.  If the
 face doesn't specify both foreground and background, then its foreground
@@ -1189,10 +1269,6 @@ This function returns the name of the background stipple pattern of face
 This function returns the name of the font of face @var{face}.
 @end defun
 
-@defun face-underline-p face &optional frame
-This function returns the underline attribute of face @var{face}.
-@end defun
-
 @tindex face-bold-p
 @defun face-bold-p face &optional frame
 This function returns the bold attribute of face @var{face}.
@@ -1203,8 +1279,12 @@ This function returns the bold attribute of face @var{face}.
 This function returns the italic attribute of face @var{face}.
 @end defun
 
+@defun face-underline-p face &optional frame
+This function returns the underline attribute of face @var{face}.
+@end defun
+
 @defun face-id face
-This function returns the face id number of face @var{face}.
+This function returns the face number of face @var{face}.
 @end defun
 
 @tindex face-documentation
@@ -1226,13 +1306,13 @@ face if each attribute is either the same as that of the default face or
 @end defun
 
 @defvar region-face
-This variable's value specifies the face id to use to display characters
+This variable's value specifies the face number to use to display characters
 in the region when it is active (in Transient Mark mode only).  The face
 thus specified takes precedence over all faces that come from text
 properties and overlays, for characters in the region.  @xref{The Mark},
 for more information about Transient Mark mode.
 
-Normally, the value is the id number of the face named @code{region}.
+Normally, the value is the face number of the face named @code{region}.
 @end defvar
 
 @node Blinking
@@ -1245,19 +1325,11 @@ Normally, the value is the id number of the face named @code{region}.
   This section describes the mechanism by which Emacs shows a matching
 open parenthesis when the user inserts a close parenthesis.
 
-@vindex blink-paren-hook
 @defvar blink-paren-function
 The value of this variable should be a function (of no arguments) to
 be called whenever a character with close parenthesis syntax is inserted.
 The value of @code{blink-paren-function} may be @code{nil}, in which
 case nothing is done.
-
-@quotation
-@strong{Please note:} This variable was named @code{blink-paren-hook} in
-older Emacs versions, but since it is not called with the standard
-convention for hooks, it was renamed to @code{blink-paren-function} in
-version 19.
-@end quotation
 @end defvar
 
 @defvar blink-matching-paren
@@ -1321,7 +1393,7 @@ is non-@code{nil}, then mode lines are displayed in inverse video.
 Otherwise, mode lines are displayed normally, just like text.  The
 default is @code{t}.
 
-For X window frames, this displays mode lines using the face named
+For window frames, this displays mode lines using the face named
 @code{modeline}, which is normally the inverse of the default face
 unless you change it.
 @end defopt
@@ -1356,14 +1428,19 @@ just like the codes in the range 128 to 255.
 @item
 Character codes 128 through 255 map to sequences of four glyphs, where
 the first glyph is the @sc{ASCII} code for @samp{\}, and the others are
-digit characters representing the code in octal.  (A display table can
-specify a glyph to use instead of @samp{\}.)
+digit characters representing the charatcer code in octal.  (A display
+table can specify a glyph to use instead of @samp{\}.)
+
+@item
+Multibyte character codes above 256 are displayed as themselves, or as a
+question mark or empty box if the terminal cannot display that
+character.
 @end itemize
 
   The usual display conventions apply even when there is a display
 table, for any character whose entry in the active display table is
 @code{nil}.  Thus, when you set up a display table, you need only
-specify the characters for which you want unusual behavior.
+specify the characters for which you want special behavior.
 
   These variables affect the way certain characters are displayed on the
 screen.  Since they change the number of columns the characters occupy,
@@ -1397,10 +1474,10 @@ stops used by the command @code{tab-to-tab-stop}.  @xref{Indent Tabs}.
 @section Display Tables
 
 @cindex display table
-You can use the @dfn{display table} feature to control how all 256
-possible character codes display on the screen.  This is useful for
-displaying European languages that have letters not in the @sc{ASCII}
-character set.
+You can use the @dfn{display table} feature to control how all possible
+character codes display on the screen.  This is useful for displaying
+European languages that have letters not in the @sc{ASCII} character
+set.
 
 The display table maps each character code into a sequence of
 @dfn{glyphs}, each glyph being an image that takes up one character
@@ -1438,8 +1515,8 @@ display that character according to the usual display conventions
 characters, the whole buffer will be displayed as one long ``line.''
 
   The display table also has six ``extra slots'' which serve special
-purposes.  Here is a table of their meanings; @code{nil} means to use
-the default stated below.
+purposes.  Here is a table of their meanings; @code{nil} in any slot
+means to use the default for that slot, as stated below.
 
 @table @asis
 @item 0
@@ -1514,9 +1591,10 @@ The argument @var{table} should be either a display table or
 @end defun
 
 @defvar buffer-display-table
-This variable is automatically local in all buffers; its value in a
-particular buffer is the display table for that buffer, or @code{nil} if
-the buffer does not have an assigned display table.
+This variable is automatically buffer-local in all buffers; its value in
+a particular buffer specifies the display table for that buffer.  If it
+is @code{nil}, that means the buffer does not have an assigned display
+table.
 @end defvar
 
 @defvar standard-display-table
@@ -1556,22 +1634,23 @@ below).
 @item string
 Send the characters in @var{string} to the terminal to output
 this glyph.  This alternative is available on character terminals,
-but not under X.
+but not under a window system.
 
 @item integer
-Define this glyph code as an alias for code @var{integer}.  You can use
-an alias to specify a face code for the glyph; see below.
+Define this glyph code as an alias for glyph code @var{integer}.  You
+can use an alias to specify a face code for the glyph; see below.
 
 @item @code{nil}
-This glyph is simple.  On an ordinary terminal, the glyph code mod 524288
-is the character to output.  With X, the glyph code mod 524288 is the
-character to output, and the glyph code divided by 524288 specifies the
-@dfn{face id number} to use while outputting it.  (524288 is
+This glyph is simple.  On an ordinary terminal, the glyph code mod
+524288 is the character to output.  In a window system, the glyph code
+mod 524288 is the character to output, and the glyph code divided by
+524288 specifies the face number (@pxref{Face Functions}) to use while
+outputting it.  (524288 is
 @ifinfo
-2**19.
+2**19.)
 @end ifinfo
 @tex
-$2^{19}$.
+$2^{19}$.)
 @end tex
 @xref{Faces}.
 @end table
@@ -1604,9 +1683,9 @@ This is a synonym for @code{ding}.
 @defvar visible-bell
 This variable determines whether Emacs should flash the screen to
 represent a bell.  Non-@code{nil} means yes, @code{nil} means no.  This
-is effective under X windows, and on a character-only terminal provided
-the terminal's Termcap entry defines the visible bell capability
-(@samp{vb}).
+is effective on a window system, and on a character-only terminal
+provided the terminal's Termcap entry defines the visible bell
+capability (@samp{vb}).
 @end defvar
 
 @tindex ring-bell-function
diff --git a/lispref/edebug.texi b/lispref/edebug.texi
index 973021833b6..d8459d2bcea 100644
--- a/lispref/edebug.texi
+++ b/lispref/edebug.texi
@@ -1,8 +1,10 @@
 @comment -*-texinfo-*-
+@c This is part of the GNU Emacs Lisp Reference Manual.
+@c Copyright (C) 1992, 1993, 1994, 1998 Free Software Foundation, Inc. 
+@c See the file elisp.texi for copying conditions.
 
-@c This file is intended to be used as a section within the Emacs Lisp 
-@c Reference Manual.  It may also be used by an independent Edebug User 
-@c Manual, edebug.tex, in which case the Edebug node below should be used 
+@c This file can also be used by an independent Edebug User 
+@c Manual in which case the Edebug node below should be used 
 @c with the following links to the Bugs section and to the top level:
 
 @c , Bugs and Todo List, Top, Top
@@ -167,9 +169,8 @@ definition @emph{unless} it has a prefix argument.  The default value of
 edebug-all-defs} toggles the value of the variable
 @code{edebug-all-defs}.
 
-@findex edebug-all-forms
-@findex eval-region (Edebug)
-@findex eval-current-buffer (Edebug)
+@findex eval-region @r{(Edebug)}
+@findex eval-current-buffer @r{(Edebug)}
   If @code{edebug-all-defs} is non-@code{nil}, then the commands
 @code{eval-region}, @code{eval-current-buffer}, and @code{eval-buffer}
 also instrument any definitions they evaluate.  Similarly,
@@ -179,16 +180,11 @@ to loading or evaluations in the minibuffer.  The command @kbd{M-x
 edebug-all-forms} toggles this option.
 
 @findex edebug-eval-top-level-form
-Another command, @kbd{M-x edebug-eval-top-level-form}, is available to
+  Another command, @kbd{M-x edebug-eval-top-level-form}, is available to
 instrument any top-level form regardless of the values of
 @code{edebug-all-defs} and @code{edebug-all-forms}.
 
-When Edebug is about to instrument code for the first time in a session,
-it runs the hook @code{edebug-setup-hook}, then sets it to @code{nil}.
-You can use this to load up Edebug specifications associated with a
-package you are using, but only when you also use Edebug.
-
-While Edebug is active, the command @kbd{I}
+  While Edebug is active, the command @kbd{I}
 (@code{edebug-instrument-callee}) instruments the definition of the
 function or macro called by the list form after point, if is not already
 instrumented.  This is possible only if Edebug knows where to find the
@@ -201,7 +197,7 @@ steps into the call after instrumenting the function.
 @cindex interactive commands (Edebug)
 @cindex anonymous lambda expressions (Edebug)
 @cindex Common Lisp (Edebug)
-@pindex cl.el (Edebug)
+@pindex cl.el @r{(Edebug)}
 @pindex cl-specs.el
   Edebug knows how to instrument all the standard special forms, an
 interactive form with an expression argument, anonymous lambda
@@ -209,7 +205,13 @@ expressions, and other defining forms.  Edebug cannot know what a
 user-defined macro will do with the arguments of a macro call, so you
 must tell it; @xref{Instrumenting Macro Calls}, for details.
 
-@findex eval-expression (Edebug)
+  When Edebug is about to instrument code for the first time in a
+session, it runs the hook @code{edebug-setup-hook}, then sets it to
+@code{nil}.  You can use this to arrange to load Edebug specifications
+(@pxref{Instrumenting Macro Calls}) associated with a package you are
+using, but actually load them only if you use Edebug.
+
+@findex eval-expression @r{(Edebug)}
   To remove instrumentation from a definition, simply reevaluate its
 definition in a way that does not instrument.  There are two ways of
 evaluating forms that never instrument them: from a file with
@@ -472,7 +474,7 @@ stop point that has a previously established conditional breakpoint puts
 the previous condition expression in the minibuffer so you can edit it.
 
 You can make a conditional or unconditional breakpoint
-@dfn{temporary} by using a prefix arg with the command to set the
+@dfn{temporary} by using a prefix argument with the command to set the
 breakpoint.  When a temporary breakpoint stops the program, it is
 automatically unset.
 
@@ -504,7 +506,6 @@ depending on the execution mode, as if a breakpoint had been hit.  If
 evaluating the condition gets an error, execution does not stop.
 
 @findex edebug-set-global-break-condition
-@vindex edebug-global-break-condition
   The condition expression is stored in
 @code{edebug-global-break-condition}.  You can specify a new expression
 using the @kbd{X} command (@code{edebug-set-global-break-condition}).
@@ -533,24 +534,24 @@ line as shown below to stop when the argument reaches zero:
     1))
 @end example
 
-When the @code{fac} definition is instrumented and the function is
+  When the @code{fac} definition is instrumented and the function is
 called, the call to @code{edebug} acts as a breakpoint.  Depending on
 the execution mode, Edebug stops or pauses there.
 
-If no instrumented code is being executed when @code{edebug} is called,
+  If no instrumented code is being executed when @code{edebug} is called,
 that function calls @code{debug}.
 @c This may not be a good idea anymore.
 
 @node Trapping Errors
 @subsection Trapping Errors
 
-Emacs normally displays an error message when an error is signaled and
-not handled with @code{condition-case}.  While Edebug is active, it
-normally responds to all unhandled errors.  You can customize this with
-the options @code{edebug-on-error} and @code{edebug-on-quit}; see
-@ref{Edebug Options}.
+  Emacs normally displays an error message when an error is signaled and
+not handled with @code{condition-case}.  While Edebug is active and
+executing instrumented code, it normally responds to all unhandled
+errors.  You can customize this with the options @code{edebug-on-error}
+and @code{edebug-on-quit}; see @ref{Edebug Options}.
 
-When Edebug responds to an error, it shows the last stop point
+  When Edebug responds to an error, it shows the last stop point
 encountered before the error.  This may be the location of a call to a
 function which was not instrumented, within which the error actually
 occurred.  For an unbound variable error, the last known stop point
@@ -558,7 +559,7 @@ might be quite distant from the offending variable reference.  In that
 case you might want to display a full backtrace (@pxref{Edebug Misc}).
 
 @c Edebug should be changed for the following: -- dan
-If you change @code{debug-on-error} or @code{debug-on-quit} while
+  If you change @code{debug-on-error} or @code{debug-on-quit} while
 Edebug is active, these changes will be forgotten when Edebug becomes
 inactive.  Furthermore, during Edebug's recursive edit, these variables
 are bound to the values they had outside of Edebug.
@@ -566,7 +567,7 @@ are bound to the values they had outside of Edebug.
 @node Edebug Views
 @subsection Edebug Views
 
-These Edebug commands let you view aspects of the buffer and window
+  These Edebug commands let you view aspects of the buffer and window
 status that obtained before entry to Edebug.  The outside window
 configuration is the collection of windows and contents that were in
 effect outside of Edebug.
@@ -597,12 +598,12 @@ the selected window.  To specify a window that is not displaying the
 source code buffer, you must use @kbd{C-x X W} from the global keymap.
 @end table
 
-You can view the outside window configuration with @kbd{v} or just
+  You can view the outside window configuration with @kbd{v} or just
 bounce to the point in the current buffer with @kbd{p}, even if
 it is not normally displayed.  After moving point, you may wish to jump
 back to the stop point with @kbd{w} from a source code buffer.
 
-Each time you use @kbd{W} to turn saving @emph{off}, Edebug forgets the
+  Each time you use @kbd{W} to turn saving @emph{off}, Edebug forgets the
 saved outside window configuration---so that even if you turn saving
 back @emph{on}, the current window configuration remains unchanged when
 you next exit Edebug (by continuing the program).  However, the
@@ -613,7 +614,7 @@ open.
 @node Edebug Eval
 @subsection Evaluation
 
-While within Edebug, you can evaluate expressions ``as if'' Edebug were
+  While within Edebug, you can evaluate expressions ``as if'' Edebug were
 not running.  Edebug tries to be invisible to the expression's
 evaluation and printing.  Evaluation of expressions that cause side
 effects will work as expected except for things that Edebug explicitly
@@ -635,16 +636,15 @@ Evaluate the expression before point, in the context outside of Edebug
 @end table
 
 @cindex lexical binding (Edebug)
-Edebug supports evaluation of expressions containing references to
+  Edebug supports evaluation of expressions containing references to
 lexically bound symbols created by the following constructs in
 @file{cl.el} (version 2.03 or later): @code{lexical-let},
 @code{macrolet}, and @code{symbol-macrolet}.
 
-
 @node Eval List
 @subsection Evaluation List Buffer
 
-You can use the @dfn{evaluation list buffer}, called @samp{*edebug*}, to
+  You can use the @dfn{evaluation list buffer}, called @samp{*edebug*}, to
 evaluate expressions interactively.  You can also set up the
 @dfn{evaluation list} of expressions to be evaluated automatically each
 time Edebug updates the display.
@@ -655,12 +655,12 @@ Switch to the evaluation list buffer @samp{*edebug*}
 (@code{edebug-visit-eval-list}).
 @end table
 
-In the @samp{*edebug*} buffer you can use the commands of Lisp
+  In the @samp{*edebug*} buffer you can use the commands of Lisp
 Interaction mode (@pxref{Lisp Interaction,,, emacs, The GNU Emacs
 Manual}) as well as these special commands:
 
 @table @kbd
-@item LFD
+@item C-j
 Evaluate the expression before point, in the outside context, and insert
 the value in the buffer (@code{edebug-eval-print-last-sexp}).
 
@@ -681,40 +681,36 @@ Switch back to the source code buffer at the current stop point
 (@code{edebug-where}).
 @end table
 
-You can evaluate expressions in the evaluation list window with
-@kbd{LFD} or @kbd{C-x C-e}, just as you would in @samp{*scratch*};
+  You can evaluate expressions in the evaluation list window with
+@kbd{C-j} or @kbd{C-x C-e}, just as you would in @samp{*scratch*};
 but they are evaluated in the context outside of Edebug.
 
-The expressions you enter interactively (and their results) are lost
+  The expressions you enter interactively (and their results) are lost
 when you continue execution; but you can set up an @dfn{evaluation list}
 consisting of expressions to be evaluated each time execution stops. 
 
 @cindex evaluation list group
-To do this, write one or more @dfn{evaluation list groups} in the
+  To do this, write one or more @dfn{evaluation list groups} in the
 evaluation list buffer.  An evaluation list group consists of one or
 more Lisp expressions.  Groups are separated by comment lines.
 
-The command @kbd{C-c C-u} (@code{edebug-update-eval-list}) rebuilds the
+  The command @kbd{C-c C-u} (@code{edebug-update-eval-list}) rebuilds the
 evaluation list, scanning the buffer and using the first expression of
 each group.  (The idea is that the second expression of the group is the
 value previously computed and displayed.)
 
-Be careful not to add expressions that execute instrumented code since
-that would cause an infinite loop.
-@c There ought to be a way to fix this.
-
-Each entry to Edebug redisplays the evaluation list by inserting each
+  Each entry to Edebug redisplays the evaluation list by inserting each
 expression in the buffer, followed by its current value.  It also
 inserts comment lines so that each expression becomes its own group.
 Thus, if you type @kbd{C-c C-u} again without changing the buffer text,
 the evaluation list is effectively unchanged.
 
-If an error occurs during an evaluation from the evaluation list, the
+  If an error occurs during an evaluation from the evaluation list, the
 error message is displayed in a string as if it were the result.
 Therefore, expressions that use variables not currently valid do not
 interrupt your debugging.
 
-Here is an example of what the evaluation list window looks like after
+  Here is an example of what the evaluation list window looks like after
 several expressions have been added to it:
 
 @smallexample
@@ -759,8 +755,6 @@ you continue execution, and recreated next time it is needed.
   If an expression in your program produces a value containing circular
 list structure, you may get an error when Edebug attempts to print it.
 
-@vindex edebug-print-length
-@vindex edebug-print-level
   One way to cope with circular structure is to set @code{print-length}
 or @code{print-level} to truncate the printing.  Edebug does this for
 you; it binds @code{print-length} and @code{print-level} to 50 if they
@@ -768,6 +762,17 @@ were @code{nil}.  (Actually, the variables @code{edebug-print-length}
 and @code{edebug-print-level} specify the values to use within Edebug.)
 @xref{Output Variables}.
 
+@defopt edebug-print-length
+If non-@code{nil}, bind @code{print-length} to this while printing
+results in Edebug.  The default value is @code{50}.
+@xref{Printing in Edebug}.
+@end defopt
+
+@defopt edebug-print-level 
+If non-@code{nil}, bind @code{print-level} to this while printing
+results in Edebug.  The default value is @code{50}.
+@end defopt
+
   You can also print circular structures and structures that share
 elements more informatively by using the @file{cust-print} package.
 
@@ -790,6 +795,11 @@ Custom printing prints this as @samp{Result: #1=(#1# y)}.  The
 structure.  This notation is used for any shared elements of lists or
 vectors.
 
+@defopt edebug-print-circle 
+If non-@code{nil}, bind @code{print-circle} to this while printing
+results in Edebug.  The default value is @code{nil}.
+@end defopt
+
   Other programs can also use custom printing; see @file{cust-print.el}
 for details.
 
@@ -850,7 +860,7 @@ Edebug provides rudimentary coverage testing and display of execution
 frequency.  All execution of an instrumented function accumulates
 frequency counts, both before and after evaluation of each instrumented
 expression, even if the execution mode is Go-nonstop.  Coverage testing
-is more expensive, so it is only done if @code{edebug-test-coverage} is
+is more expensive, so it is done only if @code{edebug-test-coverage} is
 non-@code{nil}.  The command @kbd{M-x edebug-display-freq-count}
 displays both the frequency data and the coverage data (if recorded).
 
@@ -858,11 +868,11 @@ displays both the frequency data and the coverage data (if recorded).
 This command displays the frequency count data for each line of the
 current definition.
 
-The frequency counts appear as comment lines after each line of code, and
-you can undo all insertions with one @code{undo} command.  The counts
-appear under the @kbd{(} before an expression or the @kbd{)} after
-an expression, or on the last character of a symbol.  Values do not appear if
-they are equal to the previous count on the same line.
+The frequency counts appear as comment lines after each line of code,
+and you can undo all insertions with one @code{undo} command.  The
+counts appear under the @samp{(} before an expression or the @samp{)}
+after an expression, or on the last character of a symbol.  Values do
+not appear if they are equal to the previous count on the same line.
 
 The character @samp{=} following the count for an expression says that
 the expression has returned the same value each time it was evaluated
@@ -1035,14 +1045,16 @@ Edebug is active, @code{defining-kbd-macro} is bound to
 @node Instrumenting Macro Calls
 @subsection Instrumenting Macro Calls
 
-When Edebug instruments an expression that calls a Lisp macro, it needs
-additional advice to do the job properly.  This is because there is no
-way to tell which subexpressions of the macro call are forms to be
-evaluated.  (Evaluation may occur explicitly in the macro body, or when
-the resulting expansion is evaluated, or any time later.)  You must
-explain the format of calls to each macro to enable Edebug to handle it.
-To do this, use @code{def-edebug-spec} to define the format of
-calls to a given macro.
+  When Edebug instruments an expression that calls a Lisp macro, it needs
+additional information about the macro to do the job properly.  This is
+because there is no a-priori way to tell which subexpressions of the
+macro call are forms to be evaluated.  (Evaluation may occur explicitly
+in the macro body, or when the resulting expansion is evaluated, or any
+time later.)
+
+  Therefore, you must define an Edebug specification for each macro that
+Edebug will encounter, to explain the format of calls to that macro.  To
+do this, use @code{def-edebug-spec}.
 
 @deffn Macro def-edebug-spec macro specification
 Specify which expressions of a call to macro @var{macro} are forms to be
@@ -1050,7 +1062,7 @@ evaluated.  For simple macros, the @var{specification} often looks very
 similar to the formal argument list of the macro definition, but
 specifications are much more general than macro arguments.
 
-The @var{macro} argument may actually be any symbol, not just a macro
+The @var{macro} argument can actually be any symbol, not just a macro
 name.
 @end deffn
 
@@ -1108,7 +1120,7 @@ as @code{&optional}).
 A specification list may contain sublists which match arguments that are
 themselves lists, or it may contain vectors used for grouping.  Sublists
 and groups thus subdivide the specification list into a hierarchy of
-levels.  Specification keywords only apply to the remainder of the
+levels.  Specification keywords apply only to the remainder of the
 sublist or group they are contained in.
 
 When a specification list involves alternatives or repetition, matching
@@ -1262,7 +1274,7 @@ sublist-elements@dots{})}.
 
 @c Need to document extensions with &symbol and :symbol
 
-Here is a list of additional specifications that may only appear after
+Here is a list of additional specifications that may appear only after
 @code{&define}.  See the @code{defun} example below.
 
 @table @code
@@ -1304,7 +1316,7 @@ tracing information is not output when the form is executed.  See the
 @end table
 
 @node Backtracking
-@subsubsection Backtracking
+@subsubsection Backtracking in Specifications
 
 @cindex backtracking
 @cindex syntax error (Edebug)
@@ -1473,8 +1485,6 @@ The default value is @code{step}.
 @end defopt
 
 @defopt edebug-trace
-@findex edebug-print-trace-before
-@findex edebug-print-trace-after
 Non-@code{nil} means display a trace of function entry and exit.
 Tracing output is displayed in a buffer named @samp{*edebug-trace*}, one
 function entry or exit per line, indented by the recursion level.  
@@ -1504,22 +1514,6 @@ debugged.
 @xref{Edebug Execution Modes}.
 @end defopt
 
-@defopt edebug-print-length
-If non-@code{nil}, bind @code{print-length} to this while printing
-results in Edebug.  The default value is @code{50}.
-@xref{Printing in Edebug}.
-@end defopt
-
-@defopt edebug-print-level 
-If non-@code{nil}, bind @code{print-level} to this while printing
-results in Edebug.  The default value is @code{50}.
-@end defopt
-
-@defopt edebug-print-circle 
-If non-@code{nil}, bind @code{print-circle} to this while printing
-results in Edebug.  The default value is @code{nil}.
-@end defopt
-
 @defopt edebug-on-error
 Edebug binds @code{debug-on-error} to this value, if
 @code{debug-on-error} was previously @code{nil}.  @xref{Trapping
diff --git a/lispref/errors.texi b/lispref/errors.texi
index 01ddf41ab64..809db995ed0 100644
--- a/lispref/errors.texi
+++ b/lispref/errors.texi
@@ -55,8 +55,7 @@ See @code{/} and @code{%} in @ref{Numbers}.
 @xref{Read Only Buffers}.
 
 @item cyclic-function-indirection
-@code{"Symbol's chain of function indirections contains a@*
-loop"}@*
+@code{"Symbol's chain of function indirections contains a loop"}@*
 @xref{Function Indirection}.
 
 @item end-of-buffer
@@ -65,9 +64,14 @@ loop"}@*
 
 @item end-of-file
 @code{"End of file during parsing"}@*
-This is not a @code{file-error}.@*
+Note that this is not a @code{file-error}
+because it pertains to the Lisp reader, not to file I/O.
 @xref{Input Functions}.
 
+@item file-already-exists
+This is a @code{file-error}.@*
+@xref{Writing to Files}.
+
 @item file-date-error
 This is a subcategory of @code{file-error}.  It occurs when
 @code{copy-file} tries and fails to set the last-modification time of
@@ -83,10 +87,6 @@ condition @code{file-error} is present.@*
 This is a @code{file-error}.@*
 @xref{File Locks}.
 
-@item file-already-exists
-This is a @code{file-error}.@*
-@xref{Writing to Files}.
-
 @item file-supersession
 This is a @code{file-error}.@*
 @xref{Modification Time}.
@@ -103,17 +103,28 @@ This is a @code{file-error}.@*
 @code{"Invalid regexp"}@*
 @xref{Regular Expressions}.
 
+@item mark-inactive
+@code{Mark inactive"}@*
+@xref{The Mark}.
+
 @item no-catch
 @code{"No catch for tag"}@*
 @xref{Catch and Throw}.
 
+@item scan-error
+@code{"Scan error"}@*
+This happens when certain syntax-parsing functions
+find invalid syntax or mismatched parentheses.@*
+@xref{List Motion}, and @ref{Parsing Expressions}.
+
 @item search-failed
 @code{"Search failed"}@*
 @xref{Searching and Matching}.
 
 @item setting-constant
 @code{"Attempt to set a constant symbol"}@* 
-The values of the symbols @code{nil} and @code{t}
+The values of the symbols @code{nil} and @code{t},
+and any symbols that start with @samp{:},
 may not be changed.@*
 @xref{Constant Variables, , Variables that Never Change}.
 
@@ -138,7 +149,7 @@ may not be changed.@*
 @xref{Type Predicates}.
 @end table
 
-  These error types, which are all classified as special cases of
+  These kinds of error, which are classified as special cases of
 @code{arith-error}, can occur on certain systems for invalid use of
 mathematical functions.
 
diff --git a/lispref/eval.texi b/lispref/eval.texi
index 7d5cbf7a68e..512e6d927b2 100644
--- a/lispref/eval.texi
+++ b/lispref/eval.texi
@@ -139,7 +139,7 @@ unchanged.
 
 @example
 @group
-'123               ; @r{An object, shown without evaluation.}
+'123               ; @r{A number, shown without evaluation.}
      @result{} 123
 @end group
 @group
@@ -210,7 +210,8 @@ value of @code{nil} is always @code{nil}, and the value of @code{t} is
 always @code{t}; you cannot set or bind them to any other values.  Thus,
 these two symbols act like self-evaluating forms, even though
 @code{eval} treats them like any other symbol.  A symbol whose name
-starts with @samp{:} also self-evaluates in the same way.
+starts with @samp{:} also self-evaluates in the same way; likewise,
+its value ordinarily cannot be changed.  @xref{Constant Variables}.
 
 @node Classifying Lists
 @subsection Classification of List Forms
@@ -646,15 +647,16 @@ buffer.
 @defvar max-lisp-eval-depth
 This variable defines the maximum depth allowed in calls to @code{eval},
 @code{apply}, and @code{funcall} before an error is signaled (with error
-message @code{"Lisp nesting exceeds max-lisp-eval-depth"}).  This counts
-internal uses of those functions, such as for calling the functions
-mentioned in Lisp expressions, and recursive evaluation of function call
-arguments and function body forms.
-
-This limit, with the associated error when it is exceeded, is one way
-that Lisp avoids infinite recursion on an ill-defined function.
+message @code{"Lisp nesting exceeds max-lisp-eval-depth"}).  This limit,
+with the associated error when it is exceeded, is one way that Lisp
+avoids infinite recursion on an ill-defined function.
 @cindex Lisp nesting error
 
+The depth limit counts internal uses of @code{eval}, @code{apply}, and
+@code{funcall}, such as for calling the functions mentioned in Lisp
+expressions, and recursive evaluation of function call arguments and
+function body forms, as well as explicit calls in Lisp code.
+
 The default value of this variable is 200.  If you set it to a value
 less than 100, Lisp will reset it to 100 if the given value is reached.
 
diff --git a/lispref/files.texi b/lispref/files.texi
index 4a5539eac45..45f8097fecd 100644
--- a/lispref/files.texi
+++ b/lispref/files.texi
@@ -35,7 +35,6 @@ substitutions such as @samp{$HOME}.  @xref{File Name Expansion}.
 * Magic File Names::         Defining "magic" special handling
                                for certain file names.
 * Format Conversion::        Conversion to and from various file formats.
-* Files and MS-DOS::         Distinguishing text and binary files on MS-DOS.
 @end menu
 
 @node Visiting Files
@@ -116,12 +115,11 @@ saved in that buffer.  If the file has changed, then this function asks
 the user whether to reread the changed file.  If the user says
 @samp{yes}, any changes previously made in the buffer are lost.
 
-If @code{find-file-noselect} needs to create a buffer, and there is no
-file named @var{filename}, it displays the message @samp{New file} in
-the echo area, and leaves the buffer empty.
-
 This function displays warning or advisory messages in various peculiar
-cases, unless the optional argument @var{nowarn} is non-@code{nil}.
+cases, unless the optional argument @var{nowarn} is non-@code{nil}.  For
+example, if it needs to create a buffer, and there is no file named
+@var{filename}, it displays the message @samp{New file} in the echo
+area, and leaves the buffer empty.
 
 The @code{find-file-noselect} function normally calls
 @code{after-find-file} after reading the file (@pxref{Subroutines of
@@ -297,26 +295,20 @@ the user.
 
 The optional @var{exiting} argument, if non-@code{nil}, requests this
 function to offer also to save certain other buffers that are not
-visiting files.  These are buffers that have a non-@code{nil} local
-value of @code{buffer-offer-save}.  (A user who says yes to saving one
-of these is asked to specify a file name to use.)  The
+visiting files.  These are buffers that have a non-@code{nil}
+buffer-local value of @code{buffer-offer-save}.  (A user who says yes to
+saving one of these is asked to specify a file name to use.)  The
 @code{save-buffers-kill-emacs} function passes a non-@code{nil} value
 for this argument.
 @end deffn
 
-@defvar buffer-offer-save
-When this variable is non-@code{nil} in a buffer, Emacs offers to save
-the buffer on exit even if the buffer is not visiting a file.  The
-variable is automatically local in all buffers.  Normally, Mail mode
-(used for editing outgoing mail) sets this to @code{t}.
-@end defvar
-
 @deffn Command write-file filename
 This function writes the current buffer into file @var{filename}, makes
 the buffer visit that file, and marks it not modified.  Then it renames
 the buffer based on @var{filename}, appending a string like @samp{<2>}
 if necessary to make a unique buffer name.  It does most of this work by
-calling @code{set-visited-file-name} and @code{save-buffer}.
+calling @code{set-visited-file-name} (@pxref{Buffer File Name}) and
+@code{save-buffer}.
 @end deffn
 
   Saving a buffer runs several hooks.  It also performs format
@@ -352,8 +344,8 @@ Even though this is not a normal hook, you can use @code{add-hook} and
 @c Emacs 19 feature
 @defvar local-write-file-hooks
 This works just like @code{write-file-hooks}, but it is intended to be
-made local to particular buffers, and used for hooks that pertain to the
-file name or the way the buffer contents were obtained.
+made buffer-local in particular buffers, and used for hooks that pertain
+to the file name or the way the buffer contents were obtained.
 
 The variable is marked as a permanent local, so that changing the major
 mode does not alter a buffer-local value.  This is convenient for
@@ -372,7 +364,7 @@ This variable automatically becomes buffer-local whenever it is set;
 switching to a new major mode always resets this variable.  When you use
 @code{add-hooks} to add an element to this hook, you should @emph{not}
 specify a non-@code{nil} @var{local} argument, since this variable is
-used @emph{only} locally.
+used @emph{only} buffer-locally.
 @end defvar
 
 @c Emacs 19 feature
@@ -392,8 +384,8 @@ As a side effect, backups are necessarily made by copying.  @xref{Rename
 or Copy}.  Yet, at the same time, saving a precious file always breaks
 all hard links between the file you save and other file names.
 
-Some modes set this variable non-@code{nil} locally in particular
-buffers.
+Some modes give this variable non-@code{nil} buffer-local value
+in particular buffers.
 @end defvar
 
 @defopt require-final-newline
@@ -410,16 +402,8 @@ doesn't add newlines at all.  @code{nil} is the default value, but a few
 major modes set it to @code{t} in particular buffers.
 @end defopt
 
-@deffn Command set-visited-file-name filename &optional no-query
-This function changes the visited file name of the current buffer to
-@var{filename}.  It also renames the buffer based on @var{filename},
-appending a string like @samp{<2>} if necessary to make a unique buffer
-name.  It marks the buffer as @emph{modified},a since the contents do not
-(as far as Emacs knows) match the actual file's contents.
-
-If the specified file already exists, @code{set-visited-file-name}
-asks for confirmation unless @var{no-query} is non-@code{nil}.
-@end deffn
+  See also the function @code{set-visited-file-name} (@pxref{Buffer File
+Name}).
 
 @node Reading from Files
 @comment  node-name,  next,  previous,  up
@@ -542,15 +526,12 @@ files that the user does not need to know about.
 
 @tindex with-temp-file
 @defmac with-temp-file file body...
-The @code{with-temp-file} macro evaluates the @var{body} forms
-with a temporary buffer as the current buffer; then, at the end, it
-writes the buffer contents into file @var{file}.  It kills the temporary
-buffer when finished, restoring the buffer that was current before the
-@code{with-temp-file} form.
-
-The return value is the value of the last form in @var{body}.  You can
-return the contents of the temporary buffer by using
-@code{(buffer-string)} as the last form.
+The @code{with-temp-file} macro evaluates the @var{body} forms with a
+temporary buffer as the current buffer; then, at the end, it writes the
+buffer contents into file @var{file}.  It kills the temporary buffer
+when finished, restoring the buffer that was current before the
+@code{with-temp-file} form.  Then it returns the value of the last form
+in @var{body}.
 
 The current buffer is restored even in case of an abnormal exit via
 @code{throw} or error (@pxref{Nonlocal Exits}).
@@ -568,13 +549,12 @@ arising by recording a @dfn{file lock} when a file is being modified.
 Emacs can then detect the first attempt to modify a buffer visiting a
 file that is locked by another Emacs job, and ask the user what to do.
 
-  File locks do not work properly when multiple machines can share
-file systems, such as with NFS.  Perhaps a better file locking system
-will be implemented in the future.  When file locks do not work, it is
-possible for two users to make changes simultaneously, but Emacs can
-still warn the user who saves second.  Also, the detection of
-modification of a buffer visiting a file changed on disk catches some
-cases of simultaneous editing; see @ref{Modification Time}.
+  File locks are not completely reliable when multiple machines can
+share file systems.  When file locks do not work, it is possible for two
+users to make changes simultaneously, but Emacs can still warn the user
+who saves second.  Also, the detection of modification of a buffer
+visiting a file changed on disk catches some cases of simultaneous
+editing; see @ref{Modification Time}.
 
 @defun file-locked-p filename
   This function returns @code{nil} if the file @var{filename} is not
@@ -1032,18 +1012,12 @@ For example, here are the file attributes for @file{files.texi}:
 @example
 @group
 (file-attributes "files.texi")
-     @result{}  (nil 
-          1 
-          2235 
-          75 
+     @result{}  (nil 1 2235 75 
           (8489 20284) 
           (8489 20284) 
           (8489 20285)
-          14906 
-          "-rw-rw-rw-" 
-          nil 
-          129500
-          -32252)
+          14906 "-rw-rw-rw-" 
+          nil 129500 -32252)
 @end group
 @end example
 
@@ -1614,7 +1588,7 @@ form.
 @defvar default-directory
 The value of this buffer-local variable is the default directory for the
 current buffer.  It should be an absolute directory name; it may start
-with @samp{~}.  This variable is local in every buffer.
+with @samp{~}.  This variable is buffer-local in every buffer.
 
 @code{expand-file-name} uses the default directory when its second
 argument is @code{nil}.
@@ -1651,8 +1625,8 @@ the user's home directory name, has value @samp{/xcssun/users/rms}.
 @end group
 @end example
 
-If a @samp{~} or a @samp{/} appears following a @samp{/}, after
-substitution, everything before the following @samp{/} is discarded:
+After substitution, if a @samp{~} or a @samp{/} appears following a
+@samp{/}, everything before the following @samp{/} is discarded:
 
 @example
 @group
@@ -1996,18 +1970,21 @@ Here are the operations that a magic file name handler gets to handle:
 
 @noindent
 @code{add-name-to-file}, @code{copy-file}, @code{delete-directory},
-@code{delete-file},@*
+@code{delete-file},
 @code{diff-latest-backup-file},
 @code{directory-file-name},
-@code{directory-files},@*
+@code{directory-files},
 @code{dired-call-process},
 @code{dired-compress-file}, @code{dired-uncache},
-@code{expand-file-name},@*
-@code{file-accessible-directory-p},
-@code{file-attributes}, @code{file-directory-p},@*
-@code{file-executable-p}, @code{file-exists-p}, @code{file-local-copy},
-@code{file-modes}, @code{file-name-all-completions},
-@code{file-name-as-directory}, @code{file-name-completion},@*
+@code{expand-file-name},
+@code{file-accessible-directory-p},@*
+@code{file-attributes},
+@code{file-directory-p},
+@code{file-executable-p}, @code{file-exists-p},@*
+@code{file-local-copy},
+@code{file-modes}, @code{file-name-all-completions},@*
+@code{file-name-as-directory},
+@code{file-name-completion},
 @code{file-name-directory},
 @code{file-name-nondirectory},
 @code{file-name-sans-versions}, @code{file-newer-than-file-p},
@@ -2015,15 +1992,16 @@ Here are the operations that a magic file name handler gets to handle:
 @code{file-readable-p}, @code{file-regular-p}, @code{file-symlink-p},
 @code{file-truename}, @code{file-writable-p},
 @code{find-backup-file-name},
-@code{get-file-buffer},
-@code{insert-directory},@*
+@code{get-file-buffer},@*
+@code{insert-directory},
 @code{insert-file-contents},
 @code{load}, @code{make-directory},
 @code{make-symbolic-link}, @code{rename-file}, @code{set-file-modes},
-@code{set-visited-file-modtime}, @code{shell-command}.
-@code{unhandled-file-name-directory},@*
+@code{set-visited-file-modtime}, @code{shell-command}.@*
+@code{unhandled-file-name-directory},
 @code{vc-registered},
-@code{verify-visited-file-modtime}, @code{write-region}.
+@code{verify-visited-file-modtime},@*
+@code{write-region}.
 
 Handlers for @code{insert-file-contents} typically need to clear the
 buffer's modified flag, with @code{(set-buffer-modified-p nil)}, if the
@@ -2140,10 +2118,13 @@ A regular expression which is used to recognize files represented in
 this format.
 
 @item from-fn
-A function or shell command to decode data in this format (to convert
+A shell command or function to decode data in this format (to convert
 file data into the usual Emacs data representation).
 
-If @var{from-fn} is a function, it is called with two args, @var{begin}
+A shell command is represented as a string; Emacs runs the command as a
+filter to perform the conversion.
+
+If @var{from-fn} is a function, it is called with two arguments, @var{begin}
 and @var{end}, which specify the part of the buffer it should convert.
 It should convert the text by editing it in place.  Since this can
 change the length of the text, @var{from-fn} should return the modified
@@ -2153,17 +2134,14 @@ One responsibility of @var{from-fn} is to make sure that the beginning
 of the file no longer matches @var{regexp}.  Otherwise it is likely to
 get called again.
 
-If @var{from-fn} is a string, it is a shell command; Emacs runs the
-command as a filter to perform the conversion.
-
 @item to-fn
-A function or shell command to encode data in this format (to convert
-the usual Emacs data representation into this format).
+A shell command or function to encode data in this format---that is, to
+convert the usual Emacs data representation into this format.
 
 If @var{to-fn} is a string, it is a shell command; Emacs runs the
 command as a filter to perform the conversion.
 
-If @var{to-fn} is a function, it is called with two args, @var{begin}
+If @var{to-fn} is a function, it is called with two arguments, @var{begin}
 and @var{end}, which specify the part of the buffer it should convert.
 There are two ways it can do the conversion:
 
@@ -2209,7 +2187,7 @@ buffer-local variable @code{buffer-file-format}.
 @defvar buffer-file-format
 This variable states the format of the visited file.  More precisely,
 this is a list of the file format names that were decoded in the course
-of visiting the current buffer's file.  It is always local in all
+of visiting the current buffer's file.  It is always buffer-local in all
 buffers.
 @end defvar
 
@@ -2234,7 +2212,7 @@ The argument @var{format} is a list of format names.  If @var{format} is
 @key{RET} for @var{format} specifies @code{nil}.
 @end deffn
 
-@deffn format-insert-file file format %optional beg end
+@deffn Command format-insert-file file format &optional beg end
 This command inserts the contents of file @var{file}, converting it
 according to format @var{format}.  If @var{beg} and @var{end} are
 non-@code{nil}, they specify which part of the file to read, as in
@@ -2254,62 +2232,5 @@ This variable specifies the format to use for auto-saving.  Its value is
 a list of format names, just like the value of
 @code{buffer-file-format}; but it is used instead of
 @code{buffer-file-format} for writing auto-save files.  This variable
-is always local in all buffers.
-@end defvar
-
-@node Files and MS-DOS
-@section Files and MS-DOS
-@cindex MS-DOS file types
-@cindex file types on MS-DOS
-@cindex text files and binary files
-@cindex binary files and text files
-@cindex Windows file types
-
-@c ??? This needs to be updated.
-
-  Emacs on MS-DOS and on Windows NT or 95 makes a distinction between
-text files and binary files.  This is necessary because ordinary text
-files on MS-DOS use a two character sequence between lines:
-carriage-return and linefeed (@sc{crlf}).  Emacs expects just a newline
-character (a linefeed) between lines.  When Emacs reads or writes a text
-file on MS-DOS, it needs to convert the line separators.  This means it
-needs to know which files are text files and which are binary.  It makes
-this decision when visiting a file, and records the decision in the
-variable @code{buffer-file-type} for use when the file is saved.
-
-  @xref{MS-DOS Subprocesses}, for a related feature for subprocesses.
-
-@defvar buffer-file-type
-This variable, automatically local in each buffer, records the file type
-of the buffer's visited file.  The value is @code{nil} for text,
-@code{t} for binary.
+is always buffer-local in all buffers.
 @end defvar
-
-@defun find-buffer-file-type filename
-This function determines whether file @var{filename} is a text file
-or a binary file.  It returns @code{nil} for text, @code{t} for binary.
-@end defun
-
-@defopt file-name-buffer-file-type-alist
-This variable holds an alist for distinguishing text files from binary
-files.  Each element has the form (@var{regexp} . @var{type}), where
-@var{regexp} is matched against the file name, and @var{type} may be
-@code{nil} for text, @code{t} for binary, or a function to call to
-compute which.  If it is a function, then it is called with a single
-argument (the file name) and should return @code{t} or @code{nil}.
-@end defopt
-
-@defopt default-buffer-file-type
-This variable specifies the default file type for files whose names
-don't indicate anything in particular.  Its value should be @code{nil}
-for text, or @code{t} for binary.
-@end defopt
-
-@deffn Command find-file-text filename
-Like @code{find-file}, but treat the file as text regardless of its name.
-@end deffn
-
-@deffn Command find-file-binary filename
-Like @code{find-file}, but treat the file as binary regardless of its
-name.
-@end deffn
diff --git a/lispref/frames.texi b/lispref/frames.texi
index 0309abc7a1d..b5c641d891e 100644
--- a/lispref/frames.texi
+++ b/lispref/frames.texi
@@ -18,10 +18,10 @@ horizontally into smaller windows.
 @dfn{terminal frame}.  If you create additional ones, Emacs displays
 one and only one at any given time---on the terminal screen, of course.
 
-  When Emacs communicates directly with an X server, it does not have a
-terminal frame; instead, it starts with a single @dfn{X window frame}.
-It can display multiple X window frames at the same time, each in its
-own X window.
+  When Emacs communicates directly with a supported window system, such
+as X Windows, it does not have a terminal frame; instead, it starts with
+a single @dfn{window frame}, but you can create more, and Emacs can
+display several such frames at once as is usual for window systems.
 
 @defun framep object
 This predicate returns @code{t} if @var{object} is a frame, and
@@ -30,7 +30,7 @@ This predicate returns @code{t} if @var{object} is a frame, and
 
 @menu
 * Creating Frames::             Creating additional frames.
-* Multiple Displays::           Creating frames on other X displays.
+* Multiple Displays::           Creating frames on other displays.
 * Frame Parameters::            Controlling frame size, position, font, etc.
 * Frame Titles::                Automatic updating of frame titles.
 * Deleting Frames::             Frames last until explicitly deleted.
@@ -40,7 +40,7 @@ This predicate returns @code{t} if @var{object} is a frame, and
 * Minibuffers and Frames::      How a frame finds the minibuffer to use.
 * Input Focus::                 Specifying the selected frame.
 * Visibility of Frames::        Frames may be visible or invisible, or icons.
-* Raising and Lowering::        Raising a frame makes it hide other X windows;
+* Raising and Lowering::        Raising a frame makes it hide other windows;
                                   lowering it makes the others hide them.
 * Frame Configurations::        Saving the state of all frames.
 * Mouse Tracking::              Getting events that say when the mouse moves.
@@ -48,7 +48,7 @@ This predicate returns @code{t} if @var{object} is a frame, and
 * Pop-Up Menus::                Displaying a menu for the user to select from.
 * Dialog Boxes::                Displaying a box to ask yes or no.
 * Pointer Shapes::              Specifying the shape of the mouse pointer.
-* X Selections::                Transferring text to and from other X clients.
+* Window System Selections::    Transferring text to and from other X clients.
 * Font Names::                  Looking up font names.
 * Color Names::                 Getting the definitions of color names.
 * Resources::                   Getting resource values from the server.
@@ -63,16 +63,17 @@ This predicate returns @code{t} if @var{object} is a frame, and
 To create a new frame, call the function @code{make-frame}.
 
 @defun make-frame &optional alist
-This function creates a new frame.  If you are using X, it makes
-an X window frame; otherwise, it makes a terminal frame.
+This function creates a new frame.  If you are using a supported window
+system, it makes a window frame; otherwise, it makes a terminal frame.
 
 The argument is an alist specifying frame parameters.  Any parameters
 not mentioned in @var{alist} default according to the value of the
 variable @code{default-frame-alist}; parameters not specified even there
-default from the standard X defaults file and X resources.
+default from the standard X resources or whatever is used instead on
+your system.
 
 The set of possible parameters depends in principle on what kind of
-window system Emacs uses to display its frames.  @xref{X Frame
+window system Emacs uses to display its frames.  @xref{Window Frame
 Parameters}, for documentation of individual parameters you can specify.
 @end defun
 
@@ -95,7 +96,7 @@ frame just created.
 @cindex multiple X terminals
 @cindex displays, multiple
 
-  A single Emacs can talk to more than one X Windows display.
+  A single Emacs can talk to more than one X Window display.
 Initially, Emacs uses just one display---the one chosen with the
 @code{DISPLAY} environment variable or with the @samp{--display} option
 (@pxref{Initial Options,,, emacs, The GNU Emacs Manual}).  To connect to
@@ -108,7 +109,8 @@ have values local to the current terminal (that is, the terminal
 corresponding to the currently selected frame): these are
 @code{default-minibuffer-frame}, @code{defining-kbd-macro},
 @code{last-kbd-macro}, and @code{system-key-alist}.  These variables are
-always terminal-local and can never be buffer-local.
+always terminal-local and can never be buffer-local or frame-local
+(@pxref{Buffer-Local Variables}).
 
   A single X server can handle more than one screen.  A display name
 @samp{@var{host}.@var{server}.@var{screen}} has three parts; the last
@@ -163,12 +165,13 @@ uses.
 
 Frame parameters exist for the sake of window systems.  A terminal frame
 has a few parameters, mostly for compatibility's sake; only the height,
-width and @code{buffer-predicate} parameters really do something.
+width, @code{name}, @code{title}, @code{buffer-list} and
+@code{buffer-predicate} parameters do something special.
 
 @menu
 * Parameter Access::       How to change a frame's parameters.
 * Initial Parameters::     Specifying frame parameters when you make a frame.
-* X Frame Parameters::     List of frame parameters.
+* Window Frame Parameters:: List of frame parameters for window systems.
 * Size and Position::      Changing the size and position of a frame.
 @end menu
 
@@ -199,7 +202,7 @@ by setting @code{initial-frame-alist} in your @file{.emacs} file.
 
 @defvar initial-frame-alist
 This variable's value is an alist of parameter values used when creating
-the initial X window frame.  You can set this variable to specify the
+the initial window frame.  You can set this variable to specify the
 appearance of the initial frame without altering subsequent frames.
 Each element has the form:
 
@@ -239,8 +242,9 @@ to the parameters for the main initial frame.
 
 @defvar default-frame-alist
 This is an alist specifying default values of frame parameters for all
-Emacs frames---the first frame, and subsequent frames.  In many cases,
-you can get the same results by means of X resources.
+Emacs frames---the first frame, and subsequent frames.  When using the X
+Window System, you can get the same results by means of X resources
+in many cases.
 @end defvar
 
 See also @code{special-display-frame-alist}, in @ref{Choosing Window}.
@@ -251,28 +255,34 @@ exception is @samp{-geometry}, which adds the specified position to
 @code{initial-frame-alist} instead.  @xref{Command Arguments,,, emacs,
 The GNU Emacs Manual}.
 
-@node X Frame Parameters
-@subsection X Window Frame Parameters
+@node Window Frame Parameters
+@subsection Window Frame Parameters
 
 Just what parameters a frame has depends on what display mechanism it
-uses.  Here is a table of the parameters of an X window frame; of these,
-@code{name}, @code{height}, @code{width}, and @code{buffer-predicate}
-provide meaningful information in non-X frames.
+uses.  Here is a table of the parameters that have special meanings in a
+window frame; of these, @code{name}, @code{title}, @code{height},
+@code{width}, @code{buffer-list} and @code{buffer-predicate} provide
+meaningful information in terminal frames.
 
 @table @code
+@item title
+If a frame has a non-@code{nil} title, it appears in the window system's
+border for the frame, and also in the mode line of windows in that frame
+if @code{mode-line-frame-identification} uses @samp{%F}
+(@pxref{%-Constructs}).  This is normally the case when Emacs is not
+using a window system, and can only display one frame at a time.
+@xref{Frame Titles}.
+
 @item name
-The name of the frame.  Most window managers display the frame's name in
-the frame's border, at the top of the frame.  If you don't specify a
-name, and you have more than one frame, Emacs sets the frame name based
-on the buffer displayed in the frame's selected window.
+The name of the frame.  The frame name serves as a default for the frame
+title, if the @code{title} parameter is unspecified or @code{nil}.  If
+you don't specify a name, Emacs sets the frame name automatically
+(@pxref{Frame Titles}).
 
 If you specify the frame name explicitly when you create the frame, the
 name is also used (instead of the name of the Emacs executable) when
 looking up X resources for the frame.
 
-Since a non-window terminal can display only one frame at a time, the
-frame name appears in the mode line.
-
 @item display
 The display on which to open this frame.  It should be a string of the
 form @code{"@var{host}:@var{dpy}.@var{screen}"}, just like the
@@ -287,8 +297,9 @@ negative @var{pos} value.
 A negative number @minus{}@var{pos}, or a list of the form @code{(-
 @var{pos})}, actually specifies the position of the right edge of the
 window with respect to the right edge of the screen.  A positive value
-of @var{pos} counts toward the left.  If the parameter is a negative
-integer @minus{}@var{pos} then @var{pos} is positive!
+of @var{pos} counts toward the left.  @strong{Reminder:} if the
+parameter is a negative integer @minus{}@var{pos}, then @var{pos} is
+positive.
 
 Some window managers ignore program-specified positions.  If you want to
 be sure the position you specify is not ignored, specify a
@@ -303,8 +314,9 @@ negative @var{pos} value.
 A negative number @minus{}@var{pos}, or a list of the form @code{(-
 @var{pos})}, actually specifies the position of the bottom edge of the
 window with respect to the bottom edge of the screen.  A positive value
-of @var{pos} counts toward the top.  If the parameter is a negative
-integer @minus{}@var{pos} then @var{pos} is positive!
+of @var{pos} counts toward the top.  @strong{Reminder:} if the
+parameter is a negative integer @minus{}@var{pos}, then @var{pos} is
+positive.
 
 Some window managers ignore program-specified positions.  If you want to
 be sure the position you specify is not ignored, specify a
@@ -348,7 +360,7 @@ The width of the frame contents, in characters.  (To get the height in
 pixels, call @code{frame-pixel-width}; see @ref{Size and Position}.)
 
 @item window-id
-The number of the X window for the frame.
+The number of the window-system window used by the frame.
 
 @item minibuffer
 Whether this frame has its own minibuffer.  The value @code{t} means
@@ -360,12 +372,13 @@ the new frame uses that minibuffer.
 The buffer-predicate function for this frame.  The function
 @code{other-buffer} uses this predicate (from the selected frame) to
 decide which buffers it should consider, if the predicate is not
-@code{nil}.  It calls the predicate with one arg, a buffer, once for
+@code{nil}.  It calls the predicate with one argument, a buffer, once for
 each buffer; if the predicate returns a non-@code{nil} value, it
 considers that buffer.
 
 @item buffer-list
-A list of buffers recently selected in this frame.
+A list of buffers that have been selected in this frame,
+ordered most-recently-selected first.
 
 @item font
 The name of the font for displaying text in the frame.  This is a
@@ -401,8 +414,8 @@ The name to use in the icon for this frame, when and if the icon
 appears.  If this is @code{nil}, the frame's title is used.
 
 @item foreground-color
-The color to use for the image of a character.  This is a string; the X
-server defines the meaningful color names.
+The color to use for the image of a character.  This is a string; the
+window system defines the meaningful color names.
 
 @item background-color
 The color to use for the background of characters.
@@ -507,7 +520,7 @@ Size}.
 
 @defun x-parse-geometry geom
 @cindex geometry specification
-The function @code{x-parse-geometry} converts a standard X windows
+The function @code{x-parse-geometry} converts a standard X Windows
 geometry string to an alist that you can use as part of the argument to
 @code{make-frame}.
 
@@ -560,24 +573,25 @@ the second.
 @node Frame Titles
 @section Frame Titles
 
-Every frame has a title; most window managers display the frame title at
-the top of the frame.  You can specify an explicit title with the
-@code{name} frame property.  But normally you don't specify this
-explicitly, and Emacs computes the title automatically.
+  Every frame has a @code{name} parameter; this serves as the default
+for the frame title which window systems typically display at the top of
+the frame.  You can specify a name explicitly by setting the @code{name}
+frame property.
 
-Emacs computes the frame title based on a template stored in the
-variable @code{frame-title-format}.
+  Normally you don't specify the name explicitly, and Emacs computes the
+frame name automatically based on a template stored in the variable
+@code{frame-title-format}.  Emacs recomputes the name each time the
+frame is redisplayed.
 
 @defvar frame-title-format
-This variable specifies how to compute a title for a frame
-when you have not explicitly specified one.
-
-The variable's value is actually a mode line construct, just like
-@code{mode-line-format}.  @xref{Mode Line Data}.
+This variable specifies how to compute a name for a frame when you have
+not explicitly specified one.  The variable's value is actually a mode
+line construct, just like @code{mode-line-format}.  @xref{Mode Line
+Data}.
 @end defvar
 
 @defvar icon-title-format
-This variable specifies how to compute the title for an iconified frame,
+This variable specifies how to compute the name for an iconified frame,
 when you have not explicitly specified the frame title.  This title
 appears in the icon itself.
 @end defvar
@@ -694,11 +708,11 @@ This function returns the window on @var{frame} that is selected within
 @var{frame}.
 @end defun
 
-Conversely, selecting a window for Emacs with @code{select-window} also
+  Conversely, selecting a window for Emacs with @code{select-window} also
 makes that window selected within its frame.  @xref{Selecting Windows}.
 
-Another function that (usually) returns one of the windows in a frame is
-@code{minibuffer-window}.  @xref{Minibuffer Misc}.
+  Another function that (usually) returns one of the windows in a given
+frame is @code{minibuffer-window}.  @xref{Minibuffer Misc}.
 
 @node Minibuffers and Frames
 @section Minibuffers and Frames
@@ -736,23 +750,23 @@ window always resides on the selected frame.
 This function returns the selected frame.
 @end defun
 
-The X server normally directs keyboard input to the X window that the
-mouse is in.  Some window managers use mouse clicks or keyboard events
-to @dfn{shift the focus} to various X windows, overriding the normal
-behavior of the server.
+Some window systems and window managers direct keyboard input to the
+window object that the mouse is in; others require explicit clicks or
+commands to @dfn{shift the focus} to various window objects.  Either
+way, Emacs automatically keeps track of which frame has the focus.
 
-Lisp programs can switch frames ``temporarily'' by calling
-the function @code{select-frame}.  This does not override the window
-manager; rather, it escapes from the window manager's control until
-that control is somehow reasserted.
+Lisp programs can also switch frames ``temporarily'' by calling the
+function @code{select-frame}.  This does not alter the window system's
+concept of focus; rather, it escapes from the window manager's control
+until that control is somehow reasserted.
 
-When using a text-only terminal, there is no window manager; therefore,
-@code{switch-frame} is the only way to switch frames, and the effect
-lasts until overridden by a subsequent call to @code{switch-frame}.
-Only the selected terminal frame is actually displayed on the terminal.
-Each terminal screen except for the initial one has a number, and the
-number of the selected frame appears in the mode line after the word
-@samp{Emacs} (@pxref{Mode Line Variables}).
+When using a text-only terminal, only the selected terminal frame is
+actually displayed on the terminal.  @code{switch-frame} is the only way
+to switch frames, and the change lasts until overridden by a subsequent
+call to @code{switch-frame}.  Each terminal screen except for the
+initial one has a number, and the number of the selected frame appears
+in the mode line after the word @samp{Emacs} (@pxref{Mode Line
+Variables}).
 
 @c ??? This is not yet implemented properly.
 @defun select-frame frame
@@ -762,10 +776,10 @@ the next time the user does something to select a different frame, or
 until the next time this function is called.
 @end defun
 
-Emacs cooperates with the X server and the window managers by arranging
-to select frames according to what the server and window manager ask
-for.  It does so by generating a special kind of input event, called a
-@dfn{focus} event.  The command loop handles a focus event by calling
+Emacs cooperates with the window system by arranging to select frames as
+the server and window manager request.  It does so by generating a
+special kind of input event, called a @dfn{focus} event, when
+appropriate.  The command loop handles a focus event by calling
 @code{handle-switch-frame}.  @xref{Focus Events}.
 
 @deffn Command handle-switch-frame frame
@@ -806,6 +820,14 @@ The redirection lasts until @code{redirect-frame-focus} is called to
 change it.
 @end defun
 
+@tindex focus-follows-mouse
+@defopt focus-follows-mouse
+This option is how you inform Emacs whether the window manager transfers
+focus when the user moves the mouse.  Non-@code{nil} says that it does.
+When this is so, the command @code{other-frame} moves the mouse to a
+position consistent with the new selected frame.
+@end defopt
+
 @node Visibility of Frames
 @section Visibility of Frames
 @cindex visible frame
@@ -813,7 +835,7 @@ change it.
 @cindex iconified frame
 @cindex frame visibility
 
-An X window frame may be @dfn{visible}, @dfn{invisible}, or
+A window frame may be @dfn{visible}, @dfn{invisible}, or
 @dfn{iconified}.  If it is visible, you can see its contents.  If it is
 iconified, the frame's contents do not appear on the screen, but an icon
 does.  If the frame is invisible, it doesn't show on the screen, not
@@ -844,7 +866,7 @@ This returns the visibility status of frame @var{frame}.  The value is
 @end defun
 
   The visibility status of a frame is also available as a frame
-parameter.  You can read or change it as such.  @xref{X Frame
+parameter.  You can read or change it as such.  @xref{Window Frame
 Parameters}.
 
   The user can iconify and deiconify frames with the window manager.
@@ -855,23 +877,23 @@ changes.  @xref{Misc Events}.
 @node Raising and Lowering
 @section Raising and Lowering Frames
 
-  The X Window System uses a desktop metaphor.  Part of this metaphor is
+  Most window systems use a desktop metaphor.  Part of this metaphor is
 the idea that windows are stacked in a notional third dimension
 perpendicular to the screen surface, and thus ordered from ``highest''
-to ``lowest''.  Where two X windows overlap, the one higher up covers
-the one underneath.  Even an X window at the bottom of the stack can be
-seen if no other X window overlaps it.
+to ``lowest''.  Where two windows overlap, the one higher up covers
+the one underneath.  Even a window at the bottom of the stack can be
+seen if no other window overlaps it.
 
 @cindex raising a frame
 @cindex lowering a frame
-  An X window's place in this ordering is not fixed; in fact, users tend
-to change the order frequently.  @dfn{Raising} an X window means moving
-it ``up'', to the top of the stack.  @dfn{Lowering} an X window means
+  A window's place in this ordering is not fixed; in fact, users tend
+to change the order frequently.  @dfn{Raising} a window means moving
+it ``up'', to the top of the stack.  @dfn{Lowering} a window means
 moving it to the bottom of the stack.  This motion is in the notional
-third dimension only, and does not change the position of the X window
+third dimension only, and does not change the position of the window
 on the screen.
 
-You can raise and lower Emacs's X windows with these functions:
+  You can raise and lower Emacs frame Windows with these functions:
 
 @deffn Command raise-frame frame
 This function raises frame @var{frame}.
@@ -888,7 +910,7 @@ that the minibuffer window is in.
 
 You can also enable auto-raise (raising automatically when a frame is
 selected) or auto-lower (lowering automatically when it is deselected)
-for any frame using frame parameters.  @xref{X Frame Parameters}.
+for any frame using frame parameters.  @xref{Window Frame Parameters}.
 
 @node Frame Configurations
 @section Frame Configurations
@@ -896,6 +918,7 @@ for any frame using frame parameters.  @xref{X Frame Parameters}.
 
   A @dfn{frame configuration} records the current arrangement of frames,
 all their properties, and the window configuration of each one.
+(@xref{Window Configurations}.)
 
 @defun current-frame-configuration
 This function returns a frame configuration list that describes
@@ -925,12 +948,15 @@ mouse forever---only until some other event, such as the release of a
 button.
 
 @defspec track-mouse body@dots{}
-Execute @var{body}, meanwhile generating input events for mouse motion.
-The code in @var{body} can read these events with @code{read-event} or
-@code{read-key-sequence}.  @xref{Motion Events}, for the format of mouse
-motion events.
+This special form executes @var{body}, with generation of mouse motion
+events enabled.  Typically @var{body} would use @code{read-event} to
+read the motion events and modify the display accordingly.  @xref{Motion
+Events}, for the format of mouse motion events.
 
 The value of @code{track-mouse} is that of the last form in @var{body}.
+You should design @var{body} to return when it sees the up-event that
+indicates the release of the button, or whatever kind of event means
+it is time to stop tracking.
 @end defspec
 
 The usual purpose of tracking mouse motion is to indicate on the screen
@@ -947,7 +973,7 @@ Lisp-level mouse tracking.
 
 These functions change the screen appearance instantaneously.  The
 effect is transient, only until the next ordinary Emacs redisplay.  That
-is ok for mouse tracking, since it doesn't make sense for mouse tracking
+is OK for mouse tracking, since it doesn't make sense for mouse tracking
 to change the text, and the body of @code{track-mouse} normally reads
 the events itself and does not do redisplay.
 
@@ -1015,8 +1041,8 @@ characters.  These coordinates are not required to be within the frame.
 @node Pop-Up Menus
 @section Pop-Up Menus
 
-  When using X windows, a Lisp program can pop up a menu which the
-user can choose from with the mouse.
+  When using a window system, a Lisp program can pop up a menu so that
+the user can choose an alternative with the mouse.
 
 @defun x-popup-menu position menu
 This function displays a pop-up menu and returns an indication of
@@ -1083,13 +1109,13 @@ the menu keymap as necessary.
 @section Dialog Boxes
 @cindex dialog boxes
 
-  A dialog box is a variant of a pop-up menu.  It looks a little
-different (if Emacs uses an X toolkit), it always appears in the center
-of a frame, and it has just one level and one pane.  The main use of
-dialog boxes is for asking questions that the user can answer with
-``yes'', ``no'', and a few other alternatives.  The functions
-@code{y-or-n-p} and @code{yes-or-no-p} use dialog boxes instead of the
-keyboard, when called from commands invoked by mouse clicks.
+  A dialog box is a variant of a pop-up menu---it looks a little
+different, it always appears in the center of a frame, and it has just
+one level and one pane.  The main use of dialog boxes is for asking
+questions that the user can answer with ``yes'', ``no'', and a few other
+alternatives.  The functions @code{y-or-n-p} and @code{yes-or-no-p} use
+dialog boxes instead of the keyboard, when called from commands invoked
+by mouse clicks.
 
 @defun x-popup-dialog position contents
 This function displays a pop-up dialog box and returns an indication of
@@ -1121,9 +1147,9 @@ Dialog boxes always appear in the center of a frame; the argument
 @code{x-popup-menu}, but the precise coordinates don't matter; only the
 frame matters.
 
-If your Emacs executable does not use an X toolkit, then it cannot
-display a real dialog box; so instead it displays the same items in a
-pop-up menu in the center of the frame.
+In some configurations, Emacs cannot display a real dialog box; so
+instead it displays the same items in a pop-up menu in the center of the
+frame.
 @end defun
 
 @node Pointer Shapes
@@ -1132,7 +1158,7 @@ pop-up menu in the center of the frame.
 @cindex mouse pointer shape
 
   These variables specify which shape to use for the mouse pointer in
-various situations:
+various situations, when using the X Window System:
 
 @table @code
 @item x-pointer-shape
@@ -1149,14 +1175,14 @@ is over mouse-sensitive text.
   These variables affect newly created frames.  They do not normally
 affect existing frames; however, if you set the mouse color of a frame,
 that also updates its pointer shapes based on the current values of
-these variables.  @xref{X Frame Parameters}.
+these variables.  @xref{Window Frame Parameters}.
 
   The values you can use, to specify either of these pointer shapes, are
 defined in the file @file{lisp/term/x-win.el}.  Use @kbd{M-x apropos
 @key{RET} x-pointer @key{RET}} to see a list of them.
 
-@node X Selections
-@section X Selections
+@node Window System Selections
+@section Window System Selections
 @cindex selection (for X windows)
 
 The X server records a set of @dfn{selections} which permit transfer of
@@ -1221,9 +1247,9 @@ like the way successive kills in Emacs move down the kill ring.
 
 @defun x-list-font pattern &optional face frame maximum
 This function returns a list of available font names that match
-@var{pattern}.  If the optional arguments FACE and FRAME are specified,
-then the list is limited to fonts that are the same size as @var{face}
-currently is on @var{frame}.
+@var{pattern}.  If the optional arguments @var{face} and @var{frame} are
+specified, then the list is limited to fonts that are the same size as
+@var{face} currently is on @var{frame}.
 
 The argument @var{pattern} should be a string, perhaps with wildcard
 characters: the @samp{*} character matches any substring, and the
diff --git a/lispref/functions.texi b/lispref/functions.texi
index 4ec73a1445f..b770ac39f7c 100644
--- a/lispref/functions.texi
+++ b/lispref/functions.texi
@@ -112,8 +112,8 @@ byte compiler.  @xref{Byte-Code Type}.
 
 @tindex functionp
 @defun functionp object
-This function returns @code{t} if @var{object} is any kind of function;
-that is, anything that could be called as a function.
+This function returns @code{t} if @var{object} is any kind of function,
+or a special form or macro.
 @end defun
 
 @defun subrp object
@@ -386,7 +386,7 @@ facilities.  @xref{Documentation}, for how the @var{documentation-string} is
 accessed.
 
   It is a good idea to provide documentation strings for all the
-functions in your program, even those that are only called from within
+functions in your program, even those that are called only from within
 your program.  Documentation strings are like comments, except that they
 are easier to access.
 
@@ -419,7 +419,7 @@ as the return value and as the documentation.
   In most computer languages, every function has a name; the idea of a
 function without a name is nonsensical.  In Lisp, a function in the
 strictest sense has no name.  It is simply a list whose first element is
-@code{lambda}, or a primitive subr-object.
+@code{lambda}, a byte-code function object, or a primitive subr-object.
 
   However, a symbol can serve as the name of a function.  This happens
 when you put the function in the symbol's @dfn{function cell}
@@ -580,7 +580,8 @@ name it calls is written in your program.  This means that you choose
 which function to call, and how many arguments to give it, when you
 write the program.  Usually that's just what you want.  Occasionally you
 need to compute at run time which function to call.  To do that, use the
-functions @code{funcall} and @code{apply}.
+function @code{funcall}.  When you also need to determine at run time
+how may arguments to pass, use @code{apply}.
 
 @defun funcall function &rest arguments
 @code{funcall} calls @var{function} with @var{arguments}, and returns
@@ -690,15 +691,19 @@ This function ignores any arguments and returns @code{nil}.
 list or other collection.  Emacs Lisp has several such functions;
 @code{mapcar} and @code{mapconcat}, which scan a list, are described
 here.  @xref{Creating Symbols}, for the function @code{mapatoms} which
-maps over the symbols in an obarray.  @xref{Char-Tables}, for the
-function @code{map-char-table}, which maps over the elements in a
-char-table.
+maps over the symbols in an obarray.
+
+  These mapping functions do not allow char-tables because a char-table
+is a sparse array whose nominal range of indices is very large.  To map
+over a char-table in a way that deals properly with its sparse nature,
+use the function @code{map-char-table} (@pxref{Char-Tables}).
 
 @defun mapcar function sequence
 @code{mapcar} applies @var{function} to each element of @var{sequence}
 in turn, and returns a list of the results.
 
-The argument @var{sequence} may be a list, a vector, or a string.  The
+The argument @var{sequence} can be any kind of sequence except a
+char-table; that is, a list, a vector, a bool-vector, or a string.  The
 result is always a list.  The length of the result is the same as the
 length of @var{sequence}.
 
@@ -720,14 +725,14 @@ length of @var{sequence}.
 @end group
 
 @group
-(defun mapcar* (f &rest args)
+(defun mapcar* (function &rest args)
   "Apply FUNCTION to successive cars of all ARGS.
 Return the list of results."
   ;; @r{If no list is exhausted,}
   (if (not (memq 'nil args))              
-      ;; @r{apply function to @sc{CAR}s.}
-      (cons (apply f (mapcar 'car args))  
-            (apply 'mapcar* f             
+      ;; @r{apply function to @sc{car}s.}
+      (cons (apply function (mapcar 'car args))  
+            (apply 'mapcar* function             
                    ;; @r{Recurse for rest of elements.}
                    (mapcar 'cdr args)))))
 @end group
@@ -747,7 +752,9 @@ Between each pair of result strings, @code{mapconcat} inserts the string
 other suitable punctuation.
 
 The argument @var{function} must be a function that can take one
-argument and return a string.
+argument and return a string.  The argument @var{sequence} can be any
+kind of sequence except a char-table; that is, a list, a vector, a
+bool-vector, or a string.
   
 @smallexample
 @group
@@ -823,7 +830,7 @@ uses a function as its third argument:
 
 @noindent
 Here we define a function that uses @code{change-property},
-passing a function that doubles its argument:
+passing it a function to double a number:
 
 @example
 @group
@@ -978,15 +985,18 @@ There are three normal uses of this function:
 
 @itemize @bullet
 @item
-Copying one symbol's function definition to another.  (In other words,
-making an alternate name for a function.)
+Copying one symbol's function definition to another---in other words,
+making an alternate name for a function.  (If you think of this as the
+definition of the new name, you should use @code{defalias} instead of
+@code{fset}; see @ref{Defining Functions}.)
 
 @item
 Giving a symbol a function definition that is not a list and therefore
 cannot be made with @code{defun}.  For example, you can use @code{fset}
 to give a symbol @code{s1} a function definition which is another symbol
 @code{s2}; then @code{s1} serves as an alias for whatever definition
-@code{s2} presently has.
+@code{s2} presently has.  (Once again use @code{defalias} instead of
+@code{fset} if you think of this as the definition of @code{s1}.)
 
 @item
 In constructs for defining or altering functions.  If @code{defun}
@@ -994,21 +1004,17 @@ were not a primitive, it could be written in Lisp (as a macro) using
 @code{fset}.
 @end itemize
 
-Here are examples of the first two uses:
+Here are examples of these uses:
 
 @example
 @group
-;; @r{Give @code{first} the same definition @code{car} has.}
-(fset 'first (symbol-function 'car))
-     @result{} #<subr car>
-@end group
-@group
-(first '(1 2 3))
-     @result{} 1
+;; @r{Save @code{foo}'s definition in @code{old-foo}.}
+(fset 'old-foo (symbol-function 'foo))
 @end group
 
 @group
 ;; @r{Make the symbol @code{car} the function definition of @code{xfirst}.}
+;; @r{(Most likely, @code{defalias} would be better than @code{fset} here.)}
 (fset 'xfirst 'car)
      @result{} car
 @end group
@@ -1030,10 +1036,14 @@ Here are examples of the first two uses:
 (fset 'kill-two-lines "\^u2\^k")
      @result{} "\^u2\^k"
 @end group
-@end example
 
-See also the related function @code{defalias}, in @ref{Defining
-Functions}.
+@group
+;; @r{Here is a function that alters other functions.}
+(defun copy-function-definition (new old)
+  "Define NEW with the same function definition as OLD."
+  (fset new (symbol-function old)))
+@end group
+@end example
 @end defun
 
   When writing a function that extends a previously defined function,
@@ -1058,7 +1068,8 @@ proper results.  The only way to avoid this problem is to make sure the
 file is loaded before moving aside the old definition of @code{foo}.
 
   But it is unmodular and unclean, in any case, for a Lisp file to
-redefine a function defined elsewhere.
+redefine a function defined elsewhere.  It is cleaner to use the advice
+facility (@pxref{Advising Functions}).
 
 @node Inline Functions
 @section Inline Functions
@@ -1083,15 +1094,14 @@ advantage of inline functions is greatest for small functions, you
 generally should not make large functions inline.
 
 It's possible to define a macro to expand into the same code that an
-inline function would execute.  But the macro would have a limitation:
-you can use it only explicitly---a macro cannot be called with
+inline function would execute.  (@xref{Macros}.)  But the macro would be
+limited to direct use in expressions---a macro cannot be called with
 @code{apply}, @code{mapcar} and so on.  Also, it takes some work to
-convert an ordinary function into a macro.  (@xref{Macros}.)  To convert
-it into an inline function is very easy; simply replace @code{defun}
-with @code{defsubst}.  Since each argument of an inline function is
-evaluated exactly once, you needn't worry about how many times the
-body uses the arguments, as you do for macros.  (@xref{Argument
-Evaluation}.)
+convert an ordinary function into a macro.  To convert it into an inline
+function is very easy; simply replace @code{defun} with @code{defsubst}.
+Since each argument of an inline function is evaluated exactly once, you
+needn't worry about how many times the body uses the arguments, as you
+do for macros.  (@xref{Argument Evaluation}.)
 
 Inline functions can be used and open-coded later on in the same file,
 following the definition, just like macros.
@@ -1127,6 +1137,9 @@ See @ref{Eval}.
 @item funcall
 See @ref{Calling Functions}.
 
+@item function
+See @ref{Anonymous Functions}.
+
 @item ignore
 See @ref{Calling Functions}.
 
@@ -1145,6 +1158,9 @@ See @ref{Creating Symbols}.
 @item mapcar
 See @ref{Mapping Functions}.
 
+@item map-char-table
+See @ref{Char-Tables}.
+
 @item mapconcat
 See @ref{Mapping Functions}.
 
diff --git a/lispref/help.texi b/lispref/help.texi
index 1e94b7406a5..d31315c0ef1 100644
--- a/lispref/help.texi
+++ b/lispref/help.texi
@@ -50,11 +50,11 @@ documentation string follows the initial value of the variable.
 sentence (or two complete sentences) since some commands, such as
 @code{apropos}, show only the first line of a multi-line documentation
 string.  Also, you should not indent the second line of a documentation
-string, if you have one, because that looks odd when you use @kbd{C-h f}
-(@code{describe-function}) or @kbd{C-h v} (@code{describe-variable}).
-@xref{Documentation Tips}.
+string, if it has one, because that looks odd when you use @kbd{C-h f}
+(@code{describe-function}) or @kbd{C-h v} (@code{describe-variable}) to
+view the documentation string.  @xref{Documentation Tips}.
 
-  Documentation strings may contain several special substrings, which
+  Documentation strings can contain several special substrings, which
 stand for key bindings to be looked up in the current keymaps when the
 documentation is displayed.  This allows documentation strings to refer
 to the keys for related commands and be accurate even when a user
@@ -132,7 +132,7 @@ non-@code{nil}) it calls @code{substitute-command-keys}, to return a
 value containing the actual (current) key bindings.
 
 The function @code{documentation} signals a @code{void-function} error
-if @var{function} has no function definition.  However, it is ok if
+if @var{function} has no function definition.  However, it is OK if
 the function definition has no documentation string.  In that case,
 @code{documentation} returns @code{nil}.
 @end defun
@@ -255,7 +255,7 @@ for in the directory @code{doc-directory}.  Usually @var{filename} is
 
 @c Emacs 19 feature
 @defvar doc-directory
-This variable holds the name of the directory which should contion the
+This variable holds the name of the directory which should contain the
 file @code{"DOC-@var{version}"} that contains documentation strings for
 built-in and preloaded functions and variables.
 
@@ -288,12 +288,12 @@ stands for a key sequence that will invoke @var{command}, or @samp{M-x
 @var{command}} if @var{command} has no key bindings.
 
 @item \@{@var{mapvar}@} 
-stands for a summary of the value of @var{mapvar}.  The value should be
-a keymap.  The summary is made by @code{describe-bindings}.
+stands for a summary of the keymap which is the value of the variable
+@var{mapvar}.  The summary is made using @code{describe-bindings}.
 
 @item \<@var{mapvar}> 
 stands for no text itself.  It is used only for a side effect: it
-specifies @var{mapvar} as the keymap for any following
+specifies @var{mapvar}'s value as the keymap for any following
 @samp{\[@var{command}]} sequences in this documentation string.
 
 @item \=
@@ -331,7 +331,7 @@ user's own customized key bindings.
 ?               minibuffer-completion-help
 SPC             minibuffer-complete-word
 TAB             minibuffer-complete
-LFD             minibuffer-complete-and-exit
+C-j             minibuffer-complete-and-exit
 RET             minibuffer-complete-and-exit
 C-g             abort-recursive-edit
 "
@@ -372,7 +372,7 @@ This function returns a string describing @var{event} in the standard
 Emacs notation for keyboard input.  A normal printing character appears
 as itself, but a control character turns into a string starting with
 @samp{C-}, a meta character turns into a string starting with @samp{M-},
-and space, linefeed, etc.@: appear as @samp{SPC}, @samp{LFD}, etc.  A
+and space, tab, etc.@: appear as @samp{SPC}, @samp{TAB}, etc.  A
 function key symbol appears as itself.  An event that is a list appears
 as the name of the symbol in the @sc{car} of the list.
 
@@ -383,7 +383,7 @@ as the name of the symbol in the @sc{car} of the list.
 @end group
 @group
 (key-description "\C-x \M-y \n \t \r \f123")
-     @result{} "C-x SPC M-y SPC LFD SPC TAB SPC RET SPC C-l 1 2 3"
+     @result{} "C-x SPC M-y SPC C-j SPC TAB SPC RET SPC C-l 1 2 3"
 @end group
 @group
 (single-key-description 'C-mouse-1)
@@ -423,7 +423,7 @@ the user as subcommands of the prefix @kbd{C-h}.  For more information
 about them, see @ref{Help, , Help, emacs, The GNU Emacs Manual}.  Here
 we describe some program-level interfaces to the same information.
 
-@deffn Command apropos regexp &optional do-all predicate
+@deffn Command apropos regexp &optional do-all
 This function finds all symbols whose names contain a match for the
 regular expression @var{regexp}, and returns a list of them
 (@pxref{Regular Expressions}).  It also displays the symbols in a buffer
@@ -434,15 +434,9 @@ beginning of its documentation string.
 If @var{do-all} is non-@code{nil}, then @code{apropos} also shows
 key bindings for the functions that are found.
 
-If @var{predicate} is non-@code{nil}, it should be a function to be
-called on each symbol that has matched @var{regexp}.  Only symbols for
-which @var{predicate} returns a non-@code{nil} value are listed or
-displayed.
-
 In the first of the following examples, @code{apropos} finds all the
-symbols with names containing @samp{exec}.  In the second example, it
-finds and returns only those symbols that are also commands.  (We don't
-show here the output that results in the @samp{*Help*} buffer.)
+symbols with names containing @samp{exec}.  (We don't show here the
+output that results in the @samp{*Help*} buffer.)
 
 @smallexample
 @group
@@ -451,42 +445,7 @@ show here the output that results in the @samp{*Help*} buffer.)
     exec-path execute-extended-command execute-kbd-macro
     executing-kbd-macro executing-macro)
 @end group
-
-@group
-(apropos "exec" nil 'commandp)
-     @result{} (Buffer-menu-execute execute-extended-command)
-@end group
-@ignore
-@group
----------- Buffer: *Help* ----------
-Buffer-menu-execute
-  Function: Save and/or delete buffers marked with
-  M-x Buffer-menu-save or M-x Buffer-menu-delete commands.
-execute-extended-command      ESC x
-  Function: Read function name, then read its 
-  arguments and call it.
----------- Buffer: *Help* ----------
-@end group
-@end ignore
 @end smallexample
-
-The command @kbd{C-h a} (@code{command-apropos}) calls @code{apropos},
-but specifies a @var{predicate} that restricts the output to symbols
-that are commands.  The call to @code{apropos} looks like this:
-
-@smallexample
-(apropos string t 'commandp)
-@end smallexample
-@end deffn
-
-@c Emacs 19 feature
-@deffn Command super-apropos regexp &optional do-all
-This function differs from @code{apropos} in that it searches
-documentation strings as well as symbol names for matches for
-@var{regexp}.  By default, it searches the documentation strings for
-preloaded functions and variables only.  If @var{do-all} is
-non-@code{nil}, it scans the names and documentation strings of all
-functions and variables.
 @end deffn
 
 @defvar help-map
@@ -522,7 +481,7 @@ Documentation}.
 
 @defvar help-char
 The value of this variable is the help character---the character that
-Emacs recognizes as meaning Help.  By default, it is 8, which is
+Emacs recognizes as meaning Help.  By default, it stands for 8, which is
 @kbd{C-h}.  When Emacs reads this character, if @code{help-form} is
 non-@code{nil} Lisp expression, it evaluates that expression, and
 displays the result in a window if it is a string.
@@ -539,6 +498,13 @@ binding as a subcommand of the prefix key, it runs
 subcommands of the prefix key.
 @end defvar
 
+@tindex help-event-list
+@defvar help-event-list
+The value of this variable is a list of event types that serve as
+alternative ``help characters.''  These events are handled just like the
+event specified by @code{help-char}.
+@end defvar
+
 @defvar help-form
 If this variable is non-@code{nil}, its value is a form to evaluate
 whenever the character @code{help-char} is read.  If evaluating the form
@@ -546,19 +512,19 @@ produces a string, that string is displayed.
 
 A command that calls @code{read-event} or @code{read-char} probably
 should bind @code{help-form} to a non-@code{nil} expression while it
-does input.  (The exception is when @kbd{C-h} is meaningful input.)
-Evaluating this expression should result in a string that explains what
-the input is for and how to enter it properly.
+does input.  (The time when you should not do this is when @kbd{C-h} has
+some other meaning.)  Evaluating this expression should result in a
+string that explains what the input is for and how to enter it properly.
 
 Entry to the minibuffer binds this variable to the value of
 @code{minibuffer-help-form} (@pxref{Minibuffer Misc}).
 @end defvar
 
 @defvar prefix-help-command
-This variable holds a function to print help for a prefix character.
-The function is called when the user types a prefix key followed by the
-help character, and the help character has no binding after that prefix.
-The variable's default value is @code{describe-prefix-bindings}.
+This variable holds a function to print help for a prefix key.  The
+function is called when the user types a prefix key followed by the help
+character, and the help character has no binding after that prefix.  The
+variable's default value is @code{describe-prefix-bindings}.
 @end defvar
 
 @defun describe-prefix-bindings
diff --git a/lispref/internals.texi b/lispref/internals.texi
index 77bafab47fa..74d019d2039 100644
--- a/lispref/internals.texi
+++ b/lispref/internals.texi
@@ -12,14 +12,15 @@ the preloaded Lisp libraries in it, how storage is allocated, and some
 internal aspects of GNU Emacs that may be of interest to C programmers.
 
 @menu
-* Building Emacs::      How to preload Lisp libraries into Emacs.
+* Building Emacs::      How to the dumped Emacs is made.
 * Pure Storage::        A kludge to make preloaded Lisp functions sharable.
 * Garbage Collection::  Reclaiming space for Lisp objects no longer used.
+* Memory Usage::        Info about total size of Lisp objects made so far.
 * Writing Emacs Primitives::   Writing C code for Emacs.
 * Object Internals::    Data formats of buffers, windows, processes.
 @end menu
 
-@node Building Emacs, Pure Storage, GNU Emacs Internals, GNU Emacs Internals
+@node Building Emacs
 @appendixsec Building Emacs
 @cindex building Emacs
 @pindex temacs
@@ -118,54 +119,7 @@ If you want to use this function in an Emacs that was already dumped,
 you must run Emacs with @samp{-batch}.
 @end defun
 
-@deffn Command emacs-version
-  This function returns a string describing the version of Emacs that is
-running.  It is useful to include this string in bug reports.
-
-@example
-@group
-(emacs-version)
-  @result{} "GNU Emacs 20.2.5 (i486-pc-linux-gnulibc1, X toolkit)
- of Sat Feb 14 1998 on psilocin.gnu.org"
-@end group
-@end example
-
-Called interactively, the function prints the same information in the
-echo area.
-@end deffn
-
-@defvar emacs-build-time
-The value of this variable is the time at which Emacs was built at the
-local site.
-
-@example
-@group
-emacs-build-time
-     @result{} "Tue Jun  6 14:55:57 1995"
-@end group
-@end example
-@end defvar
-
-@defvar emacs-version
-The value of this variable is the version of Emacs being run.  It is a
-string such as @code{"20.3.1"}.  The last number in this string is not
-really part of the Emacs release version number; it is incremented each
-time you build Emacs in any given directory.
-@end defvar
-
-  The following two variables have existed since Emacs version 19.23,
-
-@defvar emacs-major-version
-The major version number of Emacs, as an integer.  For Emacs version
-20.2, the value is 20.
-@end defvar
-
-@defvar emacs-minor-version
-The minor version number of Emacs, as an integer.  For Emacs version
-20.2, the value is 2.
-@end defvar
-
-@node Pure Storage, Garbage Collection, Building Emacs, GNU Emacs Internals
+@node Pure Storage
 @appendixsec Pure Storage
 @cindex pure storage
 
@@ -221,7 +175,7 @@ before and after dumping.
 You should not change this flag in a running Emacs.
 @end defvar
 
-@node Garbage Collection, Writing Emacs Primitives, Pure Storage, GNU Emacs Internals
+@node Garbage Collection
 @appendixsec Garbage Collection
 @cindex garbage collector
 
@@ -291,11 +245,16 @@ information:
 ((@var{used-conses} . @var{free-conses})
  (@var{used-syms} . @var{free-syms})
 @end group
- (@var{used-markers} . @var{free-markers})
+ (@var{used-miscs} . @var{free-miscs})
  @var{used-string-chars} 
  @var{used-vector-slots}
  (@var{used-floats} . @var{free-floats})
  (@var{used-intervals} . @var{free-intervals}))
+@end example
+
+Here is an example:
+
+@example
 @group
 (garbage-collect)
      @result{} ((106886 . 13184) (9769 . 0)
@@ -321,12 +280,13 @@ The number of symbols in use.
 The number of symbols for which space has been obtained from the
 operating system, but that are not currently being used.
 
-@item used-markers
-The number of markers in use.
+@item used-miscs
+The number of miscellaneous objects in use.  These include markers and
+overlays, plus certain objects not visible to users.
 
-@item free-markers
-The number of markers for which space has been obtained from the
-operating system, but that are not currently being used.
+@item free-miscs
+The number of miscellaneous objects for which space has been obtained
+from the operating system, but that are not currently being used.
 
 @item used-string-chars
 The total size of all strings, in characters.
@@ -373,6 +333,11 @@ until the subsequent garbage collection, at which time
 @code{garbage-collect} will set the threshold back to 10,000.
 @end defopt
 
+  The value return by @code{garbage-collect} describes the amount of
+memory used by Lisp data, broken down by data type.  By contrast, the
+function @code{memory-limit} provides information on the total amount of
+memory Emacs is currently using.
+
 @c Emacs 19 feature
 @defun memory-limit
 This function returns the address of the last byte Emacs has allocated,
@@ -383,7 +348,53 @@ You can use this to get a general idea of how your actions affect the
 memory usage.
 @end defun
 
-@node Writing Emacs Primitives, Object Internals, Garbage Collection, GNU Emacs Internals
+@node Memory Usage
+@section Memory Usage
+
+  These functions and variables give information about the total amount
+of memory allocation that Emacs has done, broken down by data type.
+Note the difference between these and the values returned by
+@code{(garbage-collect)}; those count objects that currently exist, but
+these count the number or size of all allocations, including those for
+objects that have since been freed.
+
+@defvar cons-cells-consed
+The total number of cons cells that have been allocated so far
+in this Emacs session.
+@end defvar
+
+@defvar floats-consed
+The total number of floats that have been allocated so far
+in this Emacs session.
+@end defvar
+
+@defvar vector-cells-consed
+The total number of vector cells that have been allocated so far
+in this Emacs session.
+@end defvar
+
+@defvar symbols-consed
+The total number of symbols that have been allocated so far
+in this Emacs session.
+@end defvar
+
+@defvar string-chars-consed
+The total number of string characters that have been allocated so far
+in this Emacs session.
+@end defvar
+
+@defvar misc-objects-consed
+The total number of miscellaneous objects that have been allocated so
+far in this Emacs session.  These include markers and overlays, plus
+certain objects not visible to users.
+@end defvar
+
+@defvar intervals-consed
+The total number of intervals that have been allocated so far
+in this Emacs session.
+@end defvar
+
+@node Writing Emacs Primitives
 @appendixsec Writing Emacs Primitives
 @cindex primitive function internals
 
@@ -576,57 +587,69 @@ visible in Lisp with a value that is always an integer.
 @code{DEFVAR_BOOL} makes a C variable of type @code{int} visible in Lisp
 with a value that is either @code{t} or @code{nil}.
 
+  If you define a file-scope C variable of type @code{Lisp_Object},
+you must protect it for garbage-collection by calling @code{staticpro}
+in @code{syms_of_@var{filename}}, like this:
+
+@example
+staticpro (&@var{variable});
+@end example
+
   Here is another example function, with more complicated arguments.
-This comes from the code for the X Window System, and it demonstrates
-the use of macros and functions to manipulate Lisp objects.
+This comes from the code in @file{window.c}, and it demonstrates the use
+of macros and functions to manipulate Lisp objects.
 
 @smallexample
 @group
 DEFUN ("coordinates-in-window-p", Fcoordinates_in_window_p,
   Scoordinates_in_window_p, 2, 2,
   "xSpecify coordinate pair: \nXExpression which evals to window: ",
-  "Return non-nil if POSITIONS is in WINDOW.\n\  
-  \(POSITIONS is a list, (SCREEN-X SCREEN-Y)\)\n\
+  "Return non-nil if COORDINATES is in WINDOW.\n\  
+COORDINATES is a cons of the form (X . Y), X and Y being distances\n\
+...
 @end group
 @group
-  Returned value is list of positions expressed\n\
-  relative to window upper left corner.")
-  (coordinate, window)
-     register Lisp_Object coordinate, window;
+If they are on the border between WINDOW and its right sibling,\n\
+   `vertical-line' is returned.")
+  (coordinates, window)
+     register Lisp_Object coordinates, window;
 @{
-  register Lisp_Object xcoord, ycoord;
+  int x, y;
 @end group
 
 @group
-  if (!CONSP (coordinate)) wrong_type_argument (Qlistp, coordinate);
-  CHECK_WINDOW (window, 2);
-  xcoord = Fcar (coordinate);
-  ycoord = Fcar (Fcdr (coordinate));
-  CHECK_NUMBER (xcoord, 0);
-  CHECK_NUMBER (ycoord, 1);
+  CHECK_LIVE_WINDOW (window, 0);
+  CHECK_CONS (coordinates, 1);
+  x = XINT (Fcar (coordinates));
+  y = XINT (Fcdr (coordinates));
 @end group
+
 @group
-  if ((XINT (xcoord) < XINT (XWINDOW (window)->left))
-      || (XINT (xcoord) >= (XINT (XWINDOW (window)->left)
-                            + XINT (XWINDOW (window)->width))))
-    return Qnil;
-  /* @r{Subtracting from XFASTINT (xcoord) is safe}
-     @r{as long as we know the result is not negative.}  */
-  XFASTINT (xcoord) -= XFASTINT (XWINDOW (window)->left);
+  switch (coordinates_in_window (XWINDOW (window), &x, &y))
+    @{
+    case 0:                     /* NOT in window at all. */
+      return Qnil;
 @end group
+
 @group
-  if (XINT (ycoord) == (screen_height - 1))
-    return Qnil;
+    case 1:                     /* In text part of window. */
+      return Fcons (make_number (x), make_number (y));
 @end group
+
 @group
-  if ((XINT (ycoord) < XINT (XWINDOW (window)->top))
-      || (XINT (ycoord) >= (XINT (XWINDOW (window)->top)
-                            + XINT (XWINDOW (window)->height)) - 1))
-    return Qnil;
+    case 2:                     /* In mode line of window. */
+      return Qmode_line;
 @end group
+
 @group
-  XFASTINT (ycoord) -= XFASTINT (XWINDOW (window)->top);
-  return (Fcons (xcoord, Fcons (ycoord, Qnil)));
+    case 3:                     /* On right border of window.  */
+      return Qvertical_line;
+@end group
+
+@group
+    default:
+      abort ();
+    @}
 @}
 @end group
 @end smallexample
@@ -650,7 +673,7 @@ number of arguments.  They work by calling @code{Ffuncall}.
 @file{lisp.h} contains the definitions for some important macros and
 functions.
 
-@node Object Internals,  , Writing Emacs Primitives, GNU Emacs Internals
+@node Object Internals
 @appendixsec Object Internals
 @cindex object internals
 
@@ -678,7 +701,7 @@ explicitly using a suitable predicate (@pxref{Type Predicates}).
 * Process Internals::   Components of a process structure.
 @end menu
 
-@node Buffer Internals, Window Internals, Object Internals, Object Internals
+@node Buffer Internals
 @appendixsubsec Buffer Internals
 @cindex internals, of buffer
 @cindex buffer internals
@@ -717,19 +740,19 @@ This field contains the syntax table for the buffer.  @xref{Syntax Tables}.
 
 @item downcase_table
 This field contains the conversion table for converting text to lower case.
-@xref{Case Table}.
+@xref{Case Tables}.
 
 @item upcase_table
 This field contains the conversion table for converting text to upper case.
-@xref{Case Table}.
+@xref{Case Tables}.
 
 @item case_canon_table
 This field contains the conversion table for canonicalizing text for
-case-folding search.  @xref{Case Table}.
+case-folding search.  @xref{Case Tables}.
 
 @item case_eqv_table
 This field contains the equivalence table for case-folding search.
-@xref{Case Table}.
+@xref{Case Tables}.
 
 @item display_table
 This field contains the buffer's display table, or @code{nil} if it doesn't
@@ -753,10 +776,11 @@ hence it is also included on the list @code{markers}.  @xref{The Mark}.
 This field is non-@code{nil} if the buffer's mark is active.
 
 @item local_var_alist
-This field contains the association list describing the variables local
-in this buffer, and their values, with the exception of local variables
-that have special slots in the buffer object.  (Those slots are omitted
-from this table.)  @xref{Buffer-Local Variables}.
+This field contains the association list describing the buffer-local
+variable bindings of this buffer, not including the built-in
+buffer-local bindings that that have special slots in the buffer object.
+(Those slots are omitted from this table.)  @xref{Buffer-Local
+Variables}.
 
 @item base_buffer
 This field holds the buffer's base buffer (if it is an indirect buffer),
@@ -777,9 +801,13 @@ decreasing end position.
 This field holds a list of the overlays in this buffer that end after
 the current overlay center position.  They are sorted in order of
 increasing beginning position.
+
+@item enable_multibyte_characters
+This field holds the buffer's local value of
+@code{enable-multibyte-characters}---either @code{t} or @code{nil}.
 @end table
 
-@node Window Internals, Process Internals, Buffer Internals, Object Internals
+@node Window Internals
 @appendixsubsec Window Internals
 @cindex internals, of window
 @cindex window internals
@@ -886,7 +914,7 @@ holds the mark position that made one end of that region.  Otherwise,
 this field is @code{nil}.
 @end table
 
-@node Process Internals,  , Window Internals, Object Internals
+@node Process Internals
 @appendixsubsec Process Internals
 @cindex internals, of process
 @cindex process internals
diff --git a/lispref/intro.texi b/lispref/intro.texi
index c1cf54000f3..6d2d63981eb 100644
--- a/lispref/intro.texi
+++ b/lispref/intro.texi
@@ -504,7 +504,9 @@ for other purposes as well, such as writing editing commands.
 with its own idiosyncrasies.  Many of them were inspired by Maclisp,
 which was written in the 1960's at MIT's Project MAC.  Eventually the
 implementors of the descendants of Maclisp came together and developed a
-standard for Lisp systems, called Common Lisp.
+standard for Lisp systems, called Common Lisp.  In the mean time, Gerry
+Sussman and Guy Steele at MIT developed a simplified but very powerful
+dialect of Lisp, called Scheme.
 
   GNU Emacs Lisp is largely inspired by Maclisp, and a little by Common
 Lisp.  If you know Common Lisp, you will notice many similarities.
@@ -515,6 +517,10 @@ might be very confused.  We will occasionally point out how GNU Emacs
 Lisp differs from Common Lisp.  If you don't know Common Lisp, don't
 worry about it; this manual is self-contained.
 
+  Emacs Lisp is not at all influenced by Scheme; but the GNU project has
+an implementation of Scheme, called Guile.  We use Guile for
+extensibility in all new GNU software that calls for extensibility.
+
 @node Conventions
 @section Conventions
 
@@ -529,6 +535,7 @@ manual.  You may want to skip this section and refer back to it later.
 * Error Messages::           The format we use for examples of errors.
 * Buffer Text Notation::     The format we use for buffer contents in examples.
 * Format of Descriptions::   Notation for describing functions, variables, etc.
+* Version Info::             Which Emacs version is running?
 @end menu
 
 @node Some Terms
@@ -544,8 +551,9 @@ including those you write.
 
 @cindex fonts
   Examples of Lisp code appear in this font or form: @code{(list 1 2
-3)}.  Names that represent arguments or metasyntactic variables appear
-in this font or form: @var{first-number}.
+3)}.  Names that represent metasyntactic variables, or arguments to a
+function being described, appear in this font or form:
+@var{first-number}.
 
 @node nil and t
 @subsection @code{nil} and @code{t}
@@ -587,7 +595,8 @@ choosing, use @code{t}.  The symbol @code{t} always has value @code{t}.
   In Emacs Lisp, @code{nil} and @code{t} are special symbols that always
 evaluate to themselves.  This is so that you do not need to quote them
 to use them as constants in a program.  An attempt to change their
-values results in a @code{setting-constant} error.  @xref{Accessing
+values results in a @code{setting-constant} error.  The same is true of
+any symbol whose name starts with a colon (@samp{:}).  @xref{Constant
 Variables}.
 
 @node Evaluation Notation
@@ -675,7 +684,7 @@ the buffer in question between two lines of dashes containing the buffer
 name.  In addition, @samp{@point{}} indicates the location of point.
 (The symbol for point, of course, is not part of the text in the buffer;
 it indicates the place @emph{between} two characters where point is
-located.)
+currently located.)
 
 @example
 ---------- Buffer: foo ----------
@@ -723,18 +732,18 @@ The description follows on succeeding lines, sometimes with examples.
 @cindex special form descriptions
 
   In a function description, the name of the function being described
-appears first.  It is followed on the same line by a list of parameters.
-The names used for the parameters are also used in the body of the
-description.
+appears first.  It is followed on the same line by a list of argument
+names.  These names are also used in the body of the description, to
+stand for the values of the arguments.
 
-  The appearance of the keyword @code{&optional} in the parameter list
-indicates that the arguments for subsequent parameters may be omitted
-(omitted parameters default to @code{nil}).  Do not write
-@code{&optional} when you call the function.
+  The appearance of the keyword @code{&optional} in the argument list
+indicates that the subsequent arguments may be omitted (omitted
+arguments default to @code{nil}).  Do not write @code{&optional} when
+you call the function.
 
   The keyword @code{&rest} (which will always be followed by a single
-parameter) indicates that any number of arguments can follow.  The value
-of the single following parameter will be a list of all these arguments.
+argument name) indicates that any number of arguments can follow.  The value
+of the single following arguments name will be a list of all these arguments.
 Do not write @code{&rest} when you call the function.
 
   Here is a description of an imaginary function @code{foo}:
@@ -760,15 +769,15 @@ More generally,
 @end example
 @end defun
 
-  Any parameter whose name contains the name of a type (e.g.,
+  Any argument whose name contains the name of a type (e.g.,
 @var{integer}, @var{integer1} or @var{buffer}) is expected to be of that
 type.  A plural of a type (such as @var{buffers}) often means a list of
-objects of that type.  Parameters named @var{object} may be of any type.
-(@xref{Lisp Data Types}, for a list of Emacs object types.)
-Parameters with other sorts of names (e.g., @var{new-file}) are
-discussed specifically in the description of the function.  In some
-sections, features common to parameters of several functions are
-described at the beginning.
+objects of that type.  Arguments named @var{object} may be of any type.
+(@xref{Lisp Data Types}, for a list of Emacs object types.)  Arguments
+with other sorts of names (e.g., @var{new-file}) are discussed
+specifically in the description of the function.  In some sections,
+features common to the arguments of several functions are described at
+the beginning.
 
   @xref{Lambda Expressions}, for a more complete description of optional
 and rest arguments.
@@ -780,7 +789,7 @@ 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 parameters because they can break the argument
+optional and repeated arguments because they can break the argument
 list down into separate arguments in more complicated ways.
 @samp{@code{@r{[}@var{optional-arg}@r{]}}} means that @var{optional-arg} is
 optional and @samp{@var{repeated-args}@dots{}} stands for zero or more
@@ -798,7 +807,8 @@ if @var{var} equals @var{to}.  Here is an example:
 @example
 (count-loop (i 0 10)
   (prin1 i) (princ " ")
-  (prin1 (aref vector i)) (terpri))
+  (prin1 (aref vector i))
+  (terpri))
 @end example
 
 If @var{from} and @var{to} are omitted, then @var{var} is bound to
@@ -842,6 +852,59 @@ have not yet thought about executing.
   User option descriptions have the same format, but `Variable' is
 replaced by `User Option'.
 
+@node Version Info
+@section Version Information
+
+  These functions and variables provide information about which
+version of Emacs is in use.
+
+@deffn Command emacs-version
+This function returns a string describing the version of Emacs that is
+running.  It is useful to include this string in bug reports.
+
+@example
+@group
+(emacs-version)
+  @result{} "GNU Emacs 20.3.5 (i486-pc-linux-gnulibc1, X toolkit)
+ of Sat Feb 14 1998 on psilocin.gnu.org"
+@end group
+@end example
+
+Called interactively, the function prints the same information in the
+echo area.
+@end deffn
+
+@defvar emacs-build-time
+The value of this variable is the time at which Emacs was built at the
+local site.
+
+@example
+@group
+emacs-build-time
+     @result{} "Tue Jun  6 14:55:57 1995"
+@end group
+@end example
+@end defvar
+
+@defvar emacs-version
+The value of this variable is the version of Emacs being run.  It is a
+string such as @code{"20.3.1"}.  The last number in this string is not
+really part of the Emacs release version number; it is incremented each
+time you build Emacs in any given directory.
+@end defvar
+
+  The following two variables have existed since Emacs version 19.23,
+
+@defvar emacs-major-version
+The major version number of Emacs, as an integer.  For Emacs version
+20.3, the value is 20.
+@end defvar
+
+@defvar emacs-minor-version
+The minor version number of Emacs, as an integer.  For Emacs version
+20.3, the value is 3.
+@end defvar
+
 @node Acknowledgements
 @section Acknowledgements
 
diff --git a/lispref/keymaps.texi b/lispref/keymaps.texi
index 35feb302f20..7e6cc59cecc 100644
--- a/lispref/keymaps.texi
+++ b/lispref/keymaps.texi
@@ -44,9 +44,8 @@ found.  The whole process is called @dfn{key lookup}.
   A @dfn{keymap} is a table mapping event types to definitions (which
 can be any Lisp objects, though only certain types are meaningful for
 execution by the command loop).  Given an event (or an event type) and a
-keymap, Emacs can get the event's definition.  Events include ordinary
-@sc{ASCII} characters, function keys, and mouse actions (@pxref{Input
-Events}).
+keymap, Emacs can get the event's definition.  Events include
+characters, function keys, and mouse actions (@pxref{Input Events}).
 
   A sequence of input events that form a unit is called a
 @dfn{key sequence}, or @dfn{key} for short.  A sequence of one event
@@ -125,19 +124,20 @@ completely masks any lower-precedence keymap.
 
 @item @var{vector}
 If an element of a keymap is a vector, the vector counts as bindings for
-all the @sc{ASCII} characters; vector element @var{n} is the binding for
-the character with code @var{n}.  This is a compact way to record lots
-of bindings.  A keymap with such a vector is called a @dfn{full keymap}.
-Other keymaps are called @dfn{sparse keymaps}.
+all the @sc{ASCII} characters, codes 0 through 127; vector element
+@var{n} is the binding for the character with code @var{n}.  This is a
+compact way to record lots of bindings.  A keymap with such a vector is
+called a @dfn{full keymap}.  Other keymaps are called @dfn{sparse
+keymaps}.
 
 When a keymap contains a vector, it always defines a binding for each
 @sc{ASCII} character, even if the vector contains @code{nil} for that
-character.  Such a binding of @code{nil} overrides any default binding
-in the keymap.  However, default bindings are still meaningful for
-events that are not @sc{ASCII} characters.  A binding of @code{nil} does
-@emph{not} override lower-precedence keymaps; thus, if the local map
-gives a binding of @code{nil}, Emacs uses the binding from the global
-map.
+character.  Such a binding of @code{nil} overrides any default key
+binding in the keymap.  However, default bindings are still meaningful
+for events that are not @sc{ASCII} characters.  A binding of @code{nil}
+does @emph{not} override lower-precedence keymaps; thus, if the local
+map gives a binding of @code{nil}, Emacs uses the binding from the
+global map.
 
 @item @var{string}
 @cindex keymap prompt string
@@ -333,7 +333,7 @@ from @code{text-mode-map}:
 @cindex prefix key
 
   A @dfn{prefix key} is a key sequence whose binding is a keymap.  The
-keyamp defines what to do with key sequences that extend the prefix key.
+keymap defines what to do with key sequences that extend the prefix key.
 For example, @kbd{C-x} is a prefix key, and it uses a keymap that is
 also stored in the variable @code{ctl-x-map}.  This keymap defines
 bindings for key sequences starting with @kbd{C-x}.
@@ -481,29 +481,27 @@ minor mode keymaps.
 
   All the active keymaps are used together to determine what command to
 execute when a key is entered.  Emacs searches these maps one by one, in
-order of decreasing precedence, until it finds a binding in one of the maps.
+order of decreasing precedence, until it finds a binding in one of the
+maps.  The procedure for searching a single keymap is called @dfn{key
+lookup}; see @ref{Key Lookup}.
 
-  Normally, Emacs @emph{first} searches for the key in the minor mode
+Normally, Emacs first searches for the key in the minor mode
 maps (one map at a time); if they do not supply a binding for the key,
 Emacs searches the local map; if that too has no binding, Emacs then
 searches the global map.  However, if @code{overriding-local-map} is
 non-@code{nil}, Emacs searches that map first, before the global map.
 
-  The procedure for searching a single keymap is called
-@dfn{key lookup}; see @ref{Key Lookup}.
-
 @cindex major mode keymap
   Since every buffer that uses the same major mode normally uses the
 same local keymap, you can think of the keymap as local to the mode.  A
 change to the local keymap of a buffer (using @code{local-set-key}, for
 example) is seen also in the other buffers that share that keymap.
 
-  The local keymaps that are used for Lisp mode, C mode, and several
-other major modes exist even if they have not yet been used.  These
-local maps are the values of the variables @code{lisp-mode-map},
-@code{c-mode-map}, and so on.  For most other modes, which are less
-frequently used, the local keymap is constructed only when the mode is
-used for the first time in a session.
+  The local keymaps that are used for Lisp mode and some other major
+modes exist even if they have not yet been used.  These local maps are
+the values of variables such as @code{lisp-mode-map}.  For most major
+modes, which are less frequently used, the local keymap is constructed
+only when the mode is used for the first time in a session.
 
   The minibuffer has local keymaps, too; they contain various completion
 and exit commands.  @xref{Intro to Minibuffers}.
@@ -593,11 +591,8 @@ enables or disables a minor mode.  @xref{Keymaps and Minor Modes}.
 Note that elements of @code{minor-mode-map-alist} do not have the same
 structure as elements of @code{minor-mode-alist}.  The map must be the
 @sc{cdr} of the element; a list with the map as the @sc{cadr} will not
-do.
-
-What's more, the keymap itself must appear in the @sc{cdr}.  It does not
-work to store a variable in the @sc{cdr} and make the map the value of
-that variable.
+do.  The @sc{cadr} can be either a keymap (a list) or a symbol
+whose function definition is a keymap.
 
 When more than one minor mode keymap is active, their order of priority
 is the order of @code{minor-mode-map-alist}.  But you should design
@@ -614,12 +609,12 @@ Lookup}).
 This variable allows major modes to override the key bindings for
 particular minor modes.  The elements of this alist look like the
 elements of @code{minor-mode-map-alist}: @code{(@var{variable}
-. @var{keymap})}.  If a variable has an element
-@code{minor-mode-overriding-map-alist}. that map overrides the one in
-@code{minor-mode-map-alist}.
+. @var{keymap})}.  If a variable appears an element
+@code{minor-mode-overriding-map-alist}, that element overrides any
+element for the same variable in @code{minor-mode-map-alist}.
 
-@code{minor-mode-overriding-map-alist} is automatically local in all
-buffers.
+@code{minor-mode-overriding-map-alist} is automatically buffer-local in
+all buffers.
 @end defvar
 
 @defvar overriding-local-map
@@ -688,10 +683,10 @@ keymap.
 
   Let's use the term @dfn{keymap entry} to describe the value found by
 looking up an event type in a keymap.  (This doesn't include the item
-string and other extra elements in menu key bindings because
+string and other extra elements in menu key bindings, because
 @code{lookup-key} and other key lookup functions don't include them in
 the returned value.)  While any Lisp object may be stored in a keymap as
-a keymap entry, not all make sense for key lookup.  Here is a list of
+a keymap entry, not all make sense for key lookup.  Here is a table of
 the meaningful kinds of keymap entries:
 
 @table @asis
@@ -702,11 +697,6 @@ undefined key.  When a keymap fails to mention an event type at all, and
 has no default binding, that is equivalent to a binding of @code{nil}
 for that event type.
 
-@item @var{keymap}
-@cindex keymap in keymap
-The events used so far in the lookup form a prefix key.  The next
-event of the key sequence is looked up in @var{keymap}.
-
 @item @var{command}
 @cindex command in keymap
 The events used so far in the lookup form a complete key,
@@ -718,6 +708,11 @@ The array (either a string or a vector) is a keyboard macro.  The events
 used so far in the lookup form a complete key, and the array is its
 binding.  See @ref{Keyboard Macros}, for more information.
 
+@item @var{keymap}
+@cindex keymap in keymap
+The events used so far in the lookup form a prefix key.  The next
+event of the key sequence is looked up in @var{keymap}.
+
 @item @var{list}
 @cindex list in keymap
 The meaning of a list depends on the types of the elements of the list.
@@ -807,23 +802,9 @@ of @code{emacs-lisp-mode-map}.  Note that 9 is the code for @key{TAB},
   Here are the functions and variables pertaining to key lookup.
 
 @defun lookup-key keymap key &optional accept-defaults
-This function returns the definition of @var{key} in @var{keymap}.  If
-the string or vector @var{key} is not a valid key sequence according to
-the prefix keys specified in @var{keymap}, it must be ``too long'' and
-have extra events at the end that do not fit into a single key sequence.
-Then the value is a number, the number of events at the front of
-@var{key} that compose a complete key.
-
-@c Emacs 19 feature
-If @var{accept-defaults} is non-@code{nil}, then @code{lookup-key}
-considers default bindings as well as bindings for the specific events
-in @var{key}.  Otherwise, @code{lookup-key} reports only bindings for
-the specific sequence @var{key}, ignoring default bindings except when
-you explicitly ask about them.  (To do this, supply @code{t} as an
-element of @var{key}; see @ref{Format of Keymaps}.)
-
-All the other functions described in this chapter that look up keys use
-@code{lookup-key}.
+This function returns the definition of @var{key} in @var{keymap}.  All
+the other functions described in this chapter that look up keys use
+@code{lookup-key}.  Here are examples:
 
 @example
 @group
@@ -836,7 +817,21 @@ All the other functions described in this chapter that look up keys use
 @end group
 @end example
 
-  If @var{key} contains a meta character, that character is implicitly
+If the string or vector @var{key} is not a valid key sequence according
+to the prefix keys specified in @var{keymap}, it must be ``too long''
+and have extra events at the end that do not fit into a single key
+sequence.  Then the value is a number, the number of events at the front
+of @var{key} that compose a complete key.
+
+@c Emacs 19 feature
+If @var{accept-defaults} is non-@code{nil}, then @code{lookup-key}
+considers default bindings as well as bindings for the specific events
+in @var{key}.  Otherwise, @code{lookup-key} reports only bindings for
+the specific sequence @var{key}, ignoring default bindings except when
+you explicitly ask about them.  (To do this, supply @code{t} as an
+element of @var{key}; see @ref{Format of Keymaps}.)
+
+If @var{key} contains a meta character, that character is implicitly
 replaced by a two-character sequence: the value of
 @code{meta-prefix-char}, followed by the corresponding non-meta
 character.  Thus, the first example below is handled by conversion into
@@ -932,7 +927,7 @@ lookup translates @kbd{M-b} into @kbd{@key{ESC} b}, which is normally
 defined as the @code{backward-word} command.  However, if you set
 @code{meta-prefix-char} to 24, the code for @kbd{C-x}, then Emacs will
 translate @kbd{M-b} into @kbd{C-x b}, whose standard binding is the
-@code{switch-to-buffer} command.
+@code{switch-to-buffer} command.  Here is an illustration:
 
 @smallexample
 @group
@@ -995,11 +990,8 @@ event types in a key sequence that is a vector: you can use a list
 containing modifier names plus one base event (a character or function
 key name).  For example, @code{(control ?a)} is equivalent to
 @code{?\C-a} and @code{(hyper control left)} is equivalent to
-@code{C-H-left}.
-
-  One advantage of using a list to represent the event type is that the
-precise numeric codes for the modifier bits don't appear in compiled
-files.
+@code{C-H-left}.  One advantage of such lists is that the precise
+numeric codes for the modifier bits don't appear in compiled files.
 
   For the functions below, an error is signaled if @var{keymap} is not a
 keymap or if @var{key} is not a string or vector representing a key
@@ -1016,12 +1008,10 @@ The value returned by @code{define-key} is @var{binding}.
 
 @cindex invalid prefix key error
 @cindex key sequence error
-Every prefix of @var{key} must be a prefix key (i.e., bound to a
-keymap) or undefined; otherwise an error is signaled.
-
-If some prefix of @var{key} is undefined, then @code{define-key} defines
-it as a prefix key so that the rest of @var{key} may be defined as
-specified.
+Every prefix of @var{key} must be a prefix key (i.e., bound to a keymap)
+or undefined; otherwise an error is signaled.  If some prefix of
+@var{key} is undefined, then @code{define-key} defines it as a prefix
+key so that the rest of @var{key} can be defined as specified.
 
 If there was previously no binding for @var{key} in @var{keymap}, the
 new binding is added at the beginning of @var{keymap}.  The order of
@@ -1383,7 +1373,7 @@ of a window.
 @end smallexample
 
 @noindent
-These are not all the keymaps you would see in an actual case.
+These are not all the keymaps you would see in actuality.
 @end defun
 
 @defun where-is-internal command &optional keymap firstonly noindirect
@@ -1425,9 +1415,9 @@ an indirect definition itself.
 @end defun
 
 @deffn Command describe-bindings prefix
-This function creates a listing of all defined keys and their
-definitions.  It writes the listing in a buffer named @samp{*Help*} and
-displays it in a window.
+This function creates a listing of all current key bindings, and
+displays it in a buffer named @samp{*Help*}.  The text is grouped by
+modes---minor modes first, then the major mode, then global bindings.
 
 If @var{prefix} is non-@code{nil}, it should be a prefix key; then the
 listing includes only keys that start with @var{prefix}.
@@ -1484,21 +1474,29 @@ moving to the top, if you care about the order.  When you add an item to
 an existing menu, you can specify its position in the menu using
 @code{define-key-after} (@pxref{Modifying Menus}).
 
-The individual bindings in the menu keymap should have item
-strings; these strings become the items displayed in the menu.  A
-binding with an item string looks like this:
+@menu
+* Simple Menu Items::
+* Extended Menu Items::
+@end menu
+
+@node Simple Menu Items
+@subsubsection Simple Menu Items
+
+  The simpler and older way to define a menu keymap binding
+looks like this:
 
 @example
-(@var{string} . @var{real-binding})
+(@var{item-string} . @var{real-binding})
 @end example
 
-The item string for a binding should be short---one or two words.  It
-should describe the action of the command it corresponds to.
+The @sc{car}, @var{item-string}, is the string to be displayed in the
+menu.  It should be short---preferably one to three words.  It should
+describe the action of the command it corresponds to.
 
 You can also supply a second string, called the help string, as follows:
 
 @example
-(@var{string} @var{help-string} . @var{real-binding})
+(@var{item-string} @var{help-string} . @var{real-binding})
 @end example
 
 Currently Emacs does not actually use @var{help-string}; it knows only
@@ -1506,13 +1504,13 @@ how to ignore @var{help-string} in order to extract @var{real-binding}.
 In the future we may use @var{help-string} as extended documentation for
 the menu item, available on request.
 
-As far as @code{define-key} is concerned, @var{string} and
+As far as @code{define-key} is concerned, @var{item-string} and
 @var{help-string} are part of the event's binding.  However,
 @code{lookup-key} returns just @var{real-binding}, and only
 @var{real-binding} is used for executing the key.
 
-If @var{real-binding} is @code{nil}, then @var{string} appears in the
-menu but cannot be selected.
+If @var{real-binding} is @code{nil}, then @var{item-string} appears in
+the menu but cannot be selected.
 
 If @var{real-binding} is a symbol and has a non-@code{nil}
 @code{menu-enable} property, that property is an expression that
@@ -1520,7 +1518,7 @@ controls whether the menu item is enabled.  Every time the keymap is
 used to display a menu, Emacs evaluates the expression, and it enables
 the menu item only if the expression's value is non-@code{nil}.  When a
 menu item is disabled, it is displayed in a ``fuzzy'' fashion, and
-cannot be selected with the mouse.
+cannot be selected.
 
 The menu bar does not recalculate which items are enabled every time you
 look at a menu.  This is because the X toolkit requires the whole tree
@@ -1534,12 +1532,13 @@ binding, like this:
 
 @c This line is not too long--rms.
 @example
-(@var{string} @r{[}@var{help-string}@r{]} (@var{key-binding-data}) . @var{real-binding})
+(@var{item-string} @r{[}@var{help-string}@r{]} (@var{key-binding-data}) . @var{real-binding})
 @end example
 
+@noindent
 Don't put these sublists in the menu item yourself; menu display
-calculates them automatically.  Don't add keyboard equivalents to the
-item strings in a mouse menu, since that is redundant.
+calculates them automatically.  Don't mention keyboard equivalents in
+the item strings themselves, since that is redundant.
 
 Sometimes it is useful to make menu items that use the ``same'' command
 but with different enable conditions.  You can do this by defining alias
@@ -1568,23 +1567,82 @@ itself).  To request this, give the alias symbol a non-@code{nil}
 causes menu items for @code{make-read-only} and @code{make-writable} to
 show the keyboard bindings for @code{toggle-read-only}.
 
+@node Extended Menu Items
+@subsubsection Extended Menu Items
+
+  An extended-format menu item is a more flexible and also cleaner
+alternative to the simple format.  It consists of a list that starts
+with the symbol @code{menu-item}.  To define a non-selectable string,
+the item looks like this:
+
+@example
+(menu-item @var{item-name})
+@end example
+
+@noindent
+where a string consisting of two or more dashes specifies a separator line.
+
+  To define a real menu item which can be selected, the extended format
+item looks like this:
+
+@example
+(menu-item @var{item-name} @var{real-binding}
+    . @var{item-property-list})
+@end example
+
+@noindent
+Here, @var{item-name} is an expression which evaluates to the menu item
+string.  Thus, the string need not be a constant.  The third element,
+@var{real-binding}, is the command to execute.  The tail of the list,
+@var{item-property-list}, has the form of a property list which contains
+other information.  Here is a table of the properties that are supported:
+
+@table @code
+@item :enable FORM
+The result of evaluating @var{form} determines whether the item is
+enabled (non-@code{nil} means yes).
+
+@item :visible FORM
+The result of evaluating @var{form} determines whether the item should
+actually appear in the menu (non-@code{nil} means yes).  If the item
+does not appear, then the menu is displayed as if this item were
+not defined at all.
+
+@item :help @var{help}
+The value of this property, @var{help}, is the extra help string (not
+currently used).
+
+@item :button (@var{type} . @var{selected})
+This property provides a way to define radio buttons and toggle buttons.
+The @sc{car}, @var{type}, says which: is should be @code{:toggle} or
+@code{:radio}.  The @sc{cdr}, @var{selected}, should be a form; the
+result of evaluating it says whether this button is currently selected.
+
+@item :filter @var{filter-fn}
+This property provides a way to compute the menu item dynamically.
+The property value @var{filter-fn} should be a function of one argument;
+when it is called, its argument will be @var{real-binding}.  The
+function should return the binding to use instead.
+@end table
+
 @node Mouse Menus
 @subsection Menus and the Mouse
 
-The way to make a menu keymap produce a menu is to make it the
-definition of a prefix key.
+  The usual way to make a menu keymap produce a menu is to make it the
+definition of a prefix key.  (A Lisp program can explicitly pop up a
+menu and receive the user's choice---see @ref{Pop-Up Menus}.)
 
-If the prefix key ends with a mouse event, Emacs handles the menu keymap
+  If the prefix key ends with a mouse event, Emacs handles the menu keymap
 by popping up a visible menu, so that the user can select a choice with
 the mouse.  When the user clicks on a menu item, the event generated is
 whatever character or symbol has the binding that brought about that
 menu item.  (A menu item may generate a series of events if the menu has
 multiple levels or comes from the menu bar.)
 
-It's often best to use a button-down event to trigger the menu.  Then
+  It's often best to use a button-down event to trigger the menu.  Then
 the user can select a menu item by releasing the button.
 
-A single keymap can appear as multiple menu panes, if you explicitly
+  A single keymap can appear as multiple menu panes, if you explicitly
 arrange for this.  The way to do this is to make a keymap for each pane,
 then create a binding for each of those maps in the main keymap of the
 menu.  Give each of these bindings an item string that starts with
@@ -1594,24 +1652,19 @@ bindings with @samp{@@}-less item strings are grouped into one pane,
 which appears along with the other panes explicitly created for the
 submaps.
 
-X toolkit menus don't have panes; instead, they can have submenus.
+  X toolkit menus don't have panes; instead, they can have submenus.
 Every nested keymap becomes a submenu, whether the item string starts
 with @samp{@@} or not.  In a toolkit version of Emacs, the only thing
 special about @samp{@@} at the beginning of an item string is that the
 @samp{@@} doesn't appear in the menu item.
 
-You can also get multiple panes from separate keymaps.  The full
-definition of a prefix key always comes from merging the definitions
-supplied by the various active keymaps (minor mode, local, and
-global).  When more than one of these keymaps is a menu, each of them
-makes a separate pane or panes.  @xref{Active Keymaps}.
-
-In toolkit versions of Emacs, menus don't have panes, so submenus are
-used to represent the separate keymaps.  Each keymap's contribution
-becomes one submenu.
-
-A Lisp program can explicitly pop up a menu and receive the user's
-choice.  You can use keymaps for this also.  @xref{Pop-Up Menus}.
+  You can also produce multiple panes or submenus from separate keymaps.
+The full definition of a prefix key always comes from merging the
+definitions supplied by the various active keymaps (minor mode, local,
+and global).  When more than one of these keymaps is a menu, each of
+them makes a separate pane or panes (when Emacs does not use an
+X-toolkit) or a separate submenu (when using an X-toolkit).
+@xref{Active Keymaps}.
 
 @node Keyboard Menus
 @subsection Menus and the Keyboard
@@ -1661,7 +1714,8 @@ menu bar.  First we create the keymap, and give it a name:
 (defvar menu-bar-print-menu (make-sparse-keymap "Print"))
 @end example
 
-  Next we define the menu items:
+@noindent
+Next we define the menu items:
 
 @example
 (define-key menu-bar-print-menu [ps-print-region]
@@ -1714,7 +1768,7 @@ item would be meaningless because @code{menu-bar-print-menu} is not a
 command.
 
   If you wanted to attach the same print menu to a mouse click, you
-might do it this way:
+can do it this way:
 
 @example
 (define-key global-map [C-S-down-mouse-1] menu-bar-print-menu)
@@ -1736,9 +1790,9 @@ so that pressing a button on the menu bar item leads to another menu.
 
   When more than one active keymap defines the same fake function key
 for the menu bar, the item appears just once.  If the user clicks on
-that menu bar item, it brings up a single, combined submenu containing
+that menu bar item, it brings up a single, combined menu containing
 all the subcommands of that item---the global subcommands, the local
-subcommands, and the minor mode subcommands, all together.
+subcommands, and the minor mode subcommands.
 
   The variable @code{overriding-local-map} is normally ignored when
 determining the menu bar contents.  That is, the menu bar is computed
@@ -1749,7 +1803,7 @@ were @code{nil}.  @xref{Active Keymaps}.
 parameter must be greater than zero.  Emacs uses just one line for the
 menu bar itself; if you specify more than one line, the other lines
 serve to separate the menu bar from the windows in the frame.  We
-recommend 1 or 2 as the value of @code{menu-bar-lines}.  @xref{X Frame
+recommend 1 or 2 as the value of @code{menu-bar-lines}.  @xref{Window Frame
 Parameters}.
 
   Here's an example of setting up a menu bar item:
@@ -1768,7 +1822,7 @@ Parameters}.
 @end group
 
 @group
-;; @r{Define specific subcommands in the item's menu.}
+;; @r{Define specific subcommands in this menu.}
 (define-key global-map
   [menu-bar words forward]
   '("Forward word" . forward-word))
@@ -1800,7 +1854,7 @@ local maps.
 
 This variable holds a list of fake function keys for items to display at
 the end of the menu bar rather than in normal sequence.  The default
-value is @code{(help)}; thus, the @samp{Help} menu item normally appears
+value is @code{(help-menu)}; thus, the @samp{Help} menu item normally appears
 at the end of the menu bar, following local menu items.
 @end defvar
 
@@ -1823,9 +1877,12 @@ Define a binding in @var{map} for @var{key}, with value @var{binding},
 just like @code{define-key}, but position the binding in @var{map} after
 the binding for the event @var{after}.  The argument @var{key} should be
 of length one---a vector or string with just one element.  But
-@var{after} should be an event type---a symbol or a character.
+@var{after} should be a single event type---a symbol or a character, not
+a sequence.  The new binding goes after the binding for @var{after}.  If
+@var{after} is @code{t}, then the new binding goes last, at the end of
+the keymap.
 
-For example,
+Here is an example:
 
 @example
 (define-key-after my-menu [drink]
@@ -1833,11 +1890,8 @@ For example,
 @end example
 
 @noindent
-makes a binding for the fake function key @key{drink} and puts it
-right after the binding for @key{eat}.
-
-If @var{after} is @code{t}, then the new binding goes last---at the end
-of the keymap.
+makes a binding for the fake function key @key{DRINK} and puts it
+right after the binding for @key{EAT}.
 
 Here is how to insert an item called @samp{Work} in the @samp{Signals}
 menu of Shell mode, after the item @code{break}:
@@ -1847,7 +1901,4 @@ menu of Shell mode, after the item @code{break}:
   (lookup-key shell-mode-map [menu-bar signals])
   [work] '("Work" . work-command) 'break)
 @end example
-
-Note that @var{key} is a sequence containing just one event type, but
-@var{after} is just an event type (not a sequence).
 @end defun
diff --git a/lispref/lists.texi b/lispref/lists.texi
index 6334b4bdcd9..3f269dc9093 100644
--- a/lispref/lists.texi
+++ b/lispref/lists.texi
@@ -92,8 +92,9 @@ like this:
 
 @example
 @group
-    ___ ___      ___ ___
-   |___|___|--> |___|___|--> nil
+    --- ---      --- ---
+   |   |   |--> |   |   |--> nil
+    --- ---      --- ---
      |            |
      |            |
       --> tulip    --> lily
@@ -106,14 +107,16 @@ two-element list:
 
 @example
 @group
-    ___ ___      ___ ___      ___ ___
-   |___|___|--> |___|___|--> |___|___|--> nil
+    --- ---      --- ---      --- ---
+   |   |   |--> |   |   |--> |   |   |--> nil
+    --- ---      --- ---      --- ---
      |            |            |
      |            |            |
      |             --> oak      --> maple
      |
-     |     ___ ___      ___ ___
-      --> |___|___|--> |___|___|--> nil
+     |     --- ---      --- ---
+      --> |   |   |--> |   |   |--> nil
+           --- ---      --- ---
             |            |
             |            |
              --> pine     --> needles
@@ -323,6 +326,10 @@ If @var{n} is negative, @code{nth} returns the first element of
 (nth n x) @equiv{} (car (nthcdr n x))
 @end group
 @end example
+
+The function @code{elt} is similar, but applies to any kind of sequence.
+For historical reasons, it takes its arguments in the opposite order.
+@xref{Sequence Functions}.
 @end defun
 
 @defun nthcdr n list
@@ -351,7 +358,7 @@ If @var{n} is zero or negative, @code{nthcdr} returns all of
 @end defun
 
 @tindex safe-length
-@defun safe-length sequence
+@defun safe-length list
 This function returns the length of @var{list}, with no risk
 of either an error or an infinite loop.
 
@@ -360,26 +367,30 @@ If @var{list} is not really a list, @code{safe-length} returns 0.  If
 number of distinct elements.
 @end defun
 
+  The most common way to compute the length of a list, when you are not
+worried that it may be circular, is with @code{length}.  @xref{Sequence
+Functions}.
+
 @tindex caar
-@defun caar list
-This is the same as @code{(car (car @var{list}))}.
+@defun caar cons-cell
+This is the same as @code{(car (car @var{cons-cell}))}.
 @end defun
 
 @tindex cadr
-@defun cadr list
-This is the same as @code{(car (cdr @var{list}))}
-or @code{(nth 1 @var{list})}.
+@defun cadr cons-cell
+This is the same as @code{(car (cdr @var{cons-cell}))}
+or @code{(nth 1 @var{cons-cell})}.
 @end defun
 
 @tindex cdar
-@defun cdar list
-This is the same as @code{(cdr (car @var{list}))}.
+@defun cdar cons-cell
+This is the same as @code{(cdr (car @var{cons-cell}))}.
 @end defun
 
 @tindex cddr
-@defun cddr list
-This is the same as @code{(cdr (cdr @var{list}))}
-or @code{(nthcdr 2 @var{list})}.
+@defun cddr cons-cell
+This is the same as @code{(cdr (cdr @var{cons-cell}))}
+or @code{(nthcdr 2 @var{cons-cell})}.
 @end defun
 
 @node Building Lists
@@ -470,9 +481,11 @@ elements have the identical value @var{object}.  Compare
 @defun append &rest sequences
 @cindex copying lists
 This function returns a list containing all the elements of
-@var{sequences}.  The @var{sequences} may be lists, vectors, or strings,
-but the last one should usually be a list.  All arguments except the
-last one are copied, so none of the arguments is altered.
+@var{sequences}.  The @var{sequences} may be lists, vectors,
+bool-vectors, or strings, but the last one should usually be a list.
+All arguments except the last one are copied, so none of the arguments
+is altered.  (See @code{nconc} in @ref{Rearrangement}, for a way to join
+lists with no copying.)
 
 More generally, the final argument to @code{append} may be any Lisp
 object.  The final argument is not copied or converted; it becomes the
@@ -482,9 +495,6 @@ result list.  If the final element is not a list, the result is a
 ``dotted list'' since its final @sc{cdr} is not @code{nil} as required
 in a true list.
 
-See @code{nconc} in @ref{Rearrangement}, for a way to join lists with no
-copying.
-
 Here is an example of using @code{append}:
 
 @example
@@ -517,8 +527,9 @@ original list:
 @group
 more-trees                trees
 |                           |
-|     ___ ___      ___ ___   -> ___ ___      ___ ___
- --> |___|___|--> |___|___|--> |___|___|--> |___|___|--> nil
+|     --- ---      --- ---   -> --- ---      --- ---
+ --> |   |   |--> |   |   |--> |   |   |--> |   |   |--> nil
+      --- ---      --- ---      --- ---      --- ---
        |            |            |            |
        |            |            |            |
         --> maple    -->birch     --> pine     --> oak
@@ -535,7 +546,7 @@ trees
      @result{} (pine oak)
 @end group
 @group
-(setq wood (append trees ()))
+(setq wood (append trees nil))
      @result{} (pine oak)
 @end group
 @group
@@ -552,6 +563,15 @@ wood
 This once was the usual way to copy a list, before the function
 @code{copy-sequence} was invented.  @xref{Sequences Arrays Vectors}.
 
+Here we show the use of vectors and strings as arguments to @code{append}:
+
+@example
+@group
+(append [a b] "cd" nil)
+     @result{} (a b 99 100)
+@end group
+@end example
+
 With the help of @code{apply}, we can append all the lists in a list of
 lists:
 
@@ -707,14 +727,16 @@ changes them both:
 
 @example
 @group
-        ___ ___        ___ ___      ___ ___
-x1---> |___|___|----> |___|___|--> |___|___|--> nil
+        --- ---        --- ---      --- ---
+x1---> |   |   |----> |   |   |--> |   |   |--> nil
+        --- ---        --- ---      --- ---
          |        -->   |            |
          |       |      |            |
           --> a  |       --> b        --> c
                  |
-       ___ ___   |
-x2--> |___|___|--
+       --- ---   |
+x2--> |   |   |--
+       --- ---
         |
         |
          --> z
@@ -904,6 +926,8 @@ x
 @end group
 @end example
 
+However, the other arguments (all but the last) must be lists.
+
 A common pitfall is to use a quoted constant list as a non-last
 argument to @code{nconc}.  If you do this, your program will change
 each time you run it!  Here is what happens:
@@ -1157,7 +1181,8 @@ and the @code{(4)} in the @code{sample-list} are not @code{eq}:
 @end example
 
 The following two functions are like @code{memq} and @code{delq} but use
-@code{equal} rather than @code{eq} to compare elements.
+@code{equal} rather than @code{eq} to compare elements.  @xref{Equality
+Predicates}.
 
 @defun member object list
 The function @code{member} tests to see whether @var{object} is a member
diff --git a/lispref/loading.texi b/lispref/loading.texi
index e3a72b3e318..44eac1cbe44 100644
--- a/lispref/loading.texi
+++ b/lispref/loading.texi
@@ -88,6 +88,10 @@ If you get a warning that @file{foo.elc} is older than @file{foo.el}, it
 means you should consider recompiling @file{foo.el}.  @xref{Byte
 Compilation}.
 
+When loading a source file (not compiled), @code{load} performs
+character set translation just as Emacs would do when visiting the file.
+@xref{Coding Systems}.
+
 Messages like @samp{Loading foo...} and @samp{Loading foo...done} appear
 in the echo area during loading unless @var{nomessage} is
 non-@code{nil}.
@@ -170,13 +174,6 @@ followed then by the @file{/user/bil/emacs} directory, the
 @file{/usr/local/lisplib} directory, and the @file{~/emacs} directory,
 which are then followed by the standard directories for Lisp code.
 
-The command line options @samp{-l} or @samp{-load} specify a Lisp
-library to load as part of Emacs startup.  Since this file might be in
-the current directory, Emacs 18 temporarily adds the current directory
-to the front of @code{load-path} so the file can be found there.  Newer
-Emacs versions also find such files in the current directory, but
-without altering @code{load-path}.
-
 Dumping Emacs uses a special value of @code{load-path}.  If the value of
 @code{load-path} at the end of dumping is unchanged (that is, still the
 same special value), the dumped Emacs switches to the ordinary
@@ -233,7 +230,7 @@ Normally, the variable's value is @code{nil}, which means those
 functions should use @code{read}.
 @end defvar
 
-  To learn how @code{load} is used to build Emacs, see @ref{Building Emacs}.
+  For how @code{load} is used to build Emacs, see @ref{Building Emacs}.
 
 @deffn Command locate-library library &optional nosuffix path interactive-call
 This command finds the precise file name for library @var{library}.  It
@@ -265,11 +262,11 @@ as if it had been loaded all along.
 @code{autoload}, and by writing a special ``magic'' comment in the
 source before the real definition.  @code{autoload} is the low-level
 primitive for autoloading; any Lisp program can call @code{autoload} at
-any time.  Magic comments do nothing on their own; they serve as a guide
-for the command @code{update-file-autoloads}, which constructs calls to
-@code{autoload} and arranges to execute them when Emacs is built.  Magic
-comments are the most convenient way to make a function autoload, but
-only for packages installed along with Emacs.
+any time.  Magic comments are the most convenient way to make a function
+autoload, for packages installed along with Emacs.  They do nothing on
+their own, but they serve as a guide for the command
+@code{update-file-autoloads}, which constructs calls to @code{autoload}
+and arranges to execute them when Emacs is built.
 
 @defun autoload function filename &optional docstring interactive type
 This function defines the function (or macro) named @var{function} so as
@@ -287,10 +284,10 @@ in the function definition itself.  Specifying the documentation string
 in the call to @code{autoload} makes it possible to look at the
 documentation without loading the function's real definition.
 
-If @var{interactive} is non-@code{nil}, then the function can be called
-interactively.  This lets completion in @kbd{M-x} work without loading
-the function's real definition.  The complete interactive specification
-is not given here; it's not needed unless the user actually calls
+If @var{interactive} is non-@code{nil}, that says @var{function} can be
+called interactively.  This lets completion in @kbd{M-x} work without
+loading its real definition.  The complete interactive specification is
+not given here; it's not needed unless the user actually calls
 @var{function}, and when that happens, it's time to load the real
 definition.
 
@@ -365,8 +362,9 @@ function definition, it is copied verbatim.  You can also use a magic
 comment to execute a form at build time @emph{without} executing it when
 the file itself is loaded.  To do this, write the form @emph{on the same
 line} as the magic comment.  Since it is in a comment, it does nothing
-when you load the source file; but @code{update-file-autoloads} copies
-it to @file{loaddefs.el}, where it is executed while building Emacs.
+when you load the source file; but @kbd{M-x update-file-autoloads}
+copies it to @file{loaddefs.el}, where it is executed while building
+Emacs.
 
   The following example shows how @code{doctor} is prepared for
 autoloading with a magic comment:
@@ -400,7 +398,7 @@ documentation string in the @file{etc/DOC} file.  @xref{Building Emacs}.
 @section Repeated Loading
 @cindex repeated loading
 
-  You may load one file more than once in an Emacs session.  For
+  You can load one file more than once in an Emacs session.  For
 example, after you have rewritten and reinstalled a function definition
 by editing it in a buffer, you may wish to return to the original
 version; you can do this by reloading the file it came from.
@@ -411,8 +409,8 @@ rather than a non-compiled file of similar name.  If you rewrite a file
 that you intend to save and reinstall, you need to byte-compile the new
 version; otherwise Emacs will load the older, byte-compiled file instead
 of your newer, non-compiled file!  If that happens, the message
-displayed when loading the file says, ``(compiled; source is newer'', to
-remind you to recompile.
+displayed when loading the file includes, @samp{(compiled; source is
+newer)}, to remind you to recompile it.
 
   When writing the forms in a Lisp library file, keep in mind that the
 file might be loaded more than once.  For example, think about whether
@@ -445,17 +443,17 @@ already been loaded.  Here's one way to test, in a library, whether it
 has been loaded before:
 
 @example
-(defvar foo-was-loaded)
+(defvar foo-was-loaded nil)
 
-(if (not (boundp 'foo-was-loaded))
-    @var{execute-first-time-only})
-
-(setq foo-was-loaded t)
+(unless foo-was-loaded
+  @var{execute-first-time-only}
+  (setq foo-was-loaded t))
 @end example
 
 @noindent
 If the library uses @code{provide} to provide a named feature, you can
-use @code{featurep} to test whether the library has been loaded.
+use @code{featurep} earlier in the file to test whether the
+@code{provide} call has been executed before.
 @ifinfo
 @xref{Named Features}.
 @end ifinfo
@@ -486,9 +484,6 @@ file should call @code{provide} at the top level to add the feature to
 @code{features}; if it fails to do so, @code{require} signals an error.
 @cindex load error with require
 
-  Features are normally named after the files that provide them, so that
-@code{require} need not be given the file name.
-
   For example, in @file{emacs/lisp/prolog.el}, 
 the definition for @code{run-prolog} includes the following code:
 
@@ -504,7 +499,8 @@ the definition for @code{run-prolog} includes the following code:
 @noindent
 The expression @code{(require 'comint)} loads the file @file{comint.el}
 if it has not yet been loaded.  This ensures that @code{make-comint} is
-defined.
+defined.  Features are normally named after the files that provide them,
+so that @code{require} need not be given the file name.
 
 The @file{comint.el} file contains the following top-level expression:
 
@@ -541,7 +537,7 @@ feature, as in the following example.
 The compiler ignores the @code{provide}, then processes the
 @code{require} by loading the file in question.  Loading the file does
 execute the @code{provide} call, so the subsequent @code{require} call
-does nothing while loading.
+does nothing when the file is loaded.
 
 @defun provide feature
 This function announces that @var{feature} is now loaded, or being
@@ -589,7 +585,7 @@ provided}.
 
 @defun featurep feature
 This function returns @code{t} if @var{feature} has been provided in the
-current Emacs session (i.e., @var{feature} is a member of
+current Emacs session (i.e., if @var{feature} is a member of
 @code{features}.)
 @end defun
 
@@ -612,10 +608,10 @@ reclaim memory for other Lisp objects.  To do this, use the function
 @deffn Command unload-feature feature &optional force
 This command unloads the library that provided feature @var{feature}.
 It undefines all functions, macros, and variables defined in that
-library with @code{defconst}, @code{defvar}, @code{defun},
-@code{defmacro}, @code{defsubst} and @code{defalias}.  It then restores
-any autoloads formerly associated with those symbols.  (Loading
-saves these in the @code{autoload} property of the symbol.)
+library with @code{defun}, @code{defalias}, @code{defsubst},
+@code{defmacro}, @code{defconst}, @code{defvar}, and @code{defcustom}.
+It then restores any autoloads formerly associated with those symbols.
+(Loading saves these in the @code{autoload} property of the symbol.)
 
 Ordinarily, @code{unload-feature} refuses to unload a library on which
 other loaded libraries depend.  (A library @var{a} depends on library
@@ -686,9 +682,9 @@ do (1), you can do it immediately---there is no need to wait for when
 the library is loaded.  To do (2), you must load the library (preferably
 with @code{require}).
 
-But it is ok to use @code{eval-after-load} in your personal customizations
-if you don't feel they must meet the design standards of programs to be
-released.
+But it is OK to use @code{eval-after-load} in your personal
+customizations if you don't feel they must meet the design standards for
+programs meant for wider use.
 
 @defvar after-load-alist
 An alist of expressions to evaluate if and when particular libraries are
diff --git a/lispref/locals.texi b/lispref/locals.texi
index 86e6750248c..7a93b817647 100644
--- a/lispref/locals.texi
+++ b/lispref/locals.texi
@@ -8,143 +8,151 @@
 @c The title "Standard Buffer-Local Variables" is too long for
 @c smallbook. --rjc 30mar92
 
-  The table below lists the general-purpose Emacs variables that are
-automatically local (when set) in each buffer.  Many Lisp packages
-define such variables for their internal use; we don't list them here.
+  The table below lists the general-purpose Emacs variables that
+automatically become buffer-local in each buffer.  Most become
+buffer-local only when set; a few of them are always local in every
+buffer.  Many Lisp packages define such variables for their internal
+use, but we don't try to list them all here.
 
 @table @code
 @item abbrev-mode
-@pxref{Abbrevs}
+@xref{Abbrevs}.
 
 @item auto-fill-function
-@pxref{Auto Filling}
+@xref{Auto Filling}.
 
 @item buffer-auto-save-file-name
-@pxref{Auto-Saving}
+@xref{Auto-Saving}.
 
 @item buffer-backed-up
-@pxref{Backup Files}
+@xref{Backup Files}.
+
+@item buffer-display-count
+@xref{Displaying Buffers}.
 
 @item buffer-display-table
-@pxref{Display Tables}
+@xref{Display Tables}.
 
 @item buffer-file-format
-@pxref{Format Conversion}
+@xref{Format Conversion}.
 
 @item buffer-file-name
-@pxref{Buffer File Name}
+@xref{Buffer File Name}.
 
 @item buffer-file-number
-@pxref{Buffer File Name}
+@xref{Buffer File Name}.
 
 @item buffer-file-truename
-@pxref{Buffer File Name}
+@xref{Buffer File Name}.
 
 @item buffer-file-type
-@pxref{Files and MS-DOS}
+@xref{MS-DOS File Types}.
 
 @item buffer-invisibility-spec
-@pxref{Invisible Text}
+@xref{Invisible Text}.
 
 @item buffer-offer-save
-@pxref{Saving Buffers}
+@xref{Saving Buffers}.
 
 @item buffer-read-only
-@pxref{Read Only Buffers}
+@xref{Read Only Buffers}.
 
 @item buffer-saved-size
-@pxref{Point}
+@xref{Point}.
 
 @item buffer-undo-list
-@pxref{Undo}
+@xref{Undo}.
 
 @item cache-long-line-scans
-@pxref{Text Lines}
+@xref{Text Lines}.
 
 @item case-fold-search
-@pxref{Searching and Case}
+@xref{Searching and Case}.
 
 @item ctl-arrow
-@pxref{Usual Display}
+@xref{Usual Display}.
 
 @item comment-column
-@pxref{Comments,,, emacs, The GNU Emacs Manual}
+@xref{Comments,,, emacs, The GNU Emacs Manual}.
 
 @item default-directory
-@pxref{System Environment}
+@xref{System Environment}.
 
 @item defun-prompt-regexp
-@pxref{List Motion}
+@xref{List Motion}.
+
+@item enable-multibyte-characters
+@ref{Non-ASCII Characters}.
 
 @item fill-column
-@pxref{Auto Filling}
+@xref{Auto Filling}.
 
 @item goal-column
-@pxref{Moving Point,,, emacs, The GNU Emacs Manual}
+@xref{Moving Point,,, emacs, The GNU Emacs Manual}.
 
 @item left-margin
-@pxref{Indentation}
+@xref{Indentation}.
 
 @item local-abbrev-table
-@pxref{Abbrevs}
+@xref{Abbrevs}.
 
 @item local-write-file-hooks
-@pxref{Saving Buffers}
+@xref{Saving Buffers}.
 
 @item major-mode
-@pxref{Mode Help}
+@xref{Mode Help}.
 
 @item mark-active
-@pxref{The Mark}
+@xref{The Mark}.
 
 @item mark-ring
-@pxref{The Mark}
+@xref{The Mark}.
 
 @item minor-modes
-@pxref{Minor Modes}
+@xref{Minor Modes}.
 
 @item mode-line-buffer-identification
-@pxref{Mode Line Variables}
+@xref{Mode Line Variables}.
 
 @item mode-line-format
-@pxref{Mode Line Data}
+@xref{Mode Line Data}.
 
 @item mode-line-modified
-@pxref{Mode Line Variables}
+@xref{Mode Line Variables}.
 
 @item mode-line-process
-@pxref{Mode Line Variables}
+@xref{Mode Line Variables}.
 
 @item mode-name
-@pxref{Mode Line Variables}
+@xref{Mode Line Variables}.
 
 @item overwrite-mode
-@pxref{Insertion}
+@xref{Insertion}.
 
 @item paragraph-separate
-@pxref{Standard Regexps}
+@xref{Standard Regexps}.
 
 @item paragraph-start
-@pxref{Standard Regexps}
+@xref{Standard Regexps}.
 
 @item point-before-scroll
-Used for communication between mouse commands and scroll-bar commands.
+Ued for communication between mouse commands and scroll-bar commands..
 
 @item require-final-newline
-@pxref{Insertion}
+@xref{Insertion}.
 
 @item selective-display
-@pxref{Selective Display}
+@xref{Selective Display}.
 
 @item selective-display-ellipses
-@pxref{Selective Display}
+@xref{Selective Display}.
 
 @item tab-width
-@pxref{Usual Display}
+@xref{Usual Display}.
 
 @item truncate-lines
-@pxref{Truncation}
+@xref{Truncation}.
 
 @item vc-mode
-@pxref{Mode Line Variables}
+@xref{Mode Line Variables}.
 @end table
diff --git a/lispref/macros.texi b/lispref/macros.texi
index 9ec72243562..b9e93bcf6d4 100644
--- a/lispref/macros.texi
+++ b/lispref/macros.texi
@@ -48,11 +48,12 @@ Here's a macro definition that does the job:
 @end group
 @end example
 
-  When this is called with @code{(inc x)}, the argument @code{var} has
-the value @code{x}---@emph{not} the @emph{value} of @code{x}.  The body
-of the macro uses this to construct the expansion, which is @code{(setq
-x (1+ x))}.  Once the macro definition returns this expansion, Lisp
-proceeds to evaluate it, thus incrementing @code{x}.
+  When this is called with @code{(inc x)}, the argument @var{var} is the
+symbol @code{x}---@emph{not} the @emph{value} of @code{x}, as it would
+be in a function.  The body of the macro uses this to construct the
+expansion, which is @code{(setq x (1+ x))}.  Once the macro definition
+returns this expansion, Lisp proceeds to evaluate it, thus incrementing
+@code{x}.
 
 @node Expansion
 @section Expansion of a Macro Call
@@ -192,6 +193,7 @@ like this:
 (macro lambda @var{argument-list} . @var{body-forms})
 @end example
 
+(Note that the @sc{cdr} of this list is a function---a lambda expression.)
 This macro object is stored in the function cell of @var{name}.  The
 value returned by evaluating the @code{defmacro} form is @var{name}, but
 usually we ignore this value.
@@ -210,8 +212,8 @@ called interactively.
 @findex `
 
   Macros often need to construct large list structures from a mixture of
-constants and nonconstant parts.  To make this easier, use the macro
-@samp{`} (often called @dfn{backquote}).
+constants and nonconstant parts.  To make this easier, use the @samp{`}
+syntax (usually called @dfn{backquote}).
 
   Backquote allows you to quote a list, but selectively evaluate
 elements of that list.  In the simplest case, it is identical to the
@@ -299,18 +301,16 @@ Here are some examples:
 @end group
 @end example
 
-@quotation
-Before Emacs version 19.29, @samp{`} used a different syntax which
-required an extra level of parentheses around the entire backquote
-construct.  Likewise, each @samp{,} or @samp{,@@} substition required an
-extra level of parentheses surrounding both the @samp{,} or @samp{,@@}
-and the following expression.  The old syntax required whitespace
-between the @samp{`}, @samp{,} or @samp{,@@} and the following
-expression.
+In old Emacs versions, before version 19.29, @samp{`} used a different
+syntax which required an extra level of parentheses around the entire
+backquote construct.  Likewise, each @samp{,} or @samp{,@@} substitution
+required an extra level of parentheses surrounding both the @samp{,} or
+@samp{,@@} and the following expression.  The old syntax required
+whitespace between the @samp{`}, @samp{,} or @samp{,@@} and the
+following expression.
 
 This syntax is still accepted, for compatibility with old Emacs
 versions, but we recommend not using it in new programs.
-@end quotation
 
 @node Problems with Macros
 @section Common Problems Using Macros
@@ -371,10 +371,10 @@ For example, (for i from 1 to 10 do (print i))."
 @end smallexample
 
 @noindent
-(The arguments @code{from}, @code{to}, and @code{do} in this macro are
+The arguments @code{from}, @code{to}, and @code{do} in this macro are
 ``syntactic sugar''; they are entirely ignored.  The idea is that you
 will write noise words (such as @code{from}, @code{to}, and @code{do})
-in those positions in the macro call.)
+in those positions in the macro call.
 
 Here's an equivalent definition simplified through use of backquote:
 
@@ -428,10 +428,8 @@ Here is a macro definition that creates this expansion:
 @end group
 @end smallexample
 
-  Unfortunately, this introduces another problem.
-@ifinfo
-Proceed to the following node.
-@end ifinfo
+  Unfortunately, this fix introduces another problem,
+described in the following section.
 
 @node Surprising Local Vars
 @subsection Local Variables in Macro Expansions
@@ -536,17 +534,18 @@ it.  Here is an example:
 @code{x}, because @code{a} conflicts with the macro argument variable
 @code{a}.
 
-  Another reason not to call @code{eval} in a macro definition is that
+  Another problem with calling @code{eval} in a macro definition is that
 it probably won't do what you intend in a compiled program.  The
 byte-compiler runs macro definitions while compiling the program, when
 the program's own computations (which you might have wished to access
 with @code{eval}) don't occur and its local variable bindings don't
 exist.
 
-  The safe way to work with the run-time value of an expression is to
-put the expression into the macro expansion, so that its value is
-computed as part of executing the expansion.  This is what the other
-examples in this chapter do.
+  To avoid these problems, @strong{don't evaluate an argument expression
+while computing the macro expansion.}  Instead, substitute the
+expression into the macro expansion, so that its value will be computed
+as part of executing the expansion.  This is how the other examples in
+this chapter work.
 
 @node Repeated Expansion
 @subsection How Many Times is the Macro Expanded?
@@ -557,15 +556,25 @@ expanded only once (during compilation) for a compiled function.  If the
 macro definition has side effects, they will work differently depending
 on how many times the macro is expanded.
 
-  In particular, constructing objects is a kind of side effect.  If the
-macro is called once, then the objects are constructed only once.  In
-other words, the same structure of objects is used each time the macro
-call is executed.  In interpreted operation, the macro is reexpanded
-each time, producing a fresh collection of objects each time.  Usually
-this does not matter---the objects have the same contents whether they
-are shared or not.  But if the surrounding program does side effects
-on the objects, it makes a difference whether they are shared.  Here is
-an example:
+  Therefore, you should avoid side effects in computation of the
+macro expansion, unless you really know what you are doing.
+
+  One special kind of side effect can't be avoided: constructing Lisp
+objects.  Almost all macro expansions include constructed lists; that is
+the whole point of most macros.  This is usually safe; there is just one
+case where you must be careful: when the object you construct is part of a
+quoted constant in the macro expansion.
+
+  If the macro is expanded just once, in compilation, then the object is
+constructed just once, during compilation.  But in interpreted
+execution, the macro is expanded each time the macro call runs, and this
+means a new object is constructed each time.
+
+  In most clean Lisp code, this difference won't matter.  It can matter
+only if you perform side-effects on the objects constructed by the macro
+definition.  Thus, to avoid trouble, @strong{avoid side effects on
+objects constructed by macro definitions}.  Here is an example of how
+such side effects can get you into trouble:
 
 @lisp
 @group
diff --git a/lispref/maps.texi b/lispref/maps.texi
index 77dc80001b9..78b5ceae979 100644
--- a/lispref/maps.texi
+++ b/lispref/maps.texi
@@ -29,15 +29,12 @@ A sparse keymap used by C mode.
 A full keymap used by Command History mode.
 
 @item ctl-x-4-map
-@vindex ctl-x-4-map
 A sparse keymap for subcommands of the prefix @kbd{C-x 4}.
 
 @item ctl-x-5-map
-@vindex ctl-x-5-map
 A sparse keymap for subcommands of the prefix @kbd{C-x 5}.
 
 @item ctl-x-map
-@vindex ctl-x-map
 A full keymap for @kbd{C-x} commands.
 
 @item debugger-mode-map
@@ -101,9 +98,9 @@ The keymap that displays the Special Props submenu of the Text
 Properties menu.
 
 @item function-key-map
-@vindex function-key-map
 The keymap for translating keypad and function keys.@*
 If there are none, then it contains an empty sparse keymap.
+@xref{Translating Input}.
 
 @item fundamental-mode-map
 @vindex fundamental-mode-map
@@ -130,9 +127,8 @@ A keymap that defines the characters you can type within incremental
 search.
 
 @item key-translation-map
-@vindex key-translation-map
 A keymap for translating keys.  This one overrides ordinary key
-bindings, unlike @code{function-key-map}.
+bindings, unlike @code{function-key-map}.  @xref{Translating Input}.
 
 @item lisp-interaction-mode-map
 @vindex lisp-interaction-mode-map
@@ -154,6 +150,11 @@ The keymap which displays the Files menu in the menu bar.
 @vindex menu-bar-help-menu
 The keymap which displays the Help menu in the menu bar.
 
+@tindex menu-bar-mule-menu
+@item menu-bar-mule-menu
+@vindex menu-bar-mule-menu
+The keymap which displays the Mule menu in the menu bar.
+
 @item menu-bar-search-menu
 @vindex menu-bar-search-menu
 The keymap which displays the Search menu in the menu bar.
@@ -163,7 +164,6 @@ The keymap which displays the Search menu in the menu bar.
 The keymap which displays the Tools menu in the menu bar.
 
 @item mode-specific-map
-@vindex mode-specific-map
 The keymap for characters following @kbd{C-c}.  Note, this is in the
 global map.  This map is not actually mode specific: its name was chosen
 to be informative for the user in @kbd{C-h b} (@code{display-bindings}),
@@ -174,7 +174,6 @@ where it describes the main use of the @kbd{C-c} prefix key.
 A local keymap used by Occur mode.
 
 @item query-replace-map
-@vindex query-replace-map
 A local keymap used for responses in @code{query-replace} and related
 commands; also for @code{y-or-n-p} and @code{map-y-or-n-p}.  The functions
 that use this map do not support prefix keys; they look up one event at a
diff --git a/lispref/markers.texi b/lispref/markers.texi
index ecd0978a227..6a475b7a01e 100644
--- a/lispref/markers.texi
+++ b/lispref/markers.texi
@@ -44,9 +44,10 @@ buffer.  Relocation changes the integer equivalent of the marker.
 @cindex marker relocation
   Deleting text around a marker's position leaves the marker between the
 characters immediately before and after the deleted text.  Inserting
-text at the position of a marker normally leaves the marker in front of
-the new text---unless it is inserted with @code{insert-before-markers}
-(@pxref{Insertion}).
+text at the position of a marker normally leaves the marker either in
+front of or after the new text, depending on the marker's @dfn{insertion
+type} (@pxref{Marker Insertion Types})---unless the insertion is done
+with @code{insert-before-markers} (@pxref{Insertion}).
 
 @cindex marker garbage collection
   Insertion and deletion in a buffer must check all the markers and
@@ -306,7 +307,9 @@ if they both point nowhere.
   When you insert text directly at the place where a marker points,
 there are two possible ways to relocate that marker: it can point before
 the inserted text, or point after it.  You can specify which one a given
-marker should do by setting its @dfn{insertion type}.
+marker should do by setting its @dfn{insertion type}.  Note that use of
+@code{insert-before-markers} ignores markers' insertion types, always
+relocating a marker to point after the inserted text.
 
 @tindex set-marker-insertion-type
 @defun set-marker-insertion-type marker type
@@ -396,11 +399,12 @@ absence of a mark in that buffer.''
 
   Once the mark ``exists'' in a buffer, it normally never ceases to
 exist.  However, it may become @dfn{inactive}, if Transient Mark mode is
-enabled.  The variable @code{mark-active}, which is always local in all
-buffers, indicates whether the mark is active: non-@code{nil} means yes.
-A command can request deactivation of the mark upon return to the editor
-command loop by setting @code{deactivate-mark} to a non-@code{nil} value
-(but this causes deactivation only if Transient Mark mode is enabled).
+enabled.  The variable @code{mark-active}, which is always buffer-local
+in all buffers, indicates whether the mark is active: non-@code{nil}
+means yes.  A command can request deactivation of the mark upon return
+to the editor command loop by setting @code{deactivate-mark} to a
+non-@code{nil} value (but this causes deactivation only if Transient
+Mark mode is enabled).
 
   The main motivation for using Transient Mark mode is that this mode
 also enables highlighting of the region when the mark is active.
@@ -529,20 +533,30 @@ consequence of this is that commands that modify the buffer normally
 make the mark inactive.
 @end defopt
 
+@defopt mark-even-if-inactive
+If this is non-@code{nil}, Lisp programs and the Emacs user can use the
+mark even when it is inactive.  This option affects the behavior of
+Transient Mark mode.  When the option is non-@code{nil}, deactivation of
+the mark turns off region highlighting, but commands that use the mark
+behave as if the mark were still active.
+@end defopt
+
 @defvar deactivate-mark
 If an editor command sets this variable non-@code{nil}, then the editor
-command loop deactivates the mark after the command returns, but only if
-Transient Mark mode is enabled.
+command loop deactivates the mark after the command returns (if
+Transient Mark mode is enabled).  All the primitives that change the
+buffer set @code{deactivate-mark}, to deactivate the mark when the
+command is finished.
 @end defvar
 
 @defun deactivate-mark
-This function deactivates the mark, but only if Transient Mark mode
-is enabled.
+This function deactivates the mark, if Transient Mark mode is enabled.
+Otherwise it does nothing.
 @end defun
 
 @defvar mark-active
 The mark is active when this variable is non-@code{nil}.  This variable
-is always local in each buffer.
+is always buffer-local in each buffer.
 @end defvar
 
 @defvar activate-mark-hook
diff --git a/lispref/minibuf.texi b/lispref/minibuf.texi
index 16d5f60d4e5..0ff8e79c1ca 100644
--- a/lispref/minibuf.texi
+++ b/lispref/minibuf.texi
@@ -13,8 +13,8 @@
 arguments more complicated than the single numeric prefix argument.
 These arguments include file names, buffer names, and command names (as
 in @kbd{M-x}).  The minibuffer is displayed on the bottom line of the
-screen, in the same place as the echo area, but only while it is in
-use for reading an argument.
+frame, in the same place as the echo area, but only while it is in use
+for reading an argument.
 
 @menu
 * Intro to Minibuffers::      Basic information about minibuffers.
@@ -100,26 +100,25 @@ string; however, if @var{read} is non-@code{nil}, then it uses
 @code{read} to convert the text into a Lisp object (@pxref{Input
 Functions}).
 
-The first thing this function does is to activate a minibuffer and 
+The first thing this function does is to activate a minibuffer and
 display it with @var{prompt-string} as the prompt.  This value must be a
-string.
-
-Then, if @var{initial-contents} is a string, @code{read-from-minibuffer}
-inserts it into the minibuffer, leaving point at the end.  The
-minibuffer appears with this text as its contents.
+string.  Then the user can edit text in the minibuffer.
 
-@strong{Usage note:} The @var{initial-contents} argument and the
-@var{default} argument are two alternative features for the same job.
-It usually does not make sense to use both at once.  In most cases, you
-should use @var{default}, since this permits the user to insert the
-default value but does not burden the user with deleting it from the
-minibuffer.
+When the user types a command to exit the minibuffer,
+@code{read-from-minibuffer} constructs the return value from the text in
+the minibuffer.  Normally it returns a string containing that text.
+However, if @var{read} is non-@code{nil}, @code{read-from-minibuffer}
+reads the text and returns the resulting Lisp object, unevaluated.
+(@xref{Input Functions}, for information about reading.)
 
-@c Emacs 19 feature
-The value of @var{initial-contents} may also be a cons cell of the form
-@code{(@var{string} . @var{position})}.  This means to insert
-@var{string} in the minibuffer but put point @var{position} characters
-from the beginning, rather than at the end.
+The argument @var{default} specifies a default value to make available
+through the history commands.  It should be a string, or @code{nil}.  If
+@var{read} is non-@code{nil}, then @var{default} is also used as the
+input to @code{read}, if the user enters empty input.  However, in the
+usual case (where @var{read} is @code{nil}, @code{read-from-minibuffer}
+does not return @var{default} when the user enters empty input; it
+returns an empty string, @code{""}.  In this respect, it is different
+from all the other minibuffer input functions in this chapter.
 
 If @var{keymap} is non-@code{nil}, that keymap is the local keymap to
 use in the minibuffer.  If @var{keymap} is omitted or @code{nil}, the
@@ -131,30 +130,33 @@ The argument @var{hist} specifies which history list variable to use
 for saving the input and for history commands used in the minibuffer.
 It defaults to @code{minibuffer-history}.  @xref{Minibuffer History}.
 
-When the user types a command to exit the minibuffer,
-@code{read-from-minibuffer} uses the text in the minibuffer to produce
-its return value.  Normally it simply makes a string containing that
-text.  However, if @var{read} is non-@code{nil},
-@code{read-from-minibuffer} reads the text and returns the resulting
-Lisp object, unevaluated.  (@xref{Input Functions}, for information
-about reading.)
-
 If the variable @code{minibuffer-allow-text-properties} is
 non-@code{nil}, then the string which is returned includes whatever text
 properties were present in the minibuffer.  Otherwise all the text
 properties are stripped when the value is returned.
 
-The argument @var{default} specifies a default value to make available
-through the history list.  It should be a string, or @code{nil}.  If
-@var{read} is non-@code{nil}, then @var{default} is passed through
-@code{read}, just as ordinary user input would be.  Unlike many other
-minibuffer functions, this function does @emph{not} return @var{default}
-if the user enters empty input.  It returns @code{""} in that case.
-
 If the argument @var{inherit-input-method} is non-@code{nil}, then the
 minibuffer inherits the current input method and the setting of
 @code{enable-multibyte-characters} from whichever buffer was current
 before entering the minibuffer.
+
+If @var{initial-contents} is a string, @code{read-from-minibuffer}
+inserts it into the minibuffer, leaving point at the end, before the
+user starts to edit the text.  The minibuffer appears with this text as
+its initial contents.
+
+Alternatively, @var{initial-contents} can be a cons cell of the form
+@code{(@var{string} . @var{position})}.  This means to insert
+@var{string} in the minibuffer but put point @var{position} characters
+from the beginning, rather than at the end.
+
+@strong{Usage note:} The @var{initial-contents} argument and the
+@var{default} argument are two alternative features for more or less the
+same job.  It does not make sense to use both features in a single call
+to @code{read-from-minibuffer}.  In general, we recommend using
+@var{default}, since this permits the user to insert the default value
+when it is wanted, but does not burden the user with deleting it from
+the minibuffer on other occasions.
 @end defun
 
 @defun read-string prompt &optional initial history default inherit-input-method
@@ -177,8 +179,12 @@ This function is a simplified interface to the
 @group
 (read-string @var{prompt} @var{initial} @var{history} @var{default} @var{inherit})
 @equiv{}
-(read-from-minibuffer @var{prompt} @var{initial} nil nil
-                      @var{history} @var{default} @var{inherit})
+(let ((value
+       (read-from-minibuffer @var{prompt} @var{initial} nil nil
+                             @var{history} @var{default} @var{inherit})))
+  (if (equal value "")
+      @var{default}
+    value))
 @end group
 @end smallexample
 @end defun
@@ -195,7 +201,7 @@ This is the default local keymap for reading from the minibuffer.  By
 default, it makes the following bindings:
 
 @table @asis
-@item @key{LFD}
+@item @kbd{C-j}
 @code{exit-minibuffer}
 
 @item @key{RET}
@@ -368,16 +374,16 @@ expression, thus moving point forward one word.
 @cindex minibuffer history
 @cindex history list
 
-A @dfn{minibuffer history list} records previous minibuffer inputs so
+  A @dfn{minibuffer history list} records previous minibuffer inputs so
 the user can reuse them conveniently.  A history list is actually a
 symbol, not a list; it is a variable whose value is a list of strings
 (previous inputs), most recent first.
 
-There are many separate history lists, used for different kinds of
+  There are many separate history lists, used for different kinds of
 inputs.  It's the Lisp programmer's job to specify the right history
 list for each use of the minibuffer.
 
-The basic minibuffer input functions @code{read-from-minibuffer} and
+  The basic minibuffer input functions @code{read-from-minibuffer} and
 @code{completing-read} both accept an optional argument named @var{hist}
 which is how you specify the history list.  Here are the possible
 values:
@@ -395,18 +401,20 @@ If you specify @var{startpos}, then you should also specify that element
 of the history as the initial minibuffer contents, for consistency.
 @end table
 
-If you don't specify @var{hist}, then the default history list
+  If you don't specify @var{hist}, then the default history list
 @code{minibuffer-history} is used.  For other standard history lists,
 see below.  You can also create your own history list variable; just
 initialize it to @code{nil} before the first use.
 
-Both @code{read-from-minibuffer} and @code{completing-read} add new
+  Both @code{read-from-minibuffer} and @code{completing-read} add new
 elements to the history list automatically, and provide commands to
 allow the user to reuse items on the list.  The only thing your program
 needs to do to use a history list is to initialize it and to pass its
 name to the input functions when you wish.  But it is safe to modify the
 list by hand when the minibuffer input functions are not using it.
 
+  Here are some of the standard minibuffer history list variables:
+
 @defvar minibuffer-history
 The default history list for minibuffer history input.
 @end defvar
@@ -580,7 +588,7 @@ too short).  Both of those begin with the string @samp{foobar}.
 
 @defun all-completions string collection &optional predicate nospace
 This function returns a list of all possible completions of
-@var{string}.  The parameters to this function are the same as to
+@var{string}.  The arguments to this function are the same as those of
 @code{try-completion}.
 
 If @var{collection} is a function, it is called with three arguments:
@@ -624,10 +632,7 @@ minibuffer with completion.
 @defun completing-read prompt collection &optional predicate require-match initial hist default inherit-input-method
 This function reads a string in the minibuffer, assisting the user by
 providing completion.  It activates the minibuffer with prompt
-@var{prompt}, which must be a string.  If @var{initial} is
-non-@code{nil}, @code{completing-read} inserts it into the minibuffer as
-part of the input.  Then it allows the user to edit the input, providing
-several commands to attempt completion.
+@var{prompt}, which must be a string.
 
 The actual completion is done by passing @var{collection} and
 @var{predicate} to the function @code{try-completion}.  This happens in
@@ -642,7 +647,8 @@ input already in the buffer matches an element of @var{collection}.
 
 However, empty input is always permitted, regardless of the value of
 @var{require-match}; in that case, @code{completing-read} returns
-@var{default}.
+@var{default}.  The value of @var{default} (if non-@code{nil}) is also
+available to the user through the history commands.
 
 The user can exit with null input by typing @key{RET} with an empty
 minibuffer.  Then @code{completing-read} returns @code{""}.  This is how
@@ -661,8 +667,10 @@ The argument @var{hist} specifies which history list variable to use for
 saving the input and for minibuffer history commands.  It defaults to
 @code{minibuffer-history}.  @xref{Minibuffer History}.
 
-The optional argument @var{default} specifies a default value to return
-if the user enters null input; it should be a string.
+If @var{initial} is non-@code{nil}, @code{completing-read} inserts it
+into the minibuffer as part of the input.  Then it allows the user to
+edit the input, providing several commands to attempt completion.
+In most cases, we recommend using @var{default}, and not @var{initial}.
 
 If the argument @var{inherit-input-method} is non-@code{nil}, then the
 minibuffer inherits the current input method and the setting of
@@ -750,7 +758,7 @@ bindings:
 @item @key{TAB}
 @code{minibuffer-complete}
 
-@item @key{LFD}
+@item @kbd{C-j}
 @code{minibuffer-complete-and-exit}
 
 @item @key{RET}
@@ -903,10 +911,10 @@ which @code{commandp} returns @code{t}, and a command name is a symbol
 for which @code{commandp} returns @code{t}.  @xref{Interactive Call}.
 
 The argument @var{default} specifies what to return if the user enters
-null input.  It can be a symbol or a string, but the value returned by
-@code{read-command} is always a symbol.  If @var{default} is @code{nil},
-that means no default has been specified; then if the user enters null
-input, the return value is @code{nil}.
+null input.  It can be a symbol or a string; if it is a string,
+@code{read-command} interns it before returning it.  If @var{default} is
+@code{nil}, that means no default has been specified; then if the user
+enters null input, the return value is @code{nil}.
 
 @example
 (read-command "Command name? ")
@@ -948,10 +956,10 @@ This function reads the name of a user variable and returns it as a
 symbol.
 
 The argument @var{default} specifies what to return if the user enters
-null input.  It can be a symbol or a string, but the value returned by
-@code{read-variable} is always a symbol.  If @var{default} is
-@code{nil}, that means no default has been specified; then if the user
-enters null input, the return value is @code{nil}.
+null input.  It can be a symbol or a string; if it is a string,
+@code{read-variable} interns it before returning it.  If @var{default}
+is @code{nil}, that means no default has been specified; then if the
+user enters null input, the return value is @code{nil}.
 
 @example
 @group
@@ -988,21 +996,8 @@ predicate @code{user-variable-p} instead of @code{commandp}:
 @end example
 @end defun
 
-@tindex read-coding-system
-@defun read-coding-system prompt default
-This function reads a coding system using the minibuffer, prompting with
-string @var{prompt}, and returns the coding system name as a symbol.  If
-the user tries to enter null input, it asks the user to try again.
-@xref{Coding Systems}.
-@end defun
-
-@tindex read-non-nil-coding-system
-@defun read-non-nil-coding-system prompt
-This function reads a coding system using the minibuffer, prompting with
-string @var{prompt},and returns the coding system name as a symbol.  If
-the user enters null input, it returns @var{default-coding-system}.
-which should be a symbol or a string.  @xref{Coding Systems}.
-@end defun
+  See also the functions @code{read-coding-system} and
+@code{read-non-nil-coding-system}, in @ref{Lisp and Coding Systems}.
 
 @node Reading File Names
 @subsection Reading File Names
@@ -1037,7 +1032,8 @@ If you specify @var{initial}, that is an initial file name to insert in
 the buffer (after with @var{directory}, if that is inserted).  In this
 case, point goes at the beginning of @var{initial}.  The default for
 @var{initial} is @code{nil}---don't insert any file name.  To see what
-@var{initial} does, try the command @kbd{C-x C-v}.
+@var{initial} does, try the command @kbd{C-x C-v}.  @strong{Note:} we
+recommend using @var{default} rather than @var{initial} in most cases.
 
 Here is an example: 
 
@@ -1153,7 +1149,7 @@ string is a unique and exact match already, or @code{nil} if the string
 matches no possibility.
 
 If the string is an exact match for one possibility, but also matches
-other longer possibilities, the function shuold return the string, not
+other longer possibilities, the function should return the string, not
 @code{t}.
 
 @item
@@ -1533,15 +1529,14 @@ returns zero.
 
 @defopt enable-recursive-minibuffers
 If this variable is non-@code{nil}, you can invoke commands (such as
-@code{find-file}) that use minibuffers even while in the minibuffer
-window.  Such invocation produces a recursive editing level for a new
+@code{find-file}) that use minibuffers even while the minibuffer window
+is active.  Such invocation produces a recursive editing level for a new
 minibuffer.  The outer-level minibuffer is invisible while you are
 editing the inner one.
 
-This variable only affects invoking the minibuffer while the
-minibuffer window is selected.   If you switch windows while in the 
-minibuffer, you can always invoke minibuffer commands while some other
-window is selected.
+If this variable is @code{nil}, you cannot invoke minibuffer
+commands when the minibuffer window is active, not even if you switch to
+another window to do it.
 @end defopt
 
 @c Emacs 19 feature
diff --git a/lispref/modes.texi b/lispref/modes.texi
index 2e2f1c3bb29..dbdefb5a2d3 100644
--- a/lispref/modes.texi
+++ b/lispref/modes.texi
@@ -41,7 +41,7 @@ This mode has no mode-specific definitions or variable settings, so each
 Emacs command behaves in its default manner, and each option is in its
 default state.  All other major modes redefine various keys and options.
 For example, Lisp Interaction mode provides special key bindings for
-@key{LFD} (@code{eval-print-last-sexp}), @key{TAB}
+@kbd{C-j} (@code{eval-print-last-sexp}), @key{TAB}
 (@code{lisp-indent-line}), and other keys.
 
   When you need to write several editing commands to help you perform a
@@ -58,16 +58,16 @@ Modes}).  For example, Rmail Edit mode, which is in
 Text mode except that it provides three additional commands.  Its
 definition is distinct from that of Text mode, but was derived from it.
 
-  Rmail Edit mode is an example of a case where one piece of text is put
-temporarily into a different major mode so it can be edited in a
-different way (with ordinary Emacs commands rather than Rmail).  In such
-cases, the temporary major mode usually has a command to switch back to
-the buffer's usual mode (Rmail mode, in this case).  You might be
-tempted to present the temporary redefinitions inside a recursive edit
-and restore the usual ones when the user exits; but this is a bad idea
-because it constrains the user's options when it is done in more than
-one buffer: recursive edits must be exited most-recently-entered first.
-Using alternative major modes avoids this limitation.  @xref{Recursive
+  Rmail Edit mode offers an example of changing the major mode
+temporarily for a buffer, so it can be edited in a different way (with
+ordinary Emacs commands rather than Rmail).  In such cases, the
+temporary major mode usually has a command to switch back to the
+buffer's usual mode (Rmail mode, in this case).  You might be tempted to
+present the temporary redefinitions inside a recursive edit and restore
+the usual ones when the user exits; but this is a bad idea because it
+constrains the user's options when it is done in more than one buffer:
+recursive edits must be exited most-recently-entered first.  Using an
+alternative major mode avoids this limitation.  @xref{Recursive
 Editing}.
 
   The standard GNU Emacs Lisp library directory contains the code for
@@ -98,8 +98,8 @@ define a new major mode:
 @item
 Define a command whose name ends in @samp{-mode}, with no arguments,
 that switches to the new mode in the current buffer.  This command
-should set up the keymap, syntax table, and local variables in an
-existing buffer without changing the buffer's text.
+should set up the keymap, syntax table, and buffer-local variables in an
+existing buffer, without changing the buffer's contents.
 
 @item
 Write a documentation string for this command that describes the
@@ -114,8 +114,8 @@ Documentation}.
 
 @item
 The major mode command should start by calling
-@code{kill-all-local-variables}.  This is what gets rid of the local
-variables of the major mode previously in effect.
+@code{kill-all-local-variables}.  This is what gets rid of the
+buffer-local variables of the major mode previously in effect.
 
 @item
 The major mode command should set the variable @code{major-mode} to the
@@ -124,8 +124,8 @@ which documentation to print.
 
 @item
 The major mode command should set the variable @code{mode-name} to the
-``pretty'' name of the mode, as a string.  This appears in the mode
-line.
+``pretty'' name of the mode, as a string.  This string appears in the
+mode line.
 
 @item
 @cindex functions in modes
@@ -137,11 +137,11 @@ of it if the name is long).  @xref{Coding Conventions}.
 @item
 @cindex keymaps in modes
 The major mode should usually have its own keymap, which is used as the
-local keymap in all buffers in that mode.  The major mode function
-should call @code{use-local-map} to install this local map.
-@xref{Active Keymaps}, for more information.
+local keymap in all buffers in that mode.  The major mode command should
+call @code{use-local-map} to install this local map.  @xref{Active
+Keymaps}, for more information.
 
-This keymap should be kept in a global variable named
+This keymap should be stored permanently in a global variable named
 @code{@var{modename}-mode-map}.  Normally the library that defines the
 mode sets this variable.
 
@@ -150,7 +150,7 @@ up the mode's keymap variable.
 
 @item
 The key sequences bound in a major mode keymap should usually start with
-@kbd{C-c}, followed by a control-character, a digit, or @kbd{@{},
+@kbd{C-c}, followed by a control character, a digit, or @kbd{@{},
 @kbd{@}}, @kbd{<}, @kbd{>}, @kbd{:} or @kbd{;}.  The other punctuation
 characters are reserved for minor modes, and ordinary letters are
 reserved for users.
@@ -186,23 +186,20 @@ a variable named @code{@var{modename}-mode-abbrev-table}.  @xref{Abbrev
 Tables}.
 
 @item
-@vindex font-lock-defaults
 The mode should specify how to do highlighting for Font Lock mode, by
 setting up a buffer-local value for the variable
-@code{font-lock-defaults}.
+@code{font-lock-defaults} (@pxref{Font Lock Mode}).
 
 @item
-@vindex imenu-generic-expression
-@vindex imenu-create-index-function
 The mode should specify how Imenu should find the definitions or
 sections of a buffer, by setting up a buffer-local value for the
 variable @code{imenu-generic-expression} or
-@code{imenu-create-index-function}.
+@code{imenu-create-index-function} (@pxref{Imenu}).
 
 @item
-Use @code{defvar} to set mode-related variables, so that they are not
-reinitialized if they already have a value.  (Such reinitialization
-could discard customizations made by the user.)
+Use @code{defvar} or @code{defcustom} to set mode-related variables, so
+that they are not reinitialized if they already have a value.  (Such
+reinitialization could discard customizations made by the user.)
 
 @item
 @cindex buffer-local variables in modes
@@ -213,7 +210,7 @@ variable local to every buffer in which it is subsequently set, which
 would affect buffers that do not use this mode.  It is undesirable for a
 mode to have such global effects.  @xref{Buffer-Local Variables}.
 
-It's ok to use @code{make-variable-buffer-local}, if you wish, for a
+It's OK to use @code{make-variable-buffer-local}, if you wish, for a
 variable used only within a single Lisp package.
 
 @item
@@ -234,7 +231,7 @@ or it may run them earlier.
 @item
 If something special should be done if the user switches a buffer from
 this mode to any other major mode, this mode can set up a buffer-local
-value for @code{change-major-mode-hook} (see below).
+value for @code{change-major-mode-hook} (@pxref{Creating Buffer-Local}).
 
 @item
 If this mode is appropriate only for specially-prepared text, then the
@@ -273,15 +270,6 @@ that they may be evaluated more than once without adverse consequences.
 Even if you never load the file more than once, someone else will.
 @end itemize
 
-@defvar change-major-mode-hook
-The function @code{kill-all-local-variables} runs this normal hook
-before it does anything else.  This gives major modes a way to arrange
-for something special to be done if the user switches to a different
-major mode.  For best results, make this variable buffer-local, so that
-it will disappear after doing its job and will not interfere with the
-subsequent major mode.  @xref{Hooks}.
-@end defvar
-
 @node Example Major Modes
 @subsection Major Mode Examples
 
@@ -328,21 +316,28 @@ the conventions listed above:
 @smallexample
 @group
 (defun text-mode ()
-  "Major mode for editing text intended for humans to read. 
+  "Major mode for editing text intended for humans to read@enddots{}
  Special commands: \\@{text-mode-map@}
 @end group
 @group
 Turning on text-mode runs the hook `text-mode-hook'."
   (interactive)
   (kill-all-local-variables)
+  (use-local-map text-mode-map)
 @end group
 @group
-  (use-local-map text-mode-map)     ; @r{This provides the local keymap.}
-  (setq mode-name "Text")           ; @r{This name goes into the mode line.}
-  (setq major-mode 'text-mode)      ; @r{This is how @code{describe-mode}}
-                                    ;   @r{finds the doc string to print.}
   (setq local-abbrev-table text-mode-abbrev-table)
   (set-syntax-table text-mode-syntax-table)
+@end group
+@group
+  (make-local-variable 'paragraph-start)
+  (setq paragraph-start (concat "[ \t]*$\\|" page-delimiter))
+  (make-local-variable 'paragraph-separate)
+  (setq paragraph-separate paragraph-start)
+@end group
+@group
+  (setq mode-name "Text")
+  (setq major-mode 'text-mode)
   (run-hooks 'text-mode-hook))      ; @r{Finally, this permits the user to}
                                     ;   @r{customize the mode with a hook.}
 @end group
@@ -401,27 +396,8 @@ mode functions:
 @smallexample
 @group
 (defun lisp-mode-variables (lisp-syntax)
-  ;; @r{The @code{lisp-syntax} argument is @code{nil} in Emacs Lisp mode,}
-  ;;   @r{and @code{t} in the other two Lisp modes.}
   (cond (lisp-syntax
-         (if (not lisp-mode-syntax-table)
-             ;; @r{The Emacs Lisp mode syntax table always exists, but}
-             ;;   @r{the Lisp Mode syntax table is created the first time a}
-             ;;   @r{mode that needs it is called.  This is to save space.}
-@end group
-@group
-             (progn (setq lisp-mode-syntax-table
-                       (copy-syntax-table emacs-lisp-mode-syntax-table))
-                    ;; @r{Change some entries for Lisp mode.}
-                    (modify-syntax-entry ?\| "\"   "
-                                         lisp-mode-syntax-table)
-                    (modify-syntax-entry ?\[ "_   "
-                                         lisp-mode-syntax-table)
-                    (modify-syntax-entry ?\] "_   "
-                                         lisp-mode-syntax-table)))
-@end group
-@group
-          (set-syntax-table lisp-mode-syntax-table)))
+          (set-syntax-table lisp-mode-syntax-table)))
   (setq local-abbrev-table lisp-mode-abbrev-table)
   @dots{})
 @end group
@@ -438,9 +414,9 @@ rest of @code{lisp-mode-variables}.
 @smallexample
 @group
   (make-local-variable 'paragraph-start)
-  ;; @r{Having @samp{^} is not clean, but @code{page-delimiter}}
-  ;; @r{has them too, and removing those is a pain.}
-  (setq paragraph-start (concat "^$\\|" page-delimiter))
+  (setq paragraph-start (concat page-delimiter "\\|$" ))
+  (make-local-variable 'paragraph-separate)
+  (setq paragraph-separate paragraph-start)
   @dots{}
 @end group
 @group
@@ -452,35 +428,36 @@ rest of @code{lisp-mode-variables}.
   Each of the different Lisp modes has a slightly different keymap.  For
 example, Lisp mode binds @kbd{C-c C-z} to @code{run-lisp}, but the other
 Lisp modes do not.  However, all Lisp modes have some commands in
-common.  The following function adds these common commands to a given
-keymap.
+common.  The following code sets up the common commands:
 
 @smallexample
 @group
-(defun lisp-mode-commands (map)
-  (define-key map "\e\C-q" 'indent-sexp)
-  (define-key map "\177" 'backward-delete-char-untabify)
-  (define-key map "\t" 'lisp-indent-line))
+(defvar shared-lisp-mode-map ()
+  "Keymap for commands shared by all sorts of Lisp modes.")
+
+(if shared-lisp-mode-map
+    ()
+   (setq shared-lisp-mode-map (make-sparse-keymap))
+   (define-key shared-lisp-mode-map "\e\C-q" 'indent-sexp)
+   (define-key shared-lisp-mode-map "\177"
+               'backward-delete-char-untabify))
 @end group
 @end smallexample
 
-  Here is an example of using @code{lisp-mode-commands} to initialize a
-keymap, as part of the code for Emacs Lisp mode.  First we declare a
-variable with @code{defvar} to hold the mode-specific keymap.  When this
-@code{defvar} executes, it sets the variable to @code{nil} if it was
-void.  Then we set up the keymap if the variable is @code{nil}.
-
-  This code avoids changing the keymap or the variable if it is already
-set up.  This lets the user customize the keymap.
+@noindent
+And here is the code to set up the keymap for Lisp mode:
 
 @smallexample
 @group
-(defvar emacs-lisp-mode-map () "") 
-(if emacs-lisp-mode-map
+(defvar lisp-mode-map ()
+  "Keymap for ordinary Lisp mode@enddots{}")
+
+(if lisp-mode-map
     ()
-  (setq emacs-lisp-mode-map (make-sparse-keymap))
-  (define-key emacs-lisp-mode-map "\e\C-x" 'eval-defun)
-  (lisp-mode-commands emacs-lisp-mode-map))
+  (setq lisp-mode-map (make-sparse-keymap))
+  (set-keymap-parent lisp-mode-map shared-lisp-mode-map)
+  (define-key lisp-mode-map "\e\C-x" 'lisp-eval-defun)
+  (define-key lisp-mode-map "\C-c\C-z" 'run-lisp))
 @end group
 @end smallexample
 
@@ -489,26 +466,33 @@ Emacs Lisp mode.
 
 @smallexample
 @group
-(defun emacs-lisp-mode ()
-  "Major mode for editing Lisp code to run in Emacs.
+(defun lisp-mode ()
+  "Major mode for editing Lisp code for Lisps other than GNU Emacs Lisp.
 Commands:
 Delete converts tabs to spaces as it moves back.
 Blank lines separate paragraphs.  Semicolons start comments.
-\\@{emacs-lisp-mode-map@}
+\\@{lisp-mode-map@}
+Note that `run-lisp' may be used either to start an inferior Lisp job
+or to switch back to an existing one.
 @end group
+
 @group
-Entry to this mode runs the hook `emacs-lisp-mode-hook'."
+Entry to this mode calls the value of `lisp-mode-hook'
+if that value is non-nil."
   (interactive)
   (kill-all-local-variables)
-  (use-local-map emacs-lisp-mode-map)    ; @r{This provides the local keymap.}
-  (set-syntax-table emacs-lisp-mode-syntax-table)
 @end group
 @group
-  (setq major-mode 'emacs-lisp-mode)     ; @r{This is how @code{describe-mode}}
+  (use-local-map lisp-mode-map)          ; @r{Select the mode's keymap.}
+  (setq major-mode 'lisp-mode)           ; @r{This is how @code{describe-mode}}
                                          ;   @r{finds out what to describe.}
-  (setq mode-name "Emacs-Lisp")          ; @r{This goes into the mode line.}
-  (lisp-mode-variables nil)              ; @r{This defines various variables.}
-  (run-hooks 'emacs-lisp-mode-hook))     ; @r{This permits the user to use a}
+  (setq mode-name "Lisp")                ; @r{This goes into the mode line.}
+  (lisp-mode-variables t)                ; @r{This defines various variables.}
+@end group
+@group
+  (setq imenu-case-fold-search t)
+  (set-syntax-table lisp-mode-syntax-table)
+  (run-hooks 'lisp-mode-hook))           ; @r{This permits the user to use a}
                                          ;   @r{hook to customize the mode.}
 @end group
 @end smallexample
@@ -518,7 +502,7 @@ Entry to this mode runs the hook `emacs-lisp-mode-hook'."
 
   Based on information in the file name or in the file itself, Emacs
 automatically selects a major mode for the new buffer when a file is
-visited.
+visited.  It also processes local variables specified in the file text.
 
 @deffn Command fundamental-mode
   Fundamental mode is a major mode that is not specialized for anything
@@ -531,22 +515,22 @@ state of Emacs.)
 @end deffn
 
 @deffn Command normal-mode &optional find-file
-This function establishes the proper major mode and local variable
+This function establishes the proper major mode and buffer-local variable
 bindings for the current buffer.  First it calls @code{set-auto-mode},
 then it runs @code{hack-local-variables} to parse, and bind or
-evaluate as appropriate, any local variables.
+evaluate as appropriate, the file's local variables.
 
-If the @var{find-file} argument to @code{normal-mode} is
-non-@code{nil}, @code{normal-mode} assumes that the @code{find-file}
-function is calling it.  In this case, it may process a local variables
-list at the end of the file and in the @samp{-*-} line.  The variable
-@code{enable-local-variables} controls whether to do so.
+If the @var{find-file} argument to @code{normal-mode} is non-@code{nil},
+@code{normal-mode} assumes that the @code{find-file} function is calling
+it.  In this case, it may process a local variables list at the end of
+the file and in the @samp{-*-} line.  The variable
+@code{enable-local-variables} controls whether to do so.  @xref{File
+variables, , Local Variables in Files, emacs, The GNU Emacs Manual}, for
+the syntax of the local variables section of a file.
 
 If you run @code{normal-mode} interactively, the argument
 @var{find-file} is normally @code{nil}.  In this case,
 @code{normal-mode} unconditionally processes any local variables list.
-@xref{File variables, , Local Variables in Files, emacs, The GNU Emacs
-Manual}, for the syntax of the local variables section of a file.
 
 @cindex file mode specification error
 @code{normal-mode} uses @code{condition-case} around the call to the
@@ -563,7 +547,7 @@ ask the user what to do for each file.  The default value is @code{t}.
 
 @defvar ignored-local-variables
 This variable holds a list of variables that should not be
-set by a local variables list.  Any value specified
+set by a file's local variables list.  Any value specified
 for one of these variables is ignored.
 @end defvar
 
@@ -583,17 +567,17 @@ the user what to do for each file.  The default value is @code{maybe}.
 current buffer.  It may base its decision on the value of the @w{@samp{-*-}}
 line, on the visited file name (using @code{auto-mode-alist}), on the
 @w{@samp{#!}} line (using @code{interpreter-mode-alist}), or on the
-value of a local variable.  However, this function does not look for
+file's local variables list.  However, this function does not look for
 the @samp{mode:} local variable near the end of a file; the
 @code{hack-local-variables} function does that.  @xref{Choosing Modes, ,
 How Major Modes are Chosen, emacs, The GNU Emacs Manual}.
 @end defun
 
 @defopt default-major-mode 
-  This variable holds the default major mode for new buffers.  The
+This variable holds the default major mode for new buffers.  The
 standard value is @code{fundamental-mode}.
 
-  If the value of @code{default-major-mode} is @code{nil}, Emacs uses
+If the value of @code{default-major-mode} is @code{nil}, Emacs uses
 the (previously) current buffer's major mode for the major mode of a new
 buffer.  However, if that major mode symbol has a @code{mode-class}
 property with value @code{special}, then it is not used for new buffers;
@@ -631,7 +615,7 @@ For example,
 
 @smallexample
 @group
-(("^/tmp/fol/" . text-mode)
+(("\\`/tmp/fol/" . text-mode)
  ("\\.texinfo\\'" . texinfo-mode)
  ("\\.texi\\'" . texinfo-mode)
 @end group
@@ -651,12 +635,10 @@ the proper major mode for most files.
 If an element of @code{auto-mode-alist} has the form @code{(@var{regexp}
 @var{function} t)}, then after calling @var{function}, Emacs searches
 @code{auto-mode-alist} again for a match against the portion of the file
-name that did not match before.
-
-This match-again feature is useful for uncompression packages: an entry
-of the form @code{("\\.gz\\'" @var{function} t)} can uncompress the file
-and then put the uncompressed file in the proper mode according to the
-name sans @samp{.gz}.
+name that did not match before.  This feature is useful for
+uncompression packages: an entry of the form @code{("\\.gz\\'"
+@var{function} t)} can uncompress the file and then put the uncompressed
+file in the proper mode according to the name sans @samp{.gz}.
 
 Here is an example of how to prepend several pattern pairs to
 @code{auto-mode-alist}.  (You might use this sort of expression in your
@@ -691,10 +673,10 @@ not indicate which major mode to use.
 @end defvar
 
 @defun hack-local-variables &optional force
-  This function parses, and binds or evaluates as appropriate, any local
-variables for the current buffer.
+This function parses, and binds or evaluates as appropriate, any local
+variables specified by the contents of the current buffer.
 
-  The handling of @code{enable-local-variables} documented for
+The handling of @code{enable-local-variables} documented for
 @code{normal-mode} actually takes place here.  The argument @var{force}
 usually comes from the argument @var{find-file} given to
 @code{normal-mode}.
@@ -797,11 +779,11 @@ Here is a hypothetical example:
   A @dfn{minor mode} provides features that users may enable or disable
 independently of the choice of major mode.  Minor modes can be enabled
 individually or in combination.  Minor modes would be better named
-``Generally available, optional feature modes'' except that such a name is
-unwieldy.
+``generally available, optional feature modes,'' except that such a name
+would be unwieldy.
 
   A minor mode is not usually a modification of single major mode.  For
-example, Auto Fill mode may be used in any major mode that permits text
+example, Auto Fill mode works with any major mode that permits text
 insertion.  To be general, a minor mode must be effectively independent
 of the things major modes do.
 
@@ -838,10 +820,14 @@ minor modes.
 @itemize @bullet
 @item
 @cindex mode variable
-Make a variable whose name ends in @samp{-mode} to represent the minor
-mode.  Its value should enable or disable the mode (@code{nil} to
-disable; anything else to enable.)  We call this the @dfn{mode
-variable}.
+Make a variable whose name ends in @samp{-mode} to control the minor
+mode.  We call this the @dfn{mode variable}.  The minor mode command
+should set this variable (@code{nil} to disable; anything else to
+enable.)
+
+If it is possible, implement the mode so that setting the variable
+automatically enables or disables the mode.  Then the minor mode command
+does not need to do anything except the variable.
 
 This variable is used in conjunction with the @code{minor-mode-alist} to
 display the minor mode name in the mode line.  It can also enable
@@ -877,8 +863,8 @@ enable or disable the minor mode based on the raw prefix argument value.
 
 @item
 Add an element to @code{minor-mode-alist} for each minor mode
-(@pxref{Mode Line Variables}).  This element should be a list of the
-following form:
+(@pxref{Mode Line Variables}), if you want to indicate the minor mode in
+the mode line.  This element should be a list of the following form:
 
 @smallexample
 (@var{mode-variable} @var{string})
@@ -956,9 +942,8 @@ specifying bindings in this form:
   Here is an example of using @code{easy-mmode-define-minor-mode}:
 
 @smallexample
-(easy-mmode-define-minor-mode
- hungry-mode
- "Toggle Hungry mode.
+(easy-mmode-define-minor-mode hungry-mode
+  "Toggle Hungry mode.
 With no argument, this command toggles the mode. 
 Non-null prefix argument turns on the mode.
 Null prefix argument turns off the mode.
@@ -986,11 +971,6 @@ which indicates whether the mode is enabled, and a variable named
 mode is enabled.  It initializes the keymap with key bindings for
 @kbd{C-@key{DEL}} and @kbd{C-M-@key{DEL}}.
 
-  The command @code{hungry-mode} also runs three hooks:
-@code{hungry-mode-on-hook} when enabling Hungry mode,
-@code{hungry-mode-off-hook} when disabling the mode, and
-@code{hungry-mode-hook} in both of those cases.
-
 @node Mode Line Format
 @section Mode Line Format
 @cindex mode line
@@ -1009,8 +989,8 @@ minor modes.
   @code{mode-line-format} is a buffer-local variable that holds a
 template used to display the mode line of the current buffer.  All
 windows for the same buffer use the same @code{mode-line-format} and
-their mode lines appear the same (except for scrolling percentages and
-line numbers).
+their mode lines appear the same (except for scrolling percentages, and
+line and column numbers).
 
   The mode line of a window is normally updated whenever a different
 buffer is shown in the window, or when the buffer's modified-status
@@ -1119,14 +1099,16 @@ modes) via changes to those variables remain effective.
 
 @cindex Shell mode @code{mode-line-format}
   Here is an example of a @code{mode-line-format} that might be
-useful for @code{shell-mode}, since it contains the hostname and default
+useful for @code{shell-mode}, since it contains the host name and default
 directory.
 
 @example
 @group
 (setq mode-line-format
-  (list ""
+  (list "-"
+   'mode-line-mule-info
    'mode-line-modified
+   'mode-line-frame-identification
    "%b--" 
 @end group
 @group
@@ -1143,9 +1125,11 @@ directory.
    'mode-line-process  
    'minor-mode-alist 
    "%n" 
-   ")%]----"
+   ")%]--"
 @group
+   '(which-func-mode ("" which-func-format "--"))
    '(line-number-mode "L%l--")
+   '(column-number-mode "C%c--")
    '(-3 . "%p")
    "-%-"))
 @end group
@@ -1160,22 +1144,38 @@ line.  There is nothing inherently special about these variables; any
 other variables could have the same effects on the mode line if
 @code{mode-line-format} were changed to use them.
 
+@tindex mode-line-mule-info
+@defvar mode-line-mule-info
+This variable holds the value of the mode-line construct that displays
+information about the language environment, buffer coding system, and
+current input method.  @xref{International,,, emacs, The GNU Emacs
+Manual}.
+@end defvar
+
 @defvar mode-line-modified
 This variable holds the value of the mode-line construct that displays
 whether the current buffer is modified.
 
-The default value of @code{mode-line-modified} is @code{("--%1*%1+-")}.
-This means that the mode line displays @samp{--**-} if the buffer is
-modified, @samp{-----} if the buffer is not modified, @samp{--%%-} if
-the buffer is read only, and @samp{--%*--} if the buffer is read only
-and modified.
+The default value of @code{mode-line-modified} is @code{("%1*%1+")}.
+This means that the mode line displays @samp{**} if the buffer is
+modified, @samp{--} if the buffer is not modified, @samp{%%} if the
+buffer is read only, and @samp{%*} if the buffer is read only and
+modified.
 
 Changing this variable does not force an update of the mode line.
 @end defvar
 
+@tindex mode-line-frame-identification
+@defvar mode-line-frame-identification
+This variable identifies the current frame.  The default value is
+@code{" "} if you are using a window system which can show multiple
+frames, or @code{"-%F "} on an ordinary terminal which shows only one
+frame at a time.
+@end defvar
+
 @defvar mode-line-buffer-identification
 This variable identifies the buffer being displayed in the window.  Its
-default value is @code{("%F: %17b")}, which means that it usually
+default value is @code{("%12b")}, which means that it usually
 displays @samp{Emacs:} followed by seventeen characters of the buffer
 name.  (In a terminal frame, it displays the frame name instead of
 @samp{Emacs}; this has the effect of showing the frame number.)  You may
@@ -1282,10 +1282,10 @@ The default value of @code{default-mode-line-format} is this list:
 @end defvar
 
 @defvar vc-mode
-The variable @code{vc-mode}, local in each buffer, records whether the
-buffer's visited file is maintained with version control, and, if so,
-which kind.  Its value is @code{nil} for no version control, or a string
-that appears in the mode line.
+The variable @code{vc-mode}, buffer-local in each buffer, records
+whether the buffer's visited file is maintained with version control,
+and, if so, which kind.  Its value is @code{nil} for no version control,
+or a string that appears in the mode line.
 @end defvar
 
 @node %-Constructs
@@ -1305,7 +1305,8 @@ The visited file name, obtained with the @code{buffer-file-name}
 function.  @xref{Buffer File Name}.
 
 @item %F
-The name of the selected frame.
+The title (only on a window system) or the name of the selected frame.
+@xref{Window Frame Parameters}.
 
 @item %c
 The current column number of point.
@@ -1383,12 +1384,15 @@ The value of @code{global-mode-string}.  Currently, only
 @section Imenu
 
 @cindex Imenu
-  @dfn{Imenu} is a feature that constructs a buffer index for a buffer.
-The buffer index contains the names and positions of the definitions or
-portions of in the buffer, so the user can pick one of themand move to
-it.  This section explains how to customize Imenu for a major mode.  The
-usual and simplest way is to set the variable
-@code{imenu-generic-expression}.
+  @dfn{Imenu} is a feature that lets users select a definition or
+section in the buffer, from a menu which lists all of them, to go
+directly to that location in the buffer.  Imenu works by constructing a
+buffer index which lists the names and positions of the definitions or
+portions of in the buffer, so the user can pick one of them to move to.
+This section explains how to customize Imenu for a major mode.
+
+  The usual and simplest way is to set the variable
+@code{imenu-generic-expression}:
 
 @defvar imenu-generic-expression
 This variable, if non-@code{nil}, specifies regular expressions for
@@ -1407,9 +1411,8 @@ in the top level of the buffer index.
 
 The second item in the list, @var{regexp}, is a regular expression
 (@pxref{Regular Expressions}); wherever it matches, that is a definition
-to be mentioned in the buffer index.  The third item, @var{subexp},
-indicates which subexpression in @var{regexp} contains the name for the
-definition.
+to mention in the buffer index.  The third item, @var{subexp}, indicates
+which subexpression in @var{regexp} matches the definition's name.
 
 An element can also look like this:
 
@@ -1439,7 +1442,7 @@ For Emacs Lisp mode, @var{pattern} could look like this:
 @end group
 @end example
 
-This variable is local in all buffers, if it is set.
+Setting this variable makes it buffer-local in the current buffer.
 @end defvar
 
 @defvar imenu-case-fold-search
@@ -1447,12 +1450,12 @@ This variable controls whether the regular expression matching for Imenu
 is case-sensitive: @code{t}, the default, means matching should ignore
 case.
 
-This variable is local in all buffers, if it is set.
+Setting this variable makes it buffer-local in the current buffer.
 @end defvar
 
   Another way to customize Imenu for a major mode is to set the
 variables @code{imenu-prev-index-position-function} and
-@code{imenu-extract-index-name-function}.
+@code{imenu-extract-index-name-function}:
 
 @defvar imenu-prev-index-position-function
 If this variable is non-@code{nil}, its value should be a function for
@@ -1460,19 +1463,23 @@ finding the next definition to mention in the buffer index, moving
 backwards in the file.
 
 The function should leave point at the place to be connected to the
-index item, and it should return @code{nil} when it doesn't find another
-item.
+index item; it should return @code{nil} if it doesn't find another item.
 
-This variable is local in all buffers, if it is set.
+Setting this variable makes it buffer-local in the current buffer.
 @end defvar
 
 @defvar imenu-extract-index-name-function
 If this variable is non-@code{nil}, its value should be a function to
-return the name for a definition, assuming point is at that definition.
+return the name for a definition, assuming point is in that definition
+as the @code{imenu-prev-index-position-function} function would leave
+it.
 
-This variable is local in all buffers, if it is set.
+Setting this variable makes it buffer-local in the current buffer.
 @end defvar
 
+  The last way to customize Imenu for a major mode is to set the
+variables @code{imenu-create-index-function}:
+
 @defvar imenu-create-index-function
 This variable specifies the function to use for creating a buffer index.
 The function should take no arguments, and return an index for the
@@ -1484,13 +1491,12 @@ The default value is a function that uses
 specify a different function, then @code{imenu-generic-expression} is
 not used.
 
-The variable @code{imenu-create-index-function} is local in all buffers,
-if it is set.
+Setting this variable makes it buffer-local in the current buffer.
 @end defvar
 
 @defvar imenu-index-alist
 This variable holds the index alist for the current buffer.
-It is local in each buffer, once it is set.
+Setting it makes it buffer-local in the current buffer.
 
 Simple elements in the alist look like @code{(@var{index-name}
 . @var{index-position})}.  Selecting a simple element has the effect of
@@ -1515,17 +1521,16 @@ A nested sub-alist element looks like @code{(@var{index-name}
   @dfn{Font Lock mode} is a feature that automatically attaches
 @code{face} properties to certain parts of the buffer based on their
 syntactic role.  How it parses the buffer depends on the major mode;
-most major modes define a set of syntactic criteria for which faces to
-use, in which contexts.  This section explains how to customize Font
-Lock for a particular language---in other words, for a particular major
-mode.
+most major modes define syntactic criteria for which faces to use, in
+which contexts.  This section explains how to customize Font Lock for a
+particular language---in other words, for a particular major mode.
 
   Font Lock mode finds text to highlight in two ways: through syntactic
 parsing based on the syntax table, and through searching (usually for
 regular expressions).  Syntactic fontification happens first; it finds
 comments and string constants, and highlights them using
 @code{font-lock-comment-face} and @code{font-lock-string-face}
-(@pxref{Faces for Font Lock}: Search-based fontification follows.
+(@pxref{Faces for Font Lock}); search-based fontification follows.
 
 @menu
 * Font Lock Basics::
@@ -1533,6 +1538,7 @@ comments and string constants, and highlights them using
 * Other Font Lock Variables::
 * Levels of Font Lock::
 * Faces for Font Lock::
+* Syntactic Font Lock::
 @end menu
 
 @node Font Lock Basics
@@ -1540,9 +1546,9 @@ comments and string constants, and highlights them using
 
   There are several variables that control how Font Lock mode highlights
 text.  But major modes should not set any of these variables directly.
-Instead, it should set @code{font-lock-defaults} as a local variable.
-The value assigned to this variable is used, if and when Font Lock mode
-is enabled, to set all the other variables.
+Instead, it should set @code{font-lock-defaults} as a buffer-local
+variable.  The value assigned to this variable is used, if and when Font
+Lock mode is enabled, to set all the other variables.
 
 @defvar font-lock-defaults
 This variable is set by major modes, as a buffer-local variable, to
@@ -1563,11 +1569,12 @@ symbol how to do level 2, and so on.
 
 The second element, @var{keywords-only}, specifies the value of the
 variable @code{font-lock-keywords-only}.  If this is is non-@code{nil},
-syntactic fontification (strings and comments) is not performed.
+syntactic fontification (of strings and comments) is not performed.
 
 The third element, @var{case-fold}, specifies the value of
 @code{font-lock-case-fold-search}.  If it is non-@code{nil}, Font Lock
-mode ignores case when obeying @code{font-lock-keywords}.
+mode ignores case when searching as directed by
+@code{font-lock-keywords}.
 
 If the fourth element, @var{syntax-alist}, is non-@code{nil}, it should be
 a list of cons cells of the form @code{(@var{char-or-string}
@@ -1576,8 +1583,7 @@ fontification (@pxref{Syntax Table Functions}).  The resulting syntax
 table is stored in @code{font-lock-syntax-table}.
 
 The fifth element, @var{syntax-begin}, specifies the value of
-@code{font-lock-beginning-of-syntax-function}.  See below for an
-explanation of what this value means.
+@code{font-lock-beginning-of-syntax-function} (see below).
 
 Any further elements @var{other-vars} are have form
 @code{(@var{variable} . @var{value})}.  This kind of element means to
@@ -1594,13 +1600,20 @@ search-based fontification.
 
 @defvar font-lock-keywords
 This variable's value is a list of the keywords to highlight.  Be
-careful when composing regexps for this list; a poorly written pattern
-can dramatically slow things down!
+careful when composing regular expressions for this list; a poorly
+written pattern can dramatically slow things down!
 @end defvar
 
   Each element of @code{font-lock-keywords} specifies how to find
-certain cases of text, and how to highlight those cases.  An element
-should have one of these forms:
+certain cases of text, and how to highlight those cases.  Font Lock mode
+processes the elements of @code{font-lock-keywords} one by one, and for
+each element, it finds and handles all matches.  Ordinarily, once
+part of the text has been fontified already, this cannot be overridden
+by a subsequent match in the same text; but you can specify different
+behavior using the @var{override} element of a @var{highlighter}.
+
+  Each element of @code{font-lock-keywords} should have one of these
+forms:
 
 @table @code
 @item @var{regexp}
@@ -1613,9 +1626,9 @@ Highlight all matches for @var{regexp} using
 "\\<foo\\>"
 @end example
 
-The function @code{regexp-opt} (@pxref{Syntax of Regexps}) is often
-useful for calculating complex regular expressions to match a number of
-different keywords.
+The function @code{regexp-opt} (@pxref{Syntax of Regexps}) is useful for
+calculating optimal regular expressions to match a number of different
+keywords.
 
 @item @var{function}
 Find text by calling @var{function}, and highlight the matches
@@ -1629,7 +1642,7 @@ match data to describe the match that was found.
 In this kind of element, @var{matcher} stands for either a regular
 expression or a function, as described above.  The @sc{cdr},
 @var{match}, specifies which subexpression of @var{matcher} should be
-highlighted (instead of the entire text that matched @var{matcher}).
+highlighted (instead of the entire text that @var{matcher} matched).
 
 @example
 ;; @r{Highlight the @samp{bar} in each occurrences of @samp{fubar},}
@@ -1637,7 +1650,7 @@ highlighted (instead of the entire text that matched @var{matcher}).
 ("fu\\(bar\\)" . 1)
 @end example
 
-If you use @code{regexp-opt} to produce a regular expression for
+If you use @code{regexp-opt} to produce the regular expression
 @var{matcher}, then you can use @code{regexp-opt-depth} (@pxref{Syntax
 of Regexps}) to calculate the value for @var{match}.
 
@@ -1661,8 +1674,8 @@ It has the form
 @end example
 
 The @sc{car}, @var{subexp}, is an integer specifying which subexpression
-of the match to fontify (0 means the entire matching text).
-@var{facename}, specifies the face, as described above.
+of the match to fontify (0 means the entire matching text).  The second
+subelement, @var{facename}, specifies the face, as described above.
 
 The last two values in @var{highlighter}, @var{override} and
 @var{laxmatch}, are flags.  If @var{override} is @code{t}, this element
@@ -1750,9 +1763,9 @@ line; in other words, the @var{submatcher} search should not span lines.
 @end ignore
 
 @item (eval . @var{form})
-Here @var{form} is an expression. to be evaluated the first time
+Here @var{form} is an expression to be evaluated the first time
 this value of @code{font-lock-keywords} is used in a buffer.
-Its value should be another element of one of these forms.
+Its value should have one of the forms described in this table.
 @end table
 
 @strong{Warning:} Do not design an element of @code{font-lock-keywords}
@@ -1761,33 +1774,6 @@ to match text which spans lines; this does not work reliably.  While
 updating when you edit the buffer does not, since it considers text one
 line at a time.
 
-@defvar font-lock-syntactic-keywords
-Font Lock mode can be used to update @code{syntax-table} properties
-automatically.  This is useful in languages for which a single
-syntax table by itself is not sufficient.
-
-This variable enables and controls the feature.  Its value should
-be a list of elements of this form:
-
-@example
-(@var{matcher} @var{subexp} @var{syntax} @var{override} @var{laxmatch})
-@end example
-
-The parts of this element have the same meanings as in the corresponding
-sort of element of @code{font-lock-keywords},
-
-@example
-(@var{matcher} @var{subexp} @var{facename} @var{override} @var{laxmatch})
-@end example
-
-However, instead of specifying the value @var{facename} to use for the
-@code{face} property, it specifies the value @var{syntax} to use for the
-@code{syntax-table} property.  Here, @var{syntax} can be a variable
-whose value is a syntax table, a syntax entry of the form
-@code{(@var{syntax-code} . @var{matching-char})}, or an expression whose
-value is one of those two types.
-@end defvar
-
 @node Other Font Lock Variables
 @subsection Other Font Lock Variables
 
@@ -1796,7 +1782,8 @@ can set by means of @code{font-lock-defaults}.
 
 @defvar font-lock-keywords-only
 Non-@code{nil} means Font Lock should not fontify comments or strings
-syntactictally; it should only fontify based on @code{font-lock-keywords}.
+syntactically; it should only fontify based on
+@code{font-lock-keywords}.
 @end defvar
 
 @ignore
@@ -1807,17 +1794,20 @@ Other variables include those for buffer-specialised fontification functions,
 @end ignore
 
 @defvar font-lock-keywords-case-fold-search
-Non-@code{nil} means that regular expression matching for
-patterns in @code{font-lock-keywords} is case-insensitive.
+Non-@code{nil} means that regular expression matching for the sake of
+@code{font-lock-keywords} should be case-insensitive.
 @end defvar
 
-@defvar font-lock-beginning-of-syntax-function
-If this variable is non-@code{nil}, it should be a function to use to
-move back outside of a syntactic block.
+@defvar font-lock-syntax-table
+This variable specifies the syntax table to use for fontification of
+comments and strings.
+@end defvar
 
-@c Simon, WHEN is this variable used?
-@c In what situation does Font Lock mode look for the
-@c beginning of a syntactic block?
+@defvar font-lock-beginning-of-syntax-function
+If this variable is non-@code{nil}, it should be a function to move
+point back to a position that is syntactically at ``top level'' and
+outside of strings or comments.  Font Lock uses this when necessary
+to get the right results for syntactic fontification.
 
 This function is called with no arguments.  It should leave point at the
 beginning of any enclosing syntactic block.  Typical values are
@@ -1827,30 +1817,21 @@ modes or @code{backward-paragraph} for textual modes (i.e., the
 mode-dependent function is known to move outside a syntactic block).
 
 If the value is @code{nil}, the beginning of the buffer is used as a
-position outside of a syntactic block, in the worst case.
-@end defvar
-
-@defvar font-lock-syntax-table
-This variable specifies the syntax table to use for fontification of
-comments and strings.
+position outside of a syntactic block.  This cannot be wrong, but it can
+be slow.
 @end defvar
 
 @defvar font-lock-mark-block-function
-If this variable is non-@code{nil}, it should be a function with no args
-used to mark an enclosing range of text for refontification when the
-text in the buffer changes.  A good choice of this function chooses a
-range of text large enough to give proper results, but not too large so
-that refontification becomes slow.
-
-Typical values are @code{mark-defun} for programming modes or
-@code{mark-paragraph} for textual modes (i.e., the mode-dependent
-function is known to put point and mark around a text block relevant to
-that mode).
-
-@c Simon, WHEN is this variable used?
-@c In what situation does Font Lock mode look for the
-@c beginning of a syntactic block?
-
+If this variable is non-@code{nil}, it should be a function that is
+called with no arguments, to choose an enclosing range of text for
+refontification for the command @kbd{M-g M-g}
+(@code{font-lock-fontify-block}).
+
+The function should report its choice by placing the region around it.
+A good choice is a range of text large enough to give proper results,
+but not too large so that refontification becomes slow.  Typical values
+are @code{mark-defun} for programming modes or @code{mark-paragraph} for
+textual modes.
 @end defvar
 
 @node Levels of Font Lock
@@ -1863,6 +1844,9 @@ fontification; it is up to the user to choose one of these levels.  The
 chosen level's symbol value is used to initialize
 @code{font-lock-keywords}.
 
+  Here are the conventions for how to define the levels of
+fontification:
+
 @itemize @bullet
 @item
 Level 1: highlight function declarations, file directives (such as include or
@@ -1870,17 +1854,15 @@ import directives), strings and comments.  The idea is speed, so only
 the most important and top-level components are fontified.
 
 @item
-Level 2: in addition to level 1, highlight all language keywords (with
-keyword-face) including type names (using type-face), constant values
-(with reference-face, e.g., "true" and "false" or case/switch
-constants).  The idea is that all reserved words should be fontified
-appropriately.
+Level 2: in addition to level 1, highlight all language keywords,
+including type names that act like keywords, as well as named constant
+values.  The idea is that all keywords (either syntactic or semantic)
+should be fontified appropriately.
 
 @item
-Level 3: in addition to level 2, highlight all symbols that are defined
-in function and variable declarations, and all builtin functions,
-wherever they appear.  The idea is that all declared objects should be
-fontified.
+Level 3: in addition to level 2, highlight the symbols being defined in
+function and variable declarations, and all builtin function names,
+wherever they appear.
 @end itemize
 
 @node Faces for Font Lock
@@ -1948,6 +1930,36 @@ change the meaning of other text.  For example, this is used for
 directives in C.
 @end table
 
+@node Syntactic Font Lock
+@subsection Syntactic Font Lock
+
+  Font Lock mode can be used to update @code{syntax-table} properties
+automatically.  This is useful in languages for which a single syntax
+table by itself is not sufficient.
+
+@defvar font-lock-syntactic-keywords
+This variable enables and controls syntactic Font Lock.  Its value
+should be a list of elements of this form:
+
+@example
+(@var{matcher} @var{subexp} @var{syntax} @var{override} @var{laxmatch})
+@end example
+
+The parts of this element have the same meanings as in the corresponding
+sort of element of @code{font-lock-keywords},
+
+@example
+(@var{matcher} @var{subexp} @var{facename} @var{override} @var{laxmatch})
+@end example
+
+However, instead of specifying the value @var{facename} to use for the
+@code{face} property, it specifies the value @var{syntax} to use for the
+@code{syntax-table} property.  Here, @var{syntax} can be a variable
+whose value is a syntax table, a syntax entry of the form
+@code{(@var{syntax-code} . @var{matching-char})}, or an expression whose
+value is one of those two types.
+@end defvar
+
 @node Hooks
 @section Hooks
 @cindex hooks
@@ -1968,9 +1980,10 @@ a uniform way.
   Every major mode function is supposed to run a normal hook called the
 @dfn{mode hook} as the last step of initialization.  This makes it easy
 for a user to customize the behavior of the mode, by overriding the
-local variable assignments already made by the mode.  But hooks are used
-in other contexts too.  For example, the hook @code{suspend-hook} runs
-just before Emacs suspends itself (@pxref{Suspending Emacs}).
+buffer-local variable assignments already made by the mode.  But hooks
+are used in other contexts too.  For example, the hook
+@code{suspend-hook} runs just before Emacs suspends itself
+(@pxref{Suspending Emacs}).
 
   The recommended way to add a hook function to a normal hook is by
 calling @code{add-hook} (see below).  The hook functions may be any of
@@ -1994,36 +2007,13 @@ established the convention of using @samp{-hook} for them.)
   If the variable's name ends in @samp{-function}, then its value
 is just a single function, not a list of functions.
 
-  Here's an expression that uses a mode hook to turn on Auto Fill mode
-when in Lisp Interaction mode:
+  Here's an example that uses a mode hook to turn on Auto Fill mode when
+in Lisp Interaction mode:
 
 @example
 (add-hook 'lisp-interaction-mode-hook 'turn-on-auto-fill)
 @end example
 
-  The next example shows how to use a hook to customize the way Emacs
-formats C code.  (People often have strong personal preferences for one
-format or another.)  Here the hook function is an anonymous lambda
-expression.
-
-@cindex lambda expression in hook
-@example
-@group
-(add-hook 'c-mode-hook 
-  (function (lambda ()
-              (setq c-indent-level 4
-                    c-argdecl-indent 0
-                    c-label-offset -4
-@end group
-@group
-                    c-continued-statement-indent 0
-                    c-brace-offset 0
-                    comment-column 40))))
-
-(setq c++-mode-hook c-mode-hook)
-@end group
-@end example
-
   At the appropriate time, Emacs uses the @code{run-hooks} function to
 run particular hooks.  This function calls the hook functions that have
 been added with @code{add-hook}.
@@ -2068,13 +2058,12 @@ It is best to design your hook functions so that the order in which they
 are executed does not matter.  Any dependence on the order is ``asking
 for trouble.''  However, the order is predictable: normally,
 @var{function} goes at the front of the hook list, so it will be
-executed first (barring another @code{add-hook} call).
-
-If the optional argument @var{append} is non-@code{nil}, the new hook
-function goes at the end of the hook list and will be executed last.
+executed first (barring another @code{add-hook} call).  If the optional
+argument @var{append} is non-@code{nil}, the new hook function goes at
+the end of the hook list and will be executed last.
 
 If @var{local} is non-@code{nil}, that says to make the new hook
-function local to the current buffer.  Before you can do this, you must
+function buffer-local in the current buffer.  Before you can do this, you must
 make the hook itself buffer-local by calling @code{make-local-hook}
 (@strong{not} @code{make-local-variable}).  If the hook itself is not
 buffer-local, then the value of @var{local} makes no difference---the
@@ -2085,22 +2074,24 @@ hook function is always global.
 This function removes @var{function} from the hook variable @var{hook}.
 
 If @var{local} is non-@code{nil}, that says to remove @var{function}
-from the local hook list instead of from the global hook list.  If the
-hook itself is not buffer-local, then the value of @var{local} makes no
-difference.
+from the buffer-local hook list instead of from the global hook list.
+If the hook variable itself is not buffer-local, then the value of
+@var{local} makes no difference.
 @end defun
 
 @defun make-local-hook hook
-This function makes the hook variable @code{hook} local to the current
-buffer.  When a hook variable is local, it can have local and global
-hook functions, and @code{run-hooks} runs all of them.
+This function makes the hook variable @code{hook} buffer-local in the
+current buffer.  When a hook variable is buffer-local, it can have
+buffer-local and global hook functions, and @code{run-hooks} runs all of
+them.
 
 This function works by making @code{t} an element of the buffer-local
 value.  That serves as a flag to use the hook functions in the default
-value of the hook variable as well as those in the local value.  Since
-@code{run-hooks} understands this flag, @code{make-local-hook} works
-with all normal hooks.  It works for only some non-normal hooks---those
-whose callers have been updated to understand this meaning of @code{t}.
+value of the hook variable as well as those in the buffer-local value.
+Since @code{run-hooks} understands this flag, @code{make-local-hook}
+works with all normal hooks.  It works for only some non-normal
+hooks---those whose callers have been updated to understand this meaning
+of @code{t}.
 
 Do not use @code{make-local-variable} directly for hook variables; it is
 not sufficient.
diff --git a/lispref/nonascii.texi b/lispref/nonascii.texi
index 16a22f2c443..f75900d6818 100644
--- a/lispref/nonascii.texi
+++ b/lispref/nonascii.texi
@@ -20,9 +20,12 @@ characters and how they are stored in strings and buffers.
 * Scanning Charsets::
 * Chars and Bytes::
 * Coding Systems::
+* Lisp and Coding System::
 * Default Coding Systems::
 * Specifying Coding Systems::
 * Explicit Encoding::
+* MS-DOS File Types::
+* MS-DOS Subprocesses::
 @end menu
 
 @node Text Representations
@@ -41,8 +44,8 @@ attention to the difference.
   In unibyte representation, each character occupies one byte and
 therefore the possible character codes range from 0 to 255.  Codes 0
 through 127 are @sc{ASCII} characters; the codes from 128 through 255
-are used for one non-@sc{ASCII} character set (you can choose which one
-by setting the variable @code{nonascii-insert-offset}).
+are used for one non-@sc{ASCII} character set (you can choose which
+character set by setting the variable @code{nonascii-insert-offset}).
 
 @cindex leading code
 @cindex multibyte text
@@ -67,9 +70,8 @@ This variable specifies the current buffer's text representation.
 If it is non-@code{nil}, the buffer contains multibyte text; otherwise,
 it contains unibyte text.
 
-@strong{Warning:} do not set this variable directly; instead, use the
-function @code{set-buffer-multibyte} to change a buffer's
-representation.
+You cannot set this variable directly; instead, use the function
+@code{set-buffer-multibyte} to change a buffer's representation.
 @end defvar
 
 @tindex default-enable-multibyte-characters
@@ -112,17 +114,17 @@ to unibyte, even though this conversion cannot in general preserve all
 the characters that might be in the multibyte text.  The other natural
 alternative, to convert the buffer contents to multibyte, is not
 acceptable because the buffer's representation is a choice made by the
-user that cannot simply be overrided.
+user that cannot be overridden automatically.
 
   Converting unibyte text to multibyte text leaves @sc{ASCII} characters
-unchanged.  It converts the non-@sc{ASCII} codes 128 through 255 by
-adding the value @code{nonascii-insert-offset} to each character code.
-By setting this variable, you specify which character set the unibyte
-characters correspond to.  For example, if @code{nonascii-insert-offset}
-is 2048, which is @code{(- (make-char 'latin-iso8859-1 0) 128)}, then
-the unibyte non-@sc{ASCII} characters correspond to Latin 1.  If it is
-2688, which is @code{(- (make-char 'greek-iso8859-7 0) 128)}, then they
-correspond to Greek letters.
+unchanged, and likewise 128 through 159.  It converts the non-@sc{ASCII}
+codes 160 through 255 by adding the value @code{nonascii-insert-offset}
+to each character code.  By setting this variable, you specify which
+character set the unibyte characters correspond to.  For example, if
+@code{nonascii-insert-offset} is 2048, which is @code{(- (make-char
+'latin-iso8859-1 0) 128)}, then the unibyte non-@sc{ASCII} characters
+correspond to Latin 1.  If it is 2688, which is @code{(- (make-char
+'greek-iso8859-7 0) 128)}, then they correspond to Greek letters.
 
   Converting multibyte text to unibyte is simpler: it performs
 logical-and of each character code with 255.  If
@@ -150,22 +152,21 @@ This variable provides a more general alternative to
 @code{nonascii-insert-offset}.  You can use it to specify independently
 how to translate each code in the range of 128 through 255 into a
 multibyte character.  The value should be a vector, or @code{nil}.
+If this is non-@code{nil}, it overrides @code{nonascii-insert-offset}.
 @end defvar
 
 @tindex string-make-unibyte
 @defun string-make-unibyte string
 This function converts the text of @var{string} to unibyte
 representation, if it isn't already, and return the result.  If
-conversion does not change the contents, the value may be @var{string}
-itself.
+@var{string} is a unibyte string, it is returned unchanged.
 @end defun
 
 @tindex string-make-multibyte
 @defun string-make-multibyte string
 This function converts the text of @var{string} to multibyte
 representation, if it isn't already, and return the result.  If
-conversion does not change the contents, the value may be @var{string}
-itself.
+@var{string} is a multibyte string, it is returned unchanged.
 @end defun
 
 @node Selecting a Representation
@@ -188,8 +189,8 @@ representation.
 
 This function sets @code{enable-multibyte-characters} to record which
 representation is in use.  It also adjusts various data in the buffer
-(including its overlays, text properties and markers) so that they
-cover or fall between the same text as they did before.
+(including overlays, text properties and markers) so that they cover the
+same text as they did before.
 @end defun
 
 @tindex string-as-unibyte
@@ -198,7 +199,7 @@ This function returns a string with the same bytes as @var{string} but
 treating each byte as a character.  This means that the value may have
 more characters than @var{string} has.
 
-If @var{string} is unibyte already, then the value may be @var{string}
+If @var{string} is unibyte already, then the value is @var{string}
 itself.
 @end defun
 
@@ -208,7 +209,7 @@ This function returns a string with the same bytes as @var{string} but
 treating each multibyte sequence as one character.  This means that the
 value may have fewer characters than @var{string} has.
 
-If @var{string} is multibyte already, then the value may be @var{string}
+If @var{string} is multibyte already, then the value is @var{string}
 itself.
 @end defun
 
@@ -221,8 +222,9 @@ codes.  The valid character codes for unibyte representation range from
 0 to 255---the values that can fit in one byte.  The valid character
 codes for multibyte representation range from 0 to 524287, but not all
 values in that range are valid.  In particular, the values 128 through
-255 are not valid in multibyte text.  Only the @sc{ASCII} codes 0
-through 127 are used in both representations.
+255 are not legitimate in multibyte text (though they can occur in ``raw
+bytes''; @pxref{Explicit Encoding}).  Only the @sc{ASCII} codes 0
+through 127 are fully legitimate in both representations.
 
 @defun char-valid-p charcode
 This returns @code{t} if @var{charcode} is valid for either one of the two
@@ -249,11 +251,11 @@ only one character set.
   In general, there is one character set for each distinct script.  For
 example, @code{latin-iso8859-1} is one character set,
 @code{greek-iso8859-7} is another, and @code{ascii} is another.  An
-Emacs character set can hold at most 9025 characters; therefore. in some
-cases, a set of characters that would logically be grouped together are
-split into several character sets.  For example, one set of Chinese
-characters is divided into eight Emacs character sets,
-@code{chinese-cns11643-1} through @code{chinese-cns11643-7}.
+Emacs character set can hold at most 9025 characters; therefore, in some
+cases, characters that would logically be grouped together are split
+into several character sets.  For example, one set of Chinese characters
+is divided into eight Emacs character sets, @code{chinese-cns11643-1}
+through @code{chinese-cns11643-7}.
 
 @tindex charsetp
 @defun charsetp object
@@ -299,14 +301,17 @@ that appear in the string @var{string}.
 
   In multibyte representation, each character occupies one or more
 bytes.  The functions in this section convert between characters and the
-byte values used to represent them.
+byte values used to represent them.  For most purposes, there is no need
+to be concerned with the number of bytes used to represent a character
+because Emacs translates automatically when necessary.
 
 @tindex char-bytes
 @defun char-bytes character
 This function returns the number of bytes used to represent the
 character @var{character}.  In most cases, this is the same as
 @code{(length (split-char @var{character}))}; the only exception is for
-ASCII characters, which use just one byte.
+ASCII characters and the codes used in unibyte text, which use just one
+byte.
 
 @example
 (char-bytes 2248)
@@ -378,17 +383,18 @@ cases, Emacs supports several alternative encodings for the same
 characters; for example, there are three coding systems for the Cyrillic
 (Russian) alphabet: ISO, Alternativnyj, and KOI8.
 
-@cindex end of line conversion
-  @dfn{End of line conversion} handles three different conventions used
-on various systems for end of line.  The Unix convention is to use the
-linefeed character (also called newline).  The DOS convention is to use
-the two character sequence, carriage-return linefeed, at the end of a
-line.  The Mac convention is to use just carriage-return.
-
   Most coding systems specify a particular character code for
 conversion, but some of them leave this unspecified---to be chosen
 heuristically based on the data.
 
+@cindex end of line conversion
+  @dfn{End of line conversion} handles three different conventions used
+on various systems for representing end of line in files.  The Unix
+convention is to use the linefeed character (also called newline).  The
+DOS convention is to use the two character sequence, carriage-return
+linefeed, at the end of a line.  The Mac convention is to use just
+carriage-return.
+
 @cindex base coding system
 @cindex variant coding system
   @dfn{Base coding systems} such as @code{latin-1} leave the end-of-line
@@ -398,6 +404,9 @@ coding systems} such as @code{latin-1-unix}, @code{latin-1-dos} and
 well.  Each base coding system has three corresponding variants whose
 names are formed by adding @samp{-unix}, @samp{-dos} and @samp{-mac}.
 
+@node Lisp and Coding Systems
+@subsection Coding Systems in Lisp
+
   Here are Lisp facilities for working with coding systems;
 
 @tindex coding-system-list
@@ -420,11 +429,21 @@ If that is valid, it returns @var{coding-system}.
 Otherwise it signals an error with condition @code{coding-system-error}.
 @end defun
 
+@tindex find-safe-coding-system
+@defun find-safe-coding-system from to
+Return a list of proper coding systems to encode a text between
+@var{from} and @var{to}.  All coding systems in the list can safely
+encode any multibyte characters in the text.
+
+If the text contains no multibyte characters, return a list of a single
+element @code{undecided}.
+@end defun
+
 @tindex detect-coding-region
 @defun detect-coding-region start end highest
 This function chooses a plausible coding system for decoding the text
 from @var{start} to @var{end}.  This text should be ``raw bytes''
-(@pxref{Specifying Coding Systems}).
+(@pxref{Explicit Encoding}).
 
 Normally this function returns is a list of coding systems that could
 handle decoding the text that was scanned.  They are listed in order of
@@ -473,6 +492,25 @@ This function looks up the target in @code{file-coding-system-alist},
 @xref{Default Coding Systems}.
 @end defun
 
+  Here are two functions you can use to let the user specify a coding
+system, with completion.  @xref{Completion}.
+
+@tindex read-coding-system
+@defun read-coding-system prompt default
+This function reads a coding system using the minibuffer, prompting with
+string @var{prompt}, and returns the coding system name as a symbol.  If
+the user enters null input, @var{default} specifies which coding system
+to return.  It should be a symbol or a string.
+@end defun
+
+@tindex read-non-nil-coding-system
+@defun read-non-nil-coding-system prompt
+This function reads a coding system using the minibuffer, prompting with
+string @var{prompt},and returns the coding system name as a symbol.  If
+the user tries to enter null input, it asks the user to try again.
+@xref{Coding Systems}.
+@end defun
+
 @node Default Coding Systems
 @section Default Coding Systems
 
@@ -480,9 +518,9 @@ This function looks up the target in @code{file-coding-system-alist},
 certain files or when running certain subprograms.  The idea of these
 variables is that you set them once and for all to the defaults you
 want, and then do not change them again.  To specify a particular coding
-system for a particular operation, don't change these variables;
-instead, override them using @code{coding-system-for-read} and
-@code{coding-system-for-write} (@pxref{Specifying Coding Systems}).
+system for a particular operation in a Lisp program, don't change these
+variables; instead, override them using @code{coding-system-for-read}
+and @code{coding-system-for-write} (@pxref{Specifying Coding Systems}).
 
 @tindex file-coding-system-alist
 @defvar file-coding-system-alist
@@ -519,7 +557,7 @@ other coding systems later using @code{set-process-coding-system}.
 @defvar network-coding-system-alist
 This variable is an alist that specifies the coding system to use for
 network streams.  It works much like @code{file-coding-system-alist},
-with the difference that the @var{pattern} in an elemetn may be either a
+with the difference that the @var{pattern} in an element may be either a
 port number or a regular expression.  If it is a regular expression, it
 is matched against the network service name used to open the network
 stream.
@@ -561,7 +599,7 @@ of the right way to use the variable:
 
 @example
 ;; @r{Read the file with no character code conversion.}
-;; @r{Assume CRLF represents end-of-line.}
+;; @r{Assume @sc{crlf} represents end-of-line.}
 (let ((coding-system-for-write 'emacs-mule-dos))
   (insert-file-contents filename))
 @end example
@@ -587,7 +625,7 @@ affect it.
 
 @tindex last-coding-system-used
 @defvar last-coding-system-used
-All operations that use a coding system set this variable
+All I/O operations that use a coding system set this variable
 to the coding system name that was used.
 @end defvar
 
@@ -646,32 +684,34 @@ text.  They are ``raw bytes''---bytes that represent text in the same
 way that an external file would.  When a buffer contains raw bytes, it
 is most natural to mark that buffer as using unibyte representation,
 using @code{set-buffer-multibyte} (@pxref{Selecting a Representation}),
-but this is not required.
+but this is not required.  If the buffer's contents are only temporarily
+raw, leave the buffer multibyte, which will be correct after you decode
+them.
 
   The usual way to get raw bytes in a buffer, for explicit decoding, is
-to read them with from a file with @code{insert-file-contents-literally}
+to read them from a file with @code{insert-file-contents-literally}
 (@pxref{Reading from Files}) or specify a non-@code{nil} @var{rawfile}
-arguments when visiting a file with @code{find-file-noselect}.
+argument when visiting a file with @code{find-file-noselect}.
 
   The usual way to use the raw bytes that result from explicitly
 encoding text is to copy them to a file or process---for example, to
-write it with @code{write-region} (@pxref{Writing to Files}), and
+write them with @code{write-region} (@pxref{Writing to Files}), and
 suppress encoding for that @code{write-region} call by binding
 @code{coding-system-for-write} to @code{no-conversion}.
 
 @tindex encode-coding-region
 @defun encode-coding-region start end coding-system
 This function encodes the text from @var{start} to @var{end} according
-to coding system @var{coding-system}.  The encoded text replaces
-the original text in the buffer.  The result of encoding is
-``raw bytes.''
+to coding system @var{coding-system}.  The encoded text replaces the
+original text in the buffer.  The result of encoding is ``raw bytes,''
+but the buffer remains multibyte if it was multibyte before.
 @end defun
 
 @tindex encode-coding-string
 @defun encode-coding-string string coding-system
 This function encodes the text in @var{string} according to coding
 system @var{coding-system}.  It returns a new string containing the
-encoded text.  The result of encoding is ``raw bytes.''
+encoded text.  The result of encoding is a unibyte string of ``raw bytes.''
 @end defun
 
 @tindex decode-coding-region
@@ -689,3 +729,72 @@ system @var{coding-system}.  It returns a new string containing the
 decoded text.  To make explicit decoding useful, the contents of
 @var{string} ought to be ``raw bytes.''
 @end defun
+
+@node MS-DOS File Types
+@section MS-DOS File Types
+@cindex DOS file types
+@cindex MS-DOS file types
+@cindex Windows file types
+@cindex file types on MS-DOS and Windows
+@cindex text files and binary files
+@cindex binary files and text files
+
+  Emacs on MS-DOS and on MS-Windows recognizes certain file names as
+text files or binary files.  For a text file, Emacs always uses DOS
+end-of-line conversion.  For a binary file, Emacs does no end-of-line
+conversion and no character code conversion.
+
+@defvar buffer-file-type
+This variable, automatically buffer-local in each buffer, records the
+file type of the buffer's visited file.  The value is @code{nil} for
+text, @code{t} for binary.  When a buffer does not specify a coding
+system with @code{buffer-file-coding-system}, this variable is used by
+the function @code{find-buffer-file-type-coding-system} to determine
+which coding system to use when writing the contents of the buffer.
+@end defvar
+
+@defopt file-name-buffer-file-type-alist
+This variable holds an alist for recognizing text and binary files.
+Each element has the form (@var{regexp} . @var{type}), where
+@var{regexp} is matched against the file name, and @var{type} may be
+@code{nil} for text, @code{t} for binary, or a function to call to
+compute which.  If it is a function, then it is called with a single
+argument (the file name) and should return @code{t} or @code{nil}.
+
+Emacs when running on MS-DOS or MS-Windows checks this alist to decide
+which coding system to use when reading a file.  For a text file,
+@code{undecided-dos} is used.  For a binary file, @code{no-conversion}
+is used.
+
+If no element in this alist matches a given file name, then
+@code{default-buffer-file-type} says how to treat the file.
+@end defopt
+
+@defopt default-buffer-file-type
+This variable says how to handle files for which
+@code{file-name-buffer-file-type-alist} says nothing about the type.
+
+If this variable is non-@code{nil}, then these files are treated as
+binary.  Otherwise, nothing special is done for them---the coding system
+is deduced solely from the file contents, in the usual Emacs fashion.
+@end defopt
+
+@node MS-DOS Subprocesses
+@section MS-DOS Subprocesses
+
+  On Microsoft operating systems, these variables provide an alternative
+way to specify the kind of end-of-line conversion to use for input and
+output.  The variable @code{binary-process-input} applies to input sent
+to the subprocess, and @code{binary-process-output} applies to output
+received from it.  A non-@code{nil} value means the data is ``binary,''
+and @code{nil} means the data is text.
+
+@defvar binary-process-input
+If this variable is @code{nil}, convert newlines to @sc{crlf} sequences in
+the input to a synchronous subprocess.
+@end defvar
+
+@defvar binary-process-output
+If this variable is @code{nil}, convert @sc{crlf} sequences to newlines in
+the output from a synchronous subprocess.
+@end defvar
diff --git a/lispref/numbers.texi b/lispref/numbers.texi
index ab03d384b7e..daee3890e77 100644
--- a/lispref/numbers.texi
+++ b/lispref/numbers.texi
@@ -12,9 +12,9 @@
 @dfn{floating point numbers}.  Integers are whole numbers such as
 @minus{}3, 0, 7, 13, and 511.  Their values are exact.  Floating point
 numbers are numbers with fractional parts, such as @minus{}4.5, 0.0, or
-2.71828.  They can also be expressed in exponential notation:
-1.5e2 equals 150; in this example, @samp{e2} stands for ten to the
-second power, and is multiplied by 1.5.  Floating point values are not
+2.71828.  They can also be expressed in exponential notation: 1.5e2
+equals 150; in this example, @samp{e2} stands for ten to the second
+power, and that is multiplied by 1.5.  Floating point values are not
 exact; they have a fixed, limited amount of precision.
 
 @menu
@@ -149,9 +149,9 @@ values.  It also provides for a class of values called NaN or
 there is no correct answer.  For example, @code{(sqrt -1.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 this manual
+which NaN value should be used in a particular case, so Emacs Lisp
 doesn't try to distinguish them.  Here are the read syntaxes for
-these numbers:
+these special floating point values:
 
 @table @asis
 @item positive infinity
@@ -162,6 +162,10 @@ these numbers:
 @samp{0.0e+NaN}.
 @end table
 
+  In addition, the value @code{-0.0} is distinguishable from ordinary
+zero in IEEE floating point (although @code{equal} and @code{=} consider
+them equal values).
+
   You can use @code{logb} to extract the binary exponent of a floating
 point number (or estimate the logarithm of an integer):
 
@@ -323,6 +327,10 @@ This function returns the smallest of its arguments.
 @end example
 @end defun
 
+@defun abs number
+This returns the absolute value of @var{number}.
+@end defun
+
 @node Numeric Conversions
 @section Numeric Conversions
 @cindex rounding in conversions
@@ -378,7 +386,7 @@ commonly used.
   All of these functions except @code{%} return a floating point value
 if any argument is floating.
 
-  It is important to note that in GNU Emacs Lisp, arithmetic functions
+  It is important to note that in Emacs Lisp, arithmetic functions
 do not check for overflow.  Thus @code{(1+ 134217727)} may evaluate to
 @minus{}134217728, depending on your hardware.
 
@@ -414,10 +422,6 @@ like this:
 This function returns @var{number-or-marker} minus 1.
 @end defun
 
-@defun abs number
-This returns the absolute value of @var{number}.
-@end defun
-
 @defun + &rest numbers-or-markers
 This function adds its arguments together.  When given no arguments,
 @code{+} returns 0.
@@ -478,8 +482,10 @@ permits machine-dependent rounding.  As a practical matter, all known
 machines round in the standard fashion.
 
 @cindex @code{arith-error} in division
-If you divide by 0, an @code{arith-error} error is signaled.
-(@xref{Errors}.)
+If you divide an integer by 0, an @code{arith-error} error is signaled.
+(@xref{Errors}.)  Floating point division by zero returns either
+infinity or a NaN if your machine supports IEEE floating point;
+otherwise, it signals an @code{arith-error} error.
 
 @example
 @group
@@ -488,6 +494,12 @@ If you divide by 0, an @code{arith-error} error is signaled.
 @end group
 (/ 5 2)
      @result{} 2
+(/ 5.0 2)
+     @result{} 2.5
+(/ 5 2.0)
+     @result{} 2.5
+(/ 5.0 2.0)
+     @result{} 2.5
 (/ 25 3 2)
      @result{} 4
 (/ -17 6)
@@ -925,9 +937,8 @@ bit is one in the result if, and only if, the @var{n}th bit is zero in
 @cindex transcendental functions
 @cindex mathematical functions
 
-These mathematical functions are available if floating point is
-supported.  They allow integers as well as floating point numbers
-as arguments.
+  These mathematical functions allow integers as well as floating point
+numbers as arguments.
 
 @defun sin arg
 @defunx cos arg
diff --git a/lispref/objects.texi b/lispref/objects.texi
index 66734920de9..ea1e8fb1632 100644
--- a/lispref/objects.texi
+++ b/lispref/objects.texi
@@ -25,7 +25,7 @@ but not for ``the'' type of an object.
 which all other types are constructed, are called @dfn{primitive
 types}.  Each object belongs to one and only one primitive type.  These
 types include @dfn{integer}, @dfn{float}, @dfn{cons}, @dfn{symbol},
-@dfn{string}, @dfn{vector}, @dfn{subr}, @dfn{byte-code function}, and
+@dfn{string}, @dfn{vector}, @dfn{subr}, @dfn{byte-code function}, plus
 several special types, such as @dfn{buffer}, that are related to
 editing.  (@xref{Editing Types}.)
 
@@ -69,8 +69,9 @@ input accepted by the Lisp reader (the function @code{read}) for that
 object.  @xref{Read and Print}.
 
   Most objects have more than one possible read syntax.  Some types of
-object have no read syntax; except for these cases, the printed
-representation of an object is also a read syntax for it.
+object have no read syntax, since it may not make sense to enter objects
+of these types directly in a Lisp program.  Except for these cases, the
+printed representation of an object is also a read syntax for it.
 
   In other languages, an expression is text; it has no other form.  In
 Lisp, an expression is primarily a Lisp object and only secondarily the
@@ -80,14 +81,12 @@ mind, or you will occasionally be very confused.
 
 @cindex hash notation
   Every type has a printed representation.  Some types have no read
-syntax, since it may not make sense to enter objects of these types
-directly in a Lisp program.  For example, the buffer type does not have
-a read syntax.  Objects of these types are printed in @dfn{hash
-notation}: the characters @samp{#<} followed by a descriptive string
-(typically the type name followed by the name of the object), and closed
-with a matching @samp{>}.  Hash notation cannot be read at all, so the
-Lisp reader signals the error @code{invalid-read-syntax} whenever it
-encounters @samp{#<}.
+syntax---for example, the buffer type has none.  Objects of these types
+are printed in @dfn{hash notation}: the characters @samp{#<} followed by
+a descriptive string (typically the type name followed by the name of
+the object), and closed with a matching @samp{>}.  Hash notation cannot
+be read at all, so the Lisp reader signals the error
+@code{invalid-read-syntax} whenever it encounters @samp{#<}.
 @kindex invalid-read-syntax
 
 @example
@@ -190,8 +189,7 @@ leading @samp{+} or a final @samp{.}.
 1                ; @r{The integer 1.}
 1.               ; @r{Also The integer 1.}
 +1               ; @r{Also the integer 1.}
-268435457        ; @r{Also the integer 1!} 
-                 ; @r{  (on a 28-bit implementation)}
+268435457        ; @r{Also the integer 1 on a 28-bit implementation.}
 @end group
 @end example
 
@@ -226,9 +224,10 @@ characters.  @xref{String Type}.
 
   Characters in strings, buffers, and files are currently limited to the
 range of 0 to 524287---nineteen bits.  But not all values in that range
-are valid character codes.  Characters that represent keyboard input
-have a much wider range, so they can modifier keys such as Control, Meta
-and Shift.
+are valid character codes.  Codes 0 through 127 are ASCII codes; the
+rest are non-ASCII (@pxref{Non-ASCII Characters}).  Characters that represent
+keyboard input have a much wider range, to encode modifier keys such as
+Control, Meta and Shift.
 
 @cindex read syntax for characters
 @cindex printed representation for characters
@@ -283,7 +282,7 @@ respectively.  Thus,
 ?\a @result{} 7                 ; @r{@kbd{C-g}}
 ?\b @result{} 8                 ; @r{backspace, @key{BS}, @kbd{C-h}}
 ?\t @result{} 9                 ; @r{tab, @key{TAB}, @kbd{C-i}}
-?\n @result{} 10                ; @r{newline, @key{LFD}, @kbd{C-j}}
+?\n @result{} 10                ; @r{newline, @kbd{C-j}}
 ?\v @result{} 11                ; @r{vertical tab, @kbd{C-k}}
 ?\f @result{} 12                ; @r{formfeed character, @kbd{C-l}}
 ?\r @result{} 13                ; @r{carriage return, @key{RET}, @kbd{C-m}}
@@ -314,9 +313,9 @@ equivalent to @samp{?\^I} and to @samp{?\^i}:
 that exist in @sc{ASCII}; but for keyboard input purposes, you can turn
 any character into a control character with @samp{C-}.  The character
 codes for these non-@sc{ASCII} control characters include the
-@iftex
+@tex
 $2^{26}$
-@end iftex
+@end tex
 @ifinfo
 2**26
 @end ifinfo
@@ -334,21 +333,22 @@ the control equivalent of @kbd{?}:
 
 @noindent
 As a result, it is currently not possible to represent the character
-@kbd{Control-?}, which is a meaningful input character under X.  It is
-not easy to change this as various Lisp files refer to @key{DEL} in this
-way.
+@kbd{Control-?}, which is a meaningful input character under X, using
+@samp{\C-}.  It is not easy to change this, as various Lisp files refer
+to @key{DEL} in this way.
 
   For representing control characters to be found in files or strings,
 we recommend the @samp{^} syntax; for control characters in keyboard
-input, we prefer the @samp{C-} syntax.  This does not affect the meaning
-of the program, but may guide the understanding of people who read it.
+input, we prefer the @samp{C-} syntax.  Which one you use does not
+affect the meaning of the program, but may guide the understanding of
+people who read it.
 
 @cindex meta characters
   A @dfn{meta character} is a character typed with the @key{META}
 modifier key.  The integer that represents such a character has the
-@iftex
+@tex
 $2^{27}$
-@end iftex
+@end tex
 @ifinfo
 2**27
 @end ifinfo
@@ -357,9 +357,9 @@ use high bits for this and other modifiers to make possible a wide range
 of basic character codes.
 
   In a string, the
-@iftex
+@tex
 $2^{7}$
-@end iftex
+@end tex
 @ifinfo
 2**7
 @end ifinfo
@@ -380,15 +380,15 @@ or as @samp{?\M-\101}.  Likewise, you can write @kbd{C-M-b} as
 for example, @sc{ASCII} distinguishes between the characters @samp{a}
 and @samp{A}.  But @sc{ASCII} has no way to represent whether a control
 character is upper case or lower case.  Emacs uses the
-@iftex
+@tex
 $2^{25}$
-@end iftex
+@end tex
 @ifinfo
 2**25
 @end ifinfo
-bit to indicate that the shift key was used for typing a control
+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 indicate the
+or other special terminals; ordinary terminals do not report the
 distinction to the computer in any way.
 
 @cindex hyper characters
@@ -398,10 +398,10 @@ distinction to the computer in any way.
 in a character: @dfn{hyper}, @dfn{super} and @dfn{alt}.  The syntaxes
 for these bits are @samp{\H-}, @samp{\s-} and @samp{\A-}.  Thus,
 @samp{?\H-\M-\A-x} represents @kbd{Alt-Hyper-Meta-x}.
-@iftex
+@tex
 Numerically, the
 bit values are $2^{22}$ for alt, $2^{23}$ for super and $2^{24}$ for hyper.
-@end iftex
+@end tex
 @ifinfo
 Numerically, the
 bit values are 2**22 for alt, 2**23 for super and 2**24 for hyper.
@@ -434,7 +434,7 @@ digits, so you can represent any character code in this way.
 Thus, @samp{?\x41} for the character @kbd{A}, @samp{?\x1} for the
 character @kbd{C-a}, and @code{?\x8c0} for the character
 @iftex
-@`a.
+@samp{@`a}.
 @end iftex
 @ifinfo
 @samp{a} with grave accent.
@@ -478,7 +478,7 @@ backslash.  In contrast to its use in strings, however, a backslash in
 the name of a symbol simply quotes the single character that follows the
 backslash.  For example, in a string, @samp{\t} represents a tab
 character; in the name of a symbol, however, @samp{\t} merely quotes the
-letter @kbd{t}.  To have a symbol with a tab character in its name, you
+letter @samp{t}.  To have a symbol with a tab character in its name, you
 must actually use a tab (preceded with a backslash).  But it's rare to
 do such a thing.
 
@@ -525,26 +525,28 @@ 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 and vectors.  Vectors can
-hold elements of any type, but string elements must be characters in the
-range from 0 to 255.  However, the characters in a string can have text
-properties like characters in a buffer (@pxref{Text Properties});
-vectors do not support text properties even when their elements happen
-to be characters.
-
-  Lists, strings and vectors are different, but they have important
-similarities.  For example, all have a length @var{l}, and all have
-elements which can be indexed from zero to @var{l} minus one.  Also,
-several functions, called sequence functions, accept any kind of
+  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}.  The characters in a string can have text properties like
+characters in a buffer (@pxref{Text Properties}); vectors and
+bool-vectors do not support text properties even when their elements
+happen to be characters.  Char-tables are like vectors except that they
+are indexed by any valid character code.
+
+  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}.
 
-  It is impossible to read the same sequence twice, since sequences are
-always created anew upon reading.  If you read the read syntax for a
-sequence twice, you get two sequences with equal contents.  There is one
-exception: the empty list @code{()} always stands for the same object,
-@code{nil}.
+  It is generally impossible to read the same sequence twice, since
+sequences are always created anew upon reading.  If you read the read
+syntax for a sequence twice, you get two sequences with equal contents.
+There is one exception: the empty list @code{()} always stands for the
+same object, @code{nil}.
 
 @node Cons Cell Type
 @subsection Cons Cell and List Types
@@ -596,8 +598,9 @@ violet buttercup)}:
 
 @example
 @group
-    ___ ___      ___ ___      ___ ___
-   |___|___|--> |___|___|--> |___|___|--> nil
+    --- ---      --- ---      --- ---
+   |   |   |--> |   |   |--> |   |   |--> nil
+    --- ---      --- ---      --- ---
      |            |            |
      |            |            |
       --> rose     --> violet   --> buttercup
@@ -653,8 +656,9 @@ depicted with boxes and arrows:
 
 @example
 @group
-    ___ ___      ___ ___
-   |___|___|--> |___|___|--> nil
+    --- ---      --- ---
+   |   |   |--> |   |   |--> nil
+    --- ---      --- ---
      |            |
      |            |
       --> A        --> nil
@@ -688,8 +692,9 @@ shows the pair @code{(rose . violet)}:
 
 @example
 @group
-    ___ ___
-   |___|___|--> violet
+    --- ---
+   |   |   |--> violet
+    --- ---
      |
      |
       --> rose
@@ -703,8 +708,9 @@ chain of cons cells with a non-@code{nil} final @sc{cdr}.  For example,
 
 @example
 @group
-    ___ ___      ___ ___
-   |___|___|--> |___|___|--> buttercup
+    --- ---      --- ---
+   |   |   |--> |   |   |--> buttercup
+    --- ---      --- ---
      |            |
      |            |
       --> rose     --> violet
@@ -720,8 +726,9 @@ and looks like this:
 
 @example
 @group
-    ___ ___      ___ ___
-   |___|___|--> |___|___|--> nil
+    --- ---      --- ---
+   |   |   |--> |   |   |--> nil
+    --- ---      --- ---
      |            |
      |            |
       --> rose     --> violet
@@ -735,8 +742,9 @@ It looks like this:
 
 @example
 @group
-    ___ ___      ___ ___      ___ ___
-   |___|___|--> |___|___|--> |___|___|--> nil
+    --- ---      --- ---      --- ---
+   |   |   |--> |   |   |--> |   |   |--> nil
+    --- ---      --- ---      --- ---
      |            |            |
      |            |            |
       --> rose     --> violet   --> buttercup
@@ -775,27 +783,35 @@ functions that work on alists.
 
   An @dfn{array} is composed of an arbitrary number of slots for
 referring to other Lisp objects, arranged in a contiguous block of
-memory.  Accessing any element of an array takes the same amount of
-time.  In contrast, accessing an element of a list requires time
-proportional to the position of the element in the list.  (Elements at
-the end of a list take longer to access than elements at the beginning
-of a list.)
-
-  Emacs defines two types of array, strings and vectors.  A string is an
-array of characters and a vector is an array of arbitrary objects.  Both
-are one-dimensional.  (Most other programming languages support
-multidimensional arrays, but they are not essential; you can get the
-same effect with an array of arrays.)  Each type of array has its own
-read syntax; see @ref{String Type}, and @ref{Vector Type}.
-
-  An array may have any length up to the largest integer; but once
-created, it has a fixed size.  The first element of an array has index
-zero, the second element has index 1, and so on.  This is called
-@dfn{zero-origin} indexing.  For example, an array of four elements has
-indices 0, 1, 2, @w{and 3}.
-
-  The array type is contained in the sequence type and contains both the
-string type and the vector type.
+memory.  Accessing any element of an array takes approximately the same
+amount of time.  In contrast, accessing an element of a list requires
+time proportional to the position of the element in the list.  (Elements
+at the end of a list take longer to access than elements at the
+beginning of a list.)
+
+  Emacs defines four types of array: strings, vectors, bool-vectors, and
+char-tables.
+
+  A string is an array of characters and a vector is an array of
+arbitrary objects.  A bool-vector can hold only @code{t} or @code{nil}.
+These kinds of array may have any length up to the largest integer.
+Char-tables are sparse arrays indexed by any valid character code; they
+can hold arbitrary objects.
+
+  The first element of an array has index zero, the second element has
+index 1, and so on.  This is called @dfn{zero-origin} indexing.  For
+example, an array of four elements has indices 0, 1, 2, @w{and 3}.  The
+largest possible index value is one less than the length of the array.
+Once an array is created, its length is fixed.
+
+  All Emacs Lisp arrays are one-dimensional.  (Most other programming
+languages support multidimensional arrays, but they are not essential;
+you can get the same effect with an array of arrays.)  Each type of
+array has its own read syntax; see the following sections for details.
+
+  The array type is contained in the sequence type and
+contains the string type, the vector type, the bool-vector type, and the
+char-table type.
 
 @node String Type
 @subsection String Type
@@ -854,10 +870,13 @@ but the newline is ignored if escaped."
 constant by writing it literally.  There are two text representations
 for non-@sc{ASCII} characters in Emacs strings (and in buffers): unibyte
 and multibyte.  If the string constant is read from a multibyte source,
-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.
+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.
 
+@c ??? Change this?
   You can also represent a multibyte non-@sc{ASCII} character with its
 character code, using a hex escape, @samp{\x@var{nnnnnnn}}, with as many
 digits as necessary.  (Multibyte non-@sc{ASCII} character codes are all
@@ -895,9 +914,9 @@ characters.
 
   If you use the @samp{\M-} syntax to indicate a meta character in a
 string constant, this sets the
-@iftex
+@tex
 $2^{7}$
-@end iftex
+@end tex
 @ifinfo
 2**7
 @end ifinfo
@@ -975,9 +994,24 @@ special purposes.  A char-table can also specify a single value for
 a whole character set.
 
   The printed representation of a char-table is like a vector
-except that there is an extra @samp{#} at the beginning.
+except that there is an extra @samp{#^} at the beginning.
 
   @xref{Char-Tables}, for special functions to operate on char-tables.
+Uses of char-tables include:
+
+@itemize @bullet
+@item
+Case tables (@pxref{Case Tables}).
+
+@item
+Character category tables (@pxref{Categories}).
+
+@item
+Display Tables (@pxref{Display Tables}).
+
+@item
+Syntax tables (@pxref{Syntax Tables}).
+@end itemize
 
 @node Bool-Vector Type
 @subsection Bool-Vector Type
@@ -999,6 +1033,9 @@ make no difference.
      @result{} #&3"\377"
 (make-bool-vector 3 nil)
      @result{} #&3"\0""
+;; @r{These are equal since only the first 3 bits are used.}
+(equal #&3"\377" #&3"\340")
+     @result{} t
 @end example
 
 @node Function Type
@@ -1027,7 +1064,7 @@ functions @code{funcall} and @code{apply}.  @xref{Calling Functions}.
 
   A @dfn{Lisp macro} is a user-defined construct that extends the Lisp
 language.  It is represented as an object much like a function, but with
-different parameter-passing semantics.  A Lisp macro has the form of a
+different argument-passing semantics.  A Lisp macro has the form of a
 list whose first element is the symbol @code{macro} and whose @sc{cdr}
 is a Lisp function object, including the @code{lambda} symbol.
 
@@ -1053,12 +1090,12 @@ not evaluate all its arguments is called a @dfn{special form}
 (@pxref{Special Forms}).@refill
 
   It does not matter to the caller of a function whether the function is
-primitive.  However, this does matter if you try to substitute a
-function written in Lisp for a primitive of the same name.  The reason
-is that the primitive function may be called directly from C code.
-Calls to the redefined function from Lisp will use the new definition,
-but calls from C code may still use the built-in definition.  Therefore,
-@strong{we discourage redefinition of primitive functions}.
+primitive.  However, this does matter if you try to redefine a primitive
+with a function written in Lisp.  The reason is that the primitive
+function may be called directly from C code.  Calls to the redefined
+function from Lisp will use the new definition, but calls from C code
+may still use the built-in definition.  Therefore, @strong{we discourage
+redefinition of primitive functions}.
 
   The term @dfn{function} refers to all Emacs functions, whether written
 in Lisp or C.  @xref{Function Type}, for information about the
@@ -1114,9 +1151,10 @@ symbol.  @xref{Autoload}, for more details.
 @section Editing Types
 @cindex editing types
 
-  The types in the previous section are common to many Lisp dialects.
-Emacs Lisp provides several additional data types for purposes connected
-with editing.
+  The types in the previous section used for general programming
+purposes, and most of them are common to most Lisp dialects.  Emacs Lisp
+provides several additional data types for purposes connected with
+editing.
 
 @menu
 * Buffer Type::         The basic object of editing.
@@ -1124,11 +1162,10 @@ with editing.
 * Window Type::         Buffers are displayed in windows.
 * Frame Type::          Windows subdivide frames.
 * Window Configuration Type::   Recording the way a frame is subdivided.
+* Frame Configuration Type::    Recording the status of all frames.
 * Process Type::        A process running on the underlying OS.
 * Stream Type::         Receive or send characters.
 * Keymap Type::         What function a keystroke invokes.
-* Syntax Table Type::   What a character means.
-* Display Table Type::  How display tables are represented.
 * Overlay Type::        How an overlay is represented.
 @end menu
 
@@ -1144,8 +1181,8 @@ buffer need not be displayed in any window.
 
   The contents of a buffer are much like a string, but buffers are not
 used like strings in Emacs Lisp, and the available operations are
-different.  For example, insertion of text into a buffer is very
-efficient, whereas ``inserting'' text into a string requires
+different.  For example, you can insert text efficiently into an
+existing buffer, whereas ``inserting'' text into a string requires
 concatenating substrings, and the result is an entirely new string
 object.
 
@@ -1167,10 +1204,10 @@ a local syntax table (@pxref{Syntax Tables});
 a local keymap (@pxref{Keymaps}); and,
 
 @item
-a local variable binding list (@pxref{Buffer-Local Variables}).
+a list of buffer-local variable bindings (@pxref{Buffer-Local Variables}).
 
 @item
-a list of overlays (@pxref{Overlays}).
+overlays (@pxref{Overlays}).
 
 @item
 text properties for the text in the buffer (@pxref{Text Properties}).
@@ -1183,7 +1220,7 @@ behavior of programs in different buffers, without actually changing the
 programs.
 
   A buffer may be @dfn{indirect}, which means it shares the text
-of another buffer.  @xref{Indirect Buffers}.
+of another buffer, but presents it differently.  @xref{Indirect Buffers}.
 
   Buffers have no read syntax.  They print in hash notation, showing the
 buffer name.
@@ -1263,7 +1300,7 @@ uniquely).
 @example
 @group
 (selected-frame)
-     @result{} #<frame xemacs@@mole.gnu.ai.mit.edu 0xdac80>
+     @result{} #<frame emacs@@mole.gnu.ai.mit.edu 0xdac80>
 @end group
 @end example
 
@@ -1282,6 +1319,19 @@ looks like @samp{#<window-configuration>}.  @xref{Window
 Configurations}, for a description of several functions related to
 window configurations.
 
+@node Frame Configuration Type
+@subsection Frame Configuration Type
+@cindex screen layout
+
+  A @dfn{frame configuration} stores information about the positions,
+sizes, and contents of the windows in all frames.  It is actually
+a list whose @sc{car} is @code{frame-configuration} and whose
+@sc{cdr} is an alist.  Each alist element describes one frame,
+which appears as the @sc{car} of that element.
+
+  @xref{Frame Configurations}, for a description of several functions
+related to frame configurations.
+
 @node Process Type
 @subsection Process Type
 
@@ -1343,36 +1393,6 @@ a list whose @sc{car} is the symbol @code{keymap}.
   @xref{Keymaps}, for information about creating keymaps, handling prefix
 keys, local as well as global keymaps, and changing key bindings.
 
-@node Syntax Table Type
-@subsection Syntax Table Type
-
-  A @dfn{syntax table} is a char-table which specifies the syntax of
-each character, for word and list parsing.  Each element of the syntax
-table defines how one character is interpreted when it appears in a
-buffer.  For example, in C mode (@pxref{Major Modes}), the @samp{+}
-character is punctuation, but in Lisp mode it is a valid character in a
-symbol.  These modes specify different interpretations by changing the
-syntax table entry for @samp{+}, at index 43 in the syntax table.
-
-  Syntax tables are used only to control primitives that scan text in
-buffers, not for reading Lisp expressions.  The syntax that the Lisp
-interpreter uses to read expressions is built into the Emacs source code
-and cannot be changed; thus, to change the list delimiters to be
-@samp{@{} and @samp{@}} instead of @samp{(} and @samp{)} would be
-impossible.  (Some Lisp systems provide ways to redefine the read
-syntax, but we decided to leave this feature out of Emacs Lisp for
-simplicity.)
-
-  @xref{Syntax Tables}, for details about syntax classes and how to make
-and modify syntax tables.
-
-@node Display Table Type
-@subsection Display Table Type
-
-  A @dfn{display table} specifies how to display each character code.
-Each buffer and each window can have its own display table.  A display
-table is actually a char-table.  @xref{Display Tables}.
-
 @node Overlay Type
 @subsection Overlay Type
 
@@ -1437,7 +1457,7 @@ a list and @code{symbolp} to check for a symbol.
          (setq list (append x list)))
 @need 3000
         (t
-         ;; We only handle symbols and lists.
+         ;; We handle only symbols and lists.
          (error "Invalid argument %s in add-on" x))))
 @end example
 
@@ -1451,6 +1471,9 @@ with references to further information.
 @item arrayp
 @xref{Array Functions, arrayp}.
 
+@item bool-vector-p
+@xref{Bool-Vectors, bool-vector-p}.
+
 @item bufferp
 @xref{Buffer Basics, bufferp}.
 
@@ -1458,20 +1481,29 @@ with references to further information.
 @xref{Byte-Code Type, byte-code-function-p}.
 
 @item case-table-p
-@xref{Case Table, case-table-p}.
+@xref{Case Tables, case-table-p}.
 
 @item char-or-string-p
 @xref{Predicates for Strings, char-or-string-p}.
 
+@item char-table-p
+@xref{Char-Tables, char-table-p}.
+
 @item commandp
 @xref{Interactive Call, commandp}.
 
 @item consp
 @xref{List-related Predicates, consp}.
 
+@item display-table-p
+@xref{Display Tables, display-table-p}.
+
 @item floatp
 @xref{Predicates on Numbers, floatp}.
 
+@item frame-configuration-p
+@xref{Frame Configurations, frame-configuration-p}.
+
 @item frame-live-p
 @xref{Deleting Frames, frame-live-p}.
 
@@ -1556,8 +1588,9 @@ types.  In most cases, it is more convenient to use type predicates than
 This function returns a symbol naming the primitive type of
 @var{object}.  The value is one of the symbols @code{symbol},
 @code{integer}, @code{float}, @code{string}, @code{cons}, @code{vector},
-@code{marker}, @code{overlay}, @code{window}, @code{buffer},
-@code{subr}, @code{compiled-function}, @code{process}, or
+@code{char-table}, @code{bool-vector}, @code{subr},
+@code{compiled-function}, @code{marker}, @code{overlay}, @code{window},
+@code{buffer}, @code{frame}, @code{process}, or
 @code{window-configuration}.
 
 @example
@@ -1594,11 +1627,6 @@ 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.
 
-(The @code{make-symbol} function returns an uninterned symbol that is
-not interned in the standard @code{obarray}.  When uninterned symbols
-are in use, symbol names are no longer unique.  Distinct symbols with
-the same name are not @code{eq}.  @xref{Creating Symbols}.)
-
 @example
 @group
 (eq 'foo 'foo)
@@ -1640,6 +1668,17 @@ the same name are not @code{eq}.  @xref{Creating Symbols}.)
 @end group
 @end example
 
+(The @code{make-symbol} function returns an uninterned symbol that is
+not interned in the standard @code{obarray}.  When uninterned symbols
+are in use, symbol names are no longer unique.  Distinct symbols with
+the same name are not @code{eq}.  @xref{Creating Symbols}.)
+
+@example
+@group
+(eq (make-symbol "foo") 'foo)
+     @result{} nil
+@end group
+@end example
 @end defun
 
 @defun equal object1 object2
diff --git a/lispref/os.texi b/lispref/os.texi
index bea390582d7..a9d58c55aef 100644
--- a/lispref/os.texi
+++ b/lispref/os.texi
@@ -3,7 +3,7 @@
 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc. 
 @c See the file elisp.texi for copying conditions.
 @setfilename ../info/os
-@node System Interface, Display, Processes, Top
+@node System Interface, Tips, Calendar, Top
 @chapter Operating System Interface
 
   This chapter is about starting and getting out of Emacs, access to
@@ -64,7 +64,7 @@ It processes the initial options.  (Some of them are handled
 even earlier than this.)
 
 @item
-It initializes the X window frame and faces, if appropriate.
+It initializes the window frame and faces, if appropriate.
 
 @item
 It runs the normal hook @code{before-init-hook}.
@@ -76,13 +76,13 @@ It loads the library @file{site-start}, unless the option
 @cindex @file{site-start.el}
 
 @item 
-It loads the file @file{~/.emacs} unless @samp{-q} was specified on
-the command line.  (This is not done in @samp{-batch} mode.)  The @samp{-u}
-option can specify the user name whose home directory should be used
+It loads the file @file{~/.emacs}, unless @samp{-q} was specified on the
+command line.  (This is not done in @samp{-batch} mode.)  The @samp{-u}
+option can specify another user name whose home directory should be used
 instead of @file{~}.
 
 @item 
-It loads the library @file{default} unless @code{inhibit-default-init}
+It loads the library @file{default}, unless @code{inhibit-default-init}
 is non-@code{nil}.  (This is not done in @samp{-batch} mode or if
 @samp{-q} was specified on the command line.)  The library's file name
 is usually @file{default.el}.
@@ -461,11 +461,11 @@ likely @code{fg}.
 systems, ``suspension'' actually creates a new shell temporarily as a
 subprocess of Emacs.  Then you would exit the shell to return to Emacs.
 
-  Suspension is not useful with window systems such as X, because the
-Emacs job may not have a parent that can resume it again, and in any
-case you can give input to some other job such as a shell merely by
-moving to a different window.  Therefore, suspending is not allowed
-when Emacs is an X client.
+  Suspension is not useful with window systems, because the Emacs job
+may not have a parent that can resume it again, and in any case you can
+give input to some other job such as a shell merely by moving to a
+different window.  Therefore, suspending is not allowed when Emacs is using
+a window system.
 
 @defun suspend-emacs string
 This function stops Emacs and returns control to the superior process.
@@ -478,10 +478,7 @@ as terminal input by Emacs's superior shell.  The characters in
 appear.
 
 Before suspending, @code{suspend-emacs} runs the normal hook
-@code{suspend-hook}.  In Emacs version 18, @code{suspend-hook} was not a
-normal hook; its value was a single function, and if its value was
-non-@code{nil}, then @code{suspend-emacs} returned immediately without
-actually suspending anything.
+@code{suspend-hook}.
 
 After the user resumes Emacs, @code{suspend-emacs} runs the normal hook
 @code{suspend-resume-hook}.  @xref{Hooks}.
@@ -553,6 +550,12 @@ This variable is a normal hook run after suspending.
 through various functions.  These variables include the name of the
 system, the user's @sc{uid}, and so on.
 
+@defvar system-configuration
+This variable holds the GNU configuration name for the hardware/software
+configuration of your system, as a string.  The convenient way to test
+parts of this string is with @code{string-match}.
+@end defvar
+
 @defvar system-type
 The value of this variable is a symbol indicating the type of operating
 system Emacs is operating on.  Here is a table of the possible values:
@@ -568,10 +571,12 @@ Berkeley BSD.
 Data General DGUX operating system.
 
 @item gnu
-A GNU system (using the GNU kernel, which consists of the HURD and Mach).
+the GNU system (using the GNU kernel, which consists of the HURD and Mach).
 
 @item gnu/linux
-A variant GNU system using the Linux kernel.
+A GNU/Linux system---that is, a variant GNU system, using the Linux
+kernel.  (These systems are the ones people often call ``Linux,'' but
+actually Linux is just the kernel, not the whole system.)
 
 @item hpux
 Hewlett-Packard HPUX operating system.
@@ -611,12 +616,6 @@ alternatives in the future.  We recommend using
 systems.
 @end defvar
 
-@defvar system-configuration
-This variable holds the GNU configuration name for the hardware/software
-configuration of your system, as a string.  The convenient way to test
-parts of this string is with @code{string-match}.
-@end defvar
-
 @defun system-name
 This function returns the name of the machine you are running on.
 @example
@@ -944,7 +943,7 @@ in the past or future.
 Time conversion functions always use the Gregorian calendar, even for
 dates before the Gregorian calendar was introduced.  Year numbers count
 the number of years since the year 1 B.C., and do not skip zero as
-traditional Gregorian years do; for example, the year number -37
+traditional Gregorian years do; for example, the year number @minus{}37
 represents the Gregorian year 38 B.C@.
 
 @defun format-time-string format-string time
@@ -1012,11 +1011,11 @@ This stands for the numeric day of week (0-6).  Sunday is day 0.
 This stands for the week of the year (01-52), assuming that weeks
 start on Monday.
 @item %x
-This has a locale-specific meaning.  In the default locale (named C), it
-is equivalent to @samp{%D}.
+This has a locale-specific meaning.  In the default locale (named
+@samp{C}), it is equivalent to @samp{%D}.
 @item %X
-This has a locale-specific meaning.  In the default locale (named C), it
-is equivalent to @samp{%T}.
+This has a locale-specific meaning.  In the default locale (named
+@samp{C}), it is equivalent to @samp{%T}.
 @item %y
 This stands for the year without century (00-99).
 @item %Y
@@ -1026,8 +1025,8 @@ This stands for the time zone abbreviation.
 @end table
 
 You can also specify the field width and type of padding for any of
-these @samp{%}-constructs.  This works as in @code{printf}: you write
-the field width as digits in the middle of a @samp{%}-construct.  If you
+these @samp{%}-sequences.  This works as in @code{printf}: you write
+the field width as digits in the middle of a @samp{%}-sequences.  If you
 start the field width with 0, it means to pad with zeros.
 
 For example, @samp{%S} specifies the number of seconds since the minute;
@@ -1069,8 +1068,8 @@ An integer indicating the time zone, as the number of seconds east of
 Greenwich.
 @end table
 
-Note that Common Lisp has different meanings for @var{dow} and
-@var{zone}.
+@strong{Common Lisp Note:} Common Lisp has different meanings for
+@var{dow} and @var{zone}.
 @end defun
 
 @defun encode-time seconds minutes hour day month year &optional @dots{}zone
@@ -1111,7 +1110,7 @@ arguments; for example, day 0 means the day preceding the given month.
   You can set up a @dfn{timer} to call a function at a specified future time or
 after a certain length of idleness.
 
-  Emacs cannot run a timer at any arbitrary point in a Lisp program; it
+  Emacs cannot run timers at any arbitrary point in a Lisp program; it
 can run them only when Emacs could accept output from a subprocess:
 namely, while waiting or inside certain primitive functions such as
 @code{sit-for} or @code{read-char} which @emph{can} wait.  Therefore, a
@@ -1124,10 +1123,11 @@ at time @var{time}.  The argument @var{function} is a function to call
 later, and @var{args} are the arguments to give it when it is called.
 The time @var{time} is specified as a string.
 
-Absolute times may be specified in a variety of formats; The form
+Absolute times may be specified in a wide variety of formats, and tries
+to accept all common date formats.  One valid format is
 @samp{@var{hour}:@var{min}:@var{sec} @var{timezone}
-@var{month}/@var{day}/@var{year}}, where all fields are numbers, works;
-the format that @code{current-time-string} returns is also allowed.
+@var{month}/@var{day}/@var{year}}, where all fields are numbers; the
+format that @code{current-time-string} returns is also allowed.
 
 To specify a relative time, use numbers followed by units.
 For example:
@@ -1208,12 +1208,12 @@ idleness will continue to increase and will not go down to five seconds
 again.
 
   Emacs can do various things while idle: garbage collect, autosave or
-handle data from a subprocess.  But these interludes during idleness
-have little effect on idle timers.  An idle timer set for 600 seconds
-will run when ten minutes have elapsed since the last user command was
-finished, even if subprocess output has been accepted thousands of times
-within those ten minutes, even if there have been garbage collections
-and autosaves.
+handle data from a subprocess.  But these interludes during idleness do
+not interfere with idle timers, because they do not reset the clock of
+idleness to zero.  An idle timer set for 600 seconds will run when ten
+minutes have elapsed since the last user command was finished, even if
+subprocess output has been accepted thousands of times within those ten
+minutes, even if there have been garbage collections and autosaves.
 
   When the user supplies input, Emacs becomes non-idle while executing the
 input.  Then it becomes idle again, and all the idle timers that are
@@ -1249,16 +1249,16 @@ functions.
 @defun set-input-mode interrupt flow meta quit-char
 This function sets the mode for reading keyboard input.  If
 @var{interrupt} is non-null, then Emacs uses input interrupts.  If it is
-@code{nil}, then it uses @sc{cbreak} mode.  When Emacs communicates
-directly with X, it ignores this argument and uses interrupts if that is
-the way it knows how to communicate.
+@code{nil}, then it uses @sc{cbreak} mode.  The default setting is
+system dependent.  Some systems always use @sc{cbreak} mode regardless
+of what is specified.
 
-If @var{flow} is non-@code{nil}, then Emacs uses @sc{xon/xoff} (@kbd{C-q},
-@kbd{C-s}) flow control for output to the terminal.  This has no effect except
-in @sc{cbreak} mode.  @xref{Flow Control}.
+When Emacs communicates directly with X, it ignores this argument and
+uses interrupts if that is the way it knows how to communicate.
 
-The default setting is system dependent.  Some systems always use
-@sc{cbreak} mode regardless of what is specified.
+If @var{flow} is non-@code{nil}, then Emacs uses @sc{xon/xoff}
+(@kbd{C-q}, @kbd{C-s}) flow control for output to the terminal.  This
+has no effect except in @sc{cbreak} mode.  @xref{Flow Control}.
 
 @c Emacs 19 feature
 The argument @var{meta} controls support for input character codes
@@ -1267,7 +1267,7 @@ the 8th bit set into Meta characters.  If @var{meta} is @code{nil},
 Emacs disregards the 8th bit; this is necessary when the terminal uses
 it as a parity bit.  If @var{meta} is neither @code{t} nor @code{nil},
 Emacs uses all 8 bits of input unchanged.  This is good for terminals
-using European 8-bit character sets.
+that use 8-bit character sets.
 
 @c Emacs 19 feature
 If @var{quit-char} is non-@code{nil}, it specifies the character to
@@ -1290,8 +1290,8 @@ is non-@code{nil} when Emacs is using interrupt-driven input.  If
 @code{nil}, Emacs is using @sc{cbreak} mode.
 @item flow
 is non-@code{nil} if Emacs uses @sc{xon/xoff} (@kbd{C-q}, @kbd{C-s})
-flow control for output to the terminal.  This value has no effect
-unless @var{interrupt} is non-@code{nil}.
+flow control for output to the terminal.  This value has effect when
+unless @var{interrupt} is @code{nil}.
 @item meta
 is @code{t} if Emacs treats the eighth bit of input characters as
 the meta bit; @code{nil} means Emacs clears the eighth bit of every
@@ -1310,10 +1310,11 @@ is the character Emacs currently uses for quitting, usually @kbd{C-g}.
 other input events before they become part of key sequences.  These
 features apply to each event in the order they are described here: each
 event is first modified according to @code{extra-keyboard-modifiers},
-then translated through @code{keyboard-translate-table} (if applicable).
-If it is being read as part of a key sequence, it is then added to the
-sequece being read; then subsequences containing it are checked first
-with @code{function-key-map} and then with @code{key-translation-map}.
+then translated through @code{keyboard-translate-table} (if applicable),
+and finally decoded with the specified keyboard coding system.  If it is
+being read as part of a key sequence, it is then added to the sequence
+being read; then subsequences containing it are checked first with
+@code{function-key-map} and then with @code{key-translation-map}.
 
 @c Emacs 19 feature
 @defvar extra-keyboard-modifiers
@@ -1334,9 +1335,9 @@ The @key{META} key.
 Each time the user types a keyboard key, it is altered as if the
 modifier keys specified in the bit mask were held down.
 
-When using X windows, the program can ``press'' any of the modifier
-keys in this way.  Otherwise, only the @key{CTL} and @key{META} keys can
-be virtually pressed.
+When using a window system, the program can ``press'' any of the
+modifier keys in this way.  Otherwise, only the @key{CTL} and @key{META}
+keys can be virtually pressed.
 @end defvar
 
 @defvar keyboard-translate-table
@@ -1392,7 +1393,7 @@ the keyboard translate table if necessary.
 
   The remaining translation features translate subsequences of key
 sequences being read.  They are implemented in @code{read-key-sequence}
-and have no effect on @code{read-char}.
+and have no effect on input read with @code{read-event}.
 
 @defvar function-key-map
 This variable holds a keymap that describes the character sequences sent
@@ -1406,7 +1407,7 @@ If @code{function-key-map} ``binds'' a key sequence @var{k} to a vector
 key sequence, it is replaced with the events in @var{v}.
 
 For example, VT100 terminals send @kbd{@key{ESC} O P} when the
-keypad PF1 key is pressed.  Therefore, we want Emacs to translate
+keypad @key{PF1} key is pressed.  Therefore, we want Emacs to translate
 that sequence of events into the single event @code{pf1}.  We accomplish
 this by ``binding'' @kbd{@key{ESC} O P} to @code{[pf1]} in
 @code{function-key-map}, when using a VT100.
@@ -1419,7 +1420,8 @@ this back into @kbd{C-c @key{PF1}}, which it returns as the vector
 Entries in @code{function-key-map} are ignored if they conflict with
 bindings made in the minor mode, local, or global keymaps.  The intent
 is that the character sequences that function keys send should not have
-command bindings in their own right.
+command bindings in their own right---but if they do, the ordinary
+bindings take priority.
 
 The value of @code{function-key-map} is usually set up automatically
 according to the terminal's Terminfo or Termcap entry, but sometimes
@@ -1427,9 +1429,6 @@ those need help from terminal-specific Lisp files.  Emacs comes with
 terminal-specific files for many common terminals; their main purpose is
 to make entries in @code{function-key-map} beyond those that can be
 deduced from Termcap and Terminfo.  @xref{Terminal-Specific}.
-
-Emacs versions 18 and earlier used totally different means of detecting
-the character sequences that represent function keys.
 @end defvar
 
 @defvar key-translation-map
@@ -1494,21 +1493,21 @@ to turn the character that follows into a Hyper character:
 @end group
 @end example
 
-@pindex iso-transl
-@cindex Latin-1 character set (input)
-@cindex ISO Latin-1 characters (input)
-The @file{iso-transl} library uses this feature to provide a way of
-inputting non-ASCII Latin-1 characters.
+Finally, if you have enabled keyboard character set decoding using
+@code{set-keyboard-coding-system}, decoding is done after the
+translations listed above.  @xref{Specifying Coding Systems}.  In future
+Emacs versions, character set decoding may be done before the other
+translations.
 
 @node Recording Input
 @subsection Recording Input
 
 @defun recent-keys
-This function returns a vector containing the last 100 input events
-from the keyboard or mouse.  All input events are included, whether or
-not they were used as parts of key sequences.  Thus, you always get the
-last 100 inputs, not counting keyboard macros.  (Events from keyboard
-macros are excluded because they are less interesting for debugging; it
+This function returns a vector containing the last 100 input events from
+the keyboard or mouse.  All input events are included, whether or not
+they were used as parts of key sequences.  Thus, you always get the last
+100 input events, not counting events generated by keyboard macros.
+(These are excluded because they are less interesting for debugging; it
 should be enough to see the events that invoked the macros.)
 @end defun
 
@@ -1565,9 +1564,8 @@ not.  If Emacs has the wrong value, it makes decisions that are less
 than optimal.  To fix the problem, set @code{baud-rate}.
 
 @defun baud-rate
-This function returns the value of the variable @code{baud-rate}.  In
-Emacs versions 18 and earlier, this was the only way to find out the
-terminal speed.
+This obsolete function returns the value of the variable
+@code{baud-rate}.
 @end defun
 
 @defun send-string-to-terminal string
@@ -1619,15 +1617,28 @@ To define system-specific X11 keysyms, set the variable
 This variable's value should be an alist with one element for each
 system-specific keysym.  An element has this form: @code{(@var{code}
 . @var{symbol})}, where @var{code} is the numeric keysym code (not
-including the ``vendor specific'' bit, 1 << 28), and @var{symbol} is the
-name for the function key.
+including the ``vendor specific'' bit, 
+@ifinfo 
+-2**28,
+@end ifinfo
+@tex 
+$-2^{28}$,
+@end tex
+and @var{symbol} is the name for the function key.
 
 For example @code{(168 . mute-acute)} defines a system-specific key used
-by HP X servers whose numeric code is (1 << 28) + 168.
+by HP X servers whose numeric code is
+@ifinfo 
+-2**28
+@end ifinfo
+@tex 
+$-2^{28}$
+@end tex
++ 168.
 
-It is not a problem if the alist defines keysyms for other X servers, as
-long as they don't conflict with the ones used by the X server actually
-in use.
+It is not crucial to exclude from the alist the keysyms of other X
+servers; those do no harm, as long as they don't conflict with the ones
+used by the X server actually in use.
 
 The variable is always local to the current X terminal and cannot be
 buffer-local.  @xref{Multiple Displays}.
@@ -1637,9 +1648,9 @@ buffer-local.  @xref{Multiple Displays}.
 @section Flow Control
 @cindex flow control characters
 
-  This section attempts to answer the question ``Why does Emacs choose
-to use flow-control characters in its command character set?''  For a
-second view on this issue, read the comments on flow control in the
+  This section attempts to answer the question ``Why does Emacs use
+flow-control characters in its command character set?''  For a second
+view on this issue, read the comments on flow control in the
 @file{emacs/INSTALL} file from the distribution; for help with Termcap
 entries and DEC terminal concentrators, see @file{emacs/etc/TERMS}.
 
@@ -1647,20 +1658,20 @@ entries and DEC terminal concentrators, see @file{emacs/etc/TERMS}.
 @cindex @kbd{C-q}
   At one time, most terminals did not need flow control, and none used
 @code{C-s} and @kbd{C-q} for flow control.  Therefore, the choice of
-@kbd{C-s} and @kbd{C-q} as command characters was uncontroversial.
-Emacs, for economy of keystrokes and portability, used nearly all the
-@sc{ASCII} control characters, with mnemonic meanings when possible;
-thus, @kbd{C-s} for search and @kbd{C-q} for quote.
+@kbd{C-s} and @kbd{C-q} as command characters for searching and quoting
+was natural and uncontroversial.  With so many commands needing key
+assignments. of course we assigned meanings to nearly all @sc{ASCII}
+control characters.
 
   Later, some terminals were introduced which required these characters
 for flow control.  They were not very good terminals for full-screen
-editing, so Emacs maintainers did not pay attention.  In later years,
-flow control with @kbd{C-s} and @kbd{C-q} became widespread among
-terminals, but by this time it was usually an option.  And the majority
-of users, who can turn flow control off, were unwilling to switch to
-less mnemonic key bindings for the sake of flow control.
+editing, so Emacs maintainers ignored them.  In later years, flow
+control with @kbd{C-s} and @kbd{C-q} became widespread among terminals,
+but by this time it was usually an option.  And the majority of Emacs
+users, who can turn flow control off, did not want to switch to less
+mnemonic key bindings for the sake of flow control.
 
-  So which usage is ``right'', Emacs's or that of some terminal and
+  So which usage is ``right''---Emacs's or that of some terminal and
 concentrator manufacturers?  This question has no simple answer.
 
   One reason why we are reluctant to cater to the problems caused by
@@ -1668,13 +1679,13 @@ concentrator manufacturers?  This question has no simple answer.
 techniques (albeit less common in practice) for flow control that
 preserve transparency of the character stream.  Note also that their use
 for flow control is not an official standard.  Interestingly, on the
-model 33 teletype with a paper tape punch (which is very old), @kbd{C-s}
-and @kbd{C-q} were sent by the computer to turn the punch on and off!
+model 33 teletype with a paper tape punch (around 1970), @kbd{C-s} and
+@kbd{C-q} were sent by the computer to turn the punch on and off!
 
-  As X servers and other window systems replace character-only
-terminals, this problem is gradually being cured.  For the mean time,
-Emacs provides a convenient way of enabling flow control if you want it:
-call the function @code{enable-flow-control}.
+  As window systems and PC terminal emulators replace character-only
+terminals, the flow control problem is gradually disappearing.  For the
+mean time, Emacs provides a convenient way of enabling flow control if
+you want it: call the function @code{enable-flow-control}.
 
 @deffn Command enable-flow-control
 This function enables use of @kbd{C-s} and @kbd{C-q} for output flow
diff --git a/lispref/positions.texi b/lispref/positions.texi
index b2cb47efabb..a414abb5dc7 100644
--- a/lispref/positions.texi
+++ b/lispref/positions.texi
@@ -241,7 +241,7 @@ puts point @var{n} tenths of the way from the beginning of the buffer.
 In an interactive call, @var{n} is the numeric prefix argument,
 if provided; otherwise @var{n} defaults to @code{nil}.
 
-Don't use this function in Lisp programs!
+@strong{Warning:} Don't use this function in Lisp programs!
 @end deffn
 
 @deffn Command end-of-buffer &optional n
@@ -253,7 +253,7 @@ point @var{n} tenths of the way from the end of the buffer.
 In an interactive call, @var{n} is the numeric prefix argument,
 if provided; otherwise @var{n} defaults to @code{nil}.
 
-Don't use this function in Lisp programs!
+@strong{Warning:} Don't use this function in Lisp programs!
 @end deffn
 
 @node Text Lines
@@ -759,6 +759,11 @@ The value returned by @code{save-excursion} is the result of the last of
 @end example
 @end defspec
 
+  Although @code{save-excursion} saves the location of the mark, it does
+not prevent functions which modify the buffer from setting
+@code{deactivate-mark}, and thus causing the deactivation of the mark
+after the command finishes.  @xref{The Mark}.
+
 @node Narrowing
 @section Narrowing
 @cindex narrowing
diff --git a/lispref/processes.texi b/lispref/processes.texi
index e9106f3a768..94b8e61bdf3 100644
--- a/lispref/processes.texi
+++ b/lispref/processes.texi
@@ -3,7 +3,7 @@
 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc. 
 @c See the file elisp.texi for copying conditions.
 @setfilename ../info/processes
-@node Processes, System Interface, Abbrevs, Top
+@node Processes, Display, Abbrevs, Top
 @chapter Processes
 @cindex child process
 @cindex parent process
@@ -35,8 +35,6 @@ This function returns @code{t} if @var{object} is a process,
 @menu
 * Subprocess Creation::      Functions that start subprocesses.
 * Synchronous Processes::    Details of using synchronous subprocesses.
-* MS-DOS Subprocesses::      On MS-DOS, you must indicate text vs binary
-                                for data sent to and from a subprocess.
 * Asynchronous Processes::   Starting up an asynchronous subprocess.
 * Deleting Processes::       Eliminating an asynchronous subprocess.
 * Process Information::      Accessing run-status and other attributes.
@@ -127,6 +125,46 @@ The value of @code{exec-path} is used by @code{call-process} and
 file name.
 @end defopt
 
+@node Shell Arguments
+@section Shell Arguments
+
+  Lisp programs sometimes need to run a shell and give it a command
+which contains file names that were specified by the user.  These
+programs ought to be able to support any valid file name.  But the shell
+gives special treatment to certain characters, and if these characters
+occur in the file name, they will confuse the shell.  To handle these
+characters, use the function @code{shell-quote-argument}:
+
+@defun shell-quote-argument argument
+This function returns a string which represents, in shell syntax,
+an argument whose actual contents are @var{argument}.  It should
+work reliably to concatenate the return value into a shell command
+and then pass it to a shell for execution.
+
+Precisely what this function does depends on your operating system.  The
+function is designed to work with the usual shell syntax; if you use an
+unusual shell, you will need to redefine this function.  On MS-DOS, the
+function returns @var{argument} unchanged; while this is not really
+correct, it is the best one can do, since the MS-DOS shell has no
+quoting features.
+
+@example
+;; @r{This example shows the behavior on GNU and Unix systems.}
+(shell-quote-argument "foo > bar")
+     @result{} "foo\\ \\>\\ bar"
+@end example
+
+Here's an example of using @code{shell-quote-argument} to construct
+a shell command:
+
+@example
+(concat "diff -c "
+        (shell-quote-argument oldfile)
+        " "
+        (shell-quote-argument newfile))
+@end example
+@end defun
+
 @node Synchronous Processes
 @section Creating a Synchronous Process
 @cindex synchronous subprocess
@@ -145,13 +183,15 @@ subprocess actually terminates before quitting.  If during that time the
 user types another @kbd{C-g}, that kills the subprocess instantly with
 @code{SIGKILL} and quits immediately.  @xref{Quitting}.
 
-  The synchronous subprocess functions returned @code{nil} in version
-18.  Now they return an indication of how the process terminated.
+  The synchronous subprocess functions return an indication of how the
+process terminated.
 
   The output from a synchronous subprocess is generally decoded using a
 coding system, much like text read from a file.  The input sent to a
 subprocess by @code{call-process-region} is encoded using a coding
 system, much like text written into a file.  @xref{Coding Systems}.
+On Microsoft operating systems, additional variables control
+the conversion for end-of-line (@pxref{MS-DOS Subprocesses}).
 
 @defun call-process program &optional infile destination display &rest args
 This function calls @var{program} in a separate process and waits for
@@ -168,8 +208,7 @@ Insert the output in that buffer, before point.  This includes both the
 standard output stream and the standard error stream of the process.
 
 @item a string
-Find the buffer with that name, then insert the output in that buffer,
-before point.
+Insert the output in a buffer with that name, before point.
 
 @item @code{t}
 Insert the output in the current buffer, before point.
@@ -190,9 +229,9 @@ function returns.
 Keep the standard output stream separate from the standard error stream;
 deal with the ordinary output as specified by @var{real-destination},
 and dispose of the error output according to @var{error-destination}.
-The value @code{nil} means discard it, @code{t} means mix it with the
-ordinary output, and a string specifies a file name to redirect error
-output into.
+If @var{error-destination} is @code{nil}, that means to discard the
+error output, @code{t} means mix it with the ordinary output, and a
+string specifies a file name to redirect error output into.
 
 You can't directly specify a buffer to put the error output in; that is
 too difficult to implement.  But you can achieve this result by sending
@@ -237,12 +276,12 @@ lewis:5LTsHm66CSWKg:398:21:Bil Lewis:/user/lewis:/bin/csh
 @end group
 @end smallexample
 
-The @code{insert-directory} function contains a good example of the use
-of @code{call-process}:
+Here is a good example of the use of @code{call-process}, which used to
+be found in the definition of @code{insert-directory}:
 
 @smallexample
 @group
-(call-process insert-directory-program nil t nil switches
+(call-process insert-directory-program nil t nil @var{switches}
               (if full-directory-p
                   (concat (file-name-as-directory file) ".")
                 file))
@@ -318,32 +357,6 @@ This function executes @var{command} (a string) as a shell command,
 then returns the command's output as a string.
 @end defun
 
-@node MS-DOS Subprocesses
-@section MS-DOS Subprocesses
-
-  On MS-DOS, you must indicate whether the data going to and from
-a synchronous subprocess are text or binary.  Text data requires
-translation between the end-of-line convention used within Emacs
-(a single newline character) and the convention used outside Emacs
-(the two-character sequence, @sc{crlf}).
-
-  The variable @code{binary-process-input} applies to input sent to the
-subprocess, and @code{binary-process-output} applies to output received
-from it.  A non-@code{nil} value means the data is non-text; @code{nil}
-means the data is text, and calls for conversion.
-
-@defvar binary-process-input
-If this variable is @code{nil}, convert newlines to @sc{crlf} sequences in
-the input to a synchronous subprocess.
-@end defvar
-
-@defvar binary-process-output
-If this variable is @code{nil}, convert @sc{crlf} sequences to newlines in
-the output from a synchronous subprocess.
-@end defvar
-
-  @xref{Files and MS-DOS}, for related information.
-
 @node Asynchronous Processes
 @section Creating an Asynchronous Process
 @cindex asynchronous subprocess
@@ -403,6 +416,14 @@ to execute the specified command.  The argument @var{command} is a shell
 command name, and @var{command-args} are the arguments for the shell
 command.  The variable @code{shell-file-name} specifies which shell to
 use.
+
+The point of running a program through the shell, rather than directly
+with @code{start-process}, is so that you can employ shell features such
+as wildcards in the arguments.  It follows that if you include an
+arbitrary user-specified filename in the command, you should quote it
+with @code{shell-quote-argument} first, so that any special shell
+characters in the file name do @emph{not} have their special shell
+meanings.  @xref{Shell Arguments}.
 @end defun
 
 @defvar process-connection-type
@@ -602,9 +623,6 @@ x
 For a network connection, @code{process-status} returns one of the symbols
 @code{open} or @code{closed}.  The latter means that the other side
 closed the connection, or Emacs did @code{delete-process}.
-
-In Emacs version 18, the status of a network connection was @code{run}
-if open, and @code{exit} if closed.
 @end defun
 
 @defun process-exit-status process
@@ -628,8 +646,7 @@ for decoding output from @var{process} and for encoding input to
 @var{process} (@pxref{Coding Systems}).  The value has this form:
 
 @example
-(@var{coding-system-for-decoding}
- . @var{coding-system-for-encoding})
+(@var{coding-system-for-decoding} . @var{coding-system-for-encoding})
 @end example
 @end defun
 
@@ -789,7 +806,7 @@ This function stops the process @var{process-name} by sending the
 signal @code{SIGTSTP}.  Use @code{continue-process} to resume its
 execution.
 
-On systems with job control, outside of Emacs)\, the ``stop character''
+Outside of Emacs, on systems with job control, the ``stop character''
 (usually @kbd{C-z}) normally sends this signal.  When
 @var{current-group} is non-@code{nil}, you can think of this function as
 ``typing @kbd{C-z}'' on the terminal Emacs uses to communicate with the
diff --git a/lispref/searching.texi b/lispref/searching.texi
index 7722b9b1c7f..336865c5642 100644
--- a/lispref/searching.texi
+++ b/lispref/searching.texi
@@ -199,15 +199,15 @@ the string @samp{fo}.  Still trivial.  To do something more powerful, you
 need to use one of the special characters.  Here is a list of them:
 
 @need 1200
-@table @kbd
-@item .@: @r{(Period)}
+@table @asis
+@item @samp{.}@: @r{(Period)}
 @cindex @samp{.} in regexp
 is a special character that matches any single character except a newline.
 Using concatenation, we can make regular expressions like @samp{a.b}, which
 matches any three-character string that begins with @samp{a} and ends with
 @samp{b}.@refill
 
-@item *
+@item @samp{*}
 @cindex @samp{*} in regexp
 is not a construct by itself; it is a postfix operator that means to
 match the preceding regular expression repetitively as many times as
@@ -237,35 +237,35 @@ Emacs must try each imaginable way of grouping the 35 @samp{x}'s before
 concluding that none of them can work.  To make sure your regular
 expressions run fast, check nested repetitions carefully.
 
-@item +
+@item @samp{+}
 @cindex @samp{+} in regexp
 is a postfix operator, similar to @samp{*} except that it must match
 the preceding expression at least once.  So, for example, @samp{ca+r}
 matches the strings @samp{car} and @samp{caaaar} but not the string
 @samp{cr}, whereas @samp{ca*r} matches all three strings.
 
-@item ?
+@item @samp{?}
 @cindex @samp{?} in regexp
 is a postfix operator, similar to @samp{*} except that it must match the
 preceding expression either once or not at all.  For example,
 @samp{ca?r} matches @samp{car} or @samp{cr}; nothing else.
 
-@item [ @dots{} ]
-@cindex character set (in regexp)
+@item @samp{[ @dots{} ]}
+@cindex character alternative (in regexp)
 @cindex @samp{[} in regexp
 @cindex @samp{]} in regexp
-is a @dfn{character set}, which begins with @samp{[} and is terminated
-by @samp{]}.  In the simplest case, the characters between the two
-brackets are what this set can match.
+is a @dfn{character alternative}, which begins with @samp{[} and is
+terminated by @samp{]}.  In the simplest case, the characters between
+the two brackets are what this character alternative can match.
 
 Thus, @samp{[ad]} matches either one @samp{a} or one @samp{d}, and
 @samp{[ad]*} matches any string composed of just @samp{a}s and @samp{d}s
 (including the empty string), from which it follows that @samp{c[ad]*r}
 matches @samp{cr}, @samp{car}, @samp{cdr}, @samp{caddaar}, etc.
 
-You can also include character ranges in a character set, by writing the
-starting and ending characters with a @samp{-} between them.  Thus,
-@samp{[a-z]} matches any lower-case ASCII letter.  Ranges may be
+You can also include character ranges in a character alternative, by
+writing the starting and ending characters with a @samp{-} between them.
+Thus, @samp{[a-z]} matches any lower-case ASCII letter.  Ranges may be
 intermixed freely with individual characters, as in @samp{[a-z$%.]},
 which matches any lower case ASCII letter or @samp{$}, @samp{%} or
 period.
@@ -284,33 +284,33 @@ The beginning and end of a range must be in the same character set
 (@samp{a} with grave accent) is in the Latin-1 character set.
 
 Note that the usual regexp special characters are not special inside a
-character set.  A completely different set of special characters exists
-inside character sets: @samp{]}, @samp{-} and @samp{^}.
+character alternative.  A completely different set of characters are
+special inside character alternatives: @samp{]}, @samp{-} and @samp{^}.
 
-To include a @samp{]} in a character set, you must make it the first
-character.  For example, @samp{[]a]} matches @samp{]} or @samp{a}.  To
-include a @samp{-}, write @samp{-} as the first or last character of the
-set, or put it after a range.  Thus, @samp{[]-]} matches both @samp{]}
-and @samp{-}.
+To include a @samp{]} in a character alternative, you must make it the
+first character.  For example, @samp{[]a]} matches @samp{]} or @samp{a}.
+To include a @samp{-}, write @samp{-} as the first or last character of
+the character alternative, or put it after a range.  Thus, @samp{[]-]}
+matches both @samp{]} and @samp{-}.
 
-To include @samp{^} in a set, put it anywhere but at the beginning of
-the set.
+To include @samp{^} in a character alternative, put it anywhere but at
+the beginning.
 
-@item [^ @dots{} ]
+@item @samp{[^ @dots{} ]}
 @cindex @samp{^} in regexp
-@samp{[^} begins a @dfn{complemented character set}, which matches any
+@samp{[^} begins a @dfn{complemented character alternative}, which matches any
 character except the ones specified.  Thus, @samp{[^a-z0-9A-Z]} matches
 all characters @emph{except} letters and digits.
 
-@samp{^} is not special in a character set unless it is the first
+@samp{^} is not special in a character alternative unless it is the first
 character.  The character following the @samp{^} is treated as if it
 were first (in other words, @samp{-} and @samp{]} are not special there).
 
-A complemented character set can match a newline, unless newline is
+A complemented character alternative can match a newline, unless newline is
 mentioned as one of the characters not to match.  This is in contrast to
 the handling of regexps in programs such as @code{grep}.
 
-@item ^
+@item @samp{^}
 @cindex @samp{^} in regexp
 @cindex beginning of line in regexp
 is a special character that matches the empty string, but only at the
@@ -321,7 +321,7 @@ the beginning of a line.
 When matching a string instead of a buffer, @samp{^} matches at the
 beginning of the string or after a newline character @samp{\n}.
 
-@item $
+@item @samp{$}
 @cindex @samp{$} in regexp
 is similar to @samp{^} but matches only at the end of a line.  Thus,
 @samp{x+$} matches a string of one @samp{x} or more at the end of a line.
@@ -329,7 +329,7 @@ is similar to @samp{^} but matches only at the end of a line.  Thus,
 When matching a string instead of a buffer, @samp{$} matches at the end
 of the string or before a newline character @samp{\n}.
 
-@item \
+@item @samp{\}
 @cindex @samp{\} in regexp
 has two functions: it quotes the special characters (including
 @samp{\}), and it introduces additional special constructs.
@@ -360,7 +360,7 @@ sequences starting with @samp{\} which have special meanings.  The
 second character in the sequence is always an ordinary character on
 their own.  Here is a table of @samp{\} constructs.
 
-@table @kbd
+@table @samp
 @item \|
 @cindex @samp{|} in regexp
 @cindex regexp alternative
@@ -454,7 +454,7 @@ matches any character whose syntax is not @var{code}.
 they don't use up any characters---but whether they match depends on the
 context.
 
-@table @kbd
+@table @samp
 @item \`
 @cindex @samp{\`} in regexp
 matches the empty string, but only at the beginning
@@ -519,7 +519,7 @@ string match when calling a function that wants a regular expression.
 
 One use of @code{regexp-quote} is to combine an exact string match with
 context described as a regular expression.  For example, this searches
-for the string that is the value of @code{string}, surrounded by
+for the string that is the value of @var{string}, surrounded by
 whitespace:
 
 @example
@@ -558,7 +558,7 @@ regular expression which is equivalent to the actual value
 @tindex regexp-opt-depth
 @defun regexp-opt-depth regexp
 This function returns the total number of grouping constructs
-(parenthesised expressions) in @var{regexp}.
+(parenthesized expressions) in @var{regexp}.
 @end defun
 
 @node Regexp Example
@@ -579,14 +579,14 @@ tab and @samp{\n} for a newline.
 "[.?!][]\"')@}]*\\($\\| $\\|\t\\|  \\)[ \t\n]*"
 @end example
 
-  In contrast, if you evaluate the variable @code{sentence-end}, you
+@noindent
+In contrast, if you evaluate the variable @code{sentence-end}, you
 will see the following:
 
 @example
 @group
 sentence-end
-@result{}
-"[.?!][]\"')@}]*\\($\\| $\\|  \\|  \\)[       
+     @result{} "[.?!][]\"')@}]*\\($\\| $\\|  \\|  \\)[       
 ]*"
 @end group
 @end example
@@ -599,16 +599,16 @@ deciphered as follows:
 
 @table @code
 @item [.?!]
-The first part of the pattern is a character set that matches any one of
-three characters: period, question mark, and exclamation mark.  The
-match must begin with one of these three characters.
+The first part of the pattern is a character alternative that matches
+any one of three characters: period, question mark, and exclamation
+mark.  The match must begin with one of these three characters.
 
 @item []\"')@}]*
 The second part of the pattern matches any closing braces and quotation
 marks, zero or more of them, that may follow the period, question mark
 or exclamation mark.  The @code{\"} is Lisp syntax for a double-quote in
 a string.  The @samp{*} at the end indicates that the immediately
-preceding regular expression (a character set, in this case) may be
+preceding regular expression (a character alternative, in this case) may be
 repeated zero or more times.
 
 @item \\($\\|@ $\\|\t\\|@ @ \\)
@@ -630,11 +630,11 @@ beyond the minimum needed to end a sentence.
 @cindex regexp searching
 @cindex searching for regexp
 
-  In GNU Emacs, you can search for the next match for a regexp either
-incrementally or not.  For incremental search commands, see @ref{Regexp
-Search, , Regular Expression Search, emacs, The GNU Emacs Manual}.  Here
-we describe only the search functions useful in programs.  The principal
-one is @code{re-search-forward}.
+  In GNU Emacs, you can search for the next match for a regular
+expression either incrementally or not.  For incremental search
+commands, see @ref{Regexp Search, , Regular Expression Search, emacs,
+The GNU Emacs Manual}.  Here we describe only the search functions
+useful in programs.  The principal one is @code{re-search-forward}.
 
   These search functions convert the regular expression to multibyte if
 the buffer is multibyte; they convert the regular expression to unibyte
@@ -704,8 +704,8 @@ matching a regular expression at a given spot always works from
 beginning to end, and starts at a specified beginning position.
 
 A true mirror-image of @code{re-search-forward} would require a special
-feature for matching regexps from end to beginning.  It's not worth the
-trouble of implementing that.
+feature for matching regular expressions from end to beginning.  It's
+not worth the trouble of implementing that.
 @end deffn
 
 @defun string-match regexp string &optional start
@@ -1001,13 +1001,76 @@ can't avoid another intervening search, you must save and restore the
 match data around it, to prevent it from being overwritten.
 
 @menu
+* Replacing Match::       Replacing a substring that was matched.
 * Simple Match Data::     Accessing single items of match data,
                             such as where a particular subexpression started.
-* Replacing Match::       Replacing a substring that was matched.
 * Entire Match Data::     Accessing the entire match data at once, as a list.
 * Saving Match Data::     Saving and restoring the match data.
 @end menu
 
+@node Replacing Match
+@subsection Replacing the Text That Matched
+
+  This function replaces the text matched by the last search with
+@var{replacement}.
+
+@cindex case in replacements
+@defun replace-match replacement &optional fixedcase literal string subexp
+This function replaces the text in the buffer (or in @var{string}) that
+was matched by the last search.  It replaces that text with
+@var{replacement}.
+
+If you did the last search in a buffer, you should specify @code{nil}
+for @var{string}.  Then @code{replace-match} does the replacement by
+editing the buffer; it leaves point at the end of the replacement text,
+and returns @code{t}.
+
+If you did the search in a string, pass the same string as @var{string}.
+Then @code{replace-match} does the replacement by constructing and
+returning a new string.
+
+If @var{fixedcase} is non-@code{nil}, then the case of the replacement
+text is not changed; otherwise, the replacement text is converted to a
+different case depending upon the capitalization of the text to be
+replaced.  If the original text is all upper case, the replacement text
+is converted to upper case.  If the first word of the original text is
+capitalized, then the first word of the replacement text is capitalized.
+If the original text contains just one word, and that word is a capital
+letter, @code{replace-match} considers this a capitalized first word
+rather than all upper case.
+
+If @code{case-replace} is @code{nil}, then case conversion is not done,
+regardless of the value of @var{fixed-case}.  @xref{Searching and Case}.
+
+If @var{literal} is non-@code{nil}, then @var{replacement} is inserted
+exactly as it is, the only alterations being case changes as needed.
+If it is @code{nil} (the default), then the character @samp{\} is treated
+specially.  If a @samp{\} appears in @var{replacement}, then it must be
+part of one of the following sequences:
+
+@table @asis
+@item @samp{\&}
+@cindex @samp{&} in replacement
+@samp{\&} stands for the entire text being replaced.
+
+@item @samp{\@var{n}}
+@cindex @samp{\@var{n}} in replacement
+@samp{\@var{n}}, where @var{n} is a digit, stands for the text that
+matched the @var{n}th subexpression in the original regexp.
+Subexpressions are those expressions grouped inside @samp{\(@dots{}\)}.
+
+@item @samp{\\}
+@cindex @samp{\} in replacement
+@samp{\\} stands for a single @samp{\} in the replacement text.
+@end table
+
+If @var{subexp} is non-@code{nil}, that says to replace just
+subexpression number @var{subexp} of the regexp that was matched, not
+the entire match.  For example, after matching @samp{foo \(ba*r\)},
+calling @code{replace-match} with 1 as @var{subexp} means to replace
+just the text that matched @samp{\(ba*r\)}.
+@end defun
+
 @node Simple Match Data
 @subsection Simple Match Data Access
 
@@ -1038,7 +1101,7 @@ range, or if that subexpression didn't match anything, the value is
 
 If the last such operation was done against a string with
 @code{string-match}, then you should pass the same string as the
-argument @var{in-string}.  Otherwise, after a buffer search or match,
+argument @var{in-string}.  After a buffer search or match,
 you should omit @var{in-string} or pass @code{nil} for it; but you
 should make sure that the current buffer when you call
 @code{match-string} is the one in which you did the searching or
@@ -1056,7 +1119,7 @@ last regular expression searched for, or a subexpression of it.
 
 If @var{count} is zero, then the value is the position of the start of
 the entire match.  Otherwise, @var{count} specifies a subexpression in
-the regular expresion, and the value of the function is the starting
+the regular expression, and the value of the function is the starting
 position of the match for that subexpression.
 
 The value is @code{nil} for a subexpression inside a @samp{\|}
@@ -1136,69 +1199,6 @@ I read "The cat @point{}in the hat comes back" twice.
 (In this case, the index returned is a buffer position; the first
 character of the buffer counts as 1.)
 
-@node Replacing Match
-@subsection Replacing the Text That Matched
-
-  This function replaces the text matched by the last search with
-@var{replacement}.
-
-@cindex case in replacements
-@defun replace-match replacement &optional fixedcase literal string subexp
-This function replaces the text in the buffer (or in @var{string}) that
-was matched by the last search.  It replaces that text with
-@var{replacement}.
-
-If you did the last search in a buffer, you should specify @code{nil}
-for @var{string}.  Then @code{replace-match} does the replacement by
-editing the buffer; it leaves point at the end of the replacement text,
-and returns @code{t}.
-
-If you did the search in a string, pass the same string as @var{string}.
-Then @code{replace-match} does the replacement by constructing and
-returning a new string.
-
-If @var{fixedcase} is non-@code{nil}, then the case of the replacement
-text is not changed; otherwise, the replacement text is converted to a
-different case depending upon the capitalization of the text to be
-replaced.  If the original text is all upper case, the replacement text
-is converted to upper case.  If the first word of the original text is
-capitalized, then the first word of the replacement text is capitalized.
-If the original text contains just one word, and that word is a capital
-letter, @code{replace-match} considers this a capitalized first word
-rather than all upper case.
-
-If @code{case-replace} is @code{nil}, then case conversion is not done,
-regardless of the value of @var{fixed-case}.  @xref{Searching and Case}.
-
-If @var{literal} is non-@code{nil}, then @var{replacement} is inserted
-exactly as it is, the only alterations being case changes as needed.
-If it is @code{nil} (the default), then the character @samp{\} is treated
-specially.  If a @samp{\} appears in @var{replacement}, then it must be
-part of one of the following sequences:
-
-@table @asis
-@item @samp{\&}
-@cindex @samp{&} in replacement
-@samp{\&} stands for the entire text being replaced.
-
-@item @samp{\@var{n}}
-@cindex @samp{\@var{n}} in replacement
-@samp{\@var{n}}, where @var{n} is a digit, stands for the text that
-matched the @var{n}th subexpression in the original regexp.
-Subexpressions are those expressions grouped inside @samp{\(@dots{}\)}.
-
-@item @samp{\\}
-@cindex @samp{\} in replacement
-@samp{\\} stands for a single @samp{\} in the replacement text.
-@end table
-
-If @var{subexp} is non-@code{nil}, that says to replace just
-subexpression number @var{subexp} of the regexp that was matched, not
-the entire match.  For example, after matching @samp{foo \(ba*r\)},
-calling @code{replace-match} with 1 as @var{subexp} means to replace
-just the text that matched @samp{\(ba*r\)}.
-@end defun
-
 @node Entire Match Data
 @subsection Accessing the Entire Match Data
 
@@ -1230,9 +1230,7 @@ corresponds to @code{(match-end @var{n})}.
 
 All the elements are markers or @code{nil} if matching was done on a
 buffer, and all are integers or @code{nil} if matching was done on a
-string with @code{string-match}.  (In Emacs 18 and earlier versions,
-markers were used even for matching on a string, except in the case
-of the integer 0.)
+string with @code{string-match}.
 
 As always, there must be no possibility of intervening searches between
 the call to a search function and the call to @code{match-data} that is
@@ -1258,7 +1256,7 @@ If @var{match-list} refers to a buffer that doesn't exist, you don't get
 an error; that sets the match data in a meaningless but harmless way.
 
 @findex store-match-data
-@code{store-match-data} is an alias for @code{set-match-data}.
+@code{store-match-data} is a semi-obsolete alias for @code{set-match-data}.
 @end defun
 
 @node Saving Match Data
@@ -1287,9 +1285,9 @@ This special form executes @var{body}, saving and restoring the match
 data around it.
 @end defmac
 
-  You can use @code{set-match-data} together with @code{match-data} to
-imitate the effect of the special form @code{save-match-data}.  This is
-useful for writing code that can run in Emacs 18.  Here is how:
+  You could use @code{set-match-data} together with @code{match-data} to
+imitate the effect of the special form @code{save-match-data}.  Here is
+how:
 
 @example
 @group
@@ -1384,9 +1382,10 @@ same as @code{(default-value 'case-fold-search)}.
 used for certain purposes in editing:
 
 @defvar page-delimiter
-This is the regexp describing line-beginnings that separate pages.  The
-default value is @code{"^\014"} (i.e., @code{"^^L"} or @code{"^\C-l"});
-this matches a line that starts with a formfeed character.
+This is the regular expression describing line-beginnings that separate
+pages.  The default value is @code{"^\014"} (i.e., @code{"^^L"} or
+@code{"^\C-l"}); this matches a line that starts with a formfeed
+character.
 @end defvar
 
   The following two regular expressions should @emph{not} assume the
diff --git a/lispref/sequences.texi b/lispref/sequences.texi
index 3227eb35ae9..8f19d6f9a1b 100644
--- a/lispref/sequences.texi
+++ b/lispref/sequences.texi
@@ -7,16 +7,15 @@
 @chapter Sequences, Arrays, and Vectors
 @cindex sequence
 
-  Recall that the @dfn{sequence} type is the union of three other Lisp
-types: lists, vectors, and strings.  In other words, any list is a
-sequence, any vector is a sequence, and any string is a sequence.  The
-common property that all sequences have is that each is an ordered
-collection of elements.
+  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.
 
   An @dfn{array} is a single primitive object that has a slot for each
-elements.  All the elements are accessible in constant time, but the
-length of an existing array cannot be changed.  Strings and vectors are
-the two types of arrays.
+of its elements.  All the elements are accessible in constant time, but
+the length of an existing array cannot be changed.  Strings, vectors,
+char-tables and bool-vectors are the four types of arrays.
 
   A list is a sequence of elements, but it is not a single primitive
 object; it is made of cons cells, one cell per element.  Finding the
@@ -28,18 +27,22 @@ But it is possible to add elements to the list, or remove elements.
 
 @example
 @group
-          ___________________________________
-         |                                   |
-         |          Sequence                 |
-         |  ______   ______________________  |
-         | |      | |                      | |
-         | | List | |         Array        | |
-         | |      | |  ________   _______  | |   
-         | |______| | |        | |       | | |
-         |          | | Vector | | String| | |
-         |          | |________| |_______| | |
-         |          |______________________| |
-         |___________________________________|
+          _____________________________________________
+         |                                             |
+         |          Sequence                           |
+         |  ______   ________________________________  |
+         | |      | |                                | |
+         | | List | |             Array              | |
+         | |      | |    ________       ________     | |
+         | |______| |   |        |     |        |    | |
+         |          |   | Vector |     | String |    | |
+         |          |   |________|     |________|    | |
+         |          |  ____________   _____________  | |
+         |          | |            | |             | | |
+         |          | | Char-table | | Bool-vector | | |
+         |          | |____________| |_____________| | |
+         |          |________________________________| |
+         |_____________________________________________|
 @end group
 @end example
 
@@ -59,16 +62,88 @@ elements of strings are all characters.
 @node Sequence Functions
 @section Sequences
 
-  In Emacs Lisp, a @dfn{sequence} is either a list, a vector or a
-string.  The common property that all sequences have is that each is an
-ordered collection of elements.  This section describes functions that
-accept any kind of sequence.
+  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.
 
 @defun sequencep object
 Returns @code{t} if @var{object} is a list, vector, or
 string, @code{nil} otherwise.
 @end defun
 
+@defun length sequence
+@cindex string length
+@cindex list length
+@cindex vector length
+@cindex sequence length
+This function returns the number of elements in @var{sequence}.  If
+@var{sequence} is a cons cell that is not a list (because the final
+@sc{cdr} is not @code{nil}), a @code{wrong-type-argument} error is
+signaled.
+
+@xref{List Elements}, for the related function @code{safe-list}.
+
+@example
+@group
+(length '(1 2 3))
+    @result{} 3
+@end group
+@group
+(length ())
+    @result{} 0
+@end group
+@group
+(length "foobar")
+    @result{} 6
+@end group
+@group
+(length [1 2 3])
+    @result{} 3
+@end group
+@group
+(length (make-bool-vector 5 nil))
+    @result{} 5
+@end group
+@end example
+@end defun
+
+@defun elt sequence index
+@cindex elements of sequences
+This function returns the element of @var{sequence} indexed by
+@var{index}.  Legitimate values of @var{index} are integers ranging from
+0 up to one less than the length of @var{sequence}.  If @var{sequence}
+is a list, then out-of-range values of @var{index} return @code{nil};
+otherwise, they trigger an @code{args-out-of-range} error.
+
+@example
+@group
+(elt [1 2 3 4] 2)
+     @result{} 3
+@end group
+@group
+(elt '(1 2 3 4) 2)
+     @result{} 3
+@end group
+@group
+;; @r{We use @code{string} to show clearly which character @code{elt} returns.}
+(string (elt "1234" 2))
+     @result{} "3"
+@end group
+@group
+(elt [1 2 3 4] 4)
+     @error{}Args out of range: [1 2 3 4], 4
+@end group
+@group
+(elt [1 2 3 4] -1)
+     @error{}Args out of range: [1 2 3 4], -1
+@end group
+@end example
+
+This function generalizes @code{aref} (@pxref{Array Functions}) and
+@code{nth} (@pxref{List Elements}).
+@end defun
+
 @defun copy-sequence sequence
 @cindex copying sequences
 Returns a copy of @var{sequence}.  The copy is the same type of object
@@ -133,72 +208,6 @@ y @result{} [foo (69 2)]
 @end example
 @end defun
 
-@defun length sequence
-@cindex string length
-@cindex list length
-@cindex vector length
-@cindex sequence length
-Returns the number of elements in @var{sequence}.  If @var{sequence} is
-a cons cell that is not a list (because the final @sc{cdr} is not
-@code{nil}), a @code{wrong-type-argument} error is signaled.
-
-@xref{List Elements}, for the related function @code{safe-list}.
-
-@example
-@group
-(length '(1 2 3))
-    @result{} 3
-@end group
-@group
-(length ())
-    @result{} 0
-@end group
-@group
-(length "foobar")
-    @result{} 6
-@end group
-@group
-(length [1 2 3])
-    @result{} 3
-@end group
-@end example
-@end defun
-
-@defun elt sequence index
-@cindex elements of sequences
-This function returns the element of @var{sequence} indexed by
-@var{index}.  Legitimate values of @var{index} are integers ranging from
-0 up to one less than the length of @var{sequence}.  If @var{sequence}
-is a list, then out-of-range values of @var{index} return @code{nil};
-otherwise, they trigger an @code{args-out-of-range} error.
-
-@example
-@group
-(elt [1 2 3 4] 2)
-     @result{} 3
-@end group
-@group
-(elt '(1 2 3 4) 2)
-     @result{} 3
-@end group
-@group
-(char-to-string (elt "1234" 2))
-     @result{} "3"
-@end group
-@group
-(elt [1 2 3 4] 4)
-     @error{}Args out of range: [1 2 3 4], 4
-@end group
-@group
-(elt [1 2 3 4] -1)
-     @error{}Args out of range: [1 2 3 4], -1
-@end group
-@end example
-
-This function generalizes @code{aref} (@pxref{Array Functions}) and
-@code{nth} (@pxref{List Elements}).
-@end defun
-
 @node Arrays
 @section Arrays
 @cindex array
@@ -209,20 +218,14 @@ be accessed in constant time.  In contrast, an element of a list
 requires access time that is proportional to the position of the element
 in the list.
 
-  When you create an array, you must specify how many elements it has.
-The amount of space allocated depends on the number of elements.
-Therefore, it is impossible to change the size of an array once it is
-created; you cannot add or remove elements.  However, you can replace an
-element with a different value.
-
-  Emacs defines two types of array, both of which are one-dimensional:
-@dfn{strings} and @dfn{vectors}.  A vector is a general array; its
-elements can be any Lisp objects.  A string is a specialized array; its
-elements must be characters (i.e., integers between 0 and 255).  Each
-type of array has its own read syntax.  @xref{String Type}, and
-@ref{Vector Type}.
+  Emacs defines four types of array, both of which are one-dimensional:
+@dfn{strings}, @dfn{vectors}, @dfn{bool-vectors} and @dfn{char-tables}.
+A vector is a general array; its elements can be any Lisp objects.  A
+string is a specialized array; its elements must be characters (i.e.,
+integers between 0 and 255).  Each type of array has its own read
+syntax.  @xref{String Type}, and @ref{Vector Type}.
 
-  Both kinds of array share these characteristics:
+  All four kinds of array share these characteristics:
 
 @itemize @bullet
 @item
@@ -231,13 +234,25 @@ index 1, and so on.  This is called @dfn{zero-origin} indexing.  For
 example, an array of four elements has indices 0, 1, 2, @w{and 3}.
 
 @item
+The length of the array is fixed once you create it; you cannot
+change the length of an existing array.
+
+@item
+The array is a constant, for evaluation---in other words, it evaluates
+to itself.
+
+@item
 The elements of an array may be referenced or changed with the functions
 @code{aref} and @code{aset}, respectively (@pxref{Array Functions}).
 @end itemize
 
-  In principle, if you wish to have an array of text characters, you
-could use either a string or a vector.  In practice, we always choose
-strings for such applications, for four reasons:
+    When you create an array, other than a char-table, you must specify
+its length.  You cannot specify the length of a char-table, because that
+is determined by the range of character codes.
+
+  In principle, if you want an array of text characters, you could use
+either a string or a vector.  In practice, we always choose strings for
+such applications, for four reasons:
 
 @itemize @bullet
 @item
@@ -274,9 +289,11 @@ vector, a string, a bool-vector or a char-table).
 @example
 @group
 (arrayp [a])
-@result{} t
+     @result{} t
 (arrayp "asdf")
-@result{} t
+     @result{} t
+(arrayp (syntax-table))    ;; @r{A char-table.}
+     @result{} t
 @end group
 @end example
 @end defun
@@ -292,10 +309,7 @@ first element is at index zero.
      @result{} [2 3 5 7 11 13]
 (aref primes 4)
      @result{} 11
-(elt primes 4)
-     @result{} 11
 @end group
-
 @group
 (aref "abcdefg" 1)
      @result{} 98           ; @r{@samp{b} is @sc{ASCII} code 98.}
@@ -371,11 +385,11 @@ are often useful for objects known to be arrays.  @xref{Sequence Functions}.
 
   Arrays in Lisp, like arrays in most languages, are blocks of memory
 whose elements can be accessed in constant time.  A @dfn{vector} is a
-general-purpose array; its elements can be any Lisp objects.  (By
-contrast, a string can hold only characters as elements.)  Vectors in
-Emacs are used for obarrays (vectors of symbols), and as part of keymaps
-(vectors of commands).  They are also used internally as part of the
-representation of a byte-compiled function; if you print such a
+general-purpose array of specified length; its elements can be any Lisp
+objects.  (By contrast, a string can hold only characters as elements.)
+Vectors in Emacs are used for obarrays (vectors of symbols), and as part
+of keymaps (vectors of commands).  They are also used internally as part
+of the representation of a byte-compiled function; if you print such a
 function, you will see a vector in it.
 
   In Emacs Lisp, the indices of the elements of a vector start from zero
@@ -405,7 +419,7 @@ not evaluate or even examine the elements of the vector.
 @end example
 
 @node Vector Functions
-@section Functions That Operate on Vectors
+@section Functions for Vectors
 
   Here are some functions that relate to vectors:
 
@@ -473,6 +487,10 @@ existing vector.
 @end group
 @end example
 
+The @code{vconcat} function also allows byte-code function objects as
+arguments.  This is a special feature to make it easy to access the entire
+contents of a byte-code function object.  @xref{Byte-Code Objects}.
+
 The @code{vconcat} function also allows integers as arguments.  It
 converts them to strings of digits, making up the decimal print
 representation of the integer, and then uses the strings instead of the
@@ -505,8 +523,9 @@ list with the same elements (@pxref{Building Lists}):
 
   A char-table is much like a vector, except that it is indexed by
 character codes.  Any valid character code, without modifiers, can be
-used as an index in a char-table.  You can access a char-table with
-@code{aref} and @code{aset}, just like a vector.
+used as an index in a char-table.  You can access a char-table's
+elements with @code{aref} and @code{aset}, as with any array.
+Char-tables are constants when evaluated.
 
 @cindex extra slots of char-table
 @cindex subtype of char-table
@@ -534,11 +553,14 @@ Return a newly created char-table, with subtype @var{subtype}.  Each
 element is initialized to @var{init}, which defaults to @code{nil}.  You
 cannot alter the subtype of a char-table after the char-table is
 created.
+
+There is no argument to specify the length of the char-table, because
+all char-tables have room for any valid character code as an index.
 @end defun
 
 @tindex char-table-p
 @defun char-table-p object
-This function returns @code{t} if @code{object} is a char-table,
+This function returns @code{t} if @var{object} is a char-table,
 otherwise @code{nil}.
 @end defun
 
@@ -628,9 +650,9 @@ This function calls @var{function} for each element of @var{char-table}.
 @var{function} is called with two arguments, a key and a value.  The key
 is a possible @var{range} argument for @code{char-table-range}, and the
 value is @code{(char-table-range @var{char-table} @var{key})}.  Invalid
-character codes are never used as the key.
+character codes are never used as @var{key}.
 
-Overall, the keys-value pairs passed to @var{function} describe all the
+Overall, the key-value pairs passed to @var{function} describe all the
 values stored in @var{char-table}.
 @end defun
 
@@ -640,8 +662,10 @@ values stored in @var{char-table}.
 
   A bool-vector is much like a vector, except that it stores only the
 values @code{t} and @code{nil}.  If you try to store any non-@code{nil}
-value into an element of the bool-vector, that actually stores @code{t}
-there.
+value into an element of the bool-vector, the effect is to store
+@code{t} there.  As with all arrays, bool-vector indices start from 0,
+and the length cannot be changed once the bool-vector is created.
+Bool-vectors are constants when evaluated.
 
   There are two special functions for working with bool-vectors; aside
 from that, you manipulate them with same functions used for other kinds
diff --git a/lispref/streams.texi b/lispref/streams.texi
index 4e19308fbf6..945e550fc0a 100644
--- a/lispref/streams.texi
+++ b/lispref/streams.texi
@@ -103,17 +103,21 @@ character in the string and using as many characters as required.
 
 @item @var{function}
 @cindex function input stream
-The input characters are generated by @var{function}, one character per
-call.  Normally @var{function} is called with no arguments, and should
-return a character.
-
-@cindex unreading
-Occasionally @var{function} is called with one argument (always a
-character).  When that happens, @var{function} should save the argument
-and arrange to return it on the next call.  This is called
-@dfn{unreading} the character; it happens when the Lisp reader reads one
-character too many and wants to ``put it back where it came from''.
-In this case, it makes no difference what value @var{function} returns.
+The input characters are generated by @var{function}, which must support
+two kinds of calls:
+
+@itemize @bullet
+@item
+When it is called with no arguments, it should return the next character.
+
+@item
+When it is called with one argument (always a character), @var{function}
+should save the argument and arrange to return it on the next call.
+This is called @dfn{unreading} the character; it happens when the Lisp
+reader reads one character too many and wants to ``put it back where it
+came from''.  In this case, it makes no difference what value
+@var{function} returns.
+@end itemize
 
 @item @code{t}
 @cindex @code{t} input stream
@@ -163,13 +167,6 @@ This is the@point{} contents of foo.
 Note that the first read skips a space.  Reading skips any amount of
 whitespace preceding the significant text.
 
-  In Emacs 18, reading a symbol discarded the delimiter terminating the
-symbol.  Thus, point would end up at the beginning of @samp{contents}
-rather than after @samp{the}.  The current behavior is superior because
-it correctly handles input such as @samp{bar(foo)}, where the
-open-parenthesis that ends one object is needed as the beginning of
-another object.
-
   Here is an example of reading from a stream that is a marker,
 initially positioned at the beginning of the buffer shown.  The value
 read is the symbol @code{This}.
@@ -296,9 +293,9 @@ and whose @sc{cdr} is an integer giving the position of the next
 remaining character in the string (i.e., the first one not read).
 
 If @var{start} is supplied, then reading begins at index @var{start} in
-the string (where the first character is at index 0).  If @var{end} is
-also supplied, then reading stops just before that index, as if the rest
-of the string were not there.
+the string (where the first character is at index 0).  If you specify
+@var{end}, then reading is forced to stop just before that index, as if
+the rest of the string were not there.
 
 For example:
 
@@ -381,8 +378,8 @@ definition (if any).
 @end table
 
   Many of the valid output streams are also valid as input streams.  The
-difference between input and output streams is therefore mostly one of
-how you use a Lisp object, not a distinction of types of object.
+difference between input and output streams is therefore more a matter
+of how you use a Lisp object, than of different types of object.
 
   Here is an example of a buffer used as an output stream.  Point is
 initially located as shown immediately before the @samp{h} in
@@ -532,18 +529,18 @@ being taken as delimiters when reading.  @xref{Printed Representation},
 for full details.  You specify quoting or no quoting by the choice of
 printing function.
 
-  If the text is to be read back into Lisp, then it is best to print
-with quoting characters to avoid ambiguity.  Likewise, if the purpose is
-to describe a Lisp object clearly for a Lisp programmer.  However, if
-the purpose of the output is to look nice for humans, then it is better
-to print without quoting.
+  If the text is to be read back into Lisp, then you should print with
+quoting characters to avoid ambiguity.  Likewise, if the purpose is to
+describe a Lisp object clearly for a Lisp programmer.  However, if the
+purpose of the output is to look nice for humans, then it is usually
+better to print without quoting.
 
-  Printing a self-referent Lisp object requires an infinite amount of
-text.  In certain cases, trying to produce this text leads to a stack
-overflow.  Emacs detects such recursion and prints @samp{#@var{level}}
-instead of recursively printing an object already being printed.  For
-example, here @samp{#0} indicates a recursive reference to the object at
-level 0 of the current print operation:
+  Printing a self-referent Lisp object in the normal way would require
+an infinite amount of text, and could even result in stack overflow.
+Emacs detects such recursion and prints @samp{#@var{level}} instead of
+recursively printing an object already being printed.  For example, here
+@samp{#0} indicates a recursive reference to the object at level 0 of
+the current print operation:
 
 @example
 (setq foo (list nil))
@@ -696,9 +693,9 @@ If this variable is non-@code{nil}, then newline characters in strings
 are printed as @samp{\n} and formfeeds are printed as @samp{\f}.
 Normally these characters are printed as actual newlines and formfeeds.
 
-This variable affects the print functions @code{prin1} and @code{print},
-as well as everything that uses them.  It does not affect @code{princ}.
-Here is an example using @code{prin1}:
+This variable affects the print functions @code{prin1} and @code{print}
+that print with quoting.  It does not affect @code{princ}.  Here is an
+example using @code{prin1}:
 
 @example
 @group
diff --git a/lispref/strings.texi b/lispref/strings.texi
index b6ffa8ffee4..71300010f37 100644
--- a/lispref/strings.texi
+++ b/lispref/strings.texi
@@ -29,8 +29,8 @@ keyboard character events.
 * Text Comparison::           Comparing characters or strings.
 * String Conversion::         Converting characters or strings and vice versa.
 * Formatting Strings::        @code{format}: Emacs's analog of @code{printf}.
-* Character Case::            Case conversion functions.
-* Case Table::                Customizing case conversion.
+* Case Conversion::           Case conversion functions.
+* Case Tables::               Customizing case conversion.
 @end menu
 
 @node String Basics
@@ -38,19 +38,19 @@ keyboard character events.
 
   Strings in Emacs Lisp are arrays that contain an ordered sequence of
 characters.  Characters are represented in Emacs Lisp as integers;
-whether an integer was intended as a character or not is determined only
-by how it is used.  Thus, strings really contain integers.
+whether an integer is a character or not is determined only by how it is
+used.  Thus, strings really contain integers.
 
   The length of a string (like any array) is fixed, and cannot be
 altered once the string exists.  Strings in Lisp are @emph{not}
 terminated by a distinguished character code.  (By contrast, strings in
 C are terminated by a character with @sc{ASCII} code 0.)
 
-  Since strings are considered arrays, you can operate on them with the
-general array functions.  (@xref{Sequences Arrays Vectors}.)  For
-example, you can access or change individual characters in a string
-using the functions @code{aref} and @code{aset} (@pxref{Array
-Functions}).
+  Since strings are arrays, and therefore sequences as well, you can
+operate on them with the general array and sequence functions.
+(@xref{Sequences Arrays Vectors}.)  For example, you can access or
+change individual characters in a string using the functions @code{aref}
+and @code{aset} (@pxref{Array Functions}).
 
   There are two text representations for non-@sc{ASCII} characters in
 Emacs strings (and in buffers): unibyte and multibyte (@pxref{Text
@@ -62,8 +62,8 @@ representations.
 
   Sometimes key sequences are represented as strings.  When a string is
 a key sequence, string elements in the range 128 to 255 represent meta
-characters (which are extremely large integers) rather than keyboard
-events in the range 128 to 255.
+characters (which are extremely large integers) rather than character
+codes in the range 128 to 255.
 
   Strings cannot hold characters that have the hyper, super or alt
 modifiers; they can hold @sc{ASCII} control characters, but no other
@@ -201,14 +201,19 @@ Functions}).
 If the characters copied from @var{string} have text properties, the
 properties are copied into the new string also.  @xref{Text Properties}.
 
+@code{substring} also allows vectors for the first argument.
+For example:
+
+@example
+(substring [a b (c) "d"] 1 3)
+     @result{} [b (c)]
+@end example
+
 A @code{wrong-type-argument} error is signaled if either @var{start} or
 @var{end} is not an integer or @code{nil}.  An @code{args-out-of-range}
 error is signaled if @var{start} indicates a character following
 @var{end}, or if either integer is out of range for @var{string}.
 
-@code{substring} actually allows vectors as well as strings for
-the first argument.
-
 Contrast this function with @code{buffer-substring} (@pxref{Buffer
 Contents}), which returns a string containing a portion of the text in
 the current buffer.  The beginning of a string is at index 0, but the
@@ -313,7 +318,7 @@ Empty matches do count, when not adjacent to another match:
 @var{idx} @var{char})} stores @var{char} into @var{string} at index
 @var{idx}.  Each character occupies one or more bytes, and if @var{char}
 needs a different number of bytes from the character already present at
-that index, @code{aset} gets an error.
+that index, @code{aset} signals an error.
 
   A more powerful function is @code{store-substring}:
 
@@ -325,8 +330,8 @@ may be either a character or a (smaller) string.
 
 Since it is impossible to change the length of an existing string, it is
 an error if @var{obj} doesn't fit within @var{string}'s actual length,
-or if it requires a different number of bytes from the characters
-currently present at that point in @var{string}.
+of if any new character requires a different number of bytes from the
+character currently present at that point in @var{string}.
 @end defun
 
 @need 2000
@@ -365,7 +370,7 @@ 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=}.
 
-If the arguments contain non-@sc{ASCII} characters, and one is unibyte
+If the strings contain non-@sc{ASCII} characters, and one is unibyte
 while the other is multibyte, then they cannot be equal.  @xref{Text
 Representations}.
 @end defun
@@ -385,11 +390,12 @@ function returns @code{t}.  If the lesser character is the one from
 @var{string2}, then @var{string1} is greater, and this function returns
 @code{nil}.  If the two strings match entirely, the value is @code{nil}.
 
-Pairs of characters are compared by their @sc{ASCII} codes.  Keep in
-mind that lower case letters have higher numeric values in the
-@sc{ASCII} character set than their upper case counterparts; numbers and
+Pairs of characters are compared according to their character codes.
+Keep in mind that lower case letters have higher numeric values in the
+@sc{ASCII} character set than their upper case counterparts; digits and
 many punctuation characters have a lower numeric value than upper case
-letters.  A unibyte non-@sc{ASCII} character is always less than any
+letters.  An @sc{ASCII} character is less than any non-@sc{ASCII}
+character; a unibyte non-@sc{ASCII} character is always less than any
 multibyte non-@sc{ASCII} character (@pxref{Text Representations}).
 
 @example
@@ -453,23 +459,9 @@ functions are used primarily for making help messages.
 
 @defun char-to-string character
 @cindex character to string
-  This function returns a new string with a length of one character.
-The value of @var{character}, modulo 256, is used to initialize the
-element of the string.
-
-This function is similar to @code{make-string} with an integer argument
-of 1.  (@xref{Creating Strings}.)  This conversion can also be done with
-@code{format} using the @samp{%c} format specification.
-(@xref{Formatting Strings}.)
-
-@example
-(char-to-string ?x)
-     @result{} "x"
-(char-to-string (+ 256 ?x))
-     @result{} "x"
-(make-string 1 ?x)
-     @result{} "x"
-@end example
+This function returns a new string containing one character,
+@var{character}.  This function is semi-obsolete because the function
+@code{string} is more general.  @xref{Creating Strings}.
 @end defun
 
 @defun string-to-char string
@@ -579,7 +571,7 @@ formatting feature described here; they differ from @code{format} only
 in how they use the result of formatting.
 
 @defun format string &rest objects
-  This function returns a new string that is made by copying
+This function returns a new string that is made by copying
 @var{string} and then replacing any format specification 
 in the copy with encodings of the corresponding @var{objects}.  The
 arguments @var{objects} are the computed values to be formatted.
@@ -619,7 +611,7 @@ meaningless.
 @item %s
 Replace the specification with the printed representation of the object,
 made without quoting (that is, using @code{princ}, not
-@code{print}---@pxref{Output Functions}).  Thus, strings are represented
+@code{prin1}---@pxref{Output Functions}).  Thus, strings are represented
 by their contents alone, with no @samp{"} characters, and symbols appear
 without @samp{\} characters.
 
@@ -740,12 +732,13 @@ not truncated.  In the third case, the padding is on the right.
 @end group
 @end smallexample
 
-@node Character Case
+@node Case Conversion
 @comment node-name, next, previous, up 
-@section Character Case
+@section Case Conversion in Lisp
 @cindex upper case 
 @cindex lower case 
 @cindex character case 
+@cindex case conversion in Lisp
 
   The character case functions change the case of single characters or
 of the contents of strings.  The functions convert only alphabetic
@@ -827,18 +820,39 @@ has the same result as @code{upcase}.
 @end example
 @end defun
 
-@node Case Table
+@defun upcase-initials string
+This function capitalizes the initials of the words in @var{string}.
+without altering any letters other than the initials.  It returns a new
+string whose contents are a copy of @var{string-or-char}, in which each
+word has been converted to upper case.
+
+The definition of a word is any sequence of consecutive characters that
+are assigned to the word constituent syntax class in the current syntax
+table (@xref{Syntax Class Table}).
+
+@example
+@group
+(upcase-initials "The CAT in the hAt")
+     @result{} "The CAT In The HAt"
+@end group
+@end example
+@end defun
+
+@node Case Tables
 @section The Case Table
 
   You can customize case conversion by installing a special @dfn{case
 table}.  A case table specifies the mapping between upper case and lower
-case letters.  It affects both the string and character case conversion
-functions (see the previous section) and those that apply to text in the
-buffer (@pxref{Case Changes}).
+case letters.  It affects both the case conversion functions for Lisp
+objects (see the previous section) and those that apply to text in the
+buffer (@pxref{Case Changes}).  Each buffer has a case table; there is
+also a standard case table which is used to initialize the case table
+of new buffers.
 
-  A case table is a char-table whose subtype is @code{case-table}.  This
-char-table maps each character into the corresponding lower case
-character  It has three extra slots, which are related tables:
+  A case table is a char-table (@pxref{Char-Tables}) whose subtype is
+@code{case-table}.  This char-table maps each character into the
+corresponding lower case character.  It has three extra slots, which
+hold related tables:
 
 @table @var
 @item upcase
@@ -874,17 +888,13 @@ equivalent).  (For ordinary @sc{ASCII}, this would map @samp{a} into
 equivalent characters.)
 
   When you construct a case table, you can provide @code{nil} for
-@var{canonicalize}; then Emacs fills in this string from the lower case
+@var{canonicalize}; then Emacs fills in this slot from the lower case
 and upper case mappings.  You can also provide @code{nil} for
-@var{equivalences}; then Emacs fills in this string from
+@var{equivalences}; then Emacs fills in this slot from
 @var{canonicalize}.  In a case table that is actually in use, those
 components are non-@code{nil}.  Do not try to specify @var{equivalences}
 without also specifying @var{canonicalize}.
 
-  Each buffer has a case table.  Emacs also has a @dfn{standard case
-table} which is copied into each buffer when you create the buffer.
-Changing the standard case table doesn't affect any existing buffers.
-
   Here are the functions for working with case tables:
 
 @defun case-table-p object
@@ -894,7 +904,7 @@ table.
 
 @defun set-standard-case-table table
 This function makes @var{table} the standard case table, so that it will
-apply to any buffers created subsequently.
+be used in any buffers created subsequently.
 @end defun
 
 @defun standard-case-table
@@ -912,7 +922,8 @@ This sets the current buffer's case table to @var{table}.
   The following three functions are convenient subroutines for packages
 that define non-@sc{ASCII} character sets.  They modify the specified
 case table @var{case-table}; they also modify the standard syntax table.
-@xref{Syntax Tables}.
+@xref{Syntax Tables}.  Normally you would use these functions to change
+the standard case table.
 
 @defun set-case-syntax-pair uc lc case-table
 This function specifies a pair of corresponding letters, one upper case
diff --git a/lispref/symbols.texi b/lispref/symbols.texi
index 6472d0a40d2..9f52fc0e5be 100644
--- a/lispref/symbols.texi
+++ b/lispref/symbols.texi
@@ -145,7 +145,8 @@ 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}.
+@ref{Defining Variables}.  For defining user option variables that can
+be customized, use @code{defcustom} (@pxref{Customization}).
 
   @code{defun} defines a symbol as a function, creating a lambda
 expression and storing it in the function cell of the symbol.  This
@@ -229,11 +230,6 @@ valid way to create an obarray.}  Prime numbers as lengths tend
 to result in good hashing; lengths one less than a power of two are also
 good.
 
-  It is possible for two different symbols to have the same name in
-different obarrays; these symbols are not @code{eq} or @code{equal}.
-However, this normally happens only as part of the abbrev mechanism
-(@pxref{Abbrevs}).
-
   @strong{Do not try to put symbols in an obarray yourself.}  This does
 not work---only @code{intern} can enter a symbol in an obarray properly.
 
@@ -440,10 +436,10 @@ an association list than to update a property.  All properties for a
 symbol are stored in the same property list, so there is a possibility
 of a conflict between different uses of a property name.  (For this
 reason, it is a good idea to choose property names that are probably
-unique, such as by including the name of the library in the property
-name.)  An association list may be used like a stack where associations
-are pushed on the front of the list and later discarded; this is not
-possible with a property list.
+unique, such as by beginning the property name with the program's usual
+name-prefix for variables and functions.)  An association list may be
+used like a stack where associations are pushed on the front of the list
+and later discarded; this is not possible with a property list.
 
 @node Symbol Plists
 @subsection Property List Functions for Symbols
@@ -532,3 +528,10 @@ in the place where you got @var{plist}.  For example,
 @end example
 @end defun
 
+  You could define @code{put} in terms of @code{plist-put} as follows:
+
+@example
+(defun put (symbol prop value)
+  (setplist symbol
+            (plist-put (symbol-plist symbol) prop value)))
+@end example
diff --git a/lispref/syntax.texi b/lispref/syntax.texi
index 77fe0c46cfe..3200c40ac83 100644
--- a/lispref/syntax.texi
+++ b/lispref/syntax.texi
@@ -44,12 +44,16 @@ list motion functions (@pxref{List Motion}) as well as the functions in
 this chapter.
 @end ifinfo
 
-  A syntax table is a char-table (@pxref{Char-Tables}).  Each element is
-a list that encodes the syntax of the character in question.
+  A syntax table is a char-table (@pxref{Char-Tables}).  The element at
+index @var{c} describes the character with code @var{c}.  The element's
+value should be a list that encodes the syntax of the character in
+question.
 
   Syntax tables are used only for moving across text, not for the Emacs
 Lisp reader.  Emacs Lisp uses built-in syntactic rules when reading Lisp
-expressions, and these rules cannot be changed.
+expressions, and these rules cannot be changed.  (Some Lisp systems
+provide ways to redefine the read syntax, but we decided to leave this
+feature out of Emacs Lisp for simplicity.)
 
   Each buffer has its own major mode, and each major mode has its own
 idea of the syntactic class of various characters.  For example, in Lisp
@@ -80,12 +84,11 @@ This function returns @code{t} if @var{object} is a syntax table.
   This section describes the syntax classes and flags that denote the
 syntax of a character, and how they are represented as a @dfn{syntax
 descriptor}, which is a Lisp string that you pass to
-@code{modify-syntax-entry} to specify the desired syntax.
+@code{modify-syntax-entry} to specify the syntax you want.
 
-  Emacs defines a number of @dfn{syntax classes}.  Each syntax table
-puts each character into one class.  There is no necessary relationship
-between the class of a character in one syntax table and its class in
-any other table.
+  The syntax table specifies a syntax class for each character.  There
+is no necessary relationship between the class of a character in one
+syntax table and its class in any other table.
 
   Each class is designated by a mnemonic character, which serves as the
 name of the class when you need to specify a class.  Usually the
@@ -124,7 +127,8 @@ their meanings, and examples of their use.
 separate symbols and words from each other.  Typically, whitespace
 characters have no other syntactic significance, and multiple whitespace
 characters are syntactically equivalent to a single one.  Space, tab,
-newline and formfeed are almost always classified as whitespace.
+newline and formfeed are classified as whitespace in almost all major
+modes.
 @end deffn
 
 @deffn {Syntax class} @w{word constituent}
@@ -384,9 +388,9 @@ prefix (@samp{'}).  @xref{Motion and Syntax}.
 altering syntax tables.
 
 @defun make-syntax-table
-This function creates a new syntax table.  Character codes 32 through
-127 are set up by copying the syntax from the standard syntax table.
-All other codes are set up to inherit from the standard syntax table.
+This function creates a new syntax table.  It inherits the syntax for
+letters and control characters from the standard syntax table.  For
+other characters, the syntax is copied from the standard syntax table.
 
 Most major mode syntax tables are created in this way.
 @end defun
@@ -465,20 +469,23 @@ character, @samp{)}.
 
 @example
 @group
-(char-to-string (char-syntax ?\ ))
+(string (char-syntax ?\ ))
      @result{} " "
 @end group
 
 @group
-(char-to-string (char-syntax ?/))
+(string (char-syntax ?/))
      @result{} "."
 @end group
 
 @group
-(char-to-string (char-syntax ?\())
+(string (char-syntax ?\())
      @result{} "("
 @end group
 @end example
+
+We use @code{string} to make it easier to see the character returned by
+@code{char-syntax}.
 @end defun
 
 @defun set-syntax-table table
@@ -500,7 +507,7 @@ language, you can use @code{syntax-table} text properties to override
 the syntax table for specific character occurrences in the buffer.
 @xref{Text Properties}.
 
-The valid values of @code{syntax-table} text property are
+The valid values of @code{syntax-table} text property are:
 
 @table @asis
 @item @var{syntax-table}
@@ -527,9 +534,8 @@ table.
 @node Motion and Syntax
 @section Motion and Syntax
 
-  This section describes functions for moving across characters in
-certain syntax classes.  None of these functions exists in Emacs
-version 18 or earlier.
+  This section describes functions for moving across characters that
+have certain syntax classes.
 
 @defun skip-syntax-forward syntaxes &optional limit
 This function moves point forward across characters having syntax classes
@@ -596,7 +602,7 @@ string, or the of a comment or a string, whichever comes first.
 
 @cindex parse state
 The fifth argument @var{state} is a nine-element list of the same form
-as the value of this function, described below.  (It is ok to omit the
+as the value of this function, described below.  (It is OK to omit the
 last element of the nine.)  The return value of one call may be used to
 initialize the state of the parse on another call to
 @code{parse-partial-sexp}.
@@ -758,42 +764,46 @@ a character to match was specified.
   This table gives the value of @var{syntax-code} which corresponds
 to each syntactic type.
 
-@table @asis
-@item @i{Integer}
-@i{Class}
-@item 0
-whitespace
-@item 1
-punctuation
-@item 2
-word
-@item 3
-symbol
-@item 4
-open parenthesis
-@item 5
-close parenthesis
-@item 6
-expression prefix
-@item 7
-string quote
-@item 8
-paired delimiter
-@item 9
-escape
-@item 10
-character quote
-@item 11
-comment-start
-@item 12
-comment-end
-@item 13
-inherit
-@item 14
-comment-fence
-@item 15
-string-fence
-@end table
+@multitable @columnfractions .05 .3 .3 .3
+@item@tab
+@i{Integer} @i{Class}
+@tab
+@i{Integer} @i{Class}
+@tab
+@i{Integer} @i{Class}
+@item@tab
+0 @ @  whitespace
+@tab
+5 @ @  close parenthesis
+@tab
+10 @ @  character quote
+@item@tab
+1 @ @  punctuation
+@tab
+6 @ @  expression prefix
+@tab
+11 @ @  comment-start
+@item@tab
+2 @ @  word
+@tab
+7 @ @  string quote
+@tab
+12 @ @  comment-end
+@item@tab
+3 @ @  symbol
+@tab
+8 @ @  paired delimiter
+@tab
+13 @ @  inherit
+@item@tab
+4 @ @  open parenthesis
+@tab
+9 @ @  escape
+@tab
+14 @ @  comment-fence
+@item@tab
+15 @  string-fence
+@end multitable
 
   For example, the usual syntax value for @samp{(} is @code{(4 . 41)}.
 (41 is the character code for @samp{)}.)
@@ -802,39 +812,46 @@ string-fence
 least significant bit.  This table gives the power of two which
 corresponds to each syntax flag.
 
-@table @samp
-@item @i{Flag}
-@i{Bit value}
-@item 1
-@code{(lsh 1 16)}
-@item 2
-@code{(lsh 1 17)}
-@item 3
-@code{(lsh 1 18)}
-@item 4
-@code{(lsh 1 19)}
-@item p
-@code{(lsh 1 20)}
-@item b
-@code{(lsh 1 21)}
-@end table
+@multitable @columnfractions .05 .3 .3 .3
+@item@tab
+@i{Prefix} @i{Flag}
+@tab
+@i{Prefix} @i{Flag}
+@tab
+@i{Prefix} @i{Flag}
+@item@tab
+@samp{1} @ @  @code{(lsh 1 16)}
+@tab
+@samp{3} @ @  @code{(lsh 1 18)}
+@tab
+@samp{p} @ @  @code{(lsh 1 20)}
+@item@tab
+@samp{2} @ @  @code{(lsh 1 17)}
+@tab
+@samp{4} @ @  @code{(lsh 1 19)}
+@tab
+@samp{b} @ @  @code{(lsh 1 21)}
+@end multitable
 
 @node Categories
 @section Categories
 @cindex categories of characters
 
   @dfn{Categories} provide an alternate way of classifying characters
-syntactically.  You can define a large number of categories, and then
-independently assign each character to one or more of them.  Unlike
+syntactically.  You can define several categories as needed, then
+independently assign each character to one or more categories.  Unlike
 syntax classes, categories are not mutually exclusive; it is normal for
 one character to belong to several categories.
 
   Each buffer has a @dfn{category table} which records which categories
 are defined and also which characters belong to each category.  Each
-category table defines its own categories.  Each category has a name,
-which is an @sc{ASCII} printing character in the range @w{@samp{ }} to
-@samp{~}.  You specify the name of a category when you define it with
-@code{define-category}.
+category table defines its own categories, but normally these are
+initialized by copying from the standard categories table, so that the
+standard categories are available in all modes.
+
+  Each category has a name, which is an @sc{ASCII} printing character in
+the range @w{@samp{ }} to @samp{~}.  You specify the name of a category
+when you define it with @code{define-category}.
 
   The category table is actually a char-table (@pxref{Char-Tables}).
 The element of the category table at index @var{c} is a @dfn{category
@@ -865,8 +882,8 @@ in category table @var{table}.
 
 @defun get-unused-category table
 This function returns a category name (a character) which is not
-currently defined in @var{table}.  If none is still available, it
-returns @code{nil},
+currently defined in @var{table}.  If all possible categories are in use
+in @var{table}, it returns @code{nil},
 @end defun
 
 @defun category-table
diff --git a/lispref/text.texi b/lispref/text.texi
index f1ab809c96b..96b527d23fa 100644
--- a/lispref/text.texi
+++ b/lispref/text.texi
@@ -79,6 +79,13 @@ buffer is @samp{@@}:
 @end example
 @end defun
 
+@defun char-before position
+This function returns the character in the current buffer immediately
+before position @var{position}.  If @var{position} is out of range for
+this purpose, either before the beginning of the buffer, or at or beyond
+the end, then the value is @code{nil}.
+@end defun
+
 @defun following-char
 This function returns the character following point in the current
 buffer.  This is similar to @code{(char-after (point))}.  However, if
@@ -185,19 +192,6 @@ This is the contents of buffer foo
 @defun buffer-substring-no-properties start end
 This is like @code{buffer-substring}, except that it does not copy text
 properties, just the characters themselves.  @xref{Text Properties}.
-Here's an example of using this function to get a word to look up in an
-alist:
-
-@example
-(setq flammable
-      (assoc (buffer-substring-no-properties start end)
-             '(("wood" . t) ("paper" . t)
-               ("steel" . nil) ("asbestos" . nil))))
-@end example
-
-If this were written using @code{buffer-substring} instead, it would not
-work reliably; any text properties that happened to be in the word
-copied from the buffer would make the comparisons fail.
 @end defun
 
 @defun buffer-string
@@ -282,23 +276,22 @@ at the second character.
 @cindex insertion of text
 @cindex text insertion
 
+@cindex insertion before point
+@cindex before point, insertion
   @dfn{Insertion} means adding new text to a buffer.  The inserted text
 goes at point---between the character before point and the character
-after point.
+after point.  Some insertion functions leave point before the inserted
+text, while other functions leave it after.  We call the former
+insertion @dfn{after point} and the latter insertion @dfn{before point}.
 
   Insertion relocates markers that point at positions after the
 insertion point, so that they stay with the surrounding text
 (@pxref{Markers}).  When a marker points at the place of insertion,
-insertion normally doesn't relocate the marker, so that it points to the
-beginning of the inserted text; however, certain special functions such
-as @code{insert-before-markers} relocate such markers to point after the
-inserted text.
-
-@cindex insertion before point
-@cindex before point, insertion
-  Some insertion functions leave point before the inserted text, while
-other functions leave it after.  We call the former insertion @dfn{after
-point} and the latter insertion @dfn{before point}.
+insertion may or may not relocate the marker, depending on the marker's
+insertion type (@pxref{Marker Insertion Types}).  Certain special
+functions such as @code{insert-before-markers} relocate all such markers
+to point after the inserted text, regardless of the markers' insertion
+type.
 
   Insertion functions signal an error if the current buffer is
 read-only.
@@ -329,11 +322,11 @@ inserted text falls outside the overlay; if a nonempty overlay ends at
 the insertion point, the inserted text falls inside that overlay.
 @end defun
 
-@defun insert-char character count &optional inherit
+@defun insert-char character &optional count inherit
 This function inserts @var{count} instances of @var{character} into the
-current buffer before point.  The argument @var{count} must be a number,
-and @var{character} must be a character.  The value is @code{nil}.
-@c It's unfortunate that count comes second.  Not like make-string, etc.
+current buffer before point.  The argument @var{count} should be a
+number (@code{nil} means 1), and @var{character} must be a character.
+The value is @code{nil}.
 
 If @var{inherit} is non-@code{nil}, then the inserted characters inherit
 sticky text properties from the two characters before and after the
@@ -531,6 +524,16 @@ the kill ring.
 The value returned is always @code{nil}.
 @end deffn
 
+@tindex backward-delete-char-untabify-method
+@defopt backward-delete-char-untabify-method
+This option specifies how @code{backward-delete-char-untabify} should
+deal with whitespace.  Possible values include @code{untabify}, the
+default, meaning convert a tab to many spaces and delete one;
+@code{hungry}, meaning delete all the whitespace characters before point
+with one command, and @code{nil}, meaning do nothing special for
+whitespace characters.
+@end defopt
+
 @node User-Level Deletion
 @section User-Level Deletion Commands
 
@@ -668,7 +671,7 @@ A blank line is defined as a line containing only tabs and spaces.
 @section The Kill Ring
 @cindex kill ring
 
-  @dfn{Kill} functions delete text like the deletion functions, but save
+  @dfn{Kill functions} delete text like the deletion functions, but save
 it so that the user can reinsert it by @dfn{yanking}.  Most of these
 functions have @samp{kill-} in their name.  By contrast, the functions
 whose names start with @samp{delete-} normally do not save text for
@@ -828,10 +831,10 @@ The value is always @code{nil}.
 @node Low-Level Kill Ring
 @subsection Low-Level Kill Ring
 
-  These functions and variables provide access to the kill ring at a lower
-level, but still convenient for use in Lisp programs.  They take care of
-interaction with X Window selections.  They do not exist in Emacs
-version 18.
+  These functions and variables provide access to the kill ring at a
+lower level, but still convenient for use in Lisp programs, because they
+take care of interaction with window system selections
+(@pxref{Window System Selections}).
 
 @defun current-kill n &optional do-not-move
 The function @code{current-kill} rotates the yanking pointer which
@@ -873,9 +876,9 @@ If the value is a function, @code{current-kill} calls it to get the
 then that value is used as the ``most recent kill''.  If it returns
 @code{nil}, then the first element of @code{kill-ring} is used.
 
-The normal use of this hook is to get the X server's primary selection
-as the most recent kill, even if the selection belongs to another X
-client.  @xref{X Selections}.
+The normal use of this hook is to get the window system's primary
+selection as the most recent kill, even if the selection belongs to
+another application.  @xref{Window System Selections}.
 @end defvar
 
 @defvar interprogram-cut-function
@@ -886,8 +889,8 @@ programs, when you are using a window system.  Its value should be
 If the value is a function, @code{kill-new} and @code{kill-append} call
 it with the new first element of the kill ring as an argument.
 
-The normal use of this hook is to set the X server's primary selection
-from the newly killed text.
+The normal use of this hook is to set the window system's primary
+selection from the newly killed text.  @xref{Window System Selections}.
 @end defvar
 
 @node Internals of Kill Ring
@@ -925,10 +928,12 @@ different piece of text" "yet older text")}.
 
 @example
 @group
-kill-ring       kill-ring-yank-pointer
-  |               |
-  |     ___ ___    --->  ___ ___      ___ ___
-   --> |___|___|------> |___|___|--> |___|___|--> nil
+kill-ring                  ---- kill-ring-yank-pointer
+  |                       |
+  |                       v
+  |     --- ---          --- ---      --- ---
+   --> |   |   |------> |   |   |--> |   |   |--> nil
+        --- ---          --- ---      --- ---
          |                |            |            
          |                |            |            
          |                |             -->"yet older text" 
@@ -1103,8 +1108,7 @@ has no effect.
 This function returns @code{nil}.  It cannot be called interactively.
 
 The name @code{buffer-flush-undo} is not considered obsolete, but the
-preferred name @code{buffer-disable-undo} is new as of Emacs versions
-19.
+preferred name is @code{buffer-disable-undo}.
 @end defun
 
   As editing continues, undo lists get longer and longer.  To prevent
@@ -1153,7 +1157,8 @@ If it is non-@code{nil}, that requests some kind of justification.  It
 can be @code{left}, @code{right}, @code{full}, or @code{center}, to
 request a specific style of justification.  If it is @code{t}, that
 means to use the current justification style for this part of the text
-(see @code{current-justification}, below).
+(see @code{current-justification}, below).  Any other value is treated
+as @code{full}.
 
   When you call the filling functions interactively, using a prefix
 argument implies the value @code{full} for @var{justify}.
@@ -1358,10 +1363,19 @@ whitespace.
 
 @defvar left-margin
 This variable specifies the base left margin column.  In Fundamental
-mode, @key{LFD} indents to this column.  This variable automatically
+mode, @kbd{C-j} indents to this column.  This variable automatically
 becomes buffer-local when set in any fashion.
 @end defvar
 
+@tindex fill-nobreak-predicate
+@defvar fill-nobreak-predicate
+This variable gives major modes a way to specify not to break a line at
+certain places.  Its value should be a function.  This function is
+called during filling, with no arguments and with point located at the
+place where a break is being considered.  If the function returns
+non-@code{nil}, then the line won't be broken there.
+@end defvar
+
 @node Auto Filling
 @comment  node-name,  next,  previous,  up
 @section Auto Filling
@@ -1395,7 +1409,8 @@ was renamed to @code{auto-fill-function} in version 19.
 @defvar normal-auto-fill-function
 This variable specifies the function to use for
 @code{auto-fill-function}, if and when Auto Fill is turned on.  Major
-modes can set this locally to alter how Auto Fill works.
+modes can set buffer-local values for this variable to alter how Auto
+Fill works.
 @end defvar
 
 @node Sorting
@@ -1485,9 +1500,7 @@ the sort order.
   (save-restriction
     (narrow-to-region beg end)
     (goto-char (point-min))
-    (sort-subr reverse
-               'forward-line
-               'end-of-line)))
+    (sort-subr reverse 'forward-line 'end-of-line)))
 @end group
 @end example
 
@@ -1503,8 +1516,7 @@ its @code{sort-subr} call looks like this:
 @group
 (sort-subr reverse
            (function 
-            (lambda () 
-              (skip-chars-forward "\n \t\f")))
+            (lambda () (skip-chars-forward "\n \t\f")))
            'forward-paragraph)
 @end group
 @end example
@@ -1630,7 +1642,7 @@ containing position @var{beg}, and the entire line containing position
 
 Note that @code{sort-columns} uses the @code{sort} utility program,
 and so cannot work properly on text containing tab characters.  Use
-@kbd{M-x @code{untabify}} to convert tabs to spaces before sorting.
+@kbd{M-x untabify} to convert tabs to spaces before sorting.
 @end deffn
 
 @node Columns
@@ -1715,7 +1727,7 @@ count from zero at the left margin.
 
   This section describes the primitive functions used to count and
 insert indentation.  The functions in the following sections use these
-primitives.
+primitives.  @xref{Width}, for related functions.
 
 @defun current-indentation
 @comment !!Type Primitive Function
@@ -1745,7 +1757,7 @@ Properties}.
 @comment !!SourceFile indent.c
 If this variable is non-@code{nil}, indentation functions can insert
 tabs as well as spaces.  Otherwise, they insert only spaces.  Setting
-this variable automatically makes it local to the current buffer.
+this variable automatically makes it buffer-local in the current buffer.
 @end defopt
 
 @node Mode-Specific Indent
@@ -2009,11 +2021,11 @@ nonblank character on that line.  It returns @code{nil}.
 @node Case Changes
 @comment  node-name,  next,  previous,  up
 @section Case Changes
-@cindex case changes
+@cindex case conversion in buffers
 
   The case change commands described here work on text in the current
-buffer.  @xref{Character Case}, for case conversion commands that work
-on strings and characters.  @xref{Case Table}, for how to customize
+buffer.  @xref{Case Conversion}, for case conversion functions that work
+on strings and characters.  @xref{Case Tables}, for how to customize
 which characters are upper or lower case and how to convert them.
 
 @deffn Command capitalize-region start end
@@ -2417,9 +2429,9 @@ for @var{object} is the current buffer.
 @subsection Properties with Special Meanings
 
   Here is a table of text property names that have special built-in
-meanings.  The following section lists a few more special property names
-that are used to control filling.  All other names have no standard
-meaning, and you can use them as you like.
+meanings.  The following sections list a few additional special property
+names that control filling and property inheritance.  All other names
+have no standard meaning, and you can use them as you like.
 
 @table @code
 @cindex category of text character
@@ -2813,8 +2825,8 @@ is done by the command definition.  Here is how Dired does it:
     (save-excursion
       (set-buffer (window-buffer (posn-window (event-end event))))
       (save-excursion
-        (goto-char (posn-point (event-end event)))
-        (setq file (dired-get-filename))))
+        (goto-char (posn-point (event-end event)))
+        (setq file (dired-get-filename))))
     (select-window (posn-window (event-end event)))
     (find-file-other-window (file-name-sans-versions file t))))
 @end smallexample
@@ -2955,15 +2967,11 @@ translation table.
 @cindex registers
 
   A register is a sort of variable used in Emacs editing that can hold a
-marker, a string, a rectangle, a window configuration (of one frame), or
-a frame configuration (of all frames).  Each register is named by a
-single character.  All characters, including control and meta characters
-(but with the exception of @kbd{C-g}), can be used to name registers.
-Thus, there are 255 possible registers.  A register is designated in
-Emacs Lisp by a character that is its name.
-
-  The functions in this section return unpredictable values unless
-otherwise stated.
+variety of different kinds of values.  Each register is named by a
+single character.  All ASCII characters and their meta variants (but
+with the exception of @kbd{C-g}) can be used to name registers.  Thus,
+there are 255 possible registers.  A register is designated in Emacs
+Lisp by the character that is its name.
 
 @defvar register-alist
 This variable is an alist of elements of the form @code{(@var{name} .
@@ -2971,13 +2979,47 @@ This variable is an alist of elements of the form @code{(@var{name} .
 register that has been used.
 
 The object @var{name} is a character (an integer) identifying the
-register.  The object @var{contents} is a string, marker, window
-configuration, frame configuration, or list representing the register
-contents.  A string represents text stored in the register.  A marker
-represents a position.  A list represents a rectangle; its elements are
-strings, one per line of the rectangle.
+register.
 @end defvar
 
+  The @var{contents} of a register can have several possible types:
+
+@table @asis
+@item a number
+A number stands for itself.  If @code{insert-register} finds a number
+in the register, it converts the number to decimal.
+
+@item a marker
+A marker represents a buffer position to jump to.
+
+@item a string
+A string is text saved in the register.
+
+@item a rectangle
+A rectangle is represented by a list of strings.
+
+@item @code{(@var{window-configuration} @var{position})}
+This represents a window configuration to restore in one frame, and a
+position to jump to in the current buffer.
+
+@item @code{(@var{frame-configuration} @var{position})}
+This represents a frame configuration to restore, and a position
+to jump to in the current buffer.
+
+@item (file @var{filename})
+This represents a file to visit; jumping to this value visits file
+@var{filename}.
+
+@item (file-query @var{filename} @var{position})
+This represents a file to visit and a position in it; jumping to this
+value visits file @var{filename} and goes to buffer position
+@var{position}.  Restoring this type of position asks the user for
+confirmation first.
+@end table
+
+  The functions in this section return unpredictable values unless
+otherwise stated.
+
 @defun get-register reg
 This function returns the contents of the register
 @var{reg}, or @code{nil} if it has no contents.
@@ -3136,11 +3178,18 @@ that seems safe.
 If a program makes several text changes in the same area of the buffer,
 using the macro @code{combine-after-change-calls} around that part of
 the program can make it run considerably faster when after-change hooks
-are in use.
+are in use.  When the after-change hooks are ultimately called, the
+arguments specify a portion of the buffer including all of the changes
+made within the @code{combine-after-change-calls} body.
 
 @strong{Warning:} You must not alter the values of
 @code{after-change-functions} and @code{after-change-function} within
 the body of a @code{combine-after-change-calls} form.
+
+@strong{Note:} If the changes you combine occur in widely scattered
+parts of the buffer, this will still work, but it is not advisable,
+because it may lead to inefficient behavior for some change hook
+functions.
 @end defmac
 
 @defvar before-change-function
@@ -3177,8 +3226,11 @@ to call.  Here is an example:
     (while list
       (funcall (car list) beg end len)
       (setq list (cdr list)))))
+
+@group
 (add-hooks 'after-change-functions
            'indirect-after-change-function)
+@end group
 @end example
 
 @defvar first-change-hook
diff --git a/lispref/tips.texi b/lispref/tips.texi
index e5a7bb24631..11522391a3f 100644
--- a/lispref/tips.texi
+++ b/lispref/tips.texi
@@ -3,7 +3,7 @@
 @c Copyright (C) 1990, 1991, 1992, 1993, 1995, 1998 Free Software Foundation, Inc. 
 @c See the file elisp.texi for copying conditions.
 @setfilename ../info/tips
-@node Tips, GNU Emacs Internals, Calendar, Top
+@node Tips, GNU Emacs Internals, System Interface, Top
 @appendix Tips and Conventions
 @cindex tips
 @cindex standards of coding style
@@ -37,10 +37,11 @@ names of all global variables, constants, and functions with the chosen
 prefix.  This helps avoid name conflicts.
 
 This recommendation applies even to names for traditional Lisp
-primitives that are not primitives in Emacs Lisp---even to @code{cadr}.
-Believe it or not, there is more than one plausible way to define
-@code{cadr}.  Play it safe; append your name prefix to produce a name
-like @code{foo-cadr} or @code{mylib-cadr} instead.
+primitives that are not primitives in Emacs Lisp---even to
+@code{copy-list}.  Believe it or not, there is more than one plausible
+way to define @code{copy-list}.  Play it safe; append your name prefix
+to produce a name like @code{foo-copy-list} or @code{mylib-copy-list}
+instead.
 
 If you write a function that you think ought to be added to Emacs under
 a certain name, such as @code{twiddle-files}, don't call it by that name
@@ -75,11 +76,11 @@ macro:
 @end example
 
 @noindent
-(And @var{bar} should contain @code{(provide '@var{bar})}, to make the
-@code{require} work.)  This will cause @var{bar} to be loaded when you
-byte-compile @var{foo}.  Otherwise, you risk compiling @var{foo} without
-the necessary macro loaded, and that would produce compiled code that
-won't work right.  @xref{Compiling Macros}.
+(And the library @var{bar} should contain @code{(provide '@var{bar})},
+to make the @code{require} work.)  This will cause @var{bar} to be
+loaded when you byte-compile @var{foo}.  Otherwise, you risk compiling
+@var{foo} without the necessary macro loaded, and that would produce
+compiled code that won't work right.  @xref{Compiling Macros}.
 
 Using @code{eval-when-compile} avoids loading @var{bar} when
 the compiled version of @var{foo} is @emph{used}.
@@ -111,9 +112,9 @@ Instead, define sequences consisting of @kbd{C-c} followed by a control
 character, a digit, or certain punctuation characters.  These sequences
 are reserved for major modes.
 
-Changing all the major modes in Emacs 18 so they would follow this
-convention was a lot of work.  Abandoning this convention would make
-that work go to waste, and inconvenience users.
+Changing all the Emacs major modes to follow this convention was a lot
+of work.  Abandoning this convention would make that work go to waste,
+and inconvenience users.
 
 @item
 Sequences consisting of @kbd{C-c} followed by @kbd{@{}, @kbd{@}},
@@ -136,7 +137,7 @@ as a help character for listing the subcommands of the prefix character.
 
 @item
 Do not bind a key sequence ending in @key{ESC} except following
-another @key{ESC}.  (That is, it is ok to bind a sequence ending in
+another @key{ESC}.  (That is, it is OK to bind a sequence ending in
 @kbd{@key{ESC} @key{ESC}}.)
 
 The reason for this rule is that a non-prefix binding for @key{ESC} in
@@ -251,7 +252,7 @@ user switch back at will.  @xref{Recursive Editing}.
 In some other systems there is a convention of choosing variable names
 that begin and end with @samp{*}.  We don't use that convention in Emacs
 Lisp, so please don't use it in your programs.  (Emacs uses such names
-only for program-generated buffers.)  The users will find Emacs more
+only for special-purpose buffers.)  The users will find Emacs more
 coherent if all libraries use the same conventions.
 
 @item
@@ -273,7 +274,7 @@ default indentation parameters.
 Don't make a habit of putting close-parentheses on lines by themselves;
 Lisp programmers find this disconcerting.  Once in a while, when there
 is a sequence of many consecutive close-parentheses, it may make sense
-to split them in one or two significant places.
+to split the sequence in one or two significant places.
 
 @item
 Please put a copyright notice on the file if you give copies to anyone.
@@ -366,7 +367,11 @@ the speed.  @xref{Inline Functions}.
 @node Documentation Tips
 @section Tips for Documentation Strings
 
-  Here are some tips for the writing of documentation strings.
+@tindex checkdoc-minor-mode
+@findex checkdoc-minor-mode
+  Here are some tips and conventions for the writing of documentation
+strings.  You can check many of these conventions by running the command
+@kbd{M-x checkdoc-minor-mode}.
 
 @itemize @bullet
 @item
@@ -471,10 +476,18 @@ write @code{t} and @code{nil} without single-quotes.
 When a documentation string refers to a Lisp symbol, write it as it
 would be printed (which usually means in lower case), with single-quotes
 around it.  For example: @samp{lambda}.  There are two exceptions: write
-t and nil without single-quotes.  (In this manual, we normally do use
-single-quotes for those symbols.)
+t and nil without single-quotes.  (In this manual, we use a different
+convention, with single-quotes for all symbols.)
 @end ifinfo
 
+For example:
+
+@example
+The value of `swim-speed' specifies how fast to swim.
+Possible values are t for high speed, nil for low speed,
+and `medium' for medium speed.
+@end example
+
 @item
 Don't write key sequences directly in documentation strings.  Instead,
 use the @samp{\\[@dots{}]} construct to stand for them.  For example,
@@ -541,11 +554,12 @@ at that point.  For example:
 @end group
 @end smallexample
 
-Every function that has no documentation string (because it is use only
-internally within the package it belongs to), should have instead a
-two-semicolon comment right before the function, explaining what the
-function does and how to call it properly.  Explain precisely what each
-argument means and how the function interprets its possible values.
+Every function that has no documentation string (presumably one that is
+used only internally within the package it belongs to), should have
+instead a two-semicolon comment right before the function, explaining
+what the function does and how to call it properly.  Explain precisely
+what each argument means and how the function interprets its possible
+values.
 
 @item ;;;
 Comments that start with three semicolons, @samp{;;;}, should start at
@@ -584,7 +598,7 @@ program.  For example:
 
 @noindent
 The indentation commands of the Lisp modes in Emacs, such as @kbd{M-;}
-(@code{indent-for-comment}) and @key{TAB} (@code{lisp-indent-line})
+(@code{indent-for-comment}) and @key{TAB} (@code{lisp-indent-line}),
 automatically indent comments according to these conventions,
 depending on the number of semicolons.  @xref{Comments,,
 Manipulating Comments, emacs, The GNU Emacs Manual}.
@@ -613,7 +627,9 @@ them.  This section explains these conventions.  First, an example:
 ;; Keywords: docs
 
 ;; This file is part of GNU Emacs.
-@var{copying permissions}@dots{}
+@dots{}
+;; Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+;; Boston, MA 02111-1307, USA.
 @end group
 @end smallexample
 
diff --git a/lispref/variables.texi b/lispref/variables.texi
index 765753d2794..4517d6bb02f 100644
--- a/lispref/variables.texi
+++ b/lispref/variables.texi
@@ -38,6 +38,8 @@ variable.
 * Setting Variables::     Storing new values in variables.
 * Variable Scoping::      How Lisp chooses among local and global values.
 * Buffer-Local Variables::  Variable values in effect only in one buffer.
+* Frame-Local Variables::   Variable values in effect only in one frame.
+* Future Local Variables::  New kinds of local values we might add some day.
 @end menu
 
 @node Global Variables
@@ -73,7 +75,8 @@ x @result{} (a b)
 @noindent
 assuming the @code{setq} form shown above has already been executed.
 
-  If you do another @code{setq}, the new value replaces the old one:
+  If you do set the same variable again, the new value replaces the old
+one:
 
 @example
 @group
@@ -96,14 +99,13 @@ x
 @vindex t
 @kindex setting-constant
 
-  In Emacs Lisp, certain symbols normally evaluate to themselves.
-These include @code{nil} and @code{t}, as well as any symbol whose
-name starts with @samp{:}.
-
-  The symbols @code{nil} and @code{t} @emph{always} evaluate to
-themselves.  These symbols cannot be rebound, nor can their values be
-changed.  Any attempt to change the value of @code{nil} or @code{t}
-signals a @code{setting-constant} error.
+  In Emacs Lisp, certain symbols normally evaluate to themselves.  These
+include @code{nil} and @code{t}, as well as any symbol whose name starts
+with @samp{:}.  These symbols cannot be rebound, nor can their values be
+changed.  Any attempt to set or bind @code{nil} or @code{t} signals a
+@code{setting-constant} error.  The same is true for a symbol whose name
+starts with @samp{:}, except that you are allowed to set such symbol to
+itself.
 
 @example
 @group
@@ -116,6 +118,13 @@ nil @equiv{} 'nil
 @end group
 @end example
 
+@tindex keyword-symbols-constant-flag
+@defvar keyword-symbols-constant-flag
+If this variable is @code{nil}, you are allowed to set and bind symbols
+whose names start with @samp{:} as you wish.  This is to make it
+possible to run old Lisp programs which do that.
+@end defvar
+
 @node Local Variables
 @section Local Variables
 @cindex binding local variables
@@ -125,7 +134,7 @@ nil @equiv{} 'nil
 
   Global variables have values that last until explicitly superseded
 with new values.  Sometimes it is useful to create variable values that
-exist temporarily---only while within a certain part of the program.
+exist temporarily---only until a certain part of the program finishes.
 These values are called @dfn{local}, and the variables so used are
 called @dfn{local variables}.
 
@@ -143,7 +152,7 @@ local values may be shadowed (@pxref{Scope}).
 
   If you set a variable (such as with @code{setq}) while it is local,
 this replaces the local value; it does not alter the global value, or
-previous local values that are shadowed.  To model this behavior, we
+previous local values, that are shadowed.  To model this behavior, we
 speak of a @dfn{local binding} of the variable as well as a local value.
 
   The local binding is a conceptual place that holds a local value.
@@ -161,12 +170,12 @@ not create a new binding.
   A variable can have more than one local binding at a time (for
 example, if there are nested @code{let} forms that bind it).  In such a
 case, the most recently created local binding that still exists is the
-@dfn{current binding} of the variable.  (This is called @dfn{dynamic
-scoping}; see @ref{Variable Scoping}.)  If there are no local bindings,
-the variable's global binding is its current binding.  We also call the
-current binding the @dfn{most-local existing binding}, for emphasis.
-Ordinary evaluation of a symbol always returns the value of its current
-binding.
+@dfn{current binding} of the variable.  (This rule is called
+@dfn{dynamic scoping}; see @ref{Variable Scoping}.)  If there are no
+local bindings, the variable's global binding is its current binding.
+We sometimes call the current binding the @dfn{most-local existing
+binding}, for emphasis.  Ordinary evaluation of a symbol always returns
+the value of its current binding.
 
   The special forms @code{let} and @code{let*} exist to create
 local bindings.
@@ -289,8 +298,7 @@ the error @code{void-variable}, unless and until you set it again.
 
 @example
 @group
-(makunbound 'x)      ; @r{Make the global value}
-                     ;   @r{of @code{x} void.}
+(makunbound 'x)      ; @r{Make the global value of @code{x} void.}
      @result{} x
 @end group
 @group
@@ -304,9 +312,9 @@ local existing binding.  This is the only way a symbol can have a void
 local binding, since all the constructs that create local bindings
 create them with values.  In this case, the voidness lasts at most as
 long as the binding does; when the binding is removed due to exit from
-the construct that made it, the previous or global binding is reexposed
-as usual, and the variable is no longer void unless the newly reexposed
-binding was void all along.
+the construct that made it, the previous local or global binding is
+reexposed as usual, and the variable is no longer void unless the newly
+reexposed binding was void all along.
 
 @smallexample
 @group
@@ -439,9 +447,9 @@ Emacs help functions (@pxref{Documentation}) look for this property.
 
 If the first character of @var{doc-string} is @samp{*}, it means that
 this variable is considered a user option.  This lets users set the
-variable conventiently using the commands @code{set-variable} and
+variable conveniently using the commands @code{set-variable} and
 @code{edit-options}.  However, it is better to use @code{defcustom}
-instead of @code{defvar}, for user option variables, to specify
+instead of @code{defvar} for user option variables, so you can specify
 customization information.  @xref{Customization}.
 
 Here are some examples.  This form defines @code{foo} but does not
@@ -580,7 +588,7 @@ entire computation of the value into the @code{defvar}, like this:
 @noindent
 This method has several benefits.  First, if the user quits while
 loading the file, the variable is either still uninitialized or
-initialized properly, never in-between.  If it is uninitialized,
+initialized properly, never in-between.  If it is still uninitialized,
 reloading the file will initialize it properly.  Second, reloading the
 file once the variable is initialized will not alter it; that is
 important if the user has run hooks to alter part of the contents (such
@@ -620,11 +628,11 @@ each form, if you do want to reinitialize the variable.
 @end example
 
 @noindent
-This code sets the variable, then alters it, but only if the variable
-had been @code{ni}.  If the user quits just after the @code{setq}, that
-leaves the variable neither correctly initialized nor void nor
-@code{nil}.  Once that happens, reloading the file will not initialize
-the variable; it will remain incomplete.
+This code sets the variable, then alters it, but it does so in more than
+one step.  If the user quits just after the @code{setq}, that leaves the
+variable neither correctly initialized nor void nor @code{nil}.  Once
+that happens, reloading the file will not initialize the variable; it
+will remain incomplete.
 
 @node Accessing Variables
 @section Accessing Variable Values
@@ -673,8 +681,8 @@ has no local bindings.
 @end group
 @end example
 
-A @code{void-variable} error is signaled if @var{symbol} has neither a
-local binding nor a global one.
+A @code{void-variable} error is signaled if the current binding of
+@var{symbol} is void.
 @end defun
 
 @node Setting Variables
@@ -803,6 +811,7 @@ value of @var{symbol} had better be a list already before the call.
 The argument @var{symbol} is not implicitly quoted; @code{add-to-list}
 is an ordinary function, like @code{set} and unlike @code{setq}.  Quote
 the argument yourself if that is what you want.
+@end defun
 
 Here's a scenario showing how to use @code{add-to-list}:
 
@@ -819,7 +828,6 @@ Here's a scenario showing how to use @code{add-to-list}:
 foo                       ;; @r{@code{foo} was changed.}
      @result{} (c a b)
 @end example
-@end defun
 
   An equivalent expression for @code{(add-to-list '@var{var}
 @var{value})} is this:
@@ -979,10 +987,11 @@ closures.
 works) may help you understand dynamic binding.  This technique is
 called @dfn{deep binding} and was used in early Lisp systems.
 
-  Suppose there is a stack of bindings: variable-value pairs.  At entry
-to a function or to a @code{let} form, we can push bindings onto the stack
-for the arguments or local variables created there.  We can pop those
-bindings from the stack at exit from the binding construct.
+  Suppose there is a stack of bindings, which are variable-value pairs.
+At entry to a function or to a @code{let} form, we can push bindings
+onto the stack for the arguments or local variables created there.  We
+can pop those bindings from the stack at exit from the binding
+construct.
 
   We can find the value of a variable by searching the stack from top to
 bottom for a binding for that variable; the value from that binding is
@@ -1052,18 +1061,22 @@ use short names like @code{x}.
 @cindex buffer-local variables
 
   Global and local variable bindings are found in most programming
-languages in one form or another.  Emacs also supports another, unusual
-kind of variable binding: @dfn{buffer-local} bindings, which apply only
-to one buffer.  Emacs Lisp is meant for programming editing commands,
-and having different values for a variable in different buffers is an
-important customization method.  (A few variables have bindings that
-are local to a given X terminal; see @ref{Multiple Displays}.)
+languages in one form or another.  Emacs also supports additional,
+unusual kinds of variable binding: @dfn{buffer-local} bindings, which
+apply only in one buffer, and frame-local bindings, which apply only in
+one frame.  Having different values for a variable in different buffers
+and/or frames is an important customization method.
+
+  This section describes buffer-local bindings; for frame-local
+bindings, see the following section, @ref{Frame-Local Variables}.  (A few
+variables have bindings that are local to a X terminal; see
+@ref{Multiple Displays}.)
 
 @menu
 * Intro to Buffer-Local::      Introduction and concepts.
 * Creating Buffer-Local::      Creating and destroying buffer-local bindings.
 * Default Value::              The default value is seen in buffers
-                                 that don't have their own local values.
+                                 that don't have their own buffer-local values.
 @end menu
 
 @node Intro to Buffer-Local
@@ -1082,22 +1095,25 @@ this is the global binding.
 
   A variable can have buffer-local bindings in some buffers but not in
 other buffers.  The default binding is shared by all the buffers that
-don't have their own bindings for the variable.  If you set the variable
-in a buffer that does not have a buffer-local binding for it, this sets
-the default binding, so the new value is visible in all the buffers that
-see the default binding.
+don't have their own bindings for the variable.  (This includes all
+newly created buffers.)  If you set the variable in a buffer that does
+not have a buffer-local binding for it, this sets the default binding
+(assuming there are no frame-local bindings to complicate the matter),
+so the new value is visible in all the buffers that see the default
+binding.
 
   The most common use of buffer-local bindings is for major modes to change
 variables that control the behavior of commands.  For example, C mode and
 Lisp mode both set the variable @code{paragraph-start} to specify that only
 blank lines separate paragraphs.  They do this by making the variable
 buffer-local in the buffer that is being put into C mode or Lisp mode, and
-then setting it to the new value for that mode.
+then setting it to the new value for that mode.  @xref{Major Modes}.
 
   The usual way to make a buffer-local binding is with
-@code{make-local-variable}, which is what major mode commands use.  This
-affects just the current buffer; all other buffers (including those yet to
-be created) continue to share the default value.
+@code{make-local-variable}, which is what major mode commands typically
+use.  This affects just the current buffer; all other buffers (including
+those yet to be created) will continue to share the default value unless
+they are explicitly given their own buffer-local bindings.
 
 @cindex automatically buffer-local
   A more powerful operation is to mark the variable as
@@ -1107,11 +1123,11 @@ variable local in all buffers, even those yet to be created.  More
 precisely, the effect is that setting the variable automatically makes
 the variable local to the current buffer if it is not already so.  All
 buffers start out by sharing the default value of the variable as usual,
-but any @code{setq} creates a buffer-local binding for the current
+but setting the variable creates a buffer-local binding for the current
 buffer.  The new value is stored in the buffer-local binding, leaving
-the default binding untouched.  The default value can no longer be
-changed with @code{setq} in this buffer; you need to use
-@code{setq-default} to do that.
+the default binding untouched.  This means that the default value cannot
+be changed with @code{setq} in any buffer; the only way to change it is
+with @code{setq-default}.
 
   @strong{Warning:} When a variable has buffer-local values in one or
 more buffers, you can get Emacs very confused by binding the variable
@@ -1161,7 +1177,8 @@ But @code{save-excursion} as shown here avoids the problem:
 buffer-local binding of buffer @samp{b}.
 
   When a file specifies local variable values, these become buffer-local
-values when you visit the file.  @xref{Auto Major Mode}.
+values when you visit the file.  @xref{File Variables,,, emacs, The
+GNU Emacs Manual}.
 
 @node Creating Buffer-Local
 @subsection Creating and Deleting Buffer-Local Bindings
@@ -1209,9 +1226,10 @@ foo
 @end example
 
 Making a variable buffer-local within a @code{let}-binding for that
-variable does not work.  This is because @code{let} does not distinguish
-between different kinds of bindings; it knows only which variable the
-binding was made for.
+variable does not work reliably, unless the buffer in which you do this
+is not current either on entry to or exit from the @code{let}.  This is
+because @code{let} does not distinguish between different kinds of
+bindings; it knows only which variable the binding was made for.
 
 If the variable is terminal-local, this function signals an error.  Such
 variables cannot have buffer-local bindings as well.  @xref{Multiple
@@ -1226,16 +1244,24 @@ This function marks @var{variable} (a symbol) automatically
 buffer-local, so that any subsequent attempt to set it will make it
 local to the current buffer at the time.
 
-The value returned is @var{variable}.
+A peculiar wrinkle of this feature is that binding the variable (with
+@code{let} or other binding constructs) does not create a buffer-local
+binding for it.  Only setting the variable (with @code{set} or
+@code{setq}) does so.
 
-@strong{Note:} It is a mistake to use @code{make-variable-buffer-local}
-for user-option variables, simply because users @emph{might} want to
-customize them differently in different buffers.  Users can make any
-variable local, when they wish to.
+The value returned is @var{variable}.
 
-The main use of @code{make-variable-buffer-local} is when a variable is
-used for internal purposes, and the Lisp program depends on having
-separate values in separate buffers.
+@strong{Warning:} Don't assume that you should use
+@code{make-variable-buffer-local} for user-option variables, simply
+because users @emph{might} want to customize them differently in
+different buffers.  Users can make any variable local, when they wish
+to.  It is better to leave the choice to them.
+
+The time to use @code{make-variable-buffer-local} is when it is crucial
+that no two buffers ever share the same binding.  For example, when a
+variable is used for internal purposes in a Lisp program which depends
+on having separate values in separate buffers, then using
+@code{make-variable-buffer-local} can be the best solution.
 @end deffn
 
 @defun local-variable-p variable &optional buffer
@@ -1246,11 +1272,11 @@ This returns @code{t} if @var{variable} is buffer-local in buffer
 
 @defun buffer-local-variables &optional buffer
 This function returns a list describing the buffer-local variables in
-buffer @var{buffer}.  It returns an association list (@pxref{Association
-Lists}) in which each association contains one buffer-local variable and
-its value.  When a buffer-local variable is void in @var{buffer}, then
-it appears directly in the resulting list.  If @var{buffer} is omitted,
-the current buffer is used.
+buffer @var{buffer}.  (If @var{buffer} is omitted, the current buffer is
+used.)  It returns an association list (@pxref{Association Lists}) in
+which each element contains one buffer-local variable and its value.
+However, when a variable's buffer-local binding in @var{buffer} is void,
+then the variable appears directly in the resulting list.
 
 @example
 @group
@@ -1309,7 +1335,7 @@ value of @code{standard-syntax-table}, and the abbrev table to the value
 of @code{fundamental-mode-abbrev-table}.
 
 The very first thing this function does is run the normal hook
-@code{change-major-mode-hook} (@pxref{Major Mode Conventions}).
+@code{change-major-mode-hook} (see below).
 
 Every major mode command begins by calling this function, which has the
 effect of switching to Fundamental mode and erasing most of the effects
@@ -1319,6 +1345,15 @@ variables that major modes set should not be marked permanent.
 @code{kill-all-local-variables} returns @code{nil}.
 @end defun
 
+@defvar change-major-mode-hook
+The function @code{kill-all-local-variables} runs this normal hook
+before it does anything else.  This gives major modes a way to arrange
+for something special to be done if the user switches to a different
+major mode.  For best results, make this variable buffer-local, so that
+it will disappear after doing its job and will not interfere with the
+subsequent major mode.  @xref{Hooks}.
+@end defvar
+
 @c Emacs 19 feature
 @cindex permanent local variable
 A buffer-local variable is @dfn{permanent} if the variable name (a
@@ -1332,7 +1367,8 @@ came from or how to save it, rather than with how to edit the contents.
 
   The global value of a variable with buffer-local bindings is also
 called the @dfn{default} value, because it is the value that is in
-effect except when specifically overridden.
+effect whenever neither the current buffer nor the selected frame has
+its own binding for the variable.
 
   The functions @code{default-value} and @code{setq-default} access and
 change a variable's default value regardless of whether the current
@@ -1345,13 +1381,13 @@ this variable.
 @c Emacs 19 feature
   The special forms @code{defvar} and @code{defconst} also set the
 default value (if they set the variable at all), rather than any
-buffer-local value.
+buffer-local or frame-local value.
 
 @defun default-value symbol
 This function returns @var{symbol}'s default value.  This is the value
-that is seen in buffers that do not have their own values for this
-variable.  If @var{symbol} is not buffer-local, this is equivalent to
-@code{symbol-value} (@pxref{Accessing Variables}).
+that is seen in buffers and frames that do not have their own values for
+this variable.  If @var{symbol} is not buffer-local, this is equivalent
+to @code{symbol-value} (@pxref{Accessing Variables}).
 @end defun
 
 @c Emacs 19 feature
@@ -1379,49 +1415,49 @@ current buffer sees.
 @example
 @group
 ;; @r{In buffer @samp{foo}:}
-(make-local-variable 'local)
-     @result{} local
+(make-local-variable 'buffer-local)
+     @result{} buffer-local
 @end group
 @group
-(setq local 'value-in-foo)
+(setq buffer-local 'value-in-foo)
      @result{} value-in-foo
 @end group
 @group
-(setq-default local 'new-default)
+(setq-default buffer-local 'new-default)
      @result{} new-default
 @end group
 @group
-local
+buffer-local
      @result{} value-in-foo
 @end group
 @group
-(default-value 'local)
+(default-value 'buffer-local)
      @result{} new-default
 @end group
 
 @group
 ;; @r{In (the new) buffer @samp{bar}:}
-local
+buffer-local
      @result{} new-default
 @end group
 @group
-(default-value 'local)
+(default-value 'buffer-local)
      @result{} new-default
 @end group
 @group
-(setq local 'another-default)
+(setq buffer-local 'another-default)
      @result{} another-default
 @end group
 @group
-(default-value 'local)
+(default-value 'buffer-local)
      @result{} another-default
 @end group
 
 @group
 ;; @r{Back in buffer @samp{foo}:}
-local
+buffer-local
      @result{} value-in-foo
-(default-value 'local)
+(default-value 'buffer-local)
      @result{} another-default
 @end group
 @end example
@@ -1442,3 +1478,123 @@ an ordinary evaluated argument.
 @end group
 @end example
 @end defun
+
+@node Frame-Local Variables
+@section Frame-Local Variables
+
+  Just as variables can have buffer-local bindings, they can also have
+frame-local bindings.  These bindings belong to one frame, and are in
+effect when that frame is selected.  Frame-local bindings are actually
+frame parameters: you create a frame-local binding in a specific frame
+by calling @code{modify-frame-parameters} and specifying the variable
+name as the parameter name.
+
+  To enable frame-local bindings for a certain variable, call the function
+@code{make-variable-frame-local}.
+
+@defun make-variable-frame-local variable
+Enable the use of frame-local bindings for @var{variable}.  This does
+not in itself create any frame-local bindings for the variable; however,
+if some frame already has a value for @var{variable} as a frame
+parameter, that value automatically becomes a frame-local binding.
+
+If the variable is terminal-local, this function signals an error.  Such
+variables cannot have buffer-local bindings as well.  @xref{Multiple
+Displays}.  A few variables that are implemented specially in Emacs
+can be (and usually are) buffer-local, but can never be frame-local.
+@end defun
+
+  Buffer-local bindings take precedence over frame-local bindings.  Thus,
+consider a variable @code{foo}: if the current buffer has a buffer-local
+binding for @code{foo}, that binding is active; otherwise, if the
+selected frame has a frame-local binding for @code{foo}, that binding is
+active; otherwise, the default binding of @code{foo} is active.
+
+  Here is an example.  First we prepare a few bindings for @code{foo}:
+
+@example
+(setq f1 (selected-frame))
+(make-variable-frame-local 'foo)
+
+;; @r{Make a buffer-local binding for @code{foo} in @samp{b1}.}
+(set-buffer (get-buffer-create "b1"))
+(make-local-variable 'foo)
+(setq foo '(b 1))
+
+;; @r{Make a frame-local binding for @code{foo} in a new frame.}
+;; @r{Store that frame in @code{f2}.}
+(setq f2 (make-frame))
+(modify-frame-parameters f2 '((foo . (f 2))))
+@end example
+
+  Now we examine @code{foo} in various contexts.  Whenever the
+buffer @samp{b1} is current, its buffer-local binding is in effect,
+regardless of the selected frame:
+
+@example
+(select-frame f1)
+(set-buffer (get-buffer-create "b1"))
+foo
+     @result{} (b 1)
+
+(select-frame f2)
+(set-buffer (get-buffer-create "b1"))
+foo
+     @result{} (b 1)
+@end example
+
+@noindent
+Otherwise, the frame gets a chance to provide the binding; when frame
+@code{f2} is selected, its frame-local binding is in effect:
+
+@example
+(select-frame f2)
+(set-buffer (get-buffer "*scratch*"))
+foo
+     @result{} (f 2)
+@end example
+
+@noindent
+When neither the current buffer nor the selected frame provides
+a binding, the default binding is used:
+
+@example
+(select-frame f1)
+(set-buffer (get-buffer "*scratch*"))
+foo
+     @result{} nil
+@end example
+
+@noindent
+When the active binding of a variable is a frame-local binding, setting
+the variable changes that binding.  You can observe the result with
+@code{frame-parameters}:
+
+@example
+(select-frame f2)
+(set-buffer (get-buffer "*scratch*"))
+(setq foo 'nobody)
+(assq 'foo (frame-parameters f2))
+     @result{} (foo . nobody)
+@end example
+
+@node Future Local Variables
+@section Possible Future Local Variables
+
+  We have considered the idea of bindings that are local to a category
+of frames---for example, all color frames, or all frames with dark
+backgrounds.  We have not implemented them because it is not clear that
+this feature is really useful.  You can get more or less the same
+results by adding a function to @code{after-make-frame-hook}, set up to
+define a particular frame parameter according to the appropriate
+conditions for each frame.
+
+  It would also be possible to implement window-local bindings.  We
+don't know of many situations where they would be useful, and it seems
+that indirect buffers (@pxref{Indirect Buffers}) with buffer-local
+bindings offer a way to handle these situations more robustly.
+
+  If sufficient application is found for either of these two kinds of
+local bindings, we will provide it in a subsequent Emacs version.
+
+
diff --git a/lispref/windows.texi b/lispref/windows.texi
index 6e983113f51..9199ff0f8d2 100644
--- a/lispref/windows.texi
+++ b/lispref/windows.texi
@@ -246,7 +246,7 @@ Now, the screen looks like this:
 @end smallexample
 
 Normally, Emacs indicates the border between two side-by-side windows
-with a scroll bar (@pxref{X Frame Parameters,Scroll Bars}) or @samp{|}
+with a scroll bar (@pxref{Window Frame Parameters,Scroll Bars}) or @samp{|}
 characters.  The display table can specify alternative border
 characters; see @ref{Display Tables}.
 @end deffn
@@ -328,8 +328,7 @@ of a window aside from restoring a saved window configuration
 deletes any windows that aren't part of that configuration.
 
   When you delete a window, the space it took up is given to one
-adjacent sibling.  (In Emacs version 18, the space was divided evenly
-among all the siblings.)
+adjacent sibling.
 
 @c Emacs 19 feature
 @defun window-live-p window
@@ -341,14 +340,10 @@ using a deleted window as if it were live.
 @end defun
 
 @deffn Command delete-window &optional window
-This function removes @var{window} from the display.  If @var{window}
-is omitted, then the selected window is deleted.  An error is signaled
-if there is only one window when @code{delete-window} is called.
-
-This function returns @code{nil}.
-
-When @code{delete-window} is called interactively, @var{window}
-defaults to the selected window.
+This function removes @var{window} from display, and returns @code{nil}.
+If @var{window} is omitted, then the selected window is deleted.  An
+error is signaled if there is only one window when @code{delete-window}
+is called.
 @end deffn
 
 @deffn Command delete-other-windows &optional window
@@ -356,7 +351,7 @@ This function makes @var{window} the only window on its frame, by
 deleting the other windows in that frame.  If @var{window} is omitted or
 @code{nil}, then the selected window is used by default.
 
-The result is @code{nil}.
+The return value is @code{nil}.
 @end deffn
 
 @deffn Command delete-windows-on buffer &optional frame
@@ -426,7 +421,7 @@ or contents of windows; therefore, if the @var{forms} change them,
 the change persists.
 
 Each frame, at any time, has a window selected within the frame.  This
-macro only saves @emph{the} selected window; it does not save anything
+macro saves only @emph{the} selected window; it does not save anything
 about other frames.  If the @var{forms} select some other frame and
 alter the window selected within it, the change persists.
 @end defmac
@@ -565,8 +560,8 @@ include in the cycle, as in @code{next-window}.
 
 @deffn Command other-window count
 This function selects the @var{count}th following window in the cyclic
-order.  If count is negative, then it selects the @minus{}@var{count}th
-preceding window.  It returns @code{nil}.
+order.  If count is negative, then it moves back @minus{}@var{count}
+windows in the cycle, rather than forward.  It returns @code{nil}.
 
 In an interactive call, @var{count} is the numeric prefix argument.
 @end deffn
@@ -695,7 +690,7 @@ low-level functions that give you more precise control.
   Do not use the functions in this section in order to make a buffer
 current so that a Lisp program can access or modify it; they are too
 drastic for that purpose, since they change the display of buffers in
-windows, which is gratuitous and will surprise the user.  Instead, use
+windows, which would be gratuitous and surprise the user.  Instead, use
 @code{set-buffer} (@pxref{Current Buffer}) and @code{save-excursion}
 (@pxref{Excursions}), which designate buffers as current for programmed
 access without affecting the display of buffers in windows.
@@ -713,8 +708,9 @@ buffer by that name is created.  The major mode for the new buffer is
 set according to the variable @code{default-major-mode}.  @xref{Auto
 Major Mode}.
 
-Normally the specified buffer is put at the front of the buffer list.
-This affects the operation of @code{other-buffer}.  However, if
+Normally the specified buffer is put at the front of the buffer list
+(both the selected frame's buffer list and the frame-independent buffer
+list).  This affects the operation of @code{other-buffer}.  However, if
 @var{norecord} is non-@code{nil}, this is not done.  @xref{The Buffer
 List}.
 
@@ -792,7 +788,7 @@ This function returns @code{nil}.
 
 @tindex buffer-display-count
 @defvar buffer-display-count
-This variable is always local in each buffer.  When the buffer is
+This variable is always buffer-local in each buffer.  When the buffer is
 created, @code{buffer-display-count} has value 0.  Each time the buffer
 is displayed in a window, that increments the value of
 @code{buffer-display-count}.
@@ -965,7 +961,8 @@ described above.
 @c Emacs 19 feature
 @cindex dedicated window
 A window can be marked as ``dedicated'' to its buffer.  Then
-@code{display-buffer} does not try to use that window.
+@code{display-buffer} will not try to use that window to display any
+other buffer.
 
 @defun window-dedicated-p window
 This function returns @code{t} if @var{window} is marked as dedicated;
@@ -1069,32 +1066,23 @@ For a realistic example of using @code{window-start}, see the
 description of @code{count-lines} in @ref{Text Lines}.
 @end defun
 
-@defun window-end &optional window
+@defun window-end &optional window update
 This function returns the position of the end of the display in window
 @var{window}.  If @var{window} is @code{nil}, the selected window is
 used.
 
 Simply changing the buffer text or moving point does not update the
 value that @code{window-end} returns.  The value is updated only when
-Emacs redisplays and redisplay actually finishes.
+Emacs redisplays and redisplay completes without being preempted.
 
 If the last redisplay of @var{window} was preempted, and did not finish,
 Emacs does not know the position of the end of display in that window.
-In that case, this function returns a value that is not correct.  In a
-future version, @code{window-end} will return @code{nil} in that case.
-@ignore
-in that case, this function returns @code{nil}.  You can compute where
-the end of the window @emph{would} have been, if redisplay had finished,
-like this:
+In that case, this function returns @code{nil}.
 
-@example
-(save-excursion
-  (goto-char (window-start window))
-  (vertical-motion (1- (window-height window))
-                   window)
-  (point))
-@end example
-@end ignore
+If you @var{update} is non-@code{nil}, @code{window-end} always returns
+an up-to-date value for where the window ends.  If the saved value is
+valid, @code{window-end} returns that; otherwise it computes the correct
+value by scanning the buffer text.
 @end defun
 
 @defun set-window-start window position &optional noforce
@@ -1428,10 +1416,10 @@ characters that separates side-by-side windows.
   The following three functions return size information about a window:
 
 @defun window-height &optional window
-This function returns the number of lines in @var{window}, including
-its mode line.  If @var{window} fills its entire frame, this is one less
-than the value of @code{frame-height} on that frame (since the last line
-is always reserved for the minibuffer).
+This function returns the number of lines in @var{window}, including its
+mode line.  If @var{window} fills its entire frame, this is typically
+one less than the value of @code{frame-height} on that frame (since the
+last line is always reserved for the minibuffer).
 
 If @var{window} is @code{nil}, the function uses the selected window.
 
@@ -1654,16 +1642,9 @@ If you omit @var{frame}, the selected frame is used.
 This function checks whether a particular frame position falls within
 the window @var{window}.
 
-@need 3000
-The argument @var{coordinates} is a cons cell of this form:
-
-@example
-(@var{x} . @var{y})
-@end example
-
-@noindent
-The coordinates @var{x} and @var{y} are measured in characters, and
-count from the top left corner of the screen or frame.
+The argument @var{coordinates} is a cons cell of the form @code{(@var{x}
+. @var{y})}.  The coordinates @var{x} and @var{y} are measured in
+characters, and count from the top left corner of the screen or frame.
 
 The value returned by @code{coordinates-in-window-p} is non-@code{nil}
 if the coordinates are inside @var{window}.  The value also indicates
@@ -1713,7 +1694,9 @@ This function returns a new object representing the selected frame's
 current window configuration, including the number of windows, their
 sizes and current buffers, which window is the selected window, and for
 each window the displayed buffer, the display-start position, and the
-positions of point and the mark.  An exception is made for point in the
+positions of point and the mark.  It also includes the values of
+@code{window-min-height}, @code{window-min-width} and
+@code{minibuffer-scroll-window}.  An exception is made for point in the
 current buffer, whose value is not saved.
 @end defun
 
@@ -1721,14 +1704,17 @@ current buffer, whose value is not saved.
 This function restores the configuration of windows and buffers as
 specified by @var{configuration}.  The argument @var{configuration} must
 be a value that was previously returned by
-@code{current-window-configuration}.  This function operates on the
-frame for which @var{configuration} was made, whether that frame is
-selected or not.
-
-This function always counts as a window size change and triggers
-execution of the @code{window-size-change-functions}.  (It doesn't know
-how to tell whether the new configuration actually differs from the old
-one.)
+@code{current-window-configuration}.  This configuration is restored in
+the frame from which @var{configuration} was made, whether that frame is
+selected or not.  This always counts as a window size change and
+triggers execution of the @code{window-size-change-functions}
+(@pxref{Window Hooks}), because @code{set-window-configuration} doesn't
+know how to tell whether the new configuration actually differs from the
+old one.
+
+If the frame which @var{configuration} was saved from is dead, all this
+function does is restore the three variables @code{window-min-height},
+@code{window-min-width} and @code{minibuffer-scroll-window}.
 
 Here is a way of using this function to get the same effect
 as @code{save-window-excursion}:
@@ -1786,6 +1772,17 @@ For example:
 This function returns @code{t} if @var{object} is a window configuration.
 @end defun
 
+@defun compare-window-configurations config1 config2
+This function compares two window configurations as regards the
+structure of windows, but ignores the values of point and mark and the
+saved scrolling positions---it can return @code{t} even if those
+aspects differ.
+
+The function @code{equal} can also compare two window configurations; it
+regards configurations as unequal if they differ in any respect, even a
+saved point or mark.
+@end defun
+
   Primitives to look inside of window configurations would make sense,
 but none are implemented.  It is not clear they are useful enough to be
 worth implementing.
@@ -1799,8 +1796,8 @@ There are three actions that can change this: scrolling the window,
 switching buffers in the window, and changing the size of the window.
 The first two actions run @code{window-scroll-functions}; the last runs
 @code{window-size-change-functions}.  The paradigmatic use of these
-hooks is Lazy Lock mode; see @ref{Support Modes, Lazy Lock, Font Lock
-Support Modes, emacs, The GNU Emacs Manual}.
+hooks is in the implementation of Lazy Lock mode; see @ref{Support
+Modes, Lazy Lock, Font Lock Support Modes, emacs, The GNU Emacs Manual}.
 
 @defvar window-scroll-functions
 This variable holds a list of functions that Emacs should call before