upstream

21 files changed, 485 insertions, 414 deletions

diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog
index 50eb89fe488..2407d7dd18f 100644
--- a/doc/emacs/ChangeLog
+++ b/doc/emacs/ChangeLog
@@ -1,3 +1,27 @@
+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):
+        * cal-xtra.texi (Diary Display):
+        * help.texi (Help Mode): Add xref to View Mode.
+
+2011-08-28  Chong Yidong  <cyd@stupidchicken.com>
+
+        * display.texi (View Mode): New node.  Move view-file here from
+        Misc File Ops.  Move view-buffer here from Misc Buffer.
+
+        * buffers.texi (Misc Buffer): Move view-buffer to View Mode.
+
+        * files.texi (Misc File Ops): Document new
+        delete-by-moving-to-trash behavior.  Remove view-file.
+
+        * dired.texi (Dired Deletion): Shorten description of Trash.
+
+        * misc.texi (emacsclient Options): Document server-port.
+
 2011-08-27  Eli Zaretskii  <eliz@gnu.org>
 
         * frames.texi (Frame Commands): Advise setting focus-follows-mouse
diff --git a/doc/emacs/buffers.texi b/doc/emacs/buffers.texi
index d4cc4f7bb6a..c4880af2b5d 100644
--- a/doc/emacs/buffers.texi
+++ b/doc/emacs/buffers.texi
@@ -285,16 +285,6 @@ buffers with particular names.  (With some of these features, such as
 switch to some other buffer before using the command, in order for it
 to make a different buffer.)
 
-@findex view-buffer
-  @kbd{M-x view-buffer} is much like @kbd{M-x view-file} (@pxref{Misc
-File Ops}) except that it examines an already existing Emacs buffer.
-View mode provides commands for scrolling through the buffer
-conveniently but not for changing it.  When you exit View mode with
-@kbd{q}, that switches back to the buffer (and the position) which was
-previously displayed in the window.  Alternatively, if you exit View
-mode with @kbd{e}, the buffer and the value of point that resulted from
-your perusal remain in effect.
-
   The commands @kbd{M-x append-to-buffer} and @kbd{M-x insert-buffer}
 can be used to copy text from one buffer to another.  @xref{Accumulating
 Text}.
diff --git a/doc/emacs/cal-xtra.texi b/doc/emacs/cal-xtra.texi
index 52898efc268..6d20c92a6d9 100644
--- a/doc/emacs/cal-xtra.texi
+++ b/doc/emacs/cal-xtra.texi
@@ -538,13 +538,7 @@ are no diary entries, even if that day is a holiday.  If you want such
 days to be shown in the fancy diary buffer, set the variable
 @code{diary-list-include-blanks} to @code{t}.@refill
 
-@c View mode does not seem to be described in the manual.
-@c buffers.texi has a brief mention.
-  The fancy diary buffer enables View mode, a minor mode that provides
-commands for scrolling and searching the text.  For example, @key{SPC}
-and @key{DEL} scroll forward and backward, and @key{s} starts an
-incremental search.  See the documentation of the function
-@code{view-mode} for more information.
+  The fancy diary buffer enables View mode (@pxref{View Mode}).
 
   The alternative display method @code{diary-simple-display} shows the
 actual diary buffer, and uses invisible text to hide entries that don't
diff --git a/doc/emacs/dired.texi b/doc/emacs/dired.texi
index d536547e293..eb2bcc109e8 100644
--- a/doc/emacs/dired.texi
+++ b/doc/emacs/dired.texi
@@ -201,12 +201,10 @@ delete nonempty directories including all their contents.  That can
 be somewhat risky.
 
 @vindex delete-by-moving-to-trash
-  On some systems, there is a facility called the ``Trash'' or
-``Recycle Bin'', but Emacs does @emph{not} use it by default.  Thus,
-when you delete a file in Dired, it is gone forever.  However, you can
-tell Emacs to use the Trash for file deletion, by changing the
-variable @code{delete-by-moving-to-trash} to @code{t}.  @xref{Misc
-File Ops}, for more information about the Trash.
+  If you change the variable @code{delete-by-moving-to-trash} to
+@code{t}, the above deletion commands will move the affected files or
+directories into the operating system's Trash, instead of deleting
+them outright.  @xref{Misc File Ops}.
 
 @node Flagging Many Files
 @section Flagging Many Files at Once
diff --git a/doc/emacs/display.texi b/doc/emacs/display.texi
index cc7f70cf574..09e365d9d5f 100644
--- a/doc/emacs/display.texi
+++ b/doc/emacs/display.texi
@@ -17,6 +17,7 @@ want to see, and how to display it.
 * Horizontal Scrolling::   Moving text left and right in a window.
 * Narrowing::              Restricting display and editing to a portion
                              of the buffer.
+* View Mode::              Viewing read-only buffers.
 * Follow Mode::            Follow mode lets two windows scroll as one.
 * Faces::                  How to change the display style using faces.
 * Standard Faces::         Emacs' predefined faces.
@@ -368,6 +369,28 @@ this command asks for confirmation and gives you the option of enabling it;
 if you enable the command, confirmation will no longer be required for
 it.  @xref{Disabling}.
 
+@node View Mode
+@section View Mode
+@cindex View mode
+@cindex mode, View
+
+  View mode is a minor mode that lets you scan a buffer by sequential
+screenfuls.  It provides commands for scrolling through the buffer
+conveniently but not for changing it.  Apart from the usual Emacs
+cursor motion commands, you can type @key{SPC} to scroll forward one
+windowful, @key{DEL} to scroll backward, and @kbd{s} to start an
+incremental search.
+
+  Typing @kbd{q} disables View mode, and switches back to the buffer
+and position before View mode was enabled.  Alternatively, typing
+@kbd{e} disables View mode, keeping the current buffer and position.
+
+@findex view-buffer
+@findex view-file
+  @kbd{M-x view-buffer} prompts for an existing Emacs buffer, switches
+to it, and enables View mode.  @kbd{M-x view-file} prompts for a file
+and visits it with View mode enabled.
+
 @node Follow Mode
 @section Follow Mode
 @cindex Follow mode
diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi
index 060f939fa7a..2ba4af712af 100644
--- a/doc/emacs/emacs.texi
+++ b/doc/emacs/emacs.texi
@@ -345,6 +345,7 @@ Controlling the Display
 * Horizontal Scrolling::   Moving text left and right in a window.
 * Narrowing::              Restricting display and editing to a portion
                              of the buffer.
+* View Mode::              Viewing read-only buffers.
 * Follow Mode::            Follow mode lets two windows scroll as one.
 * Faces::                  How to change the display style using faces.
 * Standard Faces::         Emacs' predefined faces.
@@ -1054,6 +1055,12 @@ Hyperlinking and Navigation Features
 * Goto Address mode::   Activating URLs.
 * FFAP::                Finding files etc. at point.
 
+Emacs Lisp Packages
+
+* Package Menu::         Buffer for viewing and managing packages.
+* Package Installation:: Options for package installation.
+* Package Files::        Where packages are installed.
+
 Customization
 
 * Easy Customization::  Convenient way to browse and change settings.
diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi
index 793a11e62ed..2672c30363b 100644
--- a/doc/emacs/files.texi
+++ b/doc/emacs/files.texi
@@ -1272,11 +1272,11 @@ this, it runs the program specified by
   The command @kbd{M-x delete-directory} prompts for a directory name
 using the minibuffer, and deletes the directory if it is empty.  If
 the directory is not empty, you will be asked whether you want to
-delete it recursively.  On systems that have a ``Trash'' or ``Recycle
-Bin'' feature, you can make this command move the specified directory
-to the Trash or Recycle Bin, instead of deleting it outright, by
-changing the variable @code{delete-by-moving-to-trash} to @code{t}.
-@xref{Misc File Ops}, for more information about using the Trash.
+delete it recursively.  On systems that have a ``Trash'' (or ``Recycle
+Bin'') feature, you can make this command move the specified directory
+to the Trash instead of deleting it outright, by changing the variable
+@code{delete-by-moving-to-trash} to @code{t}.  @xref{Misc File Ops},
+for more information about using the Trash.
 
 @node Comparing Files
 @section Comparing Files
@@ -1503,23 +1503,78 @@ patch syntax (@pxref{Useless Whitespace}).
   Emacs has commands for performing many other operations on files.
 All operate on one file; they do not accept wildcard file names.
 
-@findex view-file
-@cindex viewing
-@cindex View mode
-@cindex mode, View
-  @kbd{M-x view-file} allows you to scan or read a file by sequential
-screenfuls.  It reads a file name argument using the minibuffer.  After
-reading the file into an Emacs buffer, @code{view-file} displays the
-beginning.  You can then type @key{SPC} to scroll forward one windowful,
-or @key{DEL} to scroll backward.  Various other commands are provided
-for moving around in the file, but none for changing it; type @kbd{?}
-while viewing for a list of them.  They are mostly the same as normal
-Emacs cursor motion commands.  To exit from viewing, type @kbd{q}.
-The commands for viewing are defined by a special minor mode called View
-mode.
-
-  A related command, @kbd{M-x view-buffer}, views a buffer already present
-in Emacs.  @xref{Misc Buffer}.
+@findex delete-file
+@cindex deletion (of files)
+  @kbd{M-x delete-file} prompts for a file and deletes it.  If you are
+deleting many files in one directory, it may be more convenient to use
+Dired rather than @code{delete-file}.  @xref{Dired Deletion}.
+
+@cindex trash
+@cindex recycle bin
+  @kbd{M-x move-file-to-trash} moves a file into the system
+@dfn{Trash} (or @dfn{Recycle Bin}).  This is a facility available on
+most operating systems; files that are moved into the Trash can be
+brought back later if you change your mind.
+
+@vindex delete-by-moving-to-trash
+  By default, Emacs deletion commands do @emph{not} use the Trash.  To
+use the Trash (when it is available) for common deletion commands,
+change the variable @code{delete-by-moving-to-trash} to @code{t}.
+This affects the commands @kbd{M-x delete-file} and @kbd{M-x
+delete-directory} (@pxref{Directories}), as well as the deletion
+commands in Dired (@pxref{Dired Deletion}).  Supplying a prefix
+argument to @kbd{M-x delete-file} or @kbd{M-x delete-directory} makes
+them delete outright, instead of using the Trash, regardless of
+@code{delete-by-moving-to-trash}.
+
+@findex copy-file
+@cindex copying files
+  @kbd{M-x copy-file} reads the file @var{old} and writes a new file
+named @var{new} with the same contents.
+
+@findex copy-directory
+  @kbd{M-x copy-directory} copies directories, similar to the
+@command{cp -r} shell command.  It prompts for a directory @var{old}
+and a destination @var{new}.  If @var{new} is an existing directory,
+it creates a copy of the @var{old} directory and puts it in @var{new}.
+If @var{new} is not an existing directory, it copies all the contents
+of @var{old} into a new directory named @var{new}.
+
+@findex rename-file
+  @kbd{M-x rename-file} reads two file names @var{old} and @var{new}
+using the minibuffer, then renames file @var{old} as @var{new}.  If
+the file name @var{new} already exists, you must confirm with
+@kbd{yes} or renaming is not done; this is because renaming causes the
+old meaning of the name @var{new} to be lost.  If @var{old} and
+@var{new} are on different file systems, the file @var{old} is copied
+and deleted.  If the argument @var{new} is just a directory name, the
+real new name is in that directory, with the same non-directory
+component as @var{old}.  For example, @kbd{M-x rename-file RET ~/foo
+RET /tmp RET} renames @file{~/foo} to @file{/tmp/foo}.  The same rule
+applies to all the remaining commands in this section.  All of them
+ask for confirmation when the new file name already exists, too.
+
+@findex add-name-to-file
+@cindex hard links (creation)
+  @kbd{M-x add-name-to-file} adds an additional name to an existing
+file without removing its old name.  The new name is created as a
+``hard link'' to the existing file.  The new name must belong on the
+same file system that the file is on.  On MS-Windows, this command
+works only if the file resides in an NTFS file system.  On MS-DOS, it
+works by copying the file.
+
+@findex make-symbolic-link
+@cindex symbolic links (creation)
+  @kbd{M-x make-symbolic-link} reads two file names @var{target} and
+@var{linkname}, then creates a symbolic link named @var{linkname},
+which points at @var{target}.  The effect is that future attempts to
+open file @var{linkname} will refer to whatever file is named
+@var{target} at the time the opening is done, or will get an error if
+the name @var{target} is nonexistent at that time.  This command does
+not expand the argument @var{target}, so that it allows you to specify
+a relative name as the target of the link.  Not all systems support
+symbolic links; on systems that don't support them, this command is
+not defined.
 
 @kindex C-x i
 @findex insert-file
