Merge from emacs--devo--0

Patches applied:

 * emacs--devo--0  (patch 382-398)

   - Update from CVS
   - Update from erc--emacs--22
   - Fix ERC bug introduced in last patch
   - Merge from gnus--rel--5.10

 * gnus--rel--5.10  (patch 123-125)

   - Update from CVS

Revision: emacs@sv.gnu.org/emacs--unicode--0--patch-101

8 files changed, 622 insertions, 507 deletions

diff --git a/lispref/ChangeLog b/lispref/ChangeLog
index f64f9eb56df..d09689ce637 100644
--- a/lispref/ChangeLog
+++ b/lispref/ChangeLog
@@ -1,3 +1,62 @@
+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.
@@ -290,7 +349,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>
 
@@ -367,7 +426,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>
@@ -679,7 +738,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>
@@ -1724,7 +1783,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'.
@@ -2974,7 +3033,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>
@@ -3203,7 +3262,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
@@ -3530,7 +3589,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>
 
@@ -3566,7 +3625,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.
@@ -4593,7 +4652,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>
 
@@ -5123,7 +5182,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/commands.texi b/lispref/commands.texi
index 8e34fe360bf..2a091524bed 100644
--- a/lispref/commands.texi
+++ b/lispref/commands.texi
@@ -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{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
diff --git a/lispref/customize.texi b/lispref/customize.texi
index e3e78c46bb4..9e10e547b56 100644
--- a/lispref/customize.texi
+++ b/lispref/customize.texi
@@ -251,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
@@ -406,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/keymaps.texi b/lispref/keymaps.texi
index 44b92ddfcb8..13f4550a082 100644
--- a/lispref/keymaps.texi
+++ b/lispref/keymaps.texi
@@ -2016,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
@@ -2140,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/modes.texi b/lispref/modes.texi
index 38227633c6b..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
@@ -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
@@ -3057,7 +3051,7 @@ 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
+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
 
diff --git a/lispref/os.texi b/lispref/os.texi
index 30f66889387..ab277afdce6 100644
--- a/lispref/os.texi
+++ b/lispref/os.texi
@@ -1256,7 +1256,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 +1288,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
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 08e55f18f05..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,9 +3492,16 @@ 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 indicate clickability when the mouse moves over the text, 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.
 
   Indicating clickability usually involves highlighting the text, and
 often involves displaying helpful information about the action, such