[Emacs-diffs] /srv/bzr/emacs/trunk r108679: Misc doc fixes for Dired.

[Chong Yidong]

------------------------------------------------------------
revno: 108679
committer: Chong Yidong <address@hidden>
branch nick: trunk
timestamp: Fri 2012-06-22 15:30:33 +0800
message:
  Misc doc fixes for Dired.
  
  * dired-aux.el (dired-do-create-files): Doc fix (Bug#11327).
  (dired-create-files): Doc fix (Bug#11329).
  (dired-do-copy): Doc fix (Bug#11334).
  (dired-mark-read-string): Doc fix (Bug#11553).
  
  * dired.el (dired-recursive-copies, dired-recursive-deletes): Doc
  fix (Bug#11326).
  (dired-make-relative): Doc fix (Bug#11332).  Remove unused arg.
  (dired-dwim-target): Doc fix.
  
  * wdired.el (wdired-mode): Doc fix.
modified:
  lisp/ChangeLog
  lisp/dired-aux.el
  lisp/dired.el
  lisp/wdired.el

=== modified file 'lisp/ChangeLog'
--- a/lisp/ChangeLog    2012-06-22 07:01:32 +0000
+++ b/lisp/ChangeLog    2012-06-22 07:30:33 +0000
@@ -1,3 +1,17 @@
+2012-06-22  Chong Yidong  <address@hidden>
+
+       * dired-aux.el (dired-do-create-files): Doc fix (Bug#11327).
+       (dired-create-files): Doc fix (Bug#11329).
+       (dired-do-copy): Doc fix (Bug#11334).
+       (dired-mark-read-string): Doc fix (Bug#11553).
+
+       * dired.el (dired-recursive-copies, dired-recursive-deletes): Doc
+       fix (Bug#11326).
+       (dired-make-relative): Doc fix (Bug#11332).  Remove unused arg.
+       (dired-dwim-target): Doc fix.
+
+       * wdired.el (wdired-mode): Doc fix.
+
 2012-06-22  Glenn Morris  <address@hidden>
 
        * pcmpl-rpm.el (pcmpl-rpm): New group.

=== modified file 'lisp/dired-aux.el'
--- a/lisp/dired-aux.el 2012-04-17 01:52:00 +0000
+++ b/lisp/dired-aux.el 2012-06-22 07:30:33 +0000
@@ -395,16 +395,15 @@
 
 INITIAL, if non-nil, is the initial minibuffer input.
 OP-SYMBOL is an operation symbol (see `dired-no-confirm').
-ARG is normally the prefix argument for the calling command.
-FILES should be a list of file names.
-
-DEFAULT-VALUE, if non-nil, should be a \"standard\" value or list
-of such values, available via history commands.  Note that if the
-user enters empty input, this function returns the empty string,
-not DEFAULT-VALUE.
-
-Optional argument COLLECTION is a collection of possible completions,
-suitable for use by `completing-read'."
+ARG is normally the prefix argument for the calling command;
+it is passed as the first argument to `dired-mark-prompt'.
+FILES should be a list of marked files' names.
+
+Optional arg DEFAULT-VALUE is a default value or list of default
+values, passed as the seventh arg to `completing-read'.
+
+Optional arg COLLECTION is a collection of possible completions,
+passed as the second arg to `completing-read'."
   (dired-mark-pop-up nil op-symbol files
                     'completing-read
                     (format prompt (dired-mark-prompt arg files))
@@ -1408,9 +1407,9 @@
 argument, the name of an old file, and returning either the
 corresponding new file name or nil to skip.
 
-Optional MARKER-CHAR is a character with which to mark every
-newfile's entry, or t to use the current marker character if the
-old file was marked."
+If optional argument MARKER-CHAR is non-nil, mark each
+newly-created file's Dired entry with the character MARKER-CHAR,
+or with the current marker character if MARKER-CHAR is t."
   (let (dired-create-files-failures failures
        skipped (success-count 0) (total (length fn-list)))
     (let (to overwrite-query
@@ -1513,10 +1512,11 @@
                                        &optional marker-char op1
                                        how-to)
   "Create a new file for each marked file.
-Prompts user for target, which is a directory in which to create
-  the new files.  Target may also be a plain file if only one marked
-  file exists.  The way the default for the target directory is
-  computed depends on the value of `dired-dwim-target-directory'.
+Prompt user for a target directory in which to create the new
+  files.  The target may also be a non-directory file, if only
+  one file is marked.  The initial suggestion for target is the
+  Dired buffer's current directory (or, if `dired-dwim-target' is
+  non-nil, the current directory of a neighboring Dired window).
 OP-SYMBOL is the symbol for the operation.  Function `dired-mark-pop-up'
   will determine whether pop-ups are appropriate for this OP-SYMBOL.
 FILE-CREATOR and OPERATION as in `dired-create-files'.
@@ -1721,16 +1721,21 @@
 ;;;###autoload
 (defun dired-do-copy (&optional arg)
   "Copy all marked (or next ARG) files, or copy the current file.
-This normally preserves the last-modified date when copying.
-When operating on just the current file, you specify the new name.
-When operating on multiple or marked files, you specify a directory,
-and new copies of these files are made in that directory
-with the same names that the files currently have.  The default
-suggested for the target directory depends on the value of
-`dired-dwim-target', which see.
-
-This command copies symbolic links by creating new ones,
-like `cp -d'."
+When operating on just the current file, prompt for the new name.
+
+When operating on multiple or marked files, prompt for a target
+directory, and make the new copies in that directory, with the
+same names as the original files.  The initial suggestion for the
+target directory is the Dired buffer's current directory (or, if
+`dired-dwim-target' is non-nil, the current directory of a
+neighboring Dired window).
+
+If `dired-copy-preserve-time' is non-nil, this command preserves
+the modification time of each old file in the copy, similar to
+the \"-p\" option for the \"cp\" shell command.
+
+This command copies symbolic links by creating new ones, similar
+to the \"-d\" option for the \"cp\" shell command."
   (interactive "P")
   (let ((dired-recursive-copies dired-recursive-copies))
     (dired-do-create-files 'copy (function dired-copy-file)
@@ -1996,9 +2001,10 @@
 
 ;;;###autoload
 (defun dired-insert-subdir (dirname &optional switches no-error-if-not-dir-p)
-  "Insert this subdirectory into the same dired buffer.
-If it is already present, overwrites previous entry,
-  else inserts it at its natural place (as `ls -lR' would have done).
+  "Insert this subdirectory into the same Dired buffer.
+If it is already present, overwrite the previous entry;
+  otherwise, insert it at its natural place (as `ls -lR' would
+  have done).
 With a prefix arg, you may edit the `ls' switches used for this listing.
   You can add `R' to the switches to expand the whole tree starting at
   this subdirectory.

=== modified file 'lisp/dired.el'
--- a/lisp/dired.el     2012-06-02 10:56:09 +0000
+++ b/lisp/dired.el     2012-06-22 07:30:33 +0000
@@ -170,8 +170,9 @@
 
 (defcustom dired-dwim-target nil
   "If non-nil, Dired tries to guess a default target directory.
-This means: if there is a dired buffer displayed in the next window,
-use its current subdir, instead of the current subdir of this dired buffer.
+This means: if there is a Dired buffer displayed in the next
+window, use its current directory, instead of this Dired buffer's
+current directory.
 
 The target is used in the prompt for file copy, rename etc."
   :type 'boolean
@@ -2209,10 +2210,11 @@
   ;; dired-get-filename.
   (concat (or dir default-directory) file))
 
-(defun dired-make-relative (file &optional dir _ignore)
+(defun dired-make-relative (file &optional dir)
   "Convert FILE (an absolute file name) to a name relative to DIR.
-If this is impossible, return FILE unchanged.
-DIR must be a directory name, not a file name."
+If DIR is omitted or nil, it defaults to `default-directory'.
+If FILE is not in the directory tree of DIR, return FILE
+unchanged."
   (or dir (setq dir default-directory))
   ;; This case comes into play if default-directory is set to
   ;; use ~.
@@ -2220,8 +2222,6 @@
       (setq dir (expand-file-name dir)))
   (if (string-match (concat "^" (regexp-quote dir)) file)
       (substring file (match-end 0))
-;;;  (or no-error
-;;;    (error "%s: not in directory tree growing at %s" file dir))
     file))
 
 ;;; Functions for finding the file name in a dired buffer line.
@@ -2467,8 +2467,6 @@
                                                  dired-subdir-alist))))
           cur-dir))))
 
-;(defun dired-get-subdir-min (elt)
-;  (cdr elt))
 ;; can't use macro,  must be redefinable for other alist format in dired-nstd.
 (defalias 'dired-get-subdir-min 'cdr)
 
@@ -2730,12 +2728,14 @@
 ;; Deleting files
 
 (defcustom dired-recursive-deletes 'top
-  "Decide whether recursive deletes are allowed.
-A value of nil means no recursive deletes.
-`always' means delete recursively without asking.  This is DANGEROUS!
-`top' means ask for each directory at top level, but delete its subdirectories
-without asking.
-Anything else means ask for each directory."
+  "Whether Dired deletes directories recursively.
+If nil, Dired will not delete non-empty directories.
+`always' means to delete non-empty directories recursively,
+without asking.  This is dangerous!
+`top' means to ask for each top-level directory specified by the
+Dired deletion command, and delete its subdirectories without
+asking.
+Any other value means to ask for each directory."
   :type '(choice :tag "Delete non-empty directories"
                 (const :tag "Yes" always)
                 (const :tag "No--only delete empty directories" nil)
@@ -3577,11 +3577,11 @@
 ;;;;  Drag and drop support
 
 (defcustom dired-recursive-copies 'top
-  "Decide whether recursive copies are allowed.
-A value of nil means no recursive copies.
-`always' means copy recursively without asking.
-`top' means ask for each directory at top level.
-Anything else means ask for each directory."
+  "Whether Dired copies directories recursively.
+If nil, never copy recursively.
+`always' means to copy recursively without asking.
+`top' means to ask for each directory at top level.
+Any other value means to ask for each directory."
   :type '(choice :tag "Copy directories"
                 (const :tag "No recursive copies" nil)
                 (const :tag "Ask for each directory" t)
@@ -3739,7 +3739,7 @@
 ;;;;;;  dired-run-shell-command dired-do-shell-command 
dired-do-async-shell-command
 ;;;;;;  dired-clean-directory dired-do-print dired-do-touch dired-do-chown
 ;;;;;;  dired-do-chgrp dired-do-chmod dired-compare-directories 
dired-backup-diff
-;;;;;;  dired-diff) "dired-aux" "dired-aux.el" 
"de7e4c64718c8ba8438a6397a460bf23")
+;;;;;;  dired-diff) "dired-aux" "dired-aux.el" 
"91d39bd8f7e9ce93dc752fe74bea78c2")
 ;;; Generated autoloads from dired-aux.el
 
 (autoload 'dired-diff "dired-aux" "\
@@ -3979,16 +3979,21 @@
 
 (autoload 'dired-do-copy "dired-aux" "\
 Copy all marked (or next ARG) files, or copy the current file.
-This normally preserves the last-modified date when copying.
-When operating on just the current file, you specify the new name.
-When operating on multiple or marked files, you specify a directory,
-and new copies of these files are made in that directory
-with the same names that the files currently have.  The default
-suggested for the target directory depends on the value of
-`dired-dwim-target', which see.
-
-This command copies symbolic links by creating new ones,
-like `cp -d'.
+When operating on just the current file, prompt for the new name.
+
+When operating on multiple or marked files, prompt for a target
+directory, and make the new copies in that directory, with the
+same names as the original files.  The initial suggestion for the
+target directory is the Dired buffer's current directory (or, if
+`dired-dwim-target' is non-nil, the current directory of a
+neighboring Dired window).
+
+If `dired-copy-preserve-time' is non-nil, this command preserves
+the modification time of each old file in the copy, similar to
+the \"-p\" option for the \"cp\" shell command.
+
+This command copies symbolic links by creating new ones, similar
+to the \"-d\" option for the \"cp\" shell command.
 
 \(fn &optional ARG)" t nil)
 
@@ -4091,9 +4096,10 @@
 \(fn DIRNAME &optional SWITCHES NO-ERROR-IF-NOT-DIR-P)" t nil)
 
 (autoload 'dired-insert-subdir "dired-aux" "\
-Insert this subdirectory into the same dired buffer.
-If it is already present, overwrites previous entry,
-  else inserts it at its natural place (as `ls -lR' would have done).
+Insert this subdirectory into the same Dired buffer.
+If it is already present, overwrite the previous entry;
+  otherwise, insert it at its natural place (as `ls -lR' would
+  have done).
 With a prefix arg, you may edit the `ls' switches used for this listing.
   You can add `R' to the switches to expand the whole tree starting at
   this subdirectory.

=== modified file 'lisp/wdired.el'
--- a/lisp/wdired.el    2012-01-19 07:21:25 +0000
+++ b/lisp/wdired.el    2012-06-22 07:30:33 +0000
@@ -184,8 +184,8 @@
 
 
 (defun wdired-mode ()
-  "\\<wdired-mode-map>File Names Editing mode.
-
+  "Writable Dired mode.
+\\<wdired-mode-map>
 Press \\[wdired-finish-edit] to make the changes to take effect
 and exit.  To abort the edit, use \\[wdired-abort-changes].