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.

4 files changed, 88 insertions, 62 deletions

diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index 6ac1cc95d4d..1119a52c451 100644
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,3 +1,17 @@
+2012-06-22  Chong Yidong  <cyd@gnu.org>
+
+        * 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  <rgm@gnu.org>
 
         * pcmpl-rpm.el (pcmpl-rpm): New group.
diff --git a/lisp/dired-aux.el b/lisp/dired-aux.el
index 8a499c47464..ffd93a85ee8 100644
--- a/lisp/dired-aux.el
+++ b/lisp/dired-aux.el
@@ -395,16 +395,15 @@ Return the user input (a string).
 
 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.
+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.
 
-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 arg DEFAULT-VALUE is a default value or list of default
+values, passed as the seventh arg to `completing-read'.
 
-Optional argument COLLECTION is a collection of possible completions,
-suitable for use by `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 @@ NAME-CONSTRUCTOR should be a function accepting a single
 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 @@ ESC or `q' to not overwrite any of the remaining files,
                                         &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 @@ See HOW-TO argument for `dired-do-create-files'.")
 ;;;###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.
+When operating on just the current file, prompt for the new name.
 
-This command copies symbolic links by creating new ones,
-like `cp -d'."
+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 @@ See Info node `(emacs)Subdir switches' for more details."
 
 ;;;###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.
diff --git a/lisp/dired.el b/lisp/dired.el
index 7428087ca8f..68e1e574a00 100644
--- a/lisp/dired.el
+++ b/lisp/dired.el
@@ -170,8 +170,9 @@ If a character, new links are unconditionally marked with that character."
 
 (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 @@ Optional arg GLOBAL means to replace all matches."
   ;; 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 @@ DIR must be a directory name, not a file name."
       (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 @@ You can then feed the file name(s) to other commands with \\[yank]."
                                                   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 @@ Optional argument means return a file name relative to `default-directory'."
 ;; 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 @@ To be called first in body of `dired-sort-other', etc."
 ;;;;  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 @@ Ask means pop up a menu for the user to select one of copy, move or link."
 ;;;;;;  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 @@ If DIRECTORY already exists, signal an error.
 
 (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.
+When operating on just the current file, prompt for the new name.
 
-This command copies symbolic links by creating new ones,
-like `cp -d'.
+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 @@ See Info node `(emacs)Subdir switches' for more details.
 \(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.
diff --git a/lisp/wdired.el b/lisp/wdired.el
index fe5b4ef7b79..f65574c26ad 100644
--- a/lisp/wdired.el
+++ b/lisp/wdired.el
@@ -184,8 +184,8 @@ program `dired-chmod-program', which must exist."
 
 
 (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].