From: Chong Yidong Date: Fri, 22 Jun 2012 07:30:33 +0000 (+0800) Subject: Misc doc fixes for Dired. X-Git-Tag: emacs-24.2.90~1199^2~408 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=c5695d1d098bc4f275cfe4b4492a70779a06de02;p=emacs.git 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. --- 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 + + * 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 * 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 () - "\\File Names Editing mode. - + "Writable Dired mode. +\\ Press \\[wdired-finish-edit] to make the changes to take effect and exit. To abort the edit, use \\[wdired-abort-changes].