Document copy-directory and related changes in manuals.

* doc/emacs/buffers.texi (Misc Buffer): Move view-buffer to View Mode.

* doc/emacs/display.texi (View Mode): New node.  Move view-file here from
Misc File Ops.  Move view-buffer here from Misc Buffer.

* doc/emacs/files.texi (Misc File Ops): Document new
delete-by-moving-to-trash behavior.  Remove view-file.

* doc/lispref/files.texi (Changing Files, Create/Delete Dirs): Document new
arguments for delete-file, delete-directory, and copy-directory.

8 files changed, 102 insertions, 99 deletions

diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog
index 7b940ba7b5a..a08bd212b25 100644
--- a/doc/emacs/ChangeLog
+++ b/doc/emacs/ChangeLog
@@ -1,7 +1,12 @@
 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.
+        delete-by-moving-to-trash behavior.  Remove view-file.
 
         * dired.texi (Dired Deletion): Shorten description of Trash.
 
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/display.texi b/doc/emacs/display.texi
index cc7f70cf574..aaa04230b6f 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,27 @@ 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, or @key{DEL} to scroll backward.
+
+  Typing @kbd{q} disables View mode, and switches back to the buffer
+and position before View mode was enabled.  Alternatively, type
+@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 5f0d66b95a3..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.
diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi
index d337ed3694e..a41e14e5fcb 100644
--- a/doc/emacs/files.texi
+++ b/doc/emacs/files.texi
@@ -1503,59 +1503,18 @@ 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}.
-
-@kindex C-x i
-@findex insert-file
-  @kbd{M-x insert-file} (also @kbd{C-x i}) inserts a copy of the
-contents of the specified file into the current buffer at point,
-leaving point unchanged before the contents.  The position after the
-inserted contents is added to the mark ring, without activating the
-mark (@pxref{Mark Ring}).
-
-@findex insert-file-literally
-  @kbd{M-x insert-file-literally} is like @kbd{M-x insert-file},
-except the file is inserted ``literally'': it is treated as a sequence
-of @acronym{ASCII} characters with no special encoding or conversion,
-similar to the @kbd{M-x find-file-literally} command
-(@pxref{Visiting}).
-
-@findex write-region
-  @kbd{M-x write-region} is the inverse of @kbd{M-x insert-file}; it
-copies the contents of the region into the specified file.  @kbd{M-x
-append-to-file} adds the text of the region to the end of the
-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)
   @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}.
+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 operating
-system's @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.
+  @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
@@ -1566,42 +1525,43 @@ 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}.  The variable
-@code{delete-by-moving-to-trash} does not affect file deletions that
-happen as a side-effect of other Emacs commands (e.g. deletions of
-temporary files); those are always true deletions.
+@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.
+  @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.
+  @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)
@@ -1612,10 +1572,32 @@ 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.
+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
+  @kbd{M-x insert-file} (also @kbd{C-x i}) inserts a copy of the
+contents of the specified file into the current buffer at point,
+leaving point unchanged before the contents.  The position after the
+inserted contents is added to the mark ring, without activating the
+mark (@pxref{Mark Ring}).
 
-  Not all systems support symbolic links; on systems that don't
-support them, this command is not defined.
+@findex insert-file-literally
+  @kbd{M-x insert-file-literally} is like @kbd{M-x insert-file},
+except the file is inserted ``literally'': it is treated as a sequence
+of @acronym{ASCII} characters with no special encoding or conversion,
+similar to the @kbd{M-x find-file-literally} command
+(@pxref{Visiting}).
+
+@findex write-region
+  @kbd{M-x write-region} is the inverse of @kbd{M-x insert-file}; it
+copies the contents of the region into the specified file.  @kbd{M-x
+append-to-file} adds the text of the region to the end of the
+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 set-file-modes
 @cindex file modes
diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index a778cd92518..b0328dba3f1 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,7 +1,7 @@
 2011-08-28  Chong Yidong  <cyd@stupidchicken.com>
 
-        * files.texi (Changing Files, Create/Delete Dirs): Document TRASH
-        argument.
+        * files.texi (Changing Files, Create/Delete Dirs): Document new
+        arguments for delete-file, delete-directory, and copy-directory.
 
         * frames.texi (Layout Parameters): The defaults for the
         menu-bar-lines and tool-bar-lines parameters depend on the mode.
diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi
index c83defb433c..25afb810a88 100644
--- a/doc/lispref/files.texi
+++ b/doc/lispref/files.texi
@@ -2514,7 +2514,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.
@@ -2522,13 +2522,18 @@ 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
 
 @cindex trash
diff --git a/etc/NEWS b/etc/NEWS
index f563dde0b0c..afd004c5bb3 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -384,15 +384,12 @@ pops up *Messages*" feature, which can now easily be changed.
 * Editing Changes in Emacs 24.1
 
 ** Search changes
-
 +++
 *** C-y in Isearch is now bound to isearch-yank-kill, instead of
 isearch-yank-line.
-
 ---
 *** M-y in Isearch is now bound to isearch-yank-pop, instead of
 isearch-yank-kill.
-
 +++
 *** M-s C-e in Isearch is now bound to isearch-yank-line.
 
@@ -850,6 +847,7 @@ bidirectional editing introduced in Emacs 24.  If you need the
 bidirectional properties of a character, use `get-char-code-property'
 with the last argument `bidi-class'.
 
++++
 ** `copy-directory' now copies the source directory as a subdirectory
 of the target directory, if the latter is an existing directory.  The
 new optional arg COPY-CONTENTS, if non-nil, makes the function copy