Update and edit manual sections on major modes.

* doc/emacs/modes.texi (Choosing Modes): auto-mode-case-fold is now t.

* doc/lispref/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.

8 files changed, 208 insertions, 187 deletions

diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog
index 58b98189e2..2407d7dd18 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 314d5d4347..d82423a73b 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 aae0be5a05..57dde5ac4c 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 bb05f1b4a0..a19af90302 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 a354265b36..586fc0bbbf 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 3b7718814b..c192e3bf4b 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 22a51d3235..8e78a5fb5c 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/NEWS b/etc/NEWS
index afd004c5bb..bbaa46c722 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: