Merged from emacs@sv.gnu.org

Patches applied:

 * emacs@sv.gnu.org/emacs--devo--0--patch-371
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-372
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-373
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-374
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-375
   Merge from gnus--rel--5.10

 * emacs@sv.gnu.org/emacs--devo--0--patch-376
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-377
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-378
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-379
   Merge from erc--emacs--21

 * emacs@sv.gnu.org/emacs--devo--0--patch-380
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-381
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-382
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-383
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-384
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-385
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-386
   Update from erc--emacs--22

 * emacs@sv.gnu.org/emacs--devo--0--patch-387
   Fix ERC bug introduced in last patch

 * emacs@sv.gnu.org/emacs--devo--0--patch-388
   Update from erc--emacs--22

 * emacs@sv.gnu.org/emacs--devo--0--patch-389
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-390
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-391
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-392
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-393
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-394
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-395
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-396
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-397
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-398
   Merge from gnus--rel--5.10

 * emacs@sv.gnu.org/emacs--devo--0--patch-399
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-400
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-401
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-402
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-403
   Rcirc update from Ryan Yeske

 * emacs@sv.gnu.org/emacs--devo--0--patch-404
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-405
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-406
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-407
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-408
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-409
   Update from CVS

 * emacs@sv.gnu.org/emacs--devo--0--patch-410
   Merge from gnus--rel--5.10

 * emacs@sv.gnu.org/emacs--devo--0--patch-411
   Miscellaneous tq-related fixes.

 * emacs@sv.gnu.org/emacs--devo--0--patch-412
   Update from CVS

 * emacs@sv.gnu.org/gnus--rel--5.10--patch-121
   Update from CVS

 * emacs@sv.gnu.org/gnus--rel--5.10--patch-122
   Update from CVS

 * emacs@sv.gnu.org/gnus--rel--5.10--patch-123
   Update from CVS

 * emacs@sv.gnu.org/gnus--rel--5.10--patch-124
   Update from CVS

 * emacs@sv.gnu.org/gnus--rel--5.10--patch-125
   Update from CVS

 * emacs@sv.gnu.org/gnus--rel--5.10--patch-126
   Merge from emacs--devo--0

 * emacs@sv.gnu.org/gnus--rel--5.10--patch-127
   Update from CVS


git-archimport-id: lorentey@elte.hu--2004/emacs--multi-tty--0--patch-581

14 files changed, 1060 insertions, 777 deletions

diff --git a/lispref/ChangeLog b/lispref/ChangeLog
index 09757fca10b..cc3ccac3c7a 100644
--- a/lispref/ChangeLog
+++ b/lispref/ChangeLog
@@ -1,3 +1,129 @@
+2006-08-27  Michael Olson  <mwolson@gnu.org>
+
+        * processes.texi (Transaction Queues): Remove stray quote
+        character.
+
+2006-08-25  Richard Stallman  <rms@gnu.org>
+
+        * os.texi (Idle Timers): run-with-idle-timer allows Lisp time value.
+        Add xref.
+
+2006-08-24  Chong Yidong  <cyd@stupidchicken.com>
+
+        * os.texi (Timers): Avoid waiting inside timers.
+
+2006-08-21  Lute Kamstra  <lute@gnu.org>
+
+        * Makefile.in: Use ../man/texinfo.tex to build elisp.dvi.
+
+2006-08-20  Richard Stallman  <rms@gnu.org>
+
+        * os.texi (Idle Timers): New node, split out from Timers.
+        Document current-idle-time.
+        * commands.texi (Reading One Event): Update xref.
+        * elisp.texi (Top): Update subnode menu.
+
+2006-08-16  Richard Stallman  <rms@gnu.org>
+
+        * keymaps.texi (Extended Menu Items): Show format of cached
+        bindings in extended menu items.
+
+        * customize.texi (Variable Definitions): Explain when the
+        standard value expression is evaluated.
+
+2006-08-15  Chong Yidong  <cyd@stupidchicken.com>
+
+        * commands.texi (Reading One Event): Explain idleness in
+        `read-event'.
+
+2006-08-12  Chong Yidong  <cyd@stupidchicken.com>
+
+        * text.texi (Near Point): Say "cursor" not "terminal cursor".
+        (Commands for Insertion): Removed split-line since it's not
+        relevant for Lisp programming.
+        (Yank Commands): Rewrite introduction.
+        (Undo): Clarify.
+        (Maintaining Undo): Clarify.  Document undo-ask-before-discard.
+        (Filling): Remove redundant comment.  Clarify return value of
+        current-justification.
+        (Margins): Minor clarifications.
+        (Adaptive Fill): Update default value of adaptive-fill-regexp.
+        (Sorting): Update definition of sort-lines.
+        (Columns): Clarify behavior of sort-columns.
+        (Indent Tabs): Link to Tab Stops in Emacs manual.
+        (Special Properties): Clarify.
+        (Clickable Text): Mention Buttons package.
+
+2006-08-12  Kevin Ryde  <user42@zip.com.au>
+
+        * os.texi (Time Parsing): Add %z to description of
+        format-time-string, as per docstring.  Add cross reference to
+        glibc manual for strftime.
+
+2006-08-08  Richard Stallman  <rms@gnu.org>
+
+        * modes.texi: Clean up wording in previous change.
+
+2006-08-07  Chong Yidong  <cyd@stupidchicken.com>
+
+        * modes.texi (Hooks): Clarify.
+        (Major Mode Basics): Mention define-derived-mode explicitly.
+        (Major Mode Conventions): Rebinding RET is OK for some modes.
+        Mention change-major-mode-hook and after-change-major-mode-hook.
+        (Example Major Modes): Moved to end of Modes section.
+        (Mode Line Basics): Clarify.
+        (Mode Line Data): Mention help-echo and local-map in strings.
+        Explain reason for treatment of non-risky variables.
+        (Properties in Mode): Clarify.
+        (Faces for Font Lock): Add font-lock-negation-char-face.
+
+2006-08-04  Eli Zaretskii  <eliz@gnu.org>
+
+        * strings.texi (Formatting Strings): Warn against arbitrary
+        strings as first arg to `format'.
+
+2006-07-31  Thien-Thi Nguyen  <ttn@gnu.org>
+
+        * text.texi (Clickable Text): Mention `help-echo' text property.
+        Update intro, examples and associated explanations.
+
+2006-07-31  Richard Stallman  <rms@gnu.org>
+
+        * commands.texi: Update xrefs.
+        (Event Mod): New node, cut out from old Translating Input.
+
+        * maps.texi: Update xrefs.
+
+        * keymaps.texi (Translation Keymaps): New node.
+        Update xrefs from Translating Input to Translation Keymaps.
+
+        * elisp.texi (Top): Update subnode menu.
+
+        * display.texi (Face Functions): Fix explanations of FRAME=t or nil.
+
+        * os.texi (System Interface): Fix menu descriptions of some nodes.
+        (Translating Input): Node deleted.
+
+2006-07-31  Nick Roberts  <nickrob@snap.net.nz>
+
+        * modes.texi (Minor Mode Conventions): Update link for add-to-list.
+
+        * lists.texi (Sets And Lists): Likewise.
+
+2006-07-30  Thien-Thi Nguyen  <ttn@gnu.org>
+
+        * text.texi (Fields): Mention POS
+        requirement when narrowing is in effect.
+
+2006-07-28  Richard Stallman  <rms@gnu.org>
+
+        * display.texi (Face Attributes): Simplify wording.
+        (Attribute Functions): Clarify meaning of new-frame default
+        attribute settings.
+
+        * customize.texi (Common Keywords): Document how to use
+        :package-version in a package not in Emacs.
+
 2006-07-28  Kim F. Storm  <storm@cua.dk>
 
         * commands.texi (Reading One Event): Fix last change.
@@ -248,7 +374,7 @@
 
         * anti.texi, customize.texi, display.texi, internals.texi:
         * minibuf.texi, modes.texi, tips.texi:
-        Fix overfull/underfull boxes.
+        Fix overfull/underfull boxes.
 
 2006-07-05  Thien-Thi Nguyen  <ttn@gnu.org>
 
@@ -325,7 +451,7 @@
 
 2006-06-09  Aidan Kehoe  <kehoea@parhasard.net>
 
-        * objects.texi (Character Type): Describe the\uABCD and \U00ABCDEF
+        * objects.texi (Character Type): Describe the \uABCD and \U00ABCDEF
         syntax.
 
 2006-06-07  Eli Zaretskii  <eliz@gnu.org>
@@ -637,7 +763,7 @@
 2006-04-13  Bill Wohler  <wohler@newt.com>
 
         * customize.texi (Common Keywords): Use dotted notation for
-        :package-version value. Specify its values. Improve documentation
+        :package-version value.  Specify its values.  Improve documentation
         for customize-package-emacs-version-alist.
 
 2006-04-12  Bill Wohler  <wohler@newt.com>
@@ -1682,7 +1808,7 @@
         (Jumping): Clarify description of `h' command.
         Eliminate redundant @ref.
         (Breaks): New node.
-        (Breakpoints): is now a subsubsection.
+        (Breakpoints): Is now a subsubsection.
         (Global Break Condition): Mention `C-x X X'.
         (Edebug Views): Clarify `v' and `p'.  Mention `C-x X w'.
         (Trace Buffer): Clarify STRING arg of `edebug-tracing'.
@@ -2932,7 +3058,7 @@
 
 2004-10-24  Jason Rumney  <jasonr@gnu.org>
 
-        * commands.texi (Misc Events): Remove mouse-wheel. Add wheel-up
+        * commands.texi (Misc Events): Remove mouse-wheel.  Add wheel-up
         and wheel-down.
 
 2004-10-24  Kai Grossjohann  <kai.grossjohann@gmx.net>
@@ -3161,7 +3287,7 @@
         except while processing `frame-title-format' or `icon-title-format'.
         (Deleting Frames): Correct description of `delete-frame'.
         Non-nil return values of `frame-live-p' are like those of `framep'.
-        (Frames and Windows): mention return value of
+        (Frames and Windows): Mention return value of
         `set-frame-selected-window'.
         (Visibility of Frames): Mention `force' argument to
         `make-frame-invisible'.  `frame-visible-p' returns t for all
@@ -3488,7 +3614,7 @@
 
 2004-03-07  Thien-Thi Nguyen  <ttn@gnu.org>
 
-        * customize.texi: Fix typo. Remove eol whitespace.
+        * customize.texi: Fix typo.  Remove eol whitespace.
 
 2004-03-04  Richard M. Stallman  <rms@gnu.org>
 
@@ -3524,7 +3650,7 @@
         * text.texi: Various small changes in addition to the following:
         (User-Level Deletion): Mention optional BACKWARD-ONLY argument
         to delete-horizontal-space.
-        (Kill Functions, Yanking, Low-Level Kill Ring): clarify and correct
+        (Kill Functions, Yanking, Low-Level Kill Ring): Clarify and correct
         description of yank-handler text property at various places.
 
         * frames.texi (Window System Selections): Add anchor.
@@ -4551,7 +4677,7 @@
         * loading.texi (Unloading): Fix recent change for load-history.
 
         * customize.texi (Simple Types): Clarify description of custom
-        type 'number. Describe new custom type 'float.
+        type 'number.  Describe new custom type 'float.
 
 2002-12-04  Markus Rost  <rost@math.ohio-state.edu>
 
@@ -5081,7 +5207,7 @@ Mon Apr 17 18:56:50 1989  Robert J. Chassell  (bob@rice-chex.ai.mit.edu)
 Tue Apr 11 12:23:28 1989  Robert J. Chassell  (bob@rice-chex.ai.mit.edu)
 
         * Applied Karl Berry's patches to *.texinfo files, but not to
-        texinfo.tex; those diffs are in `berry-texinfo-tex-diffs'. (Karl's
+        texinfo.tex; those diffs are in `berry-texinfo-tex-diffs'.  (Karl's
         new title page format is also not applied, since it requires
         texinfo.tex changes.)
 
diff --git a/lispref/Makefile.in b/lispref/Makefile.in
index e3d09fe2c6f..1eea23e122e 100644
--- a/lispref/Makefile.in
+++ b/lispref/Makefile.in
@@ -27,6 +27,7 @@ srcdir = @srcdir@
 VPATH=@srcdir@
 
 infodir = $(srcdir)/../info
+usermanualdir = $(srcdir)/../man
 
 TEXI2DVI = texi2dvi
 SHELL = /bin/sh
@@ -103,7 +104,7 @@ $(infodir)/elisp: $(srcs)
         $(MAKEINFO) -I. -I$(srcdir) $(srcdir)/elisp.texi -o $(infodir)/elisp
 
 elisp.dvi: $(srcs)
-        $(TEXI2DVI) -I $(srcdir) $(srcdir)/elisp.texi
+        $(TEXI2DVI) -I $(srcdir) -I $(usermanualdir) $(srcdir)/elisp.texi
 
 # This is for use in a separate distro of the Emacs Lisp manual.
 install: elisp
diff --git a/lispref/commands.texi b/lispref/commands.texi
index 10cd97400f8..514b55205a1 100644
--- a/lispref/commands.texi
+++ b/lispref/commands.texi
@@ -1087,7 +1087,7 @@ Lisp programs by representing the former as the integer 9, and the
 latter as the symbol @code{tab}.
 
 Most of the time, it's not useful to distinguish the two.  So normally
