[Emacs-diffs] master 5c3d0ce: New manual section "Copying and Naming"

[Paul Eggert]

branch: master
commit 5c3d0ce3e09bf070bb3c89caa9d88f25d4a39283
Author: Paul Eggert <address@hidden>
Commit: Paul Eggert <address@hidden>

    New manual section "Copying and Naming"
    
    * doc/emacs/files.texi (Copying and Naming):
    New section, split off from Misc File Ops and containing the
    operations that copy, name or rename files.  This fixes some
    confusion caused by the incorrect phrase "The same rule applies
    to all the remaining commands in this section" in the old manual.
    This change does not affect the confusion about directories (see
    Bug#27986 for ongoing discussion).
---
 doc/emacs/custom.texi |   2 +-
 doc/emacs/emacs.texi  |   1 +
 doc/emacs/files.texi  | 123 +++++++++++++++++++++++++++-----------------------
 3 files changed, 69 insertions(+), 57 deletions(-)

diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi
index 1c9c14a..824fb6e 100644
--- a/doc/emacs/custom.texi
+++ b/doc/emacs/custom.texi
@@ -1710,7 +1710,7 @@ and mouse events:
 specify the key sequence.  Using a string is simpler, but only works
 for @acronym{ASCII} characters and Meta-modified @acronym{ASCII}
 characters.  For example, here's how to bind @kbd{C-x M-l} to
address@hidden (@pxref{Misc File Ops}):
address@hidden (@pxref{Copying and Naming}):
 
 @example
 (global-set-key "\C-x\M-l" 'make-symbolic-link)
diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi
index a3eb422..f3e6c94 100644
--- a/doc/emacs/emacs.texi
+++ b/doc/emacs/emacs.texi
@@ -453,6 +453,7 @@ File Handling
 * Directories::         Creating, deleting, and listing file directories.
 * Comparing Files::     Finding where two files differ.
 * Diff Mode::           Mode for editing file differences.
+* Copying and Naming::  Copying, naming and renaming files.
 * Misc File Ops::       Other things you can do on files.
 * Compressed Files::    Accessing compressed files.
 * File Archives::       Operating on tar, zip, jar etc. archive files.
diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi
index 0b4e8ed..7bca988 100644
--- a/doc/emacs/files.texi
+++ b/doc/emacs/files.texi
@@ -33,6 +33,7 @@ on file directories.
 * Directories::         Creating, deleting, and listing file directories.
 * Comparing Files::     Finding where two files differ.
 * Diff Mode::           Mode for editing file differences.
+* Copying and Naming::  Copying, naming and renaming files.
 * Misc File Ops::       Other things you can do on files.
 * Compressed Files::    Accessing compressed files.
 * File Archives::       Operating on tar, zip, jar etc. archive files.
@@ -1545,6 +1546,72 @@ decide whether to save the changes (the list of modified 
files is
 displayed in the echo area).  With a prefix argument, it tries to
 modify the original source files rather than the patched source files.
 
address@hidden Copying and Naming
address@hidden Copying, Naming and Renaming Files
+
+  Emacs has several commands for copying, naming, and renaming files.
+All of them read two file names @var{old} and @var{new} using the
+minibuffer, and then copy or adjust a file's name accordingly; they do
+not accept wildcard file names.
+
+In all these commands, 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 @key{RET} ~/foo @key{RET}
address@hidden FIXME: This part of the example should be '/tmp/' not '/tmp',
address@hidden because '/tmp' is not "just a directory name".
+/tmp
address@hidden
address@hidden renames @file{~/foo} to @file{/tmp/foo}.  All these
+commands ask for confirmation when the new file name already exists,
+too.
+
address@hidden copy-file
address@hidden copying files
+  @kbd{M-x copy-file} copies the contents of the file @var{old} to the
+file @var{new}.
+
address@hidden copy-directory
+  @kbd{M-x copy-directory} copies directories, similar to the
address@hidden -r} shell command.  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}.
+
address@hidden renaming files
address@hidden rename-file
+  @kbd{M-x rename-file} 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.
+
address@hidden
+  If a file is under version control (@pxref{Version Control}), you
+should rename it using @kbd{M-x vc-rename-file} instead of @kbd{M-x
+rename-file}.  @xref{VC Delete/Rename}.
address@hidden ifnottex
+
address@hidden add-name-to-file
address@hidden hard links (creation)
+  @kbd{M-x add-name-to-file} adds an additional name to an existing
+file without removing the 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 make-symbolic-link
address@hidden symbolic links (creation)
+  @kbd{M-x make-symbolic-link} creates a symbolic link named
address@hidden, which points at @var{target}.  The effect is that future
+attempts to open file @var{new} will refer to whatever file is named
address@hidden 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.  On MS-Windows, this
+command works only on MS Windows Vista and later.
+
 @node Misc File Ops
 @section Miscellaneous File Operations
 
@@ -1581,62 +1648,6 @@ should delete it using @kbd{M-x vc-delete-file} instead 
of @kbd{M-x
 delete-file}.  @xref{VC Delete/Rename}.
 @end ifnottex
 
address@hidden copy-file
address@hidden copying files
-  @kbd{M-x copy-file} copies the contents of the file @var{old} to the
-file @var{new}.
-
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}.
-
address@hidden renaming files
address@hidden 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
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 @key{RET}
-~/foo @key{RET} /tmp @key{RET}} renames @file{~/foo} to
address@hidden/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.
-
address@hidden
-  If a file is under version control (@pxref{Version Control}), you
-should rename it using @kbd{M-x vc-rename-file} instead of @kbd{M-x
-rename-file}.  @xref{VC Delete/Rename}.
address@hidden ifnottex
-
address@hidden add-name-to-file
address@hidden 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.
-
address@hidden make-symbolic-link
address@hidden symbolic links (creation)
-  @kbd{M-x make-symbolic-link} reads two file names @var{target} and
address@hidden, 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
address@hidden 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.  On MS-Windows, this
-command works only on MS Windows Vista and later.
-
 @kindex C-x i
 @findex insert-file
   @kbd{M-x insert-file} (also @kbd{C-x i}) inserts a copy of the