upstream

11 files changed, 328 insertions, 286 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index ca9c93b563d..57dde5ac4cb 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,28 @@
+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
+        arguments for delete-file, delete-directory, and copy-directory.
+        (Visiting Functions): Remove view-file; it is documented in the
+        Emacs manual.
+
+        * frames.texi (Layout Parameters): The defaults for the
+        menu-bar-lines and tool-bar-lines parameters depend on the mode.
+
+        * display.texi (Progress): Document spinner functionality.
+
+        * os.texi (Killing Emacs): Note that kill-emacs can be called by
+        operating system signals.  Refer to save-buffers-kill-terminal
+        instead of save-buffers-kill-emacs.
+
+        * objects.texi (Symbol Type): Document ## print representation.
+
 2011-08-25  Eli Zaretskii  <eliz@gnu.org>
 
         * display.texi (Specified Space): Mention that `space' specs
diff --git a/doc/lispref/debugging.texi b/doc/lispref/debugging.texi
index d9e807afb88..757906f286e 100644
--- a/doc/lispref/debugging.texi
+++ b/doc/lispref/debugging.texi
@@ -596,25 +596,6 @@ forms are elided.
 @end smallexample
 @end deffn
 
-@ignore @c Not worth mentioning
-@defopt stack-trace-on-error
-@cindex stack trace
-This variable controls whether Lisp automatically displays a
-backtrace buffer after every error that is not handled.  A quit signal
-counts as an error for this variable.  If it is non-@code{nil} then a
-backtrace is shown in a pop-up buffer named @samp{*Backtrace*} on every
-error.  If it is @code{nil}, then a backtrace is not shown.
-
-When a backtrace is shown, that buffer is not selected.  If either
-@code{debug-on-quit} or @code{debug-on-error} is also non-@code{nil}, then
-a backtrace is shown in one buffer, and the debugger is popped up in
-another buffer with its own backtrace.
-
-We consider this feature to be obsolete and superseded by the debugger
-itself.
-@end defopt
-@end ignore
-
 @defvar debug-on-next-call
 @cindex @code{eval}, and debugging
 @cindex @code{apply}, and debugging
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index bf7cd126a26..cfe4b8298fb 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -367,10 +367,9 @@ echo area, or @code{nil} if there is none.
   When an operation can take a while to finish, you should inform the
 user about the progress it makes.  This way the user can estimate
 remaining time and clearly see that Emacs is busy working, not hung.
+A convenient way to do this is to use a @dfn{progress reporter}.
 
-  Functions listed in this section provide simple and efficient way of
-reporting operation progress.  Here is a working example that does
-nothing useful:
+  Here is a working example that does nothing useful:
 
 @smallexample
 (let ((progress-reporter
@@ -382,11 +381,11 @@ nothing useful:
   (progress-reporter-done progress-reporter))
 @end smallexample
 
-@defun make-progress-reporter message min-value max-value &optional current-value min-change min-time
-This function creates and returns a @dfn{progress reporter}---an
-object you will use as an argument for all other functions listed
-here.  The idea is to precompute as much data as possible to make
-progress reporting very fast.
+@defun make-progress-reporter message &optional min-value max-value current-value min-change min-time
+This function creates and returns a progress reporter object, which
+you will use as an argument for the other functions listed below.  The
+idea is to precompute as much data as possible to make progress
+reporting very fast.
 
 When this progress reporter is subsequently used, it will display
 @var{message} in the echo area, followed by progress percentage.
@@ -394,24 +393,28 @@ When this progress reporter is subsequently used, it will display
 on a filename, for instance, use @code{format} before calling this
 function.
 
-@var{min-value} and @var{max-value} arguments stand for starting and
-final states of your operation.  For instance, if you scan a buffer,
-they should be the results of @code{point-min} and @code{point-max}
-correspondingly.  It is required that @var{max-value} is greater than
-@var{min-value}.  If you create progress reporter when some part of
-the operation has already been completed, then specify
-@var{current-value} argument.  But normally you should omit it or set
-it to @code{nil}---it will default to @var{min-value} then.
-
-Remaining arguments control the rate of echo area updates.  Progress
-reporter will wait for at least @var{min-change} more percents of the
-operation to be completed before printing next message.
-@var{min-time} specifies the minimum time in seconds to pass between
-successive prints.  It can be fractional.  Depending on Emacs and
-system capabilities, progress reporter may or may not respect this
-last argument or do it with varying precision.  Default value for
-@var{min-change} is 1 (one percent), for @var{min-time}---0.2
-(seconds.)
+The arguments @var{min-value} and @var{max-value} should be numbers
+standing for the starting and final states of the operation.  For
+instance, an operation that ``scans'' a buffer should set these to the
+results of @code{point-min} and @code{point-max} correspondingly.
+@var{max-value} should be greater than @var{min-value}.
+
+Alternatively, you can set @var{min-value} and @var{max-value} to
+@code{nil}.  In that case, the progress reporter does not report
+process percentages; it instead displays a ``spinner'' that rotates a
+notch each time you update the progress reporter.
+
+If @var{min-value} and @var{max-value} are numbers, you can give the
+argument @var{current-value} a numerical value specifying the initial
+progress; if omitted, this defaults to @var{min-value}.
+
+The remaining arguments control the rate of echo area updates.  The
+progress reporter will wait for at least @var{min-change} more
+percents of the operation to be completed before printing next
+message; the default is one percent.  @var{min-time} specifies the
+minimum time in seconds to pass between successive prints; the default
+is 0.2 seconds.  (On some operating systems, the progress reporter may
+handle fractions of seconds with varying precision).
 
 This function calls @code{progress-reporter-update}, so the first
 message is printed immediately.
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/files.texi b/doc/lispref/files.texi
index 4d992bd2c51..bd904bf49c0 100644
--- a/doc/lispref/files.texi
+++ b/doc/lispref/files.texi
@@ -203,17 +203,6 @@ When this command is called interactively, it prompts for
 @var{filename}.
 @end deffn
 
-@deffn Command view-file filename
-This command visits @var{filename} using View mode, returning to the
-previous buffer when you exit View mode.  View mode is a minor mode that
-provides commands to skim rapidly through the file, but does not let you
-modify the text.  Entering View mode runs the normal hook
-@code{view-mode-hook}.  @xref{Hooks}.
-
-When @code{view-file} is called interactively, it prompts for
-@var{filename}.
-@end deffn
-
 @defopt find-file-wildcards
 If this variable is non-@code{nil}, then the various @code{find-file}
 commands check for wildcard characters and visit all the files that
@@ -1529,19 +1518,26 @@ This function is not available on systems that don't support symbolic
 links.
 @end deffn
 
-@deffn Command delete-file filename
+@cindex trash
+@vindex delete-by-moving-to-trash
+@deffn Command delete-file filename &optional trash
 @pindex rm
-This command deletes the file @var{filename}, like the shell command
-@samp{rm @var{filename}}.  If the file has multiple names, it continues
-to exist under the other names.
-
-A suitable kind of @code{file-error} error is signaled if the file does
-not exist, or is not deletable.  (On Unix and GNU/Linux, a file is
-deletable if its directory is writable.)
-
-If @var{filename} is a symbolic link, @code{delete-file} does not
-replace it with its target, but it does follow symbolic links at all
-levels of parent directories.
+This command deletes the file @var{filename}.  If the file has
+multiple names, it continues to exist under the other names.  If
+@var{filename} is a symbolic link, @code{delete-file} deletes only the
+symbolic link and not its target (though it does follow symbolic links
+at all levels of parent directories).
+
+A suitable kind of @code{file-error} error is signaled if the file
+does not exist, or is not deletable.  (On Unix and GNU/Linux, a file
+is deletable if its directory is writable.)
+
+If the optional argument @var{trash} is non-@code{nil} and the
+variable @code{delete-by-moving-to-trash} is non-@code{nil}, this
+command moves the file into the system Trash instead of deleting it.
+@xref{Misc File Ops,,Miscellaneous File Operations, emacs, The GNU
+Emacs Manual}.  When called interactively, @var{trash} is @code{t} if
+no prefix argument is given, and @code{nil} otherwise.
 
 See also @code{delete-directory} in @ref{Create/Delete Dirs}.
 @end deffn
@@ -2507,7 +2503,7 @@ if they don't already exist.
 @code{mkdir} is an alias for this.
 @end deffn
 
-@deffn Command copy-directory dirname newname &optional keep-time parents
+@deffn Command copy-directory dirname newname &optional keep-time parents copy-contents
 This command copies the directory named @var{dirname} to
 @var{newname}.  If @var{newname} names an existing directory,
 @var{dirname} will be copied to a subdirectory there.
@@ -2515,16 +2511,23 @@ This command copies the directory named @var{dirname} to
 It always sets the file modes of the copied files to match the
 corresponding original file.
 
-The third arg @var{keep-time} non-@code{nil} means to preserve the
+The third argument @var{keep-time} non-@code{nil} means to preserve the
 modification time of the copied files.  A prefix arg makes
 @var{keep-time} non-@code{nil}.
 
-Noninteractively, the last argument @var{parents} says whether to
+The fourth argument @var{parents} says whether to
 create parent directories if they don't exist.  Interactively,
 this happens by default.
+
+The fifth argument @var{copy-contents}, if non-@code{nil}, means to
+copy the contents of @var{dirname} directly into @var{newname} if the
+latter is an existing directory, instead of copying @var{dirname} into
+it as a subdirectory.
 @end deffn
 
-@deffn Command delete-directory dirname &optional recursive
+@cindex trash
+@vindex delete-by-moving-to-trash
+@deffn Command delete-directory dirname &optional recursive trash
 This command deletes the directory named @var{dirname}.  The function
 @code{delete-file} does not work for files that are directories; you
 must use @code{delete-directory} for them.  If @var{recursive} is
@@ -2533,6 +2536,13 @@ must use @code{delete-directory} for them.  If @var{recursive} is
 
 @code{delete-directory} only follows symbolic links at the level of
 parent directories.
+
+If the optional argument @var{trash} is non-@code{nil} and the
+variable @code{delete-by-moving-to-trash} is non-@code{nil}, this
+command moves the file into the system Trash instead of deleting it.
+@xref{Misc File Ops,,Miscellaneous File Operations, emacs, The GNU
+Emacs Manual}.  When called interactively, @var{trash} is @code{t} if
+no prefix argument is given, and @code{nil} otherwise.
 @end deffn
 
 @node Magic File Names
diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi
index b6012a4dd53..e799cfa6b7f 100644
--- a/doc/lispref/frames.texi
+++ b/doc/lispref/frames.texi
@@ -695,20 +695,19 @@ right fringe.  However, you can force one fringe or the other to a
 precise width by specifying that width as a negative integer.  If both
 widths are negative, only the left fringe gets the specified width.
 
-@vindex menu-bar-lines, a frame parameter
+@vindex menu-bar-lines frame parameter
 @item menu-bar-lines
 The number of lines to allocate at the top of the frame for a menu
-bar.  The default is 1.  A value of @code{nil} means don't display a
-menu bar.  @xref{Menu Bar}.  (The X toolkit and GTK allow at most one
-menu bar line; they treat larger values as 1.)
+bar.  The default is 1 if Menu Bar mode is enabled, and 0 otherwise.
+@xref{Menu Bars,,,emacs, The GNU Emacs Manual}.
 
-@vindex tool-bar-lines, a frame parameter
+@vindex tool-bar-lines frame parameter
 @item tool-bar-lines
-The number of lines to use for the tool bar.  A value of @code{nil}
-means don't display a tool bar.  (GTK and Nextstep allow at most one
-tool bar line; they treat larger values as 1.)
+The number of lines to use for the tool bar.  The default is 1 if Tool
+Bar mode is enabled, and 0 otherwise.  @xref{Tool Bars,,,emacs, The
+GNU Emacs Manual}.
 
-@vindex tool-bar-position, a frame parameter
+@vindex tool-bar-position frame parameter
 @item tool-bar-position
 The position of the tool bar.  Currently only for the GTK tool bar.
 Value can be one of @code{top}, @code{bottom} @code{left}, @code{right}.
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/objects.texi b/doc/lispref/objects.texi
index 6d63bb7b750..26def7858b7 100644
--- a/doc/lispref/objects.texi
+++ b/doc/lispref/objects.texi
@@ -597,6 +597,7 @@ FOO                 ; @r{A symbol named @samp{FOO}, different from @samp{foo}.}
 @end group
 @end example
 
+@cindex @samp{##} read syntax
 @ifinfo
 @c This uses ``colon'' instead of a literal `:' because Info cannot
 @c cope with a `:' in a menu
@@ -605,9 +606,12 @@ FOO                 ; @r{A symbol named @samp{FOO}, different from @samp{foo}.}
 @ifnotinfo
 @cindex @samp{#:} read syntax
 @end ifnotinfo
-  Normally the Lisp reader interns all symbols (@pxref{Creating
-Symbols}).  To prevent interning, you can write @samp{#:} before the
-name of the symbol.
+  As an exception to the rule that a symbol's name serves as its
+printed representation, @samp{##} is the printed representation for an
+interned symbol whose name is an empty string.  Furthermore,
+@samp{#:@var{foo}} is the printed representation for an uninterned
+symbol whose name is @var{foo}.  (Normally, the Lisp reader interns
+all symbols; @pxref{Creating Symbols}.)
 
 @node Sequence Type
 @subsection Sequence Types
diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi
index 8533b77b219..7d05f8f3468 100644
--- a/doc/lispref/os.texi
+++ b/doc/lispref/os.texi
@@ -544,10 +544,11 @@ parent process normally resumes control.  The low-level primitive for
 killing Emacs is @code{kill-emacs}.
 
 @deffn Command kill-emacs &optional exit-data
-This command exits the Emacs process and kills it.
+This command calls the hook @code{kill-emacs-hook}, then exits the
+Emacs process and kills it.
 
-If @var{exit-data} is an integer, then it is used as the exit status
-of the Emacs process.  (This is useful primarily in batch operation; see
+If @var{exit-data} is an integer, that is used as the exit status of
+the Emacs process.  (This is useful primarily in batch operation; see
 @ref{Batch Mode}.)
 
 If @var{exit-data} is a string, its contents are stuffed into the
@@ -555,35 +556,44 @@ terminal input buffer so that the shell (or whatever program next reads
 input) can read them.
 @end deffn
 
-  All the information in the Emacs process, aside from files that have
-been saved, is lost when the Emacs process is killed.  Because killing
-Emacs inadvertently can lose a lot of work, Emacs queries for
-confirmation before actually terminating if you have buffers that need
-saving or subprocesses that are running.  This is done in the function
-@code{save-buffers-kill-emacs}, the higher level function from which
-@code{kill-emacs} is usually called.
+@cindex SIGTERM
+@cindex SIGHUP
+@cindex SIGINT
+@cindex operating system signal
+  The @code{kill-emacs} function is normally called via the
+higher-level command @kbd{C-x C-c}
+(@code{save-buffers-kill-terminal}).  @xref{Exiting,,, emacs, The GNU
+Emacs Manual}.  It is also called automatically if Emacs receives a
+@code{SIGTERM} or @code{SIGHUP} operating system signal (e.g. when the
+controlling terminal is disconnected), or if it receives a
+@code{SIGINT} signal while running in batch mode (@pxref{Batch Mode}).
 
-@defvar kill-emacs-query-functions
-After asking the standard questions, @code{save-buffers-kill-emacs}
-calls the functions in the list @code{kill-emacs-query-functions}, in
-order of appearance, with no arguments.  These functions can ask for
-additional confirmation from the user.  If any of them returns
-@code{nil}, @code{save-buffers-kill-emacs} does not kill Emacs, and
-does not run the remaining functions in this hook.  Calling
-@code{kill-emacs} directly does not run this hook.
+@defvar kill-emacs-hook
+This normal hook is run by @code{kill-emacs}, before it kills Emacs.
+
+Because @code{kill-emacs} can be called in situations where user
+interaction is impossible (e.g. when the terminal is disconnected),
+functions on this hook should not attempt to interact with the user.
+If you want to interact with the user when Emacs is shutting down, use
+@code{kill-emacs-query-functions}, described below.
 @end defvar
 
-@defvar kill-emacs-hook
-This variable is a normal hook; once @code{save-buffers-kill-emacs} is
-finished with all file saving and confirmation, it calls
-@code{kill-emacs} which runs the functions in this hook.
-
-@code{kill-emacs} may be invoked directly (that is not via
-@code{save-buffers-kill-emacs}) if the terminal is disconnected, or in
-similar situations where interaction with the user is not possible.
-Thus, if your hook needs to interact with the user, put it on
-@code{kill-emacs-query-functions}; if it needs to run regardless of
-how Emacs is killed, put it on @code{kill-emacs-hook}.
+  When Emacs is killed, all the information in the Emacs process,
+aside from files that have been saved, is lost.  Because killing Emacs
+inadvertently can lose a lot of work, the
+@code{save-buffers-kill-terminal} command queries for confirmation if
+you have buffers that need saving or subprocesses that are running.
+It also runs the abnormal hook @code{kill-emacs-query-functions}:
+
+@defvar kill-emacs-query-functions
+When @code{save-buffers-kill-terminal} is killing Emacs, it calls the
+functions in this hook, after asking the standard questions and before
+calling @code{kill-emacs}.  The functions are called in order of
+appearance, with no arguments.  Each function can ask for additional
+confirmation from the user.  If any of them returns @code{nil},
+@code{save-buffers-kill-emacs} does not kill Emacs, and does not run
+the remaining functions in this hook.  Calling @code{kill-emacs}
+directly does not run this hook.
 @end defvar
 
 @node Suspending Emacs
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