-@code{function-key-map} (@pxref{Translating Input}) is set up to map
+@code{function-key-map} (@pxref{Translation Keymaps}) is set up to map
 @code{tab} into 9.  Thus, a key binding for character code 9 (the
 character @kbd{C-i}) also applies to @code{tab}.  Likewise for the other
 symbols in this group.  The function @code{read-char} likewise converts
@@ -2051,14 +2051,14 @@ functions for event input are also available for use in Lisp programs.
 See also @code{momentary-string-display} in @ref{Temporary Displays},
 and @code{sit-for} in @ref{Waiting}.  @xref{Terminal Input}, for
 functions and variables for controlling terminal input modes and
-debugging terminal input.  @xref{Translating Input}, for features you
-can use for translating or modifying input events while reading them.
+debugging terminal input.
 
   For higher-level input facilities, see @ref{Minibuffers}.
 
 @menu
 * Key Sequence Input::          How to read one key sequence.
 * Reading One Event::           How to read just one event.
+* Event Mod::                   How Emacs modifies events as they are read.
 * Invoking the Input Method::   How reading an event uses the input method.
 * Quoted Character Input::      Asking the user to specify a character.
 * Event Input Misc::            How to reread or throw away input events.
@@ -2088,7 +2088,7 @@ events---characters, symbols, and lists.  The elements of the string or
 vector are the events in the key sequence.
 
 Reading a key sequence includes translating the events in various
-ways.  @xref{Translating Input}.
+ways.  @xref{Translation Keymaps}.
 
 The argument @var{prompt} is either a string to be displayed in the
 echo area as a prompt, or @code{nil}, meaning not to display a prompt.
@@ -2229,6 +2229,15 @@ number of seconds; on these systems, @var{seconds} is rounded down.
 If @var{seconds} is @code{nil}, @code{read-event} waits as long as
 necessary for input to arrive.
 
+If @var{seconds} is @code{nil}, Emacs is considered idle while waiting
+for user input to arrive.  Idle timers---those created with
+@code{run-with-idle-timer} (@pxref{Idle Timers})---can run during this
+period.  However, if @var{seconds} is non-@code{nil}, the state of
+idleness remains unchanged.  If Emacs is non-idle when
+@code{read-event} is called, it remains non-idle throughout the
+operation of @code{read-event}; if Emacs is idle (which can happen if
+the call happens inside an idle timer), it remains idle.
+
 If @code{read-event} gets an event that is defined as a help character,
 then in some cases @code{read-event} processes the event directly without
 returning.  @xref{Help Functions}.  Certain other events, called
@@ -2290,6 +2299,87 @@ This variable holds the total number of input events received so far
 from the terminal---not counting those generated by keyboard macros.
 @end defvar
 
