*** empty log message ***

42 files changed, 3884 insertions, 1477 deletions

diff --git a/lispref/abbrevs.texi b/lispref/abbrevs.texi
index 674082b6289..52847bf320a 100644
--- a/lispref/abbrevs.texi
+++ b/lispref/abbrevs.texi
@@ -4,7 +4,7 @@
 @c See the file elisp.texi for copying conditions.
 @setfilename ../info/abbrevs
 @node Abbrevs, Processes, Syntax Tables, Top
-@chapter Abbrevs And Abbrev Expansion
+@chapter Abbrevs and Abbrev Expansion
 @cindex abbrev
 @cindex abbrev table
 
diff --git a/lispref/advice.texi b/lispref/advice.texi
index 1d3d4e0e46f..6ff93495447 100644
--- a/lispref/advice.texi
+++ b/lispref/advice.texi
@@ -174,6 +174,9 @@ actually called.  If more than one piece of advice specifies an argument
 list, then the first one (the one with the smallest position) found in
 the list of all classes of advice is used.
 
+@xref{Argument Access in Advice}, for more information about argument
+lists and advice.
+
 The remaining elements, @var{flags}, are symbols that specify further
 information about how to use this piece of advice.  Here are the valid
 symbols and their meanings:
@@ -210,7 +213,7 @@ unless subsequently explicitly enabled.  @xref{Enabling Advice}.
 Activate advice for @var{function} when this @code{defadvice} is
 compiled or macroexpanded.  This generates a compiled advised definition
 according to the current advice state, which will be used during
-activation if appropriate.
+activation if appropriate.  @xref{Preactivation}.
 
 This is useful only if this @code{defadvice} is byte-compiled.
 @end table
@@ -301,7 +304,9 @@ specified @var{class}, then @var{position} specifies where in the list
 to put the new piece of advice.  The value of @var{position} can either
 be @code{first}, @code{last}, or a number (counting from 0 at the
 beginning of the list).  Numbers outside the range are mapped to the
-closest extreme position.
+beginning or the end of the range, whichever is closer.  The
+@var{position} value is ignored when redefining an existing piece of
+advice.
 
 If @var{function} already has a piece of @var{advice} with the same
 name, then the position argument is ignored and the old advice is
@@ -339,7 +344,7 @@ the command also compiles the combined definition which implements the
 advice.
 
 @deffn Command ad-activate function &optional compile
-This command activates the advice for @var{function}.
+This command activates all the advice defined for @var{function}.
 @end deffn
 
 To activate advice for a function whose advice is already active is not
diff --git a/lispref/anti.texi b/lispref/anti.texi
index d9873088f17..1b9fa426d86 100644
--- a/lispref/anti.texi
+++ b/lispref/anti.texi
@@ -1,248 +1,226 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1998 Free Software Foundation, Inc. 
+@c Copyright (C) 1999 Free Software Foundation, Inc. 
 @c See the file elisp.texi for copying conditions.
 @node Antinews, Index, Standard Hooks, Top
-@appendix Emacs 19 Antinews
+@appendix Emacs 20 Antinews
 
 For those users who live backwards in time, here is information about
-downgrading to Emacs version 19.34.  We hope you will enjoy the greater
-simplicity that results from the absence of many Emacs 20 features.  In
-the following section, we carry this information back as far as Emacs
-19.29, for which the previous printed edition of this manual was made.
+downgrading to Emacs version 20.4.  We hope you will enjoy the greater
+simplicity that results from the absence of many Emacs 21 features.  In
+the following section, we carry this information back to Emacs
+20.3, for which the previous printed edition of this manual was made.
 
-@section Old Lisp Features in Emacs 19
-
-Here are the most important of the features that you will learn
-to do without in Emacs 19:
+@section Old Lisp Features in Emacs 20
 
 @itemize @bullet
 @item
-In a great simplification, Emacs 19 supports ASCII characters only.
-There are no multibyte characters, character sets, language
-environments, coding systems, or input methods; all the functions that
-specifically relate to them are gone as well.
-
-Valid character codes for text must be in the range 0 through 255.
-Within this range, there are no invalid character codes.
+The @code{push} and @code{pop} macros are not defined.
 
 @item
-The Custom facility has been replaced with a much simpler and more
-general method of defining user option variables.  Instead of
-@code{defcustom}, which requires you to specify each user option's data
-type and classify options into groups, all you have to do is write a
-@code{defvar}.  You should still start the documentation string with
-@samp{*}, though.
-@end itemize
-
-Here are changes in the Lisp language itself:
+You can't display images in buffers.  (Emacs is meant for editing text.)
+With no images, there are no display margins, and no tool bars.
 
-@itemize @bullet
 @item
-Symbols whose names start with @samp{:} are no longer special
-in any way.  They start out void, like most other symbols.
+The @code{display} text property has no special meaning; you can use it
+freely in Lisp programs, with no effects except what you implement for
+yourself.  With no images, who needs the @code{display} text property?
 
 @item
-The macros @code{when} and @code{unless} have been deleted.
+Faces have fewer attributes.  The attributes @code{:family},
+@code{:height}, @code{:width}, @code{:weight}, and @code{:slant},
+have been replaced with a font name, a ``bold'' flag, and an
+``italic'' flag.
 
-@item
-The functions @code{caar}, @code{cadr}, @code{cdar} and @code{cddr}
-no longer exist.
+The attributes @code{:overline}, @code{:strike-through}
+and @code{:box} have been eliminated too.
 
-@item
-The function @code{functionp} is now gone.  If you don't know
-by now whether something is a function, Emacs can't tell you.
-@end itemize
+With fewer font attributes, there are no functions
+@code{set-face-attribute} and @code{face-attribute}.  Instead, you
+access these attributes using functions such as @code{face-font}, and
+set them with functions such as @code{set-face-font}.  (These functions
+were available in Emacs 21, but are not as useful there.)
 
-Here are changes in handling strings and text.
+@item
+There are no facilities for playing sound.  This means Emacs will
+respect your peace and quiet, aside from occasional beeps.
 
-@itemize @bullet
 @item
-The function @code{substring} works only on strings, not on vectors.
+Regular expressions do not support the POSIX character classes
+such as @samp{[:alpha:]}.  All characters are created equal.
 
 @item
-There are no more character categories.
+Hash tables have been eliminated; use alists instead.
 
 @item
-When you compare strings with @code{equal}, it now compares
-their string properties as well as their text.  All must match,
-or the strings are not equal.
+The Lisp printer does not detect and report circular structure.  That is
+ok, because the Lisp reader cannot recreate circular structure anyway.
+However, there is a library @samp{cust-print.el} which can report
+circular structure.
 
 @item
-@code{format-time-string} no longer supports specified field width
-or specified padding.
+Emacs provides its own implementation of scroll bars, instead
+of using those of the X toolkit.  They always use the frame foreground
+and background colors, so you cannot specify different colors for
+the scroll bars.
 
 @item
-The functions @code{split-string} and @code{string} no longer exist.
-Neither does @code{store-substring} or @code{sref}.
+For simplicity, all ASCII characters now have the same height and width.
+(Certain characters, such as Chinese characters, always have have twice
+the standard width.)  All characters are created equal.
 
 @item
-All printing characters have the same width.  Therefore, we have deleted
-@code{char-width}, @code{string-width} and
-@code{truncate-string-to-width}.
+Tooltips operate using ordinary Emacs frames.
 
 @item
-We have eliminated the functions @code{next-char-property-change} and
-@code{previous-char-property-change} also.
+Areas of the mode line are not mouse-sensitive; however, some mouse
+commands are available for the mode line as a whole.
 
 @item
-Syntax parsing now determines the syntax of each character from the
-syntax table alone---not from text properties.  This makes the syntax
-codes @samp{|} and @samp{!}, which were meant for use with text
-properties, useless; so we have deleted them.
+Windows cannot have header lines.  Conversely, there is no way to turn
+off the mode line of a window unless it is a minibuffer.
 
 @item
-In the function @code{parse-partial-sexp}, passing @code{syntax-table}
-as the sixth argument @var{commentstop} no longer has any special meaning.
-And the return value has only eight elements.
-@end itemize
+Plain dashes are the only separators you can use in a menu.
 
-Here are changes in other areas of Emacs Lisp:
+@item
+Vertical fractional scrolling does not exist.
 
-@itemize @bullet
 @item
-The macros @code{save-current-buffer}, @code{with-current-buffer},
-@code{with-temp-buffer}, @code{with-temp-file}, @code{save-selected-window}, 
-and @code{with-output-to-string} are gone.
+The functions @code{format} and @code{message} ignore and discard text
+properties.
 
 @item
-The easy-mmode facility for defining minor modes is gone too.
+Colors are supported only on window systems, not on text-only terminals.
+So the support functions for colors on text-only terminals are
+not needed.
 
 @item
-Process filters and sentinels must explicitly save the match data, with
-@code{save-match-data}, or they will clobber the match data and
-something horrible will happen.
+The functions @code{color-values}, @code{color-defined-p} and
+@code{defined-colors} have been renamed to @code{x-color-values},
+@code{x-color-defined-p} and @code{x-defined-colors}.
 
 @item
-As part of our effort to loosen up, @code{batch-byte-compile-file} no
-longer returns a nonzero status code if there is a compilation error.
+Windows cannot be made fixed-width or fixed-height;
+Emacs will adjust the size of all windows when it needs to.
 
 @item
-The ``mail user agent'' feature is gone.
+The minibuffer prompt does not actually appear in content of the
+minibuffer; it is displayed specially in the minibuffer window.
 
 @item
-We have removed the functions @code{add-to-invisibility-spec} and
-@code{remove-from-invisibility-spec}, so you should manipulate
-the value of @code{buffer-invisibility-spec} by hand.
+The ``exclusive open'' feature of @code{write-region}
+has been eliminated; any non-@code{nil} value for the seventh
+argument now means to ask the user for confirmation.
 
 @item
-The functions @code{face-documentation}, @code{face-bold-p},
-@code{face-italic-p}, @code{set-face-bold-p}, @code{set-face-italic-p}
-are gone.  Instead, use @code{make-face-bold} and friends.
+The function @code{buffer-size} always reports on the
+current buffer.
 
 @item
-All the functions that operate on a file now discard an extra redundant
-directory name from the beginning of the file name---just like
-@code{substitute-in-file-name}.
+The function @code{assoc-delete-all} has itself been deleted. 
+So there!
 
 @item
-We have got rid of the function @code{access-file}.
+The variable @code{small-temporary-file-directory} has no special
+meaning.  There's only one variable for specifying which directory to
+use for temporary files, @code{temporary-file-directory}, but not all
+Emacs features use it anyway.  Some use the @code{TMP} environment
+variable, and some use the @code{TMPDIR} environment variable.
 
 @item
-Most of the minibuffer input functions no longer take a default value as
-an argument.  Also, they do not discard text properties from the result.
-This means that if you insert text with text properties into the minibuffer,
-the minibuffer value really will contain text properties.
+The variable  @code{inhibit-modification-hooks}
+has no special meaning.
 
 @item
-Only the simple menu item format is supported (@pxref{Simple Menu Items}).
+The hook @code{fontification-functions} has been eliminated,
+but there are other hooks, such as @code{window-scroll-functions},
+that you can use to do a similar job.
 
 @item
-You can still bind @code{x-resource-class} around a call to
-@code{x-get-resource}, but it won't do anything special.
+The variable  @code{redisplay-dont-pause}
+has no special meaning.
 
 @item
-Wave goodbye to the hooks @code{before-make-frame-hook},
-@code{after-make-frame-functions}, and
-@code{window-configuration-change-hook},
+The hook @code{calendar-move-hook} has been deleted.
 
 @item
-The functions and variables that deal with MS Windows NT/95
-have been renamed to start with @samp{win32-} instead of @samp{w32-}.
-This is because we admire Microsoft more each day as we go back
-into the past.
+The function @code{move-to-column} treats any non-@code{nil}
+second argument just like @code{t}.
 @end itemize
 
-@section Onward into the Past!
+@section Old Lisp Features in Emacs 20.3
 
-Here we go even further back, as far as Emacs 19.29, for which the
-previous printed edition of the Emacs Lisp manual was made.
+Here are the most important of the features that you will learn
+to do without in Emacs 20.3:
 
-@itemize @bullet
-@item
-There are no char-tables or bool-vectors.  Syntax tables, display
-tables, and case tables are all vectors now, and the value of
-@code{keyboard-translate-table} should be a vector or a string.
+Here are changes in the Lisp language itself:
 
+@itemize @bullet
 @item
-There is only one kind of marker.  When you insert text at the place
-where a marker points, the marker always ends up before that text,
-unless you use @code{insert-before-markers}, which puts all the markers
-after the inserted text.
+The functions @code{line-beginning-position} and @code{line-end-position}
+have been eliminated.
 
 @item
-There is no function @code{overlays-in}.
+The functions @code{directory-files-and-attributes},
+@code{file-attributes-lessp}, and @code{file-expand-wildcards}, have
+been eliminated.
 
 @item
-The variable @code{print-length} applies only to lists, not to
-vectors or strings.
+The functions @code{decode-coding-region} and @code{encode-coding-region}
+leave text properties untouched, in case that is useful.  (It rarely makes
+any sense, though.)
 
 @item
-The function @code{convert-standard-filename} no longer exists, so each
-Lisp package must independently figure out which file names to use for
-its initialization files on each kind of operating system.
+The functions @code{position-bytes} and @code{byte-to-position} have
+been eliminated.
 
 @item
-The macro @code{with-timeout} has been eliminated, along with the
-function @code{y-or-n-p-with-timeout}.  Idle timers don't exist at all;
-instead, maybe you can use @code{post-command-idle-hook} to do some of
-the same job.
+Temporary buffers made with @code{with-output-to-temp-buffer} are now
+modifiable by default, and use Fundamental mode rather than Help mode.
 
 @item
-The functions @code{keymap-parent} and @code{set-keymap-parent} are
-gone.  We expect keymaps to recognize their own parents.
+The functions @code{sref} interprets its @var{index} argument as a
+number of bytes, not a number of characters.  And the function
+@code{char-bytes} actually tries to report on the number of bytes that a
+character occupies.
 
 @item
-When you delete text and then undo a deletion, markers that were
-originally inside the deleted text end up either at the beginning
-or the end of it---not back in their original places.
+The function @code{process-running-child-p} has been eliminated.
 
 @item
-The interactive specification @samp{N} is gone now.
+The function @code{interrupt-process} and similar functions no longer do
+anything special when the second argument is @code{lambda}.
 
 @item
-There is no more @code{safe-length}.  Don't try to be so safe!  Did you
-expect to live forever?
+The function @code{define-prefix-command} accepts only two arguments.
 
 @item
-We got rid of @code{insert-file-contents-literally}, because
-programmers are too literal-minded anyway.
+The meaning of the second argument to @code{read-char},
+@code{read-event}, and @code{read-char-exclusive} has been reversed:
+they use the current input method if the argument is if @code{nil}.
 
 @item
-As part of our continuing effort to help Lisp programmers to relax, we
-threw out the function @code{error-message-string}.  Don't worry so much
-about errors!  We all make mistakes.
+The function @code{with-temp-message} has been eliminated. 
 
 @item
-The keymap @code{special-event-map} is gone, because Emacs has no more
-special events.  If you want to hold a party in Emacs, please let us
-know.
+The function @code{clear-this-command-keys} has been eliminated. 
 
 @item
-You can't do date arithmetic with @code{encode-time} any more.
+The functions @code{gap-position} and @code{gap-size} have been eliminated. 
 
 @item
-The functions @code{command-execute} and @code{call-interactively} no
-longer accept the optional argument @var{keys}.
+In @code{modify-face}, an argument of @code{(nil)} has no special
+meaning.
 
 @item
-@code{get-buffer-window-list} is gone as well.
+The base64 conversion functions have been eliminated.
 
 @item
-With the function @code{replace-match}, you can only replace the whole
-match, not a subexpression of it.
+Wildcard support has been eliminated from @code{find-file}
+and allied functions.
 
 @item
-We eliminated the hooks @code{buffer-access-fontify-functions},
-@code{window-scroll-functions}, and @code{redisplay-end-trigger-functions}.
+@code{file-attributes} returns the file size and the file inode number
+only as a simple integer.
 @end itemize
diff --git a/lispref/backups.texi b/lispref/backups.texi
index f81caa58649..3ff74a50bb1 100644
--- a/lispref/backups.texi
+++ b/lispref/backups.texi
@@ -179,6 +179,19 @@ This variable is significant only if @code{backup-by-copying} is
 non-@code{nil}.
 @end defvar
 
+@defvar backup-by-copying-when-privileged-mismatch
+This variable, if non-@code{nil}, specifies the same behavior as
+@code{backup-by-copying-when-mismatch}, but only for certain user-id
+values: namely, those less than or equal to a certain number.  You set
+this variable to that number.
+
+Thus, if you set @code{backup-by-copying-when-privileged-mismatch}
+to 0, backup by copying is done for the superuser only,
+when necessary to prevent a change in the owner of the file.
+
+The default is 200.
+@end defvar
+
 @node Numbered Backups
 @subsection Making and Deleting Numbered Backup Files
 
@@ -393,8 +406,8 @@ integer.  Otherwise, it turns auto-saving off.
 
 @defun auto-save-file-name-p filename
 This function returns a non-@code{nil} value if @var{filename} is a
-string that could be the name of an auto-save file.  It works based on
-knowledge of the naming convention for auto-save files: a name that
+string that could be the name of an auto-save file.  It assumes
+the usual naming convention for auto-save files: a name that
 begins and ends with hash marks (@samp{#}) is a possible auto-save file
 name.  The argument @var{filename} should not contain a directory part.
 
@@ -433,8 +446,8 @@ correspondingly.
 This function returns the file name to use for auto-saving the current
 buffer.  This is just the file name with hash marks (@samp{#}) prepended
 and appended to it.  This function does not look at the variable
-@code{auto-save-visited-file-name} (described below); you should check
-that before calling this function.
+@code{auto-save-visited-file-name} (described below); callers of this
+function should check that variable first.
 
 @example
 @group
@@ -475,10 +488,11 @@ file that you are editing.  Normally, this variable is @code{nil}, so
 auto-save files have distinct names that are created by
 @code{make-auto-save-file-name}.
 
-When you change the value of this variable, the value does not take
-effect until the next time auto-save mode is reenabled in any given
-buffer.  If auto-save mode is already enabled, auto-saves continue to go
-in the same file name until @code{auto-save-mode} is called again.
+When you change the value of this variable, the new value does not take
+effect in an existing buffer until the next time auto-save mode is
+reenabled in it.  If auto-save mode is already enabled, auto-saves
+continue to go in the same file name until @code{auto-save-mode} is
+called again.
 @end defvar
 
 @defun recent-auto-save-p
@@ -493,18 +507,18 @@ function returns @code{nil}.
 @end defun
 
 @defopt auto-save-interval
-The value of this variable is the number of characters that Emacs
-reads from the keyboard between auto-saves.  Each time this many more
-characters are read, auto-saving is done for all buffers in which it is
+The value of this variable specifies how often to do auto-saving, in
+terms of number of input events.  Each time this many additional input
+events are read, Emacs does auto-saving for all buffers in which that is
 enabled.
 @end defopt
 
 @defopt auto-save-timeout
 The value of this variable is the number of seconds of idle time that
 should cause auto-saving.  Each time the user pauses for this long,
-Emacs auto-saves any buffers that need it.  (Actually, the specified
-timeout is multiplied by a factor depending on the size of the current
-buffer.)
+Emacs does auto-saving for all buffers in which that is enabled.
+(Actually, the specified timeout is multiplied by a factor depending on
+the size of the current buffer.)
 @end defopt
 
 @defvar auto-save-hook
@@ -552,14 +566,15 @@ nothing.
 
 @defvar buffer-saved-size
 The value of this buffer-local variable is the length of the current
-buffer as of the last time it was read in, saved, or auto-saved.  This is
+buffer, when it was last 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 @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.
+If it is @minus{}1, that means auto-saving is temporarily shut off in
+this buffer due to a substantial decrease in size.  Explicitly saving
+the buffer stores a positive value in this variable, thus reenabling
+auto-saving.  Turning auto-save mode off or on also updates this
+variable, so that the substantial decrease in size is forgotten.
 @end defvar
 
 @defvar auto-save-list-file-name
@@ -570,14 +585,14 @@ enabled.  The first line gives the name of the visited file (it's empty
 if the buffer has none), and the second gives the name of the auto-save
 file.
 
-If Emacs exits normally, it deletes this file.  If Emacs crashes, you
+When Emacs exits normally, it deletes this file; if Emacs crashes, you
 can look in the file to find all the auto-save files that might contain
 work that was otherwise lost.  The @code{recover-session} command uses
-these files.
+this file to find them.
 
-The default name for this file is in your home directory and starts with
-@samp{.saves-}.  It also contains the Emacs process @sc{id} and the host
-name.
+The default name for this file specifies your home directory and starts
+with @samp{.saves-}.  It also contains the Emacs process @sc{id} and the
+host name.
 @end defvar
 
 @node Reverting
@@ -594,10 +609,10 @@ file on disk.  This action undoes all changes since the file was visited
 or saved.
 
 By default, if the latest auto-save file is more recent than the visited
-file, @code{revert-buffer} asks the user whether to use that instead.
-But if the argument @var{ignore-auto} is non-@code{nil}, then only the
-the visited file itself is used.  Interactively, @var{ignore-auto} is
-@code{t} unless there is a numeric prefix argument; thus, the
+file, and the argument @var{ignore-auto} is non-@code{nil},
+@code{revert-buffer} asks the user whether to use that auto-save
+instead.  When you invoke this command interactively, @var{ignore-auto}
+is @code{t} unless there is a numeric prefix argument; thus, the
 interactive default is to check the auto-save file.
 
 Normally, @code{revert-buffer} asks for confirmation before it changes
@@ -608,9 +623,9 @@ Reverting tries to preserve marker positions in the buffer by using the
 replacement feature of @code{insert-file-contents}.  If the buffer
 contents and the file contents are identical before the revert
 operation, reverting preserves all the markers.  If they are not
-identical, reverting does change the buffer; then it preserves the
-markers in the unchanged text (if any) at the beginning and end of the
-buffer.  Preserving any additional markers would be problematical.
+identical, reverting does change the buffer; in that case, it preserves
+the markers in the unchanged text (if any) at the beginning and end of
+the buffer.  Preserving any additional markers would be problematical.
 @end deffn
 
 You can customize how @code{revert-buffer} does its work by setting
@@ -618,10 +633,10 @@ these variables---typically, as buffer-local variables.
 
 @defvar revert-without-query
 This variable holds a list of files that should be reverted without
-query.  The value is a list of regular expressions.  If a file name
-matches one of these regular expressions, then @code{revert-buffer}
-reverts the file without asking the user for confirmation, if the file
-has changed on disk and the buffer is not modified.
+query.  The value is a list of regular expressions.  If the visited file
+name matches one of these regular expressions, and the file has changed
+on disk but the buffer is not modified, then @code{revert-buffer}
+reverts the file without asking the user for confirmation.
 @end defvar
 
 @defvar revert-buffer-function
@@ -637,20 +652,20 @@ regenerate the contents.
 @end defvar
 
 @defvar revert-buffer-insert-file-contents-function
-The value of this variable, if non-@code{nil}, is the function to use to
+The value of this variable, if non-@code{nil}, specifies the function to use to
 insert the updated contents when reverting this buffer.  The function
 receives two arguments: first the file name to use; second, @code{t} if
 the user has asked to read the auto-save file.
 @end defvar
 
 @defvar before-revert-hook
-This normal hook is run by @code{revert-buffer} before actually
+This normal hook is run by @code{revert-buffer} before
 inserting the modified contents---but only if
 @code{revert-buffer-function} is @code{nil}.
 @end defvar
 
 @defvar after-revert-hook
-This normal hook is run by @code{revert-buffer} after actually inserting
+This normal hook is run by @code{revert-buffer} after inserting
 the modified contents---but only if @code{revert-buffer-function} is
 @code{nil}.
 @end defvar
diff --git a/lispref/buffers.texi b/lispref/buffers.texi
index f05d242ef1a..670b147a3b8 100644
--- a/lispref/buffers.texi
+++ b/lispref/buffers.texi
@@ -10,7 +10,7 @@
   A @dfn{buffer} is a Lisp object containing text to be edited.  Buffers
 are used to hold the contents of files that are being visited; there may
 also be buffers that are not visiting files.  While several buffers may
-exist at one time, exactly one buffer is designated the @dfn{current
+exist at one time, only one buffer is designated the @dfn{current
 buffer} at any time.  Most editing commands act on the contents of the
 current buffer.  Each buffer, including the current buffer, may or may
 not be displayed in any windows.
@@ -18,7 +18,7 @@ not be displayed in any windows.
 @menu
 * Buffer Basics::       What is a buffer?
 * Current Buffer::      Designating a buffer as current
-                          so primitives will access its contents.
+                          so that primitives will access its contents.
 * Buffer Names::        Accessing and changing buffer names.
 * Buffer File Name::    The buffer file name indicates which file is visited.
 * Buffer Modification:: A buffer is @dfn{modified} if it needs to be saved.
@@ -39,8 +39,8 @@ not be displayed in any windows.
 @ifinfo
   A @dfn{buffer} is a Lisp object containing text to be edited.  Buffers
 are used to hold the contents of files that are being visited; there may
-also be buffers that are not visiting files.  While several buffers may
-exist at one time, exactly one buffer is designated the @dfn{current
+also be buffers that are not visiting files.  Although several buffers
+normally exist, only one buffer is designated the @dfn{current
 buffer} at any time.  Most editing commands act on the contents of the
 current buffer.  Each buffer, including the current buffer, may or may
 not be displayed in any windows.
@@ -103,12 +103,12 @@ current, to prevent confusion: the buffer that the cursor is in when
 Emacs reads a command is the buffer that the command will apply to.
 (@xref{Command Loop}.)  Therefore, @code{set-buffer} is not the way to
 switch visibly to a different buffer so that the user can edit it.  For
-this, you must use the functions described in @ref{Displaying Buffers}.
+that, you must use the functions described in @ref{Displaying Buffers}.
 
-  However, Lisp functions that change to a different current buffer
+  @strong{Note:} Lisp functions that change to a different current buffer
 should not depend on the command loop to set it back afterwards.
 Editing commands written in Emacs Lisp can be called from other programs
-as well as from the command loop.  It is convenient for the caller if
+as well as from the command loop; it is convenient for the caller if
 the subroutine does not change which buffer is current (unless, of
 course, that is the subroutine's purpose).  Therefore, you should
 normally use @code{set-buffer} within a @code{save-current-buffer} or
@@ -153,9 +153,9 @@ binding.  Otherwise, use @code{save-current-buffer} or
 @code{save-excursion} to make sure that the buffer current at the
 beginning is current again whenever the variable is unbound.
 
-  It is not reliable to change the current buffer back with
-@code{set-buffer}, because that won't do the job if a quit happens while
-the wrong buffer is current.  Here is what @emph{not} to do:
+  Do not rely on using @code{set-buffer} to change the current buffer
+back, because that won't do the job if a quit happens while the wrong
+buffer is current.  Here is what @emph{not} to do:
 
 @example
 @group
@@ -192,10 +192,9 @@ This function returns the current buffer.
 @end defun
 
 @defun set-buffer buffer-or-name
-This function makes @var{buffer-or-name} the current buffer.  It does
-not display the buffer in the currently selected window or in any other
-window, so the user cannot necessarily see the buffer.  But Lisp
-programs can in any case work on it.
+This function makes @var{buffer-or-name} the current buffer.  This does
+not display the buffer in any window, so the user cannot necessarily see
+the buffer.  But Lisp programs will now operate on it.
 
 This function returns the buffer identified by @var{buffer-or-name}.
 An error is signaled if @var{buffer-or-name} does not identify an
@@ -302,18 +301,15 @@ Ordinarily, @code{rename-buffer} signals an error if @var{newname} is
 already in use.  However, if @var{unique} is non-@code{nil}, it modifies
 @var{newname} to make a name that is not in use.  Interactively, you can
 make @var{unique} non-@code{nil} with a numeric prefix argument.
-
-One application of this command is to rename the @samp{*shell*} buffer
-to some other name, thus making it possible to create a second shell
-buffer under the name @samp{*shell*}.
+(This is how the command @code{rename-uniquely} is implemented.)
 @end deffn
 
 @defun get-buffer buffer-or-name
 This function returns the buffer specified by @var{buffer-or-name}.
 If @var{buffer-or-name} is a string and there is no buffer with that
 name, the value is @code{nil}.  If @var{buffer-or-name} is a buffer, it
-is returned as given.  (That is not very useful, so the argument is usually 
-a name.)  For example:
+is returned as given; that is not very useful, so the argument is usually 
+a name.  For example:
 
 @example
 @group
@@ -374,7 +370,7 @@ supplied, it defaults to the current buffer.
 @defvar buffer-file-name
 This buffer-local variable contains the name of the file being visited
 in the current buffer, or @code{nil} if it is not visiting a file.  It
-is a permanent local, unaffected by @code{kill-local-variables}.
+is a permanent local variable, unaffected by @code{kill-local-variables}.
 
 @example
 @group
@@ -621,7 +617,7 @@ the read-only flag with @kbd{C-x C-q}.
 
 @item
 Modes such as Dired and Rmail make buffers read-only when altering the
-contents with the usual editing commands is probably a mistake.
+contents with the usual editing commands would probably be a mistake.
 
 The special commands of these modes bind @code{buffer-read-only} to
 @code{nil} (with @code{let}) or bind @code{inhibit-read-only} to
@@ -649,7 +645,7 @@ of the list (comparison is done with @code{eq}).
 
 @deffn Command toggle-read-only
 This command changes whether the current buffer is read-only.  It is
-intended for interactive use; don't use it in programs.  At any given
+intended for interactive use; do not use it in programs.  At any given
 point in a program, you should know whether you want the read-only flag
 on or off; so you can set @code{buffer-read-only} explicitly to the
 proper value, @code{t} or @code{nil}.
@@ -857,8 +853,8 @@ text space available for other use.
   The buffer object for the buffer that has been killed remains in
 existence as long as anything refers to it, but it is specially marked
 so that you cannot make it current or display it.  Killed buffers retain
-their identity, however; two distinct buffers, when killed, remain
-distinct according to @code{eq}.
+their identity, however; if you kill two distinct buffers, they remain
+distinct according to @code{eq} although both are dead.
 
   If you kill a buffer that is current or displayed in a window, Emacs
 automatically selects or displays some other buffer instead.  This means
@@ -916,9 +912,9 @@ Buffer foo.changed modified; kill anyway? (yes or no) @kbd{yes}
 After confirming unsaved changes, @code{kill-buffer} calls the functions
 in the list @code{kill-buffer-query-functions}, in order of appearance,
 with no arguments.  The buffer being killed is the current buffer when
-they are called.  The idea is that these functions ask for confirmation
-from the user for various nonstandard reasons.  If any of them returns
-@code{nil}, @code{kill-buffer} spares the buffer's life.
+they are called.  The idea of this feature is that these functions will
+ask for confirmation from the user.  If any of them returns @code{nil},
+@code{kill-buffer} spares the buffer's life.
 @end defvar
 
 @defvar kill-buffer-hook
@@ -951,7 +947,7 @@ base buffer; changes made by editing either one are visible immediately
 in the other.  This includes the text properties as well as the characters
 themselves.
 
-  But in all other respects, the indirect buffer and its base buffer are
+  In all other respects, the indirect buffer and its base buffer are
 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
@@ -959,8 +955,8 @@ overlays for both), different major modes, and different buffer-local
 variables.
 
   An indirect buffer cannot visit a file, but its base buffer can.  If
-you try to save the indirect buffer, that actually works by saving the
-base buffer.
+you try to save the indirect buffer, that actually saves the base
+buffer.
 
   Killing an indirect buffer has no effect on its base buffer.  Killing
 the base buffer effectively kills the indirect buffer in that it cannot
diff --git a/lispref/calendar.texi b/lispref/calendar.texi
index ad521822e88..30718d2902c 100644
--- a/lispref/calendar.texi
+++ b/lispref/calendar.texi
@@ -117,6 +117,10 @@ terminal.
   A similar normal hook, @code{today-invisible-calendar-hook} is run if
 the current date is @emph{not} visible in the window.
 
+@vindex calendar-move-hook
+  Starting in Emacs 21, each of the calendar cursor motion commands
+runs the hook @code{calendar-move-hook} after it moves the cursor.
+
 @node Holiday Customizing
 @section Customizing the Holidays
 
@@ -776,7 +780,7 @@ can use
 @noindent
 and the fancy diary will show
 @smallexample
-Ruth & Ed's anniversary
+Ed's anniversary
 @end smallexample
 @noindent
 both on December 15 and on December 22.
diff --git a/lispref/commands.texi b/lispref/commands.texi
index cf64fc3abb0..f5e4f90f357 100644
--- a/lispref/commands.texi
+++ b/lispref/commands.texi
@@ -322,7 +322,7 @@ You can use @samp{e} more than once in a single command's interactive
 specification.  If the key sequence that invoked the command has
 @var{n} events that are lists, the @var{n}th @samp{e} provides the
 @var{n}th such event.  Events that are not lists, such as function keys
-and @sc{ASCII} characters, do not count where @samp{e} is concerned.
+and @sc{ascii} characters, do not count where @samp{e} is concerned.
 
 @item f
 A file name of an existing file (@pxref{File Names}).  The default
@@ -760,7 +760,7 @@ last-command-event
 @end example
 
 @noindent
-The value is 5 because that is the @sc{ASCII} code for @kbd{C-e}.
+The value is 5 because that is the @sc{ascii} code for @kbd{C-e}.
 
 The alias @code{last-command-char} exists for compatibility with
 Emacs version 18.
@@ -834,7 +834,7 @@ An input character event consists of a @dfn{basic code} between 0 and
 @item meta
 The
 @tex
-$2^{27}$
+@math{2^{27}}
 @end tex
 @ifinfo
 2**27
@@ -845,57 +845,57 @@ typed with the meta key held down.
 @item control
 The
 @tex
-$2^{26}$
+@math{2^{26}}
 @end tex
 @ifinfo
 2**26
 @end ifinfo
-bit in the character code indicates a non-@sc{ASCII}
+bit in the character code indicates a non-@sc{ascii}
 control character.
 
-@sc{ASCII} control characters such as @kbd{C-a} have special basic
+@sc{ascii} control characters such as @kbd{C-a} have special basic
 codes of their own, so Emacs needs no special bit to indicate them.
 Thus, the code for @kbd{C-a} is just 1.
 
-But if you type a control combination not in @sc{ASCII}, such as
+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
 @tex
-$2^{26}$
+@math{2^{26}}
 @end tex
 @ifinfo
 2**26
 @end ifinfo
-(assuming the terminal supports non-@sc{ASCII}
+(assuming the terminal supports non-@sc{ascii}
 control characters).
 
 @item shift
 The
 @tex
-$2^{25}$
+@math{2^{25}}
 @end tex
 @ifinfo
 2**25
 @end ifinfo
-bit in the character code indicates an @sc{ASCII} control
+bit in the character code indicates an @sc{ascii} control
 character typed with the shift key held down.
 
 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
+@sc{ascii} character set whenever possible, Emacs avoids using the
 @tex
-$2^{25}$
+@math{2^{25}}
 @end tex
 @ifinfo
 2**25
 @end ifinfo
 bit for those characters.
 
-However, @sc{ASCII} provides no way to distinguish @kbd{C-A} from
+However, @sc{ascii} provides no way to distinguish @kbd{C-A} from
 @kbd{C-a}, so Emacs uses the
 @tex
-$2^{25}$
+@math{2^{25}}
 @end tex
 @ifinfo
 2**25
@@ -906,7 +906,7 @@ bit in @kbd{C-A} and not in
 @item hyper
 The
 @tex
-$2^{24}$
+@math{2^{24}}
 @end tex
 @ifinfo
 2**24
@@ -917,7 +917,7 @@ typed with the hyper key held down.
 @item super
 The
 @tex
-$2^{23}$
+@math{2^{23}}
 @end tex
 @ifinfo
 2**23
@@ -928,7 +928,7 @@ typed with the super key held down.
 @item alt
 The
 @tex
-$2^{22}$
+@math{2^{22}}
 @end tex
 @ifinfo
 2**22
@@ -966,10 +966,10 @@ function keys:
 
 @table @asis
 @item @code{backspace}, @code{tab}, @code{newline}, @code{return}, @code{delete}
-These keys correspond to common @sc{ASCII} control characters that have
+These keys correspond to common @sc{ascii} control characters that have
 special keys on most keyboards.
 
-In @sc{ASCII}, @kbd{C-i} and @key{TAB} are the same character.  If the
+In @sc{ascii}, @kbd{C-i} and @key{TAB} are the same character.  If the
 terminal can distinguish between them, Emacs conveys the distinction to
 Lisp programs by representing the former as the integer 9, and the
 latter as the symbol @code{tab}.
@@ -981,7 +981,7 @@ character @kbd{C-i}) also applies to @code{tab}.  Likewise for the other
 symbols in this group.  The function @code{read-char} likewise converts
 these events into characters.
 
-In @sc{ASCII}, @key{BS} is really @kbd{C-h}.  But @code{backspace}
+In @sc{ascii}, @key{BS} is really @kbd{C-h}.  But @code{backspace}
 converts into the character code 127 (@key{DEL}), not into code 8
 (@key{BS}).  This is what most users prefer.
 
@@ -1657,7 +1657,7 @@ 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}$
+@math{2^{27}}
 @end tex
 @ifinfo
 2**27
@@ -1677,14 +1677,14 @@ in the string unchanged.
 @item
 The meta variants of those characters, with codes in the range of
 @tex
-$2^{27}$
+@math{2^{27}}
 @end tex
 @ifinfo
 2**27
 @end ifinfo
 to
 @tex
-$2^{27} + 127$,
+@math{2^{27} + 127},
 @end tex
 @ifinfo
 2**27+127,
@@ -1692,14 +1692,14 @@ $2^{27} + 127$,
 can also go in the string, but you must change their
 numeric values.  You must set the
 @tex
-$2^{7}$
+@math{2^{7}}
 @end tex
 @ifinfo
 2**7
 @end ifinfo
 bit instead of the
 @tex
-$2^{27}$
+@math{2^{27}}
 @end tex
 @ifinfo
 2**27
@@ -1708,7 +1708,7 @@ 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.
+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
@@ -1869,7 +1869,7 @@ Echo Area}.
 
 If @var{inherit-input-method} is non-@code{nil}, then the current input
 method (if any) is employed to make it possible to enter a
-non-@sc{ASCII} character.  Otherwise, input method handling is disabled
+non-@sc{ascii} character.  Otherwise, input method handling is disabled
 for reading this event.
 
 If @code{cursor-in-echo-area} is non-@code{nil}, then @code{read-event}
@@ -1899,7 +1899,7 @@ user generates an event which is not a character (i.e. a mouse click or
 function key event), @code{read-char} signals an error.  The arguments
 work as in @code{read-event}.
 
-In the first example, the user types the character @kbd{1} (@sc{ASCII}
+In the first example, the user types the character @kbd{1} (@sc{ascii}
 code 49).  The second example shows a keyboard macro definition that
 calls @code{read-char} from the minibuffer using @code{eval-expression}.
 @code{read-char} reads the keyboard macro's very next character, which
@@ -2078,7 +2078,7 @@ This variable records the last terminal input event read, whether
 as part of a command or explicitly by a Lisp program.
 
 In the example below, the Lisp program reads the character @kbd{1},
-@sc{ASCII} code 49.  It becomes the value of @code{last-input-event},
+@sc{ascii} code 49.  It becomes the value of @code{last-input-event},
 while @kbd{C-e} (we assume @kbd{C-x C-e} command is used to evaluate
 this expression) remains the value of @code{last-command-event}.
 
@@ -2171,12 +2171,8 @@ period measured in milliseconds.  This adds to the period specified by
 @var{seconds}.  If the system doesn't support waiting fractions of a
 second, you get an error if you specify nonzero @var{millisec}.
 
-@cindex forcing redisplay
-Redisplay is always preempted if input arrives, and does not happen at
-all if input is available before it starts.  Thus, there is no way to
-force screen updating if there is pending input; however, if there is no
-input pending, you can force an update with no delay by using
-@code{(sit-for 0)}.
+The expression @code{(sit-for 0)} is a convenient way to request a
+redisplay, without any delay.  @xref{Forcing Redisplay}.
 
 If @var{nodisp} is non-@code{nil}, then @code{sit-for} does not
 redisplay, but it still returns as soon as input is available (or when
diff --git a/lispref/control.texi b/lispref/control.texi
index 2925201285b..1d79fc83316 100644
--- a/lispref/control.texi
+++ b/lispref/control.texi
@@ -20,8 +20,8 @@ write several forms in succession in the body of a function, or at top
 level in a file of Lisp code---the forms are executed in the order
 written.  We call this @dfn{textual order}.  For example, if a function
 body consists of two forms @var{a} and @var{b}, evaluation of the
-function evaluates first @var{a} and then @var{b}, and the function's
-value is the value of @var{b}.
+function evaluates first @var{a} and then @var{b}.  The result of
+evaluating @var{b} becomes the value of the function.
 
   Explicit control structures make possible an order of execution other
 than sequential.
@@ -60,9 +60,9 @@ control construct of Lisp.
 
 @noindent
 and it says to execute the forms @var{a}, @var{b}, @var{c}, and so on, in
-that order.  These forms are called the body of the @code{progn} form.
+that order.  These forms are called the @dfn{body} of the @code{progn} form.
 The value of the last form in the body becomes the value of the entire
-@code{progn}.
+@code{progn}.  @code{(progn)} returns @code{nil}.
 
 @cindex implicit @code{progn}
   In the early days of Lisp, @code{progn} was the only way to execute
@@ -72,8 +72,8 @@ body of a function, where (at that time) only one form was allowed.  So
 the body of a function was made into an ``implicit @code{progn}'':
 several forms are allowed just as in the body of an actual @code{progn}.
 Many other control structures likewise contain an implicit @code{progn}.
-As a result, @code{progn} is not used as often as it used to be.  It is
-needed now most often inside an @code{unwind-protect}, @code{and},
+As a result, @code{progn} is not used as much as it was many years ago.
+It is needed now most often inside an @code{unwind-protect}, @code{and},
 @code{or}, or in the @var{then}-part of an @code{if}.
 
 @defspec progn forms@dots{}
@@ -265,6 +265,7 @@ For example,
 
 @example
 @group
+(setq a 5)
 (cond ((eq a 'hack) 'foo)
       (t "default"))
 @result{} "default"
@@ -272,8 +273,8 @@ For example,
 @end example
 
 @noindent
-This expression is a @code{cond} which returns @code{foo} if the value
-of @code{a} is @code{hack}, and returns the string @code{"default"} otherwise.
+This @code{cond} expression returns @code{foo} if the value of @code{a}
+is @code{hack}, and returns the string @code{"default"} otherwise.
 @end defspec
 
 Any conditional construct can be expressed with @code{cond} or with
@@ -310,11 +311,14 @@ order written.
 
 If any of the @var{conditions} evaluates to @code{nil}, then the result
 of the @code{and} must be @code{nil} regardless of the remaining
-@var{conditions}; so @code{and} returns right away, ignoring the
-remaining @var{conditions}.
+@var{conditions}; so @code{and} returns @code{nil} right away, ignoring
+the remaining @var{conditions}.
 
 If all the @var{conditions} turn out non-@code{nil}, then the value of
-the last of them becomes the value of the @code{and} form.
+the last of them becomes the value of the @code{and} form.  Just
+@code{(and)}, with no @var{conditions}, returns @code{t}, appropriate
+because all the @var{conditions} turned out non-@code{nil}.  (Think
+about it; which one did not?)
 
 Here is an example.  The first condition returns the integer 1, which is
 not @code{nil}.  Similarly, the second condition returns the integer 2,
@@ -368,10 +372,13 @@ right away, ignoring the remaining @var{conditions}.  The value it
 returns is the non-@code{nil} value of the condition just evaluated.
 
 If all the @var{conditions} turn out @code{nil}, then the @code{or}
-expression returns @code{nil}.
+expression returns @code{nil}.  Just @code{(or)}, with no
+@var{conditions}, returns @code{nil}, appropriate because all the
+@var{conditions} turned out @code{nil}.  (Think about it; which one
+did not?)
 
-For example, this expression tests whether @code{x} is either 0 or
-@code{nil}:
+For example, this expression tests whether @code{x} is either 
+@code{nil} or the integer zero:
 
 @example
 (or (eq x nil) (eq x 0))
@@ -446,9 +453,10 @@ The value of a @code{while} form is always @code{nil}.
 @end group
 @end example
 
-If you would like to execute something on each iteration before the
-end-test, put it together with the end-test in a @code{progn} as the
-first argument of @code{while}, as shown here:
+To write a ``repeat...until'' loop, which will execute something on each
+iteration and then do the end-test, put the body followed by the
+end-test in a @code{progn} as the first argument of @code{while}, as
+shown here:
 
 @example
 @group
@@ -560,9 +568,10 @@ With the return point in effect, @code{catch} evaluates the forms of the
 error or nonlocal exit) the value of the last body form is returned from
 the @code{catch}.
 
-If a @code{throw} is done within @var{body} specifying the same value
-@var{tag}, the @code{catch} exits immediately; the value it returns is
-whatever was specified as the second argument of @code{throw}.
+If a @code{throw} is executed during the execution of @var{body},
+specifying the same value @var{tag}, the @code{catch} form exits
+immediately; the value it returns is whatever was specified as the
+second argument of @code{throw}.
 @end defspec
 
 @defun throw tag value
@@ -641,13 +650,6 @@ printed.  Finally the second body form in the outer @code{catch}, which is
 
 @example
 @group
-(defun catch2 (tag)
-  (catch tag
-    (throw 'hack 'yes)))
-@result{} catch2
-@end group
-
-@group
 (catch 'hack
   (print (catch2 'quux))
   'no)
@@ -709,6 +711,11 @@ buffer.  You can also signal errors explicitly with the functions
 considered an error, but it is handled almost like an error.
 @xref{Quitting}.
 
+  The error message should state what is wrong (``File does not
+exist''), not how things ought to be (``File must exist'').  The
+convention in Emacs Lisp is that error messages should start with a
+capital letter, but should not end with any sort of punctuation.
+
 @defun error format-string &rest args
 This function signals an error with an error message constructed by
 applying @code{format} (@pxref{String Conversion}) to
@@ -852,7 +859,7 @@ above, there is one handler, and it specifies one condition name,
   The search for an applicable handler checks all the established handlers
 starting with the most recently established one.  Thus, if two nested
 @code{condition-case} forms offer to handle the same error, the inner of
-the two will actually handle it.
+the two gets to handle it.
 
   If an error is handled by some @code{condition-case} form, this
 ordinarily prevents the debugger from being run, even if
@@ -881,10 +888,11 @@ totally unpredictable, such as when the program evaluates an expression
 read from the user.
 
   Error signaling and handling have some resemblance to @code{throw} and
-@code{catch}, but they are entirely separate facilities.  An error
-cannot be caught by a @code{catch}, and a @code{throw} cannot be handled
-by an error handler (though using @code{throw} when there is no suitable
-@code{catch} signals an error that can be handled).
+@code{catch} (@pxref{Catch and Throw}), but they are entirely separate
+facilities.  An error cannot be caught by a @code{catch}, and a
+@code{throw} cannot be handled by an error handler (though using
+@code{throw} when there is no suitable @code{catch} signals an error
+that can be handled).
 
 @defspec condition-case var protected-form handlers@dots{}
 This special form establishes the error handlers @var{handlers} around
@@ -1127,9 +1135,9 @@ the value of the last @var{body} form, after it evaluates the
 @var{cleanup-forms}.  If the @var{body} forms do not finish,
 @code{unwind-protect} does not return any value in the normal sense.
 
-Only the @var{body} is actually protected by the @code{unwind-protect}.
-If any of the @var{cleanup-forms} themselves exits nonlocally (e.g., via
-a @code{throw} or an error), @code{unwind-protect} is @emph{not}
+Only the @var{body} is protected by the @code{unwind-protect}.  If any
+of the @var{cleanup-forms} themselves exits nonlocally (via a
+@code{throw} or an error), @code{unwind-protect} is @emph{not}
 guaranteed to evaluate the rest of them.  If the failure of one of the
 @var{cleanup-forms} has the potential to cause trouble, then protect it
 with another @code{unwind-protect} around that form.
@@ -1167,13 +1175,13 @@ 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
-creates a process (@pxref{Processes}) to try to establish a connection
-to a remote machine.  As the function @code{ftp-login} is highly
-susceptible to numerous problems that the writer of the function cannot
-anticipate, it is protected with a form that guarantees deletion of the
-process in the event of failure.  Otherwise, Emacs might fill up with
-useless subprocesses.
+  Here is an actual example derived from an FTP package.  It creates a
+process (@pxref{Processes}) to try to establish a connection to a remote
+machine.  As the function @code{ftp-login} is highly susceptible to
+numerous problems that the writer of the function cannot anticipate, it
+is protected with a form that guarantees deletion of the process in the
+event of failure.  Otherwise, Emacs might fill up with useless
+subprocesses.
 
 @smallexample
 @group
@@ -1188,7 +1196,7 @@ useless subprocesses.
 @end group
 @end smallexample
 
-  This example actually has a small bug: if the user types @kbd{C-g} to
+  This example has a small bug: if the user types @kbd{C-g} to
 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,
diff --git a/lispref/customize.texi b/lispref/customize.texi
index 51ed4e0d526..ff5f724cd74 100644
--- a/lispref/customize.texi
+++ b/lispref/customize.texi
@@ -19,7 +19,7 @@ definitions---as well as face definitions (@pxref{Defining Faces}).
 @end menu
 
 @node Common Keywords
-@section Common Keywords for All Kinds of Items
+@section Common Item Keywords
 
   All kinds of customization declarations (for variables and groups, and
 for faces) accept keyword arguments for specifying various information.
@@ -31,8 +31,8 @@ The keyword @code{:tag} is an exception because any given item can only
 display one name.
 
 @table @code
-@item :tag @var{name}
-Use @var{name}, a string, instead of the item's name, to label the item
+@item :tag @var{label}
+Use @var{label}, a string, instead of the item's name, to label the item
 in customization menus and buffers.
 
 @item :group @var{group}
@@ -42,7 +42,7 @@ Put this customization item in group @var{group}.  When you use
 
 If you use this keyword more than once, you can put a single item into
 more than one group.  Displaying any of those groups will show this
-item.  Be careful not to overdo this!
+item.  Please don't overdo this, since the result would be annoying.
 
 @item :link @var{link-data}
 Include an external link after the documentation string for this item.
@@ -113,7 +113,8 @@ keyword.
 @tindex defgroup
 Declare @var{group} as a customization group containing @var{members}.
 Do not quote the symbol @var{group}.  The argument @var{doc} specifies
-the documentation string for the group.
+the documentation string for the group.  It should not start with a
+@samp{*} as in @code{defcustom}; that convention is for variables only.
 
 The argument @var{members} is a list specifying an initial set of
 customization items to be members of the group.  However, most often
@@ -165,12 +166,20 @@ turn this feature back on, if someone would like to do the work.
 @tindex defcustom
 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.
+string for the variable; it should normally start with a @samp{*}.  This
+marks the variable, for other purposes, as one that users may want to
+customize.
 
 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 evaluated on more
 than one occasion.
+
+When you evaluate a @code{defcustom} form with @kbd{C-M-x} in Emacs Lisp
+mode (@code{eval-defun}), a special feature of @code{eval-defun}
+arranges to set the variable unconditionally, without testing whether
+its value is void.  (The same feature applies to @code{defvar}.)
+@xref{Defining Variables}.
 @end defmac
 
   @code{defcustom} accepts the following additional keywords:
@@ -277,7 +286,8 @@ options for @code{emacs-lisp-mode-hook}, but not by editing its
 definition.   You can do it thus:
 
 @example
-(custom-add-option 'emacs-lisp-mode-hook 'my-lisp-mode-initialization)
+(custom-add-option 'emacs-lisp-mode-hook
+                   'my-lisp-mode-initialization)
 @end example
 
 @defun custom-add-option symbol option
@@ -392,10 +402,9 @@ edit both the key and the value of each pair.
 
 You can specify the key and value types like this:
 
-@example
-(alist :key-type @var{key-type}
-       :value-type @var{value-type})
-@end example
+@smallexample
+(alist :key-type @var{key-type} :value-type @var{value-type})
+@end smallexample
 
 @noindent
 where @var{key-type} and @var{value-type} are customization type
@@ -414,9 +423,9 @@ The argument to the @code{:options} keywords should be a list of option
 specifications.  Ordinarily, the options are simply atoms, which are the
 specified keys.  For example:
 
-@example
+@smallexample
 :options '("foo" "bar" "baz")
-@end example
+@end smallexample
 
 @noindent
 specifies that there are three ``known'' keys, namely @code{"foo"},
@@ -428,9 +437,9 @@ You can specify this by using a list instead of an atom in the option
 specification.  The first element will specify the key, like before,
 while the second element will specify the value type.
 
-@example
+@smallexample
 :options '("foo" ("bar" integer) "baz")
-@end example
+@end smallexample
 
 Finally, you may want to change how the key is presented.  By default,
 the key is simply shown as a @code{const}, since the user cannot change
@@ -440,36 +449,36 @@ you may want to use a more specialized type for presenting the key, like
 This is done by using a customization type specification instead of a
 symbol for the key.
 
-@example
+@smallexample
 :options '("foo" ((function-item some-function) integer) "baz")
-@end example
+@end smallexample
 
 Many alists use lists with two elements, instead of cons cells.  For
 example,
 
-@example
+@smallexample
 (defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3))
   "Each element is a list of the form (KEY VALUE).")
-@end example
+@end smallexample
 
 @noindent
 instead of 
 
-@example
+@smallexample
 (defcustom cons-alist '(("foo" . 1) ("bar" . 2) ("baz" . 3))
   "Each element is a cons-cell (KEY . VALUE).")
-@end example
+@end smallexample
 
 Because of the way lists are implemented on top of cons cells, you can
 treat @code{list-alist} in the example above as a cons cell alist, where
 the value type is a list with a single element containing the real
 value.
 
-@example
+@smallexample
 (defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3))
   "Each element is a list of the form (KEY VALUE)."
   :type '(alist :value-type (group integer)))
-@end example
+@end smallexample
 
 The @code{group} widget is used here instead of @code{list} only because
 the formatting is better suited for the purpose.
@@ -477,7 +486,7 @@ the formatting is better suited for the purpose.
 Similarily, you can have alists with more values associated with each
 key, using variations of this trick:
 
-@example
+@smallexample
 (defcustom person-data '(("brian"  50 t) 
                          ("dorith" 55 nil)
                          ("ken"    52 t))
@@ -489,16 +498,16 @@ key, using variations of this trick:
                   ("ken" "cat"))
   "Alist where the KEY is a person, and the VALUE is a list of pets."
   :type '(alist :value-type (repeat string)))
-@end example
+@end smallexample
 
 @item plist
 The @code{plist} custom type is similar to the @code{alist} (see above),
 except that the information is stored as a property list, i.e. a list of
 this form:
 
-@example
+@smallexample
 (@var{key} @var{value} @var{key} @var{value} @var{key} @var{value} @dots{})
-@end example
+@end smallexample
 
 The default @code{:key-type} for @code{plist} is @code{symbol},
 rather than @code{sexp}.
diff --git a/lispref/debugging.texi b/lispref/debugging.texi
index 4bc3d07d69b..8946cf0baab 100644
--- a/lispref/debugging.texi
+++ b/lispref/debugging.texi
@@ -510,9 +510,9 @@ debugger.
 
 @defvar debugger
 The value of this variable is the function to call to invoke the
-debugger.  Its value must be a function of any number of arguments (or,
-more typically, the name of a function).  Presumably this function will
-enter some kind of debugger.  The default value of the variable is
+debugger.  Its value must be a function of any number of arguments, or,
+more typically, the name of a function.  This function should invoke
+some kind of debugger.  The default value of the variable is
 @code{debug}.
 
 The first argument that Lisp hands to the function indicates why it
@@ -531,11 +531,13 @@ value is always @code{nil}.
 
 In the following example, a Lisp expression calls @code{backtrace}
 explicitly.  This prints the backtrace to the stream
-@code{standard-output}: in this case, to the buffer
-@samp{backtrace-output}.  Each line of the backtrace represents one
-function call.  The line shows the values of the function's arguments if
-they are all known.  If they are still being computed, the line says so.
-The arguments of special forms are elided.
+@code{standard-output}, which, in this case, is the buffer
+@samp{backtrace-output}.
+
+Each line of the backtrace represents one function call.  The line shows
+the values of the function's arguments if they are all known; if they
+are still being computed, the line says so.  The arguments of special
+forms are elided.
 
 @smallexample
 @group
@@ -620,9 +622,9 @@ 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 an
-ordinary global variable is that the data will never carry over to a
-subsequent command invocation.
+The advantage 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
 
 @defun backtrace-frame frame-number
@@ -630,11 +632,11 @@ The function @code{backtrace-frame} is intended for use in Lisp
 debuggers.  It returns information about what computation is happening
 in the stack frame @var{frame-number} levels down.
 
-If that frame has not evaluated the arguments yet (or is a special
-form), the value is @code{(nil @var{function} @var{arg-forms}@dots{})}.
+If that frame has not evaluated the arguments yet, or is a special
+form, the value is @code{(nil @var{function} @var{arg-forms}@dots{})}.
 
 If that frame has evaluated its arguments and called its function
-already, the value is @code{(t @var{function}
+already, the return value is @code{(t @var{function}
 @var{arg-values}@dots{})}.
 
 In the return value, @var{function} is whatever was supplied as the
@@ -679,12 +681,9 @@ find the mismatch.)
 @subsection Excess Open Parentheses
 
   The first step is to find the defun that is unbalanced.  If there is
-an excess open parenthesis, the way to do this is to insert a
-close parenthesis at the end of the file and type @kbd{C-M-b}
-(@code{backward-sexp}).  This will move you to the beginning of the
-defun that is unbalanced.  (Then type @kbd{C-@key{SPC} C-_ C-u
-C-@key{SPC}} to set the mark there, undo the insertion of the
-close parenthesis, and finally return to the mark.)
+an excess open parenthesis, the way to do this is to go to the end of
+the file and type @kbd{C-u C-M-u}.  This will move you to the beginning
+of the defun that is unbalanced.
 
   The next step is to determine precisely what is wrong.  There is no
 way to be sure of this except by studying the program, but often the
@@ -715,11 +714,9 @@ anything.
 @node Excess Close
 @subsection Excess Close Parentheses
 
-  To deal with an excess close parenthesis, first insert an open
-parenthesis at the beginning of the file, back up over it, and type
-@kbd{C-M-f} to find the end of the unbalanced defun.  (Then type
-@kbd{C-@key{SPC} C-_ C-u C-@key{SPC}} to set the mark there, undo the
-insertion of the open parenthesis, and finally return to the mark.)
+  To deal with an excess close parenthesis, first go to the beginning of
+the file, then type @kbd{C-u -1 C-M-u} to find the end of the unbalanced
+defun.
 
   Then find the actual matching close parenthesis by typing @kbd{C-M-f}
 at the beginning of that defun.  This will leave you somewhere short of
diff --git a/lispref/display.texi b/lispref/display.texi
index 1ada1dbd373..2f9cb0c9bdc 100644
--- a/lispref/display.texi
+++ b/lispref/display.texi
@@ -11,6 +11,7 @@ that Emacs presents to the user.
 
 @menu
 * Refresh Screen::      Clearing the screen and redrawing everything on it.
+* Forcing Redisplay::   Forcing redisplay.
 * Truncation::          Folding or wrapping long text lines.
 * The Echo Area::       Where messages are displayed.
 * Invisible Text::      Hiding part of the buffer text.
@@ -20,6 +21,8 @@ that Emacs presents to the user.
 * Overlays::            Use overlays to highlight parts of the buffer.
 * Width::               How wide is a character or string.
 * Faces::               A face defines a graphics appearance: font, color, etc.
+* Display Property::    Enabling special display features.
+* Images::              Displaying images in Emacs buffers.
 * Blinking::            How Emacs shows the matching open parenthesis.
 * Inverse Video::       Specifying how the screen looks.
 * Usual Display::       The usual conventions for displaying nonprinting chars.
@@ -64,6 +67,32 @@ has been suspended and resumed.  Non-@code{nil} means there is no need
 to redraw, @code{nil} means redrawing is needed.  The default is @code{nil}.
 @end defvar
 
+@node Forcing Redisplay
+@section Forcing Redisplay
+@cindex forcing redisplay
+
+  Emacs redisplay normally stops if input arrives, and does not happen
+at all if input is available before it starts.  Most of the time, this
+is exactly what you want.  However, you can prevent preemption by
+binding @code{redisplay-dont-pause} to a non-@code{nil} value.
+
+@tindex redisplay-dont-pause
+@defvar redisplay-dont-pause
+If this variable is non-@code{nil}, pending input does not
+prevent or halt redisplay; redisplay occurs, and finishes,
+regardless of whether input is available.  This feature is available
+as of Emacs 21.
+@end defvar
+
+  You can request a display update, but only if no input is pending,
+with @code{(sit-for 0)}.  To force a display update even when input is
+pending, do this:
+
+@example
+(let ((redisplay-dont-pause t))
+  (sit-for 0))
+@end example
+
 @node Truncation
 @section Truncation
 @cindex line wrapping
@@ -158,10 +187,14 @@ constructed string.
 In batch mode, @code{message} prints the message text on the standard
 error stream, followed by a newline.
 
+If @var{string}, or strings among the @var{arguments}, have @code{face}
+text properties, these affect the way the message is displayed.
+
 @c Emacs 19 feature
-If @var{string} is @code{nil}, @code{message} clears the echo area.  If
-the minibuffer is active, this brings the minibuffer contents back onto
-the screen immediately.
+If @var{string} is @code{nil}, @code{message} clears the echo area; if
+the echo area has been expanded automatically, this brings it back to
+its normal size.  If the minibuffer is active, this brings the
+minibuffer contents back onto the screen immediately.
 
 @example
 @group
@@ -682,7 +715,7 @@ these affect the display of the text within the overlay.
 @node Overlay Properties
 @subsection Overlay Properties
 
-Overlay properties are like text properties in that the properties that
+  Overlay properties are like text properties in that the properties that
 alter how a character is displayed can come from either source.  But in
 most respects they are different.  Text properties are considered a part
 of the text; overlays are specifically considered not to be part of the
@@ -693,6 +726,29 @@ overlay or changing its properties does not.  Unlike text property
 changes, overlay changes are not recorded in the buffer's undo list.
 @xref{Text Properties}, for comparison.
 
+  These functions are used for reading and writing the properties of an
+overlay:
+
+@defun overlay-get overlay prop
+This function returns the value of property @var{prop} recorded in
+@var{overlay}, if any.  If @var{overlay} does not record any value for
+that property, but it does have a @code{category} property which is a
+symbol, that symbol's @var{prop} property is used.  Otherwise, the value
+is @code{nil}.
+@end defun
+
+@defun overlay-put overlay prop value
+This function sets the value of property @var{prop} recorded in
+@var{overlay} to @var{value}.  It returns @var{value}.
+@end defun
+
+  See also the function @code{get-char-property} which checks both
+overlay properties and text properties for a given character.
+@xref{Examining Properties}.
+
+  Many overlay properties have special meanings; here is a table
+of them:
+
 @table @code
 @item priority
 @kindex priority @r{(overlay property)}
@@ -721,20 +777,51 @@ of the symbol serve as defaults for the properties of the overlay.
 @item face
 @kindex face @r{(overlay property)}
 This property controls the way text is displayed---for example, which
-font and which colors.  Its value is a face name or a list of face
-names.  @xref{Faces}, for more information.
+font and which colors.  @xref{Faces}, for more information.
 
-If the property value is a list, elements may also have the form
-@code{(foreground-color . @var{color-name})} or @code{(background-color
-. @var{color-name})}.  These elements specify just the foreground color
-or just the background color; therefore, there is no need to create a
-face for each color that you want to use.
+In the simplest case, the value is a face name.  It can also be a list;
+then each element can be any of these possibilities;
+
+@itemize @bullet
+@item
+A face name (a symbol or string).
+
+@item
+Starting in Emacs 21, a property list of face attributes.  This has the
+form (@var{keyword} @var{value} @dots{}), where each @var{keyword} is a
+face attribute name and @var{value} is a meaningful value for that
+attribute.  With this feature, you do not need to create a face each
+time you want to specify a particular attribute for certain text.
+@xref{Face Attributes}.
+
+@item
+A cons cell of the form @code{(foreground-color . @var{color-name})} or
+@code{(background-color . @var{color-name})}.  These elements specify
+just the foreground color or just the background color.
+
+@code{(foreground-color . @var{color-name})} is equivalent to
+@code{(:foreground @var{color-name})}, and likewise for the background.
+@end itemize
 
 @item mouse-face
 @kindex mouse-face @r{(overlay property)}
 This property is used instead of @code{face} when the mouse is within
 the range of the overlay.
 
+@item display
+@kindex display @r{(overlay property)}
+This property activates various features that change the
+way text is displayed.  For example, it can make text appear taller
+or shorter, higher or lower, wider or narror, or replaced with an image.
+@xref{Display Property}.
+
+@item help-echo
+@kindex help-echo @r{(text property)}
+If an overlay has a string as its @code{help-echo} property, then when
+you move the mouse onto the text in the overlay, Emacs displays that
+string in the echo area, or in the tooltip window.  It is available
+starting in Emacs 21.
+
 @item modification-hooks
 @kindex modification-hooks @r{(overlay property)}
 This property's value is a list of functions to be called if any
@@ -818,26 +905,6 @@ 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}.
 @end table
 
-  These are the functions for reading and writing the properties of an
-overlay.
-
-@defun overlay-get overlay prop
-This function returns the value of property @var{prop} recorded in
-@var{overlay}, if any.  If @var{overlay} does not record any value for
-that property, but it does have a @code{category} property which is a
-symbol, that symbol's @var{prop} property is used.  Otherwise, the value
-is @code{nil}.
-@end defun
-
-@defun overlay-put overlay prop value
-This function sets the value of property @var{prop} recorded in
-@var{overlay} to @var{value}.  It returns @var{value}.
-@end defun
-
-  See also the function @code{get-char-property} which checks both
-overlay properties and text properties for a given character.
-@xref{Examining Properties}.
-
 @node Managing Overlays
 @subsection Managing Overlays
 
@@ -974,13 +1041,14 @@ the beginning of the result if one multi-column character in
 @section Faces
 @cindex face
 
-A @dfn{face} is a named collection of graphical attributes: font,
-foreground color, background color, and optional underlining.  Faces
-control the display of text on the screen.
+  A @dfn{face} is a named collection of graphical attributes: font
+family, foreground color, background color, optional underlining, and
+many others.  Faces are used in Emacs to control the style of display of
+particular parts of the text or the frame.
 
 @cindex face id
 Each face has its own @dfn{face number}, which distinguishes faces at
-low levels within Emacs.  However, for most purposes, you can refer to
+low levels within Emacs.  However, for most purposes, you refer to
 faces in Lisp programs by their names.
 
 @defun facep object
@@ -996,23 +1064,56 @@ 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 Attributes::     What is in a face?
+* Attribute Functions:: Functions to examine and set face attributes.
+* Merging Faces::       How Emacs combines the faces specified for a character.
+* Font Selection::      Finding the best available font for a face.
 * Face Functions::      How to define and examine faces.
+* Auto Faces::          Hook for automatic face assignment.
+* Font Lookup::         Looking up the names of available fonts
+                          and information about them.
+* Fontsets::            A fontset is a collection of fonts
+                          that handle a range of character sets.
 @end menu
 
 @node Standard Faces
 @subsection Standard Faces
 
-  This table lists all the standard faces and their uses.
+  This table lists all the standard faces and their uses.  Most of them
+are used for displaying certain parts of the frames or certain kinds of
+text; you can control how those places look by customizing these faces.
 
 @table @code
 @item default
 @kindex default @r{(face name)}
 This face is used for ordinary text.
 
+@item mode-line
+@kindex mode-line @r{(face name)}
+This face is used for mode lines, and for menu bars
+when toolkit menus are not used.
+
 @item modeline
 @kindex modeline @r{(face name)}
-This face is used for mode lines and menu bars.
+This is an alias for the @code{mode-line} face, for compatibility with
+old Emacs versions.
+
+@item header-line
+@kindex header-line @r{(face name)}
+This face is used for the header lines of windows that have them.
+
+@item fringe
+@kindex fringe @r{(face name)}
+This face controls the colors of window fringes, the thin areas on
+either side that are used to display continuation and truncation glyphs.
+
+@item scroll-bar
+@kindex scroll-bar @r{(face name)}
+This face controls the colors for display of scroll bars.
+
+@item tool-bar
+@kindex tool-bar @r{(face name)}
+This face is used for display of the tool bar, if any.
 
 @item region
 @kindex region @r{(face name)}
@@ -1026,10 +1127,16 @@ This face is used to show any secondary selection you have made.
 @kindex highlight @r{(face name)}
 This face is meant to be used for highlighting for various purposes.
 
-@item underline
-@kindex underline @r{(face name)}
-This face underlines text.
+@item trailing-whitespace
+@kindex trailing-whitespace @r{(face name)}
+This face is used to display excess whitespace at the end of a line.
+@end table
 
+  In contrast, these faces are provided to change the appearance of text
+in specific ways.  You can use them on specific text, when you want
+the effects they produce.
+
+@table @code
 @item bold
 @kindex bold @r{(face name)}
 This face uses a bold font, if possible.  It uses the bold variant of
@@ -1044,6 +1151,20 @@ This face uses the italic variant of the frame's font, if it has one.
 @kindex bold-italic @r{(face name)}
 This face uses the bold italic variant of the frame's font, if it has
 one.
+
+@item underline
+@kindex underline @r{(face name)}
+This face underlines text.
+
+@item fixed-patch
+@kindex fixed-patch @r{(face name)}
+This face forces use of a particular fixed-width font.
+
+@item variable-patch
+@kindex variable-patch @r{(face name)}
+This face forces use of a particular variable-width font.  It's
+reasonable to customize this to use a diffrent variable-width font, if
+you like, but you should not make it a fixed-width font.
 @end table
 
 @node Defining Faces
@@ -1139,90 +1260,223 @@ background colors.  If it is @code{light}, then Emacs treats all frames
 as if they had a light background.
 @end defopt
 
-@node Merging Faces
-@subsection Merging Faces for Display
+@node Face Attributes
+@subsection Face Attributes
+@cindex face attributes
 
-  Here are all the ways to specify which face to use for display of text:
+  The effect of using a face is determined by a fixed set of @dfn{face
+attributes}.  This table lists all the face attributes, and what they
+mean.  Note that in general, more than one face be specified for a given
+piece of text; when that happens, the attributes of all the faces are
+merged to specify how to display the text.  @xref{Merging Faces}.
 
-@itemize @bullet
-@item
-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.)
+  In Emacs 21, any attribute in a face can have the value
+@code{unspecified}.  This means the face doesn't specify that attribute.
+In face merging, when the first face fails to specify a particular
+attribute, that means the next face gets a chance.  However, the
+@code{default} face must specify all attributes.
 
-@item
-With text properties.  A character may have a @code{face} property; if so,
-it is displayed with that face.  @xref{Special Properties}.
+  Some of these font attributes are meaningful only on certain
+kinds of displays---if your display cannot handle a certain attribute,
+the attribute is ignored.
 
-If the character has a @code{mouse-face} property, that is used instead
-of the @code{face} property when the mouse is ``near enough'' to the
-character.
+@table @code
+@item :family
+Font family name, or fontset name (@pxref{Fontsets}).  If you specify a
+font family name, the wild-cards @samp{*} and @samp{?} are allowed.
+
+@item :width
+Relative proportionate width, also known as the character set width or
+set width.  This should be one of the symbols @code{ultra-condensed},
+@code{extra-condensed}, @code{condensed}, @code{semi-condensed},
+@code{normal}, @code{semi-expanded}, @code{expanded},
+@code{extra-expanded}, or @code{ultra-expanded}.
+   
+@item :height
+Font height, an integer in units of 1/10pt.
+   
+@item :weight
+Font weight---a symbol from this series (from most dense to most faint):
+@code{ultra-bold}, @code{extra-bold}, @code{bold}, @code{semi-bold},
+@code{normal}, @code{semi-light}, @code{light}, @code{extra-light},
+@code{ultra-light}, or else @code{nil} meaning this attribute is not
+specified.
+   
+@item :slant
+Font slant---one of the symbols @code{italic}, @code{oblique}, @code{normal},
+@code{reverse-italic}, or @code{reverse-oblique}.
+   
+@item :foreground
+Foreground color, a string.
+   
+@item :background
+Background color, a string.
+
+@item :inverse-video
+Whether or not characters should be displayed in inverse video.  The
+value should be @code{t} (yes) or @code{nil} (no).
+
+@item :stipple
+The background stipple, a bitmap name.
+
+The value can be a string; then is the name of a file of pixmap data.
+The file is found in the directories listed in the variable
+@code{x-bitmap-file-path}.
+
+Alternatively, the value can be a list of the form @code{(@var{width}
+@var{height} @var{data})}.  Here, width and height are the size in
+pixels, and @var{data} is a string containing the raw bits of the
+bitmap.
+
+If the value is @code{nil}, that means use no stipple pattern.
+
+Normally you do not need to set the stipple attribute, because it is
+used automatically to handle certain shades of gray.
+
+@item :underline
+Whether or not characters should be underlined, and in what color.  If
+the value is @code{t}, underlining uses the foreground color of the
+face.  If the value is a string, underlining uses that color.  The
+value @code{nil} means do not underline.
+
+@item :overline
+Whether or not characters should be overlined, and in what color.
+The value is used like that of @code{:underline}.
+
+@item :strike-through
+Whether or not characters should be strike-through, and in what
+color.  The value is used like that of @code{:underline}.
+
+@item :box
+Whether or not a box should be drawn around characters, its color, the
+width of the box lines, and 3D appearance.  See below for the possible
+values and what they mean.
+@end table
 
-@item
-With overlays.  An overlay may have @code{face} and @code{mouse-face}
-properties too; they apply to all the text covered by the overlay.
+  Here are the possible values of the @code{:box} attribute, and what
+they mean:
 
-@item
-With a region that is active.  In Transient Mark mode, the region is
-highlighted with a particular face (see @code{region-face}, below).
+@table @asis
+@item @code{nil}
+Don't draw a box.
 
-@item
-With special glyphs.  Each glyph can specify a particular face 
-number.  @xref{Glyphs}.
-@end itemize
+@item @code{t}
+Draw a box with lines of width 1, in the foreground color.
 
-  If these various sources together specify more than one face for a
-particular character, Emacs merges the attributes of the various faces
-specified.  The attributes of the faces of special glyphs come first;
-then comes the face for region highlighting, if appropriate;
-then come attributes of faces from overlays, followed by those from text
-properties, and last the default face.
+@item @var{color}
+Draw a box with lines of width 1, in color @var{color}.
 
-  When multiple overlays cover one character, an overlay with higher
-priority overrides those with lower priority.  @xref{Overlays}.
+@item @code{(:line-width @var{width} :color @var{color} :style @var{style})}
+This way you can explicitly specify all aspects of the box.  The value
+@var{width} specifies the width of the lines to draw; it defaults to 1.
 
-  If an attribute such as the font or a color is not specified in any of
-the above ways, the frame's own font or color is used.
+The value @var{color} specifies the color to draw with.  The default is
+the foreground color of the face for simple boxes, and the background
+color of the face for 3D boxes.
 
-@node Face Functions
-@subsection Functions for Working with Faces
+The value @var{style} specifies whether to draw a 3D box.  If it is
+@code{released-button}, the box looks like a 3D button that is not being
+pressed.  If it is @code{pressed-button}, the box looks like a 3D button
+that is being pressed.  If it is @code{nil} or omitted, a plain 2D box
+is used.
+@end table
 
-  The attributes a face can specify include the font, the foreground
-color, the background color, and underlining.  The face can also leave
-these unspecified by giving the value @code{nil} for them.
+  The attributes @code{:overline}, @code{:strike-through} and
+@code{:box} are new in Emacs 21.  The attributes @code{:family},
+@code{:height}, @code{:width}, @code{:weight}, @code{:slant} are also
+new, previous versions had another way to specify some of the same
+information.
 
-  Here are the primitives for creating and changing faces.
+@table @code
+@item :font
+This attribute specified the font name.
 
-@defun make-face name
-This function defines a new face named @var{name}, initially with all
-attributes @code{nil}.  It does nothing if there is already a face named
-@var{name}.
-@end defun
+@item :bold
+A non-@code{nil} value specifies a bold font.
 
-@defun face-list
-This function returns a list of all defined face names.
-@end defun
+@item :italic
+A non-@code{nil} value specifies an italic font.
+@end table
 
-@defun copy-face old-face new-name &optional frame new-frame
-This function defines the face @var{new-name} as a copy of the existing
-face named @var{old-face}.  It creates the face @var{new-name} if that
-doesn't already exist.
+  For compatibility, you can still set these ``attributes'' in Emacs 21,
+even though they are not real face attributes.  Here is what that does:
 
-If the optional argument @var{frame} is given, this function applies
-only to that frame.  Otherwise it applies to each frame individually,
-copying attributes from @var{old-face} in each frame to @var{new-face}
-in the same frame.
+@table @code
+@item :font
+@code{:font} is not really a font attribute, but you can use it in
+@code{set-face-attribute} to specify several attributes at once.  You
+specify an X font name as the value, and based on this font name, and
+it sets the attributes @code{:family}, @code{:width}, @code{:height},
+@code{:weight}, and @code{:slant} according to the font name.
+
+If the value is a pattern with wildcards, the first font that matches
+the pattern is used to set these attributes.
+
+@item :bold
+A non-@code{nil} makes the face bold; @code{nil} makes it normal.
+This actually works by setting the @code{:weight} attribute.
+
+@item :italic
+A non-@code{nil} makes the face italic; @code{nil} makes it normal.
+This actually works by setting the @code{:slant} attribute.
+@end table
 
-If the optional argument @var{new-frame} is given, then @code{copy-face}
-copies the attributes of @var{old-face} in @var{frame} to @var{new-name}
-in @var{new-frame}.
-@end defun
+@defvar x-bitmap-file-path
+This variable specifies a list of directories for searching
+for bitmap files, for the @code{:stipple} attribute.
+@end defvar
+
+@node Attribute Functions
+@subsection Face Attribute Functions
 
   You can modify the attributes of an existing face with the following
 functions.  If you specify @var{frame}, they affect just that frame;
 otherwise, they affect all frames as well as the defaults that apply to
 new frames.
 
+@tindex set-face-attribute
+@defun set-face-attribute face frame &rest arguments
+This function sets one or more attributes of face @var{face}
+for frame @var{frame}.  If @var{frame} is @code{nil}, it sets
+the attribute for all frames, and the defaults for new frames.
+
+The extra arguments @var{arguments} specify the attributes to set, and
+the values for them.  They should consist of alternating attribute names
+(such as @code{:family} or @code{:underline} and corresponding values.
+Thus,
+
+@example
+(set-face-attribute 'foo nil
+                    :width :extended
+                    :weight :bold
+                    :underline "red")
+@end example
+
+@noindent
+sets the attributes @code{:width}, @code{:weight} and @code{:underline}
+to the corresponding values.
+@end defun
+
+@tindex face-attribute
+@defun face-attribute face attribute &optional frame
+This returns the value of the @var{attribute} attribute of face
+@var{face} on @var{frame}.  If @var{frame} is @code{nil},
+that means the selected frame.
+
+If @var{frame} is @code{t}, the value is the default for
+@var{face} for new frames.
+
+For example,
+
+@example
+(face-attribute 'bold :weight)
+     @result{} bold
+@end example
+@end defun
+
+  For older Emacs versions, you can these functions to set
+and examine the face attributes which existed in those versions.
+
 @defun set-face-foreground face color &optional frame
 @defunx set-face-background face color &optional frame
 These functions set the foreground (or background, respectively) color
@@ -1244,23 +1498,33 @@ they are used automatically to handle certain shades of gray.
 @end defun
 
 @defun set-face-font face font &optional frame
-This function sets the font of face @var{face}.  The argument @var{font}
-should be a string, either a valid font name for your system or the name
-of an Emacs fontset (@pxref{Fontsets}).  Note that if you set the font
+This function sets the font of face @var{face}.
+
+In Emacs 21, this actually sets the attributes @code{:family},
+@code{:width}, @code{:height}, @code{:weight}, and @code{:slant}
+according to the font name @var{font}.
+
+In Emacs 20, this sets the font attribute.  Once you set the font
 explicitly, the bold and italic attributes cease to have any effect,
-because the precise font that you specified is always used.
+because the precise font that you specified is used.
 @end defun
 
 @defun set-face-bold-p face bold-p &optional frame
 @tindex set-face-bold-p
-This function sets the bold attribute of face @var{face}.
-Non-@code{nil} means bold; @code{nil} means non-bold.
+This function specifies whether @var{face} should be bold.  If
+@var{bold-p} is non-@code{nil}, that means yes; @code{nil} means no.
+
+In Emacs 21, this sets the @code{:weight} attribute.
+In Emacs 20, it sets the @code{:bold} attribute.
 @end defun
 
 @defun set-face-italic-p face italic-p &optional frame
 @tindex set-face-italic-p
-This function sets the italic attribute of face @var{face}.
-Non-@code{nil} means italic; @code{nil} means non-italic.
+This function specifies whether @var{face} should be italic.  If
+@var{italic-p} is non-@code{nil}, that means yes; @code{nil} means no.
+
+In Emacs 21, this sets the @code{:slant} attribute.
+In Emacs 20, it sets the @code{:italic} attribute.
 @end defun
 
 @defun set-face-underline-p face underline-p &optional frame
@@ -1269,10 +1533,9 @@ 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
-and background are set to the default background and foreground,
-respectively.
+This function inverts the @code{:inverse-video} attribute of face
+@var{face}.  If the attribute is @code{nil}, this function sets it to
+@code{t}, and vice versa.
 @end defun
 
   These functions examine the attributes of a face.  If you don't
@@ -1295,16 +1558,220 @@ This function returns the name of the font of face @var{face}.
 
 @defun face-bold-p face &optional frame
 @tindex face-bold-p
-This function returns the bold attribute of face @var{face}.
+This function returns @code{t} if @var{face} is bold---that is, if it is
+bolder than normal.  It returns @code{nil} otherwise.
 @end defun
 
 @defun face-italic-p face &optional frame
 @tindex face-italic-p
-This function returns the italic attribute of face @var{face}.
+This function returns @code{t} if @var{face} is italic or oblique,
+@code{nil} otherwise.
 @end defun
 
 @defun face-underline-p face &optional frame
-This function returns the underline attribute of face @var{face}.
+This function returns the @code{:underline} attribute of face @var{face}.
+@end defun
+
+@defun face-inverse-video-p face &optional frame
+This function returns the @code{:inverse-video} attribute of face @var{face}.
+@end defun
+
+@node Merging Faces
+@subsection Merging Faces for Display
+
+  Here are the ways to specify which faces to use for display of text:
+
+@itemize @bullet
+@item
+With defaults.  The @code{default} face is used as the ultimate
+default for all text.  (In Emacs 19 and 20, the @code{default}
+face is used only when no other face is specified.)
+
+For a mode line or header line, the face @code{modeline} or
+@code{header-line} is used just before @code{default}.
+
+@item
+With text properties.  A character can have a @code{face} property; if
+so, the faces and face attributes specified there apply.  @xref{Special
+Properties}.
+
+If the character has a @code{mouse-face} property, that is used instead
+of the @code{face} property when the mouse is ``near enough'' to the
+character.
+
+@item
+With overlays.  An overlay can have @code{face} and @code{mouse-face}
+properties too; they apply to all the text covered by the overlay.
+
+@item
+With a region that is active.  In Transient Mark mode, the region is
+highlighted with the face @code{region} (@pxref{Standard Faces}).
+
+@item
+With special glyphs.  Each glyph can specify a particular face 
+number.  @xref{Glyphs}.
+@end itemize
+
+  If these various sources together specify more than one face for a
+particular character, Emacs merges the attributes of the various faces
+specified.  The attributes of the faces of special glyphs come first;
+then comes the face for region highlighting, if appropriate;
+then come attributes of faces from overlays, followed by those from text
+properties, and last the default face.
+
+  When multiple overlays cover one character, an overlay with higher
+priority overrides those with lower priority.  @xref{Overlays}.
+
+  In Emacs 20, if an attribute such as the font or a color is not
+specified in any of the above ways, the frame's own font or color is
+used.  In newer Emacs versions, this cannot happen, because the
+@code{default} face specifies all attributes---in fact, the frame's own
+font and colors are synonymous with those of the default face.
+
+@node Font Selection
+@subsection Font Selection
+
+  @dfn{Selecting a font} means mapping the specified face attributes for
+a character to a font that is available on a particular display.  The
+face attributes, as determined by face merging, specify most of the
+font choice, but not all.  Part of the choice depends on what character
+it is.
+
+  For multibyte characters, typically each font covers only one
+character set.  So each character set (@pxref{Character Sets}) specifies
+a registry and encoding to use, with the character set's
+@code{x-charset-registry} property.  Its value is a string containing
+the registry and the encoding, with a dash between them:
+
+@example
+(plist-get (charset-plist 'latin-iso8859-1)
+           'x-charset-registry)
+     @result{} "ISO8859-1"
+@end example
+
+  Unibyte text does not have character sets, so displaying a unibyte
+character takes the registry and encoding from the variable
+@code{face-default-registry}.
+
+@defvar face-default-registry
+This variable specifies which registry and encoding to use in choosing
+fonts for unibyte characters.  The value is initialized at Emacs startup
+time from the font the user specified for Emacs.
+@end defvar
+
+  If the face specifies a fontset name, that fontset determines a
+pattern for fonts of the given charset.  If the face specifies a font
+family, a font pattern is constructed.
+
+  Emacs tries to find an available font for the given face attributes
+and character's registry and encoding.  If there is a font that matches
+exactly, it is used, of course.  The hard case is when no available font
+exactly fits the specification.  Then Emacs looks for one that is
+``close''---one attribute at a time.  You can specify the order
+to consider the attributes.
+
+@defvar face-font-selection-order
+@tindex face-font-selection-order
+This variable specifies the order of importance of the face attributes
+@code{:width}, @code{:height}, @code{:weight}, and @code{:slant}.  The
+value should be a list containing those four symbols, in order of
+decreasing importance.
+
+Font selection first finds the best available matches for the first
+attribute listed; then, among the fonts which are best in that way, it
+searches for the best matches in the second attribute, and so on.
+
+The attributes @code{:weight} and @code{:width} have symbolic values in
+a range centered around @code{normal}.  Matches that are more extreme
+(farther from @code{normal}) are somewhat preferred to matches that are
+less extreme (closer to @code{normal}); this is designed to ensure that
+non-normal faces contrast with normal ones, whenever possible.
+
+The default is @code{(:width :height :weight :slant)}, which means first
+find the fonts closest to the specified @code{:width}, then---among the
+fonts with that width---find a best match for the specified font height,
+and so on.
+
+One example of a case where this variable makes a difference is when the
+default font has no italic equivalent.  With the default ordering, the
+@code{italic} face will use a non-italic font that is similar to the
+default one.  But if you put @code{:slant} before @code{:height}, the
+@code{italic} face will use an italic font, even if its height is not
+quite right.
+@end defvar
+
+@defvar face-alternative-font-family-alist
+@tindex face-alternative-font-family-alist
+This variable lets you specify alternative font families to try, if a
+given family is specified and doesn't exist.  Each element should have
+this form:
+
+@example
+(@var{family} @var{alternate-families}@dots{})
+@end example
+
+If @var{family} is specified but not available, Emacs will try the other
+families given in @var{alternate-families}, one by one, until it finds a
+family that does exist.
+@end defvar
+
+  Emacs can make use of scalable fonts, but by default it does not use
+them, since the use of too many or too big scalable fonts can crash
+XFree86 servers.
+
+@defvar scalable-fonts-allowed
+@tindex scalable-fonts-allowed
+This variable controls which scalable fonts to use.  A value of
+@code{nil}, the default, means do not use scalable fonts.  @code{t}
+means to use any scalable font that seems appropriate for the text.
+
+Otherwise, the value must be a list of regular expressions.  Then a
+scalable font is enabled for use if its name matches any regular
+expression in the list.  For example,
+
+@example
+(setq scalable-fonts-allowed '("muleindian-2$"))
+@end example
+
+@noindent
+allows the use of scalable fonts with registry @code{muleindian-2}.
+@end example
+
+@defun clear-face-cache &optional unload-p
+@tindex clear-face-cache
+This function clears the face cache for all frames.
+If @var{unload-p} is non-@code{nil}, that means to unload
+all unused fonts as well.
+@end defun
+
+@node Face Functions
+@subsection Functions for Working with Faces
+
+  Here are additional functions for creating and working with faces.
+
+@defun make-face name
+This function defines a new face named @var{name}, initially with all
+attributes @code{nil}.  It does nothing if there is already a face named
+@var{name}.
+@end defun
+
+@defun face-list
+This function returns a list of all defined face names.
+@end defun
+
+@defun copy-face old-face new-name &optional frame new-frame
+This function defines the face @var{new-name} as a copy of the existing
+face named @var{old-face}.  It creates the face @var{new-name} if that
+doesn't already exist.
+
+If the optional argument @var{frame} is given, this function applies
+only to that frame.  Otherwise it applies to each frame individually,
+copying attributes from @var{old-face} in each frame to @var{new-face}
+in the same frame.
+
+If the optional argument @var{new-frame} is given, then @code{copy-face}
+copies the attributes of @var{old-face} in @var{frame} to @var{new-name}
+in @var{new-frame}.
 @end defun
 
 @defun face-id face
@@ -1329,22 +1796,801 @@ face if each attribute is either the same as that of the default face or
 @code{nil} (meaning to inherit from the default).
 @end defun
 
-@defvar region-face
-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 face number of the face named @code{region}.
-@end defvar
-
 @tindex frame-update-face-colors
 @defun frame-update-face-colors frame
 This function updates the way faces display on @var{frame}, for a change
 in @var{frame}'s foreground or background color.
 @end defun
 
+@node Auto Faces
+@subsection Automatic Face Assignment
+@cindex automatic face assignment
+@cindex faces, automatic choice
+
+@cindex Font-Lock mode
+  Starting with Emacs 21, a hook is available for automatically
+assigning faces to text in the buffer.  This hook is used for part of
+the implementation of Font-Lock mode.
+
+@tindex fontification-functions
+@defvar fontification-functions
+This variable holds a list of functions that are called by Emacs
+redisplay as needed to assign faces automatically to text in the buffer.
+
+The functions are called in the order listed, with one argument, a
+buffer position @var{pos}.  Each function should attempt to assign faces
+to the text in the current buffer starting at @var{pos}.
+
+Each function should record the faces they assign by setting the
+@code{face} property.  It should also add a non-@code{nil}
+@code{fontified} property for all the text it has assigned faces to.
+That property tells redisplay that faces have been assigned to that text
+already.
+
+It is probably a good idea for each function to do nothing if the
+character after @var{pos} already has a non-@code{nil} @code{fontified}
+property, but this is not required.  If one function overrides the
+assignments made by a previous one, the properties as they are
+after the last function finishes are the ones that really matter.
+
+For efficiency, we recommend writing these functions so that they
+usually assign faces to around 400 to 600 characters at each call.
+@end defvar
+
+@node Font Lookup
+@subsection Looking Up Fonts
+
+@defun x-list-fonts pattern &optional face frame maximum
+This function returns a list of available font names that match
+@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
+@samp{?} character matches any single character.  Pattern matching
+of font names ignores case.
+
+If you specify @var{face} and @var{frame}, @var{face} should be a face name
+(a symbol) and @var{frame} should be a frame.
+
+The optional argument @var{maximum} sets a limit on how many fonts to
+return.  If this is non-@code{nil}, then the return value is truncated
+after the first @var{maximum} matching fonts.  Specifying a small value
+for @var{maximum} can make this function much faster, in cases where
+many fonts match the pattern.
+@end defun
+
+  These additional functions are available starting in Emacs 21.
+
+@defun x-family-fonts &optional family frame
+@tindex x-family-fonts
+This function returns a list describing the available fonts for family
+@var{family} on @var{frame}.  If @var{family} is omitted or @code{nil},
+this list applies to all families, and therefore, it contains all
+available fonts.  Otherwise, @var{family} must be a string; it may
+contain the wildcards @samp{?} and @samp{*}.
+
+The list describes the display that @var{frame} is on; if @var{frame} is
+omitted or @code{nil}, it applies to the selected frame's display.
+
+The list contains a vector of the following form for each font:
+
+@example
+[@var{family} @var{width} @var{point-size} @var{weight} @var{slant}
+ @var{fixed-p} @var{full} @var{registry-and-encoding}]
+@end example
+
+The first five elements correspond to face attributes; if you
+specify these attributes for a face, it will use this font.
+
+The last three elements give additional information about the font.
+@var{fixed-p} is non-nil if the font is fixed-pitch.  @var{full} is the
+full name of the font, and @var{registry-and-encoding} is a string
+giving the registry and encoding of the font.
+
+The result list is sorted according to the current face font sort order.
+@end defun
+
+@defun x-font-family-list &optional frame
+@tindex x-font-family-list
+This function returns a list of the font families available for
+@var{frame}'s display.  If @var{frame} is omitted or @code{nil}, it
+describes the selected frame's display.
+
+The value is a list of elements of this form:
+
+@example
+(@var{family} . @var{fixed-p})
+@end example
+
+@noindent
+Here @var{family} is a font family, and @var{fixed-p} is
+non-@code{nil} if fonts of that family are fixed-pitch.
+@end defun
+
+@defvar font-list-limit
+@tindex font-list-limit
+This variable specifies maximum number of fonts to consider in font
+matching.  The function @code{x-family-fonts} will not return more than
+that many fonts, and font selection will consider only that many fonts
+when searching a matching font for face attributes.  The default is
+currently 100.
+@end defvar
+
+@node Fontsets
+@subsection Fontsets
+
+  A @dfn{fontset} is a list of fonts, each assigned to a range of
+character codes.  An individual font cannot display the whole range of
+characters that Emacs supports, but a fontset can.  Fontsets have names,
+just as fonts do, and you can use a fontset name in place of a font name
+when you specify the ``font'' for a frame or a face.  Here is
+information about defining a fontset under Lisp program control.
+
+@defun create-fontset-from-fontset-spec fontset-spec &optional style-variant-p noerror
+This function defines a new fontset according to the specification
+string @var{fontset-spec}.  The string should have this format:
+
+@smallexample
+@var{fontpattern}, @r{[}@var{charsetname}:@var{fontname}@r{]@dots{}}
+@end smallexample
+
+@noindent
+Whitespace characters before and after the commas are ignored.
+
+The first part of the string, @var{fontpattern}, should have the form of
+a standard X font name, except that the last two fields should be
+@samp{fontset-@var{alias}}.
+
+The new fontset has two names, one long and one short.  The long name is
+@var{fontpattern} in its entirety.  The short name is
+@samp{fontset-@var{alias}}.  You can refer to the fontset by either
+name.  If a fontset with the same name already exists, an error is
+signaled, unless @var{noerror} is non-@code{nil}, in which case this
+function does nothing.
+
+If optional argument @var{style-variant-p} is non-@code{nil}, that says
+to create bold, italic and bold-italic variants of the fontset as well.
+These variant fontsets do not have a short name, only a long one, which
+is made by altering @var{fontpattern} to indicate the bold or italic
+status.
+
+The specification string also says which fonts to use in the fontset.
+See below for the details.
+@end defun
+
+  The construct @samp{@var{charset}:@var{font}} specifies which font to
+use (in this fontset) for one particular character set.  Here,
+@var{charset} is the name of a character set, and @var{font} is the font
+to use for that character set.  You can use this construct any number of
+times in the specification string.
+
+  For the remaining character sets, those that you don't specify
+explicitly, Emacs chooses a font based on @var{fontpattern}: it replaces
+@samp{fontset-@var{alias}} with a value that names one character set.
+For the @sc{ascii} character set, @samp{fontset-@var{alias}} is replaced
+with @samp{ISO8859-1}.
+
+  In addition, when several consecutive fields are wildcards, Emacs
+collapses them into a single wildcard.  This is to prevent use of
+auto-scaled fonts.  Fonts made by scaling larger fonts are not usable
+for editing, and scaling a smaller font is not useful because it is
+better to use the smaller font in its own size, which Emacs does.
+
+  Thus if @var{fontpattern} is this,
+
+@example
+-*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24
+@end example
+
+@noindent
+the font specification for ASCII characters would be this:
+
+@example
+-*-fixed-medium-r-normal-*-24-*-ISO8859-1
+@end example
+
+@noindent
+and the font specification for Chinese GB2312 characters would be this:
+
+@example
+-*-fixed-medium-r-normal-*-24-*-gb2312*-*
+@end example
+
+  You may not have any Chinese font matching the above font
+specification.  Most X distributions include only Chinese fonts that
+have @samp{song ti} or @samp{fangsong ti} in the @var{family} field.  In
+such a case, @samp{Fontset-@var{n}} can be specified as below:
+
+@smallexample
+Emacs.Fontset-0: -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24,\
+        chinese-gb2312:-*-*-medium-r-normal-*-24-*-gb2312*-*
+@end smallexample
+
+@noindent
+Then, the font specifications for all but Chinese GB2312 characters have
+@samp{fixed} in the @var{family} field, and the font specification for
+Chinese GB2312 characters has a wild card @samp{*} in the @var{family}
+field.
+
+@node Display Property
+@section The @code{display} Property
+@cindex display specification
+@kindex display @r{(text property)}
+
+  The @code{display} text property is used to insert images into text,
+and also control other aspects of how text displays.  These features are
+available starting in Emacs 21.  The value of the @code{display}
+property should be a display specification, or a list or vector
+containing several display specifications.  The rest of this section
+describes several kinds of display specifications and what they mean.
+
+@menu
+* Specified Space::
+* Other Display Specs::
+* Display Margins::
+* Conditional Display::
+@end menu
+
+@node Specified Space
+@subsection Specified Spaces
+@cindex spaces, specified height or width
+@cindex specified spaces
+@cindex variable-width spaces
+
+  To display a space of specified width and/or height, use a display
+specification of the form @code{(space @var{props})}, where @var{props}
+is a property list (see below).  You can put this property on one or
+more consecutive characters; a space of the specified height and width
+is displayed in place of @emph{all} of those characters.
+
+@table @code
+@item :width @var{width}
+Specifies that the space width should be @var{width} times the normal
+character width.  @var{width} can be an integer or floating point
+number.
+
+@item :relative-width @var{factor}
+Specifies that the width of the stretch should be computed from the
+first character in the group of consecutive characters that have the
+same @code{display} property.  The space width is the width of that
+character, multiplied by @var{factor}.
+
+@item :align-to @var{hpos}
+Specifies that the space should be wide enough to reach @var{hpos}.  The
+value @var{hpos} is measured in units of the normal character width.
+@end table
+
+  Exactly one of the above properties should be used.  You can also
+specify the height of the space, with other properties:
+
+@table @code
+@item :height @var{height}
+Specifies the height of the space, as @var{height},
+measured in terms of the normal line height.
+
+@item :relative-height @var{factor}
+Specifies the height of the space, multiplying the ordinary height
+of the text having this display specification by @var{factor}.
+
+@item :ascent @var{ascent}
+Specifies that @var{ascent} percent of the height of the space should be
+considered as the ascent of the space.  The value of @var{ascent} must
+be a non-negative number no greater than 100.
+@end table
+
+  You should not use both @code{:height} and @code{:relative-height}
+together.
+
+@node Other Display Specs
+@subsection Other Display Specifications
+
+@table @code
+@item (image . @var{image-props})
+This is in fact an image descriptor (@pxref{Images}).  When used as a
+display specification, it means to display the image instead of the text
+that has the display specification.
+
+@item (space-width @var{factor})
+This display specification affects all the spaces in the text that has
+the specification.  It displays all of these spaces @var{factor} times
+as wide as normal.  The element @var{factor} should be an integer or
+float.
+
+@item (height @var{height})
+This display specification makes the text taller or shorter.
+Here are the possibilities for @var{height}:
+
+@table @asis
+@item @code{(+ @var{n})}
+This means to use a font that is @var{n} steps larger.  A ``step'' is
+defined by the set of available fonts; each size for which a font is
+available counts as a step.  @var{n} should be an integer.
+
+@item @code{(- @var{n})}
+This means to use a font that is @var{n} steps smaller.
+
+@item a number, @var{factor}
+A number, @var{factor}, means to use a font that is @var{factor} times
+as tall as the default font.
+
+@item a symbol, @var{function}
+A symbol is a function to compute the height.  It is called with the
+current height as argument, and should return the new height to use.
+
+@item anything else, @var{form}
+If the @var{height} value doesn't fit the previous possibilities, it is
+a form.  Emacs evaluates it to get the new height, with the symbol
+@code{height} bound to the current specified font height.
+@end table
+
+@item (raise @var{factor})
+This kind of display specification raises or lowers the text
+it applies to, relative to the baseline of the line.
+
+@var{factor} must be a number, which is interpreted as a multiple of the
+height of the affected text.  If it is positive, that means to display
+the characters raised.  If it is negative, that means to display them
+lower down.
+
+If the text also has a @code{height} display specification, that does
+not affect the amount of raising or lowering, which is based on the
+faces used for the text.
+@end table
+
+@node Display Margins
+@subsection Displaying in the Margins
+@cindex display margins
+@cindex margins, display
+
+  A buffer can have blank areas called @dfn{display margins} on the left
+and on the right.  Ordinary text never appears in these areas, but you
+can put things into the display margins using the @code{display}
+property.
+
+  To put text in the left or right display margin of the window, use a
+display specification of the form @code{(margin right-margin)} or
+@code{(margin left-margin)} on it.  To put an image in a display margin,
+use that display specification along with the display specification for
+the image.
+
+  Before the display margins can display anything, you must give
+them a nonzero width.  The usual way to do that is to set these
+variables:
+
+@defvar left-margin-width
+@tindex left-margin-width
+This variable specifies the width of the left margin.
+It is buffer-local in all buffers.
+@end defvar
+
+@defvar right-margin-width
+@tindex right-margin-width
+This variable specifies the width of the right margin.
+It is buffer-local in all buffers.
+@end defvar
+
+  Setting these variables does not immediately affect the window.  These
+variables are checked when a new buffer is displayed in the window.
+Thus, you can make changes take effect by calling
+@code{set-window-buffer}.
+
+  You can also set the margin widths immediately.
+
+@defun set-window-margins window left right
+@tindex set-window-margins
+This function specifies the margin widths for window @var{window}.
+The argument @var{left} controls the left margin and 
+@var{right} controls the right margin.
+@end defun
+
+@defun window-margins &optional window
+@tindex window-margins
+This function returns the left and right margins of @var{window}
+as a cons cell of the form @code{(@var{left} . @var{right})}.
+If @var{window} is @code{nil}, the selected window is used.
+@end defun
+
+@node Conditional Display
+@subsection Conditional Display Specifications
+@cindex conditional display specifications
+
+  You can make any display specification conditional.  To do that,
+package it in another list of the form @code{(when @var{condition}
+@var{spec})}.  Then the specification @var{spec} applies only when
+@var{condition} evaluates to a non-@code{nil} value.  During the
+evaluation, point is temporarily set at the end position of the text
+having this conditional display specification.
+
+@node Images
+@section Images
+@cindex images in buffers
+
+  To display an image in an Emacs buffer, you must first create an image
+descriptor, then use it as a display specifier in the @code{display}
+property of text that is displayed (@pxref{Display Property}).  Like the
+@code{display} property, this feature is available starting in Emacs 21.
+
+  Emacs can display a number of different image formats; some of them
+are supported only if particular support libraries are installed on your
+machine.  The supported image formats include XBM, XPM (needing the
+libraries @code{libXpm} version 3.4k and @code{libz}), GIF (needing
+@code{libungif} 4.1.0), Postscript, PBM, JPEG (needing the
+@code{libjpeg} library version v6a), TIFF (needing @code{libtiff} v3.4),
+and PNG (needing @code{libpng} 1.0.2).
+
+  You specify one of these formats with an image type symbol.  The image
+type symbols are @code{xbm}, @code{xpm}, @code{gif}, @code{postscript},
+@code{pbm}, @code{jpeg}, @code{tiff}, and @code{png}.
+
+@defvar image-types
+This variable contains a list of those image type symbols that are
+supported in the current configuration.
+@end defvar
+
+@menu
+* Image Descriptors::
+* XBM Images::                    
+* XPM Images::
+* GIF Images::
+* Postscript Images::
+* Other Image Types::
+* Defining Images::
+* Showing Images::
+* Image Cache::
+@end menu
+
+@node Image Descriptors
+@subsection Image Descriptors
+@cindex image descriptor
+
+  An image description is a list of the form @code{(image
+. @var{props})}, where @var{props} is a property list containing
+alternating keyword symbols (symbols whose names start with a colon) and
+their values.  Every image descriptor must contain the property
+@code{:type @var{type}} to specify the format of the image.  The value
+of @var{type} should be an image type symbol; for example, @code{xpm}
+for an image in XPM format.
+
+  Here is a list of other properties that are meaningful for all image
+types:
+
+@table @code
+@item :ascent @var{ascent}
+The @code{:ascent} property specifies the percentage of the image's
+height to use for its ascent---that is, the part above the baseline.  The
+value, @var{ascent}, must be a number in the range 0 to 100.  If this
+property is omitted, it defaults to 50.
+
+@item :margin @var{margin}
+The @code{:margin} property specifies how many pixels to add as an extra
+margin around the image.  The value, @var{margin}, must be a
+non-negative number; if it is not specified, the default is zero.
+
+@item :relief @var{relief}
+The @code{:relief} property, if non-@code{nil}, adds a shadow rectangle
+around the image.  The value, @var{relief}, specifies the width of the
+shadow lines, in pixels.  If @var{relief} is negative, shadows are drawn
+so that the image appears as a pressed button; otherwise, it appears as
+an unpressed button.
+
+@item :algorithm @var{algorithm}
+The @code{:algorithm} property, if non-@code{nil}, specifies a
+conversion algorithm that should be applied to the image before it is
+displayed; the value, @var{algorithm}, specifies which algorithm.
+
+Currently, the only meaningful value for @var{algorithm} (aside from
+@code{nil}) is @code{laplace}; this applies the Laplace edge detection
+algorithm, which blurs out small differences in color while highlighting
+larger differences.  People sometimes consider this useful for
+displaying the image for a ``disabled'' button.
+
+@item :heuristic-mask @var{transparent-color}
+The @code{:heuristic-mask} property, if non-@code{nil}, specifies that a
+certain color in the image should be transparent.  Each pixel where this
+color appears will actually allow the frame's background to show
+through.
+
+If @var{transparent-color} is @code{t}, then determine the transparent
+color by looking at the four corners of the image.  This uses the color
+that occurs most frequently near the corners as the transparent color.
+
+Otherwise, @var{heuristic-mask} should specify the transparent color
+directly, as a list of three integers in the form @code{(@var{red}
+@var{green} @var{blue})}.
+
+@item :file @var{file}
+The @code{:file} property specifies to load the image from file
+@var{file}.  If @var{file} is not an absolute file name, it is expanded
+in @code{data-directory}.
+
+@item :data @var{data}
+The @code{:data} property specifies the actual contents of the image.
+Each image must use either @code{:data} or @code{:file}, but not both.
+However, only certain image types support @code{:data}; for other types,
+you must use @code{:file}.
+
+The formats that support @code{:data} include XBM and XPM.
+Before using @code{:data}, see the section describing the specific
+format you wish to use for further information.
+@end table
+
+@node XBM Images
+@subsection XBM Images
+@cindex XBM
+
+  To use XBM format, specify @code{xbm} as the image type.  This image
+format doesn't require an external library, so images of this type are
+always supported.
+
+  Additional image properties supported for the @code{xbm} image type are:
+
+@table @code
+@item :foreground @var{foreground}
+The value, @var{foreground}, should be a string specifying the image
+foreground color.  This color is used for each pixel in the XBM that is
+1.  The default is the frame's foreground color.
+
+@item :background @var{background}
+The value, @var{background}, should be a string specifying the image
+background color.  This color is used for each pixel in the XBM that is
+0.  The default is the frame's background color.
+@end table
+
+  You can specify an XBM image using data within Emacs instead
+of an external file.  To do this, don't use @code{:file}; instead,
+use the following three properties (all of them):
+
+@table @code
+@item :width @var{width}
+The value, @var{width}, specifies the width the image in pixels.
+
+@item :height @var{height}
+The value, @var{height}, specifies the height of the image in pixels.
+
+@item :data @var{data}
+The value, @var{data}, is normally a string or a bool-vector.  Either
+way, it must contain enough bits for the area of the image: at least
+@var{width} * @code{height}.
+
+Alternatively, @var{data} can be a vector of strings or bool-vectors,
+each specifying one line of the image.
+@end table
+
+@node XPM Images
+@subsection XPM Images
+@cindex XPM
+
+  To use XPM format, specify @code{xpm} as the image type.  These
+additional image properties are meaningful with the @code{xpm} image
+type:
+
+@table @code
+@item :color-symbols @var{symbols}
+The value, @var{symbols}, should be an alist whose elements have the
+form @code{(@var{name} . @var{color})}.  In each element, @var{name} is
+the name of a color as it appears in the image file, and @var{color}
+specifies the actual color to use for displaying that name.
+
+@item :data @var{data}
+XPM images can be displayed from data instead of files.  In that case,
+use the @code{:data} property instead of the @code{:file} property.
+
+The value @var{data} must be a string containing an XPM image.  The
+contents of the string have same format as an external XPM file.
+@end table
+
+@node GIF Images
+@subsection GIF Images
+@cindex GIF
+
+  For GIF images, specify image type @code{gif}.  Because of the patents
+in the US covering the LZW algorithm, the continued use of GIF format is
+a problem for the whole Internet; to end this problem, it is a good idea
+for everyone, even outside the US, to stop using GIFS right away
+(@uref{http://www.burnallgifs.org/}).  But if you still want to use
+them, Emacs can display them.
+
+@table @code
+@item :index @var{index}
+You can use @code{:index} to specify one image from a GIF file that
+contains more than one image.  This property specifies use of image
+number @var{index} from the file.  An error is signaled if the GIF file
+doesn't contain an image with index @var{index}.
+@end table
+
+@ignore
+This could be used to implement limited support for animated GIFs.
+For example, the following function displays a multi-image GIF file
+at point-min in the current buffer, switching between sub-images
+every 0.1 seconds.
+
+(defun show-anim (file max)
+  "Display multi-image GIF file FILE which contains MAX subimages."
+  (display-anim (current-buffer) file 0 max t))
+
+(defun display-anim (buffer file idx max first-time)
+  (when (= idx max)
+    (setq idx 0))
+  (let ((img (create-image file nil :image idx)))
+    (save-excursion
+      (set-buffer buffer)
+      (goto-char (point-min))
+      (unless first-time (delete-char 1))
+      (insert-image img))
+    (run-with-timer 0.1 nil 'display-anim buffer file (1+ idx) max nil)))
+@end ignore
+
+@node Postscript Images
+@subsection Postscript Images
+@cindex Postscript images
+
+  To use Postscript for an image, specify image type @code{postscript}.
+This works only if you have Ghostscript installed.  You must always use
+these three properties:
+
+@table @code
+@item :pt-width @var{width}
+The value, @var{width}, specifies the width of the image measured in
+points (1/72 inch).  @var{width} must be an integer.
+
+@item :pt-height @var{height}
+The value, @var{height}, specifies the height of the image in points
+(1/72 inch).  @var{height} must be an integer.
+
+@item :bounding-box @var{box}
+The value, @var{box}, must be a list or vector of four integers, which
+specifying the bounding box of the Postscript image, analogous to the
+@samp{BoundingBox} comment found in Postscript files.
+
+@example
+%%BoundingBox: 22 171 567 738
+@end example
+@end table
+
+@node Other Image Types
+@subsection Other Image Types
+@cindex PBM
+
+  For PBM images, specify image type @code{pbm}.  Color, gray-scale and
+monochromatic images are supported.
+
+  For JPEG images, specify image type @code{jpeg}.  There are no
+additional image properties defined.
+
+  For TIFF images, specify image type @code{tiff}.
+
+  For PNG images, specify image type @code{png}.
+
+@node Defining Images
+@subsection Defining Images
+
+  The functions @code{create-image} and @code{defimage} provide
+convenient ways to create image descriptors.
+
+@defun create-image file &optional type &rest props
+@tindex create-image
+This function creates and returns an image descriptor which uses the
+data in @var{file}.
+
+The optional argument @var{type} is a symbol specifying the image type.
+If @var{type} is omitted or @code{nil}, @code{create-image} tries to
+determine the image type from the file's first few bytes, or else
+from the file's name.
+
+The remaining arguments, @var{props}, specify additional image
+properties---for example,
+
+@example
+(create-image "foo.xpm" 'xpm :heuristic-mask t)
+@end example
+
+The function returns @code{nil} if images of this type are not
+supported.  Otherwise it returns an image descriptor.
+@end defun
+
+@defmac defimage variable doc &rest specs
+@tindex defimage
+This macro defines @var{variable} as an image name.  The second argument,
+@var{doc}, is an optional documentation string.  The remaining
+arguments, @var{specs}, specify alternative ways to display the image.
+
+Each argument in @var{specs} has the form of a property list, and each
+one should specify at least the @code{:type} property and the
+@code{:file} property.  Here is an example:
+
+@smallexample
+(defimage test-image ((:type xpm :file \"~/test1.xpm\")
+                      (:type xbm :file \"~/test1.xbm\")))"
+@end smallexample
+
+@code{defimage} tests each argument, one by one, to see if it is
+usable---that is, if the type is supported and the file exists.  The
+first usable argument is used to make an image descriptor which is
+stored in the variable @var{variable}.
+
+If none of the alternatives will work, then @var{variable} is defined
+as @code{nil}.
+@end defmac
+
+@node Showing Images
+@subsection Showing Images
+
+  You can use an image descriptor by setting up the @code{display}
+property yourself, but it is easier to use the functions in this
+section.
+
+@defun insert-image image &optional area
+This function inserts @var{image} in the current buffer at point.  The
+value @var{image} should be an image descriptor; it could be a value
+returned by @code{create-image}, or the value of a symbol defined with
+@code{defimage}.
+
+The argument @var{area} specifies whether to put the image in a margin.
+If it is @code{left-margin}, the image appears in the left margin;
+@code{right-margin} specifies the right margin.  If @var{area} is
+@code{nil} or omitted, the image is displayed at point within the
+buffer's text.
+
+Internally, this function inserts an @samp{x} in the buffer, and gives
+it a @code{display} property which specifies this image.  @xref{Display
+Property}.
+@end defun
+
+@defun put-image image pos &optional area
+This function puts image @var{image} in front of @var{pos} in the
+current buffer.  The argument @var{pos} should be an integer or a
+marker.  It specifies the buffer position where the image should appear.
+
+The argument @var{image} must be an image descriptor, perhaps returned
+by @code{create-image} or stored by @code{defimage}.
+
+The argument @var{area} specifies whether to put the image in a margin.
+If it is @code{left-margin}, the image appears in the left margin;
+@code{right-margin} specifies the right margin.  If @var{area} is
+@code{nil} or omitted, the image is displayed at point within the
+buffer's text.
+
+Internally, this function creates an overlay, and gives it a
+@code{before-string} property containing text that has a @code{display}
+property whose value is the image.  (Whew!)
+@end defun
+
+@defun remove-images start end &optional buffer
+This function removes images in @var{buffer} between positions
+@var{start} and @var{end}.  If @var{buffer} is omitted or @code{nil},
+images are removed from the current buffer.
+
+This remove only images that were put into @var{buffer} the way
+@code{put-image} does it, not images that were inserted with
+@code{insert-image} or in other ways.
+@end defun
+
+@node Image Cache
+@subsection Image Cache
+
+  Emacs stores images in an image cache when it displays them, so it can
+display them again more efficiently.  It removes an image from the cache
+when it hasn't been displayed for a specified period of time.
+
+@defvar image-cache-eviction-delay
+@tindex image-cache-eviction-delay
+This variable specifies the number of seconds an image can remain in the
+cache without being displayed.  When an image is not displayed for this
+length of time, Emacs removes it from the image cache.
+
+If the value is @code{nil}, Emacs does not remove images from the cache
+except when you explicitly clear it.  This mode can be useful for
+debugging.
+@end defvar
+
+@defun clear-image-cache &optional frame
+@tindex clear-image-cache
+This function clears the image cache.  If @var{frame} is non-@code{nil},
+only the cache for that frame is cleared.  Otherwise all frames' caches
+are cleared.
+@end defun
 @node Blinking
 @section Blinking Parentheses
 @cindex parenthesis matching
@@ -1451,13 +2697,19 @@ Character code 10 is a newline.
 All other codes in the range 0 through 31, and code 127, display in one
 of two ways according to the value of @code{ctl-arrow}.  If it is
 non-@code{nil}, these codes map to sequences of two glyphs, where the
-first glyph is the @sc{ASCII} code for @samp{^}.  (A display table can
+first glyph is the @sc{ascii} code for @samp{^}.  (A display table can
 specify a glyph to use instead of @samp{^}.)  Otherwise, these codes map
 just like the codes in the range 128 to 255.
 
+On MS-DOS terminals, Emacs arranges by default for the character code
+127 to be mapped to the glyph code 127, which normally displays as an
+empty polygon.  This glyph is used to display non-@sc{ascii} characters
+that the MS-DOS terminal doesn't support.  @xref{MS-DOS and MULE,,,
+emacs, The GNU Emacs Manual}.
+
 @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
+the first glyph is the @sc{ascii} code for @samp{\}, and the others are
 digit characters representing the character code in octal.  (A display
 table can specify a glyph to use instead of @samp{\}.)
 
@@ -1511,11 +2763,11 @@ stops used by the command @code{tab-to-tab-stop}.  @xref{Indent Tabs}.
 @cindex display table
 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
+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
+@dfn{glyphs}, each glyph being a graphic that takes up one character
 position on the screen.  You can also define how to display each glyph
 on your terminal, using the @dfn{glyph table}.
 
@@ -1557,9 +2809,14 @@ means to use the default for that slot, as stated below.
 @table @asis
 @item 0
 The glyph for the end of a truncated screen line (the default for this
-is @samp{$}).  @xref{Glyphs}.
+is @samp{$}).  @xref{Glyphs}.  Newer Emacs versions, on some platforms,
+display arrows to indicate truncation---the display table has no effect
+in these situations.
 @item 1
 The glyph for the end of a continued line (the default is @samp{\}).
+Newer Emacs versions, on some platforms, display curved arrows to
+indicate truncation---the display table has no effect in these
+situations.
 @item 2
 The glyph for indicating a character displayed as an octal character
 code (the default is @samp{\}).
@@ -1570,7 +2827,9 @@ A vector of glyphs for indicating the presence of invisible lines (the
 default is @samp{...}).  @xref{Selective Display}.
 @item 5
 The glyph used to draw the border between side-by-side windows (the
-default is @samp{|}).  @xref{Splitting Windows}.
+default is @samp{|}).  @xref{Splitting Windows}.  This takes effect only
+when there are no scroll bars; if scroll bars are supported and in use,
+a scroll bar separates the two windows.
 @end table
 
   For example, here is how to construct a display table that mimics the
@@ -1604,6 +2863,18 @@ This function stores @var{value} in the extra slot @var{slot} of
 @code{selective-display}, and @code{vertical-border}.
 @end defun
 
+@defun describe-display-table display-table
+@tindex describe-display-table
+This function displays a description of the display table
+@var{display-table} in a help buffer.
+@end defun
+
+@deffn Command describe-current-display-table
+@tindex describe-current-display-table
+This command displays a description of the current display table in a
+help buffer.
+@end deffn
+
 @node Active Display Table
 @subsection Active Display Table
 @cindex active display table
@@ -1645,6 +2916,9 @@ if the window specifies none, its buffer specifies none, and
 display conventions for all character codes in that window.  @xref{Usual
 Display}.
 
+A number of functions for changing the standard display table
+are defined in the library @file{disp-table}.
+
 @node Glyphs
 @subsection Glyphs
 
@@ -1694,6 +2968,12 @@ $2^{19}$.)
   If a glyph code is greater than or equal to the length of the glyph
 table, that code is automatically simple.
 
+@defun create-glyph string
+@tindex create-glyph
+This function returns a newly-allocated glyph code which is set up to
+display by sending @var{string} to the terminal.
+@end defun
+
 @node Beeping
 @section Beeping
 @cindex beeping
@@ -1747,9 +3027,11 @@ under.  The possible values are
 @cindex X Window System
 Emacs is displaying using X.
 @item pc
-Emacs is displaying using MSDOS.
+Emacs is displaying using MS-DOS.
 @item w32
-Emacs is displaying using Windows NT or Windows 95.
+Emacs is displaying using Windows NT or Windows 9x.
+@item mac
+Emacs is displaying using a Macintosh.
 @item nil
 Emacs is using a character-based terminal.
 @end table
diff --git a/lispref/edebug.texi b/lispref/edebug.texi
index c40a70d753b..d06275bb9f7 100644
--- a/lispref/edebug.texi
+++ b/lispref/edebug.texi
@@ -66,9 +66,9 @@ enable you to use it.
 * Jumping::                     Commands to jump to a specified place.
 * Misc: Edebug Misc.            Miscellaneous commands.
 * Breakpoints::                 Setting breakpoints to make the program stop.
-* Trapping Errors::             trapping errors with Edebug.
+* Trapping Errors::             Trapping errors with Edebug.
 * Views: Edebug Views.          Views inside and outside of Edebug.
-* Eval: Edebug Eval.                    Evaluating expressions within Edebug.
+* Eval: Edebug Eval.            Evaluating expressions within Edebug.
 * Eval List::                   Expressions whose values are displayed
                                   each time you enter Edebug.
 * Printing in Edebug::          Customization of printing.
@@ -89,23 +89,23 @@ first move point into the definition of a function or macro and then do
 @ref{Instrumenting}, for alternative ways to instrument code.
 
   Once a function is instrumented, any call to the function activates
-Edebug.  Activating Edebug may stop execution and let you step through
-the function, or it may update the display and continue execution while
-checking for debugging commands, depending on which Edebug execution
-mode you have selected.  The default execution mode is step, which does
-stop execution.  @xref{Edebug Execution Modes}.
+Edebug.  Depending on which Edebug execution mode you have selected,
+activating Edebug may stop execution and let you step through the
+function, or it may update the display and continue execution while
+checking for debugging commands.  The default execution mode is step,
+which stops execution.  @xref{Edebug Execution Modes}.
 
   Within Edebug, you normally view an Emacs buffer showing the source of
 the Lisp code you are debugging.  This is referred to as the @dfn{source
-code buffer}.  This buffer is temporarily read-only.
+code buffer}, and is is temporarily read-only.
 
   An arrow at the left margin indicates the line where the function is
 executing.  Point initially shows where within the line the function is
 executing, but this ceases to be true if you move point yourself.
 
   If you instrument the definition of @code{fac} (shown below) and then
-execute @code{(fac 3)}, here is what you normally see.  Point is at the
-open-parenthesis before @code{if}.
+execute @code{(fac 3)}, here is what you would normally see.  Point is
+at the open-parenthesis before @code{if}.
 
 @example
 (defun fac (n)
@@ -118,7 +118,7 @@ open-parenthesis before @code{if}.
 The places within a function where Edebug can stop execution are called
 @dfn{stop points}.  These occur both before and after each subexpression
 that is a list, and also after each variable reference.  
-Here we show with periods the stop points found in the function
+Here we use periods to show the stop points in the function
 @code{fac}:
 
 @example
@@ -163,7 +163,7 @@ into it, to invoke Edebug at the proper places.
 argument on a definition, it instruments the definition before
 evaluating it.  (The source code itself is not modified.)  If the
 variable @code{edebug-all-defs} is non-@code{nil}, that inverts the
-meaning of the prefix argument: then @kbd{C-M-x} instruments the
+meaning of the prefix argument: in this case, @kbd{C-M-x} instruments the
 definition @emph{unless} it has a prefix argument.  The default value of
 @code{edebug-all-defs} is @code{nil}.  The command @kbd{M-x
 edebug-all-defs} toggles the value of the variable
@@ -188,10 +188,11 @@ instrument any top-level form regardless of the values of
 (@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
-source for that function; after loading Edebug, @code{eval-region}
-records the position of every definition it evaluates, even if not
-instrumenting it.  See also the @kbd{i} command (@pxref{Jumping}), which
-steps into the call after instrumenting the function.
+source for that function; for this reading, after loading Edebug,
+@code{eval-region} records the position of every definition it
+evaluates, even if not instrumenting it.  See also the @kbd{i} command
+(@pxref{Jumping}), which steps into the call after instrumenting the
+function.
 
 @cindex special forms (Edebug)
 @cindex interactive commands (Edebug)
@@ -201,15 +202,16 @@ steps into the call after instrumenting the function.
 @pindex cl-specs.el
   Edebug knows how to instrument all the standard special forms,
 @code{interactive} forms with an expression argument, anonymous lambda
-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; see @ref{Instrumenting Macro Calls}, for details.
+expressions, and other defining forms.  However, Edebug cannot determine
+on its own what a user-defined macro will do with the arguments of a
+macro call, so you must provide that information; see @ref{Instrumenting
+Macro Calls}, for details.
 
   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
+@code{nil}.  You can use this to load Edebug specifications
 (@pxref{Instrumenting Macro Calls}) associated with a package you are
-using, but actually load them only if you use Edebug.
+using, but only when you use Edebug.
 
 @findex eval-expression @r{(Edebug)}
   To remove instrumentation from a definition, simply re-evaluate its
@@ -238,12 +240,12 @@ before it stops.
 
 Normally, you specify the Edebug execution mode by typing a command to
 continue the program in a certain mode.  Here is a table of these
-commands.  All except for @kbd{S} resume execution of the program, at
+commands; all except for @kbd{S} resume execution of the program, at
 least for a certain distance.
 
 @table @kbd
 @item S
-Stop: don't execute any more of the program for now, just wait for more
+Stop: don't execute any more of the program, but wait for more
 Edebug commands (@code{edebug-stop}).
 
 @item @key{SPC}
@@ -296,7 +298,7 @@ Keyboard macros containing the commands in this section do not
 completely work: exiting from Edebug, to resume the program, loses track
 of the keyboard macro.  This is not easy to fix.  Also, defining or
 executing a keyboard macro outside of Edebug does not affect commands
-inside Edebug.  This is usually an advantage.  But see the
+inside Edebug.  This is usually an advantage.  See also the
 @code{edebug-continue-kbd-macro} option (@pxref{Edebug Options}).
 
 When you enter a new Edebug level, the initial execution mode comes from
@@ -316,8 +318,8 @@ breakpoint reached before the intended stop point will also stop
 execution.  @xref{Breakpoints}, for the details on breakpoints.
 
   These commands may fail to work as expected in case of nonlocal exit,
-because a nonlocal exit can bypass the temporary breakpoint where you
-expected the program to stop.
+as that can bypass the temporary breakpoint where you expected the
+program to stop.
 
 @table @kbd
 @item h
@@ -348,13 +350,13 @@ With a prefix argument @var{n}, the temporary breakpoint is placed
 more elements, then the place to stop is after the containing
 expression.
 
-Be careful that the position @kbd{C-M-f} finds is a place that the
-program will really get to; this may not be true in a
-@code{cond}, for example.
+You must check that the position @kbd{C-M-f} finds is a place that the
+program will really get to.  In @code{cond}, for example, this may not
+be true.
 
-The @kbd{f} command does @code{forward-sexp} starting at point, rather
-than at the stop point, for flexibility.  If you want to execute one
-expression @emph{from the current stop point}, type @kbd{w} first, to
+For flexibility, the @kbd{f} command does @code{forward-sexp} starting
+at point, rather than at the stop point.  If you want to execute one
+expression @emph{from the current stop point}, first type @kbd{w}, to
 move point there, and then type @kbd{f}.
 
 The @kbd{o} command continues ``out of'' an expression.  It places a
@@ -397,7 +399,7 @@ activity.  However, instrumented code protected with
 debugging.
 
 @item Q
-Like @kbd{q} but don't stop even for protected code
+Like @kbd{q}, but don't stop even for protected code
 (@code{top-level-nonstop}).
 
 @item r
@@ -415,22 +417,21 @@ The backtrace buffer is killed automatically when you continue
 execution.
 @end table
 
-From the Edebug recursive edit, you may invoke commands that activate
-Edebug again recursively.  Any time Edebug is active, you can quit to
-the top level with @kbd{q} or abort one recursive edit level with
-@kbd{C-]}.  You can display a backtrace of all the 
-pending evaluations with @kbd{d}.
+You can invoke commands from Edebug that activate Edebug again
+recursively.  Whenever Edebug is active, you can quit to the top level
+with @kbd{q} or abort one recursive edit level with @kbd{C-]}.  You can
+display a backtrace of all the pending evaluations with @kbd{d}.
 
 @node Breakpoints
 @subsection Breakpoints
 
 @cindex breakpoints
-Edebug's step mode stops execution at the next stop point reached.
+Edebug's step mode stops execution when the next stop point is reached.
 There are three other ways to stop Edebug execution once it has started:
 breakpoints, the global break condition, and source breakpoints.
 
 While using Edebug, you can specify @dfn{breakpoints} in the program you
-are testing: points where execution should stop.  You can set a
+are testing: these are places where execution should stop.  You can set a
 breakpoint at any stop point, as defined in @ref{Using Edebug}.  For
 setting and unsetting breakpoints, the stop point that is affected is
 the first one at or after point in the source code buffer.  Here are the
@@ -440,8 +441,8 @@ Edebug commands for breakpoints:
 @item b
 Set a breakpoint at the stop point at or after point
 (@code{edebug-set-breakpoint}).  If you use a prefix argument, the
-breakpoint is temporary (it turns off the first time it stops the
-program).
+breakpoint is temporary---it turns off the first time it stops the
+program.
 
 @item u
 Unset the breakpoint (if any) at the stop point at or after 
@@ -463,7 +464,8 @@ with @kbd{u}.  First move point to the Edebug stop point of your choice,
 then type @kbd{b} or @kbd{u} to set or unset a breakpoint there.
 Unsetting a breakpoint where none has been set has no effect.
 
-Re-evaluating or reinstrumenting a definition forgets all its breakpoints.
+Re-evaluating or reinstrumenting a definition removes all of its
+previous breakpoints.
 
 A @dfn{conditional breakpoint} tests a condition each time the program
 gets there.  Any errors that occur as a result of evaluating the
@@ -478,7 +480,7 @@ You can make a conditional or unconditional breakpoint
 breakpoint.  When a temporary breakpoint stops the program, it is
 automatically unset.
 
-Edebug always stops or pauses at a breakpoint except when the Edebug
+Edebug always stops or pauses at a breakpoint, except when the Edebug
 mode is Go-nonstop.  In that mode, it ignores breakpoints entirely.
 
 To find out where your breakpoints are, use the @kbd{B} command, which
@@ -500,7 +502,7 @@ point in the buffer.
 @cindex global break condition
   A @dfn{global break condition} stops execution when a specified
 condition is satisfied, no matter where that may occur.  Edebug
-evaluates the global break condition at every stop point.  If it
+evaluates the global break condition at every stop point; if it
 evaluates to a non-@code{nil} value, then execution stops or pauses
 depending on the execution mode, as if a breakpoint had been hit.  If
 evaluating the condition gets an error, execution does not stop.
@@ -520,11 +522,12 @@ should reset the condition to @code{nil} when not using it.
 @findex edebug
 @cindex source breakpoints
   All breakpoints in a definition are forgotten each time you
-reinstrument it.  To make a breakpoint that won't be forgotten, you can
-write a @dfn{source breakpoint}, which is simply a call to the function
-@code{edebug} in your source code.  You can, of course, make such a call
-conditional.  For example, in the @code{fac} function, insert the first
-line as shown below to stop when the argument reaches zero:
+reinstrument it.  If you wish to make a breakpoint that won't be
+forgotten, you can write a @dfn{source breakpoint}, which is simply a
+call to the function @code{edebug} in your source code.  You can, of
+course, make such a call conditional.  For example, in the @code{fac}
+function, you can insert the first line as shown below, to stop when the
+argument reaches zero:
 
 @example
 (defun fac (n)
@@ -553,10 +556,10 @@ and @code{edebug-on-quit}; see @ref{Edebug Options}.
 
   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
+function which was not instrumented, and within which the error actually
 occurred.  For an unbound variable error, the last known stop point
 might be quite distant from the offending variable reference.  In that
-case you might want to display a full backtrace (@pxref{Edebug Misc}).
+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
@@ -616,12 +619,12 @@ open.
 @node Edebug Eval
 @subsection Evaluation
 
-  While within Edebug, you can evaluate expressions ``as if'' Edebug were
-not running.  Edebug tries to be invisible to the expression's
+  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
-saves and restores.  @xref{The Outside Context}, for details on this
-process.
+effects will work as expected, except for changes to data that Edebug
+explicitly saves and restores.  @xref{The Outside Context}, for details
+on this process.
 
 @table @kbd
 @item e @var{exp} @key{RET}
@@ -739,9 +742,9 @@ eval-last-sexp
 To delete a group, move point into it and type @kbd{C-c C-d}, or simply
 delete the text for the group and update the evaluation list with
 @kbd{C-c C-u}.  To add a new expression to the evaluation list, insert
-the expression at a suitable place, and insert a new comment line.  (You
-need not insert dashes in the comment line---its contents don't matter.)
-Then type @kbd{C-c C-u}.
+the expression at a suitable place, insert a new comment line, then type
+@kbd{C-c C-u}.  You need not insert dashes in the comment line---its
+contents don't matter.
 
 After selecting @samp{*edebug*}, you can return to the source code
 buffer with @kbd{C-c C-w}.  The @samp{*edebug*} buffer is killed when
@@ -764,22 +767,18 @@ 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}.
+If non-@code{nil}, Edebug binds @code{print-length} to this value while
+printing results.  The default value is @code{50}.
 @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}.
+If non-@code{nil}, Edebug binds @code{print-level} to this value while
+printing results.  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.
-
-  To load @file{cust-print} and activate custom printing only for
-Edebug, simply use the command @kbd{M-x edebug-install-custom-print}.
-To restore the standard print functions, use @kbd{M-x
-edebug-uninstall-custom-print}.
+elements more informatively by binding @code{print-circle}
+to a non-@code{nil} value.
 
   Here is an example of code that creates a circular structure:
 
@@ -796,8 +795,8 @@ 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}.
+If non-@code{nil}, Edebug binds @code{print-circle} to this value while
+printing results.  The default value is @code{nil}.
 @end defopt
 
   Other programs can also use custom printing; see @file{cust-print.el}
@@ -816,9 +815,9 @@ trace recording, set @code{edebug-trace} to a non-@code{nil} value.
 mode (@pxref{Edebug Execution Modes}).
 
   When trace recording is enabled, each function entry and exit adds
-lines to the trace buffer.  A function entry record looks like
-@samp{::::@{} followed by the function name and argument values.  A
-function exit record looks like @samp{::::@}} followed by the function
+lines to the trace buffer.  A function entry record consists of
+@samp{::::@{}, followed by the function name and argument values.  A
+function exit record consists of @samp{::::@}}, followed by the function
 name and result of the function.
 
   The number of @samp{:}s in an entry shows its recursion depth.  You
@@ -834,7 +833,7 @@ redefining the functions @code{edebug-print-trace-before} and
 @defmac edebug-tracing string body@dots{}
 This macro requests additional trace information around the execution
 of the @var{body} forms.  The argument @var{string} specifies text
-to put in the trace buffer.  All the arguments are evaluated.
+to put in the trace buffer.  All the arguments are evaluated, and
 @code{edebug-tracing} returns the value of the last form in @var{body}.
 @end defmac
 
@@ -964,15 +963,15 @@ the current window configuration from ``outside'' Edebug
 the program), it restores the previous window configuration.
 
 Emacs redisplays only when it pauses.  Usually, when you continue
-execution, the program comes back into Edebug at a breakpoint or after
-stepping without pausing or reading input in between.  In such cases,
+execution, the program re-enters Edebug at a breakpoint or after
+stepping, without pausing or reading input in between.  In such cases,
 Emacs never gets a chance to redisplay the ``outside'' configuration.
-What you see is the same window configuration as the last time Edebug
-was active, with no interruption.
+Consequently, what you see is the same window configuration as the last
+time Edebug was active, with no interruption.
 
 Entry to Edebug for displaying something also saves and restores the
-following data, but some of these are deliberately not restored if an
-error or quit signal occurs.
+following data (though some of them are deliberately not restored if an
+error or quit signal occurs).
 
 @itemize @bullet
 @item 
diff --git a/lispref/elisp.texi b/lispref/elisp.texi
index aebd78d50c6..182d9d121f3 100644
--- a/lispref/elisp.texi
+++ b/lispref/elisp.texi
@@ -12,8 +12,8 @@
 @smallbook
 
 @ifinfo
-This Info file contains edition 2.5.1 of the GNU Emacs Lisp
-Reference Manual, corresponding to Emacs version 20.4.
+This Info file contains edition 2.6 of the GNU Emacs Lisp
+Reference Manual, corresponding to Emacs version 21.1.
 @c Please REMEMBER to update edition number in *four* places in this file
 @c                 and also in *one* place in intro.texi
 
@@ -75,7 +75,7 @@ instead of in the original English.
 @subtitle For Emacs Version 20.4
 @c The edition number appears in several places in this file
 @c and also in the file intro.texi.
-@subtitle Revision 2.5.1, January 1999
+@subtitle Revision 2.6, September 1999
 
 @author by Bil Lewis, Dan LaLiberte, Richard Stallman
 @author and the GNU Manual Group
@@ -85,11 +85,11 @@ Copyright @copyright{} 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998, 1999
 Free Software Foundation, Inc. 
 
 @sp 2
-Edition 2.5.1 @*
-Revised for Emacs Version 20.4,@*
-January 1999.@*
+Edition 2.6 @*
+Revised for Emacs Version 21.1,@*
+September 1999.@*
 @sp 2
-ISBN 1-882114-72-8
+ISBN 1-882114-73-6
 
 @sp 2
 Published by the Free Software Foundation @*
@@ -120,8 +120,8 @@ Cover art by Etienne Suvasa.
 @node Top, Copying, (dir), (dir)
 
 @ifinfo
-This Info file contains edition 2.5.1 of the GNU Emacs Lisp
-Reference Manual, corresponding to GNU Emacs version 20.4.
+This Info file contains edition 2.6 of the GNU Emacs Lisp
+Reference Manual, corresponding to GNU Emacs version 21.1.
 @end ifinfo
 
 @menu
@@ -136,6 +136,7 @@ Reference Manual, corresponding to GNU Emacs version 20.4.
 * Sequences Arrays Vectors::  Lists, strings and vectors are called sequences.
                                 Certain functions act on any kind of sequence.
                                 The description of vectors is here as well.
+* Hash Tables::             Very fast lookup-tables.
 * Symbols::                 Symbols represent names, uniquely.
 
 * Evaluation::              How Lisp expressions are evaluated.
@@ -867,10 +868,10 @@ Operating System Interface
 
 Starting Up Emacs
 
-* Start-up Summary::        Sequence of actions Emacs performs at start-up.
+* Startup Summary::         Sequence of actions Emacs performs at start-up.
 * Init File::               Details on reading the init file (@file{.emacs}).
 * Terminal-Specific::       How the terminal-specific Lisp file is read.
-* Command Line Arguments::  How command line arguments are processed,
+* Command-Line Arguments::  How command line arguments are processed,
                               and how you can customize them.
 
 Getting out of Emacs
@@ -914,6 +915,7 @@ Object Internals
 
 @include lists.texi
 @include sequences.texi
+@include hash.texi
 @include symbols.texi
 @include eval.texi
 
diff --git a/lispref/errors.texi b/lispref/errors.texi
index 700884ebd67..e58e99d537f 100644
--- a/lispref/errors.texi
+++ b/lispref/errors.texi
@@ -64,12 +64,12 @@ See @code{/} and @code{%} in @ref{Numbers}.
 
 @item end-of-file
 @code{"End of file during parsing"}@*
-Note that this is not a @code{file-error}
+Note that this is not a subcategory of @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}.@*
+This is a subcategory of @code{file-error}.@*
 @xref{Writing to Files}.
 
 @item file-date-error
@@ -84,11 +84,11 @@ condition @code{file-error} is present.@*
 @xref{Files}.
 
 @item file-locked     
-This is a @code{file-error}.@*
+This is a subcategory of @code{file-error}.@*
 @xref{File Locks}.
 
 @item file-supersession
-This is a @code{file-error}.@*
+This is a subcategory of @code{file-error}.@*
 @xref{Modification Time}.
 
 @item invalid-function
diff --git a/lispref/files.texi b/lispref/files.texi
index a94cb2c080e..f82e724e4da 100644
--- a/lispref/files.texi
+++ b/lispref/files.texi
@@ -126,7 +126,7 @@ the user whether to reread the changed file.  If the user says
 This function displays warning or advisory messages in various peculiar
 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
+@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
@@ -260,7 +260,7 @@ and by the default revert function (@pxref{Reverting}).
 If reading the file got an error because the file does not exist, but
 its directory does exist, the caller should pass a non-@code{nil} value
 for @var{error}.  In that case, @code{after-find-file} issues a warning:
-@samp{(New File)}.  For more serious errors, the caller should usually not
+@samp{(New file)}.  For more serious errors, the caller should usually not
 call @code{after-find-file}.
 
 If @var{warn} is non-@code{nil}, then this function issues a warning
@@ -312,7 +312,7 @@ 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}
-buffer-local value of @code{buffer-offer-save}.  (A user who says yes to
+buffer-local value of @code{buffer-offer-save}.  (A user who says @samp{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.
@@ -447,7 +447,9 @@ The function @code{insert-file-contents} checks the file contents
 against the defined file formats, and converts the file contents if
 appropriate.  @xref{Format Conversion}.  It also calls the functions in
 the list @code{after-insert-file-functions}; see @ref{Saving
-Properties}.
+Properties}.  Normally, one of the functions in the
+@code{after-insert-file-functions} list determines the coding system
+(@pxref{Coding Systems}) used for decoding the file's contents.
 
 If @var{visit} is non-@code{nil}, this function additionally marks the
 buffer as unmodified and sets up various fields in the buffer so that it
@@ -510,19 +512,29 @@ An error is signaled if @var{filename} specifies a nonwritable file,
 or a nonexistent file in a directory where files cannot be created.
 @end deffn
 
-@deffn Command write-region start end filename &optional append visit confirm
+@deffn Command write-region start end filename &optional append visit mustbenew
 This function writes the region delimited by @var{start} and @var{end}
 in the current buffer into the file specified by @var{filename}.
 
 @c Emacs 19 feature
 If @var{start} is a string, then @code{write-region} writes or appends
-that string, rather than text from the buffer.
+that string, rather than text from the buffer.  @var{end} is ignored in
+this case.
 
 If @var{append} is non-@code{nil}, then the specified text is appended
 to the existing file contents (if any).
 
-If @var{confirm} is non-@code{nil}, then @code{write-region} asks
+If @var{mustbenew} is non-@code{nil}, then @code{write-region} asks
 for confirmation if @var{filename} names an existing file.
+Starting in Emacs 21, if @var{mustbenew} is the symbol @code{excl}, 
+then @code{write-region} does not ask for confirmation, but instead
+it signals an error @code{file-already-exists} if the file already
+exists.
+
+The test for an existing file, when @var{mustbenew} is @code{excl}, uses
+a special system feature.  At least for files on a local disk, there is
+no chance that some other program could create a file of the same name
+before Emacs does, without Emacs's noticing.
 
 If @var{visit} is @code{t}, then Emacs establishes an association
 between the buffer and the file: the buffer is then visiting that file.
@@ -615,6 +627,10 @@ the file should not be locked, so this function does nothing.  It also
 does nothing if the current buffer is not visiting a file.
 @end defun
 
+  File locking is not supported on some systems.  On systems that do not
+support it, the functions @code{lock-buffer}, @code{unlock-buffer} and
+@code{file-locked-p} do nothing and return @code{nil}.
+
 @defun ask-user-about-lock file other-user
 This function is called when the user tries to modify @var{file}, but it
 is locked by another user named @var{other-user}.  The default
@@ -710,10 +726,10 @@ and you can read it.  It returns @code{nil} otherwise.
 @c Emacs 19 feature
 @defun file-executable-p filename
 This function returns @code{t} if a file named @var{filename} exists and
-you can execute it.  It returns @code{nil} otherwise.  If the file is a
-directory, execute permission means you can check the existence and
-attributes of files inside the directory, and open those files if their
-modes permit.
+you can execute it.  It returns @code{nil} otherwise.  On Unix, if the
+file is a directory, execute permission means you can check the
+existence and attributes of files inside the directory, and open those
+files if their modes permit.
 @end defun
 
 @defun file-writable-p filename
@@ -1081,7 +1097,8 @@ was last modified on Aug 19 00:09.
 last had its inode changed on Aug 19 00:09.
 
 @item 14906
-is 14906 characters long.
+is 14906 bytes long.  (It may not contain 14906 characters, though,
+if some of the bytes belong to multibyte sequences.)
 
 @item "-rw-rw-rw-"
 has a mode of read and write access for the owner, group, and world.
@@ -1186,7 +1203,8 @@ contents of @file{foo3} are lost.
 @end example
 
 This function is meaningless on operating systems where multiple names
-for one file are not allowed.
+for one file are not allowed.  Some systems implement multiple names
+by copying the file instead.
 
 See also @code{file-nlinks} in @ref{File Attributes}.
 @end defun
@@ -1241,6 +1259,9 @@ This command makes a symbolic link to @var{filename}, named
 In an interactive call, this function prompts for @var{filename} and
 @var{newname} in the minibuffer; also, it requests confirmation if
 @var{newname} already exists.
+
+This function is not available on systems that don't support symbolic
+links.
 @end deffn
 
 @defun define-logical-name varname string
@@ -1275,9 +1296,13 @@ This function returns the current default protection value.
 @cindex MS-DOS and file modes
 @cindex file modes and MS-DOS
   On MS-DOS, there is no such thing as an ``executable'' file mode bit.
-So Emacs considers a file executable if its name ends in @samp{.com},
-@samp{.bat} or @samp{.exe}.  This is reflected in the values returned
-by @code{file-modes} and @code{file-attributes}.
+So Emacs considers a file executable if its name ends in one of the
+standard executable extensions, such as @file{.com}, @file{.bat},
+@file{.exe}, and some others.  Files that begin with the Unix-standard
+@samp{#!} signature, such as shell and Perl scripts, are also considered
+as executable files.  This is reflected in the values returned by
+@code{file-modes} and @code{file-attributes}.  Directories are also
+reported with executable bit set, for compatibility with Unix.
 
 @node File Names
 @section File Names
@@ -1327,22 +1352,22 @@ parts: the @dfn{directory name} part, and the @dfn{nondirectory} part
 (or @dfn{file name within the directory}).  Either part may be empty.
 Concatenating these two parts reproduces the original file name.
 
-  On Unix, the directory part is everything up to and including the last
-slash; the nondirectory part is the rest.  The rules in VMS syntax are
-complicated.
+  On most systems, the directory part is everything up to and including
+the last slash; the nondirectory part is the rest.  The rules in VMS
+syntax are complicated.
 
   For some purposes, the nondirectory part is further subdivided into
-the name proper and the @dfn{version number}.  On Unix, only backup
-files have version numbers in their names.  On VMS, every file has a
-version number, but most of the time the file name actually used in
-Emacs omits the version number, so that version numbers in Emacs are
+the name proper and the @dfn{version number}.  On most systems, only
+backup files have version numbers in their names.  On VMS, every file
+has a version number, but most of the time the file name actually used
+in Emacs omits the version number, so that version numbers in Emacs are
 found mostly in directory lists.
 
 @defun file-name-directory filename
 This function returns the directory part of @var{filename} (or
 @code{nil} if @var{filename} does not include a directory part).  On
-Unix, the function returns a string ending in a slash.  On VMS, it
-returns a string ending in one of the three characters @samp{:},
+most systems, the function returns a string ending in a slash.  On VMS,
+it returns a string ending in one of the three characters @samp{:},
 @samp{]}, or @samp{>}.
 
 @example
@@ -1429,7 +1454,7 @@ The extension, in a file name, is the part that starts with the last
 kind of file, and it has a file name, which is related to the directory
 name but not identical to it.  (This is not quite the same as the usual
 Unix terminology.)  These two different names for the same entity are
-related by a syntactic transformation.  On Unix, this is simple: a
+related by a syntactic transformation.  On most systems, this is simple: a
 directory name ends in a slash, whereas the directory's name as a file
 lacks that slash.  On VMS, the relationship is more complicated.
 
@@ -1444,9 +1469,9 @@ such as @samp{$HOME}, and the constructs @samp{~}, and @samp{..}.
 
 @defun file-name-as-directory filename
 This function returns a string representing @var{filename} in a form
-that the operating system will interpret as the name of a directory.  In
-Unix, this means appending a slash to the string (if it does not already
-end in one).  On VMS, the function converts a string of the form
+that the operating system will interpret as the name of a directory.  On
+most systems, this means appending a slash to the string (if it does not
+already end in one).  On VMS, the function converts a string of the form
 @file{[X]Y.DIR.1} to the form @file{[X.Y]}.
 
 @example
@@ -1459,9 +1484,9 @@ end in one).  On VMS, the function converts a string of the form
 
 @defun directory-file-name dirname
 This function returns a string representing @var{dirname} in a form that
-the operating system will interpret as the name of a file.  On Unix,
-this means removing the final slash from the string.  On VMS, the
-function converts a string of the form @file{[X.Y]} to
+the operating system will interpret as the name of a file.  On most
+systems, this means removing the final slash from the string.  On VMS,
+the function converts a string of the form @file{[X.Y]} to
 @file{[X]Y.DIR.1}.
 
 @example
@@ -1522,8 +1547,10 @@ starting from the root of the tree; then it is called an @dfn{absolute}
 file name.  Or it can specify the position of the file in the tree
 relative to a default directory; then it is called a @dfn{relative}
 file name.  On Unix, an absolute file name starts with a slash or a
-tilde (@samp{~}), and a relative one does not.  The rules on VMS are
-complicated.
+tilde (@samp{~}), and a relative one does not.  On MS-DOS and
+MS-Windows, an absolute file name starts with a slash or a backslash, or
+with a drive specification @samp{@var{x}:/}, where @var{x} is the
+@dfn{drive letter}. The rules on VMS are complicated.
 
 @defun file-name-absolute-p filename
 This function returns @code{t} if file @var{filename} is an absolute
@@ -1625,7 +1652,7 @@ 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}.
 
-On Unix systems, the value is always a string ending with a slash.
+Aside from VMS, the value is always a string ending with a slash.
 
 @example
 @group
@@ -1680,45 +1707,74 @@ on VMS except discard superfluous initial components as shown above.
 @subsection Generating Unique File Names
 
   Some programs need to write temporary files.  Here is the usual way to
-construct a name for such a file:
+construct a name for such a file, starting in Emacs 21:
 
 @example
-(make-temp-name
- (expand-file-name @var{name-of-application}
-                   temporary-file-directory))
+(make-temp-file @var{name-of-application})
 @end example
 
 @noindent
-The job of @code{make-temp-name} is to prevent two different users or
-two different jobs from trying to use the exact same file name.  This
-example uses the variable @code{temporary-file-directory} to decide
-where to put the temporary file.  All Emacs Lisp programs should
-use @code{temporary-file-directory} for this purpose, to give the user
-a uniform way to specify the directory for all temporary files.
+The job of @code{make-temp-file} is to prevent two different users or
+two different jobs from trying to use the exact same file name.
 
-@defun make-temp-name string
-This function generates a string that can be used as a unique file name.
-The name starts with @var{string}, and contains a number that is
-different in each Emacs job.
+@defun make-temp-file prefix &optional dir-flag
+@tindex make-temp-file
+This function creates a temporary file and returns its name.
+The name starts with @var{prefix}; it also contains a number that is
+different in each Emacs job.  If @var{prefix} is a relative file name,
+it is expanded against @code{temporary-file-directory}.
 
 @example
 @group
-(make-temp-name "/tmp/foo")
+(make-temp-file "foo")
      @result{} "/tmp/foo232J6v"
 @end group
 @end example
 
+When @code{make-temp-file} returns, the file has been created and is
+empty.  At that point, you should write the intended contents into the
+file.
+
+If @var{dir-flag} is non-@code{nil}, @code{make-temp-file} creates
+an empty directory instead of an empty file.
+
 To prevent conflicts among different libraries running in the same
-Emacs, each Lisp program that uses @code{make-temp-name} should have its
-own @var{string}.  The number added to the end of @var{string}
+Emacs, each Lisp program that uses @code{make-temp-file} should have its
+own @var{prefix}.  The number added to the end of @var{prefix}
 distinguishes between the same application running in different Emacs
 jobs.  Additional added characters permit a large number of distinct
 names even in one Emacs job.
 @end defun
 
+  The default directory for temporary files is controlled by the
+variable @code{temporary-file-directory}.  This variable gives the user
+a uniform way to specify the directory for all temporary files.  Some
+programs use @code{small-temporary-file-directory} instead, if that is
+non-@code{nil}.  To use it, you should expand the prefix against
+the proper directory before calling @code{make-temp-file}.
+
+  In older Emacs versions where @code{make-temp-file} does not exist,
+you should use @code{make-temp-name} instead:
+
+@example
+(make-temp-name
+ (expand-file-name @var{name-of-application}
+                   temporary-file-directory))
+@end example
+
+@defun make-temp-name string
+This function generates a string that can be used as a unique file name.
+The name starts with @var{string}, and contains a number that is
+different in each Emacs job.  It is like @code{make-temp-file} except
+that it just constructs a name, and does not create a file.  On MS-DOS,
+the @var{string} prefix can be truncated to fit into the 8+3 file-name
+limits.
+@end defun
+
 @defvar temporary-file-directory
-@cindex @code{TMPDIR} environment variable.
-@cindex @code{TMP} environment variable.
+@cindex @code{TMPDIR} environment variable
+@cindex @code{TMP} environment variable
+@cindex @code{TEMP} environment variable
 This variable specifies the directory name for creating temporary files.
 Its value should be a directory name (@pxref{Directory Names}), but it
 is good for Lisp programs to cope if the value is a directory's file
@@ -1726,12 +1782,31 @@ name instead.  Using the value as the second argument to
 @code{expand-file-name} is a good way to achieve that.
 
 The default value is determined in a reasonable way for your operating
-system; on GNU and Unix systems it is based on the @code{TMP} and
-@code{TMPDIR} environment variables.
+system; it is based on the @code{TMPDIR}, @code{TMP} and @code{TEMP}
+environment variables, with a fall-back to a system-dependent name if
+none of these variables is defined.
 
 Even if you do not use @code{make-temp-name} to choose the temporary
 file's name, you should still use this variable to decide which
-directory to put the file in.
+directory to put the file in.  However, if you expect the file to be
+small, you should use @code{small-temporary-file-directory} first if
+that is non-@code{nil}.
+@end defvar
+
+@tindex small-temporary-file-directory
+@defvar small-temporary-file-directory
+This variable (new in Emacs 21) specifies the directory name for
+creating certain temporary files, which are likely to be small.
+
+If you want to write a temporary file which is likely to be small, you
+should compute the directory like this:
+
+@example
+(make-temp-file
+  (expand-file-name @var{prefix}
+                    (or small-temporary-file-directory
+                        temporary-file-directory)))
+@end example
 @end defvar
 
 @node File Name Completion
@@ -1953,15 +2028,20 @@ not contain @samp{-d}.  (The @samp{-d} option to @code{ls} says to
 describe a directory itself as a file, rather than showing its
 contents.)
 
-This function works by running a directory listing program whose name is
-in the variable @code{insert-directory-program}.  If @var{wildcard} is
-non-@code{nil}, it also runs the shell specified by
+On most systems, this function works by running a directory listing
+program whose name is in the variable @code{insert-directory-program}.
+If @var{wildcard} is non-@code{nil}, it also runs the shell specified by
 @code{shell-file-name}, to expand the wildcards.
+
+MS-DOS and MS-Windows systems usually lack the standard Unix program
+@code{ls}, so this function emulates the standard Unix program @code{ls}
+with Lisp code.
 @end defun
 
 @defvar insert-directory-program
 This variable's value is the program to run to generate a directory listing
-for the function @code{insert-directory}.
+for the function @code{insert-directory}.  It is ignored on systems
+which generate the listing with Lisp code.
 @end defvar
 
 @node Create/Delete Dirs
@@ -2070,6 +2150,7 @@ Here are the operations that a magic file name handler gets to handle:
 @end ifinfo
 @iftex
 @noindent
+@flushleft
 @code{add-name-to-file}, @code{copy-file}, @code{delete-directory},
 @code{delete-file},
 @code{diff-latest-backup-file},
@@ -2103,6 +2184,7 @@ Here are the operations that a magic file name handler gets to handle:
 @code{vc-regis@discretionary{}{}{}tered},
 @code{verify-visited-file-modtime},
 @code{write-region}.
+@end flushleft
 @end iftex
 
 Handlers for @code{insert-file-contents} typically need to clear the
diff --git a/lispref/frames.texi b/lispref/frames.texi
index b75f9529060..b371e658b6c 100644
--- a/lispref/frames.texi
+++ b/lispref/frames.texi
@@ -24,8 +24,22 @@ 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
-@code{nil} otherwise.
+This predicate returns a non-@code{nil} value if @var{object} is a
+frame, and @code{nil} otherwise.  For a frame, the value indicates which
+kind of display the frame uses:
+
+@table @code
+@item x
+The frame is displayed in an X window.
+@item t
+A terminal frame on a character display.
+@item mac
+The frame is displayed on a Macintosh.
+@item w32
+The frame is displayed on MS-Windows 9X/NT.
+@item pc
+The frame is displayed on an MS-DOS terminal.
+@end table
 @end defun
 
 @menu
@@ -49,10 +63,8 @@ This predicate returns @code{t} if @var{object} is a frame, and
 * Dialog Boxes::                Displaying a box to ask yes or no.
 * Pointer Shapes::              Specifying the shape of the mouse pointer.
 * Window System Selections::    Transferring text to and from other X clients.
-* Font Names::                  Looking up font names.
-* Fontsets::                    A fontset is a collection of fonts
-                                  for displaying various character sets.
 * Color Names::                 Getting the definitions of color names.
+* Text Terminal Colors::        Defining colors for text-only terminals.
 * Resources::                   Getting resource values from the server.
 * Server Data::                 Getting info about the X server.
 @end menu
@@ -86,8 +98,8 @@ A normal hook run by @code{make-frame} before it actually creates the
 frame.
 @end defvar
 
-@defvar after-make-frame-hook
-@tindex after-make-frame-hook
+@defvar after-make-frame-functions
+@tindex after-make-frame-functions
 An abnormal hook run by @code{make-frame} after it creates the frame.
 Each function in @code{after-make-frame-hook} receives one argument, the
 frame just created.
@@ -163,14 +175,17 @@ that display (@pxref{Deleting Frames}).
 @node Frame Parameters
 @section Frame Parameters
 
-A frame has many parameters that control its appearance and behavior.
+  A frame has many parameters that control its appearance and behavior.
 Just what parameters a frame has depends on what display mechanism it
 uses.
 
-Frame parameters exist for the sake of window systems.  A terminal frame
-has a few parameters, mostly for compatibility's sake; only the @code{height},
-@code{width}, @code{name}, @code{title}, @code{buffer-list} and
-@code{buffer-predicate} parameters do something special.
+  Frame parameters exist mostly for the sake of window systems.  A
+terminal frame has a few parameters, mostly for compatibility's sake;
+only the @code{height}, @code{width}, @code{name}, @code{title},
+@code{menu-bar-lines}, @code{buffer-list} and @code{buffer-predicate}
+parameters do something special.  If the terminal supports colors, the
+parameters @code{foreground-color}, @code{background-color},
+@code{background-mode} and @code{display-type} are also meaningful.
 
 @menu
 * Parameter Access::       How to change a frame's parameters.
@@ -222,7 +237,7 @@ created initial frame.
 If these settings affect the frame geometry and appearance, you'll see
 the frame appear with the wrong ones and then change to the specified
 ones.  If that bothers you, you can specify the same geometry and
-appearance with X resources; those do take affect before the frame is
+appearance with X resources; those do take effect before the frame is
 created.  @xref{Resources X,, X Resources, emacs, The GNU Emacs Manual}.
 
 X resource settings typically apply to all frames.  If you want to
@@ -391,7 +406,9 @@ ordered most-recently-selected first.
 @item font
 The name of the font for displaying text in the frame.  This is a
 string, either a valid font name for your system or the name of an Emacs
-fontset (@pxref{Fontsets}).
+fontset (@pxref{Fontsets}).  Changing this frame parameter on a frame,
+also changes the font-related attributes of the default face on that
+frame.
 
 @item auto-raise
 Whether selecting the frame raises it (non-@code{nil} means yes).
@@ -424,30 +441,40 @@ 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
-window system defines the meaningful color names.
-
-If you set the @code{foreground-color} frame parameter, you should
-call @code{frame-update-face-colors} to update faces accordingly.
+window system defines the meaningful color names.  Changing this
+parameter is equivalent to changing the foreground color of the face
+@code{default} on the frame in question.
 
 @item background-color
-The color to use for the background of characters.
-
-If you set the @code{background-color} frame parameter, you should
-call @code{frame-update-face-colors} to update faces accordingly.
-@xref{Face Functions}.
+The color to use for the background of characters.  Changing this
+parameter is equivalent to changing the foreground color of the face
+@code{default} on the frame in question.
 
 @item background-mode
 This parameter is either @code{dark} or @code{light}, according
 to whether the background color is a light one or a dark one.
 
 @item mouse-color
-The color for the mouse pointer.
+The color for the mouse pointer.  Changing this parameter is equivalent
+to changing the background color of face @code{mouse}.
 
 @item cursor-color
-The color for the cursor that shows point.
+The color for the cursor that shows point. Changing this parameter is
+equivalent to changing the background color of face @code{cursor}.
 
 @item border-color
-The color for the border of the frame.
+The color for the border of the frame. Changing this parameter is
+equivalent to changing the background color of face @code{border}.
+
+@item scroll-bar-foreground
+If non-@code{nil}, the color for the foreground of scroll bars.
+Changing this parameter is equivalent to setting the foreground color of
+face @code{scroll-bar}.
+
+@item scroll-bar-background
+If non-@code{nil}, the color for the background of scroll bars.
+Changing this parameter is equivalent to setting the foreground color of
+face @code{scroll-bar}.
 
 @item display-type
 This parameter describes the range of possible colors that can be used
@@ -482,6 +509,17 @@ The default is 1.  @xref{Menu Bar}.  (In Emacs versions that use the X
 toolkit, there is only one menu bar line; all that matters about the
 number you specify is whether it is greater than zero.)
 
+@item screen-gamma
+If this is a number, Emacs performs ``gamma correction'' on colors.  The
+value should be the screen gamma of your display, a floating point
+number.  Usual PC monitors have a screen gamma of 2.2.  Smaller values
+result in darker colors; you might want to try a screen gamma of 1.5 for
+LCD color displays.  The viewing gamma Emacs uses is 0.4545 (1/2.2).
+
+@item tool-bar-lines
+The number of lines to use for the toolbar.  A value of @code{nil} means
+don't display a tool bar.
+
 @ignore
 @item parent-id
 @c ??? Not yet working.
@@ -755,7 +793,7 @@ upper left corner, down and to the right, until it reaches the window at
 the lower right corner (always the minibuffer window, if the frame has
 one), and then it moves back to the top.  @xref{Cyclic Window Ordering}.
 
-@defun frame-top-window frame
+@defun frame-first-window frame
 This returns the topmost, leftmost window of frame @var{frame}.
 @end defun
 
@@ -1309,180 +1347,160 @@ like the way successive kills in Emacs move down the kill ring.
 @defvar selection-coding-system
 @tindex selection-coding-system
 This variable specifies the coding system to use when reading and
-writing a selections, the clipboard, or a cut buffer.  @xref{Coding
+writing selections, the clipboard, or a cut buffer.  @xref{Coding
 Systems}.  The default is @code{compound-text}.
 @end defvar
 
-@need 1500
-@node Font Names
-@section Looking up Font Names
-
-@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 @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
-@samp{?} character matches any single character.  Pattern matching
-of font names ignores case.
-
-If you specify @var{face} and @var{frame}, @var{face} should be a face name
-(a symbol) and @var{frame} should be a frame.
-
-The optional argument @var{maximum} sets a limit on how many fonts to
-return.  If this is non-@code{nil}, then the return value is truncated
-after the first @var{maximum} matching fonts.  Specifying a small value
-for @var{maximum} can make this function much faster, in cases where
-many fonts match the pattern.
-@end defun
-
-@node Fontsets
-@section Fontsets
-
-  A @dfn{fontset} is a list of fonts, each assigned to a range of
-character codes.  An individual font cannot display the whole range of
-characters that Emacs supports, but a fontset can.  Fontsets have names,
-just as fonts do, and you can use a fontset name in place of a font name
-when you specify the ``font'' for a frame or a face.  Here is
-information about defining a fontset under Lisp program control.
-
-@defun create-fontset-from-fontset-spec fontset-spec &optional style-variant-p noerror
-This function defines a new fontset according to the specification
-string @var{fontset-spec}.  The string should have this format:
-
-@smallexample
-@var{fontpattern}, @r{[}@var{charsetname}:@var{fontname}@r{]@dots{}}
-@end smallexample
-
-@noindent
-Whitespace characters before and after the commas are ignored.
-
-The first part of the string, @var{fontpattern}, should have the form of
-a standard X font name, except that the last two fields should be
-@samp{fontset-@var{alias}}.
-
-The new fontset has two names, one long and one short.  The long name is
-@var{fontpattern} in its entirety.  The short name is
-@samp{fontset-@var{alias}}.  You can refer to the fontset by either
-name.  If a fontset with the same name already exists, an error is
-signaled, unless @var{noerror} is non-@code{nil}, in which case this
-function does nothing.
-
-If optional argument @var{style-variant-p} is non-@code{nil}, that says
-to create bold, italic and bold-italic variants of the fontset as well.
-These variant fontsets do not have a short name, only a long one, which
-is made by altering @var{fontpattern} to indicate the bold or italic
-status.
-
-The specification string also says which fonts to use in the fontset.
-See below for the details.
-@end defun
-
-  The construct @samp{@var{charset}:@var{font}} specifies which font to
-use (in this fontset) for one particular character set.  Here,
-@var{charset} is the name of a character set, and @var{font} is the font
-to use for that character set.  You can use this construct any number of
-times in the specification string.
-
-  For the remaining character sets, those that you don't specify
-explicitly, Emacs chooses a font based on @var{fontpattern}: it replaces
-@samp{fontset-@var{alias}} with a value that names one character set.
-For the @sc{ASCII} character set, @samp{fontset-@var{alias}} is replaced
-with @samp{ISO8859-1}.
-
-  In addition, when several consecutive fields are wildcards, Emacs
-collapses them into a single wildcard.  This is to prevent use of
-auto-scaled fonts.  Fonts made by scaling larger fonts are not usable
-for editing, and scaling a smaller font is not useful because it is
-better to use the smaller font in its own size, which Emacs does.
-
-  Thus if @var{fontpattern} is this,
-
-@example
--*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24
-@end example
-
-@noindent
-the font specification for ASCII characters would be this:
-
-@example
--*-fixed-medium-r-normal-*-24-*-ISO8859-1
-@end example
-
-@noindent
-and the font specification for Chinese GB2312 characters would be this:
-
-@example
--*-fixed-medium-r-normal-*-24-*-gb2312*-*
-@end example
-
-  You may not have any Chinese font matching the above font
-specification.  Most X distributions include only Chinese fonts that
-have @samp{song ti} or @samp{fangsong ti} in the @var{family} field.  In
-such a case, @samp{Fontset-@var{n}} can be specified as below:
-
-@smallexample
-Emacs.Fontset-0: -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24,\
-        chinese-gb2312:-*-*-medium-r-normal-*-24-*-gb2312*-*
-@end smallexample
-
-@noindent
-Then, the font specifications for all but Chinese GB2312 characters have
-@samp{fixed} in the @var{family} field, and the font specification for
-Chinese GB2312 characters has a wild card @samp{*} in the @var{family}
-field.
+@cindex clipboard support (for MS-Windows)
+When Emacs runs on MS-Windows, it does not implement X selections in
+general, but it it does support the clipboard.  @code{x-get-selection}
+and @code{x-set-selection} on MS-Windows support the text data type
+only; if the clipboard holds other types of data, Emacs treats the
+clipboard as empty.
+
+@defopt x-select-enable-clipboard
+If this is non-@code{nil}, the Emacs yank functions consult the
+clipboard before the primary selection, and the kill functions store in
+the clipboard as well as the primary selection.  Otherwise they do not
+access the clipboard at all.  The default is @code{nil} on most systems,
+but @code{t} on MS-Windows.
+@end defopt
 
 @node Color Names
 @section Color Names
 
-@defun x-color-defined-p color &optional frame
+  These functions provide a way to determine which color names are
+valid, and what they look like.
+
+@defun color-defined-p color &optional frame
+@tindex color-defined-p
 This function reports whether a color name is meaningful.  It returns
 @code{t} if so; otherwise, @code{nil}.  The argument @var{frame} says
 which frame's display to ask about; if @var{frame} is omitted or
 @code{nil}, the selected frame is used.
 
 Note that this does not tell you whether the display you are using
-really supports that color.  You can ask for any defined color on any
-kind of display, and you will get some result---that is how the X server
-works.  Here's an approximate way to test whether your display supports
-the color @var{color}:
+really supports that color.  When using X, you can ask for any defined
+color on any kind of display, and you will get some result---typically,
+the best it knows how to do.  Here's an approximate way to test whether
+your display supports the color @var{color}:
 
 @example
 (defun x-color-supported-p (color &optional frame)
-  (and (x-color-defined-p color frame)
+  (and (color-defined-p color frame)
        (or (x-display-color-p frame)
            (member color '("black" "white"))
            (and (> (x-display-planes frame) 1)
                 (equal color "gray")))))
 @end example
+
+This function used to be called @code{x-color-defined-p},
+and that name is still supported as an alias.
+@end defun
+
+@defun defined-colors &optional frame
+@tindex defined-colors
+This function returns a list of the color names that are defined
+and supported on frame @var{frame} (default, the selected frame).
+
+This function used to be called @code{x-defined-colors},
+and that name is still supported as an alias.
 @end defun
 
-@defun x-color-values color &optional frame
+@defun color-values color &optional frame
+@tindex color-values
 This function returns a value that describes what @var{color} should
 ideally look like.  If @var{color} is defined, the value is a list of
 three integers, which give the amount of red, the amount of green, and
 the amount of blue.  Each integer ranges in principle from 0 to 65535,
-but in practice no value seems to be above 65280.  If @var{color} is not
-defined, the value is @code{nil}.
+but in practice no value seems to be above 65280.  This kind
+of three-element list is called an @dfn{rgb value}.
+
+If @var{color} is not defined, the value is @code{nil}.
 
 @example
-(x-color-values "black")
+(color-values "black")
      @result{} (0 0 0)
-(x-color-values "white")
+(color-values "white")
      @result{} (65280 65280 65280)
-(x-color-values "red")
+(color-values "red")
      @result{} (65280 0 0)
-(x-color-values "pink")
+(color-values "pink")
      @result{} (65280 49152 51968)
-(x-color-values "hungry")
+(color-values "hungry")
      @result{} nil
 @end example
 
 The color values are returned for @var{frame}'s display.  If @var{frame}
 is omitted or @code{nil}, the information is returned for the selected
 frame's display.
+
+This function used to be called @code{x-color-values},
+and that name is still supported as an alias.
+@end defun
+
+@node Text Terminal Colors
+@section Text Terminal Colors
+@cindex colors on text-only terminals
+
+  Emacs can display color on text-only terminals, starting with version
+21.  These terminals support only a small number of colors, and the
+computer uses small integers to select colors on the terminal.  This
+means that the computer cannot reliably tell what the selected color
+looks like; instead, you have to inform your application which small
+integers correspond to which colors.  However, Emacs does know the
+standard set of colors and will try to use them automatically.
+
+@cindex rgb value
+  Several of these functions use or return @dfn{rgb values}.  An rgb
+value is a list of three integers, which give the amount of red, the
+amount of green, and the amount of blue.  Each integer ranges in
+principle from 0 to 65535, but in practice the largest value used is
+65280.
+
+@defun tty-define-color name number &optional rgb
+@tindex tty-define-color
+This function associates the color name @var{name} with
+color number @var{number} on the terminal.
+
+The optional argument @var{rgb}, if specified, is an rgb value; it says
+what the color actually looks like.  If you do not specify @var{rgb},
+then this color cannot be used by @code{tty-color-approximate} to
+approximate other colors, because Emacs does not know what it looks
+like.
+@end defun
+
+@defun tty-clear-colors
+@tindex tty-clear-colors
+This function clears the table of defined colors for a text-only terminal.
+@end defun
+
+@defvar tty-color-alist
+@tindex tty-color-alist
+This variable holds an alist recording the colors supported by the
+terminal.
+
+Each element has the form @code{(@var{name} @var{number} . @var{rgb})}
+or @code{(@var{name} @var{number})}.  Here, @var{name} is the color
+name, @var{number} is the number used to specify it to the terminal.
+If present, @var{rgb} is an rgb value that says what the color
+actually looks like.
+@end defun
+
+@defun tty-color-approximate rgb
+@tindex tty-color-approximate
+This function finds the closest available color, among those in
+@code{tty-color-alist}, to that described by the rgb value @var{rgb}.
+@end defun
+
+@defun tty-color-translate color
+@tindex tty-color-translate
+This function finds the closest available color, among those in
+@code{tty-color-alist}, to the name @var{color}.  If that name
+is not defined, the value is @code{nil}.
+
+@var{color} can be an X-style @code{#@var{xxxyyyzzz}} specification
+instead of an actual name.
 @end defun
 
 @node Resources
diff --git a/lispref/functions.texi b/lispref/functions.texi
index 510b3e1766d..edec40d5072 100644
--- a/lispref/functions.texi
+++ b/lispref/functions.texi
@@ -879,6 +879,7 @@ comment:
 (function @var{symbol}) @equiv{} (quote @var{symbol}) @equiv{} '@var{symbol}
 @end example
 
+@cindex @samp{#'} syntax
   The read syntax @code{#'} is a short-hand for using @code{function}.
 For example, 
 
diff --git a/lispref/internals.texi b/lispref/internals.texi
index 33f5cb26dbd..0df7f9ec509 100644
--- a/lispref/internals.texi
+++ b/lispref/internals.texi
@@ -97,7 +97,7 @@ installation directory for Lisp files when you install Emacs.
 
 @item
 Specify a non-@code{nil} value for
-@code{byte-compile-dynamic-docstrings} as a local variable in each these
+@code{byte-compile-dynamic-docstrings} as a local variable in each of these
 files, and load them with either @file{site-load.el} or
 @file{site-init.el}.  (This method has the drawback that the
 documentation strings take up space in Emacs all the time.)
@@ -107,7 +107,7 @@ documentation strings take up space in Emacs all the time.)
 @file{site-init.el} that would alter any of the features that users
 expect in an ordinary unmodified Emacs.  If you feel you must override
 normal features for your site, do it with @file{default.el}, so that
-users can override your changes if they wish.  @xref{Start-up Summary}.
+users can override your changes if they wish.  @xref{Startup Summary}.
 
 @defun dump-emacs to-file from-file
 @cindex unexec
@@ -125,7 +125,7 @@ you must run Emacs with @samp{-batch}.
 
   Emacs Lisp uses two kinds of storage for user-created Lisp objects:
 @dfn{normal storage} and @dfn{pure storage}.  Normal storage is where
-all the new data created during an Emacs session is kept; see the
+all the new data created during an Emacs session are kept; see the
 following section for information on normal storage.  Pure storage is
 used for certain data in the preloaded standard Lisp files---data that
 should never change during actual use of Emacs.
@@ -142,8 +142,8 @@ increase the compilation parameter @code{PURESIZE} in the file
 preload additional libraries or add features to the standard ones.
 
 @defun purecopy object
-This function makes a copy of @var{object} in pure storage and returns
-it.  It copies strings by simply making a new string with the same
+This function makes a copy in pure storage of @var{object}, and returns
+it.  It copies a string by simply making a new string with the same
 characters in pure storage.  It recursively copies the contents of
 vectors and cons cells.  It does not make copies of other objects such
 as symbols, but just returns them unchanged.  It signals an error if
@@ -553,10 +553,10 @@ you use @code{GCPRO2}, you must declare @code{gcpro1} and @code{gcpro2}.
 Alas, we can't explain all the tricky details here.
 
   You must not use C initializers for static or global variables unless
-they are never written once Emacs is dumped.  These variables with
-initializers are allocated in an area of memory that becomes read-only
-(on certain operating systems) as a result of dumping Emacs.  @xref{Pure
-Storage}.
+the variables are never stored in once Emacs is dumped.  These variables
+with initializers are allocated in an area of memory that becomes
+read-only (on certain operating systems) as a result of dumping Emacs.
+@xref{Pure Storage}.
 
   Do not use static variables within functions---place all static
 variables at top level in the file.  This is necessary because Emacs on
@@ -587,16 +587,19 @@ file, add to it a @code{syms_of_@var{filename}} (e.g.,
 of these functions are called, and add a call to
 @code{syms_of_@var{filename}} there.
 
+@vindex byte-boolean-vars
   The function @code{syms_of_@var{filename}} is also the place to define
 any C variables that are to be visible as Lisp variables.
 @code{DEFVAR_LISP} makes a C variable of type @code{Lisp_Object} visible
 in Lisp.  @code{DEFVAR_INT} makes a C variable of type @code{int}
 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}.
+with a value that is either @code{t} or @code{nil}.  Note that variables
+defined with @code{DEFVAR_BOOL} are automatically added to the list
+@code{byte-boolean-vars} used by the byte compiler.
 
   If you define a file-scope C variable of type @code{Lisp_Object},
-you must protect it for garbage-collection by calling @code{staticpro}
+you must protect it from garbage-collection by calling @code{staticpro}
 in @code{syms_of_@var{filename}}, like this:
 
 @example
@@ -681,6 +684,11 @@ number of arguments.  They work by calling @code{Ffuncall}.
 @file{lisp.h} contains the definitions for some important macros and
 functions.
 
+  If you define a function which is side-effect free, update the code in
+@file{byte-opt.el} which binds @code{side-effect-free-fns} and
+@code{side-effect-and-error-free-fns} to include it.  This will help the
+optimizer.
+
 @node Object Internals
 @appendixsec Object Internals
 @cindex object internals
@@ -729,9 +737,9 @@ This field contains the time when the buffer was last saved, as an integer.
 
 @item modtime
 This field contains the modification time of the visited file.  It is
-set when the file is written or read.  Every time the buffer is written
-to the file, this field is compared to the modification time of the
-file.  @xref{Buffer Modification}.
+set when the file is written or read.  Before writing the buffer into a
+file, this field is compared to the modification time of the file to see
+if the file has changed on disk.  @xref{Buffer Modification}.
 
 @item auto_save_modified
 This field contains the time when the buffer was last auto-saved.
@@ -872,7 +880,9 @@ the screen is @w{line 0}.)
 The height of the window, measured in lines.
 
 @item width
-The width of the window, measured in columns.
+The width of the window, measured in columns.  This width includes the
+scroll bar and fringes, and/or the separator line on the right of the
+window (if any).
 
 @item next
 This is the window that is the next in the chain of siblings.  It is
diff --git a/lispref/intro.texi b/lispref/intro.texi
index 10c3763822a..34a6ae12fac 100644
--- a/lispref/intro.texi
+++ b/lispref/intro.texi
@@ -343,7 +343,7 @@ the ``copyright'' line and a pointer to where the full notice is found.
 
 @smallexample
 @var{one line to give the program's name and an idea of what it does.}
-Copyright (C) 19@var{yy}  @var{name of author}
+Copyright (C) @var{year}  @var{name of author}
 
 This program is free software; you can redistribute it and/or
 modify it under the terms of the GNU General Public License
@@ -366,7 +366,7 @@ If the program is interactive, make it output a short notice like this
 when it starts in an interactive mode:
 
 @smallexample
-Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author}
+Gnomovision version 69, Copyright (C) @var{year} @var{name of author}
 Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
 type `show w'.  This is free software, and you are welcome
 to redistribute it under certain conditions; type `show c' 
@@ -521,7 +521,7 @@ worry about it; this manual is self-contained.
 
 @pindex cl
   A certain amount of Common Lisp emulation is available via the
-@file{cl} library @xref{Top,, Common Lisp Extension, cl, Common Lisp
+@file{cl} library.  @xref{Top,, Common Lisp Extension, cl, Common Lisp
 Extensions}.
 
   Emacs Lisp is not at all influenced by Scheme; but the GNU project has
@@ -556,10 +556,9 @@ addressed as ``you''.  ``The user'' is the person who uses Lisp
 programs, including those you write.
 
 @cindex fonts
-  Examples of Lisp code appear in this font or form: @code{(list 1 2
-3)}.  Names that represent metasyntactic variables, or arguments to a
-function being described, appear in this font or form:
-@var{first-number}.
+  Examples of Lisp code are formatted like this: @code{(list 1 2 3)}.
+Names that represent metasyntactic variables, or arguments to a function
+being described, are formatted like this: @var{first-number}.
 
 @node nil and t
 @subsection @code{nil} and @code{t}
@@ -685,13 +684,13 @@ the echo area.
 @subsection Buffer Text Notation
 @cindex buffer text notation
 
-  Some examples show modifications to text in a buffer, with ``before''
-and ``after'' versions of the text.  These examples show the contents of
-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
-currently located.)
+  Some examples describe modifications to the contents of a buffer, by
+showing the ``before'' and ``after'' versions of the text.  These
+examples show the contents of 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 currently located.)
 
 @example
 ---------- Buffer: foo ----------
@@ -900,7 +899,9 @@ emacs-build-time
 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.
+time you build Emacs in any given directory.  A value with three numeric
+components, such as @code{"20.3.9.1"}, indicates an unreleased test
+version.
 @end defvar
 
   The following two variables have existed since Emacs version 19.23:
diff --git a/lispref/keymaps.texi b/lispref/keymaps.texi
index b036679d4f6..d6ed2e3e4c9 100644
--- a/lispref/keymaps.texi
+++ b/lispref/keymaps.texi
@@ -124,17 +124,17 @@ 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, codes 0 through 127; vector element
+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
+@sc{ascii} character, even if the vector contains @code{nil} for that
 character.  Such a binding of @code{nil} overrides any default key
-binding in the keymap, for @sc{ASCII} characters.  However, default
-bindings are still meaningful for events other than @sc{ASCII}
+binding in the keymap, for @sc{ascii} characters.  However, default
+bindings are still meaningful for events other than @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.
@@ -215,8 +215,8 @@ otherwise.  More precisely, this function tests for a list whose
 @c ??? This should come after make-sparse-keymap
 @defun make-keymap &optional prompt
 This function creates and returns a new full keymap (i.e., one
-containing a vector of length 128 for defining all the @sc{ASCII}
-characters).  The new keymap initially binds all @sc{ASCII} characters
+containing a vector of length 128 for defining all the @sc{ascii}
+characters).  The new keymap initially binds all @sc{ascii} characters
 to @code{nil}, and does not bind any other kind of event.
 
 @example
@@ -567,7 +567,7 @@ other.
 This function returns the current buffer's local keymap, or @code{nil}
 if it has none.  In the following example, the keymap for the
 @samp{*scratch*} buffer (using Lisp Interaction mode) is a sparse keymap
-in which the entry for @key{ESC}, @sc{ASCII} code 27, is another sparse
+in which the entry for @key{ESC}, @sc{ascii} code 27, is another sparse
 keymap.
 
 @example
@@ -953,7 +953,7 @@ This variable is the meta-prefix character code.  It is used when
 translating a meta character to a two-character sequence so it can be
 looked up in a keymap.  For useful results, the value should be a prefix
 event (@pxref{Prefix Keys}).  The default value is 27, which is the
-@sc{ASCII} code for @key{ESC}.
+@sc{ascii} code for @key{ESC}.
 
 As long as the value of @code{meta-prefix-char} remains 27, key
 lookup translates @kbd{M-b} into @kbd{@key{ESC} b}, which is normally
@@ -1256,6 +1256,35 @@ redefines @kbd{C-x C-\} to move down a line.
 redefines the first (leftmost) mouse button, typed with the Meta key, to
 set point where you click.
 
+@cindex non-ASCII text in keybindings
+  Be careful when using non-@sc{ascii} text characters in Lisp
+specifications of keys to bind.  If these are read as multibyte text, as
+they usually will be in a Lisp file (@pxref{Loading Non-ASCII}), you
+must type the keys as multibyte too.  For instance, if you use this:
+
+@smallexample
+(global-set-key "@"o" 'my-function) ; bind o-umlaut
+@end smallexample
+
+@noindent
+or
+
+@smallexample
+(global-set-key ?@"o 'my-function) ; bind o-umlaut
+@end smallexample
+
+@noindent
+and your language environment is multibyte Latin-1, these commands
+actually bind the multibyte character with code 2294, not the unibyte
+Latin-1 character with code 246 (@kbd{M-v}).  In order to use this
+binding, you need to enter the multibyte Latin-1 character as keyboard
+input.  One way to do this is by using an appropriate input method
+(@pxref{Input Methods, , Input Methods, emacs,The GNU Emacs Manual}).
+
+  If you want to use a unibyte character in the key binding, you can
+construct the key sequence string using @code{multibyte-char-to-unibyte}
+or @code{string-make-unibyte} (@pxref{Converting Representations}).
+
 @deffn Command global-set-key key definition
 This function sets the binding of @var{key} in the current global map
 to @var{definition}.
@@ -1431,7 +1460,7 @@ If @var{firstonly} is @code{non-ascii}, then the value is a single
 string representing the first key sequence found, rather than a list of
 all possible key sequences.  If @var{firstonly} is @code{t}, then the
 value is the first key sequence, except that key sequences consisting
-entirely of @sc{ASCII} characters (or meta variants of @sc{ASCII}
+entirely of @sc{ascii} characters (or meta variants of @sc{ascii}
 characters) are preferred to all other key sequences.
 
 If @var{noindirect} is non-@code{nil}, @code{where-is-internal} doesn't
@@ -1457,13 +1486,13 @@ listing includes only keys that start with @var{prefix}.
 The listing describes meta characters as @key{ESC} followed by the
 corresponding non-meta character.
 
-When several characters with consecutive @sc{ASCII} codes have the
+When several characters with consecutive @sc{ascii} codes have the
 same definition, they are shown together, as
 @samp{@var{firstchar}..@var{lastchar}}.  In this instance, you need to
-know the @sc{ASCII} codes to understand which characters this means.
+know the @sc{ascii} codes to understand which characters this means.
 For example, in the default global map, the characters @samp{@key{SPC}
-..@: ~} are described by a single line.  @key{SPC} is @sc{ASCII} 32,
-@kbd{~} is @sc{ASCII} 126, and the characters between them include all
+..@: ~} are described by a single line.  @key{SPC} is @sc{ascii} 32,
+@kbd{~} is @sc{ascii} 126, and the characters between them include all
 the normal printing characters, (e.g., letters, digits, punctuation,
 etc.@:); all these characters are bound to @code{self-insert-command}.
 @end deffn
@@ -1483,6 +1512,7 @@ work with the keyboard also.
 * Keyboard Menus::              How they actuate it with the keyboard.
 * Menu Example::                Making a simple menu.
 * Menu Bar::                    How to customize the menu bar.
+* Tool Bar::                    A tool bar is a row of images.
 * Modifying Menus::             How to add new items to a menu.
 @end menu
 
@@ -1509,10 +1539,11 @@ an existing menu, you can specify its position in the menu using
 @menu
 * Simple Menu Items::       A simple kind of menu key binding,
                               limited in capabilities.
-* Alias Menu Items::        Using command aliases in menu items.
 * Extended Menu Items::     More powerful menu item definitions
                               let you specify keywords to enable
                               various features.
+* Menu Separators::         Drawing a horizontal line through a menu.
+* Alias Menu Items::        Using command aliases in menu items.
 @end menu
 
 @node Simple Menu Items
@@ -1591,7 +1622,8 @@ the item looks like this:
 @end example
 
 @noindent
-where a string consisting of two or more dashes specifies a separator line.
+A string starting with two or more dashes specifies a separator line;
+see @ref{Menu Separators}.
 
   To define a real menu item which can be selected, the extended format
 item looks like this:
@@ -1609,11 +1641,12 @@ string.  Thus, the string need not be a constant.  The third element,
 other information.  Here is a table of the properties that are supported:
 
 @table @code
-@item :enable FORM
+@item :enable @var{form}
 The result of evaluating @var{form} determines whether the item is
-enabled (non-@code{nil} means yes).
+enabled (non-@code{nil} means yes).  If the item is not enabled,
+you can't really click on it.
 
-@item :visible FORM
+@item :visible @var{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
@@ -1684,6 +1717,80 @@ when it is called, its argument will be @var{real-binding}.  The
 function should return the binding to use instead.
 @end table
 
+@node Menu Separators
+@subsubsection Menu Separators
+@cindex menu separators
+
+  A menu separator is a kind of menu item that doesn't display any
+text--instead, it divides the menu into subparts with a horizontal line.
+A separator looks like this in the menu keymap:
+
+@example
+(menu-item @var{separator-type})
+@end example
+
+@noindent
+where @var{separator-type} is a string starting with two or more dashes.
+
+  In the simplest case, @var{separator-type} consists of only dashes.
+That specifies the default kind of separator.  (For compatibility,
+@code{""} and @code{-} also count as separators.)
+
+  Starting in Emacs 21, certain other values of @var{separator-type}
+specify a different style of separator.  Here is a table of them:
+
+@table @code
+@item "--no-line"
+@itemx "--space"
+An extra vertical space, with no actual line.
+
+@item "--single-line"
+A single line in the menu's foreground color.
+
+@item "--double-line"
+A double line in the menu's foreground color.
+
+@item "--single-dashed-line"
+A single dashed line in the menu's foreground color.
+
+@item "--double-dashed-line"
+A double dashed line in the menu's foreground color.
+
+@item "--shadow-etched-in"
+A single line with a 3D sunken appearance.  This is the default,
+used separators consisting of dashes only.
+
+@item "--shadow-etched-out"
+A single line with a 3D raised appearance.
+
+@item "--shadow-etched-in-dash"
+A single dashed line with a 3D sunken appearance.
+
+@item "--shadow-etched-out-dash"
+A single dashed line with a 3D raised appearance.
+
+@item "--shadow-double-etched-in"
+Two lines with a 3D sunken appearance.
+
+@item "--shadow-double-etched-out"
+Two lines with a 3D raised appearance.
+
+@item "--shadow-double-etched-in-dash"
+Two dashed lines with a 3D sunken appearance.
+
+@item "--shadow-double-etched-out-dash"
+Two dashed lines with a 3D raised appearance.
+@end table
+
+  You can also give these names in another style, adding a colon after
+the double-dash and replacing each single dash with capitalization of
+the following word.  Thus, @code{"--:singleLine"}, is equivalent to
+@code{"--single-line"}.
+
+  Some systems and display toolkits don't really handle all of these
+separator types.  If you use a type that isn't supported, the menu
+displays a similar kind of separator that is supported.
+
 @node Alias Menu Items
 @subsubsection Alias Menu Items
 
@@ -1978,6 +2085,115 @@ displaying a submenu.  You can use it to update submenus whose contents
 should vary.
 @end defvar
 
+@node Tool Bar
+@subsection Tool bars
+@cindex tool bar
+
+  A @dfn{tool bar} is a row of icons at the top of a frame, that execute
+commands when you click on them---in effect, a kind of graphical menu
+bar.  Emacs supports tool bars starting with version 21.
+
+  The frame parameter @code{tool-bar-lines} (X resource @samp{toolBar})
+controls how may lines' worth of height to reserve for the tool bar.  A
+zero value suppresses the tool bar.  If the value is nonzero, and
+@code{auto-resize-tool-bars} is non-@code{nil}, the tool bar expands and
+contracts automatically as needed to hold the specified contents.
+
+  The tool bar contents are controlled by a menu keymap attached to a
+fake ``function key'' called @code{tool-bar} (much like the way the menu
+bar is controlled).  So you define a tool bar item using
+@code{define-key}, like this:
+
+@example
+(define-key global-map [tool-bar @var{key}] @var{item})
+@end example
+
+@noindent
+where @var{key} is a fake ``function key'' to distinguish this item from
+other items, and @var{item} is a menu item key binding (@pxref{Extended
+Menu Items}), which says how to display this item and how it behaves.
+
+  The usual menu keymap item properties, @code{:visible},
+@code{:enable}, @code{:button}, and @code{:filter}, are useful in
+tool bar bindings and have their normal meanings.  The @var{real-binding}
+in the item must be a command, not a keymap; in other words, it does not
+work to define a tool bar icon as a prefix key.
+
+  The @code{:help} property is meaningful, and specifies a ``help-echo''
+string to display while the mouse is on that item.
+
+  In addition, you should use the @code{:image} property;
+this is how you specify the image to display in the tool bar:
+
+@table @code
+@item :image @var{image}
+@var{images} is either a single image specification or a vector of four
+image specifications.  If you use a vector of four,
+one of them is used, depending on circumstances:
+
+@table @asis
+@item item 0
+Used when the iitem is enabled and selected.
+@item item 1
+Used when the item is enabled and deselected.
+@item item 2
+Used when the item is disabled and selected.
+@item item 3
+Used when the item is disabled and deselected.
+@end table
+@end table
+
+@tindex auto-resize-tool-bar
+@defvar auto-resize-tool-bar
+If this variable is non-@code{nil}, the tool bar automatically resizes to
+show all defined tool bar items---but not larger than a quarter of the
+frame's height.
+@end defvar
+
+@tindex auto-raise-tool-bar-items
+@defvar auto-raise-tool-bar-items
+If this variable is non-@code{nil}, tool bar items display
+in raised form when the mouse moves over them.
+@end defvar
+
+@tindex tool-bar-item-margin
+@defvar tool-bar-item-margin
+This variable specifies an extra margin to add around tool bar items.
+The value is an integer, a number of pixels.  The default is 1.
+@end defvar
+
+@tindex tool-bar-item-relief
+@defvar tool-bar-item-relief
+This variable specifies the shadow width for tool bar items.
+The value is an integer, a number of pixels.  The default is 3.
+@end defvar
+
+  You can define a special meaning for clicking on a tool bar item with
+the shift, control, meta, etc., modifiers.  You do this by setting up
+additional items that relate to the original item through the fake
+function keys.  Specifically, the additional items should use the
+modified versions of the same fake function key used to name the
+original item.
+
+  Thus, if the original item was defined this way,
+
+@example
+(define-key global-map [tool-bar shell]
+  '(menu-item "Shell" shell
+              :image (image :type xpm :file "shell.xpm")))
+@end example
+
+@noindent
+then here is how you can define clicking on the same tool bar image with
+the shift modifier:
+
+@example
+(define-key global-map [tool-bar S-shell] 'some-command)
+@end example
+
+@xref{Function Keys}, for more information about how to add modifiers to
+function keys.
+
 @node Modifying Menus
 @subsection Modifying Menus
 
diff --git a/lispref/lists.texi b/lispref/lists.texi
index ca310235940..58b1cfe4de8 100644
--- a/lispref/lists.texi
+++ b/lispref/lists.texi
@@ -302,6 +302,26 @@ This is in contrast to @code{cdr}, which signals an error if
 @end example
 @end defun
 
+@tindex pop
+@defmac pop listname
+This macro is a way of examining the @sc{car} of a list,
+and taking it off the list, all at once.  It is new in Emacs 21.
+
+It operates on the list which is stored in the symbol @var{listname}.
+It removes this element from the list by setting @var{listname}
+to the @sc{cdr} of its old value---but it also returns the @sc{car}
+of that list, which is the element being removed.
+
+@example
+x
+     @result{} (a b c)
+(pop x)
+     @result{} a
+x
+     @result{} (b c)
+@end example
+@end defmac
+
 @defun nth n list
 This function returns the @var{n}th element of @var{list}.  Elements
 are numbered starting with zero, so the @sc{car} of @var{list} is
@@ -441,6 +461,13 @@ used in this example and the function named @code{list} described below;
 any symbol can serve both purposes.
 @end defun
 
+@tindex push
+@defmac push newelt listname
+This macro provides an alternative way to write
+@code{(setq @var{listname} (cons @var{newelt} @var{listname}))}.
+It is new in Emacs 21.
+@end defmac
+
 @defun list &rest objects
 This function creates a list with @var{objects} as its elements.  The
 resulting list is always @code{nil}-terminated.  If no @var{objects}
@@ -1509,4 +1536,14 @@ the associations of one copy without affecting the other:
 @end smallexample
 @end defun
 
+@defun assoc-delete-all key alist
+@tindex assoc-delete-all
+This function deletes from @var{alist} all the elements whose @sc{car}
+is @var{key}.  It returns the modified alist.
 
+@example
+(assoc-delete-all 'foo
+                  '((foo 1) (bar 2) (foo 3) (lose 4)))
+     @result{} ((bar 2) (lose 4))
+@end example
+@end defun
diff --git a/lispref/loading.texi b/lispref/loading.texi
index b5b03abc93b..813e03338f6 100644
--- a/lispref/loading.texi
+++ b/lispref/loading.texi
@@ -36,7 +36,7 @@ containing Lisp code.
 @menu
 * How Programs Do Loading::     The @code{load} function and others.
 * Library Search::              Finding a library to load.
-* Loading Non-ASCII::           Non-@sc{ASCII} characters in Emacs Lisp files.
+* Loading Non-ASCII::           Non-@sc{ascii} characters in Emacs Lisp files.
 * Autoload::                    Setting up a function to autoload.
 * Repeated Loading::            Precautions about loading a file twice.
 * Named Features::              Loading a library if it isn't already loaded.
@@ -257,10 +257,10 @@ subdirectories multiple levels down are added to @code{load-path}.
 
   Not all subdirectories are included, though.  Subdirectories whose
 names do not start with a letter or digit are excluded.  Subdirectories
-named @file{RCS} are excluded.  Also, a subdirectory which contains a
-file named @file{.nosearch} is excluded.  You can use these methods to
-prevent certain subdirectories of the @file{site-lisp} directories from
-being searched.
+named @file{RCS} or @file{CVS} are excluded.  Also, a subdirectory which
+contains a file named @file{.nosearch} is excluded.  You can use these
+methods to prevent certain subdirectories of the @file{site-lisp}
+directories from being searched.
 
   If you run Emacs from the directory where it was built---that is, an
 executable that has not been formally installed---then @code{load-path}
@@ -287,7 +287,7 @@ tells @code{locate-library} to display the file name in the echo area.
 @node Loading Non-ASCII
 @section Loading Non-ASCII Characters
 
-  When Emacs Lisp programs contain string constants with non-@sc{ASCII}
+  When Emacs Lisp programs contain string constants with non-@sc{ascii}
 characters, these can be represented within Emacs either as unibyte
 strings or as multibyte strings (@pxref{Text Representations}).  Which
 representation is used depends on how the file is read into Emacs.  If
@@ -301,7 +301,7 @@ unibyte text, and its string constants will be unibyte strings.
   To make the results more predictable, Emacs always performs decoding
 into the multibyte representation when loading Lisp files, even if it
 was started with the @samp{--unibyte} option.  This means that string
-constants with non-@sc{ASCII} characters translate into multibyte
+constants with non-@sc{ascii} characters translate into multibyte
 strings.  The only exception is when a particular file specifies no
 decoding.
 
@@ -313,13 +313,13 @@ notice whether the user prefers unibyte or multibyte text, by checking
 @code{default-enable-multibyte-characters}, and convert representations
 appropriately.
 
-  In most Emacs Lisp programs, the fact that non-@sc{ASCII} strings are
+  In most Emacs Lisp programs, the fact that non-@sc{ascii} strings are
 multibyte strings should not be noticeable, since inserting them in
 unibyte buffers converts them to unibyte automatically.  However, if
 this does make a difference, you can force a particular Lisp file to be
 interpreted as unibyte by writing @samp{-*-unibyte: t;-*-} in a
 comment on the file's first line.  With that designator, the file will
-be unconditionally be interpreted as unibyte, even in an ordinary
+unconditionally be interpreted as unibyte, even in an ordinary
 multibyte Emacs session.
 
 @node Autoload
@@ -432,13 +432,20 @@ autoloads for all files in the current directory.
 
   The same magic comment can copy any kind of form into
 @file{loaddefs.el}.  If the form following the magic comment is not a
-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 @kbd{M-x update-file-autoloads}
-copies it to @file{loaddefs.el}, where it is executed while building
-Emacs.
+function-defining form or a @code{defcustom} form, it is copied
+verbatim.  ``Function-defining forms'' include @code{define-skeleton},
+@code{define-derived-mode}, @code{define-generic-mode} and
+@code{easy-mmode-define-minor-mode} as well as @code{defun} and
+@code{defmacro}.  To save space, a @code{defcustom} form is converted to
+a @code{defvar} in @file{loaddefs.el}, with some additional information
+if it uses @code{:require}.
+
+  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
+@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:
@@ -456,17 +463,17 @@ autoloading with a magic comment:
 Here's what that produces in @file{loaddefs.el}:
 
 @smallexample
-(autoload 'doctor "doctor"
-  "\
+(autoload 'doctor "doctor" "\
 Switch to *doctor* buffer and start giving psychotherapy."
   t)
 @end smallexample
 
 @noindent
 The backslash and newline immediately following the double-quote are a
-convention used only in the preloaded Lisp files such as
+convention used only in the preloaded uncompiled Lisp files such as
 @file{loaddefs.el}; they tell @code{make-docfile} to put the
 documentation string in the @file{etc/DOC} file.  @xref{Building Emacs}.
+See also the commentary in @file{lib-src/make-docfile.c}.
 
 @node Repeated Loading
 @section Repeated Loading
@@ -591,7 +598,9 @@ done.
   When @code{require} is used at top level in a file, it takes effect
 when you byte-compile that file (@pxref{Byte Compilation}) as well as
 when you load it.  This is in case the required package contains macros
-that the byte compiler must know about.
+that the byte compiler must know about.  It also avoids byte-compiler
+warnings for functions and variables defined in the file loaded with
+@code{require}.
 
   Although top-level calls to @code{require} are evaluated during
 byte compilation, @code{provide} calls are not.  Therefore, you can
@@ -701,6 +710,8 @@ is defined, it is run as a normal hook before restoring the previous
 definitions, @emph{instead of} the usual hook-removing actions.  The
 unload hook ought to undo all the global state changes made by the
 library that might cease to work once the library is unloaded.
+@code{unload-feature} can cause problems with libraries that fail to do
+this, so it should be used with caution.
 
 Ordinarily, @code{unload-feature} refuses to unload a library on which
 other loaded libraries depend.  (A library @var{a} depends on library
@@ -741,7 +752,16 @@ The value of @code{load-history} may have one element whose @sc{car} is
 by adding the symbols defined to the element for the file being visited,
 rather than replacing that element.  @xref{Eval}.
 
-  Preloaded libraries don't contribute to @code{load-history}.
+  Preloaded libraries don't contribute initially to @code{load-history}.
+Instead, preloading writes information about preloaded libraries into a
+file, which can be loaded later on to to add information to
+@code{load-history} describing the preloaded files.  This file is
+installed in @code{exec-directory} and has a name of the form
+@file{fns-@var{emacsversion}.el}.
+
+@findex symbol-file
+  See the source for the function @code{symbol-file}, for an example of
+code that loads this file to find functions in preloaded libraries.
 
 @tindex loadhist-special-hooks
 @defvar loadhist-special-hooks
@@ -784,8 +804,8 @@ 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
-loaded.  Each element looks like this:
+This variable holds an alist of expressions to evaluate if and when
+particular libraries are loaded.  Each element looks like this:
 
 @example
 (@var{filename} @var{forms}@dots{})
diff --git a/lispref/maps.texi b/lispref/maps.texi
index 96f8d0921ee..38734cd6523 100644
--- a/lispref/maps.texi
+++ b/lispref/maps.texi
@@ -67,34 +67,35 @@ A sparse keymap used by Emacs Lisp mode.
 
 @item facemenu-menu
 @vindex facemenu-menu
-The keymap that displays the Text Properties menu.
+The sparse keymap that displays the Text Properties menu.
 
 @item facemenu-background-menu
 @vindex facemenu-background-menu
-The keymap that displays the Background Color submenu of the Text
+The sparse keymap that displays the Background Color submenu of the Text
 Properties menu.
 
 @item facemenu-face-menu
 @vindex facemenu-face-menu
-The keymap that displays the Face submenu of the Text Properties menu.
+The sparse keymap that displays the Face submenu of the Text Properties menu.
 
 @item facemenu-foreground-menu
 @vindex facemenu-foreground-menu
-The keymap that displays the Foreground Color submenu of the Text
+The sparse keymap that displays the Foreground Color submenu of the Text
 Properties menu.
 
 @item facemenu-indentation-menu
 @vindex facemenu-indentation-menu
-The keymap that displays the Indentation submenu of the Text Properties menu.
+The sparse keymap that displays the Indentation submenu of the Text
+Properties menu.
 
 @item facemenu-justification-menu
 @vindex facemenu-justification-menu
-The keymap that displays the Justification submenu of the Text
+The sparse keymap that displays the Justification submenu of the Text
 Properties menu.
 
 @item facemenu-special-menu
 @vindex facemenu-special-menu
-The keymap that displays the Special Props submenu of the Text
+The sparse keymap that displays the Special Props submenu of the Text
 Properties menu.
 
 @item function-key-map
@@ -104,7 +105,7 @@ If there are none, then it contains an empty sparse keymap.
 
 @item fundamental-mode-map
 @vindex fundamental-mode-map
-The local keymap for Fundamental mode.@*
+The sparse keymap for Fundamental mode.@*
 It is empty and should not be changed.
 
 @item Helper-help-map
@@ -132,7 +133,7 @@ bindings, unlike @code{function-key-map}.  @xref{Translating Input}.
 
 @item lisp-interaction-mode-map
 @vindex lisp-interaction-mode-map
-A sparse keymap used by Lisp mode.
+A sparse keymap used by Lisp Interaction mode.
 
 @item lisp-mode-map
 @vindex lisp-mode-map
@@ -171,10 +172,10 @@ where it describes the main use of the @kbd{C-c} prefix key.
 
 @item occur-mode-map
 @vindex occur-mode-map
-A local keymap used by Occur mode.
+A sparse keymap used by Occur mode.
 
 @item query-replace-map
-A local keymap used for responses in @code{query-replace} and related
+A sparse 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
 time.
diff --git a/lispref/markers.texi b/lispref/markers.texi
index ee4d2144498..095e6a7f46b 100644
--- a/lispref/markers.texi
+++ b/lispref/markers.texi
@@ -136,7 +136,7 @@ integer or floating point) or a marker, @code{nil} otherwise.
 @end defun
 
 @node Creating Markers
-@section Functions That Create Markers
+@section Functions that Create Markers
 
   When you create a new marker, you can make it point nowhere, or point
 to the present position of point, or to the beginning or end of the
diff --git a/lispref/minibuf.texi b/lispref/minibuf.texi
index e6aeb01a163..7eacbc64279 100644
--- a/lispref/minibuf.texi
+++ b/lispref/minibuf.texi
@@ -42,12 +42,26 @@ windows always appear at the bottom of a frame.  (Sometimes frames have
 no minibuffer window, and sometimes a special kind of frame contains
 nothing but a minibuffer window; see @ref{Minibuffers and Frames}.)
 
-  The minibuffer's window is normally a single line.  You can resize it
-temporarily with the window sizing commands; it reverts to its normal
-size when the minibuffer is exited.  You can resize it permanently by
-using the window sizing commands in the frame's other window, when the
-minibuffer is not active.  If the frame contains just a minibuffer, you
-can change the minibuffer's size by changing the frame's size.
+  The text in the minibuffer always starts with the @dfn{prompt string},
+the text that was specified by the program that is using the minibuffer
+to tell the user what sort of input to type.  This text is marked
+read-only so you won't accidentally delete or change it.  In other
+respects, it is an ordinary part of the buffer contents, but certain
+functions such as @code{erase-buffer}, @code{buffer-string},
+@code{beginning-of-line}, @code{forward-word}, @code{forward-sentence},
+and @code{forward-paragraph}, treat it a little bit specially.  (In
+older Emacs versions, the prompt was displayed using a special mechanism
+and was not part of the buffer contents.)
+
+@c ???
+  The minibuffer's window is normally a single line; it grows
+automatically if necessary if the contents require more space.  You can
+explicitly resize it temporarily with the window sizing commands; it
+reverts to its normal size when the minibuffer is exited.  You can
+resize it permanently by using the window sizing commands in the frame's
+other window, when the minibuffer is not active.  If the frame contains
+just a minibuffer, you can change the minibuffer's size by changing the
+frame's size.
 
   If a command uses a minibuffer while there is an active minibuffer,
 this is called a @dfn{recursive minibuffer}.  The first minibuffer is
@@ -724,7 +738,7 @@ see @ref{Completion Commands}.
 @end defun
 
 @node Completion Commands
-@subsection Minibuffer Commands That Do Completion
+@subsection Minibuffer Commands that Do Completion
 
   This section describes the keymaps, commands and user options used in
 the minibuffer to do completion.
@@ -1483,9 +1497,16 @@ This function returns the prompt string of the currently active
 minibuffer.  If no minibuffer is active, it returns @code{nil}.
 @end defun
 
-@defun minibuffer-prompt-width
-This function returns the display width of the prompt string of the
-currently active minibuffer.  If no minibuffer is active, it returns 0.
+@tindex minubuffer-prompt-end
+@defun minubuffer-prompt-end
+This function, available starting in Emacs 21, returns the current
+position of the end of the minibuffer prompt, if a minibuffer is
+current.  Otherwise, it returns zero.
+@end defun
+
+@defun minubuffer-prompt-width
+This function returns the current display-width of the minibuffer
+prompt, if a minibuffer is current.  Otherwise, it returns zero.
 @end defun
 
 @defvar minibuffer-setup-hook
diff --git a/lispref/modes.texi b/lispref/modes.texi
index 3b51b2e7559..432d94679dd 100644
--- a/lispref/modes.texi
+++ b/lispref/modes.texi
@@ -61,7 +61,7 @@ definition is distinct from that of Text mode, but was derived from it.
   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 commands).  In such cases, the
-temporary major mode usually has a command to switch back to the
+temporary major mode usually provides 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
@@ -70,8 +70,8 @@ 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
-several major modes, in files such as @file{text-mode.el},
+  The standard GNU Emacs Lisp library directory tree contains the code
+for several major modes, in files such as @file{text-mode.el},
 @file{texinfo.el}, @file{lisp-mode.el}, @file{c-mode.el}, and
 @file{rmail.el}.  You can study these libraries to see how modes are
 written.  Text mode is perhaps the simplest major mode aside from
@@ -245,7 +245,7 @@ with value @code{special}, put on as follows:
 @end example
 
 @noindent
-This tells Emacs that new buffers created while the current buffer has
+This tells Emacs that new buffers created while the current buffer is in
 Funny mode should not inherit Funny mode.  Modes such as Dired, Rmail,
 and Buffer List use this feature.
 
@@ -368,7 +368,7 @@ correspondingly more complicated.  Here are excerpts from
 @group
       ;; @r{Set syntax of chars up to 0 to class of chars that are}
       ;;   @r{part of symbol names but not words.}
-      ;;   @r{(The number 0 is @code{48} in the @sc{ASCII} character set.)}
+      ;;   @r{(The number 0 is @code{48} in the @sc{ascii} character set.)}
       (while (< i ?0) 
         (modify-syntax-entry i "_   " emacs-lisp-mode-syntax-table)
         (setq i (1+ i)))
@@ -782,7 +782,8 @@ individually or in combination.  Minor modes would be better named
 ``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
+  A minor mode is not usually meant as a variation of a single major mode.
+Usually they are general and can apply to many major modes.  For
 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.
@@ -825,7 +826,7 @@ 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
+If 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 set the variable.
 
@@ -890,6 +891,40 @@ check for an existing element, to avoid duplication.  For example:
   You can also use @code{add-to-list} to add an element to this list
 just once (@pxref{Setting Variables}).
 
+  Global minor modes distributed with Emacs should if possible support
+enabling and disabling via Custom (@pxref{Customization}).  To do this,
+the first step is to define the mode variable with @code{defcustom}, and
+specify @code{:type boolean}.
+
+  If just setting the variable is not sufficient to enable the mode, you
+should also specify a @code{:set} method which enables the mode by
+invoke the mode command.  Note in the variable's documentation string that
+setting the variable other than via Custom may not take effect.
+
+  Also mark the definition with an autoload cookie (@pxref{Autoload}),
+and specify a @code{:require} so that customizing the variable will load
+the library that defines the mode.  This will copy suitable definitions
+into @file{loaddefs.el} so that users can use @code{customize-option} to
+enable the mode.  For example:
+
+@smallexample
+@group
+
+;;;###autoload
+(defcustom msb-mode nil
+  "Toggle msb-mode.
+Setting this variable directly does not take effect;
+use either \\[customize] or the function `msb-mode'."
+  :set (lambda (symbol value)
+         (msb-mode (or value 0)))
+  :initialize 'custom-initialize-default
+  :version "20.4"
+  :type    'boolean
+  :group   'msb
+  :require 'msb)
+@end group
+@end smallexample
+
 @node Keymaps and Minor Modes
 @subsection Keymaps and Minor Modes
 
@@ -908,15 +943,15 @@ standard one.  The editor command loop handles this function specially.)
 
 The key sequences bound in a minor mode should consist of @kbd{C-c}
 followed by a punctuation character @emph{other than} @kbd{@{},
-@kbd{@}}, @kbd{<}, @kbd{>}, @kbd{:} or @kbd{;}.  (Those few punctuation
+@kbd{@}}, @kbd{<}, @kbd{>}, @kbd{:}, and @kbd{;}.  (Those few punctuation
 characters are reserved for major modes.)
 
 @node Easy-Mmode
 @subsection Easy-Mmode
 
   The easy-mmode package provides a convenient way of implementing a
-minor mode; with it, you can specify everything about a simple minor
-mode in one self-contained definition.
+mode in one self-contained definition.  It currently supports only
+buffer-local minor modes, not global ones.
 
 @defmac easy-mmode-define-minor-mode mode doc &optional init-value mode-indicator keymap
 @tindex easy-mmode-define-minor-mode
@@ -978,35 +1013,39 @@ mode is enabled.  It initializes the keymap with key bindings for
 @section Mode Line Format
 @cindex mode line
 
-  Each Emacs window (aside from minibuffer windows) includes a mode line,
-which displays status information about the buffer displayed in the
-window.  The mode line contains information about the buffer, such as its
-name, associated file, depth of recursive editing, and the major and
-minor modes.
+  Each Emacs window (aside from minibuffer windows) typically has a mode
+line at the bottom, which displays status information about the buffer
+displayed in the window.  The mode line contains information about the
+buffer, such as its name, associated file, depth of recursive editing,
+and major and minor modes.  A window can also have a @dfn{header
+line}, which is much like the mode line but appears at the top of the
+window (starting in Emacs 21).
 
-  This section describes how the contents of the mode line are
-controlled.  We include it in this chapter because much of the
+  This section describes how to control the contents of the mode line
+and header line.  We include it in this chapter because much of the
 information displayed in the mode line relates to the enabled major and
 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 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
-changes from @code{nil} to @code{t} or vice-versa.  If you modify any of
-the variables referenced by @code{mode-line-format} (@pxref{Mode Line
-Variables}), or any other variables and data structures that affect how
-text is displayed (@pxref{Display}), you may want to force an update of
-the mode line so as to display the new information or display it in
-the new way.
+windows for the same buffer use the same @code{mode-line-format}, so
+their mode lines appear the same---except for scrolling percentages, and
+line and column numbers, since those depend on point and on how the
+window is scrolled.  @code{header-line-format} is used likewise for
+header lines.
+
+  The mode line and header line of a window are normally updated
+whenever a different buffer is shown in the window, or when the buffer's
+modified-status changes from @code{nil} to @code{t} or vice-versa.  If
+you modify any of the variables referenced by @code{mode-line-format}
+(@pxref{Mode Line Variables}), or any other variables and data
+structures that affect how text is displayed (@pxref{Display}), you may
+want to force an update of the mode line so as to display the new
+information or display it in the new way.
 
 @c Emacs 19 feature
 @defun force-mode-line-update
-Force redisplay of the current buffer's mode line.
+Force redisplay of the current buffer's mode line and header line.
 @end defun
 
   The mode line is usually displayed in inverse video; see
@@ -1016,6 +1055,8 @@ Force redisplay of the current buffer's mode line.
 * Mode Line Data::        The data structure that controls the mode line.
 * Mode Line Variables::   Variables used in that data structure.
 * %-Constructs::          Putting information into a mode line.
+* Properties in Mode::    Using text properties in the mode line.
+* Header Lines::          Like a mode line, but at the top.
 @end menu
 
 @node Mode Line Data
@@ -1034,6 +1075,9 @@ The value of this variable is a mode line construct with overall
 responsibility for the mode line format.  The value of this variable
 controls which other variables are used to form the mode line text, and
 where they appear.
+
+If you set this variable to @code{nil} in a buffer, that buffer does not
+have a mode line.  (This feature was added in Emacs 21.)
 @end defvar
 
   A mode line construct may be as simple as a fixed string of text, but
@@ -1050,6 +1094,11 @@ variables that @code{mode-line-format} refers to.
   A mode line construct may be a list, a symbol, or a string.  If the
 value is a list, each element may be a list, a symbol, or a string.
 
+  The mode line can display various faces, if the strings that control
+it have the @code{face} property.  @xref{Properties in Mode}.  In
+addition, the face @code{mode-line} is used as a default for the whole
+mode line (@pxref{Standard Faces}).
+
 @table @code
 @cindex percent symbol in mode line
 @item @var{string}
@@ -1061,7 +1110,7 @@ is left justified).  @xref{%-Constructs}.
 @item @var{symbol}
 A symbol as a mode line construct stands for its value.  The value of
 @var{symbol} is used as a mode line construct, in place of @var{symbol}.
-However, the symbols @code{t} and @code{nil} are ignored; so is any
+However, the symbols @code{t} and @code{nil} are ignored, as is any
 symbol whose value is void.
 
 There is one exception: if the value of @var{symbol} is a string, it is
@@ -1072,14 +1121,19 @@ A list whose first element is a string or list means to process all the
 elements recursively and concatenate the results.  This is the most
 common form of mode line construct.
 
+@item (:eval @var{form})
+A list whose first element is the symbol @code{:eval} says to evaluate
+@var{form}, and use the result as a string to display.
+(This feature is new as of Emacs 21.)
+
 @item (@var{symbol} @var{then} @var{else})
-A list whose first element is a symbol is a conditional.  Its meaning
-depends on the value of @var{symbol}.  If the value is non-@code{nil},
-the second element, @var{then}, is processed recursively as a mode line
-element.  But if the value of @var{symbol} is @code{nil}, the third
-element, @var{else}, is processed recursively.  You may omit @var{else};
-then the mode line element displays nothing if the value of @var{symbol}
-is @code{nil}.
+A list whose first element is a symbol that is not a keyword specifies a
+conditional.  Its meaning depends on the value of @var{symbol}.  If the
+value is non-@code{nil}, the second element, @var{then}, is processed
+recursively as a mode line element.  But if the value of @var{symbol} is
+@code{nil}, the third element, @var{else}, is processed recursively.
+You may omit @var{else}; then the mode line element displays nothing if
+the value of @var{symbol} is @code{nil}.
 
 @item (@var{width} @var{rest}@dots{})
 A list whose first element is an integer specifies truncation or
@@ -1124,7 +1178,7 @@ directory.
    "   "
    'global-mode-string
    "   %[("
-   'mode-name 
+   '(:eval (mode-line-mode-name))
    'mode-line-process  
    'minor-mode-alist 
    "%n" 
@@ -1268,7 +1322,7 @@ The default value of @code{default-mode-line-format} is this list:
  global-mode-string
 @group
  "   %[("
- mode-name 
+ (:eval (mode-line-mode-name))
  mode-line-process
  minor-mode-alist 
  "%n" 
@@ -1315,7 +1369,8 @@ The title (only on a window system) or the name of the selected frame.
 The current column number of point.
 
 @item %l
-The current line number of point.
+The current line number of point, counting within the accessible portion
+of the buffer.
 
 @item %*
 @samp{%} if the buffer is read only (see @code{buffer-read-only}); @*
@@ -1383,6 +1438,64 @@ The value of @code{global-mode-string}.  Currently, only
 @code{display-time} modifies the value of @code{global-mode-string}.
 @end table
 
+@node Properties in Mode
+@subsection Properties in the Mode Line
+
+  Starting in Emacs 21, certain text properties are meaningful in the
+mode line.  The @code{face} property affects the appearance of text; the
+@code{help-echo} property associate help strings with the text, and
+@code{local-map} can make the text mouse-sensitive.
+
+  There are three ways to specify text properties for text in the mode
+line:
+
+@enumerate
+@item
+Put a string with the @code{local-map} property directly into the
+mode-line data structure.
+
+@item
+Put a @code{local-map} property on a mode-line %-construct
+such as @samp{%12b}; then the expansion of the %-construct
+will have that same text property.
+
+@item
+Use a list containing @code{:eval @var{form}} in the mode-line data
+structure, and make @var{form} evaluate to a string that has a
+@code{local-map} property.
+@end enumerate
+
+  You use the @code{local-map} property to specify a keymap.  Like any
+keymap, it can bind character keys and function keys; but that has no
+effect, since is impossible to move point into the mode line, This
+keymap can only take real effect for mouse clicks.
+
+@node Header Lines
+@subsection Window Header Lines
+@cindex header line (of a window)
+@cindex window header line
+
+  Starting in Emacs 21, a window can have a @dfn{header line} at the
+top, just as it can have a mode line at the bottom.  The header line
+feature works just like the mode line feature, except that it's
+controlled by different variables.
+
+@tindex header-line-format
+@defvar header-line-format
+This variable, local in every buffer, specifies how to display the
+header line, for windows displaying the buffer.  The format of the value
+is the same as for @code{mode-line-format} (@xref{Mode Line Data}).
+@end defvar
+
+@tindex default-header-line-format
+@defvar default-header-line-format
+This variable holds the default @code{header-line-format} for buffers
+that do not override it.  This is the same as @code{(default-value
+'header-line-format)}.
+
+It is normally @code{nil}, so that ordinary buffers have no header line.
+@end defvar
+
 @node Imenu
 @section Imenu
 
@@ -1390,9 +1503,10 @@ The value of @code{global-mode-string}.  Currently, only
   @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.
+buffer index which lists the names and buffer positions of the
+definitions, or portions of 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}:
@@ -1413,9 +1527,10 @@ for this element should go in a submenu of the buffer index;
 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 mention in the buffer index.  The third item, @var{subexp}, indicates
-which subexpression in @var{regexp} matches the definition's name.
+(@pxref{Regular Expressions}); anything in the buffer that it matches is
+considered a 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:
 
@@ -1483,7 +1598,7 @@ For example, Fortran mode uses it this way:
 
 The @code{imenu-generic-expression} patterns can then use @samp{\\sw+}
 instead of @samp{\\(\\sw\\|\\s_\\)+}.  Note that this technique may be
-inconvenient to use when the mode needs to limit the initial character
+inconvenient when the mode needs to limit the initial character
 of a name to a smaller set of characters than are allowed in the rest
 of a name.
 
@@ -1682,7 +1797,7 @@ expression or a function, as described above.  The @sc{cdr},
 highlighted (instead of the entire text that @var{matcher} matched).
 
 @example
-;; @r{Highlight the @samp{bar} in each occurrences of @samp{fubar},}
+;; @r{Highlight the @samp{bar} in each occurrence of @samp{fubar},}
 ;; @r{using @code{font-lock-keyword-face}.}
 ("fu\\(bar\\)" . 1)
 @end example
@@ -1734,7 +1849,7 @@ Here are some examples of elements of this kind, and what they do:
 ;; @r{@code{foo-bar-face} should be a variable whose value is a face.}
 ("foo\\|bar" 0 foo-bar-face t)
 
-;; @r{Highlight the first subexpression within each occurrences}
+;; @r{Highlight the first subexpression within each occurrence}
 ;; @r{that the function @code{fubar-match} finds,}
 ;; @r{using the face which is the value of @code{fubar-face}.}
 (fubar-match 1 fubar-face)
diff --git a/lispref/nonascii.texi b/lispref/nonascii.texi
index 7b6745945df..053bdbe4f50 100644
--- a/lispref/nonascii.texi
+++ b/lispref/nonascii.texi
@@ -8,7 +8,7 @@
 @cindex multibyte characters
 @cindex non-ASCII characters
 
-  This chapter covers the special issues relating to non-@sc{ASCII}
+  This chapter covers the special issues relating to non-@sc{ascii}
 characters and how they are stored in strings and buffers.
 
 @menu
@@ -40,8 +40,8 @@ attention to the difference.
 @cindex unibyte text
   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
+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
 character set by setting the variable @code{nonascii-insert-offset}).
 
 @cindex leading code
@@ -132,30 +132,30 @@ 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 be overridden automatically.
 
-  Converting unibyte text to multibyte text leaves @sc{ASCII} characters
-unchanged, and likewise 128 through 159.  It converts the non-@sc{ASCII}
+  Converting unibyte text to multibyte text leaves @sc{ascii} characters
+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 (@pxref{Character
 Sets}).  For example, if @code{nonascii-insert-offset} is 2048, which is
 @code{(- (make-char 'latin-iso8859-1) 128)}, then the unibyte
-non-@sc{ASCII} characters correspond to Latin 1.  If it is 2688, which
+non-@sc{ascii} characters correspond to Latin 1.  If it is 2688, which
 is @code{(- (make-char 'greek-iso8859-7) 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
-@code{nonascii-insert-offset} has a reasonable value, corresponding to
-the beginning of some character set, this conversion is the inverse of
-the other: converting unibyte text to multibyte and back to unibyte
-reproduces the original unibyte text.
+  Converting multibyte text to unibyte is simpler: it discards all but
+the low 8 bits of each character code.  If @code{nonascii-insert-offset}
+has a reasonable value, corresponding to the beginning of some character
+set, this conversion is the inverse of the other: converting unibyte
+text to multibyte and back to unibyte reproduces the original unibyte
+text.
 
 @defvar nonascii-insert-offset
 @tindex nonascii-insert-offset
-This variable specifies the amount to add to a non-@sc{ASCII} character
+This variable specifies the amount to add to a non-@sc{ascii} character
 when converting unibyte text to multibyte.  It also applies when
 @code{self-insert-command} inserts a character in the unibyte
-non-@sc{ASCII} range, 128 through 255.  However, the function
+non-@sc{ascii} range, 128 through 255.  However, the function
 @code{insert-char} does not perform this conversion.
 
 The right value to use to select character set @var{cs} is @code{(-
@@ -245,7 +245,7 @@ codes.  The valid character codes for unibyte representation range from
 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 legitimate in multibyte text (though they can occur in ``raw
-bytes''; @pxref{Explicit Encoding}).  Only the @sc{ASCII} codes 0
+bytes''; @pxref{Explicit Encoding}).  Only the @sc{ascii} codes 0
 through 127 are fully legitimate in both representations.
 
 @defun char-valid-p charcode
@@ -281,7 +281,7 @@ character sets, @code{chinese-big5-1} and @code{chinese-big5-2}.
 
 @defun charsetp object
 @tindex charsetp
-Return @code{t} if @var{object} is a character set name symbol,
+Returns @code{t} if @var{object} is a symbol that names a character set,
 @code{nil} otherwise.
 @end defun
 
@@ -296,6 +296,15 @@ This function returns the name of the character set that @var{character}
 belongs to.
 @end defun
 
+@defun charset-plist charset
+@tindex charset-plist
+This function returns the charset property list of the character set
+@var{charset}.  Although @var{charset} is a symbol, this is not the same
+as the property list of that symbol.  Charset properties are used for
+special purposes within Emacs; for example, @code{x-charset-registry}
+helps determine which fonts to use (@pxref{Font Selection}).
+@end defun
+
 @node Chars and Bytes
 @section Characters and Bytes
 @cindex bytes and characters
@@ -304,7 +313,7 @@ belongs to.
 @cindex dimension (of character set)
   In multibyte representation, each character occupies one or more
 bytes.  Each character set has an @dfn{introduction sequence}, which is
-normally one or two bytes long.  (Exception: the @sc{ASCII} character
+normally one or two bytes long.  (Exception: the @sc{ascii} character
 set has a zero-length introduction sequence.)  The introduction sequence
 is the beginning of the byte sequence for any character in the character
 set.  The rest of the character's bytes distinguish it from the other
@@ -354,7 +363,7 @@ values is the character set's dimension.
      @result{} (ascii 65)
 @end example
 
-Unibyte non-@sc{ASCII} characters are considered as part of
+Unibyte non-@sc{ascii} characters are considered as part of
 the @code{ascii} character set:
 
 @example
@@ -418,7 +427,7 @@ In two peculiar cases, the value includes the symbol @code{unknown}:
 
 @itemize @bullet
 @item
-When a unibyte buffer contains non-@sc{ASCII} characters.
+When a unibyte buffer contains non-@sc{ascii} characters.
 
 @item
 When a multibyte buffer contains invalid byte-sequences (raw bytes).
@@ -445,10 +454,10 @@ for other purposes.  Some coding systems specify their own particular
 translation tables; there are also default translation tables which
 apply to all other coding systems.
 
-@defun make-translation-table translations
-This function returns a translation table based on the arguments
-@var{translations}.  Each argument---each element of
-@var{translations}---should be a list of the form @code{(@var{from}
+@defun make-translation-table &rest translations
+This function returns a translation table based on the argument
+@var{translations}.  Each element of
+@var{translations} should be a list of the form @code{(@var{from}
 . @var{to})}; this says to translate the character @var{from} into
 @var{to}.
 
@@ -495,7 +504,8 @@ subprocess or receives text from a subprocess, it normally performs
 character code conversion and end-of-line conversion as specified
 by a particular @dfn{coding system}.
 
-  How to define a coding system is an arcane matter, not yet documented.
+  How to define a coding system is an arcane matter, and is not
+documented here.
 
 @menu
 * Coding System Basics::
@@ -523,16 +533,15 @@ characters; for example, there are three coding systems for the Cyrillic
 (Russian) alphabet: ISO, Alternativnyj, and KOI8.
 
   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.
+conversion, but some of them leave the choice unspecified---to be chosen
+heuristically for each file, 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.
+DOS convention is to use a carriage-return and a linefeed at the end of
+a line.  The Mac convention is to use just carriage-return.
 
 @cindex base coding system
 @cindex variant coding system
@@ -610,10 +619,14 @@ to a subprocess.
 @defvar save-buffer-coding-system
 @tindex save-buffer-coding-system
 This variable specifies the coding system for saving the buffer---but it
-is not used for @code{write-region}.  When saving the buffer asks the
-user to specify a different coding system, and
-@code{save-buffer-coding-system} was used, then it is updated to the
-coding system that was specified.
+is not used for @code{write-region}.
+
+When a command to save the buffer starts out to use
+@code{save-buffer-coding-system}, and that coding system cannot handle
+the actual text in the buffer, the command asks the user to choose
+another coding system.  After that happens, the command also updates
+@code{save-buffer-coding-system} to represent the coding system that the
+user specified.
 @end defvar
 
 @defvar last-coding-system-used
@@ -623,8 +636,8 @@ coding system name that was used.  The explicit encoding and decoding
 functions (@pxref{Explicit Encoding}) set it too.
 
 @strong{Warning:} Since receiving subprocess output sets this variable,
-it can change whenever Emacs waits; therefore, you should use copy the
-value shortly after the function call which stores the value you are
+it can change whenever Emacs waits; therefore, you should copy the
+value shortly after the function call that stores the value you are
 interested in.
 @end defvar
 
@@ -634,7 +647,7 @@ selections for the window system.  @xref{Window System Selections}.
 @node Lisp and Coding Systems
 @subsection Coding Systems in Lisp
 
-  Here are Lisp facilities for working with coding systems;
+  Here are the Lisp facilities for working with coding systems:
 
 @defun coding-system-list &optional base-only
 @tindex coding-system-list
@@ -711,7 +724,7 @@ decreasing priority.  But if @var{highest} is non-@code{nil}, then the
 return value is just one coding system, the one that is highest in
 priority.
 
-If the region contains only @sc{ASCII} characters, the value
+If the region contains only @sc{ascii} characters, the value
 is @code{undecided} or @code{(undecided)}.
 @end defun
 
@@ -788,13 +801,14 @@ expression that matches certain file names.  The element applies to file
 names that match @var{pattern}.
 
 The @sc{cdr} of the element, @var{coding}, should be either a coding
-system, a cons cell containing two coding systems, or a function symbol.
-If @var{val} is a coding system, that coding system is used for both
-reading the file and writing it.  If @var{val} is a cons cell containing
-two coding systems, its @sc{car} specifies the coding system for
-decoding, and its @sc{cdr} specifies the coding system for encoding.
-
-If @var{val} is a function symbol, the function must return a coding
+system, a cons cell containing two coding systems, or a function name (a
+symbol with a function definition).  If @var{coding} is a coding system,
+that coding system is used for both reading the file and writing it.  If
+@var{coding} is a cons cell containing two coding systems, its @sc{car}
+specifies the coding system for decoding, and its @sc{cdr} specifies the
+coding system for encoding.
+
+If @var{coding} is a function name, the function must return a coding
 system or a cons cell containing two coding systems.  This value is used
 as described above.
 @end defvar
@@ -810,8 +824,8 @@ coding systems used for I/O to the subprocess, but you can specify
 other coding systems later using @code{set-process-coding-system}.
 @end defvar
 
-  @strong{Warning:} Coding systems such as @code{undecided} which
-determine the coding system from the data do not work entirely reliably
+  @strong{Warning:} Coding systems such as @code{undecided}, which
+determine the coding system from the data, do not work entirely reliably
 with asynchronous subprocess output.  This is because Emacs handles
 asynchronous subprocess output in batches, as it arrives.  If the coding
 system leaves the character code conversion unspecified, or leaves the
@@ -859,13 +873,14 @@ for decoding (in case @var{operation} does decoding), and
 @var{encoding-system} is the coding system for encoding (in case
 @var{operation} does encoding).
 
-The argument @var{operation} should be an Emacs I/O primitive:
+The argument @var{operation} should be a symbol, one of
 @code{insert-file-contents}, @code{write-region}, @code{call-process},
 @code{call-process-region}, @code{start-process}, or
-@code{open-network-stream}.
+@code{open-network-stream}.  These are the names of the Emacs I/O primitives
+that can do coding system conversion.
 
 The remaining arguments should be the same arguments that might be given
-to that I/O primitive.  Depending on which primitive, one of those
+to that I/O primitive.  Depending on the primitive, one of those
 arguments is selected as the @dfn{target}.  For example, if
 @var{operation} does file I/O, whichever argument specifies the file
 name is the target.  For subprocess primitives, the process name is the
@@ -1079,13 +1094,15 @@ that means do not encode terminal output.
 @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.  By ``binary file'' we mean a file of
-literal byte values that are not necessary meant to be characters.
-Emacs does no end-of-line conversion and no character code conversion
-for a binary file.  Meanwhile, when you create a new file which is
-marked by its name as a ``text file'', Emacs uses DOS end-of-line
-conversion.
+  On MS-DOS and Microsoft Windows, Emacs guesses the appropriate
+end-of-line conversion for a file by looking at the file's name.  This
+feature classifies fils as @dfn{text files} and @dfn{binary files}.  By
+``binary file'' we mean a file of literal byte values that are not
+necessarily meant to be characters; Emacs does no end-of-line conversion
+and no character code conversion for them.  On the other hand, the bytes
+in a text file are intended to represent characters; when you create a
+new file whose name implies that it is a text file, Emacs uses DOS
+end-of-line conversion.
 
 @defvar buffer-file-type
 This variable, automatically buffer-local in each buffer, records the
@@ -1108,7 +1125,7 @@ Each element has the form (@var{regexp} . @var{type}), where
 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
+When running on MS-DOS or MS-Windows, Emacs 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.
@@ -1131,9 +1148,9 @@ from the file contents, in the usual Emacs fashion.
 @section Input Methods
 @cindex input methods
 
-  @dfn{Input methods} provide convenient ways of entering non-@sc{ASCII}
+  @dfn{Input methods} provide convenient ways of entering non-@sc{ascii}
 characters from the keyboard.  Unlike coding systems, which translate
-non-@sc{ASCII} characters to and from encodings meant to be read by
+non-@sc{ascii} characters to and from encodings meant to be read by
 programs, input methods provide human-friendly commands.  (@xref{Input
 Methods,,, emacs, The GNU Emacs Manual}, for information on how users
 use input methods to enter text.)  How to define input methods is not
diff --git a/lispref/numbers.texi b/lispref/numbers.texi
index 3bba60a7f9f..eda707e9040 100644
--- a/lispref/numbers.texi
+++ b/lispref/numbers.texi
@@ -40,14 +40,14 @@ minimum range is @minus{}134217728 to 134217727 (28 bits; i.e.,
 -2**27
 @end ifinfo
 @tex 
-$-2^{27}$
+@math{-2^{27}}
 @end tex
 to 
 @ifinfo 
 2**27 - 1),
 @end ifinfo
 @tex 
-$2^{27}-1$),
+@math{2^{27}-1}),
 @end tex
 but some machines may provide a wider range.  Many examples in this
 chapter assume an integer has 28 bits.
@@ -312,6 +312,8 @@ otherwise.
 
 @defun max number-or-marker &rest numbers-or-markers
 This function returns the largest of its arguments.
+If any of the argument is floating-point, the value is returned
+as floating point, even if it was given as an integer.
 
 @example
 (max 20)
@@ -319,12 +321,14 @@ This function returns the largest of its arguments.
 (max 1 2.5)
      @result{} 2.5
 (max 1 3 2.5)
-     @result{} 3
+     @result{} 3.0
 @end example
 @end defun
 
 @defun min number-or-marker &rest numbers-or-markers
 This function returns the smallest of its arguments.
+If any of the argument is floating-point, the value is returned
+as floating point, even if it was given as an integer.
 
 @example
 (min -4 1)
@@ -958,14 +962,14 @@ The value of @code{(asin @var{arg})} is a number between
 @minus{}pi/2
 @end ifinfo
 @tex
-$-\pi/2$
+@math{-\pi/2}
 @end tex
 and
 @ifinfo
 pi/2
 @end ifinfo
 @tex
-$\pi/2$
+@math{\pi/2}
 @end tex
 (inclusive) whose sine is @var{arg}; if, however, @var{arg}
 is out of range (outside [-1, 1]), then the result is a NaN.
@@ -977,7 +981,7 @@ The value of @code{(acos @var{arg})} is a number between 0 and
 pi
 @end ifinfo
 @tex
-$\pi$
+@math{\pi}
 @end tex
 (inclusive) whose cosine is @var{arg}; if, however, @var{arg}
 is out of range (outside [-1, 1]), then the result is a NaN.
@@ -989,14 +993,14 @@ The value of @code{(atan @var{arg})} is a number between
 @minus{}pi/2
 @end ifinfo
 @tex
-$-\pi/2$
+@math{-\pi/2}
 @end tex
 and
 @ifinfo
 pi/2
 @end ifinfo
 @tex
-$\pi/2$
+@math{\pi/2}
 @end tex
 (exclusive) whose tangent is @var{arg}.
 @end defun
@@ -1004,14 +1008,14 @@ $\pi/2$
 @defun exp arg
 This is the exponential function; it returns
 @tex
-$e$
+@math{e}
 @end tex
 @ifinfo
 @i{e}
 @end ifinfo
 to the power @var{arg}.
 @tex
-$e$
+@math{e}
 @end tex
 @ifinfo
 @i{e}
@@ -1024,7 +1028,7 @@ logarithms.
 This function returns the logarithm of @var{arg}, with base @var{base}.
 If you don't specify @var{base}, the base
 @tex
-$e$
+@math{e}
 @end tex
 @ifinfo
 @i{e}
@@ -1085,9 +1089,9 @@ first call to @code{(random)} after you start Emacs always returns
 -1457731, and the second one always returns -7692030.  This
 repeatability is helpful for debugging.
 
-If you want truly unpredictable random numbers, execute @code{(random
-t)}.  This chooses a new seed based on the current time of day and on
-Emacs's process @sc{id} number.
+If you want random numbers that don't always come out the same, execute
+@code{(random t)}.  This chooses a new seed based on the current time of
+day and on Emacs's process @sc{id} number.
 
 @defun random &optional limit
 This function returns a pseudo-random integer.  Repeated calls return a
diff --git a/lispref/objects.texi b/lispref/objects.texi
index fcd50f3c1e9..7a70f4417ac 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}, plus
+@dfn{string}, @dfn{vector}, @dfn{subr}, and @dfn{byte-code function}, plus
 several special types, such as @dfn{buffer}, that are related to
 editing.  (@xref{Editing Types}.)
 
@@ -52,6 +52,7 @@ to use these types can be found in later chapters.
 * Comments::                    Comments and their formatting conventions.
 * Programming Types::           Types found in all Lisp systems.
 * Editing Types::               Types specific to Emacs.
+* Circular Objects::            Read syntax for circular structure.
 * Type Predicates::             Tests related to types.
 * Equality Predicates::         Tests of equality between any two objects.
 @end menu
@@ -146,6 +147,7 @@ latter are unique to Emacs Lisp.
 * Vector Type::         One-dimensional arrays.
 * Char-Table Type::     One-dimensional sparse arrays indexed by characters.
 * Bool-Vector Type::    One-dimensional arrays of @code{t} or @code{nil}.
+* Hash Table Type::     Super-fast lookup tables.
 * Function Type::       A piece of executable code you can call from elsewhere.
 * Macro Type::          A method of expanding an expression into another
                           expression, more fundamental but less pretty.
@@ -164,14 +166,14 @@ latter are unique to Emacs Lisp.
 -2**27
 @end ifinfo
 @tex
-$-2^{27}$
+@math{-2^{27}}
 @end tex
 to
 @ifinfo
 2**27 - 1)
 @end ifinfo
 @tex
-$2^{28}-1$)
+@math{2^{28}-1})
 @end tex
 on most machines.  (Some machines may provide a wider range.)  It is
 important to note that the Emacs Lisp arithmetic functions do not check
@@ -187,7 +189,7 @@ leading @samp{+} or a final @samp{.}.
 @group
 -1               ; @r{The integer -1.}
 1                ; @r{The integer 1.}
-1.               ; @r{Also The integer 1.}
+1.               ; @r{Also the integer 1.}
 +1               ; @r{Also the integer 1.}
 268435457        ; @r{Also the integer 1 on a 28-bit implementation.}
 @end group
@@ -212,7 +214,7 @@ number whose value is 1500.  They are all equivalent.
 
 @node Character Type
 @subsection Character Type
-@cindex @sc{ASCII} character codes
+@cindex @sc{ascii} character codes
 
   A @dfn{character} in Emacs Lisp is nothing more than an integer.  In
 other words, characters are represented by their character codes.  For
@@ -290,6 +292,7 @@ respectively.  Thus,
 ?\r @result{} 13                ; @r{carriage return, @key{RET}, @kbd{C-m}}
 ?\e @result{} 27                ; @r{escape character, @key{ESC}, @kbd{C-[}}
 ?\\ @result{} 92                ; @r{backslash character, @kbd{\}}
+?\d @result{} 127               ; @r{delete character, @key{DEL}}
 @end example
 
 @cindex escape sequence
@@ -312,17 +315,17 @@ equivalent to @samp{?\^I} and to @samp{?\^i}:
 @end example
 
   In strings and buffers, the only control characters allowed are those
-that exist in @sc{ASCII}; but for keyboard input purposes, you can turn
+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
+codes for these non-@sc{ascii} control characters include the
 @tex
-$2^{26}$
+@math{2^{26}}
 @end tex
 @ifinfo
 2**26
 @end ifinfo
 bit as well as the code for the corresponding non-control
-character.  Ordinary terminals have no way of generating non-@sc{ASCII}
+character.  Ordinary terminals have no way of generating non-@sc{ascii}
 control characters, but you can generate them straightforwardly using X
 and other window systems.
 
@@ -349,7 +352,7 @@ people who read it.
   A @dfn{meta character} is a character typed with the @key{META}
 modifier key.  The integer that represents such a character has the
 @tex
-$2^{27}$
+@math{2^{27}}
 @end tex
 @ifinfo
 2**27
@@ -360,14 +363,14 @@ of basic character codes.
 
   In a string, the
 @tex
-$2^{7}$
+@math{2^{7}}
 @end tex
 @ifinfo
 2**7
 @end ifinfo
 bit attached to an ASCII character indicates a meta character; thus, the
 meta characters that can fit in a string have codes in the range from
-128 to 255, and are the meta versions of the ordinary @sc{ASCII}
+128 to 255, and are the meta versions of the ordinary @sc{ascii}
 characters.  (In Emacs versions 18 and older, this convention was used
 for characters outside of strings as well.)
 
@@ -379,11 +382,11 @@ or as @samp{?\M-\101}.  Likewise, you can write @kbd{C-M-b} as
 @samp{?\M-\C-b}, @samp{?\C-\M-b}, or @samp{?\M-\002}.
 
   The case of a graphic character is indicated by its character code;
-for example, @sc{ASCII} distinguishes between the characters @samp{a}
-and @samp{A}.  But @sc{ASCII} has no way to represent whether a control
+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
 @tex
-$2^{25}$
+@math{2^{25}}
 @end tex
 @ifinfo
 2**25
@@ -405,7 +408,7 @@ significant in these prefixes.)  Thus, @samp{?\H-\M-\A-x} represents
 @kbd{Alt-Hyper-Meta-x}.
 @tex
 Numerically, the
-bit values are $2^{22}$ for alt, $2^{23}$ for super and $2^{24}$ for hyper.
+bit values are @math{2^{22}} for alt, @math{2^{23}} for super and @math{2^{24}} for hyper.
 @end tex
 @ifinfo
 Numerically, the
@@ -420,9 +423,9 @@ character code in either octal or hex.  To use octal, write a question
 mark followed by a backslash and the octal character code (up to three
 octal digits); thus, @samp{?\101} for the character @kbd{A},
 @samp{?\001} for the character @kbd{C-a}, and @code{?\002} for the
-character @kbd{C-b}.  Although this syntax can represent any @sc{ASCII}
+character @kbd{C-b}.  Although this syntax can represent any @sc{ascii}
 character, it is preferred only when the precise octal value is more
-important than the @sc{ASCII} representation.
+important than the @sc{ascii} representation.
 
 @example
 @group
@@ -520,6 +523,11 @@ char-to-string      ; @r{A symbol named @samp{char-to-string}.}
 @end group
 @end example
 
+@cindex @samp{#:} read syntax
+  Normally the Lisp reader interns all symbols (@pxref{Creating
+Symbols}).  To prevent interning, you can write @samp{#:} before the
+name of the symbol.
+
 @node Sequence Type
 @subsection Sequence Types
 
@@ -559,7 +567,7 @@ same object, @code{nil}.
 
   A @dfn{cons cell} is an object that consists of two slots, called the
 @sc{car} slot and the @sc{cdr} slot.  Each slot can @dfn{hold} or
-@dfn{refer to} any Lisp object.  We also say that the ``the @sc{car} of
+@dfn{refer to} any Lisp object.  We also say that ``the @sc{car} of
 this cons cell is'' whatever object its @sc{car} slot currently holds,
 and likewise for the @sc{cdr}.
 
@@ -794,7 +802,8 @@ sets the variable @code{alist-of-colors} to an alist of three elements.  In the
 first element, @code{rose} is the key and @code{red} is the value.
 
   @xref{Association Lists}, for a further explanation of alists and for
-functions that work on alists.
+functions that work on alists.  @xref{Hash Tables}, for another kind of
+lookup table, which is much faster for handling a large number of keys.
 
 @node Array Type
 @subsection Array Type
@@ -884,9 +893,9 @@ but the newline is ignored if escaped."
 @node Non-ASCII in Strings
 @subsubsection Non-ASCII Characters in Strings
 
-  You can include a non-@sc{ASCII} international character in a string
+  You can include a non-@sc{ascii} international character in a string
 constant by writing it literally.  There are two text representations
-for non-@sc{ASCII} characters in Emacs strings (and in buffers): unibyte
+for non-@sc{ascii} characters in Emacs strings (and in buffers): unibyte
 and multibyte.  If the string constant is read from a multibyte source,
 such as a multibyte buffer or string, or a file that would be visited as
 multibyte, then the character is read as a multibyte character, and that
@@ -895,7 +904,7 @@ unibyte source, then the character is read as unibyte and that makes the
 string unibyte.
 
   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
+character code: use a hex escape, @samp{\x@var{nnnnnnn}}, with as many
 digits as necessary.  (Multibyte non-@sc{ASCII} character codes are all
 greater than 256.)  Any character which is not a valid hex digit
 terminates this construct.  If the next character in the string could be
@@ -906,7 +915,7 @@ constant is just like backslash-newline; it does not contribute any
 character to the string, but it does terminate the preceding hex escape.
 
   Using a multibyte hex escape forces the string to multibyte.  You can
-represent a unibyte non-@sc{ASCII} character with its character code,
+represent a unibyte non-@sc{ascii} character with its character code,
 which must be in the range from 128 (0200 octal) to 255 (0377 octal).
 This forces a unibyte string.
   
@@ -925,16 +934,16 @@ description of the read syntax for characters.
 
   However, not all of the characters you can write with backslash
 escape-sequences are valid in strings.  The only control characters that
-a string can hold are the @sc{ASCII} control characters.  Strings do not
-distinguish case in @sc{ASCII} control characters.
+a string can hold are the @sc{ascii} control characters.  Strings do not
+distinguish case in @sc{ascii} control characters.
 
   Properly speaking, strings cannot hold meta characters; but when a
 string is to be used as a key sequence, there is a special convention
-that provides a way to represent meta versions of @sc{ASCII} characters in a
+that provides a way to represent meta versions of @sc{ascii} characters in a
 string.  If you use the @samp{\M-} syntax to indicate a meta character
 in a string constant, this sets the
 @tex
-$2^{7}$
+@math{2^{7}}
 @end tex
 @ifinfo
 2**7
@@ -1043,7 +1052,7 @@ Syntax tables (@pxref{Syntax Tables}).
   A @dfn{bool-vector} is a one-dimensional array of elements that
 must be @code{t} or @code{nil}.
 
-  The printed representation of a Bool-vector is like a string, except
+  The printed representation of a bool-vector is like a string, except
 that it begins with @samp{#&} followed by the length.  The string
 constant that follows actually specifies the contents of the bool-vector
 as a bitmap---each ``character'' in the string contains 8 bits, which
@@ -1063,6 +1072,19 @@ these extras really make no difference.
      @result{} t
 @end example
 
+@node Hash Table Type
+@subsection Hash Table Type
+
+    A hash table is a very fast kind of lookup table, somewhat like an
+alist in that it maps keys to corresponding values, but much faster.
+Hash tables are a new feature in Emacs 21; they have no read syntax, and
+print using hash notation.  @xref{Hash Tables}.
+
+@example
+(make-hash-table)
+     @result{} #<hash-table 'eql nil 0/65 0x83af980>
+@end example
+
 @node Function Type
 @subsection Function Type
 
@@ -1156,11 +1178,11 @@ opening @samp{[}.
 @subsection Autoload Type
 
   An @dfn{autoload object} is a list whose first element is the symbol
-@code{autoload}.  It is stored as the function definition of a symbol as
-a placeholder for the real definition; it says that the real definition
-is found in a file of Lisp code that should be loaded when necessary.
-The autoload object contains the name of the file, plus some other
-information about the real definition.
+@code{autoload}.  It is stored as the function definition of a symbol,
+where it serves as a placeholder for the real definition.  The autoload
+object says that the real definition is found in a file of Lisp code
+that should be loaded when necessary.  It contains the name of the file,
+plus some other information about the real definition.
 
   After the file has been loaded, the symbol should have a new function
 definition that is not an autoload object.  The new definition is then
@@ -1207,9 +1229,9 @@ 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, 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.
+existing buffer, altering the buffer's contents, whereas ``inserting''
+text into a string requires concatenating substrings, and the result is
+an entirely new string object.
 
   Each buffer has a designated position called @dfn{point}
 (@pxref{Positions}).  At any time, one buffer is the @dfn{current
@@ -1431,6 +1453,69 @@ positions.
 
   @xref{Overlays}, for how to create and use overlays.
 
+@node Circular Objects
+@section Read Syntax for Circular Objects
+@cindex circular structure, read syntax
+@cindex shared structure, read syntax
+@cindex @samp{#@var{n}=} read syntax
+@cindex @samp{#@var{n}#} read syntax
+
+  In Emacs 21, to represent shared or circular structure within a
+complex of Lisp objects, you can use the reader constructs
+@samp{#@var{n}=} and @samp{#@var{n}#}.
+
+  Use @code{#@var{n}=} before an object to label it for later reference;
+subsequently, you can use @code{#@var{n}#} to refer the same object in
+another place.  Here, @var{n} is some integer.  For example, here is how
+to make a list in which the first element recurs as the third element:
+
+@example
+(#1=(a) b #1#)
+@end example
+
+@noindent
+This differs from ordinary syntax such as this
+
+@example
+((a) b (a))
+@end example
+
+@noindent
+which would result in a list whose first and third elements
+look alike but are not the same Lisp object.  This shows the difference:
+
+@example
+(prog1 nil
+  (setq x '(#1=(a) b #1#)))
+(eq (nth 0 x) (nth 2 x))
+     @result{} t
+(setq x '((a) b (a)))
+(eq (nth 0 x) (nth 2 x))
+     @result{} nil
+@end example
+
+  You can also use the same syntax to make a circular structure, which
+appears as an ``element'' within itself.  Here is an example:
+
+@example
+#1=(a #1#)
+@end example
+
+@noindent
+This makes a list whose second element is the list itself.
+Here's how you can see that it really works:
+
+@example
+(prog1 nil
+  (setq x '#1=(a #1#)))
+(eq x (cadr x))
+     @result{} t
+@end example
+
+  The Lisp printer can produce this syntax to record circular and shared
+structure in a Lisp object, if you bind the variable @code{print-circle}
+to a non-@code{nil} value.  @xref{Output Variables}.
+
 @node Type Predicates
 @section Type Predicates
 @cindex predicates
@@ -1764,7 +1849,7 @@ arguments to see if their elements are the same.  So, if two objects are
 Comparison of strings is case-sensitive, but does not take account of
 text properties---it compares only the characters in the strings.
 A unibyte string never equals a multibyte string unless the
-contents are entirely @sc{ASCII} (@pxref{Text Representations}).
+contents are entirely @sc{ascii} (@pxref{Text Representations}).
 
 @example
 @group
diff --git a/lispref/os.texi b/lispref/os.texi
index 380b67abb17..06c297ab881 100644
--- a/lispref/os.texi
+++ b/lispref/os.texi
@@ -15,7 +15,7 @@ and flow control.
 pertaining to the terminal and the screen.
 
 @menu
-* Starting Up::         Customizing Emacs start-up processing.
+* Starting Up::         Customizing Emacs startup processing.
 * Getting Out::         How exiting works (permanent or temporary).
 * System Environment::  Distinguish the name and kind of system.
 * User Identification:: Finding the name and user id of the user.
@@ -25,6 +25,7 @@ pertaining to the terminal and the screen.
 * Timers::              Setting a timer to call a function at a certain time.
 * Terminal Input::      Recording terminal input for debugging.
 * Terminal Output::     Recording terminal output for debugging.
+* Sound Output::        Playing sounds on the computer's speaker.
 * Special Keysyms::     Defining system-specific key symbols for X windows.
 * Flow Control::        How to turn output flow control on or off.
 * Batch Mode::          Running Emacs without terminal interaction.
@@ -37,17 +38,17 @@ pertaining to the terminal and the screen.
 can customize these actions.
 
 @menu
-* Start-up Summary::        Sequence of actions Emacs performs at start-up.
+* Startup Summary::         Sequence of actions Emacs performs at startup.
 * Init File::               Details on reading the init file (@file{.emacs}).
 * Terminal-Specific::       How the terminal-specific Lisp file is read.
-* Command Line Arguments::  How command line arguments are processed,
+* Command-Line Arguments::  How command-line arguments are processed,
                               and how you can customize them.
 @end menu
 
-@node Start-up Summary
-@subsection Summary: Sequence of Actions at Start Up
+@node Startup Summary
+@subsection Summary: Sequence of Actions at Startup
 @cindex initialization
-@cindex start up of Emacs
+@cindex startup of Emacs
 @cindex @file{startup.el}
 
    The order of operations performed (in @file{startup.el}) by Emacs when
@@ -86,7 +87,7 @@ It loads the library @file{site-start}, unless the option
 @item 
 It loads the file @file{~/.emacs}, unless @samp{-q} or @samp{-batch} was
 specified on the command line.  The @samp{-u} option can specify another
-user name whose home directory should be used instead of @file{~}.
+user whose home directory should be used instead of @file{~}.
 
 @item 
 It loads the library @file{default}, unless @code{inhibit-default-init}
@@ -127,7 +128,7 @@ It runs @code{window-setup-hook}.  @xref{Window Systems}.
 
 @item 
 It displays copyleft, nonwarranty, and basic use information, provided
-there were no remaining command line arguments (a few steps above),
+there were no remaining command-line arguments (a few steps above),
 the value of @code{inhibit-startup-message} is @code{nil}, and the
 buffer is still empty.
 @end enumerate
@@ -170,12 +171,12 @@ message for someone else.
 @cindex @file{.emacs}
 
   When you start Emacs, it normally attempts to load the file
-@file{.emacs} from your home directory.  This file, if it exists, must
-contain Lisp code.  It is called your @dfn{init file}.  The command line
-switches @samp{-q} and @samp{-u} affect the use of the init file;
-@samp{-q} says not to load an init file, and @samp{-u} says to load a
-specified user's init file instead of yours.  @xref{Entering Emacs,,,
-emacs, The GNU Emacs Manual}.
+@file{.emacs} from your home directory.  This file is called your
+@dfn{init file}.  If it exists, it must contain Lisp code.  The
+command-line switches @samp{-q} and @samp{-u} affect the use of the init
+file; @samp{-q} says not to load an init file, and @samp{-u} says to
+load a specified user's init file instead of yours.  @xref{Entering
+Emacs,,, emacs, The GNU Emacs Manual}.
 
 @cindex default init file
   A site may have a @dfn{default init file}, which is the library named
@@ -200,9 +201,8 @@ Emacs.
 @end defvar
 
   If there is a great deal of code in your @file{.emacs} file, you
-should move it into another file named @file{@var{something}.el},
-byte-compile it (@pxref{Byte Compilation}), and make your @file{.emacs}
-file load the other file using @code{load} (@pxref{Loading}).
+can make it load faster by renaming it to @file{.emacs.el}
+and then byte-compiling it (@pxref{Byte Compilation}).
 
   @xref{Init File Examples,,, emacs, The GNU Emacs Manual}, for
 examples of how to make various commonly desired customizations in your
@@ -234,7 +234,8 @@ before the terminal-specific initialization.
   Each terminal type can have its own Lisp library that Emacs loads when
 run on that type of terminal.  The library's name is constructed by
 concatenating the value of the variable @code{term-file-prefix} and the
-terminal type.  Normally, @code{term-file-prefix} has the value
+terminal type (specified by the environment variable @code{TERM}).
+Normally, @code{term-file-prefix} has the value
 @code{"term/"}; changing this is not recommended.  Emacs finds the file
 in the normal manner, by searching the @code{load-path} directories, and
 trying the @samp{.elc} and @samp{.el} suffixes.
@@ -279,6 +280,9 @@ You may set the @code{term-file-prefix} variable to @code{nil} in your
 @file{.emacs} file if you do not wish to load the
 terminal-initialization file.  To do this, put the following in
 your @file{.emacs} file: @code{(setq term-file-prefix nil)}.
+
+On MS-DOS, if the environment variable @code{TERM} is not set, Emacs
+uses @samp{internal} as the terminal type.
 @end defvar
 
 @defvar term-setup-hook 
@@ -293,27 +297,27 @@ terminal-specific file.
   See @code{window-setup-hook} in @ref{Window Systems}, for a related
 feature.
 
-@node Command Line Arguments
-@subsection Command Line Arguments
-@cindex command line arguments
+@node Command-Line Arguments
+@subsection Command-Line Arguments
+@cindex command-line arguments
 
-  You can use command line arguments to request various actions when you
+  You can use command-line arguments to request various actions when you
 start Emacs.  Since you do not need to start Emacs more than once per
 day, and will often leave your Emacs session running longer than that,
-command line arguments are hardly ever used.  As a practical matter, it
+command-line arguments are hardly ever used.  As a practical matter, it
 is best to avoid making the habit of using them, since this habit would
 encourage you to kill and restart Emacs unnecessarily often.  These
 options exist for two reasons: to be compatible with other editors (for
 invocation by other programs) and to enable shell scripts to run
 specific Lisp programs.
 
-  This section describes how Emacs processes command line arguments,
+  This section describes how Emacs processes command-line arguments,
 and how you can customize them.
 
 @ignore
   (Note that some other editors require you to start afresh each time
 you want to edit a file.  With this kind of editor, you will probably
-specify the file as a command line argument.  The recommended way to
+specify the file as a command-line argument.  The recommended way to
 use GNU Emacs is to start it only once, just after you log in, and do
 all your editing in the same Emacs process.  Each time you want to edit
 a different file, you visit it with the existing Emacs, which eventually
@@ -333,19 +337,19 @@ processed.
 
 If you redump Emacs by calling @code{dump-emacs}, you may wish to set
 this variable to @code{nil} first in order to cause the new dumped Emacs
-to process its new command line arguments.
+to process its new command-line arguments.
 @end defvar
 
 @defvar command-switch-alist
 @cindex switches on command line
 @cindex options on command line
-@cindex command line options
+@cindex command-line options
 The value of this variable is an alist of user-defined command-line
 options and associated handler functions.  This variable exists so you
 can add elements to it.
 
-A @dfn{command line option} is an argument on the command line of the
-form:
+A @dfn{command-line option} is an argument on the command line, which
+has the form:
 
 @example
 -@var{option}
@@ -357,8 +361,10 @@ The elements of the @code{command-switch-alist} look like this:
 (@var{option} . @var{handler-function})
 @end example
 
-The @var{handler-function} is called to handle @var{option} and receives
-the option name as its sole argument.
+The @sc{car}, @var{option}, is a string, the name of a command-line
+option (not including the initial hyphen).  The @var{handler-function}
+is called to handle @var{option}, and receives the option name as its
+sole argument.
 
 In some cases, the option is followed in the command line by an
 argument.  In these cases, the @var{handler-function} can find all the
@@ -366,14 +372,14 @@ remaining command-line arguments in the variable
 @code{command-line-args-left}.  (The entire list of command-line
 arguments is in @code{command-line-args}.)
 
-The command line arguments are parsed by the @code{command-line-1}
+The command-line arguments are parsed by the @code{command-line-1}
 function in the @file{startup.el} file.  See also @ref{Command
 Switches, , Command Line Switches and Arguments, emacs, The GNU Emacs
 Manual}.
 @end defvar
 
 @defvar command-line-args
-The value of this variable is the list of command line arguments passed
+The value of this variable is the list of command-line arguments passed
 to Emacs.
 @end defvar
 
@@ -436,10 +442,10 @@ input) can read them.
 @end defun
 
   All the information in the Emacs process, aside from files that have
-been saved, is lost when the Emacs is killed.  Because killing Emacs
-inadvertently can lose a lot of work, Emacs queries for confirmation
-before actually terminating if you have buffers that need saving or
-subprocesses that are running.  This is done in the function
+been saved, is lost when the Emacs process is killed.  Because killing
+Emacs inadvertently can lose a lot of work, Emacs queries for
+confirmation before actually terminating if you have buffers that need
+saving or subprocesses that are running.  This is done in the function
 @code{save-buffers-kill-emacs}.
 
 @defvar kill-emacs-query-functions
@@ -475,7 +481,7 @@ subprocess of Emacs.  Then you would exit the shell to return to Emacs.
 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.
+a window system (X Windows or MS Windows).
 
 @defun suspend-emacs string
 This function stops Emacs and returns control to the superior process.
@@ -545,11 +551,12 @@ Resumed!
 @end defun
 
 @defvar suspend-hook
-This variable is a normal hook run before suspending.
+This variable is a normal hook that Emacs runs before suspending.
 @end defvar
 
 @defvar suspend-resume-hook
-This variable is a normal hook run after suspending.
+This variable is a normal hook that Emacs runs on resuming
+after a suspension.
 @end defvar
 
 @node System Environment
@@ -598,7 +605,9 @@ Hewlett-Packard HPUX operating system.
 Silicon Graphics Irix system.
 
 @item ms-dos
-Microsoft MS-DOS ``operating system.''
+Microsoft MS-DOS ``operating system.''  Emacs compiled with DJGPP for
+MS-DOS binds @code{system-type} to @code{ms-dos} even when you run it on
+MS-Windows.
 
 @item next-mach
 NeXT Mach-based system.
@@ -616,7 +625,8 @@ AT&T System V.
 VAX VMS.
 
 @item windows-nt
-Microsoft windows NT.
+Microsoft windows NT.  The same executable supports Windows 9X, but the
+value of @code{system-type} is @code{windows-nt} in either case.
 
 @item xenix
 SCO Xenix 386.
@@ -710,7 +720,7 @@ process-environment
 This variable holds a string which says which character separates
 directories in a search path (as found in an environment variable).  Its
 value is @code{":"} for Unix and GNU systems, and @code{";"} for MS-DOS
-and Windows NT.
+and MS-Windows.
 @end defvar
 
 @defvar invocation-name
@@ -770,10 +780,11 @@ in the system's terminal driver, before Emacs was started.
 
 @defun setprv privilege-name &optional setp getprv
 This function sets or resets a VMS privilege.  (It does not exist on
-Unix.)  The first arg is the privilege name, as a string.  The second
-argument, @var{setp}, is @code{t} or @code{nil}, indicating whether the
-privilege is to be turned on or off.  Its default is @code{nil}.  The
-function returns @code{t} if successful, @code{nil} otherwise.
+other systems.)  The first argument is the privilege name, as a string.
+The second argument, @var{setp}, is @code{t} or @code{nil}, indicating
+whether the privilege is to be turned on or off.  Its default is
+@code{nil}.  The function returns @code{t} if successful, @code{nil}
+otherwise.
 
   If the third argument, @var{getprv}, is non-@code{nil}, @code{setprv}
 does not change the privilege, but returns @code{t} or @code{nil}
@@ -785,7 +796,7 @@ indicating whether the privilege is currently enabled.
 
 @defvar init-file-user
 This variable says which user's init files should be used by Emacs---or
-@code{nil} if none.  The value reflects command line options such as
+@code{nil} if none.  The value reflects command-line options such as
 @samp{-q} or @samp{-u @var{user}}.
 
 Lisp packages that load files of customizations, or any other sort of
@@ -830,8 +841,9 @@ environment variables @code{LOGNAME} and @code{USER}.
 
 @defun user-full-name &optional uid
 This function returns the full name of the logged-in user---or the value
-of the environment variables @code{NAME}, if that is set.
+of the environment variable @code{NAME}, if that is set.
 
+@c "Bil" is the correct spelling.
 @example
 @group
 (user-full-name)
@@ -907,7 +919,7 @@ two elements are integers.  Thus, you can use times obtained from
 This function returns the system's time value as a list of three
 integers: @code{(@var{high} @var{low} @var{microsec})}.  The integers
 @var{high} and @var{low} combine to give the number of seconds since
-0:00 January 1, 1970, which is
+0:00 January 1, 1970 (local time), which is
 @ifinfo
 @var{high} * 2**16 + @var{low}.
 @end ifinfo
@@ -916,8 +928,8 @@ $high*2^{16}+low$.
 @end tex
 
 The third element, @var{microsec}, gives the microseconds since the
-start of the current second (or 0 for systems that return time only on
-the resolution of a second).
+start of the current second (or 0 for systems that return time with
+the resolution of only one second).
 
 The first two elements can be compared with file time values such as you
 get with the function @code{file-attributes}.  @xref{File Attributes}.
@@ -931,7 +943,7 @@ in.
 The value has the form @code{(@var{offset} @var{name})}.  Here
 @var{offset} is an integer giving the number of seconds ahead of UTC
 (east of Greenwich).  A negative value means west of Greenwich.  The
-second element, @var{name} is a string giving the name of the time
+second element, @var{name}, is a string giving the name of the time
 zone.  Both elements change when daylight savings time begins or ends;
 if the user has specified a time zone that does not use a seasonal time
 adjustment, then the value is constant through time.
@@ -998,7 +1010,7 @@ This is a synonym for @samp{%b}.
 @item %H
 This stands for the hour (00-23).
 @item %I
-This stands for the hour (00-12).
+This stands for the hour (01-12).
 @item %j
 This stands for the day of the year (001-366).
 @item %k
@@ -1018,7 +1030,7 @@ This is a synonym for @samp{%I:%M:%S %p}.
 @item %R
 This is a synonym for @samp{%H:%M}.
 @item %S
-This stands for the seconds (00-60).
+This stands for the seconds (00-59).
 @item %t
 This stands for a tab character.
 @item %T
@@ -1068,9 +1080,9 @@ return value is a list of nine elements, as follows:
 Here is what the elements mean:
 
 @table @var
-@item sec
+@item seconds
 The number of seconds past the minute, as an integer between 0 and 59.
-@item minute
+@item minutes
 The number of minutes past the hour, as an integer between 0 and 59.
 @item hour
 The hour of the day, as an integer between 0 and 23.
@@ -1099,9 +1111,9 @@ This function is the inverse of @code{decode-time}.  It converts seven
 items of calendrical data into a time value.  For the meanings of the
 arguments, see the table above under @code{decode-time}.
 
-Year numbers less than 100 are treated just like other year numbers.  If
-you want them to stand for years above 1900, you must alter them yourself
-before you call @code{encode-time}.
+Year numbers less than 100 are not treated specially.  If you want them
+to stand for years above 1900, you must alter them yourself before you
+call @code{encode-time}.
 
 The optional argument @var{zone} defaults to the current time zone and
 its daylight savings time rules.  If specified, it can be either a list
@@ -1121,7 +1133,7 @@ feature makes it possible to use the elements of a list returned by
 @end example
 
 You can perform simple date arithmetic by using out-of-range values for
-the @var{sec}, @var{minute}, @var{hour}, @var{day}, and @var{month}
+the @var{seconds}, @var{minutes}, @var{hour}, @var{day}, and @var{month}
 arguments; for example, day 0 means the day preceding the given month.
 
 The operating system puts limits on the range of possible time values;
@@ -1175,6 +1187,9 @@ denotes 65 seconds from now.
 denotes exactly 103 months, 123 days, and 10862 seconds from now.
 @end table
 
+For relative time values, Emacs considers a month to be exactly thirty
+days, and a year to be exactly 365.25 days.
+
 If @var{time} is a number (integer or floating point), that specifies a
 relative time measured in seconds.
 
@@ -1236,10 +1251,10 @@ can use in calling @code{cancel-timer} (see below).
   Emacs becomes ``idle'' when it starts waiting for user input, and it
 remains idle until the user provides some input.  If a timer is set for
 five seconds of idleness, it runs approximately five seconds after Emacs
-first became idle.  Even if its @var{repeat} is true, this timer will
-not run again as long as Emacs remains idle, because the duration of
-idleness will continue to increase and will not go down to five seconds
-again.
+first becomes idle.  Even if @var{repeat} is non-@code{nil}, this timer
+will not run again as long as Emacs remains idle, because the duration
+of 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 do
@@ -1247,7 +1262,7 @@ 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.
+minutes, and 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
@@ -1284,7 +1299,7 @@ functions.
 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.  The default setting is
-system dependent.  Some systems always use @sc{cbreak} mode regardless
+system-dependent.  Some systems always use @sc{cbreak} mode regardless
 of what is specified.
 
 When Emacs communicates directly with X, it ignores this argument and
@@ -1314,7 +1329,7 @@ Emacs is currently using.
 
 @c Emacs 19 feature
 @defun current-input-mode
-This function returns current mode for reading keyboard input.  It
+This function returns the current mode for reading keyboard input.  It
 returns a list, corresponding to the arguments of @code{set-input-mode},
 of the form @code{(@var{interrupt} @var{flow} @var{meta} @var{quit})} in
 which:
@@ -1379,10 +1394,10 @@ This variable is the translate table for keyboard characters.  It lets
 you reshuffle the keys on the keyboard without changing any command
 bindings.  Its value is normally a char-table, or else @code{nil}.
 
-If @code{keyboard-translate-table} is a char-table, then each character
-read from the keyboard is looked up in this character.  If the value
-found there is non-@code{nil}, then it is used instead of the
-actual input character.
+If @code{keyboard-translate-table} is a char-table
+(@pxref{Char-Tables}), then each character read from the keyboard is
+looked up in this char-table.  If the value found there is
+non-@code{nil}, then it is used instead of the actual input character.
 
 In the example below, we set @code{keyboard-translate-table} to a
 char-table.  Then we fill it in to swap the characters @kbd{C-s} and
@@ -1573,7 +1588,7 @@ trigger an Emacs bug, for the sake of a bug report.
 @section Terminal Output
 @cindex terminal output
 
-  The terminal output functions send output to the terminal or keep
+  The terminal output functions send output to the terminal, or keep
 track of output sent to the terminal.  The variable @code{baud-rate}
 tells you what Emacs thinks is the output speed of the terminal.
 
@@ -1607,8 +1622,8 @@ This function sends @var{string} to the terminal without alteration.
 Control characters in @var{string} have terminal-dependent effects.
 
 One use of this function is to define function keys on terminals that
-have downloadable function key definitions.  For example, this is how on
-certain terminals to define function key 4 to move forward four
+have downloadable function key definitions.  For example, this is how (on
+certain terminals) to define function key 4 to move forward four
 characters (by transmitting the characters @kbd{C-u C-f} to the
 computer):
 
@@ -1641,6 +1656,51 @@ See also @code{open-dribble-file} in @ref{Terminal Input}.
 @end example
 @end deffn
 
+@node Sound Output
+@section Sound Output
+@cindex sound
+
+  To play sound using Emacs, use the function @code{play-sound}.  Only
+certain systems are supported; if you call @code{play-sound} on a system
+which cannot really do the job, it gives an error.  Emacs version 20 and
+earlier did not support sound at all.
+
+  The sound must be stored as a file in RIFF-WAVE format (@samp{.wav})
+or Sun Audio format (@samp{.au}).
+
+@tindex play-sound
+@defun play-sound sound
+This function plays a specified sound.  The argument, @var{sound}, has
+the form @code{(sound @var{properties}...)}, where the @var{properties}
+consist of alternating keywords (particular symbols recognized
+specially) and values corresponding to them.
+
+Here is a table of the keywords that are currently meaningful in
+@var{sound}, and their meanings:
+
+@table @code
+@item :file @var{file}
+This specifies the file containing the sound to play.
+If the file name is not absolute, it is expanded against
+the directory @code{data-directory}.
+
+@item :volume @var{volume}
+This specifies how loud to play the sound.  It should be a number in the
+range of 0 to 1.  The default is to use whatever volume has been
+specified before.
+@end table
+
+Before actually playing the sound, @code{play-sound}
+calls the functions in the list @code{play-sound-functions}.
+Each function is called with one argument, @var{sound}.
+@end defun
+
+@tindex play-sound-functions
+@defvar play-sound-functions
+A list of functions to be called before playing a sound.  Each function
+is called with one argument, a property list that describes the sound.
+@end defvar
+
 @node Special Keysyms
 @section System-Specific X11 Keysyms
 
@@ -1649,7 +1709,7 @@ To define system-specific X11 keysyms, set the variable
 
 @defvar system-key-alist
 This variable's value should be an alist with one element for each
-system-specific keysym.  An element has this form: @code{(@var{code}
+system-specific keysym.  Each element has the form @code{(@var{code}
 . @var{symbol})}, where @var{code} is the numeric keysym code (not
 including the ``vendor specific'' bit, 
 @ifinfo 
@@ -1660,8 +1720,8 @@ $-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
+For example @code{(168 . mute-acute)} defines a system-specific key (used
+by HP X servers) whose numeric code is
 @ifinfo 
 -2**28
 @end ifinfo
@@ -1694,7 +1754,7 @@ entries and DEC terminal concentrators, see @file{emacs/etc/TERMS}.
 @code{C-s} and @kbd{C-q} for flow control.  Therefore, the choice of
 @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}
+assignments, of course we assigned meanings to nearly all @sc{ascii}
 control characters.
 
   Later, some terminals were introduced which required these characters
@@ -1769,7 +1829,7 @@ speed when calculating the padding needed.  @xref{Terminal Output}.
 @cindex batch mode
 @cindex noninteractive use
 
-  The command line option @samp{-batch} causes Emacs to run
+  The command-line option @samp{-batch} causes Emacs to run
 noninteractively.  In this mode, Emacs does not read commands from the
 terminal, it does not alter the terminal modes, and it does not expect
 to be outputting to an erasable screen.  The idea is that you specify
@@ -1779,7 +1839,7 @@ loads the library named @var{file}, and @samp{-f @var{function}}, which
 calls @var{function} with no arguments.
 
   Any Lisp program output that would normally go to the echo area,
-either using @code{message} or using @code{prin1}, etc., with @code{t}
+either using @code{message}, or using @code{prin1}, etc., with @code{t}
 as the stream, goes instead to Emacs's standard error descriptor when
 in batch mode.  Thus, Emacs behaves much like a noninteractive
 application program.  (The echo area output that Emacs itself normally
diff --git a/lispref/positions.texi b/lispref/positions.texi
index 43be1bad65e..49c42bc1d3c 100644
--- a/lispref/positions.texi
+++ b/lispref/positions.texi
@@ -42,10 +42,10 @@ the character that immediately follows point; point is actually before
 the character on which the cursor sits.
 
 @cindex point with narrowing
-  The value of point is a number between 1 and the buffer size plus 1.
-If narrowing is in effect (@pxref{Narrowing}), then point is constrained
-to fall within the accessible portion of the buffer (possibly at one end
-of it).
+  The value of point is a number no less than 1, and no greater than the
+buffer size plus 1.  If narrowing is in effect (@pxref{Narrowing}), then
+point is constrained to fall within the accessible portion of the buffer
+(possibly at one end of it).
 
   Each buffer has its own value of point, which is independent of the
 value of point in other buffers.  Each window also has a value of point,
@@ -81,7 +81,7 @@ is the position of the start of the region that you narrowed to.
 This function returns the maximum accessible value of point in the
 current buffer.  This is @code{(1+ (buffer-size))}, unless narrowing is
 in effect, in which case it is the position of the end of the region
-that you narrowed to.  (@pxref{Narrowing}).
+that you narrowed to.  (@xref{Narrowing}.)
 @end defun
 
 @defun buffer-end flag
@@ -89,11 +89,14 @@ This function returns @code{(point-min)} if @var{flag} is less than 1,
 @code{(point-max)} otherwise.  The argument @var{flag} must be a number.
 @end defun
 
-@defun buffer-size
+@defun buffer-size &optional buffer
 This function returns the total number of characters in the current
 buffer.  In the absence of any narrowing (@pxref{Narrowing}),
 @code{point-max} returns a value one larger than this.
 
+If you specify a buffer, @var{buffer}, then the value is the
+size of @var{buffer}.
+
 @example
 @group
 (buffer-size)
@@ -190,6 +193,9 @@ the buffer boundary (except perhaps after the last word), the value is
 @code{t}.  Otherwise, the return value is @code{nil} and point stops
 at the buffer boundary.
 
+In the minibuffer, the end of the prompt always acts as a word boundary,
+regardless of what characters appear before and after it.
+
 In an interactive call, @var{count} is set to the numeric prefix
 argument.
 @end deffn
@@ -241,7 +247,8 @@ they set the mark and display messages in the echo area.
 This function moves point to the beginning of the buffer (or the limits
 of the accessible portion, when narrowing is in effect), setting the
 mark at the previous position.  If @var{n} is non-@code{nil}, then it
-puts point @var{n} tenths of the way from the beginning of the buffer.
+puts point @var{n} tenths of the way from the beginning of the
+accessible portion of the buffer.
 
 In an interactive call, @var{n} is the numeric prefix argument,
 if provided; otherwise @var{n} defaults to @code{nil}.
@@ -250,10 +257,11 @@ if provided; otherwise @var{n} defaults to @code{nil}.
 @end deffn
 
 @deffn Command end-of-buffer &optional n
-This function moves point to the end of the buffer (or the limits of
-the accessible portion, when narrowing is in effect), setting the mark
-at the previous position.  If @var{n} is non-@code{nil}, then it puts
-point @var{n} tenths of the way from the end of the buffer.
+This function moves point to the end of the buffer (or the limits of the
+accessible portion, when narrowing is in effect), setting the mark at
+the previous position.  If @var{n} is non-@code{nil}, then it puts point
+@var{n} tenths of the way from the end of the accessible portion of the
+buffer.
 
 In an interactive call, @var{n} is the numeric prefix argument,
 if provided; otherwise @var{n} defaults to @code{nil}.
@@ -308,6 +316,9 @@ argument @var{count} not @code{nil} or 1, it moves forward
 If this function reaches the end of the buffer (or of the accessible
 portion, if narrowing is in effect), it positions point there.  No error
 is signaled.
+
+As a special feature, in the minibuffer, this command will not
+move back into the prompt, if it starts from after the prompt.
 @end deffn
 
 @defun line-beginning-position &optional count
@@ -584,7 +595,7 @@ expressions (also called @dfn{sexps} in connection with moving across
 them in Emacs).  The syntax table controls how these functions interpret
 various characters; see @ref{Syntax Tables}.  @xref{Parsing
 Expressions}, for lower-level primitives for scanning sexps or parts of
-sexps.  For user-level commands, see @ref{Lists Commands,,, emacs, GNU
+sexps.  For user-level commands, see @ref{Lists Commands,,, emacs, The GNU
 Emacs Manual}.
 
 @deffn Command forward-list arg
@@ -725,9 +736,9 @@ is zero or less.
   It is often useful to move point ``temporarily'' within a localized
 portion of the program, or to switch buffers temporarily.  This is
 called an @dfn{excursion}, and it is done with the @code{save-excursion}
-special form.  This construct saves the current buffer and its values of
-point and the mark so they can be restored after the completion of the
-excursion.
+special form.  This construct initially remembers the identity of the
+current buffer, and its values of point and the mark, and restores them
+after the completion of the excursion.
 
   The forms for saving and restoring the configuration of windows are
 described elsewhere (see @ref{Window Configurations}, and @pxref{Frame
diff --git a/lispref/processes.texi b/lispref/processes.texi
index 908ed240bc5..16aa65a3ffd 100644
--- a/lispref/processes.texi
+++ b/lispref/processes.texi
@@ -58,7 +58,7 @@ The other two, @code{call-process} and @code{call-process-region},
 create a synchronous process and do not return a process object
 (@pxref{Synchronous Processes}).
 
-  Synchronous and asynchronous processes are explained in following
+  Synchronous and asynchronous processes are explained in the following
 sections.  Since the three functions are all called in a similar
 fashion, their common arguments are described here.
 
@@ -108,7 +108,7 @@ Environment}.
 
 @defvar exec-directory 
 @pindex movemail
-The value of this variable is the name of a directory (a string) that
+The value of this variable is a string, the name of a directory that
 contains programs that come with GNU Emacs, programs intended for Emacs
 to invoke.  The program @code{movemail} is an example of such a program;
 Rmail uses it to fetch new mail from an inbox.
@@ -130,7 +130,7 @@ file name.
 @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
+that 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
@@ -143,16 +143,18 @@ 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.
+function is designed to work with the syntax of your system's standard
+shell; if you use an unusual shell, you will need to redefine this
+function.
 
 @example
 ;; @r{This example shows the behavior on GNU and Unix systems.}
 (shell-quote-argument "foo > bar")
      @result{} "foo\\ \\>\\ bar"
+
+;; @r{This example shows the behavior on MS-DOS and MS-Windows systems.}
+(shell-quote-argument "foo > bar")
+     @result{} "\"foo > bar\""
 @end example
 
 Here's an example of using @code{shell-quote-argument} to construct
@@ -171,18 +173,20 @@ a shell command:
 @cindex synchronous subprocess
 
   After a @dfn{synchronous process} is created, Emacs waits for the
-process to terminate before continuing.  Starting Dired is an example of
-this: it runs @code{ls} in a synchronous process, then modifies the
-output slightly.  Because the process is synchronous, the entire
-directory listing arrives in the buffer before Emacs tries to do
-anything with it.
+process to terminate before continuing.  Starting Dired on GNU or
+Unix@footnote{On other systems, Emacs uses a Lisp emulation of
+@code{ls}; see @ref{Contents of Directories}.} is an example of this: it
+runs @code{ls} in a synchronous process, then modifies the output
+slightly.  Because the process is synchronous, the entire directory
+listing arrives in the buffer before Emacs tries to do anything with it.
 
   While Emacs waits for the synchronous subprocess to terminate, the
 user can quit by typing @kbd{C-g}.  The first @kbd{C-g} tries to kill
 the subprocess with a @code{SIGINT} signal; but it waits until the
 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}.
+@code{SIGKILL} and quits immediately (except on MS-DOS, where killing
+other processes doesn't work).  @xref{Quitting}.
 
   The synchronous subprocess functions return an indication of how the
 process terminated.
@@ -197,7 +201,7 @@ This function calls @var{program} in a separate process and waits for
 it to finish.
 
 The standard input for the process comes from file @var{infile} if
-@var{infile} is not @code{nil}, and from @file{/dev/null} otherwise.
+@var{infile} is not @code{nil}, and from the null device otherwise.
 The argument @var{destination} says where to put the process output.
 Here are the possibilities:
 
@@ -216,7 +220,7 @@ Insert the output in the current buffer, before point.
 Discard the output.
 
 @item 0
-Discard the output, and return immediately without waiting
+Discard the output, and return @code{nil} immediately without waiting
 for the subprocess to finish.
 
 In this case, the process is not truly synchronous, since it can run in
@@ -224,6 +228,9 @@ parallel with Emacs; but you can think of it as synchronous in that
 Emacs is essentially finished with the subprocess as soon as this
 function returns.
 
+MS-DOS doesn't support asynchronous subprocesses, so this option doesn't
+work there.
+
 @item @code{(@var{real-destination} @var{error-destination})}
 Keep the standard output stream separate from the standard error stream;
 deal with the ordinary output as specified by @var{real-destination},
@@ -242,11 +249,12 @@ If @var{display} is non-@code{nil}, then @code{call-process} redisplays
 the buffer as output is inserted.  (However, if the coding system chosen
 for decoding output is @code{undecided}, meaning deduce the encoding
 from the actual data, then redisplay sometimes cannot continue once
-non-@sc{ASCII} characters are encountered.  There are fundamental
-reasons why it is hard to fix this.)  Otherwise the function
-@code{call-process} does no redisplay, and the results become visible on
-the screen only when Emacs redisplays that buffer in the normal course
-of events.
+non-@sc{ascii} characters are encountered.  There are fundamental
+reasons why it is hard to fix this; see @ref{Output from Processes}.)
+
+Otherwise the function @code{call-process} does no redisplay, and the
+results become visible on the screen only when Emacs redisplays that
+buffer in the normal course of events.
 
 The remaining arguments, @var{args}, are strings that specify command
 line arguments for the program.
@@ -262,7 +270,7 @@ In the examples below, the buffer @samp{foo} is current.
 @smallexample
 @group
 (call-process "pwd" nil t)
-     @result{} nil
+     @result{} 0
 
 ---------- Buffer: foo ----------
 /usr/user/lewis/manual
@@ -271,7 +279,7 @@ In the examples below, the buffer @samp{foo} is current.
 
 @group
 (call-process "grep" nil "bar" nil "lewis" "/etc/passwd")
-     @result{} nil
+     @result{} 0
 
 ---------- Buffer: bar ----------
 lewis:5LTsHm66CSWKg:398:21:Bil Lewis:/user/lewis:/bin/csh
@@ -294,7 +302,7 @@ be found in the definition of @code{insert-directory}:
 @end defun
 
 @defun call-process-region start end program &optional delete destination display &rest args
-This function sends the text between @var{start} to @var{end} as
+This function sends the text from @var{start} to @var{end} as
 standard input to a process running @var{program}.  It deletes the text
 sent if @var{delete} is non-@code{nil}; this is useful when
 @var{destination} is @code{t}, to insert the output in the current
@@ -305,7 +313,8 @@ with the output from the subprocess, and whether to update the display
 as it comes in.  For details, see the description of
 @code{call-process}, above.  If @var{destination} is the integer 0,
 @code{call-process-region} discards the output and returns @code{nil}
-immediately, without waiting for the subprocess to finish.
+immediately, without waiting for the subprocess to finish (this only
+works if asynchronous subprocess are supported).
 
 The remaining arguments, @var{args}, are strings that specify command
 line arguments for the program.
@@ -331,7 +340,7 @@ input@point{}
 
 @group
 (call-process-region 1 6 "cat" nil t)
-     @result{} nil
+     @result{} 0
 
 ---------- Buffer: foo ----------
 inputinput@point{}
@@ -368,7 +377,7 @@ then returns the command's output as a string.
   After an @dfn{asynchronous process} is created, Emacs and the subprocess
 both continue running immediately.  The process thereafter runs
 in parallel with Emacs, and the two can communicate with each other
-using the functions described in following sections.  However,
+using the functions described in the following sections.  However,
 communication is only partially asynchronous: Emacs sends data to the
 process only when certain functions are called, and Emacs accepts data
 from the process only when Emacs is waiting for input or for a time
@@ -429,10 +438,10 @@ 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
+arbitrary user-specified arguments 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}.
+characters do @emph{not} have their special shell meanings.  @xref{Shell
+Arguments}.
 @end defun
 
 @defvar process-connection-type
@@ -450,7 +459,7 @@ often better to use a pipe, because they are more efficient.  In
 addition, the total number of @sc{pty}s is limited on many systems and
 it is good not to waste them.
 
-The value @code{process-connection-type} is used when
+The value of @code{process-connection-type} is used when
 @code{start-process} is called.  So you can specify how to communicate
 with one subprocess by binding the variable around the call to
 @code{start-process}.
@@ -727,7 +736,7 @@ introduction.txt                text.texi~
 @end smallexample
 @end defun
 
-@deffn Command process-send-region process-name start end
+@defun process-send-region process-name start end
 This function sends the text in the region defined by @var{start} and
 @var{end} as standard input to @var{process-name}, which is a process or
 a process name.  (If it is @code{nil}, the current buffer's process is
@@ -736,7 +745,7 @@ used.)
 An error is signaled unless both @var{start} and @var{end} are
 integers or markers that indicate positions in the current buffer.  (It
 is unimportant which number is larger.)
-@end deffn
+@end defun
 
 @defun process-send-eof &optional process-name
   This function makes @var{process-name} see an end-of-file in its
diff --git a/lispref/searching.texi b/lispref/searching.texi
index 0f465edc011..68593e4bbef 100644
--- a/lispref/searching.texi
+++ b/lispref/searching.texi
@@ -34,9 +34,9 @@ portions of it.
 
   These are the primitive functions for searching through the text in a
 buffer.  They are meant for use in programs, but you may call them
-interactively.  If you do so, they prompt for the search string;
-@var{limit} and @var{noerror} are set to @code{nil}, and @var{repeat}
-is set to 1.
+interactively.  If you do so, they prompt for the search string; the
+arguments @var{limit} and @var{noerror} are @code{nil}, and @var{repeat}
+is 1.
 
   These search functions convert the search string to multibyte if the
 buffer is multibyte; they convert the search string to unibyte if the
@@ -167,6 +167,7 @@ regexps; the following section says how to search for them.
 
 @menu
 * Syntax of Regexps::       Rules for writing regular expressions.
+* Regexp Functions::        Functions for operating on regular expressions.
 * Regexp Example::          Illustrates regular expression syntax.
 @end menu
 
@@ -182,21 +183,33 @@ special characters will be defined in the future.  Any other character
 appearing in a regular expression is ordinary, unless a @samp{\}
 precedes it.
 
-For example, @samp{f} is not a special character, so it is ordinary, and
+  For example, @samp{f} is not a special character, so it is ordinary, and
 therefore @samp{f} is a regular expression that matches the string
 @samp{f} and no other string.  (It does @emph{not} match the string
-@samp{ff}.)  Likewise, @samp{o} is a regular expression that matches
-only @samp{o}.@refill
+@samp{fg}, but it does match a @emph{part} of that string.)  Likewise,
+@samp{o} is a regular expression that matches only @samp{o}.@refill
 
-Any two regular expressions @var{a} and @var{b} can be concatenated.  The
+  Any two regular expressions @var{a} and @var{b} can be concatenated.  The
 result is a regular expression that matches a string if @var{a} matches
 some amount of the beginning of that string and @var{b} matches the rest of
 the string.@refill
 
-As a simple example, we can concatenate the regular expressions @samp{f}
+  As a simple example, we can concatenate the regular expressions @samp{f}
 and @samp{o} to get the regular expression @samp{fo}, which matches only
 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 to use one of the special regular expression constructs.
+
+@menu
+* Regexp Special::      Special characters in regular expressions.
+* Char Classes::        Character classes used in regular expressions.
+* Regexp Backslash::    Backslash-sequences in regular expressions.
+@end menu
+
+@node Regexp Special
+@subsubsection Special Characters in Regular Expressions
+
+  Here is a list of the characters that are special in a regular
+expression.
 
 @need 800
 @table @asis
@@ -266,23 +279,10 @@ matches @samp{cr}, @samp{car}, @samp{cdr}, @samp{caddaar}, etc.
 
 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 @sc{ASCII} letter.  Ranges may be
+Thus, @samp{[a-z]} matches any lower-case @sc{ascii} letter.  Ranges may be
 intermixed freely with individual characters, as in @samp{[a-z$%.]},
-which matches any lower case @sc{ASCII} letter or @samp{$}, @samp{%} or
+which matches any lower case @sc{ascii} letter or @samp{$}, @samp{%} or
 period.
- 
-You cannot always match all non-@sc{ASCII} characters with the regular
-expression @samp{[\200-\377]}.  This works when searching a unibyte
-buffer or string (@pxref{Text Representations}), but not in a multibyte
-buffer or string, because many non-@sc{ASCII} characters have codes
-above octal 0377.  However, the regular expression @samp{[^\000-\177]}
-does match all non-@sc{ASCII} characters, in both multibyte and unibyte
-representations, because only the @sc{ASCII} characters are excluded.
-
-The beginning and end of a range must be in the same character set
-(@pxref{Character Sets}).  Thus, @samp{[a-\x8e0]} is invalid because
-@samp{a} is in the @sc{ASCII} character set but the character 0x8e0
-(@samp{a} with grave accent) is in the Emacs character set for Latin-1.
 
 Note that the usual regexp special characters are not special inside a
 character alternative.  A completely different set of characters is
@@ -297,6 +297,27 @@ matches both @samp{]} and @samp{-}.
 To include @samp{^} in a character alternative, put it anywhere but at
 the beginning.
 
+The beginning and end of a range must be in the same character set
+(@pxref{Character Sets}).  Thus, @samp{[a-\x8e0]} is invalid because
+@samp{a} is in the @sc{ascii} character set but the character 0x8e0
+(@samp{a} with grave accent) is in the Emacs character set for Latin-1.
+ 
+You cannot always match all non-@sc{ascii} characters with the regular
+expression @samp{[\200-\377]}.  This works when searching a unibyte
+buffer or string (@pxref{Text Representations}), but not in a multibyte
+buffer or string, because many non-@sc{ascii} characters have codes
+above octal 0377.  However, the regular expression @samp{[^\000-\177]}
+does match all non-@sc{ascii} characters (see below regarding @samp{^}),
+in both multibyte and unibyte representations, because only the
+@sc{ascii} characters are excluded.
+
+Starting in Emacs 21, a character alternative can also specify named
+character classes (@pxref{Char Classes}).  This is a POSIX feature whose
+syntax is @samp{[:@var{class}:]}.  Using a character class is equivalent
+to mentioning each of the characters in that class; but the latter is
+not feasible in practice, since some classes include thousands of
+different characters.
+
 @item @samp{[^ @dots{} ]}
 @cindex @samp{^} in regexp
 @samp{[^} begins a @dfn{complemented character alternative}, which matches any
@@ -321,14 +342,21 @@ 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}.
 
+For historical compatibility reasons, @samp{^} can be used only at the
+beginning of the regular expression, or after @samp{\(} or @samp{\|}.
+
 @item @samp{$}
 @cindex @samp{$} in regexp
+@cindex end of line 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.
 
 When matching a string instead of a buffer, @samp{$} matches at the end
 of the string or before a newline character @samp{\n}.
 
+For historical compatibility reasons, @samp{$} can be used only at the
+end of the regular expression, or before @samp{\)} or @samp{\|}.
+
 @item @samp{\}
 @cindex @samp{\} in regexp
 has two functions: it quotes the special characters (including
@@ -354,11 +382,66 @@ ordinary since there is no preceding expression on which the @samp{*}
 can act.  It is poor practice to depend on this behavior; quote the
 special character anyway, regardless of where it appears.@refill
 
-For the most part, @samp{\} followed by any character matches only that
-character.  However, there are several exceptions: two-character
-sequences starting with @samp{\} which have special meanings.  (The
-second character in such a sequence is always ordinary when used on its
-own.)  Here is a table of @samp{\} constructs.
+@node Char Classes
+@subsubsection Character Classes
+@cindex character classes in regexp
+
+  Here is a table of the classes you can use in a character alternative,
+in Emacs 21, and what they mean:
+
+@table @samp
+@item [:ascii:]
+This matches any ASCII (unibyte) character.
+@item [:alnum:]
+This matches any letter or digit.  (At present, for multibyte
+characters, it matches anything that has word syntax.)
+@item [:alpha:]
+This matches any letter.  (At present, for multibyte characters, it
+matches anything that has word syntax.)
+@item [:blank:]
+This matches space and tab only.
+@item [:cntrl:]
+This matches any ASCII control character.
+@item [:digit:]
+This matches @samp{0} through @samp{9}.  Thus, @samp{[-+[:digit:]]}
+matches any digit, as well as @samp{+} and @samp{-}.
+@item [:graph:]
+This matches graphic characters---everything except ASCII control characters,
+space, and DEL.
+@item [:lower:]
+This matches any lower-case letter, as determined by
+the current case table (@pxref{Case Tables}).
+@item [:nonascii:]
+This matches any non-ASCII (multibyte) character.
+@item [:print:]
+This matches printing characters---everything except ASCII control
+characters and DEL.
+@item [:punct:]
+This matches any punctuation character.  (At present, for multibyte
+characters, it matches anything that has non-word syntax.)
+@item [:space:]
+This matches any character that has whitespace syntax
+(@pxref{Syntax Class Table}).
+@item [:upper:]
+This matches any upper-case letter, as determined by
+the current case table (@pxref{Case Tables}).
+@item [:word:]
+This matches any character that has word syntax (@pxref{Syntax Class
+Table}).
+@item [:xdigit:]
+This matches the hexadecimal digits: @samp{0} through @samp{9}, @samp{a}
+through @samp{f} and @samp{A} through @samp{F}.
+@end table
+
+@node Regexp Backslash
+@subsubsection Backslash Constructs in Regular Expressions
+
+  For the most part, @samp{\} followed by any character matches only
+that character.  However, there are several exceptions: certain
+two-character sequences starting with @samp{\} that have special
+meanings.  (The character after the @samp{\} in such a sequence is
+always ordinary when used on its own.)  Here is a table of the special
+@samp{\} constructs.
 
 @table @samp
 @item \|
@@ -376,7 +459,9 @@ but no other string.@refill
 surrounding @samp{\( @dots{} \)} grouping can limit the grouping power of
 @samp{\|}.@refill
 
-Full backtracking capability exists to handle multiple uses of @samp{\|}.
+Full backtracking capability exists to handle multiple uses of
+@samp{\|}, if you use the POSIX regular expression functions
+(@pxref{POSIX Regexps}).
 
 @item \( @dots{} \)
 @cindex @samp{(} in regexp
@@ -505,62 +590,6 @@ as @samp{[]]}), and so is a string that ends with a single @samp{\}.  If
 an invalid regular expression is passed to any of the search functions,
 an @code{invalid-regexp} error is signaled.
 
-@defun regexp-quote string
-This function returns a regular expression string that matches exactly
-@var{string} and nothing else.  This allows you to request an exact
-string match when calling a function that wants a regular expression.
-
-@example
-@group
-(regexp-quote "^The cat$")
-     @result{} "\\^The cat\\$"
-@end group
-@end example
-
-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 @var{string}, surrounded by
-whitespace:
-
-@example
-@group
-(re-search-forward
- (concat "\\s-" (regexp-quote string) "\\s-"))
-@end group
-@end example
-@end defun
-
-@defun regexp-opt strings &optional paren
-@tindex regexp-opt
-This function returns an efficient regular expression that will match
-any of the strings @var{strings}.  This is useful when you need to make
-matching or searching as fast as possible---for example, for Font Lock
-mode.
-
-If the optional argument @var{paren} is non-@code{nil}, then the
-returned regular expression is always enclosed by at least one
-parentheses-grouping construct.
-
-This simplified definition of @code{regexp-opt} produces a
-regular expression which is equivalent to the actual value
-(but not as efficient):
-
-@example
-(defun regexp-opt (strings paren)
-  (let ((open-paren (if paren "\\(" ""))
-        (close-paren (if paren "\\)" "")))
-    (concat open-paren
-            (mapconcat 'regexp-quote strings "\\|")
-            close-paren)))
-@end example
-@end defun
-
-@defun regexp-opt-depth regexp
-@tindex regexp-opt-depth
-This function returns the total number of grouping constructs
-(parenthesized expressions) in @var{regexp}.
-@end defun
-
 @node Regexp Example
 @comment  node-name,  next,  previous,  up
 @subsection Complex Regexp Example
@@ -624,6 +653,72 @@ Finally, the last part of the pattern matches any additional whitespace
 beyond the minimum needed to end a sentence.
 @end table
 
+@node Regexp Functions
+@subsection Regular Expression Functions
+
+  These functions operate on regular expressions.
+
+@defun regexp-quote string
+This function returns a regular expression whose only exact match is
+@var{string}.  Using this regular expression in @code{looking-at} will
+succeed only if the next characters in the buffer are @var{string};
+using it in a search function will succeed if the text being searched
+contains @var{string}.
+
+This allows you to request an exact string match or search when calling
+a function that wants a regular expression.
+
+@example
+@group
+(regexp-quote "^The cat$")
+     @result{} "\\^The cat\\$"
+@end group
+@end example
+
+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 @var{string}, surrounded by
+whitespace:
+
+@example
+@group
+(re-search-forward
+ (concat "\\s-" (regexp-quote string) "\\s-"))
+@end group
+@end example
+@end defun
+
+@defun regexp-opt strings &optional paren
+@tindex regexp-opt
+This function returns an efficient regular expression that will match
+any of the strings @var{strings}.  This is useful when you need to make
+matching or searching as fast as possible---for example, for Font Lock
+mode.
+
+If the optional argument @var{paren} is non-@code{nil}, then the
+returned regular expression is always enclosed by at least one
+parentheses-grouping construct.
+
+This simplified definition of @code{regexp-opt} produces a
+regular expression which is equivalent to the actual value
+(but not as efficient):
+
+@example
+(defun regexp-opt (strings paren)
+  (let ((open-paren (if paren "\\(" ""))
+        (close-paren (if paren "\\)" "")))
+    (concat open-paren
+            (mapconcat 'regexp-quote strings "\\|")
+            close-paren)))
+@end example
+@end defun
+
+@defun regexp-opt-depth regexp
+@tindex regexp-opt-depth
+This function returns the total number of grouping constructs
+(parenthesized expressions) in @var{regexp}.
+@end defun
+
 @node Regexp Search
 @section Regular Expression Searching
 @cindex regular expression searching
@@ -908,10 +1003,19 @@ The argument @var{replacements} specifies what to replace occurrences
 with.  If it is a string, that string is used.  It can also be a list of
 strings, to be used in cyclic order.
 
+If @var{replacements} is a cons cell, @var{(@var{function}
+. @var{data})}, this means to call @var{function} after each match to
+get the replacement text.  This function is called with two arguments:
+@var{data}, and the number of replacements already made.
+
 If @var{repeat-count} is non-@code{nil}, it should be an integer.  Then
 it specifies how many times to use each of the strings in the
 @var{replacements} list before advancing cyclicly to the next one.
 
+If @var{from-string} contains upper-case letters, then
+@code{perform-replace} binds @code{case-fold-search} to @code{nil}, and
+it uses the @code{replacements} without altering the case of them.
+
 Normally, the keymap @code{query-replace-map} defines the possible user
 responses for queries.  The argument @var{map}, if non-@code{nil}, is a
 keymap to use instead of @code{query-replace-map}.
@@ -1009,7 +1113,7 @@ match data around it, to prevent it from being overwritten.
 @end menu
 
 @node Replacing Match
-@subsection Replacing the Text That Matched
+@subsection Replacing the Text that Matched
 
   This function replaces the text matched by the last search with
 @var{replacement}.
@@ -1039,9 +1143,6 @@ 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
@@ -1361,8 +1462,8 @@ preserve case.  If the variable is @code{nil}, that means to use the
 replacement text verbatim.  A non-@code{nil} value means to convert the
 case of the replacement text according to the text being replaced.
 
-The function @code{replace-match} is where this variable actually has
-its effect.  @xref{Replacing Match}.
+This variable is used by passing it as an argument to the function
+@code{replace-match}.  @xref{Replacing Match}.
 @end defopt
 
 @defopt case-fold-search
diff --git a/lispref/sequences.texi b/lispref/sequences.texi
index f812112e243..006b863e7ed 100644
--- a/lispref/sequences.texi
+++ b/lispref/sequences.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/sequences
-@node Sequences Arrays Vectors, Symbols, Lists, Top
+@node Sequences Arrays Vectors, Hash Tables, Lists, Top
 @chapter Sequences, Arrays, and Vectors
 @cindex sequence
 
@@ -312,7 +312,7 @@ first element is at index zero.
 @end group
 @group
 (aref "abcdefg" 1)
-     @result{} 98           ; @r{@samp{b} is @sc{ASCII} code 98.}
+     @result{} 98           ; @r{@samp{b} is @sc{ascii} code 98.}
 @end group
 @end example
 
diff --git a/lispref/streams.texi b/lispref/streams.texi
index 2209a40baf9..90089b10bf7 100644
--- a/lispref/streams.texi
+++ b/lispref/streams.texi
@@ -716,25 +716,25 @@ In the second expression, the local binding of
 
 @tindex print-escape-nonascii
 @defvar print-escape-nonascii
-If this variable is non-@code{nil}, then unibyte non-@sc{ASCII}
+If this variable is non-@code{nil}, then unibyte non-@sc{ascii}
 characters in strings are unconditionally printed as backslash sequences
 by the print functions @code{prin1} and @code{print} that print with
 quoting.
 
-Those functions also use backslash sequences for unibyte non-@sc{ASCII}
+Those functions also use backslash sequences for unibyte non-@sc{ascii}
 characters, regardless of the value of this variable, when the output
 stream is a multibyte buffer or a marker pointing into one.
 @end defvar
 
 @tindex print-escape-multibyte
 @defvar print-escape-multibyte
-If this variable is non-@code{nil}, then multibyte non-@sc{ASCII}
+If this variable is non-@code{nil}, then multibyte non-@sc{ascii}
 characters in strings are unconditionally printed as backslash sequences
 by the print functions @code{prin1} and @code{print} that print with
 quoting.
 
 Those functions also use backslash sequences for multibyte
-non-@sc{ASCII} characters, regardless of the value of this variable,
+non-@sc{ascii} characters, regardless of the value of this variable,
 when the output stream is a unibyte buffer or a marker pointing into
 one.
 @end defvar
@@ -766,3 +766,48 @@ parentheses and brackets when printed.  Any list or vector at a depth
 exceeding this limit is abbreviated with an ellipsis.  A value of
 @code{nil} (which is the default) means no limit.
 @end defvar
+
+  These variables are used for detecting and reporting circular 
+and shared structure---but they are only defined in Emacs 21.
+
+@tindex print-circle
+@defvar print-circle
+If non-@code{nil}, this variable enables detection of circular 
+and shared structure in printing.
+@end defvar
+
+@tindex print-gensym
+@defvar print-gensym
+If non-@code{nil}, this variable enables detection of uninterned symbols
+(@pxref{Creating Symbols}) in printing.  When this is enabled,
+uninterned symbols print with the prefix @samp{#:}, which tells the Lisp
+reader to produce an uninterned symbol.
+@end defvar
+
+@tindex print-continuous-numbering
+@defvar print-continuous-numbering
+To print several objects with shared structure in common, you should
+bind @code{print-continuous-numbering} to @code{t} around them all.
+That tells @code{print} not to reinitialize @code{print-number-table}
+each time.
+@end defvar
+
+@tindex print-number-table
+@defvar print-number-table
+This variable holds the table used as the basis of outputting
+@samp{#@var{n}=} and @samp{#@var{n}#} constructs for circular and shared
+structure.  When you want to print several objects with shared structure
+in common, you should bind @code{print-number-table} to @code{nil}
+around them all.
+@end defvar
+
+  Here is an example of printing two objects with a common
+set of shared substructure:
+
+@example
+(let ((print-circle t)
+      (print-continuous-numbering t)
+      print-number-table)
+  (print1 x)
+  (print1 y))
+@end example
diff --git a/lispref/strings.texi b/lispref/strings.texi
index eb7e35293d1..bec0864de71 100644
--- a/lispref/strings.texi
+++ b/lispref/strings.texi
@@ -27,7 +27,7 @@ keyboard character events.
 * Creating Strings::          Functions to allocate new strings.
 * Modifying Strings::         Altering the contents of an existing string.
 * Text Comparison::           Comparing characters or strings.
-* String Conversion::         Converting characters or strings and vice versa.
+* String Conversion::         Converting to and from characters and strings.
 * Formatting Strings::        @code{format}: Emacs's analogue of @code{printf}.
 * Case Conversion::           Case conversion functions.
 * Case Tables::               Customizing case conversion.
@@ -43,7 +43,7 @@ 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.)
+C are terminated by a character with @sc{ascii} code 0.)
 
   Since strings are arrays, and therefore sequences as well, you can
 operate on them with the general array and sequence functions.
@@ -51,25 +51,25 @@ operate on them with the general array and sequence functions.
 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
+  There are two text representations for non-@sc{ascii} characters in
 Emacs strings (and in buffers): unibyte and multibyte (@pxref{Text
-Representations}).  @sc{ASCII} characters always occupy one byte in a
-string; in fact, when a string is all @sc{ASCII}, there is no real
+Representations}).  An @sc{ascii} character always occupies one byte in a
+string; in fact, when a string is all @sc{ascii}, there is no real
 difference between the unibyte and multibyte representations.
 For most Lisp programming, you don't need to be concerned with these two
 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 character
+characters (which are 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
-control characters.  They do not distinguish case in @sc{ASCII} control
+modifiers; they can hold @sc{ascii} control characters, but no other
+control characters.  They do not distinguish case in @sc{ascii} control
 characters.  If you want to store such characters in a sequence, such as
 a key sequence, you must use a vector instead of a string.
-@xref{Character Type}, for more information about representation of meta
+@xref{Character Type}, for more information about the representation of meta
 and other modifiers for keyboard input characters.
 
   Strings are useful for holding regular expressions.  You can also
@@ -200,7 +200,7 @@ 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.
+@code{substring} also accepts a vector for the first argument.
 For example:
 
 @example
@@ -250,8 +250,8 @@ When an argument is an integer (not a sequence of integers), it is
 converted to a string of digits making up the decimal printed
 representation of the integer.  @strong{Don't use this feature; we plan
 to eliminate it.  If you already use this feature, change your programs
-now!}  The proper way to convert an integer to a decimal number in this
-way is with @code{format} (@pxref{Formatting Strings}) or
+now!}  The proper way to convert an integer to its decimal printed form
+is with @code{format} (@pxref{Formatting Strings}) or
 @code{number-to-string} (@pxref{String Conversion}).
 
 @example
@@ -271,7 +271,7 @@ Lists}.
 
 @defun split-string string separators
 @tindex split-string
-Split @var{string} into substrings in between matches for the regular
+This function splits @var{string} into substrings at matches for the regular
 expression @var{separators}.  Each match for @var{separators} defines a
 splitting point; the substrings between the splitting points are made
 into a list, which is the value returned by @code{split-string}.
@@ -367,7 +367,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 strings 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
@@ -379,9 +379,9 @@ Representations}.
 @cindex lexical comparison
 @defun string< string1 string2
 @c (findex string< causes problems for permuted index!!)
-This function compares two strings a character at a time.  First it
-scans both the strings at once to find the first pair of corresponding
-characters that do not match.  If the lesser character of those two is
+This function compares two strings a character at a time.  It
+scans both the strings at the same time to find the first pair of corresponding
+characters that do not match.  If the lesser character of these two is
 the character from @var{string1}, then @var{string1} is less, and this
 function returns @code{t}.  If the lesser character is the one from
 @var{string2}, then @var{string1} is greater, and this function returns
@@ -389,11 +389,11 @@ function returns @code{t}.  If the lesser character is the one from
 
 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
+@sc{ascii} character set than their upper case counterparts; digits and
 many punctuation characters have a lower numeric value than upper case
-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}).
+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
 @group
@@ -433,11 +433,12 @@ no characters is less than any other string.
 
 @defun compare-strings string1 start1 end1 string2 start2 end2 &optional ignore-case
 @tindex compare-strings
-This function compares a specified part of @var{string1} with a
+This function compares the specified part of @var{string1} with the
 specified part of @var{string2}.  The specified part of @var{string1}
-runs from index @var{start1} up to index @var{end1} (default, the end of
-the string).  The specified part of @var{string2} runs from index
-@var{start2} up to index @var{end2} (default, the end of the string).
+runs from index @var{start1} up to index @var{end1} (@code{nil} means
+the end of the string).  The specified part of @var{string2} runs from
+index @var{start2} up to index @var{end2} (@code{nil} means the end of
+the string).
 
 The strings are both converted to multibyte for the comparison
 (@pxref{Text Representations}) so that a unibyte string can be equal to
@@ -500,7 +501,7 @@ This function returns a new string containing one character,
 @cindex string to character
   This function returns the first character in @var{string}.  If the
 string is empty, the function returns 0.  The value is also 0 when the
-first character of @var{string} is the null character, @sc{ASCII} code
+first character of @var{string} is the null character, @sc{ascii} code
 0.
 
 @example
@@ -510,8 +511,10 @@ first character of @var{string} is the null character, @sc{ASCII} code
      @result{} 120
 (string-to-char "")
      @result{} 0
+@group
 (string-to-char "\000")
      @result{} 0
+@end group
 @end example
 
 This function may be eliminated in the future if it does not seem useful
@@ -523,7 +526,7 @@ enough to retain.
 @cindex integer to decimal
 This function returns a string consisting of the printed base-ten
 representation of @var{number}, which may be an integer or a floating
-point number.  The value starts with a sign if the argument is
+point number.  The returned value starts with a minus sign if the argument is
 negative.
 
 @example
@@ -553,8 +556,9 @@ more work and does not seem useful.
 The parsing skips spaces and tabs at the beginning of @var{string}, then
 reads as much of @var{string} as it can interpret as a number.  (On some
 systems it ignores other whitespace at the beginning, not just spaces
-and tabs.)  If the first character after the ignored whitespace is not a
-digit or a plus or minus sign, this function returns 0.
+and tabs.)  If the first character after the ignored whitespace is
+neither a digit, nor a plus or minus sign, nor the leading dot of a
+floating point number, this function returns 0.
 
 @example
 (string-to-number "256")
@@ -607,6 +611,10 @@ 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.
+
+The characters in @var{string}, other than the format specifications,
+are copied directly into the output; starting in Emacs 21, if they have
+text properties, these are copied into the output also.
 @end defun
 
 @cindex @samp{%} in format
@@ -646,6 +654,10 @@ made without quoting (that is, using @code{princ}, not
 by their contents alone, with no @samp{"} characters, and symbols appear
 without @samp{\} characters.
 
+Starting in Emacs 21, if the object is a string, its text properties are
+copied into the output.  The text properties of the @samp{%s} itself
+are also copied, but those of the object take priority.
+
 If there is no corresponding object, the empty string is used.
 
 @item %S
@@ -774,15 +786,15 @@ not truncated.  In the third case, the padding is on the right.
   The character case functions change the case of single characters or
 of the contents of strings.  The functions normally convert only
 alphabetic characters (the letters @samp{A} through @samp{Z} and
-@samp{a} through @samp{z}, as well as non-ASCII letters); other
-characters are not altered.  (You can specify a different case
-conversion mapping by specifying a case table---@pxref{Case Tables}.)
+@samp{a} through @samp{z}, as well as non-@sc{ascii} letters); other
+characters are not altered.  You can specify a different case
+conversion mapping by specifying a case table (@pxref{Case Tables}).
 
   These functions do not modify the strings that are passed to them as
 arguments.
 
   The examples below use the characters @samp{X} and @samp{x} which have
-@sc{ASCII} codes 88 and 120 respectively.
+@sc{ascii} codes 88 and 120 respectively.
 
 @defun downcase string-or-char
 This function converts a character or a string to lower case.
@@ -814,7 +826,7 @@ lower case is converted to upper case.
 When the argument to @code{upcase} is a character, @code{upcase}
 returns the corresponding upper case character.  This value is an integer.
 If the original character is upper case, or is not a letter, then the
-value equals the original character.
+value returned equals the original character.
 
 @example
 (upcase "The cat in the hat")
@@ -921,7 +933,7 @@ of them, or @samp{A} for both of them).
 
   The extra table @var{equivalences} is a map that cyclicly permutes
 each equivalence class (of characters with the same canonical
-equivalent).  (For ordinary @sc{ASCII}, this would map @samp{a} into
+equivalent).  (For ordinary @sc{ascii}, this would map @samp{a} into
 @samp{A} and @samp{A} into @samp{a}, and likewise for each set of
 equivalent characters.)
 
@@ -958,7 +970,7 @@ This sets the current buffer's case table to @var{table}.
 @end defun
 
   The following three functions are convenient subroutines for packages
-that define non-@sc{ASCII} character sets.  They modify the specified
+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}.  Normally you would use these functions to change
 the standard case table.
diff --git a/lispref/symbols.texi b/lispref/symbols.texi
index c9a2d34d5ef..3239a9ecaef 100644
--- a/lispref/symbols.texi
+++ b/lispref/symbols.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/symbols
-@node Symbols, Evaluation, Sequences Arrays Vectors, Top
+@node Symbols, Evaluation, Hash Tables, Top
 @chapter Symbols
 @cindex symbol
 
@@ -57,7 +57,7 @@ The @dfn{function cell} holds the function definition of the symbol.
 When a symbol is used as a function, its function definition is used in
 its place.  This cell is also used to make a symbol stand for a keymap
 or a keyboard macro, for editor command execution.  Because each symbol
-has separate value and function cells, variables and function names do
+has separate value and function cells, variables names and function names do
 not conflict.  See @code{symbol-function} in @ref{Function Cells}.
 
 @item Property list
@@ -194,7 +194,9 @@ book cover to cover when looking up Jan Jones, you start with the J's
 and go from there.  That is a simple version of hashing.  Each element
 of the obarray is a @dfn{bucket} which holds all the symbols with a
 given hash code; to look for a given name, it is sufficient to look
-through all the symbols in the bucket for that name's hash code.
+through all the symbols in the bucket for that name's hash code.  (The
+same idea is used for general Emacs hash tables, but they are a
+different data type; see @ref{Hash Tables}.)
 
 @cindex interning
   If a symbol with the desired name is found, the reader uses that
@@ -208,6 +210,11 @@ particular name.  Other like-named symbols may exist, but not in the
 same obarray.  Thus, the reader gets the same symbols for the same
 names, as long as you keep reading with the same obarray.
 
+  Interning usually happens automatically in the reader, but sometimes
+other programs need to do it.  For example, after the @kbd{M-x} command
+obtains the command name as a string using the minibuffer, it then
+interns the string, to get the interned symbol with that name.
+
 @cindex symbol equality
 @cindex uninterned symbol
   No obarray contains all symbols; in fact, some symbols are not in any
@@ -216,6 +223,10 @@ symbol has the same four cells as other symbols; however, the only way
 to gain access to it is by finding it in some other object or as the
 value of a variable.
 
+  Creating an uninterned symbol is useful in generating Lisp code,
+because an uninterned symbol used as a variable in the code you generate
+cannot clash with any variables used in other Lisp programs.
+
   In Emacs Lisp, an obarray is actually a vector.  Each element of the
 vector is a bucket; its value is either an interned symbol whose name
 hashes to that bucket, or 0 if the bucket is empty.  Each interned
@@ -224,7 +235,7 @@ in the bucket.  Because these links are invisible, there is no way to
 find all the symbols in an obarray except using @code{mapatoms} (below).
 The order of symbols in a bucket is not significant.
 
-  In an empty obarray, every element is 0, and you can create an obarray
+  In an empty obarray, every element is 0, so you can create an obarray
 with @code{(make-vector @var{length} 0)}.  @strong{This is the only
 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
diff --git a/lispref/syntax.texi b/lispref/syntax.texi
index 35cde861d15..4405be5a4f8 100644
--- a/lispref/syntax.texi
+++ b/lispref/syntax.texi
@@ -71,7 +71,7 @@ A syntax table can inherit the data for some characters from the
 standard syntax table, while specifying other characters itself.  The
 ``inherit'' syntax class means ``inherit this character's syntax from
 the standard syntax table.''  Just changing the standard syntax for a
-characters affects all syntax tables which inherit from it.
+character affects all syntax tables that inherit from it.
 
 @defun syntax-table-p object
 This function returns @code{t} if @var{object} is a syntax table.
@@ -92,9 +92,11 @@ 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
-designator character is one that is frequently in that class; however,
+designator character is one that is often assigned that class; however,
 its meaning as a designator is unvarying and independent of what syntax
-that character currently has.
+that character currently has.  Thus, @samp{\} as a designator character
+always gives ``escape character'' syntax, regardless of what syntax
+@samp{\} currently has.
 
 @cindex syntax descriptor
   A syntax descriptor is a Lisp string that specifies a syntax class, a
@@ -106,7 +108,7 @@ character or flags are needed, one character is sufficient.
 
   For example, the syntax descriptor for the character @samp{*} in C
 mode is @samp{@w{. 23}} (i.e., punctuation, matching character slot
-unused, second character of a comment-starter, first character of an
+unused, second character of a comment-starter, first character of a
 comment-ender), and the entry for @samp{/} is @samp{@w{. 14}} (i.e.,
 punctuation, matching character slot unused, first character of a
 comment-starter, second character of a comment-ender).
@@ -542,6 +544,10 @@ This function moves point forward across characters having syntax classes
 mentioned in @var{syntaxes}.  It stops when it encounters the end of
 the buffer, or position @var{limit} (if specified), or a character it is
 not supposed to skip.
+
+If @var{syntaxes} starts with @samp{^}, then the function skips
+characters whose syntax is @emph{not} in @var{syntaxes}.
+
 The return value is the distance traveled, which is a nonnegative
 integer.
 @end defun
@@ -549,8 +555,11 @@ integer.
 @defun skip-syntax-backward syntaxes &optional limit
 This function moves point backward across characters whose syntax
 classes are mentioned in @var{syntaxes}.  It stops when it encounters
-the beginning of the buffer, or position @var{limit} (if specified), or a
-character it is not supposed to skip.
+the beginning of the buffer, or position @var{limit} (if specified), or
+a character it is not supposed to skip.
+
+If @var{syntaxes} starts with @samp{^}, then the function skips
+characters whose syntax is @emph{not} in @var{syntaxes}.
 
 The return value indicates the distance traveled.  It is an integer that
 is zero or less.
@@ -856,7 +865,7 @@ 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
+  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}.
 
diff --git a/lispref/text.texi b/lispref/text.texi
index 840601bc4c8..b5b5c58af2b 100644
--- a/lispref/text.texi
+++ b/lispref/text.texi
@@ -220,6 +220,9 @@ This is the contents of buffer foo
 "
 @end group
 @end example
+
+When this function is used in the minibuffer, the value does not include
+the prompt.
 @end defun
 
 @defun thing-at-point thing
@@ -275,7 +278,7 @@ and @samp{rara!}.  The value is 2 because the first substring is greater
 at the second character.
 
 @example
-(compare-buffer-substring nil 6 11 nil 16 21)
+(compare-buffer-substrings nil 6 11 nil 16 21)
      @result{} 2
 @end example
 @end defun
@@ -482,6 +485,8 @@ empty.  If the buffer is read-only, it signals a @code{buffer-read-only}
 error.  Otherwise, it deletes the text without asking for any
 confirmation.  It returns @code{nil}.
 
+In the minibuffer, @code{erase-buffer} does not delete the prompt.
+
 Normally, deleting a large amount of text from a buffer inhibits further
 auto-saving of that buffer ``because it has shrunk''.  However,
 @code{erase-buffer} does not do this, the idea being that the future
@@ -1790,8 +1795,8 @@ converts the tab into spaces so that it can move precisely to column
 @var{force}, since there is no way to split them.
 
 The argument @var{force} also has an effect if the line isn't long
-enough to reach column @var{column}; in that case, it says to add
-whitespace at the end of the line to reach that column.
+enough to reach column @var{column}; if it is @code{t}, that means to
+add whitespace at the end of the line to reach that column.
 
 If @var{column} is not an integer, an error is signaled.
 
@@ -2540,14 +2545,31 @@ of the symbol serve as defaults for the properties of the character.
 @cindex face codes of text
 @kindex face @r{(text property)}
 You can use the property @code{face} to control the font and color of
-text.  Its value is a face name or a list of face names.  @xref{Faces},
-for more information.
+text.  @xref{Faces}, for more information.
+
+In the simplest case, the value is a face name.  It can also be a list;
+then each element can be any of these possibilities;
+
+@itemize @bullet
+@item
+A face name (a symbol or string).
 
-If the property value is a list, elements may also have the form
-@code{(foreground-color . @var{color-name})} or @code{(background-color
-. @var{color-name})}.  These elements specify just the foreground color
-or just the background color; therefore, there is no need to create a
-face for each color that you want to use.
+@item
+Starting in Emacs 21, a property list of face attributes.  This has the
+form (@var{keyword} @var{value} @dots{}), where each @var{keyword} is a
+face attribute name and @var{value} is a meaningful value for that
+attribute.  With this feature, you do not need to create a face each
+time you want to specify a particular attribute for certain text.
+@xref{Face Attributes}.
+
+@item
+A cons cell of the form @code{(foreground-color . @var{color-name})} or
+@code{(background-color . @var{color-name})}.  These elements specify
+just the foreground color or just the background color.
+
+@code{(foreground-color . @var{color-name})} is equivalent to
+@code{(:foreground @var{color-name})}, and likewise for the background.
+@end itemize
 
 @xref{Font Lock Mode}, for information on how to update @code{face}
 properties automatically based on the contents of the text.
@@ -2559,6 +2581,26 @@ mouse is on or near the character.  For this purpose, ``near'' means
 that all text between the character and where the mouse is have the same
 @code{mouse-face} property value.
 
+@item fontified
+@kindex fontified @r{(text property)}
+This property, if non-@code{nil}, says that text in the buffer has
+had faces assigned automatically by a feature such as Font-Lock mode.
+@xref{Auto Faces}.
+
+@item display
+@kindex display @r{(text property)}
+This property activates various features that change the
+way text is displayed.  For example, it can make text appear taller
+or shorter, higher or lower, wider or narror, or replaced with an image.
+@xref{Display Property}.
+
+@item help-echo
+@kindex help-echo @r{(text property)}
+If text has a string as its @code{help-echo} property, then when you
+move the mouse onto that text, Emacs displays that string in the echo
+area, or in the tooltip window.  This feature is used in the mode line.
+It is available starting in Emacs 21.
+
 @item local-map
 @cindex keymap of character
 @kindex local-map @r{(text property)}
@@ -3231,7 +3273,7 @@ all markers unrelocated.
 @cindex base 64 encoding
 
   Base 64 code is used in email to encode a sequence of 8-bit bytes as a
-longer sequence of @sc{ASCII} graphic characters.  This section
+longer sequence of @sc{ascii} graphic characters.  This section
 describes the functions for converting to and from this code.
 
 @defun base64-encode-region beg end &optional no-line-break
@@ -3377,3 +3419,14 @@ to call.  Here is an example:
 This variable is a normal hook that is run whenever a buffer is changed
 that was previously in the unmodified state.
 @end defvar
+
+@defvar inhibit-modification-hooks
+@tindex inhibit-modification-hooks
+If this variable is non-@code{nil}, all of the change hooks are
+disabled; none of them run.  This affects all the hook variables
+described above in this section, as well as the hooks attached to
+certain special text properties (@pxref{Special Properties}) and overlay
+properties (@pxref{Overlay Properties}).
+
+This variable is available starting in Emacs 21.
+@end defvar
diff --git a/lispref/tips.texi b/lispref/tips.texi
index 5e7ac75302b..5ce4c437176 100644
--- a/lispref/tips.texi
+++ b/lispref/tips.texi
@@ -14,6 +14,12 @@ it gives advice on making effective use of the features described in the
 previous chapters, and describes conventions Emacs Lisp programmers
 should follow.
 
+  You can automatically check some of the conventions described below by
+running the command @kbd{M-x checkdoc RET} when visiting a Lisp file.
+It cannot check all of the conventions, and not all the warnings it
+gives necessarily correspond to problems, but it is worth examining them
+all.
+
 @menu
 * Coding Conventions::        Conventions for clean and robust programs.
 * Compilation Tips::          Making compiled code run fast.
@@ -287,6 +293,17 @@ coherent if all libraries use the same conventions.
 Try to avoid compiler warnings about undefined free variables, by adding
 @code{defvar} definitions for these variables.
 
+Sometimes adding a @code{require} for another package is useful to avoid
+compilation warnings for variables and functions defined in that
+package.  If you do this, often it is better if the @cpde{require} acts
+only at compile time.  Here's how to do that:
+
+@example
+(eval-when-compile
+  (require 'foo)
+  (defvar bar-baz))
+@end example
+
 If you bind a variable in one function, and use it or set it in another
 function, the compiler warns about the latter function unless the
 variable has a definition.  But often these variables have short names,
@@ -421,12 +438,12 @@ should be made up of complete sentences also, but they may be filled if
 that looks good.
 
 @item
-For consistency, phrase the verb in the first sentence of a
-function's documentation string as an infinitive with ``to'' omitted.  For
-instance, use ``Return the cons of A and B.'' in preference to ``Returns
-the cons of A and B@.''  Usually it looks good to do likewise for the
-rest of the first paragraph.  Subsequent paragraphs usually look better
-if they have proper subjects.
+For consistency, phrase the verb in the first sentence of a function's
+documentation string as an imperative--for instance, use ``Return the
+cons of A and B.'' in preference to ``Returns the cons of A and B@.''
+Usually it looks good to do likewise for the rest of the first
+paragraph.  Subsequent paragraphs usually look better if each sentence
+has a proper subject.
 
 @item
 Write documentation strings in the active voice, not the passive, and in
@@ -485,9 +502,15 @@ a name for that value.  Thus, the documentation string of the function
 @code{/} refers to its second argument as @samp{DIVISOR}, because the
 actual argument name is @code{divisor}.
 
-Also use all caps for meta-syntactic variables, such as when you show
+Also use all caps for metasyntactic variables, such as when you show
 the decomposition of a list or vector into subunits, some of which may
-vary.
+vary.  @samp{KEY} and @samp{VALUE} in the following example
+illustrate this practice:
+
+@example
+The argument TABLE should be an alist whose elements
+have the form (KEY . VALUE).  Here, KEY is ...
+@end example
 
 @item
 @iftex
@@ -537,6 +560,14 @@ that satisfy the criterion.
 does not make a hyperlink to the documentation, irrelevant here, of the
 function @code{list}.
 
+To make a hyperlink to Info documentation, write the name of the Info
+node in single quotes, preceded by @samp{info node} or @samp{Info
+node}.  The Info file name defaults to @samp{emacs}.  For example,
+
+@smallexample
+See Info node `Font Lock' and Info node `(elisp)Font Lock Basics'.
+@end smallexample
+
 @item
 Don't write key sequences directly in documentation strings.  Instead,
 use the @samp{\\[@dots{}]} construct to stand for them.  For example,
@@ -659,7 +690,21 @@ Manipulating Comments, emacs, The GNU Emacs Manual}.
 
   Emacs has conventions for using special comments in Lisp libraries
 to divide them into sections and give information such as who wrote
-them.  This section explains these conventions.  First, an example:
+them.  This section explains these conventions.
+
+  We'll start with an example, a package that is included in the Emacs
+distribution.
+
+  Parts of this example reflect its status as part of Emacs; for
+example, the copyright notice lists the Free Software Foundation as the
+copyright holder, and the copying permission says the file is part of
+Emacs.  When you write a package and post it, the copyright holder would
+be you (unless your employer claims to own it instead), and you should
+get the suggested copying permission from the end of the GNU General
+Public License itself.  Don't say your file is part of Emacs
+if we haven't installed it in Emacs yet!
+
+  With that warning out of the way, on to the example:
 
 @smallexample
 @group
@@ -773,7 +818,8 @@ This begins change log information stored in the library file (if you
 store the change history there).  For most of the Lisp
 files distributed with Emacs, the change history is kept in the file
 @file{ChangeLog} and not in the source file at all; these files do
-not have a @samp{;;; Change Log:} line.
+not have a @samp{;;; Change Log:} line.  @samp{History} is an
+alternative to @samp{Change Log}.
 
 @item ;;; Code:
 This begins the actual code of the program.
diff --git a/lispref/variables.texi b/lispref/variables.texi
index 4d46e19d0dc..b37af877b3c 100644
--- a/lispref/variables.texi
+++ b/lispref/variables.texi
@@ -94,7 +94,7 @@ x
 @end example
 
 @node Constant Variables
-@section Variables That Never Change
+@section Variables that Never Change
 @vindex nil
 @vindex t
 @kindex setting-constant
@@ -104,8 +104,8 @@ 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 a symbol to
-itself.
+starts with @samp{:} (if it is interned in the standard obarray), except
+that you are allowed to set such a symbol to itself.
 
 @example
 @group
@@ -563,8 +563,9 @@ then the variable is a user option.
   If a user option variable has a @code{variable-interactive} property,
 the @code{set-variable} command uses that value to control reading the
 new value for the variable.  The property's value is used as if it were
-to @code{interactive} (@pxref{Using Interactive}).  However, this feature
-is largely obsoleted by @code{defcustom} (@pxref{Customization}).
+specified in @code{interactive} (@pxref{Using Interactive}).  However,
+this feature is largely obsoleted by @code{defcustom}
+(@pxref{Customization}).
 
   @strong{Warning:} If the @code{defconst} and @code{defvar} special
 forms are used while the variable has a local binding, they set the
@@ -606,8 +607,7 @@ variable.  Here's a safe way to avoid that:
 @example
 (defvar my-mode-map nil
   @var{docstring})
-(if my-mode-map
-    nil
+(unless my-mode-map
   (let ((map (make-sparse-keymap)))
     (define-key my-mode-map "\C-c\C-a" 'my-command)
     @dots{}
@@ -624,8 +624,7 @@ each form, if you do want to reinitialize the variable.
 @example
 (defvar my-mode-map nil
   @var{docstring})
-(if my-mode-map
-    nil
+(unless my-mode-map
   (setq my-mode-map (make-sparse-keymap))
   (define-key my-mode-map "\C-c\C-a" 'my-command)
   @dots{})
@@ -854,10 +853,10 @@ the others.
 @cindex dynamic scoping
   Local bindings in Emacs Lisp have @dfn{indefinite scope} and
 @dfn{dynamic extent}.  @dfn{Scope} refers to @emph{where} textually in
-the source code the binding can be accessed.  Indefinite scope means
+the source code the binding can be accessed.  ``Indefinite scope'' means
 that any part of the program can potentially access the variable
 binding.  @dfn{Extent} refers to @emph{when}, as the program is
-executing, the binding exists.  Dynamic extent means that the binding
+executing, the binding exists.  ``Dynamic extent'' means that the binding
 lasts as long as the activation of the construct that established it.
 
   The combination of dynamic extent and indefinite scope is called
@@ -902,9 +901,9 @@ definitions:
   In a lexically scoped language, the binding of @code{x} in
 @code{binder} would never be accessible in @code{user}, because
 @code{user} is not textually contained within the function
-@code{binder}.  However, in dynamically scoped Emacs Lisp, @code{user}
+@code{binder}.  However, in dynamically-scoped Emacs Lisp, @code{user}
 may or may not refer to the binding of @code{x} established in
-@code{binder}, depending on circumstances:
+@code{binder}, depending on the circumstances:
 
 @itemize @bullet
 @item
@@ -1065,9 +1064,9 @@ 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 additional,
+languages in one form or another.  Emacs, however, 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
+apply only in one buffer, and @dfn{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.
 
@@ -1100,7 +1099,7 @@ 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.  (This includes all
-newly created buffers.)  If you set the variable in a buffer that does
+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
@@ -1239,7 +1238,7 @@ If the variable is terminal-local, this function signals an error.  Such
 variables cannot have buffer-local bindings as well.  @xref{Multiple
 Displays}.
 
-@strong{Note:} do not use @code{make-local-variable} for a hook
+@strong{Note:} Do not use @code{make-local-variable} for a hook
 variable.  Instead, use @code{make-local-hook}.  @xref{Hooks}.
 @end deffn
 
diff --git a/lispref/windows.texi b/lispref/windows.texi
index 29307467d42..5596a597ca4 100644
--- a/lispref/windows.texi
+++ b/lispref/windows.texi
@@ -23,8 +23,9 @@ displayed in windows.
 * Window Point::            Each window has its own location of point.
 * Window Start::            The display-start position controls which text
                               is on-screen in the window.
-* Vertical Scrolling::      Moving text up and down in the window.
-* Horizontal Scrolling::    Moving text sideways on the window.
+* Textual Scrolling::       Moving text up and down through the window.
+* Vertical Scrolling::      Moving the contents up and down on the window.
+* Horizontal Scrolling::    Moving the contents sideways on the window.
 * Size of Window::          Accessing the size of a window.
 * Resizing Windows::        Changing the size of a window.
 * Coordinates and Windows:: Converting coordinates to windows.
@@ -251,40 +252,32 @@ characters.  The display table can specify alternative border
 characters; see @ref{Display Tables}.
 @end deffn
 
-@deffn Command split-window-vertically size
+@deffn Command split-window-vertically &optional size
 This function splits the selected window into two windows, one above the
 other, leaving the upper of the two windows selected, with @var{size}
 lines.  (If @var{size} is negative, then the lower of the two windows
 gets @minus{} @var{size} lines and the upper window gets the rest, but
 the upper window is still the one selected.)
-
-This function is simply an interface to @code{split-window}.
-Here is the complete function definition for it:
-
-@smallexample
-@group
-(defun split-window-vertically (&optional arg)
-  "Split current window into two windows, @dots{}"
-  (interactive "P")
-  (split-window nil (and arg (prefix-numeric-value arg))))
-@end group
-@end smallexample
 @end deffn
 
 @deffn Command split-window-horizontally size
 This function splits the selected window into two windows
 side-by-side, leaving the selected window with @var{size} columns.
 
-This function is simply an interface to @code{split-window}.  Here is
-the complete definition for @code{split-window-horizontally} (except for
-part of the documentation string):
+This function is basically an interface to @code{split-window}.
+You could define a simplified version of the function like this:
 
 @smallexample
 @group
 (defun split-window-horizontally (&optional arg)
   "Split selected window into two windows, side by side..."
   (interactive "P")
-  (split-window nil (and arg (prefix-numeric-value arg)) t))
+@endgroup
+@group
+  (let ((size (and arg (prefix-numeric-value arg))))
+    (and size (< size 0)
+         (setq size (+ (window-width) size)))
+    (split-window nil size t)))
 @end group
 @end smallexample
 @end deffn
@@ -565,11 +558,15 @@ ordering of windows.  The other arguments specify which windows to
 include in the cycle, as in @code{next-window}.
 @end defun
 
-@deffn Command other-window count
+@deffn Command other-window count &optional all-frames
 This function selects the @var{count}th following window in the cyclic
 order.  If count is negative, then it moves back @minus{}@var{count}
 windows in the cycle, rather than forward.  It returns @code{nil}.
 
+The argument @var{all-frames} has the same meaning is as in
+@code{next-window}, but the @var{minibuf} argument of @code{next-window}
+is always effectively @code{nil}.
+
 In an interactive call, @var{count} is the numeric prefix argument.
 @end deffn
 
@@ -895,11 +892,11 @@ variable is a function that creates a frame using parameters from
 @code{pop-up-frame-alist}.
 @end defvar
 
-@defvar pop-up-frame-alist
+@defopt pop-up-frame-alist
 This variable holds an alist specifying frame parameters used when
 @code{display-buffer} makes a new frame.  @xref{Frame Parameters}, for
 more information about frame parameters.
-@end defvar
+@end defopt
 
 @defopt special-display-buffer-names
 A list of buffer names for buffers that should be displayed specially.
@@ -938,16 +935,24 @@ The default value of this variable is
 @code{special-display-popup-frame}.
 @end defvar
 
-@defun special-display-popup-frame buffer
+@defun special-display-popup-frame buffer &rest args
 This function makes @var{buffer} visible in a frame of its own.  If
 @var{buffer} is already displayed in a window in some frame, it makes
 the frame visible and raises it, to use that window.  Otherwise, it
 creates a frame that will be dedicated to @var{buffer}.
 
-This function uses an existing window displaying @var{buffer} whether or
-not it is in a frame of its own; but if you set up the above variables
-in your init file, before @var{buffer} was created, then presumably the
-window was previously made by this function.
+If @var{args} is an alist, it specifies frame parameters for the new
+frame.
+
+If @var{args} is a list whose @sc{car} is a symbol, then @code{(car
+@var{args})} is called as a function to actually create and set up the
+frame; it is called with @var{buffer} as first argument, and @code{(cdr
+@var{args})} as additional arguments.
+
+This function always uses an existing window displaying @var{buffer},
+whether or not it is in a frame of its own; but if you set up the above
+variables in your init file, before @var{buffer} was created, then
+presumably the window was previously made by this function.
 @end defun
 
 @defopt special-display-frame-alist
@@ -1035,10 +1040,11 @@ point and the buffer's point always move together; they remain equal.
 when the user switches to another buffer, the cursor jumps to the
 position of point in that buffer.
 
-@defun window-point window
+@defun window-point &optional window
 This function returns the current position of point in @var{window}.
 For a nonselected window, this is the value point would have (in that
-window's buffer) if that window were selected.
+window's buffer) if that window were selected.  If @var{window} is
+@code{nil}, the selected window is used.
 
 When @var{window} is the selected window and its buffer is also the
 current buffer, the value returned is the same as point in that buffer.
@@ -1081,10 +1087,11 @@ display-start position is set to a display-start position recently used
 for the same buffer, or 1 if the buffer doesn't have any.
 
 Redisplay updates the window-start position (if you have not specified
-it explicitly since the previous redisplay) so that point appears on the
-screen.  Nothing except redisplay automatically changes the window-start
-position; if you move point, do not expect the window-start position to
-change in response until after the next redisplay.
+it explicitly since the previous redisplay)---for example, to make sure
+point appears on the screen.  Nothing except redisplay automatically
+changes the window-start position; if you move point, do not expect the
+window-start position to change in response until after the next
+redisplay.
 
 For a realistic example of using @code{window-start}, see the
 description of @code{count-lines} in @ref{Text Lines}.
@@ -1188,18 +1195,22 @@ argument @var{position} defaults to the current position of point;
 The @code{pos-visible-in-window-p} function considers only vertical
 scrolling.  If @var{position} is out of view only because @var{window}
 has been scrolled horizontally, @code{pos-visible-in-window-p} returns
-@code{t}.  @xref{Horizontal Scrolling}.
+@code{t} anyway.  @xref{Horizontal Scrolling}.
 @end defun
 
-@node Vertical Scrolling
-@section Vertical Scrolling
-@cindex vertical scrolling
-@cindex scrolling vertically
+@node Textual Scrolling
+@section Textual Scrolling
+@cindex textual scrolling
+@cindex scrolling textually
+
+  @dfn{Textual scrolling} means moving the text up or down though a
+window.  It works by changing the value of the window's display-start
+location.  It may also change the value of @code{window-point} to keep
+point on the screen.
 
-  Vertical scrolling means moving the text up or down in a window.  It
-works by changing the value of the window's display-start location.  It
-may also change the value of @code{window-point} to keep it on the
-screen.
+  Textual scrolling was formerly called ``vertical scrolling,'' but we
+changed its name to distinguish it from the new vertical fractional
+scrolling feature (@pxref{Vertical Scrolling}).
 
   In the commands @code{scroll-up} and @code{scroll-down}, the directions
 ``up'' and ``down'' refer to the motion of the text in the buffer at which
@@ -1218,9 +1229,10 @@ position of a window on the terminal does not move, and short scrolling
 commands clearly move the text up or down on the screen.  We have chosen
 names that fit the user's point of view.
 
-  The scrolling functions (aside from @code{scroll-other-window}) have
-unpredictable results if the current buffer is different from the buffer
-that is displayed in the selected window.  @xref{Current Buffer}.
+  The textual scrolling functions (aside from
+@code{scroll-other-window}) have unpredictable results if the current
+buffer is different from the buffer that is displayed in the selected
+window.  @xref{Current Buffer}.
 
 @deffn Command scroll-up &optional count
 This function scrolls the text in the selected window upward
@@ -1251,10 +1263,14 @@ This function scrolls the text in another window upward @var{count}
 lines.  Negative values of @var{count}, or @code{nil}, are handled
 as in @code{scroll-up}.
 
-You can specify a buffer to scroll with the variable
-@code{other-window-scroll-buffer}.  When the selected window is the
-minibuffer, the next window is normally the one at the top left corner.
-You can specify a different window to scroll with the variable
+You can specify which buffer to scroll by setting the variable
+@code{other-window-scroll-buffer} to a buffer.  If that buffer isn't
+already displayed, @code{scroll-other-window} displays it in some
+window.
+
+When the selected window is the minibuffer, the next window is normally
+the one at the top left corner.  You can specify a different window to
+scroll, when the minibuffer is selected, by setting the variable
 @code{minibuffer-scroll-window}.  This variable has no effect when any
 other window is selected.  @xref{Minibuffer Misc}.
 
@@ -1353,43 +1369,122 @@ Replaces three keystroke sequence C-u 0 C-l."
 @end example
 @end deffn
 
+@node Vertical Scrolling
+@section Vertical Fractional Scrolling
+@cindex Vertical Fractional Scrolling
+
+  @dfn{Vertical fractional scrolling} means shifting the image in the
+window up or down by a specified multiple or fraction of a line.
+Starting in Emacs 21, each window has a @dfn{vertical scroll position},
+which is a number, never less than zero.  It specifies how far to raise
+the contents of the window.  Raising the window contents generally makes
+all or part of some lines disappear off the top, and all or part of some
+other lines appear at the bottom.  The usual value is zero.
+
+  The vertical scroll position is measured in units of the normal line
+height, which is the height of the default font.  Thus, if the value is
+.5, that means the window contents are scrolled up half the normal line
+height.  If it is 3.3, that means the window contents are scrolled up
+somewhat over three times the normal line height.
+
+  What fraction of a line the vertical scrolling covers, or how many
+lines, depends on what the lines contain.  A value of .5 could scroll a
+line whose height is very short off the screen, while a value of 3.3
+could scroll just part of the way through a tall line or an image.
+
+@defun window-vscroll &optional window
+This function returns the current vertical scroll position of
+@var{window}, If @var{window} is @code{nil}, the selected window is
+used.
+
+@example
+@group
+(window-vscroll)
+     @result{} 0
+@end group
+@end example
+@end defun
+
+@defun set-window-vscroll window lines
+This function sets @var{window}'s vertical scroll position to
+@var{lines}.  The argument @var{lines} should be zero or positive; if
+not, it is taken as zero.
+
+The actual vertical scroll position must always correspond
+to an integral number of pixels, so the value you specify
+is rounded accordingly.
+
+The return value is the result of this rounding.
+
+@example
+@group
+(set-window-vscroll (selected-window) 1.2)
+     @result{} 1.13
+@end group
+@end example
+@end defun
+
 @node Horizontal Scrolling
 @section Horizontal Scrolling
 @cindex horizontal scrolling
 
-  Because we read English from left to right in the ``inner loop'', and
-from top to bottom in the ``outer loop'', horizontal scrolling is not
-like vertical scrolling.  Vertical scrolling involves selection of a
-contiguous portion of text to display, but horizontal scrolling causes
-part of each line to go off screen.  The amount of horizontal scrolling
-is therefore specified as a number of columns rather than as a position
-in the buffer.  It has nothing to do with the display-start position
-returned by @code{window-start}.
+  @dfn{Horizontal scrolling} means shifting the image in the window left
+or right by a specified multiple of the normal character width.  Each
+window has a @dfn{vertical scroll position}, which is a number, never
+less than zero.  It specifies how far to shift the contents left.
+Shifting the window contents left generally makes all or part of some
+characters disappear off the left, and all or part of some other
+characters appear at the right.  The usual value is zero.
+
+  The horizontal scroll position is measured in units of the normal
+character width, which is the width of space in the default font.  Thus,
+if the value is 5, that means the window contents are scrolled left by 5
+times the the normal character width.  How many characters actually
+disappear off to the left depends on their width, and could vary from
+line to line.
+
+  Because we read from side to side in the ``inner loop'', and from top
+to bottom in the ``outer loop'', the effect of horizontal scrolling is
+not like that of textual or vertical scrolling.  Textual scrolling
+involves selection of a portion of text to display, and vertical
+scrolling moves the window contents contiguously; but horizontal
+scrolling causes part of @emph{each line} to go off screen.
 
   Usually, no horizontal scrolling is in effect; then the leftmost
 column is at the left edge of the window.  In this state, scrolling to
-the right is meaningless, since there is no data to the left of the
-screen to be revealed by it; so this is not allowed.  Scrolling to the
-left is allowed; it scrolls the first columns of text off the edge of
-the window and can reveal additional columns on the right that were
-truncated before.  Once a window has a nonzero amount of leftward
-horizontal scrolling, you can scroll it back to the right, but only so
-far as to reduce the net horizontal scroll to zero.  There is no limit
-to how far left you can scroll, but eventually all the text will
-disappear off the left edge.
-
-@deffn Command scroll-left count
+the right is meaningless, since there is no data to the left of the edge
+to be revealed by it; so this is not allowed.  Scrolling to the left is
+allowed; it scrolls the first columns of text off the edge of the window
+and can reveal additional columns on the right that were truncated
+before.  Once a window has a nonzero amount of leftward horizontal
+scrolling, you can scroll it back to the right, but only so far as to
+reduce the net horizontal scroll to zero.  There is no limit to how far
+left you can scroll, but eventually all the text will disappear off the
+left edge.
+
+  In Emacs 21, redisplay automatically alters the horizontal scrolling
+of a window as necessary to ensure that point is always visible.
+However, you can still set the horizontal scrolling value explicitly.
+The value you specify will be used, provided it leaves point visible.
+
+@deffn Command scroll-left &optional count
 This function scrolls the selected window @var{count} columns to the
-left (or to the right if @var{count} is negative).  The return value is
-the total amount of leftward horizontal scrolling in effect after the
-change---just like the value returned by @code{window-hscroll} (below).
+left (or to the right if @var{count} is negative).  The default
+for @var{count} is the window width, minus 2.
+
+The return value is the total amount of leftward horizontal scrolling in
+effect after the change---just like the value returned by
+@code{window-hscroll} (below).
 @end deffn
 
-@deffn Command scroll-right count
+@deffn Command scroll-right &optional count
 This function scrolls the selected window @var{count} columns to the
-right (or to the left if @var{count} is negative).  The return value is
-the total amount of leftward horizontal scrolling in effect after the
-change---just like the value returned by @code{window-hscroll} (below).
+right (or to the left if @var{count} is negative).  The default
+for @var{count} is the window width, minus 2.
+
+The return value is the total amount of leftward horizontal scrolling in
+effect after the change---just like the value returned by
+@code{window-hscroll} (below).
 
 Once you scroll a window as far right as it can go, back to its normal
 position where the total leftward scrolling is zero, attempts to scroll
@@ -1426,6 +1521,7 @@ If @var{window} is @code{nil}, the selected window is used.
 This function sets the number of columns from the left margin that
 @var{window} is scrolled from the value of @var{columns}.  The argument
 @var{columns} should be zero or positive; if not, it is taken as zero.
+Fractional values of @var{columns} are not supported at present.
 
 The value returned is @var{columns}.
 
@@ -1516,12 +1612,12 @@ the frame.  The element @var{right} of the value is one more than the
 rightmost column used by @var{window}, and @var{bottom} is one more than
 the bottommost row used by @var{window} and its mode-line.
 
-When you have side-by-side windows, the right edge value for a window
-with a neighbor on the right includes the width of the separator between
-the window and that neighbor.  This separator may be a column of
-@samp{|} characters or it may be a scroll bar.  Since the width of the
-window does not include this separator, the width does not equal the
-difference between the right and left edges in this case.
+If a window has a scroll bar, the right edge value includes the width of
+the scroll bar.  Otherwise, if the window has a neighbor on the right,
+its right edge value includes the width of the separator line between
+the window and that neighbor.  Since the width of the window does not
+include this separator, the width does not usually equal the difference
+between the right and left edges.
 
 Here is the result obtained on a typical 24-line terminal with just one
 window:
@@ -1538,14 +1634,12 @@ The bottom edge is at line 23 because the last line is the echo area.
 
 If @var{window} is at the upper left corner of its frame, then
 @var{bottom} is the same as the value of @code{(window-height)},
-@var{right} is almost the same as the value of
-@code{(window-width)}@footnote{They are not exactly equal because
-@var{right} includes the vertical separator line or scroll bar, while
-@code{(window-width)} does not.}, and @var{top} and @var{left} are zero.
-For example, the edges of the following window are @w{@samp{0 0 5 8}}.
-Assuming that the frame has more than 8 columns, the last column of the
-window (column 7) holds a border rather than text.  The last row (row 4)
-holds the mode line, shown here with @samp{xxxxxxxxx}.
+@var{right} is almost the same as the value of @code{(window-width)},
+and @var{top} and @var{left} are zero.  For example, the edges of the
+following window are @w{@samp{0 0 8 5}}.  Assuming that the frame has
+more than 8 columns, the last column of the window (column 7) holds a
+border rather than text.  The last row (row 4) holds the mode line,
+shown here with @samp{xxxxxxxxx}.
 
 @example
 @group
@@ -1561,15 +1655,9 @@ holds the mode line, shown here with @samp{xxxxxxxxx}.
 @end group
 @end example
 
-When there are side-by-side windows, any window not at the right edge of
-its frame has a separator in its last column or columns.  The separator
-counts as one or two columns in the width of the window.  A window never
-includes a separator on its left, since that belongs to the window to
-the left.
-
 In the following example, let's suppose that the frame is 7
 columns wide.  Then the edges of the left window are @w{@samp{0 0 4 3}}
-and the edges of the right window are @w{@samp{4 0 7 3}}.
+and the edges of the right window are @w{@samp{4 0 8 3}}.
 
 @example
 @group
@@ -1610,6 +1698,13 @@ If the requested size would exceed that of the window's frame, then the
 function makes the window occupy the entire height (or width) of the
 frame.
 
+If there are various other windows from which lines or columns can be
+stolen, and some of them specify fixed size (using
+@code{window-size-fixed}, see below), they are left untouched while
+other windows are ``robbed.''  If it would be necessary to alter the
+size of a fixed-size window, @code{enlarge-window} gets an error
+instead.
+
 If @var{size} is negative, this function shrinks the window by
 @minus{}@var{size} lines or columns.  If that makes the window smaller
 than the minimum size (@code{window-min-height} and
@@ -1652,10 +1747,11 @@ It could be defined as follows:
 @end example
 @end deffn
 
-@deffn Command shrink-window-if-larger-than-buffer window
+@deffn Command shrink-window-if-larger-than-buffer &optional window
 This command shrinks @var{window} to be as small as possible while still
 showing the full contents of its buffer---but not less than
-@code{window-min-height} lines.
+@code{window-min-height} lines.  If @var{window} is not given,
+it defaults to the selected window.
 
 However, the command does nothing if the window is already too small to
 display the whole text of the buffer, or if part of the contents are
@@ -1663,6 +1759,35 @@ currently scrolled off screen, or if the window is not the full width of
 its frame, or if the window is the only window in its frame.
 @end deffn
 
+@tindex window-size-fixed
+@defvar window-size-fixed
+If this variable is non-@code{nil}, in any given buffer,
+then the size of any window displaying the buffer remains fixed
+unless you explicitly change it or Emacs has no other choice.
+(This feature is new in Emacs 21.)
+
+If the value is @code{height}, then only the window's height is fixed;
+if the value is @code{width}, then only the window's width is fixed.
+Any other non-@code{nil} value fixes both the width and the height.
+
+The usual way to use this variable is to give it a buffer-local value in
+a particular buffer.  That way, the windows (but usually there is only
+one) displaying that buffer have fixed size.
+
+Explicit size-change functions such as @code{enlarge-window}
+get an error if they would have to change a window size which is fixed.
+Therefore, when you want to change the size of such a window,
+you should bind @code{window-size-fixed} to @code{nil}, like this:
+
+@example
+(let ((window-size-fixed nil))
+   (enlarge-window 10))
+@end example
+
+Note that changing the frame size will change the size of a
+fixed-size window, if there is no other alternative.
+@end defvar
+
 @cindex minimum window size
   The following two variables constrain the window-size-changing
 functions to a minimum height and width.
@@ -1721,11 +1846,14 @@ window.
 @item mode-line
 The coordinates are in the mode line of @var{window}.
 
-@item vertical-split
+@item header-line
+The coordinates are in the header line of @var{window}.
+
+@item vertical-line
 The coordinates are in the vertical line between @var{window} and its
 neighbor to the right.  This value occurs only if the window doesn't
 have a scroll bar; positions in a scroll bar are considered outside the
-window.
+window for these purposes.
 
 @item nil
 The coordinates are not in any part of @var{window}.
@@ -1750,8 +1878,8 @@ configuration previously saved.
 configuration instead of a window configuration.  @xref{Frame
 Configurations}.
 
-@defun current-window-configuration
-This function returns a new object representing the selected frame's
+@defun current-window-configuration &optional frame
+This function returns a new object representing @var{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
@@ -1759,16 +1887,20 @@ 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.
+
+If @var{frame} is omitted, the selected frame is used.
 @end defun
 
 @defun set-window-configuration configuration
 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 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}
+specified by @var{configuration}, for the frame that @var{configuration}
+was created for.
+
+The argument @var{configuration} must be a value that was previously
+returned by @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.
@@ -1913,7 +2045,7 @@ This function sets @var{window}'s end trigger position at
 @var{position}.
 @end defun
 
-@defun window-redisplay-end-trigger window
+@defun window-redisplay-end-trigger &optional window
 @tindex window-redisplay-end-trigger
 This function returns @var{window}'s current end trigger position.
 @end defun