Merge from trunk.

13 files changed, 267 insertions, 454 deletions

diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog
index 58b98189e29..2407d7dd18f 100644
--- a/doc/emacs/ChangeLog
+++ b/doc/emacs/ChangeLog
@@ -1,3 +1,7 @@
+2011-08-29  Chong Yidong  <cyd@stupidchicken.com>
+
+        * modes.texi (Choosing Modes): auto-mode-case-fold is now t.
+
 2011-08-28  Chong Yidong  <cyd@stupidchicken.com>
 
         * files.texi (File Archives):
diff --git a/doc/emacs/modes.texi b/doc/emacs/modes.texi
index 314d5d4347e..d82423a73b4 100644
--- a/doc/emacs/modes.texi
+++ b/doc/emacs/modes.texi
@@ -353,12 +353,13 @@ the element has the form @code{(@var{regexp} @var{mode-function}
 @var{regexp} and searches the list again for another match.
 
 @vindex auto-mode-case-fold
-  On systems with case-insensitive file names, such as Microsoft
-Windows, Emacs performs a single case-insensitive search through
-@code{auto-mode-alist}.  On other systems, Emacs normally performs a
-single case-sensitive search through the alist.  However, if you
-change the variable @code{auto-mode-case-fold} to @code{t}, Emacs
-performs a second case-insensitive search if the first search fails.
+  On GNU/Linux and other systems with case-sensitive file names, Emacs
+performs a case-sensitive search through @code{auto-mode-alist}; if
+this search fails, it performs a second case-insensitive search
+through the alist.  To suppress the second search, change the variable
+@code{auto-mode-case-fold} to @code{nil}.  On systems with
+case-insensitive file names, such as Microsoft Windows, Emacs performs
+a single case-insensitive search through @code{auto-mode-alist}.
 
 @vindex magic-fallback-mode-alist
   Finally, if Emacs @emph{still} hasn't found a major mode to use, it
diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index aae0be5a054..57dde5ac4cb 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,10 @@
+2011-08-29  Chong Yidong  <cyd@stupidchicken.com>
+
+        * modes.texi (Basic Major Modes): New node.  Callers updated.
+        (Major Modes): Document fundamental-mode and major-mode.
+        (Major Mode Basics): Node deleted; text moved to Major Modes.
+        (Derived Modes): Document derived-mode-p.
+
 2011-08-28  Chong Yidong  <cyd@stupidchicken.com>
 
         * files.texi (Changing Files, Create/Delete Dirs): Document new
diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi
index bb05f1b4a0b..a19af903027 100644
--- a/doc/lispref/elisp.texi
+++ b/doc/lispref/elisp.texi
@@ -765,8 +765,7 @@ Major and Minor Modes
 * Major Modes::        Defining major modes.
 * Minor Modes::        Defining minor modes.
 * Mode Line Format::   Customizing the text that appears in the mode line.
-* Imenu::              How a mode can provide a menu
-                         of definitions in the buffer.
+* Imenu::              Providing a menu of definitions made in a buffer.
 * Font Lock Mode::     How modes can highlight text according to syntax.
 * Desktop Save Mode::  How modes can have buffer state saved between
                          Emacs sessions.
@@ -778,12 +777,12 @@ Hooks
 
 Major Modes
 
-* Major Mode Basics::
 * Major Mode Conventions::  Coding conventions for keymaps, etc.
 * 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
                               mode.
+* Basic Major Modes::       Modes that other modes are often derived from.
 * 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.
diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index a354265b365..586fc0bbbfb 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -19,16 +19,15 @@ user.  For related topics such as keymaps and syntax tables, see
 @ref{Keymaps}, and @ref{Syntax Tables}.
 
 @menu
-* Hooks::                       How to use hooks; how to write code that provides hooks.
-* Major Modes::                 Defining major modes.
-* Minor Modes::                 Defining minor modes.
-* Mode Line Format::            Customizing the text that appears in the mode line.
-* Imenu::                       How a mode can provide a menu
-                         of definitions in the buffer.
-* Font Lock Mode::              How modes can highlight text according to syntax.
-* Auto-Indentation::            How to teach Emacs to indent for a major mode.
-* Desktop Save Mode::           How modes can have buffer state saved between
-                         Emacs sessions.
+* Hooks::             How to use hooks; how to write code that provides hooks.
+* Major Modes::       Defining major modes.
+* Minor Modes::       Defining minor modes.
+* Mode Line Format::  Customizing the text that appears in the mode line.
+* Imenu::             Providing a menu of definitions made in a buffer.
+* Font Lock Mode::    How modes can highlight text according to syntax.
+* Auto-Indentation::  How to teach Emacs to indent for a major mode.
+* Desktop Save Mode:: How modes can have buffer state saved between
+                        Emacs sessions.
 @end menu
 
 @node Hooks
@@ -48,12 +47,12 @@ 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
+  Every major mode command 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}).
 
@@ -78,8 +77,8 @@ convention.
 its value is just a single function, not a list of functions.
 
 @menu
-* Running Hooks::               How to run a hook.
-* Setting Hooks::               How to put functions on a hook, or remove them.
+* Running Hooks::    How to run a hook.
+* Setting Hooks::    How to put functions on a hook, or remove them.
 @end menu
 
 @node Running Hooks
@@ -195,115 +194,98 @@ from the buffer-local hook list instead of from the global hook list.
 @section Major Modes
 @cindex major mode
 
+@cindex major mode command
   Major modes specialize Emacs for editing particular kinds of text.