@@ -1544,74 +1599,6 @@ specified file.  @xref{Accumulating Text}.  The variable
 @code{write-region-inhibit-fsync} applies to these commands, as well
 as saving files; see @ref{Customize Save}.
 
-@findex delete-file
-@cindex deletion (of files)
-@vindex delete-by-moving-to-trash
-  @kbd{M-x delete-file} deletes the specified file, like the @code{rm}
-command in the shell.  If you are deleting many files in one
-directory, it may be more convenient to use Dired rather than
-@code{delete-file}.  @xref{Dired}.
-
-@cindex trash
-@cindex recycle bin
-  On some systems, there is a facility called the ``Trash'' (or
-``Recycle Bin''); ``deleting'' a file normally means moving it into
-the Trash, and you can bring the file back from the Trash if you later
-change your mind.  By default, Emacs does @emph{not} use the Trash for
-file deletion---when Emacs deletes a file, it is gone forever.  You
-can tell Emacs to use the Trash by changing the variable
-@code{delete-by-moving-to-trash} to @code{t}.  This applies to file
-deletion via @kbd{M-x delete-file}, as well as @kbd{M-x
-delete-directory} (@pxref{Directories}) and file deletion in Dired
-(@pxref{Dired Deletion}).  In addition, you can explicitly move a file
-into the Trash with the command @kbd{M-x move-file-to-trash}.
-
-@findex rename-file
-  @kbd{M-x rename-file} reads two file names @var{old} and @var{new} using
-the minibuffer, then renames file @var{old} as @var{new}.  If the file name
-@var{new} already exists, you must confirm with @kbd{yes} or renaming is not
-done; this is because renaming causes the old meaning of the name @var{new}
-to be lost.  If @var{old} and @var{new} are on different file systems, the
-file @var{old} is copied and deleted.
-
-  If the argument @var{new} is just a directory name, the real new
-name is in that directory, with the same non-directory component as
-@var{old}.  For example, @kbd{M-x rename-file RET ~/foo RET /tmp RET}
-renames @file{~/foo} to @file{/tmp/foo}.  The same rule applies to all
-the remaining commands in this section.  All of them ask for
-confirmation when the new file name already exists, too.
-
-@findex add-name-to-file
-@cindex hard links (creation)
-  The similar command @kbd{M-x add-name-to-file} is used to add an
-additional name to an existing file without removing its old name.
-The new name is created as a ``hard link'' to the existing file.
-The new name must belong on the same file system that the file is on.
-On MS-Windows, this command works only if the file resides in an NTFS
-file system.  On MS-DOS, it works by copying the file.
-
-@findex copy-file
-@findex copy-directory
-@cindex copying files
-  @kbd{M-x copy-file} reads the file @var{old} and writes a new file
-named @var{new} with the same contents.  @kbd{M-x copy-directory} does
-the same for directories, by recursive copying all files and
-subdirectories.
-
-@findex make-symbolic-link
-@cindex symbolic links (creation)
-  @kbd{M-x make-symbolic-link} reads two file names @var{target} and
-@var{linkname}, then creates a symbolic link named @var{linkname},
-which points at @var{target}.  The effect is that future attempts to
-open file @var{linkname} will refer to whatever file is named
-@var{target} at the time the opening is done, or will get an error if
-the name @var{target} is nonexistent at that time.  This command does
-not expand the argument @var{target}, so that it allows you to specify
-a relative name as the target of the link.
-
-  Not all systems support symbolic links; on systems that don't
-support them, this command is not defined.
-
 @findex set-file-modes
 @cindex file modes
 @cindex file permissions