+@node Event Mod
+@subsection Modifying and Translating Input Events
+
+  Emacs modifies every event it reads according to
+@code{extra-keyboard-modifiers}, then translates it through
+@code{keyboard-translate-table} (if applicable), before returning it
+from @code{read-event}.
+
+@c Emacs 19 feature
+@defvar extra-keyboard-modifiers
+This variable lets Lisp programs ``press'' the modifier keys on the
+keyboard.  The value is a character.  Only the modifiers of the
+character matter.  Each time the user types a keyboard key, it is
+altered as if those modifier keys were held down.  For instance, if
+you bind @code{extra-keyboard-modifiers} to @code{?\C-\M-a}, then all
+keyboard input characters typed during the scope of the binding will
+have the control and meta modifiers applied to them.  The character
+@code{?\C-@@}, equivalent to the integer 0, does not count as a control
+character for this purpose, but as a character with no modifiers.
+Thus, setting @code{extra-keyboard-modifiers} to zero cancels any
+modification.
+
+When using a window system, the program can ``press'' any of the
+modifier keys in this way.  Otherwise, only the @key{CTL} and @key{META}
+keys can be virtually pressed.
+
+Note that this variable applies only to events that really come from
+the keyboard, and has no effect on mouse events or any other events.
+@end defvar
+
+@defvar keyboard-translate-table
+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}.
+(It can also be a string or vector, but this is considered obsolete.)
+
+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.
+
+Note that this translation is the first thing that happens to a
+character after it is read from the terminal.  Record-keeping features
+such as @code{recent-keys} and dribble files record the characters after
+translation.
+
+Note also that this translation is done before the characters are
+supplied to input methods (@pxref{Input Methods}).  Use
+@code{translation-table-for-input} (@pxref{Translation of Characters}),
+if you want to translate characters after input methods operate.
+@end defvar
+
+@defun keyboard-translate from to
+This function modifies @code{keyboard-translate-table} to translate
+character code @var{from} into character code @var{to}.  It creates
+the keyboard translate table if necessary.
+@end defun
+
+  Here's an example of using the @code{keyboard-translate-table} to
+make @kbd{C-x}, @kbd{C-c} and @kbd{C-v} perform the cut, copy and paste
+operations:
+
+@example
+(keyboard-translate ?\C-x 'control-x)
+(keyboard-translate ?\C-c 'control-c)
+(keyboard-translate ?\C-v 'control-v)
+(global-set-key [control-x] 'kill-region)
+(global-set-key [control-c] 'kill-ring-save)
+(global-set-key [control-v] 'yank)
+@end example
+
+@noindent
+On a graphical terminal that supports extended @acronym{ASCII} input,
+you can still get the standard Emacs meanings of one of those
+characters by typing it with the shift key.  That makes it a different
+character as far as keyboard translation is concerned, but it has the
+same usual meaning.
+
+  @xref{Translation Keymaps}, for mechanisms that translate event sequences
+at the level of @code{read-key-sequence}.
+
 @node Invoking the Input Method
 @subsection Invoking the Input Method
 
diff --git a/lispref/customize.texi b/lispref/customize.texi
index 3aca1a90bcf..9e10e547b56 100644
--- a/lispref/customize.texi
+++ b/lispref/customize.texi
@@ -133,18 +133,21 @@ version.  The value @var{version} must be a string.
 
 @item :package-version '(@var{package} . @var{version})
 This option specifies that the item was first introduced in
-@var{package} version @var{version}, or that its default value was
-changed in that version.  This keyword takes priority over :version.
-The value of @var{package} is a symbol and @var{version} is a string.
-The @var{package} and @var{version} must appear in the alist
-@code{customize-package-emacs-version-alist}.  Since @var{package} must
-be unique and the user might see it in an error message, a good choice
-is the official name of the package, such as MH-E or Gnus.
+@var{package} version @var{version}, or that its meaning or default
+value was changed in that version.  The value of @var{package} is a
+symbol and @var{version} is a string.
 
+This keyword takes priority over @code{:version}.
+
+@var{package} should be the official name of the package, such as MH-E
+or Gnus.  If the package @var{package} is released as part of Emacs,
+@var{package} and @var{version} should appear in the value of
+@code{customize-package-emacs-version-alist}.
 @end table
 
-Packages that use the @code{:package-version} keyword must also update
-the @code{customize-package-emacs-version-alist} variable.
+Packages distributed as part of Emacs that use the
+@code{:package-version} keyword must also update the
+@code{customize-package-emacs-version-alist} variable.
 
 @defvar customize-package-emacs-version-alist
 This alist provides a mapping for the versions of Emacs that are
@@ -248,19 +251,30 @@ turn this feature back on, if someone would like to do the work.
 
   Use @code{defcustom} to declare user-editable variables.
 
-@defmac defcustom option default doc [keyword value]@dots{}
-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.  There is no need to start it with a @samp{*}
-because @code{defcustom} automatically marks @var{option} as a
-@dfn{user option} (@pxref{Defining Variables}).
-
-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.  You should normally avoid using backquotes in
-@var{default} because they are not expanded when editing the value,
-causing list values to appear to have the wrong structure.
+@defmac defcustom option standard doc [keyword value]@dots{}
+This construct declares @var{option} as a customizable user option
+variable.  You should not quote @var{option}.  The argument @var{doc}
+specifies the documentation string for the variable.  There is no need
+to start it with a @samp{*}, because @code{defcustom} automatically
+marks @var{option} as a @dfn{user option} (@pxref{Defining
+Variables}).
+
+The argument @var{standard} is an expression that specifies the
+standard value for @var{option}.  Evaluating the @code{defcustom} form
+evaluates @var{standard}, but does not necessarily install the
+standard value.  If @var{option} already has a default value,
+@code{defcustom} does not change it.  If the user has saved a
+customization for @var{option}, @code{defcustom} installs the user's
+customized value as @var{option}'s default value.  If neither of those
+cases applies, @code{defcustom} installs the result of evaluating
+@var{standard} as the default value.
+
+The expression @var{standard} can be evaluated at various other times,
+too---whenever the customization facility needs to know @var{option}'s
+standard value.  So be sure to use an expression which is harmless to
+evaluate at any time.  We recommend avoiding backquotes in
+@var{standard}, because they are not expanded when editing the value,
+so list values will appear to have the wrong structure.
 
 If you specify the @code{:set} option, to make the variable take other
 special actions when set through the customization buffer, the
@@ -403,7 +417,7 @@ type of @var{symbol}.
 @end defun
 
 Internally, @code{defcustom} uses the symbol property
-@code{standard-value} to record the expression for the default value,
+@code{standard-value} to record the expression for the standard value,
 and @code{saved-value} to record the value saved by the user with the
 customization buffer.  Both properties are actually lists whose car is
 an expression which evaluates to the value.
diff --git a/lispref/display.texi b/lispref/display.texi
index 678ca657b5b..e762c14a7f0 100644
--- a/lispref/display.texi
+++ b/lispref/display.texi
@@ -1857,9 +1857,9 @@ as if they had a light background.
 
   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 can 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{Displaying Faces}.
+mean.  You can specify more than one face for a given piece of text;
+Emacs merges the attributes of all the faces to determine how to
+display the text.  @xref{Displaying Faces}.
 
   Any attribute in a face can have the value @code{unspecified}.  This
 means the face doesn't specify that attribute.  In face merging, when
@@ -2048,15 +2048,13 @@ suitable for use with @code{:stipple} (see above).  It returns
 @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.
+  This section describes the functions for accessing and modifying the
+attributes of an existing face.
 
 @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.
+This function sets one or more attributes of face @var{face} for frame
+@var{frame}.  The attributes you specify this way override whatever
+the @code{defface} says.
 
 The extra arguments @var{arguments} specify the attributes to set, and
 the values for them.  They should consist of alternating attribute names
@@ -2073,6 +2071,13 @@ Thus,
 @noindent
 sets the attributes @code{:width}, @code{:weight} and @code{:underline}
 to the corresponding values.
+
+If @var{frame} is @code{t}, this function sets the default attributes
+for new frames.  Default attribute values specified this way override
+the @code{defface} for newly created frames.
+
+If @var{frame} is @code{nil}, this function sets the attributes for
+all existing frames, and the default for new frames.
 @end defun
 
 @defun face-attribute face attribute &optional frame inherit
@@ -2080,8 +2085,10 @@ 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 (@pxref{Input Focus}).
 
-If @var{frame} is @code{t}, the value is the default for
-@var{face} for new frames.
+If @var{frame} is @code{t}, this returns whatever new-frames default
+value you previously specified with @code{set-face-attribute} for the
+@var{attribute} attribute of @var{face}.  If you have not specified
+one, it returns @code{nil}.
 
 If @var{inherit} is @code{nil}, only attributes directly defined by
 @var{face} are considered, so the return value may be
@@ -2135,6 +2142,8 @@ face attribute @var{attribute}, returns @var{value1} unchanged.
   The functions above did not exist before Emacs 21.  For compatibility
 with older Emacs versions, you can use the following functions to set
 and examine the face attributes which existed in those versions.
+They use values of @code{t} and @code{nil} for @var{frame}
+just like @code{set-face-attribute} and @code{face-attribute}.
 
 @defun set-face-foreground face color &optional frame
 @defunx set-face-background face color &optional frame
@@ -2191,9 +2200,10 @@ This function swaps the foreground and background colors of face
 @end defun
 
   These functions examine the attributes of a face.  If you don't
-specify @var{frame}, they refer to the default data for new frames.
-They return the symbol @code{unspecified} if the face doesn't define any
-value for that attribute.
+specify @var{frame}, they refer to the selected frame; @code{t} refers
+to the default data for new frames.  They return the symbol
+@code{unspecified} if the face doesn't define any value for that
+attribute.
 
 @defun face-foreground face &optional frame inherit
 @defunx face-background face &optional frame inherit
diff --git a/lispref/elisp.texi b/lispref/elisp.texi
index db92bdc97ee..41a2f1cdde0 100644
--- a/lispref/elisp.texi
+++ b/lispref/elisp.texi
@@ -1039,8 +1039,10 @@ Operating System Interface
 * Processor Run Time::      Getting the run time used by Emacs.
 * Time Calculations::       Adding, subtracting, comparing times, etc.
 * 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.
+* Idle Timers::             Setting a timer to call a function when Emacs has
+                              been idle for a certain length of time.
+* Terminal Input::          Accessing and recordingo terminal input.
+* Terminal Output::         Controlling and recording terminal output.
 * Sound Output::            Playing sounds on the computer's speaker.
 * X11 Keysyms::             Operating on key symbols for X Windows
 * Batch Mode::              Running Emacs without terminal interaction.
diff --git a/lispref/keymaps.texi b/lispref/keymaps.texi
index f93c94b8dfe..13f4550a082 100644
--- a/lispref/keymaps.texi
+++ b/lispref/keymaps.texi
@@ -33,6 +33,7 @@ found.  The whole process is called @dfn{key lookup}.
 * Functions for Key Lookup::    How to request key lookup.
 * Changing Key Bindings::       Redefining a key in a keymap.
 * Remapping Commands::          Bindings that translate one command to another.
+* Translation Keymaps::         Keymaps for translating sequences of events.
 * Key Binding Commands::        Interactive interfaces for redefining keys.
 * Scanning Keymaps::            Looking through all keymaps, for printing help.
 * Menu Keymaps::                Defining a menu as a keymap.
@@ -642,7 +643,7 @@ only when the mode is used for the first time in a session.
 and exit commands.  @xref{Intro to Minibuffers}.
 
   Emacs has other keymaps that are used in a different way---translating
-events within @code{read-key-sequence}.  @xref{Translating Input}.
+events within @code{read-key-sequence}.  @xref{Translation Keymaps}.
 
   @xref{Standard Keymaps}, for a list of standard keymaps.
 
@@ -682,7 +683,7 @@ An error is signaled if @var{key} is not a string or a vector.
 @node Searching Keymaps
 @section Searching the Active Keymaps
 
-  After translation of the input events (@pxref{Translating Input})
+  After translation of event subsequences (@pxref{Translation Keymaps})
 Emacs looks for them in the active keymaps.  Here is a pseudo-Lisp
 description of the order in which the active keymaps are searched:
 
@@ -1472,6 +1473,125 @@ given the current active keymaps.  If @var{command} is not remapped
 @code{nil}.
 @end defun
 
+@node Translation Keymaps
+@section Keymaps for Translating Sequences of Events
+
+  This section describes keymaps that are used during reading a key
+sequence, to translate certain event sequences into others.
+@code{read-key-sequence} checks every subsequence of the key sequence
+being read, as it is read, against @code{function-key-map} and then
+against @code{key-translation-map}.
+
+@defvar function-key-map
+This variable holds a keymap that describes the character sequences sent
+by function keys on an ordinary character terminal.  This keymap has the
+same structure as other keymaps, but is used differently: it specifies
+translations to make while reading key sequences, rather than bindings
+for key sequences.
+
+If @code{function-key-map} ``binds'' a key sequence @var{k} to a vector
+@var{v}, then when @var{k} appears as a subsequence @emph{anywhere} in a
+key sequence, it is replaced with the events in @var{v}.
+
+For example, VT100 terminals send @kbd{@key{ESC} O P} when the
+keypad @key{PF1} key is pressed.  Therefore, we want Emacs to translate
+that sequence of events into the single event @code{pf1}.  We accomplish
+this by ``binding'' @kbd{@key{ESC} O P} to @code{[pf1]} in
+@code{function-key-map}, when using a VT100.
+
+Thus, typing @kbd{C-c @key{PF1}} sends the character sequence @kbd{C-c
+@key{ESC} O P}; later the function @code{read-key-sequence} translates
+this back into @kbd{C-c @key{PF1}}, which it returns as the vector
+@code{[?\C-c pf1]}.
+
+Entries in @code{function-key-map} are ignored if they conflict with
+bindings made in the minor mode, local, or global keymaps.  The intent
+is that the character sequences that function keys send should not have
+command bindings in their own right---but if they do, the ordinary
+bindings take priority.
+
+The value of @code{function-key-map} is usually set up automatically
+according to the terminal's Terminfo or Termcap entry, but sometimes
+those need help from terminal-specific Lisp files.  Emacs comes with
+terminal-specific files for many common terminals; their main purpose is
+to make entries in @code{function-key-map} beyond those that can be
+deduced from Termcap and Terminfo.  @xref{Terminal-Specific}.
+@end defvar
+
+@defvar key-translation-map
+This variable is another keymap used just like @code{function-key-map}
+to translate input events into other events.  It differs from
+@code{function-key-map} in two ways:
+
+@itemize @bullet
+@item
+@code{key-translation-map} goes to work after @code{function-key-map} is
+finished; it receives the results of translation by
+@code{function-key-map}.
+
+@item
+Non-prefix bindings in @code{key-translation-map} override actual key
+bindings.  For example, if @kbd{C-x f} has a non-prefix binding in
+@code{key-translation-map}, that translation takes effect even though
+@kbd{C-x f} also has a key binding in the global map.
+@end itemize
+
+Note however that actual key bindings can have an effect on
+@code{key-translation-map}, even though they are overridden by it.
+Indeed, actual key bindings override @code{function-key-map} and thus
+may alter the key sequence that @code{key-translation-map} receives.
+Clearly, it is better to avoid this type of situation.
+
+The intent of @code{key-translation-map} is for users to map one
+character set to another, including ordinary characters normally bound
+to @code{self-insert-command}.
+@end defvar
+
+@cindex key translation function
+You can use @code{function-key-map} or @code{key-translation-map} for
+more than simple aliases, by using a function, instead of a key
+sequence, as the ``translation'' of a key.  Then this function is called
+to compute the translation of that key.
+
+The key translation function receives one argument, which is the prompt
+that was specified in @code{read-key-sequence}---or @code{nil} if the
+key sequence is being read by the editor command loop.  In most cases
+you can ignore the prompt value.
+
+If the function reads input itself, it can have the effect of altering
+the event that follows.  For example, here's how to define @kbd{C-c h}
+to turn the character that follows into a Hyper character:
+
+@example
+@group
+(defun hyperify (prompt)
+  (let ((e (read-event)))
+    (vector (if (numberp e)
+                (logior (lsh 1 24) e)
+              (if (memq 'hyper (event-modifiers e))
+                  e
+                (add-event-modifier "H-" e))))))
+
+(defun add-event-modifier (string e)
+  (let ((symbol (if (symbolp e) e (car e))))
+    (setq symbol (intern (concat string
+                                 (symbol-name symbol))))
+@end group
+@group
+    (if (symbolp e)
+        symbol
+      (cons symbol (cdr e)))))
+
+(define-key function-key-map "\C-ch" 'hyperify)
+@end group
+@end example
+
+  If you have enabled keyboard character set decoding using
+@code{set-keyboard-coding-system}, decoding is done after the
+translations listed above.  @xref{Terminal I/O Encoding}.  However, in
+future Emacs versions, character set decoding may be done at an
+earlier stage.
+
 @node Key Binding Commands
 @section Commands for Binding Keys
 
@@ -1896,7 +2016,7 @@ binding, like this:
 
 @c This line is not too long--rms.
 @example
-(@var{item-string} @r{[}@var{help-string}@r{]} (@var{key-binding-data}) . @var{real-binding})
+(@var{item-string} @r{[}@var{help}@r{]} (@var{key-binding-data}) . @var{real-binding})
 @end example
 
 @noindent
@@ -2020,6 +2140,13 @@ operates on menu data structures, so you should write it so it can
 safely be called at any time.
 @end table
 
+  When an equivalent key binding is cached, the binding looks like this.
+
+@example
+(menu-item @var{item-name} @var{real-binding} (@var{key-binding-data})
+    . @var{item-property-list})
+@end example
+
 @node Menu Separators
 @subsubsection Menu Separators
 @cindex menu separators
diff --git a/lispref/lists.texi b/lispref/lists.texi
index cb60baef900..1c6247d818c 100644
--- a/lispref/lists.texi
+++ b/lispref/lists.texi
@@ -1489,7 +1489,7 @@ several @code{equal} occurrences of an element in @var{list},
 @code{delete-dups} keeps the first one.
 @end defun
 
-  See also the function @code{add-to-list}, in @ref{Setting Variables},
+  See also the function @code{add-to-list}, in @ref{List Variables},
 for another way to add an element to a list stored in a variable.
 
 @node Association Lists
diff --git a/lispref/maps.texi b/lispref/maps.texi
index ec7728f7840..cdbd655eb3c 100644
--- a/lispref/maps.texi
+++ b/lispref/maps.texi
@@ -115,7 +115,7 @@ Properties menu.
 @item function-key-map
 The keymap for translating keypad and function keys.@*
 If there are none, then it contains an empty sparse keymap.
-@xref{Translating Input}.
+@xref{Translation Keymaps}.
 
 @item fundamental-mode-map
 @vindex fundamental-mode-map
@@ -158,7 +158,7 @@ search.
 
 @item key-translation-map
 A keymap for translating keys.  This one overrides ordinary key
-bindings, unlike @code{function-key-map}.  @xref{Translating Input}.
+bindings, unlike @code{function-key-map}.  @xref{Translation Keymaps}.
 
 @item kmacro-map
 @vindex kmacro-map
diff --git a/lispref/modes.texi b/lispref/modes.texi
index b0c057ec1c9..f8afcd8a829 100644
--- a/lispref/modes.texi
+++ b/lispref/modes.texi
@@ -43,18 +43,19 @@ up in the init file (@pxref{Init File}), but Lisp programs can set them also.
 
 @cindex normal hook
   Most of the hooks in Emacs are @dfn{normal hooks}.  These variables
-contain lists of functions to be called with no arguments.  When the
-hook name ends in @samp{-hook}, that tells you it is normal.  We try to
-make all hooks normal, as much as possible, so that you can use them in
-a uniform way.
-
-  Every major mode function is supposed to run a normal hook called the
-@dfn{mode hook} as the last step of initialization.  This makes it easy
-for a user to customize the behavior of the mode, by overriding the
-buffer-local variable assignments already made by the mode.  Most
-minor modes also run a mode hook at their end.  But hooks are used in
-other contexts too.  For example, the hook @code{suspend-hook} runs
-just before Emacs suspends itself (@pxref{Suspending Emacs}).
+contain lists of functions to be called with no arguments.  By
+convention, whenever the hook name ends in @samp{-hook}, that tells
+you it is normal.  We try to make all hooks normal, as much as
+possible, so that you can use them in a uniform way.
+
+  Every major mode function is supposed to run a normal hook called
+the @dfn{mode hook} as the one of the last steps of initialization.
+This makes it easy for a user to customize the behavior of the mode,
+by overriding the buffer-local variable assignments already made by
+the mode.  Most minor mode functions also run a mode hook at the end.
+But hooks are used in other contexts too.  For example, the hook
+@code{suspend-hook} runs just before Emacs suspends itself
+(@pxref{Suspending Emacs}).
 
   The recommended way to add a hook function to a normal hook is by
 calling @code{add-hook} (see below).  The hook functions may be any of
@@ -65,20 +66,16 @@ globally or buffer-locally with @code{add-hook}.
 
 @cindex abnormal hook
   If the hook variable's name does not end with @samp{-hook}, that
-indicates it is probably an @dfn{abnormal hook}.  Then you should look at its
-documentation to see how to use the hook properly.
+indicates it is probably an @dfn{abnormal hook}.  That means the hook
+functions are called with arguments, or their return values are used
+in some way.  The hook's documentation says how the functions are
+called.  You can use @code{add-hook} to add a function to an abnormal
+hook, but you must write the function to follow the hook's calling
+convention.
 
-  If the variable's name ends in @samp{-functions} or @samp{-hooks},
-then the value is a list of functions, but it is abnormal in that either
-these functions are called with arguments or their values are used in
-some way.  You can use @code{add-hook} to add a function to the list,
-but you must take care in writing the function.  (A few of these
-variables, notably those ending in @samp{-hooks}, are actually
-normal hooks which were named before we established the convention of
-using @samp{-hook} for them.)
-
-  If the variable's name ends in @samp{-function}, then its value
-is just a single function, not a list of functions.
+  By convention, abnormal hook names end in @samp{-functions} or
+@samp{-hooks}.  If the variable's name ends in @samp{-function}, then
+its value is just a single function, not a list of functions.
 
   Here's an example that uses a mode hook to turn on Auto Fill mode when
 in Lisp Interaction mode:
@@ -96,12 +93,13 @@ arguments, and runs each hook in turn.  Each argument should be a
 symbol that is a normal hook variable.  These arguments are processed
 in the order specified.
 
-If a hook variable has a non-@code{nil} value, that value may be a
-function or a list of functions.  (The former option is considered
-obsolete.)  If the value is a function (either a lambda expression or
-a symbol with a function definition), it is called.  If it is a list
-that isn't a function, its elements are called, consecutively.  All
-the hook functions are called with no arguments.
+If a hook variable has a non-@code{nil} value, that value should be a
+list of functions.  @code{run-hooks} calls all the functions, one by
+one, with no arguments.
+
+The hook variable's value can also be a single function---either a
+lambda expression or a symbol with a function definition---which
+@code{run-hooks} calls.  But this usage is obsolete.
 @end defun
 
 @defun run-hook-with-args hook &rest args
@@ -187,7 +185,6 @@ to another major mode in the same buffer.
 @menu
 * Major Mode Basics::
 * Major Mode Conventions::  Coding conventions for keymaps, etc.
-* Example Major Modes::     Text mode and Lisp modes.
 * Auto Major Mode::         How Emacs chooses the major mode automatically.
 * Mode Help::               Finding out how to use a mode.
 * Derived Modes::           Defining a new major mode based on another major
@@ -195,6 +192,7 @@ to another major mode in the same buffer.
 * Generic Modes::           Defining a simple major mode that supports
                               comment syntax and Font Lock mode.
 * Mode Hooks::              Hooks run at the end of major mode functions.
+* Example Major Modes::     Text mode and Lisp modes.
 @end menu
 
 @node Major Mode Basics
@@ -214,14 +212,14 @@ specialized editing task, creating a new major mode is usually a good
 idea.  In practice, writing a major mode is easy (in contrast to
 writing a minor mode, which is often difficult).
 
-  If the new mode is similar to an old one, it is often unwise to modify
-the old one to serve two purposes, since it may become harder to use and
-maintain.  Instead, copy and rename an existing major mode definition
-and alter the copy---or define a @dfn{derived mode} (@pxref{Derived
-Modes}).  For example, Rmail Edit mode, which is in
-@file{emacs/lisp/mail/rmailedit.el}, is a major mode that is very similar to
-Text mode except that it provides two additional commands.  Its
-definition is distinct from that of Text mode, but uses that of Text mode.
+  If the new mode is similar to an old one, it is often unwise to
+modify the old one to serve two purposes, since it may become harder
+to use and maintain.  Instead, copy and rename an existing major mode
+definition and alter the copy---or use @code{define-derived-mode} to
+define a @dfn{derived mode} (@pxref{Derived Modes}).  For example,
+Rmail Edit mode is a major mode that is very similar to Text mode
+except that it provides two additional commands.  Its definition is
+distinct from that of Text mode, but uses that of Text mode.
 
   Even if the new mode is not an obvious derivative of any other mode,
 it is convenient to use @code{define-derived-mode} with a @code{nil}
@@ -287,8 +285,10 @@ Documentation}.
 
 @item
 The major mode command should start by calling
-@code{kill-all-local-variables}.  This is what gets rid of the
-buffer-local variables of the major mode previously in effect.
+@code{kill-all-local-variables}.  This runs the normal hook
+@code{change-major-mode-hook}, then gets rid of the buffer-local
+variables of the major mode previously in effect.  @xref{Creating
+Buffer-Local}.
 
 @item
 The major mode command should set the variable @code{major-mode} to the
@@ -355,9 +355,11 @@ Rmail that do not allow self-insertion of text can reasonably redefine
 letters and other printing characters as special commands.
 
 @item
-Major modes must not define @key{RET} to do anything other than insert
-a newline.  The command to insert a newline and then indent is
-@kbd{C-j}.  Please keep this distinction uniform for all major modes.
+Major modes modes for editing text should not define @key{RET} to do
+anything other than insert a newline.  However, it is ok for
+specialized modes for text that users don't directly edit, such as
+Dired and Info modes, to redefine @key{RET} to do something entirely
+different.
 
 @item
 Major modes should not alter options that are primarily a matter of user
@@ -427,10 +429,11 @@ other packages would interfere with them.
 @item
 @cindex mode hook
 @cindex major mode hook
-Each major mode should have a @dfn{mode hook} named
-@code{@var{modename}-mode-hook}.  The major mode command should run that
-hook, with @code{run-mode-hooks}, as the very last thing it
-does.  @xref{Mode Hooks}.
+Each major mode should have a normal @dfn{mode hook} named
+@code{@var{modename}-mode-hook}.  The very last thing the major mode command
+should do is to call @code{run-mode-hooks}.  This runs the mode hook,
+and then runs the normal hook @code{after-change-major-mode-hook}.
+@xref{Mode Hooks}.
 
 @item
 The major mode command may start by calling some other major mode
@@ -488,281 +491,6 @@ that they may be evaluated more than once without adverse consequences.
 Even if you never load the file more than once, someone else will.
 @end itemize
 
-@node Example Major Modes
-@subsection Major Mode Examples
-
-  Text mode is perhaps the simplest mode besides Fundamental mode.
-Here are excerpts from  @file{text-mode.el} that illustrate many of
-the conventions listed above:
-
-@smallexample
-@group
-;; @r{Create the syntax table for this mode.}
-(defvar text-mode-syntax-table
-  (let ((st (make-syntax-table)))
-    (modify-syntax-entry ?\" ".   " st)
-    (modify-syntax-entry ?\\ ".   " st)
-    ;; Add `p' so M-c on `hello' leads to `Hello', not `hello'.
-    (modify-syntax-entry ?' "w p" st)
-    st)
-  "Syntax table used while in `text-mode'.")
-@end group
-
-;; @r{Create the keymap for this mode.}
-@group
-(defvar text-mode-map
-  (let ((map (make-sparse-keymap)))
-    (define-key map "\e\t" 'ispell-complete-word)
-    (define-key map "\es" 'center-line)
-    (define-key map "\eS" 'center-paragraph)
-    map)
-  "Keymap for `text-mode'.
-Many other modes, such as Mail mode, Outline mode
-and Indented Text mode, inherit all the commands
-defined in this map.")
-@end group
-@end smallexample
-
-  Here is how the actual mode command is defined now:
-
-@smallexample
-@group
-(define-derived-mode text-mode nil "Text"
-  "Major mode for editing text written for humans to read.
-In this mode, paragraphs are delimited only by blank or white lines.
-You can thus get the full benefit of adaptive filling
- (see the variable `adaptive-fill-mode').
-\\@{text-mode-map@}
-Turning on Text mode runs the normal hook `text-mode-hook'."
-@end group
-@group
-  (make-local-variable 'text-mode-variant)
-  (setq text-mode-variant t)
-  ;; @r{These two lines are a feature added recently.}
-  (set (make-local-variable 'require-final-newline)
-       mode-require-final-newline)
-  (set (make-local-variable 'indent-line-function) 'indent-relative))
-@end group
-@end smallexample
-
-  But here is how it was defined formerly, before
-@code{define-derived-mode} existed:
-
-@smallexample
-@group
-;; @r{This isn't needed nowadays, since @code{define-derived-mode} does it.}
-(defvar text-mode-abbrev-table nil
-  "Abbrev table used while in text mode.")
-(define-abbrev-table 'text-mode-abbrev-table ())
-@end group
-
-@group
-(defun text-mode ()
-  "Major mode for editing text intended for humans to read...
- Special commands: \\@{text-mode-map@}
-@end group
-@group
-Turning on text-mode runs the hook `text-mode-hook'."
-  (interactive)
-  (kill-all-local-variables)
-  (use-local-map text-mode-map)
-@end group
-@group
-  (setq local-abbrev-table text-mode-abbrev-table)
-  (set-syntax-table text-mode-syntax-table)
-@end group
-@group
-  ;; @r{These four lines are absent from the current version}
-  ;; @r{not because this is done some other way, but rather}
-  ;; @r{because nowadays Text mode uses the normal definition of paragraphs.}
-  (make-local-variable 'paragraph-start)
-  (setq paragraph-start (concat "[ \t]*$\\|" page-delimiter))
-  (make-local-variable 'paragraph-separate)
-  (setq paragraph-separate paragraph-start)
-  (make-local-variable 'indent-line-function)
-  (setq indent-line-function 'indent-relative-maybe)
-@end group
-@group
-  (setq mode-name "Text")
-  (setq major-mode 'text-mode)
-  (run-mode-hooks 'text-mode-hook)) ; @r{Finally, this permits the user to}
-                                    ;   @r{customize the mode with a hook.}
-@end group
-@end smallexample
-
-@cindex @file{lisp-mode.el}
-  The three Lisp modes (Lisp mode, Emacs Lisp mode, and Lisp
-Interaction mode) have more features than Text mode and the code is
-correspondingly more complicated.  Here are excerpts from
-@file{lisp-mode.el} that illustrate how these modes are written.
-
-@cindex syntax table example
-@smallexample
-@group
-;; @r{Create mode-specific table variables.}
-(defvar lisp-mode-syntax-table nil "")
-(defvar lisp-mode-abbrev-table nil "")
-@end group
-
-@group
-(defvar emacs-lisp-mode-syntax-table
-  (let ((table (make-syntax-table)))
-    (let ((i 0))
-@end group
-
-@group
-      ;; @r{Set syntax of chars up to @samp{0} to say they are}
-      ;;   @r{part of symbol names but not words.}
-      ;;   @r{(The digit @samp{0} is @code{48} in the @acronym{ASCII} character set.)}
-      (while (< i ?0)
-        (modify-syntax-entry i "_   " table)
-        (setq i (1+ i)))
-      ;; @r{@dots{} similar code follows for other character ranges.}
-@end group
-@group
-      ;; @r{Then set the syntax codes for characters that are special in Lisp.}
-      (modify-syntax-entry ?  "    " table)
-      (modify-syntax-entry ?\t "    " table)
-      (modify-syntax-entry ?\f "    " table)
-      (modify-syntax-entry ?\n ">   " table)
-@end group
-@group
-      ;; @r{Give CR the same syntax as newline, for selective-display.}
-      (modify-syntax-entry ?\^m ">   " table)
-      (modify-syntax-entry ?\; "<   " table)
-      (modify-syntax-entry ?` "'   " table)
-      (modify-syntax-entry ?' "'   " table)
-      (modify-syntax-entry ?, "'   " table)
-@end group
-@group
-      ;; @r{@dots{}likewise for many other characters@dots{}}
-      (modify-syntax-entry ?\( "()  " table)
-      (modify-syntax-entry ?\) ")(  " table)
-      (modify-syntax-entry ?\[ "(]  " table)
-      (modify-syntax-entry ?\] ")[  " table))
-    table))
-@end group
-@group
-;; @r{Create an abbrev table for lisp-mode.}
-(define-abbrev-table 'lisp-mode-abbrev-table ())
-@end group
-@end smallexample
-
-  Much code is shared among the three Lisp modes.  The following
-function sets various variables; it is called by each of the major Lisp
-mode functions:
-
-@smallexample
-@group
-(defun lisp-mode-variables (lisp-syntax)
-  (when lisp-syntax
-    (set-syntax-table lisp-mode-syntax-table))
-  (setq local-abbrev-table lisp-mode-abbrev-table)
-  @dots{}
-@end group
-@end smallexample
-
-  Functions such as @code{forward-paragraph} use the value of the
-@code{paragraph-start} variable.  Since Lisp code is different from
-ordinary text, the @code{paragraph-start} variable needs to be set
-specially to handle Lisp.  Also, comments are indented in a special
-fashion in Lisp and the Lisp modes need their own mode-specific
-@code{comment-indent-function}.  The code to set these variables is the
-rest of @code{lisp-mode-variables}.
-
-@smallexample
-@group
-  (make-local-variable 'paragraph-start)
-  (setq paragraph-start (concat page-delimiter "\\|$" ))
-  (make-local-variable 'paragraph-separate)
-  (setq paragraph-separate paragraph-start)
-  @dots{}
-@end group
-@group
-  (make-local-variable 'comment-indent-function)
-  (setq comment-indent-function 'lisp-comment-indent))
-  @dots{}
-@end group
-@end smallexample
-
-  Each of the different Lisp modes has a slightly different keymap.  For
-example, Lisp mode binds @kbd{C-c C-z} to @code{run-lisp}, but the other
-Lisp modes do not.  However, all Lisp modes have some commands in
-common.  The following code sets up the common commands:
-
-@smallexample
-@group
-(defvar shared-lisp-mode-map ()
-  "Keymap for commands shared by all sorts of Lisp modes.")
-
-;; @r{Putting this @code{if} after the @code{defvar} is an older style.}
-(if shared-lisp-mode-map
-    ()
-   (setq shared-lisp-mode-map (make-sparse-keymap))
-   (define-key shared-lisp-mode-map "\e\C-q" 'indent-sexp)
-   (define-key shared-lisp-mode-map "\177"
-               'backward-delete-char-untabify))
-@end group
-@end smallexample
-
-@noindent
-And here is the code to set up the keymap for Lisp mode:
-
-@smallexample
-@group
-(defvar lisp-mode-map ()
-  "Keymap for ordinary Lisp mode...")
-
-(if lisp-mode-map
-    ()
-  (setq lisp-mode-map (make-sparse-keymap))
-  (set-keymap-parent lisp-mode-map shared-lisp-mode-map)
-  (define-key lisp-mode-map "\e\C-x" 'lisp-eval-defun)
-  (define-key lisp-mode-map "\C-c\C-z" 'run-lisp))
-@end group
-@end smallexample
-
-  Finally, here is the complete major mode function definition for
-Lisp mode.
-
-@smallexample
-@group
-(defun lisp-mode ()
-  "Major mode for editing Lisp code for Lisps other than GNU Emacs Lisp.
-Commands:
-Delete converts tabs to spaces as it moves back.
-Blank lines separate paragraphs.  Semicolons start comments.
-\\@{lisp-mode-map@}
-Note that `run-lisp' may be used either to start an inferior Lisp job
-or to switch back to an existing one.
-@end group
-
-@group
-Entry to this mode calls the value of `lisp-mode-hook'
-if that value is non-nil."
-  (interactive)
-  (kill-all-local-variables)
-@end group
-@group
-  (use-local-map lisp-mode-map)          ; @r{Select the mode's keymap.}
-  (setq major-mode 'lisp-mode)           ; @r{This is how @code{describe-mode}}
-                                         ;   @r{finds out what to describe.}
-  (setq mode-name "Lisp")                ; @r{This goes into the mode line.}
-  (lisp-mode-variables t)                ; @r{This defines various variables.}
-  (make-local-variable 'comment-start-skip)
-  (setq comment-start-skip
-        "\\(\\(^\\|[^\\\\\n]\\)\\(\\\\\\\\\\)*\\)\\(;+\\|#|\\) *")
-  (make-local-variable 'font-lock-keywords-case-fold-search)
-  (setq font-lock-keywords-case-fold-search t)
-@end group
-@group
-  (setq imenu-case-fold-search t)
-  (set-syntax-table lisp-mode-syntax-table)
-  (run-mode-hooks 'lisp-mode-hook))           ; @r{This permits the user to use a}
-                                         ;   @r{hook to customize the mode.}
-@end group
-@end smallexample
-
 @node Auto Major Mode
 @subsection How Emacs Chooses a Major Mode
 
@@ -1073,104 +801,365 @@ Do not write an @code{interactive} spec in the definition;
 @subsection Generic Modes
 @cindex generic mode
 
-@dfn{Generic modes} are simple major modes with basic support for
-comment syntax and Font Lock mode.  They are primarily useful for
-configuration files.  To define a generic mode, use the macro
-@code{define-generic-mode}.  See the file @file{generic-x.el} for some
-examples of the use of @code{define-generic-mode}.
+  @dfn{Generic modes} are simple major modes with basic support for
+comment syntax and Font Lock mode.  To define a generic mode, use the
+macro @code{define-generic-mode}.  See the file @file{generic-x.el}
+for some examples of the use of @code{define-generic-mode}.
 
 @defmac define-generic-mode mode comment-list keyword-list font-lock-list auto-mode-list function-list &optional docstring
-This macro creates a new generic mode.  The argument @var{mode} (an
-unquoted symbol) is the major mode command.  The optional argument
-@var{docstring} is the documentation for the mode command.  If you do
-not supply it, @code{define-generic-mode} uses a default documentation
-string instead.
-
-@var{comment-list} is a list in which each element is either a
-character, a string of one or two characters, or a cons cell.  A
-character or a string is set up in the mode's syntax table as a
+This macro defines a generic mode command named @var{mode} (a symbol,
+not quoted).  The optional argument @var{docstring} is the
+documentation for the mode command.  If you do not supply it,
+@code{define-generic-mode} generates one by default.
+
+The argument @var{comment-list} is a list in which each element is
+either a character, a string of one or two characters, or a cons cell.
+A character or a string is set up in the mode's syntax table as a
 ``comment starter.''  If the entry is a cons cell, the @sc{car} is set
 up as a ``comment starter'' and the @sc{cdr} as a ``comment ender.''
 (Use @code{nil} for the latter if you want comments to end at the end
-of the line.)  Note that the syntax table has limitations about what
-comment starters and enders are actually possible.  @xref{Syntax
-Tables}.
-
-@var{keyword-list} is a list of keywords to highlight with
-@code{font-lock-keyword-face}.  Each keyword should be a string.
-@var{font-lock-list} is a list of additional expressions to highlight.
-Each element of this list should have the same form as an element of
-@code{font-lock-keywords}.  @xref{Search-based Fontification}.
-
-@var{auto-mode-list} is a list of regular expressions to add to the
-variable @code{auto-mode-alist}.  These regular expressions are added
-when Emacs runs the macro expansion.
-
-@var{function-list} is a list of functions to call to do some
-additional setup.  The mode command calls these functions just before
-it runs the mode hook variable @code{@var{mode}-hook}.
+of the line.)  Note that the syntax table mechanism has limitations
+about what comment starters and enders are actually possible.
+@xref{Syntax Tables}.
+
+The argument @var{keyword-list} is a list of keywords to highlight
+with @code{font-lock-keyword-face}.  Each keyword should be a string.
+Meanwhile, @var{font-lock-list} is a list of additional expressions to
+highlight.  Each element of this list should have the same form as an
+element of @code{font-lock-keywords}.  @xref{Search-based
+Fontification}.
+
+The argument @var{auto-mode-list} is a list of regular expressions to
+add to the variable @code{auto-mode-alist}.  They are added by the execution
+of the @code{define-generic-mode} form, not by expanding the macro call.
+
+Finally, @var{function-list} is a list of functions for the mode
+command to call for additional setup.  It calls these functions just
+before it runs the mode hook variable @code{@var{mode}-hook}.
 @end defmac
 
 @node Mode Hooks
 @subsection Mode Hooks
 
-  The two last things a major mode function should do is run its mode
-hook and finally the mode independent normal hook
-@code{after-change-major-mode-hook}.  If the major mode is a derived
-mode, that is if it calls another major mode (the parent mode) in its
-body, then the parent's mode hook is run just before the derived
-mode's hook.  Neither the parent's mode hook nor
-@code{after-change-major-mode-hook} are run at the end of the actual
-call to the parent mode.  This applies recursively if the parent mode
-has itself a parent.  That is, the mode hooks of all major modes
-called directly or indirectly by the major mode function are all run
-in sequence at the end, just before
-@code{after-change-major-mode-hook}.
-
-  These conventions are new in Emacs 22, and some major modes
-implemented by users do not follow them yet.  So if you put a function
-onto @code{after-change-major-mode-hook}, keep in mind that some modes
-will fail to run it.  If a user complains about that, you can respond,
-``That major mode fails to follow Emacs conventions, and that's why it
-fails to work.  Please fix the major mode.''  In most cases, that is
-good enough, so go ahead and use @code{after-change-major-mode-hook}.
-However, if a certain feature needs to be completely reliable,
-it should not use @code{after-change-major-mode-hook} as of yet.
+  Every major mode function should finish by running its mode hook and
+the mode-independent normal hook @code{after-change-major-mode-hook}.
+It does this by calling @code{run-mode-hooks}.  If the major mode is a
+derived mode, that is if it calls another major mode (the parent mode)
+in its body, it should do this inside @code{delay-mode-hooks} so that
+the parent won't run these hooks itself.  Instead, the derived mode's
+call to @code{run-mode-hooks} runs the parent's mode hook too.
+@xref{Major Mode Conventions}.
+
+  Emacs versions before Emacs 22 did not have @code{delay-mode-hooks}.
+When user-implemented major modes have not been updated to use it,
+they won't entirely follow these conventions: they may run the
+parent's mode hook too early, or fail to run
+@code{after-change-major-mode-hook}.  If you encounter such a major
+mode, please correct it to follow these conventions.
 
   When you defined a major mode using @code{define-derived-mode}, it
 automatically makes sure these conventions are followed.  If you
-define a major mode ``from scratch,'' not using
-@code{define-derived-mode}, make sure the major mode command follows
-these and other conventions.  @xref{Major Mode Conventions}.  You use
-these functions to do it properly.
+define a major mode ``by hand,'' not using @code{define-derived-mode},
+use the following functions to handle these conventions automatically.
 
 @defun run-mode-hooks &rest hookvars
 Major modes should run their mode hook using this function.  It is
 similar to @code{run-hooks} (@pxref{Hooks}), but it also runs
 @code{after-change-major-mode-hook}.
 
-When the call to this function is dynamically inside a
-@code{delay-mode-hooks} form, this function does not run any hooks.
+When this function is called during the execution of a
+@code{delay-mode-hooks} form, it does not run the hooks immediately.
 Instead, it arranges for the next call to @code{run-mode-hooks} to run
-@var{hookvars}.
+them.
 @end defun
 
 @defmac delay-mode-hooks body@dots{}
-This macro executes @var{body} like @code{progn}, but all calls to
-@code{run-mode-hooks} inside @var{body} delay running their hooks.
-They will be run by the first call to @code{run-mode-hooks} after exit
-from @code{delay-mode-hooks}.  This is the proper way for a major mode
-command to invoke its parent mode.
+When one major mode command calls another, it should do so inside of
+@code{delay-mode-hooks}.
+
+This macro executes @var{body}, but tells all @code{run-mode-hooks}
+calls during the execution of @var{body} to delay running their hooks.
+The hooks will actually run during the next call to
+@code{run-mode-hooks} after the end of the @code{delay-mode-hooks}
+construct.
 @end defmac
 
 @defvar after-change-major-mode-hook
-Every major mode function should run this normal hook at its very end.
-It normally does not need to do so explicitly.  Indeed, a major mode
-function should normally run its mode hook with @code{run-mode-hooks}
-as the very last thing it does, and the last thing
-@code{run-mode-hooks} does is run @code{after-change-major-mode-hook}.
+This is a normal hook run by @code{run-mode-hooks}.  It is run at the
+very end of every properly-written major mode function.
 @end defvar
 
+@node Example Major Modes
+@subsection Major Mode Examples
+
+  Text mode is perhaps the simplest mode besides Fundamental mode.
+Here are excerpts from  @file{text-mode.el} that illustrate many of
+the conventions listed above:
+
+@smallexample
+@group
+;; @r{Create the syntax table for this mode.}
+(defvar text-mode-syntax-table
+  (let ((st (make-syntax-table)))
+    (modify-syntax-entry ?\" ".   " st)
+    (modify-syntax-entry ?\\ ".   " st)
+    ;; Add `p' so M-c on `hello' leads to `Hello', not `hello'.
+    (modify-syntax-entry ?' "w p" st)
+    st)
+  "Syntax table used while in `text-mode'.")
+@end group
+
+;; @r{Create the keymap for this mode.}
+@group
+(defvar text-mode-map
+  (let ((map (make-sparse-keymap)))
+    (define-key map "\e\t" 'ispell-complete-word)
+    (define-key map "\es" 'center-line)
+    (define-key map "\eS" 'center-paragraph)
+    map)
+  "Keymap for `text-mode'.
+Many other modes, such as Mail mode, Outline mode
+and Indented Text mode, inherit all the commands
+defined in this map.")
+@end group
+@end smallexample
+
+  Here is how the actual mode command is defined now:
+
+@smallexample
+@group
+(define-derived-mode text-mode nil "Text"
+  "Major mode for editing text written for humans to read.
+In this mode, paragraphs are delimited only by blank or white lines.
+You can thus get the full benefit of adaptive filling
+ (see the variable `adaptive-fill-mode').
+\\@{text-mode-map@}
+Turning on Text mode runs the normal hook `text-mode-hook'."
+@end group
+@group
+  (make-local-variable 'text-mode-variant)
+  (setq text-mode-variant t)
+  ;; @r{These two lines are a feature added recently.}
+  (set (make-local-variable 'require-final-newline)
+       mode-require-final-newline)
+  (set (make-local-variable 'indent-line-function) 'indent-relative))
+@end group
+@end smallexample
+
+  But here is how it was defined formerly, before
+@code{define-derived-mode} existed:
+
+@smallexample
+@group
+;; @r{This isn't needed nowadays, since @code{define-derived-mode} does it.}
+(defvar text-mode-abbrev-table nil
+  "Abbrev table used while in text mode.")
+(define-abbrev-table 'text-mode-abbrev-table ())
+@end group
+
+@group
+(defun text-mode ()
+  "Major mode for editing text intended for humans to read...
+ Special commands: \\@{text-mode-map@}
+@end group
+@group
+Turning on text-mode runs the hook `text-mode-hook'."
+  (interactive)
+  (kill-all-local-variables)
+  (use-local-map text-mode-map)
+@end group
+@group
+  (setq local-abbrev-table text-mode-abbrev-table)
+  (set-syntax-table text-mode-syntax-table)
+@end group
+@group
+  ;; @r{These four lines are absent from the current version}
+  ;; @r{not because this is done some other way, but rather}
+  ;; @r{because nowadays Text mode uses the normal definition of paragraphs.}
+  (make-local-variable 'paragraph-start)
+  (setq paragraph-start (concat "[ \t]*$\\|" page-delimiter))
+  (make-local-variable 'paragraph-separate)
+  (setq paragraph-separate paragraph-start)
+  (make-local-variable 'indent-line-function)
+  (setq indent-line-function 'indent-relative-maybe)
+@end group
+@group
+  (setq mode-name "Text")
+  (setq major-mode 'text-mode)
+  (run-mode-hooks 'text-mode-hook)) ; @r{Finally, this permits the user to}
+                                    ;   @r{customize the mode with a hook.}
+@end group
+@end smallexample
+
+@cindex @file{lisp-mode.el}
+  The three Lisp modes (Lisp mode, Emacs Lisp mode, and Lisp
+Interaction mode) have more features than Text mode and the code is
+correspondingly more complicated.  Here are excerpts from
+@file{lisp-mode.el} that illustrate how these modes are written.
+
+@cindex syntax table example
+@smallexample
+@group
+;; @r{Create mode-specific table variables.}
+(defvar lisp-mode-syntax-table nil "")
+(defvar lisp-mode-abbrev-table nil "")
+@end group
+
+@group
+(defvar emacs-lisp-mode-syntax-table
+  (let ((table (make-syntax-table)))
+    (let ((i 0))
+@end group
+
+@group
+      ;; @r{Set syntax of chars up to @samp{0} to say they are}
+      ;;   @r{part of symbol names but not words.}
+      ;;   @r{(The digit @samp{0} is @code{48} in the @acronym{ASCII} character set.)}
+      (while (< i ?0)
+        (modify-syntax-entry i "_   " table)
+        (setq i (1+ i)))
+      ;; @r{@dots{} similar code follows for other character ranges.}
+@end group
+@group
+      ;; @r{Then set the syntax codes for characters that are special in Lisp.}
+      (modify-syntax-entry ?  "    " table)
+      (modify-syntax-entry ?\t "    " table)
+      (modify-syntax-entry ?\f "    " table)
+      (modify-syntax-entry ?\n ">   " table)
+@end group
+@group
+      ;; @r{Give CR the same syntax as newline, for selective-display.}
+      (modify-syntax-entry ?\^m ">   " table)
+      (modify-syntax-entry ?\; "<   " table)
+      (modify-syntax-entry ?` "'   " table)
+      (modify-syntax-entry ?' "'   " table)
+      (modify-syntax-entry ?, "'   " table)
+@end group
+@group
+      ;; @r{@dots{}likewise for many other characters@dots{}}
+      (modify-syntax-entry ?\( "()  " table)
+      (modify-syntax-entry ?\) ")(  " table)
+      (modify-syntax-entry ?\[ "(]  " table)
+      (modify-syntax-entry ?\] ")[  " table))
+    table))
+@end group
+@group
+;; @r{Create an abbrev table for lisp-mode.}
+(define-abbrev-table 'lisp-mode-abbrev-table ())
+@end group
+@end smallexample
+
+  The three modes for Lisp share much of their code.  For instance,
+each calls the following function to set various variables:
+
+@smallexample
+@group
+(defun lisp-mode-variables (lisp-syntax)
+  (when lisp-syntax
+    (set-syntax-table lisp-mode-syntax-table))
+  (setq local-abbrev-table lisp-mode-abbrev-table)
+  @dots{}
+@end group
+@end smallexample
+
+  In Lisp and most programming languages, we want the paragraph
+commands to treat only blank lines as paragraph separators.  And the
+modes should undestand the Lisp conventions for comments.  The rest of
+@code{lisp-mode-variables} sets this up:
+
+@smallexample
+@group
+  (make-local-variable 'paragraph-start)
+  (setq paragraph-start (concat page-delimiter "\\|$" ))
+  (make-local-variable 'paragraph-separate)
+  (setq paragraph-separate paragraph-start)
+  @dots{}
+@end group
+@group
+  (make-local-variable 'comment-indent-function)
+  (setq comment-indent-function 'lisp-comment-indent))
+  @dots{}
+@end group
+@end smallexample
+
+  Each of the different Lisp modes has a slightly different keymap.  For
+example, Lisp mode binds @kbd{C-c C-z} to @code{run-lisp}, but the other
+Lisp modes do not.  However, all Lisp modes have some commands in
+common.  The following code sets up the common commands:
+
+@smallexample
+@group
+(defvar shared-lisp-mode-map ()
+  "Keymap for commands shared by all sorts of Lisp modes.")
+
+;; @r{Putting this @code{if} after the @code{defvar} is an older style.}
+(if shared-lisp-mode-map
+    ()
+   (setq shared-lisp-mode-map (make-sparse-keymap))
+   (define-key shared-lisp-mode-map "\e\C-q" 'indent-sexp)
+   (define-key shared-lisp-mode-map "\177"
+               'backward-delete-char-untabify))
+@end group
+@end smallexample
+
+@noindent
+And here is the code to set up the keymap for Lisp mode:
+
+@smallexample
+@group
+(defvar lisp-mode-map ()
+  "Keymap for ordinary Lisp mode...")
+
+(if lisp-mode-map
+    ()
+  (setq lisp-mode-map (make-sparse-keymap))
+  (set-keymap-parent lisp-mode-map shared-lisp-mode-map)
+  (define-key lisp-mode-map "\e\C-x" 'lisp-eval-defun)
+  (define-key lisp-mode-map "\C-c\C-z" 'run-lisp))
+@end group
+@end smallexample
+
+  Finally, here is the complete major mode function definition for
+Lisp mode.
+
+@smallexample
+@group
+(defun lisp-mode ()
+  "Major mode for editing Lisp code for Lisps other than GNU Emacs Lisp.
+Commands:
+Delete converts tabs to spaces as it moves back.
+Blank lines separate paragraphs.  Semicolons start comments.
+\\@{lisp-mode-map@}
+Note that `run-lisp' may be used either to start an inferior Lisp job
+or to switch back to an existing one.
+@end group
+
+@group
+Entry to this mode calls the value of `lisp-mode-hook'
+if that value is non-nil."
+  (interactive)
+  (kill-all-local-variables)
+@end group
+@group
+  (use-local-map lisp-mode-map)          ; @r{Select the mode's keymap.}
+  (setq major-mode 'lisp-mode)           ; @r{This is how @code{describe-mode}}
+                                         ;   @r{finds out what to describe.}
+  (setq mode-name "Lisp")                ; @r{This goes into the mode line.}
+  (lisp-mode-variables t)                ; @r{This defines various variables.}
+  (make-local-variable 'comment-start-skip)
+  (setq comment-start-skip
+        "\\(\\(^\\|[^\\\\\n]\\)\\(\\\\\\\\\\)*\\)\\(;+\\|#|\\) *")
+  (make-local-variable 'font-lock-keywords-case-fold-search)
+  (setq font-lock-keywords-case-fold-search t)
+@end group
+@group
+  (setq imenu-case-fold-search t)
+  (set-syntax-table lisp-mode-syntax-table)
+  (run-mode-hooks 'lisp-mode-hook))           ; @r{This permits the user to use a}
+                                         ;   @r{hook to customize the mode.}
+@end group
+@end smallexample
+
 @node Minor Modes
 @section Minor Modes
 @cindex minor mode
@@ -1295,7 +1284,7 @@ check for an existing element, to avoid duplication.  For example:
 @end smallexample
 
 @noindent
-or like this, using @code{add-to-list} (@pxref{Setting Variables}):
+or like this, using @code{add-to-list} (@pxref{List Variables}):
 
 @smallexample
 @group
@@ -1533,16 +1522,14 @@ minor modes.
 @subsection Mode Line Basics
 
   @code{mode-line-format} is a buffer-local variable that holds a
-@dfn{mode line construct}, a kind of template, which controls the
-display the mode line of the current buffer.  All 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.  The value of @code{header-line-format} specifies the
-buffer's header line in the same way, with a mode line construct.
-
-  For efficiency, Emacs does not recompute the mode line and header
-line of a window in every redisplay.  It does so when circumstances
+@dfn{mode line construct}, a kind of template, which controls what is
+displayed on the mode line of the current buffer.  The value of
+@code{header-line-format} specifies the buffer's header line in the
+same way.  All windows for the same buffer use the same
+@code{mode-line-format} and @code{header-line-format}.
+
+  For efficiency, Emacs does not continuously recompute the mode
+line and header line of a window.  It does so when circumstances
 appear to call for it---for instance, if you change the window
 configuration, switch buffers, narrow or widen the buffer, scroll, or
 change the buffer's modification status.  If you modify any of the
@@ -1552,7 +1539,6 @@ 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 &optional all
 Force redisplay of the current buffer's mode line and header line.
 The next redisplay will update the mode line and header line based on
@@ -1589,15 +1575,17 @@ defined to have mode-line constructs as their values.
 @table @code
 @cindex percent symbol in mode line
 @item @var{string}
-A string as a mode-line construct appears verbatim in the mode line
-except for @dfn{@code{%}-constructs} in it.  These stand for
-substitution of other data; see @ref{%-Constructs}.
-
-If the string has @code{face} properties, they are copied into the
-mode line contents too (@pxref{Properties in Mode}).  Any characters
-in the mode line which have no @code{face} properties are displayed,
-by default, in the face @code{mode-line} or @code{mode-line-inactive}
-(@pxref{Standard Faces,,, emacs, The GNU Emacs Manual}).
+A string as a mode-line construct appears verbatim except for
+@dfn{@code{%}-constructs} in it.  These stand for substitution of
+other data; see @ref{%-Constructs}.
+
+If parts of the string have @code{face} properties, they control
+display of the text just as they would text in the buffer.  Any
+characters which have no @code{face} properties are displayed, by
+default, in the face @code{mode-line} or @code{mode-line-inactive}
+(@pxref{Standard Faces,,, emacs, The GNU Emacs Manual}).  The
+@code{help-echo} and @code{local-map} properties in @var{string} have
+special meanings.  @xref{Properties in Mode}.
 
 @item @var{symbol}
 A symbol as a mode-line construct stands for its value.  The value of
@@ -1612,7 +1600,9 @@ Unless @var{symbol} is marked as ``risky'' (i.e., it has a
 non-@code{nil} @code{risky-local-variable} property), all text
 properties specified in @var{symbol}'s value are ignored.  This
 includes the text properties of strings in @var{symbol}'s value, as
-well as all @code{:eval} and @code{:propertize} forms in it.
+well as all @code{:eval} and @code{:propertize} forms in it.  (The
+reason for this is security: non-risky variables could be set
+automatically from file variables without prompting the user.)
 
 @item (@var{string} @var{rest}@dots{})
 @itemx (@var{list} @var{rest}@dots{})
@@ -2055,10 +2045,10 @@ structure, and make @var{form} evaluate to a string that has a text
 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 it is impossible to move point into the mode line.  This
-keymap can only take real effect for mouse clicks.
+  You can use the @code{local-map} property to specify a keymap.  This
+keymap only takes real effect for mouse clicks; binding character keys
+and function keys to it has no effect, since it is impossible to move
+point into the mode line.
 
   When the mode line refers to a variable which does not have a
 non-@code{nil} @code{risky-local-variable} property, any text
@@ -2889,6 +2879,10 @@ Used (typically) for constant names.
 @vindex font-lock-preprocessor-face
 Used (typically) for preprocessor commands.
 
+@item font-lock-negation-char-face
+@vindex font-lock-negation-char-face
+Used (typically) for easily-overlooked negation characters.
+
 @item font-lock-warning-face
 @vindex font-lock-warning-face
 Used (typically) for constructs that are peculiar, or that greatly
@@ -3044,7 +3038,7 @@ closely related, and often getting one of them to work will appear to
 make the other also work.  However, for reliable results you must
 attend explicitly to both aspects.
 
-  There are two ways to ensure correct identification of multiline
+  There are three ways to ensure correct identification of multiline
 constructs:
 
 @itemize
@@ -3055,6 +3049,10 @@ property on the construct when it is added to the buffer.
 Use @code{font-lock-fontify-region-function} hook to extend the scan
 so that the scanned text never starts or ends in the middle of a
 multiline construct.
+@item
+Add a function to @code{font-lock-extend-region-functions} that does
+the @emph{identification} and extends the scan so that the scanned
+text never starts or ends in the middle of a multiline construct.
 @end itemize
 
   There are three ways to do rehighlighting of multiline constructs:
@@ -3144,7 +3142,7 @@ earlier line.
   You can enlarge (or even reduce) the region to fontify by setting
 one the following variables:
 
-@defvar font-lock-extend-region-function
+@defvar font-lock-extend-after-change-region-function
 This buffer-local variable is either @code{nil} or a function for
 Font-Lock to call to determine the region to scan and fontify.
 
diff --git a/lispref/os.texi b/lispref/os.texi
index e3634746988..f6682548e5b 100644
--- a/lispref/os.texi
+++ b/lispref/os.texi
@@ -28,8 +28,10 @@ pertaining to the terminal and the screen.
 * Processor Run Time::  Getting the run time used by Emacs.
 * Time Calculations::   Adding, subtracting, comparing times, etc.
 * 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.
+* Idle Timers::         Setting a timer to call a function when Emacs has
+                          been idle for a certain length of time.
+* Terminal Input::      Accessing and recording terminal input.
+* Terminal Output::     Controlling and recording terminal output.
 * Sound Output::        Playing sounds on the computer's speaker.
 * X11 Keysyms::         Operating on key symbols for X Windows
 * Batch Mode::          Running Emacs without terminal interaction.
@@ -1256,7 +1258,9 @@ This stands for the year without century (00-99).
 @item %Y
 This stands for the year with century.
 @item %Z
-This stands for the time zone abbreviation.
+This stands for the time zone abbreviation (e.g., @samp{EST}).
+@item %z
+This stands for the time zone numerical offset (e.g., @samp{-0500}).
 @end table
 
 You can also specify the field width and type of padding for any of
@@ -1286,12 +1290,14 @@ If @var{universal} is non-@code{nil}, that means to describe the time as
 Universal Time; @code{nil} means describe it using what Emacs believes
 is the local time zone (see @code{current-time-zone}).
 
-This function uses the C library function @code{strftime} to do most of
-the work.  In order to communicate with that function, it first encodes
-its argument using the coding system specified by
-@code{locale-coding-system} (@pxref{Locales}); after @code{strftime}
-returns the resulting string, @code{format-time-string} decodes the
-string using that same coding system.
+This function uses the C library function @code{strftime}
+(@pxref{Formatting Calendar Time,,, libc, The GNU C Library Reference
+Manual}) to do most of the work.  In order to communicate with that
+function, it first encodes its argument using the coding system
+specified by @code{locale-coding-system} (@pxref{Locales}); after
+@code{strftime} returns the resulting string,
+@code{format-time-string} decodes the string using that same coding
+system.
 @end defun
 
 @defun seconds-to-time seconds
@@ -1388,6 +1394,13 @@ both before and after changing the buffer, to separate the timer's
 changes from user commands' changes and prevent a single undo entry
 from growing to be quite large.
 
+  Timer functions should also avoid calling functions that cause Emacs
+to wait, such as @code{sit-for} (@pxref{Waiting}).  This can lead to
+unpredictable effects, since other timers (or even the same timer) can
+run while waiting.  If a timer function needs to perform an action
+after a certain time has elapsed, it can do this by scheduling a new
+timer.
+
   If a timer function calls functions that can change the match data,
 it should save and restore the match data.  @xref{Saving Match Data}.
 
@@ -1469,10 +1482,26 @@ calls one of those primitives.  So use @code{with-timeout} only with a
 a timer to avoid waiting too long for an answer.  @xref{Yes-or-No
 Queries}.
 
+@defun cancel-timer timer
+This cancels the requested action for @var{timer}, which should be a
+timer---usually, one previously returned by @code{run-at-time} or
+@code{run-with-idle-timer}.  This cancels the effect of that call to
+one of these functions; the arrival of the specified time will not
+cause anything special to happen.
+@end defun
+
+@node Idle Timers
+@section Idle Timers
+
+  Here is how to set up a timer that runs when Emacs is idle for a
+certain length of time.  Aside from how to set them up, idle timers
+work just like ordinary timers.
+
 @deffn Command run-with-idle-timer secs repeat function &rest args
 Set up a timer which runs when Emacs has been idle for @var{secs}
 seconds.  The value of @var{secs} may be an integer or a floating point
-number.
+number; a value of the type returned by @code{current-idle-time}
+is also allowed.
 
 If @var{repeat} is @code{nil}, the timer runs just once, the first time
 Emacs remains idle for a long enough time.  More often @var{repeat} is
@@ -1480,7 +1509,7 @@ non-@code{nil}, which means to run the timer @emph{each time} Emacs
 remains idle for @var{secs} seconds.
 
 The function @code{run-with-idle-timer} returns a timer value which you
-can use in calling @code{cancel-timer} (see below).
+can use in calling @code{cancel-timer} (@pxref{Timers}).
 @end deffn
 
 @cindex idleness
@@ -1504,11 +1533,49 @@ minutes, and even if there have been garbage collections and autosaves.
 input.  Then it becomes idle again, and all the idle timers that are
 set up to repeat will subsequently run another time, one by one.
 
-@defun cancel-timer timer
-Cancel the requested action for @var{timer}, which should be a value
-previously returned by @code{run-at-time} or @code{run-with-idle-timer}.
-This cancels the effect of that call to one of these functions; the
-arrival of the specified time will not cause anything special to happen.
+@c Emacs 19 feature
+@defun current-idle-time
+This function returns the length of time Emacs has been idle, 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 of idleness, which is
+@ifnottex
+@var{high} * 2**16 + @var{low}.
+@end ifnottex
+@tex
+$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 with
+the resolution of only one second).
+
+The main use of this function is when an idle timer function wants to
+``take a break'' for a while.  It can set up another idle timer to
+call the same function again, after a few seconds more idleness.
+Here's an example:
+
+@smallexample
+(defvar resume-timer nil
+  "Timer that `timer-function' used to reschedule itself, or nil.")
+
+(defun timer-function ()
+  ;; @r{If the user types a command while @code{resume-timer}}
+  ;; @r{is active, the next time this function is called from}
+  ;; @r{its main idle timer, deactivate @code{resume-timer}.}
+  (when resume-timer
+    (cancel-timer resume-timer))
+  ...@var{do the work for a while}...
+  (when @var{taking-a-break}
+    (setq resume-timer
+          (run-with-idle-timer
+            ;; Compute an idle time @var{break-length}
+            ;; more than the current value.
+            (time-add (current-idle-time)
+                      (seconds-to-time @var{break-length}))
+            nil
+            'timer-function))))
+@end smallexample
 @end defun
 
 @node Terminal Input
@@ -1521,8 +1588,6 @@ functions.
 
 @menu
 * Input Modes::         Options for how input is processed.
-* Translating Input::   Low level conversion of some characters or events
-                          into others.
 * Recording Input::     Saving histories of recent or all input events.
 @end menu
 
@@ -1587,204 +1652,6 @@ is the character Emacs currently uses for quitting, usually @kbd{C-g}.
 @end table
 @end defun
 
-@node Translating Input
-@subsection Translating Input Events
-@cindex translating input events
-
-  This section describes features for translating input events into
-other input events before they become part of key sequences.  These
-features apply to each event in the order they are described here: each
-event is first modified according to @code{extra-keyboard-modifiers},
-then translated through @code{keyboard-translate-table} (if applicable),
-and finally decoded with the specified keyboard coding system.  If it is
-being read as part of a key sequence, it is then added to the sequence
-being read; then subsequences containing it are checked first with
-@code{function-key-map} and then with @code{key-translation-map}.
-
-@c Emacs 19 feature
-@defvar extra-keyboard-modifiers
-This variable lets Lisp programs ``press'' the modifier keys on the
-keyboard.  The value is a character.  Only the modifiers of the
-character matter.  Each time the user types a keyboard key, it is
-altered as if those modifier keys were held down.  For instance, if
-you bind @code{extra-keyboard-modifiers} to @code{?\C-\M-a}, then all
-keyboard input characters typed during the scope of the binding will
-have the control and meta modifiers applied to them.  The character
-@code{?\C-@@}, equivalent to the integer 0, does not count as a control
-character for this purpose, but as a character with no modifiers.
-Thus, setting @code{extra-keyboard-modifiers} to zero cancels any
-modification.
-
-When using a window system, the program can ``press'' any of the
-modifier keys in this way.  Otherwise, only the @key{CTL} and @key{META}
-keys can be virtually pressed.
-
-Note that this variable applies only to events that really come from
-the keyboard, and has no effect on mouse events or any other events.
-@end defvar
-
-@defvar keyboard-translate-table
-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}.
-(It can also be a string or vector, but this is considered obsolete.)
-
-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.
-
-Note that this translation is the first thing that happens to a
-character after it is read from the terminal.  Record-keeping features
-such as @code{recent-keys} and dribble files record the characters after
-translation.
-
-Note also that this translation is done before the characters are
-supplied to input methods (@pxref{Input Methods}).  Use
-@code{translation-table-for-input} (@pxref{Translation of Characters}),
-if you want to translate characters after input methods operate.
-@end defvar
-
-@defun keyboard-translate from to
-This function modifies @code{keyboard-translate-table} to translate
-character code @var{from} into character code @var{to}.  It creates
-the keyboard translate table if necessary.
-@end defun
-
-  Here's an example of using the @code{keyboard-translate-table} to
-make @kbd{C-x}, @kbd{C-c} and @kbd{C-v} perform the cut, copy and paste
-operations:
-
-@example
-(keyboard-translate ?\C-x 'control-x)
-(keyboard-translate ?\C-c 'control-c)
-(keyboard-translate ?\C-v 'control-v)
-(global-set-key [control-x] 'kill-region)
-(global-set-key [control-c] 'kill-ring-save)
-(global-set-key [control-v] 'yank)
-@end example
-
-@noindent
-On a graphical terminal that supports extended @acronym{ASCII} input,
-you can still get the standard Emacs meanings of one of those
-characters by typing it with the shift key.  That makes it a different
-character as far as keyboard translation is concerned, but it has the
-same usual meaning.
-
-  The remaining translation features translate subsequences of key
-sequences being read.  They are implemented in @code{read-key-sequence}
-and have no effect on input read with @code{read-event}.
-
-@defvar function-key-map
-This variable holds a keymap that describes the character sequences sent
-by function keys on an ordinary character terminal.  This keymap has the
-same structure as other keymaps, but is used differently: it specifies
-translations to make while reading key sequences, rather than bindings
-for key sequences.
-
-If @code{function-key-map} ``binds'' a key sequence @var{k} to a vector
-@var{v}, then when @var{k} appears as a subsequence @emph{anywhere} in a
-key sequence, it is replaced with the events in @var{v}.
-
-For example, VT100 terminals send @kbd{@key{ESC} O P} when the
-keypad @key{PF1} key is pressed.  Therefore, we want Emacs to translate
-that sequence of events into the single event @code{pf1}.  We accomplish
-this by ``binding'' @kbd{@key{ESC} O P} to @code{[pf1]} in
-@code{function-key-map}, when using a VT100.
-
-Thus, typing @kbd{C-c @key{PF1}} sends the character sequence @kbd{C-c
-@key{ESC} O P}; later the function @code{read-key-sequence} translates
-this back into @kbd{C-c @key{PF1}}, which it returns as the vector
-@code{[?\C-c pf1]}.
-
-Entries in @code{function-key-map} are ignored if they conflict with
-bindings made in the minor mode, local, or global keymaps.  The intent
-is that the character sequences that function keys send should not have
-command bindings in their own right---but if they do, the ordinary
-bindings take priority.
-
-The value of @code{function-key-map} is usually set up automatically
-according to the terminal's Terminfo or Termcap entry, but sometimes
-those need help from terminal-specific Lisp files.  Emacs comes with
-terminal-specific files for many common terminals; their main purpose is
-to make entries in @code{function-key-map} beyond those that can be
-deduced from Termcap and Terminfo.  @xref{Terminal-Specific}.
-@end defvar
-
-@defvar key-translation-map
-This variable is another keymap used just like @code{function-key-map}
-to translate input events into other events.  It differs from
-@code{function-key-map} in two ways:
-
-@itemize @bullet
-@item
-@code{key-translation-map} goes to work after @code{function-key-map} is
-finished; it receives the results of translation by
-@code{function-key-map}.
-
-@item
-Non-prefix bindings in @code{key-translation-map} override actual key
-bindings.  For example, if @kbd{C-x f} has a non-prefix binding in
-@code{key-translation-map}, that translation takes effect even though
-@kbd{C-x f} also has a key binding in the global map.
-@end itemize
-
-Note however that actual key bindings can have an effect on
-@code{key-translation-map}, even though they are overridden by it.
-Indeed, actual key bindings override @code{function-key-map} and thus
-may alter the key sequence that @code{key-translation-map} receives.
-Clearly, it is better to avoid this type of situation.
-
-The intent of @code{key-translation-map} is for users to map one
-character set to another, including ordinary characters normally bound
-to @code{self-insert-command}.
-@end defvar
-
-@cindex key translation function
-You can use @code{function-key-map} or @code{key-translation-map} for
-more than simple aliases, by using a function, instead of a key
-sequence, as the ``translation'' of a key.  Then this function is called
-to compute the translation of that key.
-
-The key translation function receives one argument, which is the prompt
-that was specified in @code{read-key-sequence}---or @code{nil} if the
-key sequence is being read by the editor command loop.  In most cases
-you can ignore the prompt value.
-
-If the function reads input itself, it can have the effect of altering
-the event that follows.  For example, here's how to define @kbd{C-c h}
-to turn the character that follows into a Hyper character:
-
-@example
-@group
-(defun hyperify (prompt)
-  (let ((e (read-event)))
-    (vector (if (numberp e)
-                (logior (lsh 1 24) e)
-              (if (memq 'hyper (event-modifiers e))
-                  e
-                (add-event-modifier "H-" e))))))
-
-(defun add-event-modifier (string e)
-  (let ((symbol (if (symbolp e) e (car e))))
-    (setq symbol (intern (concat string
-                                 (symbol-name symbol))))
-@end group
-@group
-    (if (symbolp e)
-        symbol
-      (cons symbol (cdr e)))))
-
-(define-key function-key-map "\C-ch" 'hyperify)
-@end group
-@end example
-
-Finally, if you have enabled keyboard character set decoding using
-@code{set-keyboard-coding-system}, decoding is done after the
-translations listed above.  @xref{Terminal I/O Encoding}.  In future
-Emacs versions, character set decoding may be done before the other
-translations.
-
 @node Recording Input
 @subsection Recording Input
 
diff --git a/lispref/processes.texi b/lispref/processes.texi
index a6f43cfa95d..f957ebcac4b 100644
--- a/lispref/processes.texi
+++ b/lispref/processes.texi
@@ -1520,7 +1520,7 @@ text at the end of the entire answer, but nothing before; that's how
 
 If the argument @var{delay-question} is non-nil, delay sending this
 question until the process has finished replying to any previous
-questions.  This produces more reliable results with some processes."
+questions.  This produces more reliable results with some processes.
 
 The return value of @code{tq-enqueue} itself is not meaningful.
 @end defun
diff --git a/lispref/strings.texi b/lispref/strings.texi
index 46c01982f32..17a62b546b4 100644
--- a/lispref/strings.texi
+++ b/lispref/strings.texi
@@ -700,8 +700,8 @@ 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; if they have text properties,
-these are copied into the output also.
+are copied directly into the output, including their text properties,
+if any.
 @end defun
 
 @cindex @samp{%} in format
@@ -719,6 +719,17 @@ For example:
 @end group
 @end example
 
+  Since @code{format} interprets @samp{%} characters as format
+specifications, you should @emph{never} pass an arbitrary string as
+the first argument.  This is particularly true when the string is
+generated by some Lisp code.  Unless the string is @emph{known} to
+never include any @samp{%} characters, pass @code{"%s"}, described
+below, as the first argument, and the string as the second, like this:
+
+@example
+  (format "%s" @var{arbitrary-string})
+@end example
+
   If @var{string} contains more than one format specification, the
 format specifications correspond to successive values from
 @var{objects}.  Thus, the first format specification in @var{string}
diff --git a/lispref/text.texi b/lispref/text.texi
index 898f33443b5..4d2f278bee8 100644
--- a/lispref/text.texi
+++ b/lispref/text.texi
@@ -103,9 +103,9 @@ This function returns the character following point in the current
 buffer.  This is similar to @code{(char-after (point))}.  However, if
 point is at the end of the buffer, then @code{following-char} returns 0.
 
-Remember that point is always between characters, and the terminal
-cursor normally appears over the character following point.  Therefore,
-the character returned by @code{following-char} is the character the
+Remember that point is always between characters, and the cursor
+normally appears over the character following point.  Therefore, the
+character returned by @code{following-char} is the character the
 cursor is over.
 
 In this example, point is between the @samp{a} and the @samp{c}.
@@ -526,16 +526,6 @@ The value returned is @code{nil}.  In an interactive call, @var{count}
 is the numeric prefix argument.
 @end deffn
 
-@deffn Command split-line
-This command splits the current line, moving the portion of the line
-after point down vertically so that it is on the next line directly
-below where it was before.  Whitespace is inserted as needed at the
-beginning of the lower line, using the @code{indent-to} function.
-@code{split-line} returns the position of point.
-
-Programs hardly ever use this function.
-@end deffn
-
 @defvar overwrite-mode
 This variable controls whether overwrite mode is in effect.  The value
 should be @code{overwrite-mode-textual}, @code{overwrite-mode-binary},
@@ -978,8 +968,11 @@ the @var{undo} value.
 @comment  node-name,  next,  previous,  up
 @subsection Functions for Yanking
 
-  @dfn{Yanking} means reinserting an entry of previously killed text
-from the kill ring.  The text properties are copied too.
+  This section describes higher-level commands for yanking, which are
+intended primarily for the user but useful also in Lisp programs.
+Both @code{yank} and @code{yank-pop} honor the
+@code{yank-excluded-properties} variable and @code{yank-handler} text
+property (@pxref{Yanking}).
 
 @deffn Command yank &optional arg
 @cindex inserting killed text
@@ -1213,7 +1206,7 @@ value for @code{kill-ring-max} is 60.
 to the buffer's text so that they can be undone.  (The buffers that
 don't have one are usually special-purpose buffers for which Emacs
 assumes that undoing is not useful.  In particular, any buffer whose
-name begins with a space has its undo recording off by default,
+name begins with a space has its undo recording off by default;
 see @ref{Buffer Names}.)  All the primitives that modify the
 text in the buffer automatically add elements to the front of the undo
 list, which is in the variable @code{buffer-undo-list}.
@@ -1318,8 +1311,7 @@ they're being called for the sake of undoing.
 @defun primitive-undo count list
 This is the basic function for undoing elements of an undo list.
 It undoes the first @var{count} elements of @var{list}, returning
-the rest of @var{list}.  You could write this function in Lisp,
-but it is convenient to have it in C.
+the rest of @var{list}.
 
 @code{primitive-undo} adds elements to the buffer's undo list when it
 changes the buffer.  Undo commands avoid confusion by saving the undo
@@ -1372,7 +1364,9 @@ them back to size limits you can set.  (For this purpose, the ``size''
 of an undo list measures the cons cells that make up the list, plus the
 strings of deleted text.)  Three variables control the range of acceptable
 sizes: @code{undo-limit}, @code{undo-strong-limit} and
-@code{undo-outer-limit}.
+@code{undo-outer-limit}.  In these variables, size is counted as the
+number of bytes occupied, which includes both saved text and other
+data.
 
 @defopt undo-limit
 This is the soft limit for the acceptable size of an undo list.  The
@@ -1392,6 +1386,17 @@ exceeds this limit, Emacs discards the info and displays a warning.
 This is a last ditch limit to prevent memory overflow.
 @end defopt
 
+@defopt undo-ask-before-discard
+If this variable is non-@code{nil}, when the undo info exceeds
+@code{undo-outer-limit}, Emacs asks in the echo area whether to
+discard the info.  The default value is @code{nil}, which means to
+discard it automatically.
+
+This option is mainly intended for debugging.  Garbage collection is
+inhibited while the question is asked, which means that Emacs might
+leak memory if the user waits too long before answering the question.
+@end defopt
+
 @node Filling
 @comment  node-name,  next,  previous,  up
 @section Filling
@@ -1481,8 +1486,6 @@ it.  If the region was made up of many paragraphs, the blank lines
 between paragraphs are removed.  This function justifies as well as
 filling when @var{justify} is non-@code{nil}.
 
-In an interactive call, any prefix argument requests justification.
-
 If @var{nosqueeze} is non-@code{nil}, that means to leave whitespace
 other than line breaks untouched.  If @var{squeeze-after} is
 non-@code{nil}, it specifies a position in the region, and means don't
@@ -1522,6 +1525,11 @@ values are @code{left}, @code{right}, @code{full}, @code{center}, or
 @defun current-justification
 This function returns the proper justification style to use for filling
 the text around point.
+
+This returns the value of the @code{justification} text property at
+point, or the variable @var{default-justification} if there is no such
+text property.  However, it returns @code{nil} rather than @code{none}
+to mean ``don't justify''.
 @end defun
 
 @defopt sentence-end-double-space
@@ -1569,14 +1577,14 @@ newlines'' act as paragraph separators.
 @section Margins for Filling
 
 @defopt fill-prefix
-This buffer-local variable specifies a string of text that appears at
-the beginning
-of normal text lines and should be disregarded when filling them.  Any
-line that fails to start with the fill prefix is considered the start of
-a paragraph; so is any line that starts with the fill prefix followed by
-additional whitespace.  Lines that start with the fill prefix but no
-additional whitespace are ordinary text lines that can be filled
-together.  The resulting filled lines also start with the fill prefix.
+This buffer-local variable, if non-@code{nil}, specifies a string of
+text that appears at the beginning of normal text lines and should be
+disregarded when filling them.  Any line that fails to start with the
+fill prefix is considered the start of a paragraph; so is any line
+that starts with the fill prefix followed by additional whitespace.
+Lines that start with the fill prefix but no additional whitespace are
+ordinary text lines that can be filled together.  The resulting filled
+lines also start with the fill prefix.
 
 The fill prefix follows the left margin whitespace, if any.
 @end defopt
@@ -1661,12 +1669,11 @@ becomes buffer-local when set in any fashion.
 
 @defvar fill-nobreak-predicate
 This variable gives major modes a way to specify not to break a line
-at certain places.  Its value should be a list of functions, but a
-single function is also supported for compatibility.  Whenever filling
-considers breaking the line at a certain place in the buffer, it calls
-each of these functions with no arguments and with point located at
-that place.  If any of the functions returns non-@code{nil}, then the
-line won't be broken there.
+at certain places.  Its value should be a list of functions.  Whenever
+filling considers breaking the line at a certain place in the buffer,
+it calls each of these functions with no arguments and with point
+located at that place.  If any of the functions returns
+non-@code{nil}, then the line won't be broken there.
 @end defvar
 
 @node Adaptive Fill
@@ -1733,7 +1740,7 @@ Adaptive Fill mode matches this regular expression against the text
 starting after the left margin whitespace (if any) on a line; the
 characters it matches are that line's candidate for the fill prefix.
 
-@w{@code{"[ \t]*\\([-|#;>*]+[ \t]*\\|(?[0-9]+[.)][ \t]*\\)*"}} is the
+@w{@code{"[ \t]*\\([-!|#%;>*·•‣⁃◦]+[ \t]*\\|(?[0-9]+[.)][ \t]*\\)*"}} is the
 default value.  This matches a number enclosed in parentheses or
 followed by a period, or certain punctuation characters, or any
 sequence of these intermingled with whitespace.  In particular, it
@@ -1898,7 +1905,8 @@ the sort order."
     (save-restriction
       (narrow-to-region beg end)
       (goto-char (point-min))
-      (sort-subr reverse 'forward-line 'end-of-line))))
+      (let ((inhibit-field-text-motion t))
+        (sort-subr reverse 'forward-line 'end-of-line)))))
 @end group
 @end example
 
@@ -2054,9 +2062,12 @@ One unusual thing about this command is that the entire line
 containing position @var{beg}, and the entire line containing position
 @var{end}, are included in the region sorted.
 
-Note that @code{sort-columns} uses the @code{sort} utility program,
-and so cannot work properly on text containing tab characters.  Use
-@kbd{M-x untabify} to convert tabs to spaces before sorting.
+Note that @code{sort-columns} rejects text that contains tabs, because
+tabs could be split across the specified columns.  Use @kbd{M-x
+untabify} to convert tabs to spaces before sorting.
+
+When possible, this command actually works by calling the @code{sort}
+utility program.
 @end deffn
 
 @node Columns
@@ -2391,6 +2402,7 @@ spaces and tab characters to reach the next tab stop column; it does not
 affect the display of tab characters in the buffer (@pxref{Usual
 Display}).  Note that the @key{TAB} character as input uses this tab
 stop feature only in a few major modes, such as Text mode.
+@xref{Tab Stops,,, emacs, The GNU Emacs Manual}.
 
 @deffn Command tab-to-tab-stop
 This command inserts spaces or tabs before point, up to the next tab
@@ -3079,22 +3091,23 @@ This feature is used in the mode line and for other active text.
 @cindex keymap of character
 @kindex keymap @r{(text property)}
 The @code{keymap} property specifies an additional keymap for
-commands.  The property's value for the character before point applies
-if it is non-@code{nil} and rear-sticky, and the property's value for
-the character after point applies if it is non-@code{nil} and
+commands.  When this keymap applies, it is used for key lookup before
+the minor mode keymaps and before the buffer's local map.
+@xref{Active Keymaps}.  If the property value is a symbol, the
+symbol's function definition is used as the keymap.
+
+The property's value for the character before point applies if it is
+non-@code{nil} and rear-sticky, and the property's value for the
+character after point applies if it is non-@code{nil} and
 front-sticky.  (For mouse clicks, the position of the click is used
-instead of the position of point.)  If the property value is a symbol,
-the symbol's function definition is used as the keymap.
-
-When this keymap applies, it is used for key lookup before the minor
-mode keymaps and before the buffer's local map.  @xref{Active
-Keymaps}.
+instead of the position of point.)
 
 @item local-map
 @kindex local-map @r{(text property)}
 This property works like @code{keymap} except that it specifies a
 keymap to use @emph{instead of} the buffer's local map.  For most
-purposes (perhaps all purposes), the @code{keymap} is superior.
+purposes (perhaps all purposes), it is better to use the @code{keymap}
+property.
 
 @item syntax-table
 The @code{syntax-table} property overrides what the syntax table says
@@ -3479,26 +3492,39 @@ being called over and over for the same text.
 @subsection Defining Clickable Text
 @cindex clickable text
 
-  There are two parts of setting up @dfn{clickable text} in a buffer:
-(1) to make that text highlight when the mouse moves over it, and (2)
-to make a mouse button do something when you click on that text.
+  @dfn{Clickable text} is text that can be clicked, with either the
+the mouse or via keyboard commands, to produce some result.  Many
+major modes use clickable text to implement features such as
+hyper-links.  The @code{button} package provides an easy way to insert
+and manipulate clickable text.  @xref{Buttons}.
+
+  In this section, we will explain how to manually set up clickable
+text in a buffer using text properties.  This involves two things: (1)
+indicating clickability when the mouse moves over the text, and (2)
+making @kbd{RET} or a mouse click on that text do something.
 
-  For highlighting, use the @code{mouse-face} text property.  Here is
-an example of how Dired does it:
+  Indicating clickability usually involves highlighting the text, and
+often involves displaying helpful information about the action, such
+as which mouse button to press, or a short summary of the action.
+This can be done with the @code{mouse-face} and @code{help-echo}
+text properties.  @xref{Special Properties}.
+Here is an example of how Dired does it:
 
 @smallexample
 (condition-case nil
     (if (dired-move-to-filename)
-        (put-text-property (point)
-                           (save-excursion
-                             (dired-move-to-end-of-filename)
-                             (point))
-                           'mouse-face 'highlight))
+        (add-text-properties
+         (point)
+         (save-excursion
+           (dired-move-to-end-of-filename)
+           (point))
+         '(mouse-face highlight
+           help-echo "mouse-2: visit this file in other window")))
   (error nil))
 @end smallexample
 
 @noindent
-The first two arguments to @code{put-text-property} specify the
+The first two arguments to @code{add-text-properties} specify the
 beginning and end of the text.
 
   The usual way to make the mouse do something when you click it
@@ -3508,24 +3534,34 @@ is done by the command definition.  Here is how Dired does it:
 
 @smallexample
 (defun dired-mouse-find-file-other-window (event)
-  "In dired, visit the file or directory name you click on."
+  "In Dired, visit the file or directory name you click on."
   (interactive "e")
-  (let (file)
+  (let (window pos file)
     (save-excursion
-      (set-buffer (window-buffer (posn-window (event-end event))))
-      (save-excursion
-        (goto-char (posn-point (event-end event)))
-        (setq file (dired-get-filename))))
-    (select-window (posn-window (event-end event)))
-    (find-file-other-window (file-name-sans-versions file t))))
+      (setq window (posn-window (event-end event))
+            pos (posn-point (event-end event)))
+      (if (not (windowp window))
+          (error "No file chosen"))
+      (set-buffer (window-buffer window))
+      (goto-char pos)
+      (setq file (dired-get-file-for-visit)))
+    (if (file-directory-p file)
+        (or (and (cdr dired-subdir-alist)
+                 (dired-goto-subdir file))
+            (progn
+              (select-window window)
+              (dired-other-window file)))
+      (select-window window)
+      (find-file-other-window (file-name-sans-versions file t)))))
 @end smallexample
 
 @noindent
-The reason for the outer @code{save-excursion} construct is to avoid
-changing the current buffer; the reason for the inner one is to avoid
-permanently altering point in the buffer you click on.  In this case,
-Dired uses the function @code{dired-get-filename} to determine which
-file to visit, based on the position found in the event.
+The reason for the @code{save-excursion} construct is to avoid
+changing the current buffer.  In this case,
+Dired uses the functions @code{posn-window} and @code{posn-point}
+to determine which buffer the click happened in and where, and
+in that buffer, @code{dired-get-file-for-visit} to determine which
+file to visit.
 
   Instead of defining a mouse command for the major mode, you can define
 a key binding for the clickable text itself, using the @code{keymap}
@@ -3697,7 +3733,8 @@ field nor the following field; the field functions treat it as belonging
 to an empty field whose beginning and end are both at @var{pos}.
 
   In all of these functions, if @var{pos} is omitted or @code{nil}, the
-value of point is used by default.
+value of point is used by default.  If narrowing is in effect, then
+@var{pos} should fall within the accessible portion.  @xref{Narrowing}.
 
 @defun field-beginning &optional pos escape-from-edge limit
 This function returns the beginning of the field specified by @var{pos}.