-Each buffer has only one major mode at a time.  For each major mode
-there is a function to switch to that mode in the current buffer; its
-name should end in @samp{-mode}.  These functions work by setting
-buffer-local variable bindings and other data associated with the
-buffer, such as a local keymap.  The effect lasts until you switch
-to another major mode in the same buffer.
+Each buffer has one major mode at a time.  Every major mode is
+associated with a @dfn{major mode command}, whose name should end in
+@samp{-mode}.  This command takes care of switching to that mode in the
+current buffer, by setting various buffer-local variables such as a
+local keymap.  @xref{Major Mode Conventions}.
+
+  The least specialized major mode is called @dfn{Fundamental mode},
+which has no mode-specific definitions or variable settings.
+
+@deffn Command fundamental-mode
+This is the major mode command for Fundamental mode.  Unlike other mode
+commands, it does @emph{not} run any mode hooks (@pxref{Major Mode
+Conventions}), since you are not supposed to customize this mode.
+@end deffn
+
+  The easiest way to write a major mode is to use the macro
+@code{define-derived-mode}, which sets up the new mode as a variant of
+an existing major mode.  @xref{Derived Modes}.  We recommend using
+@code{define-derived-mode} even if the new mode is not an obvious
+derivative of another mode, as it automatically enforces many coding
+conventions for you.  @xref{Basic Major Modes}, for common modes to
+derive from.
+
+  The standard GNU Emacs Lisp directory tree contains the code for
+several major modes, in files such as @file{text-mode.el},
+@file{texinfo.el}, @file{lisp-mode.el}, and @file{rmail.el}.  You can
+study these libraries to see how modes are written.
+
+@defopt major-mode
+The buffer-local value of this variable is a symbol naming the buffer's
+current major mode.  Its default value holds the default major mode for
+new buffers.  The standard default value is @code{fundamental-mode}.
+
+If the default value is @code{nil}, then whenever Emacs creates a new
+buffer via a command such as @kbd{C-x b} (@code{switch-to-buffer}), the
+new buffer is put in the major mode of the previously current buffer.
+As an exception, if the major mode of the previous buffer has a
+@code{mode-class} symbol property with value @code{special}, the new
+buffer is put in Fundamental mode (@pxref{Major Mode Conventions}).
+@end defopt
 
 @menu
-* Major Mode Basics::           
-* Major Mode Conventions::      Coding conventions for keymaps, etc.
-* 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
+* Major Mode Conventions::  Coding conventions for keymaps, etc.
+* 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
                               mode.
-* Generic Modes::               Defining a simple major mode that supports
+* Basic Major Modes::       Modes that other modes are often derived from.
+* 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.
+* Mode Hooks::              Hooks run at the end of major mode commands.
+* Example Major Modes::     Text mode and Lisp modes.
 @end menu
 
-@node Major Mode Basics
-@subsection Major Mode Basics
-@cindex Fundamental mode
-
-  The least specialized major mode is called @dfn{Fundamental mode}.
-This mode has no mode-specific definitions or variable settings, so each
-Emacs command behaves in its default manner, and each option is in its
-default state.  All other major modes redefine various keys and options.
-For example, Lisp Interaction mode provides special key bindings for
-@kbd{C-j} (@code{eval-print-last-sexp}), @key{TAB}
-(@code{lisp-indent-line}), and other keys.
-
-  When you need to write several editing commands to help you perform a
-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 use the @code{define-derived-mode}
-macro 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,
-we recommend to use @code{define-derived-mode}, since it automatically
-enforces the most important coding conventions for you.
-
-  For a very simple programming language major mode that handles
-comments and fontification, you can use @code{define-generic-mode}.
-@xref{Generic Modes}.
-
-  Rmail Edit mode offers an example of changing the major mode
-temporarily for a buffer, so it can be edited in a different way (with
-ordinary Emacs commands rather than Rmail commands).  In such cases, the
-temporary major mode usually provides a command to switch back to the
-buffer's usual mode (Rmail mode, in this case).  You might be tempted to
-present the temporary redefinitions inside a recursive edit and restore
-the usual ones when the user exits; but this is a bad idea because it
-constrains the user's options when it is done in more than one buffer:
-recursive edits must be exited most-recently-entered first.  Using an
-alternative major mode avoids this limitation.  @xref{Recursive
-Editing}.
-
-  The standard GNU Emacs Lisp library directory tree contains the code
-for several major modes, in files such as @file{text-mode.el},
-@file{texinfo.el}, @file{lisp-mode.el}, @file{c-mode.el}, and
-@file{rmail.el}.  They are found in various subdirectories of the
-@file{lisp} directory.  You can study these libraries to see how modes
-are written.  Text mode is perhaps the simplest major mode aside from
-Fundamental mode.  Rmail mode is a complicated and specialized mode.
-
 @node Major Mode Conventions
 @subsection Major Mode Conventions
 @cindex major mode conventions
 @cindex conventions for writing major modes
 
-  The code for existing major modes follows various coding conventions,
-including conventions for local keymap and syntax table initialization,
-global names, and hooks.  Please follow these conventions when you
-define a new major mode.  (Fundamental mode is an exception to many
-of these conventions, because its definition is to present the global
-state of Emacs.)
+  The code for every major mode should follow various coding
+conventions, including conventions for local keymap and syntax table
+initialization, function and variable names, and hooks.
+
+  If you use the @code{define-derived-mode} macro, it will take care of
+many of these conventions automatically.  @xref{Derived Modes}.  Note
+also that fundamental mode is an exception to many of these conventions,
+because its definition is to present the global state of Emacs.
 
-  This list of conventions is only partial, because each major mode
-should aim for consistency in general with other Emacs major modes.
-This makes Emacs as a whole more coherent.  It is impossible to list
+  The following list of conventions is only partial.  Each major mode
+should aim for consistency in general with other Emacs major modes, as
+this makes Emacs as a whole more coherent.  It is impossible to list
 here all the possible points where this issue might come up; if the
 Emacs developers point out an area where your major mode deviates from
 the usual conventions, please make it compatible.
 
 @itemize @bullet
 @item