@@ -1670,13 +1657,13 @@ Tar mode is used also for compressed archives---files with extensions
   The keys @kbd{e}, @kbd{f} and @key{RET} all extract a component file
 into its own buffer.  You can edit it there, and if you save the
 buffer, the edited version will replace the version in the Tar buffer.
-@kbd{v} extracts a file into a buffer in View mode.  @kbd{o} extracts
-the file and displays it in another window, so you could edit the file
-and operate on the archive simultaneously.  @kbd{d} marks a file for
-deletion when you later use @kbd{x}, and @kbd{u} unmarks a file, as in
-Dired.  @kbd{C} copies a file from the archive to disk and @kbd{R}
-renames a file within the archive.  @kbd{g} reverts the buffer from
-the archive on disk.
+@kbd{v} extracts a file into a buffer in View mode (@pxref{View
+Mode}).  @kbd{o} extracts the file and displays it in another window,
+so you could edit the file and operate on the archive simultaneously.
+@kbd{d} marks a file for deletion when you later use @kbd{x}, and
+@kbd{u} unmarks a file, as in Dired.  @kbd{C} copies a file from the
+archive to disk and @kbd{R} renames a file within the archive.
+@kbd{g} reverts the buffer from the archive on disk.
 
   The keys @kbd{M}, @kbd{G}, and @kbd{O} change the file's permission
 bits, group, and owner, respectively.
diff --git a/doc/emacs/help.texi b/doc/emacs/help.texi
index bf93892c0db..9ff995138f5 100644
--- a/doc/emacs/help.texi
+++ b/doc/emacs/help.texi
@@ -405,8 +405,8 @@ the variable @code{apropos-documentation-sort-by-scores} is
 @node Help Mode
 @section Help Mode Commands
 
-  Help buffers provide the same commands as View mode (@pxref{Misc File
-Ops}), plus a few special commands of their own.
+  Help buffers provide the same commands as View mode (@pxref{View
+Mode}), plus a few special commands of their own.
 
 @table @kbd
 @item @key{SPC}
diff --git a/doc/emacs/misc.texi b/doc/emacs/misc.texi
index 2dab70c512a..598f495784f 100644
--- a/doc/emacs/misc.texi
+++ b/doc/emacs/misc.texi
@@ -1596,6 +1596,11 @@ runs, and (ii) provide @command{emacsclient} with the server file.
 (One convenient way to do the latter is to put the server file on a
 networked file system such as NFS.)
 
+@vindex server-port
+  When the Emacs server is using TCP, the variable @code{server-port}
+determines the port number to listen on; the default value,
+@code{nil}, means to choose a random port when the server starts.
+
 @item -n
 @itemx --no-wait
 Let @command{emacsclient} exit immediately, instead of waiting until
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 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