[Emacs-diffs] /srv/bzr/emacs/trunk r105605: Document copy-directory and related changes in manuals.

[Chong Yidong]

------------------------------------------------------------
revno: 105605
committer: Chong Yidong <address@hidden>
branch nick: trunk
timestamp: Sun 2011-08-28 17:07:10 -0400
message:
  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.
modified:
  doc/emacs/ChangeLog
  doc/emacs/buffers.texi
  doc/emacs/display.texi
  doc/emacs/emacs.texi
  doc/emacs/files.texi
  doc/lispref/ChangeLog
  doc/lispref/files.texi
  etc/NEWS

=== modified file 'doc/emacs/ChangeLog'
--- a/doc/emacs/ChangeLog       2011-08-28 20:22:10 +0000
+++ b/doc/emacs/ChangeLog       2011-08-28 21:07:10 +0000
@@ -1,7 +1,12 @@
 2011-08-28  Chong Yidong  <address@hidden>
 
+       * 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.
 

=== modified file 'doc/emacs/buffers.texi'
--- a/doc/emacs/buffers.texi    2011-06-06 19:43:39 +0000
+++ b/doc/emacs/buffers.texi    2011-08-28 21:07:10 +0000
@@ -285,16 +285,6 @@
 switch to some other buffer before using the command, in order for it
 to make a different buffer.)
 
address@hidden 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
address@hidden, 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}.

=== modified file 'doc/emacs/display.texi'
--- a/doc/emacs/display.texi    2011-08-25 16:13:59 +0000
+++ b/doc/emacs/display.texi    2011-08-28 21:07:10 +0000
@@ -17,6 +17,7 @@
 * 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 @@
 if you enable the command, confirmation will no longer be required for
 it.  @xref{Disabling}.
 
address@hidden View Mode
address@hidden View Mode
address@hidden View mode
address@hidden 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
address@hidden disables View mode, keeping the current buffer and position.
+
address@hidden view-buffer
address@hidden 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

=== modified file 'doc/emacs/emacs.texi'
--- a/doc/emacs/emacs.texi      2011-08-28 18:49:59 +0000
+++ b/doc/emacs/emacs.texi      2011-08-28 21:07:10 +0000
@@ -345,6 +345,7 @@
 * 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.

=== modified file 'doc/emacs/files.texi'
--- a/doc/emacs/files.texi      2011-08-28 20:22:10 +0000
+++ b/doc/emacs/files.texi      2011-08-28 21:07:10 +0000
@@ -1503,59 +1503,18 @@
   Emacs has commands for performing many other operations on files.
 All operate on one file; they do not accept wildcard file names.
 
address@hidden view-file
address@hidden viewing
address@hidden View mode
address@hidden 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}.
-
address@hidden C-x i
address@hidden 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}).
-
address@hidden 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}).
-
address@hidden 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
address@hidden 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
address@hidden (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 @@
 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
address@hidden  The variable
address@hidden 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.
address@hidden
+
address@hidden copy-file
address@hidden copying files
+  @kbd{M-x copy-file} reads the file @var{old} and writes a new file
+named @var{new} with the same contents.
+
address@hidden copy-directory
+  @kbd{M-x copy-directory} copies directories, similar to the
address@hidden -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
address@hidden 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
address@hidden  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
address@hidden 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
address@hidden 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.
-
address@hidden copy-file
address@hidden copy-directory
address@hidden 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 @@
 @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.
+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.
+
address@hidden C-x i
address@hidden 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}).
+
address@hidden 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}).
+
address@hidden 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
address@hidden applies to these commands, as well
+as saving files; see @ref{Customize Save}.
 
 @findex set-file-modes
 @cindex file modes

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2011-08-28 20:22:10 +0000
+++ b/doc/lispref/ChangeLog     2011-08-28 21:07:10 +0000
@@ -1,7 +1,7 @@
 2011-08-28  Chong Yidong  <address@hidden>
 
-       * 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.

=== modified file 'doc/lispref/files.texi'
--- a/doc/lispref/files.texi    2011-08-28 20:22:10 +0000
+++ b/doc/lispref/files.texi    2011-08-28 21:07:10 +0000
@@ -2514,7 +2514,7 @@
 @code{mkdir} is an alias for this.
 @end deffn
 
address@hidden Command copy-directory dirname newname &optional keep-time 
parents
address@hidden 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 @@
 It always sets the file modes of the copied files to match the
 corresponding original file.
 
-The third arg @var{keep-time} address@hidden means to preserve the
+The third argument @var{keep-time} address@hidden means to preserve the
 modification time of the copied files.  A prefix arg makes
 @var{keep-time} address@hidden
 
-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 address@hidden, 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

=== modified file 'etc/NEWS'
--- a/etc/NEWS  2011-08-28 20:22:10 +0000
+++ b/etc/NEWS  2011-08-28 21:07:10 +0000
@@ -384,15 +384,12 @@
 * 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 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