-Define a command whose name ends in @samp{-mode}, with no arguments,
-that switches to the new mode in the current buffer.  This command
-should set up the keymap, syntax table, and buffer-local variables in an
-existing buffer, without changing the buffer's contents.
+Define a major mode command whose name ends in @samp{-mode}.  When
+called with no arguments, this command should switch to the new mode in
+the current buffer by setting up the keymap, syntax table, and
+buffer-local variables in an existing buffer.  It should not change the
+buffer's contents.
 
 @item
-Write a documentation string for this command that describes the
-special commands available in this mode.  @kbd{C-h m}
-(@code{describe-mode}) in your mode will display this string.
+Write a documentation string for this command that describes the special
+commands available in this mode.  @xref{Mode Help}.
 
 The documentation string may include the special documentation
 substrings, @samp{\[@var{command}]}, @samp{\@{@var{keymap}@}}, and
-@samp{\<@var{keymap}>}, which enable the documentation to adapt
+@samp{\<@var{keymap}>}, which allow the help display to adapt
 automatically to the user's own key bindings.  @xref{Keys in
 Documentation}.
 
@@ -527,10 +509,9 @@ mode when creating new buffers (@pxref{Auto Major Mode}), but with such
 Dired, Rmail, and Buffer List use this feature.
 
 The @code{define-derived-mode} macro automatically marks the derived
-mode as special if the parent mode is special.  The special mode
-@code{special-mode} provides a convenient parent for other special
-modes to inherit from; it sets @code{buffer-read-only} to @code{t},
-and does little else.
+mode as special if the parent mode is special.  Special mode is a
+convenient parent for such modes to inherit from; @xref{Basic Major
+Modes}.
 
 @item
 If you want to make the new mode the default for files with certain
@@ -564,16 +545,6 @@ Even if you never load the file more than once, someone else will.
 automatically selects a major mode for the new buffer when a file is
 visited.  It also processes local variables specified in the file text.
 
-@deffn Command fundamental-mode
-  Fundamental mode is a major mode that is not specialized for anything
-in particular.  Other major modes are defined in effect by comparison
-with this one---their definitions say what to change, starting from
-Fundamental mode.  The @code{fundamental-mode} function does @emph{not}
-run any mode hooks; you're not supposed to customize it.  (If you want Emacs
-to behave differently in Fundamental mode, change the @emph{global}
-state of Emacs.)
-@end deffn
-
 @deffn Command normal-mode &optional find-file
 This function establishes the proper major mode and buffer-local variable
 bindings for the current buffer.  First it calls @code{set-auto-mode}
@@ -599,23 +570,22 @@ by the default value of @code{major-mode} (see below).
 
 @cindex file mode specification error
 @code{normal-mode} uses @code{condition-case} around the call to the
-major mode function, so errors are caught and reported as a @samp{File
-mode specification error},  followed by the original error message.
+major mode command, so errors are caught and reported as a @samp{File
+mode specification error}, followed by the original error message.
 @end deffn
 
 @defun set-auto-mode &optional keep-mode-if-same
 @cindex visited file mode
   This function selects the major mode that is appropriate for the
-current buffer.  It bases its decision (in order of precedence) on
-the @w{@samp{-*-}} line, on any @samp{mode:} local variable near the
-end of a file, on the @w{@samp{#!}} line (using
-@code{interpreter-mode-alist}), on the text at the beginning of the
-buffer (using @code{magic-mode-alist}), and finally on the visited
-file name (using @code{auto-mode-alist}).  @xref{Choosing Modes, , How
-Major Modes are Chosen, emacs, The GNU Emacs Manual}. 
-If @code{enable-local-variables} is @code{nil}, @code{set-auto-mode}
-does not check the @w{@samp{-*-}} line, or near the end of the file,
-for any mode tag.
+current buffer.  It bases its decision (in order of precedence) on the
+@w{@samp{-*-}} line, on any @samp{mode:} local variable near the end of
+a file, on the @w{@samp{#!}} line (using @code{interpreter-mode-alist}),
+on the text at the beginning of the buffer (using
+@code{magic-mode-alist}), and finally on the visited file name (using
+@code{auto-mode-alist}).  @xref{Choosing Modes, , How Major Modes are
+Chosen, emacs, The GNU Emacs Manual}.  If @code{enable-local-variables}
+is @code{nil}, @code{set-auto-mode} does not check the @w{@samp{-*-}}
+line, or near the end of the file, for any mode tag.
 
 If @var{keep-mode-if-same} is non-@code{nil}, this function does not
 call the mode command if the buffer is already in the proper major
@@ -624,21 +594,6 @@ mode.  For instance, @code{set-visited-file-name} sets this to
 have set.
 @end defun
 
-@defopt major-mode
-The buffer-local value of this variable holds the major mode
-currently active.  The default value of this variable holds the
-default major mode for new buffers.  The standard default value is
-@code{fundamental-mode}.
-
-If the default value of @code{major-mode} is @code{nil}, Emacs uses
-the (previously) current buffer's major mode as the default major mode
-of a new buffer.  However, if that major mode symbol has a @code{mode-class}
-property with value @code{special}, then it is not used for new buffers;
-Fundamental mode is used instead.  The modes that have this property are
-those such as Dired and Rmail that are useful only with text that has
-been specially prepared.
-@end defopt
-
 @defun set-buffer-major-mode buffer
 This function sets the major mode of @var{buffer} to the default value of
 @code{major-mode}; if that is @code{nil}, it uses the
@@ -745,18 +700,17 @@ init file.)
 @cindex help for major mode
 @cindex documentation for major mode
 
-  The @code{describe-mode} function is used to provide information
-about major modes.  It is normally called with @kbd{C-h m}.  The
-@code{describe-mode} function uses the value of @code{major-mode},
-which is why every major mode function needs to set the
-@code{major-mode} variable.
+  The @code{describe-mode} function is provides information about major
+modes.  It is normally bound to @kbd{C-h m}.  It uses the value of the
+variable @code{major-mode} (which is why every major mode command needs
+to set this variable).
 
 @deffn Command describe-mode
 This function displays the documentation of the current major mode.
 
 The @code{describe-mode} function calls the @code{documentation}
 function using the value of @code{major-mode} as an argument.  Thus, it
-displays the documentation string of the major mode function.
+displays the documentation string of the major mode command.
 (@xref{Accessing Documentation}.)
 @end deffn
 
@@ -772,11 +726,12 @@ documentation of the major mode.
 @subsection Defining Derived Modes
 @cindex derived mode
 
-  The recommended way to define a new major mode is to derive it
-from an existing one using @code{define-derived-mode}.  If there is no
-closely related mode, you can inherit from @code{text-mode},
-@code{special-mode}, @code{prog-mode}, or in the worst case
-@code{fundamental-mode}.
+  The recommended way to define a new major mode is to derive it from an
+existing one using @code{define-derived-mode}.  If there is no closely
+related mode, you should inherit from either @code{text-mode},
+@code{special-mode}, or @code{prog-mode}.  @xref{Basic Major Modes}.  If
+none of these are suitable, you can inherit from @code{fundamental-mode}
+(@pxref{Major Modes}).
 
 @defmac define-derived-mode variant parent name docstring keyword-args@dots{} body@dots{}
 This macro defines @var{variant} as a major mode command, using
@@ -877,6 +832,64 @@ Do not write an @code{interactive} spec in the definition;
 @code{define-derived-mode} does that automatically.
 @end defmac
 
+@defun derived-mode-p &rest modes
+This function returns non-@code{nil} if the current major mode is
+derived from any of the major modes given by the symbols @var{modes}.
+@end defun
+
+@node Basic Major Modes
+@subsection Basic Major Modes
+
+  Apart from Fundamental mode, there are three major modes that other
+major modes commonly derive from: Text mode, Prog mode, and Special
+mode.  While Text mode is useful in its own right (e.g. for editing
+files ending in @file{.txt}), Prog mode and Special mode exist mainly to
+let other modes derive from them.
+
+@vindex prog-mode-hook
+  As far as possible, new major modes should be derived, either directly
+or indirectly, from one of these three modes.  One reason is that this
+allows users to customize a single mode hook
+(e.g. @code{prog-mode-hook}) for an entire family of relevant modes
+(e.g. all programming language modes).
+
+@deffn Command text-mode
+Text mode is a major mode for editing human languages.  It defines the
+@samp{"} and @samp{\} characters as having punctuation syntax
+(@pxref{Syntax Class Table}), and binds @kbd{M-@key{TAB}} to
+@code{ispell-complete-word} (@pxref{Spelling,,, emacs, The GNU Emacs
+Manual}).
+
+An example of a major mode derived from Text mode is HTML mode.
+@xref{HTML Mode,,SGML and HTML Modes, emacs, The GNU Emacs Manual}.
+@end deffn
+
+@deffn Command prog-mode
+Prog mode is a basic major mode for buffers containing programming
+language source code.  Most of the programming language major modes
+built into Emacs are derived from it.
+
+Prog mode binds @code{parse-sexp-ignore-comments} to @code{t}
+(@pxref{Motion via Parsing}) and @code{bidi-paragraph-direction} to
+@code{left-to-right} (@pxref{Bidirectional Display}).
+@end deffn
+
+@deffn Command special-mode
+Special mode is a basic major mode for buffers containing text that is
+produced specially by Emacs, rather than from a file.  Major modes
+derived from Special mode are given a @code{mode-class} property of
+@code{special} (@pxref{Major Mode Conventions}).
+
+Special mode sets the buffer to read-only.  Its keymap defines several
+common bindings, including @kbd{q} for @code{quit-window}, @kbd{z} for
+@code{kill-this-buffer}, and @kbd{g} for @code{revert-buffer}
+(@pxref{Reverting}).
+
+An example of a major mode derived from Special mode is Buffer Menu
+mode, which is used by the @samp{*Buffer List*} buffer.  @xref{List
+Buffers,,Listing Existing Buffers, emacs, The GNU Emacs Manual}.
+@end deffn
+
 @node Generic Modes
 @subsection Generic Modes
 @cindex generic mode
@@ -921,7 +934,7 @@ before it runs the mode hook variable @code{@var{mode}-hook}.
 @node Mode Hooks
 @subsection Mode Hooks
 
-  Every major mode function should finish by running its mode hook and
+  Every major mode command 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)
@@ -966,7 +979,7 @@ construct.
 
 @defvar 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.
+very end of every properly-written major mode command.
 @end defvar
 
 @node Example Major Modes
@@ -1194,8 +1207,8 @@ And here is the code to set up the keymap for Lisp mode:
 @end group
 @end smallexample
 
-  Finally, here is the complete major mode function definition for
-Lisp mode.
+  Finally, here is the complete major mode command definition for Lisp
+mode.
 
 @smallexample
 @group
@@ -2752,10 +2765,10 @@ highlighting patterns.  See the variables
 @code{c-font-lock-extra-types}, @code{c++-font-lock-extra-types},
 and @code{java-font-lock-extra-types}, for example.
 
-@strong{Warning:} major mode functions must not call
+@strong{Warning:} major mode commands must not call
 @code{font-lock-add-keywords} under any circumstances, either directly
-or indirectly, except through their mode hooks.  (Doing so would lead
-to incorrect behavior for some minor modes.)  They should set up their
+or indirectly, except through their mode hooks.  (Doing so would lead to
+incorrect behavior for some minor modes.)  They should set up their
 rules for search-based fontification by setting
 @code{font-lock-keywords}.
 @end defun
diff --git a/doc/lispref/vol1.texi b/doc/lispref/vol1.texi
index 3b7718814b5..c192e3bf4b7 100644
--- a/doc/lispref/vol1.texi
+++ b/doc/lispref/vol1.texi
@@ -786,8 +786,7 @@ Major and Minor Modes
 * Major Modes::        Defining major modes.
 * Minor Modes::        Defining minor modes.
 * Mode Line Format::   Customizing the text that appears in the mode line.
-* Imenu::              How a mode can provide a menu
-                         of definitions in the buffer.
+* Imenu::              Providing a menu of definitions made in a buffer.
 * Font Lock Mode::     How modes can highlight text according to syntax.
 * Desktop Save Mode::  How modes can have buffer state saved between
                          Emacs sessions.
@@ -799,15 +798,15 @@ Hooks
 
 Major Modes
 
-* Major Mode Basics::
 * Major Mode Conventions::  Coding conventions for keymaps, etc.
 * 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
                               mode.
+* Basic Major Modes::       Modes that other modes are often derived from.
 * 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.
+* Mode Hooks::              Hooks run at the end of major mode commands.
 * Example Major Modes::     Text mode and Lisp modes.
 
 Minor Modes
diff --git a/doc/lispref/vol2.texi b/doc/lispref/vol2.texi
index 22a51d3235c..8e78a5fb5ca 100644
--- a/doc/lispref/vol2.texi
+++ b/doc/lispref/vol2.texi
@@ -785,8 +785,7 @@ Major and Minor Modes
 * Major Modes::        Defining major modes.
 * Minor Modes::        Defining minor modes.
 * Mode Line Format::   Customizing the text that appears in the mode line.
-* Imenu::              How a mode can provide a menu
-                         of definitions in the buffer.
+* Imenu::              Providing a menu of definitions made in a buffer.
 * Font Lock Mode::     How modes can highlight text according to syntax.
 * Desktop Save Mode::  How modes can have buffer state saved between
                          Emacs sessions.
@@ -798,15 +797,15 @@ Hooks
 
 Major Modes
 
-* Major Mode Basics::
 * Major Mode Conventions::  Coding conventions for keymaps, etc.
 * 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
                               mode.
+* Basic Major Modes::       Modes that other modes are often derived from.
 * 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.
+* Mode Hooks::              Hooks run at the end of major mode commands.
 * Example Major Modes::     Text mode and Lisp modes.
 
 Minor Modes
diff --git a/etc/ChangeLog b/etc/ChangeLog
index 092aa6fb387..24c0fd54422 100644
--- a/etc/ChangeLog
+++ b/etc/ChangeLog
@@ -1,3 +1,9 @@
+2011-08-30  Paul Eggert  <eggert@cs.ucla.edu>
+
+        * MACHINES: Remove obsolete info and update a bit (Bug#9404).
+
+        * PROBLEMS: Remove obsolete comment re Yellow Dog (Bug#9403).
+
 2011-08-24  Steve Chapel  <schapel@laptop.stevechapel.com>  (tiny change)
 
         * refcards/refcard.tex: Add a few more commands. (Bug#9343)
diff --git a/etc/MACHINES b/etc/MACHINES
index 126ae40cb57..1e68376b94a 100644
--- a/etc/MACHINES
+++ b/etc/MACHINES
@@ -24,227 +24,13 @@ file, and then edit the `configure' script to tell it which
 configuration name(s) should select your new machine description and
 system description files.
 
-Some obsolete platforms are unsupported beginning with Emacs 23.1, see
+Some obsolete platforms are unsupported beginning with Emacs 23.1.  See
 the list at the end of this file.
 
 
-** Alpha (DEC) running GNU/Linux (alpha-dec-linux-gnu)
-
-  DEC C compiler version 5.9 (DEC C V5.9-005 on Digital UNIX V4.0f)
-  is reported to produce bogus binaries of Emacs 21.2 when the
-  command-line switches "-O4 -arch ev6 -tune ev6" are used.  Using
-  just -O4 produces a good executable.
-
-  For 4.0 revision 564, and 4.0A and 4.0B, Emacs 20 seems to work
-  with no special configuration options.  However, if you use GCC as
-  your compiler, you will need version 2.8.1 or later, as older
-  versions fail to build with a message "Invalid dimension for the
-  charset-ID 160".
-
-** Apple Macintosh running Mac OS X
-
-** Apple PowerPC Macintosh running GNU/Linux
-
-** HP 9000 series 700 or 800 (Spectrum) (hppa1.0-hp-hpux or hppa1.1-hp-hpux)
-
-  Emacs 20 may work on HPUX 10.  You need patch PHSS_6202 to install
-  the Xaw and Xmu libraries.  On HPUX 10.20 you may need to compile with GCC;
-  when Emacs was compiled with HP's C compiler, HP92453-01 A.10.32.03,
-  the subprocess features failed to work.
-
-  If you turn on the DSUSP character (delayed suspend), Emacs 19.26
-  does not know how to turn it off on HPUX. You need to turn it off manually.
-
-  If you are running HP/UX release 8.0 or later, you need the optional
-  "C/ANSI C" software in order to build Emacs (older releases of HP/UX
-  do not require any special software).  If the file "/etc/filesets/C"
-  exists on your machine, you have this software, otherwise you do not.
-
-** IBM RS/6000 (rs6000-ibm-aix*)
-
-  Emacs 19.26 is believed to work; its pretest was tested.
-
-  Compiling with the system's `cc' and CFLAGS containing `-O5' might
-  fail because libXbsd isn't found.  This is a compiler bug;
-  re-configure Emacs so that it isn't compiled with `-O5'.
-
-  On AIX 4.3.x and 4.4, compiling with /bin/c89 fails because it
-  treats certain warnings as errors.  Use `cc' instead.
-
-  At last report, Emacs didn't run well on terminals.  Informed
-  persons say that the tty VMIN and VTIME settings have been
-  corrupted; if you have a fix, please send it to us.
-
-  Compiling with -O using the IBM compiler has been known to make
-  Emacs work incorrectly.  There are reports that IBM compiler versions
-  earlier than 1.03.00.02 fail even without -O.
-
-  As of 19.11, if you strip the Emacs executable, it ceases to work.
-
-  If anyone can fix the above problems, or confirm that they don't happen
-  with certain versions of various programs, we would appreciate it.
-
-** IBM System/390 running GNU/Linux (s390-*-linux-gnu)
-
-  As of Emacs 21.2, a 31-bit only version is supported on this system.
-
-** Intel 386 (i386-*-freebsd,      i386-*-linux-gnu,
-           i386-*-cygwin,       i386-*-msdos,   i386-*-windowsnt.
-           i386 can be replaced with i486, i586, or i686)
-
-  In the above configurations, * means that the manufacturer's name
-  you specify does not matter, and you can use any name you like
-  (but it should not contain any dashes or stars).
-
-  Use i386-*-linux-gnu for GNU/Linux systems; Emacs runs as of version 19.26.
-  Use i386-*-cygwin for Cygwin; Emacs builds as of version 22.1, in both X11
-  and non-X11 modes.  (The Cygwin site has source and binaries for 21.2.)
-
-  On GNU/Linux systems, Emacs 19.23 was said to work properly with libc
-  version 4.5.21, but not with 4.5.19.
-
-  On GNU/Linux, configure may fail to put these definitions in config.h:
-
-    #define HAVE_GETTIMEOFDAY
-    #define HAVE_MKDIR
-    #define HAVE_RMDIR
-    #define HAVE_XSCREENNUMBEROFSCREEN
-
-  To work around the problem, add those definitions by hand.
-  It is possible that this problem happens only with X11R6.
-  Newer system versions have fixed it.
-
-  On NetBSD and FreeBSD, at one time, it was necessary to use
-  GNU make, not the system's make.  Assuming it's installed as gmake,
-  do `gmake install MAKE=gmake'.  However, more recently it is
-  reported that using the system Make on NetBSD 1.3.1 works ok.
-
-  Note that use of Linux with GCC 2.4 and the DLL 4.4 libraries
-  requires the experimental "net 2" network patches (no relation to
-  Berkeley Net 2).  There is a report that (some version of) Linux
-  requires including `/usr/src/linux/include/linux' in buffer.c
-  but no coherent explanation of why that might be so.  If it is so,
-  in current versions of Linux, something else should probably be changed.
-
-  You may find that adding -I/usr/X/include or -I/usr/netinclude or both
-  to CFLAGS avoids compilation errors on certain systems.
-
-  Some versions convince sysdep.c to try to use `struct tchars'
-  but define `struct tc' instead; add `#define tchars tc'
-  to config.h to solve this problem.
-
-** Iris 4D (mips-sgi-irix6.*)
-
-  Emacs 21.3 is reported to work on IRIX 6.5.x.
-
-  You can build a 64-bit executable (with larger maximum buffer size)
-  on Irix 6.5 by specifying the 64-bit ABI using the `-64' compiler
-  flag or otherwise (see cc(1)).
-
-  If compiling with GCC on Irix 6 yields an error "conflicting types
-  for `initstate'", install GCC 2.95 or a newer version, and this
-  problem should go away.  It is possible that this problem results
-  from upgrading the operating system without reinstalling GCC; so you
-  could also try reinstalling the same version of GCC, and telling us
-  whether that fixes the problem.
-
-** Sun 4 (sparc), Sun 386 (sparc-sun-solaris2.*,
-                               i386-sun-solaris2.*, sparc*-*-linux-gnu)
-
-  To build a 32-bit Emacs (i.e. if you are having any sort of problem
-  bootstrapping a 64-bit version), you can use the Sun Studio compiler
-  and configure Emacs with:
-    env CC="cc -xarch=v7" CFLAGS='' ./configure    # on SPARC systems
-    env CC="cc -xarch=386" CFLAGS='' ./configure   # on x86 systems
-  On Solaris 2.10, it is also possible to use /usr/sfw/bin/gcc to build
-  a 32-bit version of Emacs.  Just make sure you point ./configure to
-  the right compiler:
-
-    env CC='/usr/sfw/bin/gcc -m32' ./configure
-
-  To build a 64-bit Emacs (with larger maximum buffer size and
-  including large file support) on a Solaris system which supports
-  64-bit executables, use the Sun compiler, configuring something like
-  this (see the cc documentation for information on 64-bit
-  compilation):
-
-    env CC="cc -xarch=v9" CFLAGS='' ./configure    # on SPARC systems
-    env CC="cc -xarch=amd64" CFLAGS='' ./configure # on x86 systems
-
-  As of version 2.95, GCC doesn't support the 64-bit ABI properly, but
-  later releases may.
-
-  Some versions of Solaris 8 have a bug in their XIM (X Input Method)
-  implementation which causes Emacs to dump core when one of several
-  frames is closed.  To avoid this, either install patch 108773-12
-  (for Sparc) or 108874-12 (for x86), or configure Emacs with the
-  `--with-xim=no' switch (you can use Leim input methods instead).
-
-  On Solaris 2.7, building Emacs with WorkShop Compilers 5.0 98/12/15
-  C 5.0 failed, apparently with non-default CFLAGS, most probably due to
-  compiler bugs.  Using Sun Solaris 2.7 Sun WorkShop 6 update 1 C
-  release was reported to work without problems.  It worked OK on
-  another system with Solaris 8 using apparently the same 5.0 compiler
-  and the default CFLAGS.
-
-  Emacs 21.1 and 21.2 built with Sun's ProWorks PC3.0.1 compiler on
-  Intel/Solaris 8 was reported to abort and dump core during startup.
-  Using GCC or a newer SUN compiler (Sun WokShop 6 update 2 C 5.3
-  2001/05/15) solves the problem.
-
-  Emacs 20.5 and later work on SPARC GNU/Linux with the 32-bit ABI.
-  As of release 2.95, GCC doesn't work properly with the 64-bit ABI
-  (applicable on UltraSPARC), but that isn't the default mode.
-
-  There are reports that using SunSoft cc with -xO4 -xdepend produces
-  bad code for some part of Emacs.
-
-  Some people report that Emacs crashes immediately on startup when
-  used with a non-X terminal, but we think this is due to compiling
-  with GCC and failing to use GCC's "fixed" system header files.
-
-  Some Sun versions of X windows use the clipboard, not the selections,
-  for transferring text between clients.  The Cut, Paste and Copy items
-  in the menu bar Edit menu work with the clipboard.
-
-  If you compile with Sun's ANSI compiler acc, you need additional options
-  when linking temacs, such as
-     /usr/lang/SC2.0.1/values-Xt.o -L/usr/lang/SC2.0.1/cg87 -L/usr/lang/SC2.0.1
-  (those should be added just before the libraries) and you need to
-  add -lansi just before -lc.  The precise file names depend on the
-  compiler version, so we cannot easily arrange to supply them.
-
-  On Solaris 2, you need to install patch 100947-02 to fix a system bug.
-  Presumably this patch comes from Sun.  You must alter the definition of
-  LD_SWITCH_SYSTEM if your X11 libraries are not in /usr/openwin/lib.
-  You must make sure that /usr/ucblib is not in your LD_LIBRARY_PATH.
-
-  On Solaris, do not use /usr/ucb/cc.  Use /opt/SUNWspro/bin/cc.  Make
-  sure that /usr/ccs/bin and /opt/SUNWspro/bin are in your PATH before
-  /usr/ucb.  (Most free software packages have the same requirement on
-  Solaris.)  With this compiler, use `/opt/SUNWspro/bin/cc -E' as the
-  preprocessor.  If this inserts extra whitespace into its output (see
-  the PROBLEMS file) then add the option `-Xs'.
-
-  If you have trouble using open-network-stream, get the distribution
-  of `bind' (the BSD name-server), build libresolv.a, and link Emacs
-  with -lresolv, by editing LIBRESOLV in src/Makefile.  This problem is
-  due to obsolete software in the nonshared standard library.
-
-  Note that Emacs on a Sun is not really as big as it looks.  As
-  dumped, it includes around 200k of zeros between the original text
-  section and the original data section (now remapped as part of the
-  text). These are never swapped in.
-
-** SuperH (sh[34]*-*-linux-gnu)
-
-  Emacs 23.0.60 was reported to work on GNU/Linux (October 2008).
-  Tested on a little-endian sh4 system (cpu type SH7751R) running
-  Gentoo Linux 2008.0.
-
 * Here are notes about some of the systems supported:
 
-** Linux (actually GNU/Linux)
+** GNU/Linux
 
   Most of the complete systems which use the Linux kernel are close
   enough to the GNU system to be considered variant GNU systems.  We
@@ -263,31 +49,63 @@ the list at the end of this file.
   people to write more free software.  See the file LINUX-GNU in this
   directory for more explanation.
 
+*** 64-bit GNU/Linux
+
+  No special procedures should be needed to build a 64-bit Emacs on a
+  64-bit GNU/Linux system.  To build a 32-bit Emacs, first ensure that
+  the necessary 32-bit system libraries and include files are
+  installed.  Then use:
+
+    ./configure CC='gcc -m32' --build=i386-linux-gnu \
+      --x-libraries=/usr/X11R6/lib
+
+  (using the location of the 32-bit X libraries on your system).
+
+*** IBM System/390 running GNU/Linux (s390-*-linux-gnu)
+
+  As of Emacs 21.2, a 31-bit only version is supported on this system.
+
+*** SuperH (sh[34]*-*-linux-gnu)
+
+  Emacs 23.0.60 was reported to work on GNU/Linux (October 2008).
+  This was tested on a little-endian sh4 system (cpu type SH7751R) running
+  Gentoo Linux 2008.0.
+
 ** Mac OS X
 
   For installation instructions see the file nextstep/INSTALL.
 
-** MSDOS
+** Microsoft Windows
 
-  For installation on MSDOS, see the file msdos/INSTALL.
+  For installation instructions see the file nt/INSTALL.
+
+** MS-DOS
+
+  For installation instructions see the file msdos/INSTALL.
   See the "MS-DOS" chapter of the manual for information about using
-  Emacs on MSDOS.
+  Emacs on MS-DOS.
 
-** MS-Windows NT/95/98/ME/2000
+** Solaris
 
-  For installation on all versions of the MS-Windows platform, see the
-  file nt/INSTALL.
+  On Solaris it is also possible to use either GCC or Solaris Studio
+  to build Emacs, by pointing ./configure to the right compiler:
 
-** X86_64 GNU/Linux
+    ./configure CC='/usr/sfw/bin/gcc'  # GCC
+    ./configure CC='cc'                # Solaris Studio
 
-  No special procedures should be needed to build a 64-bit Emacs.  To
-  build a 32-bit Emacs, first ensure that the necessary 32-bit system
-  libraries and include files are installed.  Then use:
+  On Solaris, do not use /usr/ucb/cc.  Use /opt/SUNWspro/bin/cc.  Make
+  sure that /usr/ccs/bin and /opt/SUNWspro/bin are in your PATH before
+  /usr/ucb.  (Most free software packages have the same requirement on
+  Solaris.)  With this compiler, use `/opt/SUNWspro/bin/cc -E' as the
+  preprocessor.  If this inserts extra whitespace into its output (see
+  the PROBLEMS file) then add the option `-Xs'.
 
-    env CC="gcc -m32" ./configure --build=i386-linux-gnu \
-      --x-libraries=/usr/X11R6/lib
+  To build a 64-bit Emacs (with larger maximum buffer size) on a
+  Solaris system which supports 64-bit executables, specify the -m64
+  compiler option.  For example:
 
-  (using the location of the 32-bit X libraries on your system).
+    ./configure CC='/usr/sfw/bin/gcc -m64'  # GCC
+    ./configure CC='cc -m64'                # Solaris Studio
 
 
 * Obsolete platforms
diff --git a/etc/NEWS b/etc/NEWS
index afd004c5bb3..bbaa46c7222 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -43,10 +43,12 @@ to configure.  Note that other libraries used by Emacs, RSVG and GConf,
 also depend on Gtk+.  You can disable them with --without-rsvg and
 --without-gconf.
 
+---
 ** There is a new configure option --enable-use-lisp-union-type.
 This is only useful for Emacs developers to debug certain types of bugs.
 This is not a new feature; only the configure flag is new.
 
+---
 ** There is a new configure option --with-wide-int.
 With it, Emacs integers typically have 62 bits, even on 32-bit machines.
 
@@ -87,6 +89,7 @@ and also when HOME is set to C:\ by default.
 
 * Changes in Emacs 24.1
 
++++
 ** auto-mode-case-fold is now enabled by default.
 
 ** Completion
@@ -314,15 +317,12 @@ for `list-colors-display'.
 
 ** An Emacs Lisp package manager is now included.
 This is a convenient way to download and install additional packages,
-from a package repository at elpa.gnu.org.
-
+from a package repository at http://elpa.gnu.org.
 +++
 *** `M-x list-packages' shows a list of packages, which can be
 selected for installation.
-
 +++
 *** New command `describe-package', bound to `C-h P'.
-
 +++
 *** By default, all installed packages are loaded and activated
 automatically when Emacs starts up.  To disable this, set
@@ -479,10 +479,8 @@ between applications.
 +++
 *** Support for X cut buffers has been removed.
 
-*** Support for X clipboard managers has been added.
-
-**** To inhibit use of the clipboard manager, set
-`x-select-enable-clipboard-manager' to nil.
+*** X clipboard managers are now supported.
+To inhibit this, change `x-select-enable-clipboard-manager' to nil.
 
 ** New command `rectangle-number-lines', bound to `C-x r N', numbers
 the lines in the current rectangle.  With an prefix argument, this
@@ -1032,6 +1030,7 @@ syntactic rules.
 
 ** frame-local variables cannot be let-bound any more.
 
++++
 ** prog-mode is a new major-mode meant to be the parent of programming mode.
 The prog-mode-hook it defines can be used to enable features for
 programming modes.  For example:
diff --git a/etc/PROBLEMS b/etc/PROBLEMS
index 2f344955cb2..1869124987a 100644
--- a/etc/PROBLEMS
+++ b/etc/PROBLEMS
@@ -2648,43 +2648,6 @@ of PURESIZE in puresize.h.
 But in some of the cases listed above, this problem is a consequence
 of something else that is wrong.  Be sure to check and fix the real problem.
 
-*** Linux: Emacs crashes when dumping itself on Mac PPC running Yellow Dog GNU/Linux.
-
-The crashes happen inside the function Fmake_symbol; here's a typical
-C backtrace printed by GDB:
-
-  0x190c0c0 in Fmake_symbol ()
-  (gdb) where
-  #0  0x190c0c0 in Fmake_symbol ()
-  #1  0x1942ca4 in init_obarray ()
-  #2  0x18b3500 in main ()
-  #3  0x114371c in __libc_start_main (argc=5, argv=0x7ffff5b4, envp=0x7ffff5cc,
-
-This could happen because GCC version 2.95 and later changed the base
-of the load address to 0x10000000.  Emacs needs to be told about this,
-but we currently cannot do that automatically, because that breaks
-other versions of GNU/Linux on the MacPPC.  Until we find a way to
-distinguish between the Yellow Dog and the other varieties of
-GNU/Linux systems on the PPC, you will have to manually uncomment the
-following section near the end of the file src/m/macppc.h in the Emacs
-distribution:
-
-  #if 0  /* This breaks things on PPC GNU/Linux except for Yellowdog,
-            even with identical GCC, as, ld.  Let's take it out until we
-            know what's really going on here.  */
-  /* GCC 2.95 and newer on GNU/Linux PPC changed the load address to
-     0x10000000.  */
-  #if defined __linux__
-  #if __GNUC__ > 2 || (__GNUC__ == 2 && __GNUC_MINOR__ >= 95)
-  #define DATA_SEG_BITS  0x10000000
-  #endif
-  #endif
-  #endif /* 0 */
-
-Remove the "#if 0" and "#endif" directives which surround this, save
-the file, and then reconfigure and rebuild Emacs.  The dumping process
-should now succeed.
-
 *** OpenBSD 4.0 macppc: Segfault during dumping.
 
 The build aborts with signal 11 when the command `./temacs --batch
diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index 03423942f4f..15296e09b46 100644
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,3 +1,8 @@
+2011-08-29  Juri Linkov  <juri@jurta.org>
+
+        * isearch.el (isearch-done): Don't display message "Mark saved"
+        when arg `edit' is non-nil to prevent its flicker in the echo area.
+
 2011-08-28  Chong Yidong  <cyd@stupidchicken.com>
 
         * emacs-lisp/package.el (package-menu-mark-delete): Allow marking
diff --git a/lisp/isearch.el b/lisp/isearch.el
index 8764952dbf5..6eab3dbcbc4 100644
--- a/lisp/isearch.el
+++ b/lisp/isearch.el
@@ -952,7 +952,7 @@ NOPUSH is t and EDIT is t."
       (or (and transient-mark-mode mark-active)
           (progn
             (push-mark isearch-opoint t)
-            (or executing-kbd-macro (> (minibuffer-depth) 0)
+            (or executing-kbd-macro (> (minibuffer-depth) 0) edit
                 (message "Mark saved where search started")))))
 
   (and (not edit) isearch-recursive-edit (exit-recursive-edit)))