One more doc fix for bug #17362.

[bpt/emacs.git] / lisp / dired.el

diff --git a/lisp/dired.el b/lisp/dired.el
index 48f1b46..1cce5bc 100644 (file)
--- a/lisp/dired.el
+++ b/lisp/dired.el
@@ -1,10 +1,10 @@
 ;;; dired.el --- directory-browsing commands -*- lexical-binding: t -*-
 
 ;;; dired.el --- directory-browsing commands -*- lexical-binding: t -*-
 

-;; Copyright (C) 1985-1986, 1992-1997, 2000-2013 Free Software
+;; Copyright (C) 1985-1986, 1992-1997, 2000-2014 Free Software

 ;; Foundation, Inc.
 
 ;; Author: Sebastian Kremer <sk@thp.uni-koeln.de>
 ;; Foundation, Inc.
 
 ;; Author: Sebastian Kremer <sk@thp.uni-koeln.de>

-;; Maintainer: FSF
+;; Maintainer: emacs-devel@gnu.org

 ;; Keywords: files
 ;; Package: emacs
 
 ;; Keywords: files
 ;; Package: emacs
 


@@ -34,6 +34,9 @@
 
 ;;; Code:
 
 
 ;;; Code:
 

+(declare-function dired-buffer-more-recently-used-p
+                 "dired-x" (buffer1 buffer2))
+

 ;;; Customizable variables
 
 (defgroup dired nil
 ;;; Customizable variables
 
 (defgroup dired nil


@@ -217,7 +220,7 @@ with the buffer narrowed to the listing."
 ;; Note this can't simply be run inside function `dired-ls' as the hook
 ;; functions probably depend on the dired-subdir-alist to be OK.
 
 ;; Note this can't simply be run inside function `dired-ls' as the hook
 ;; functions probably depend on the dired-subdir-alist to be OK.
 

-(defcustom dired-initial-point-hook nil
+(defcustom dired-initial-position-hook nil

   "This hook is used to position the point.
 It is run the function `dired-initial-position'."
   :group 'dired
   "This hook is used to position the point.
 It is run the function `dired-initial-position'."
   :group 'dired


@@ -238,13 +241,13 @@ new Dired buffers."
   :group 'dired)
 
 (defcustom dired-hide-details-hide-symlink-targets t
   :group 'dired)
 
 (defcustom dired-hide-details-hide-symlink-targets t

-  "If non-nil, `dired-hide-details-mode' hides symbolic link targets."
+  "Non-nil means `dired-hide-details-mode' hides symbolic link targets."

   :type 'boolean
   :version "24.4"
   :group 'dired)
 
 (defcustom dired-hide-details-hide-information-lines t
   :type 'boolean
   :version "24.4"
   :group 'dired)
 
 (defcustom dired-hide-details-hide-information-lines t

-  "Non-nil means hide lines other than header and file/dir lines."
+  "Non-nil means `dired-hide-details-mode' hides all but header and file lines."

   :type 'boolean
   :version "24.4"
   :group 'dired)
   :type 'boolean
   :version "24.4"
   :group 'dired)


@@ -631,7 +634,8 @@ Optional second argument ARG, if non-nil, specifies files near
  point instead of marked files.  It usually comes from the prefix
  argument.
   If ARG is an integer, use the next ARG files.
  point instead of marked files.  It usually comes from the prefix
  argument.
   If ARG is an integer, use the next ARG files.

-  Any other non-nil value means to use the current file instead.
+  If ARG is any other non-nil value, return the current file name.
+  If no files are marked, and ARG is nil, also return the current file name.

 Optional third argument FILTER, if non-nil, is a function to select
   some of the files--those for which (funcall FILTER FILENAME) is non-nil.
 
 Optional third argument FILTER, if non-nil, is a function to select
   some of the files--those for which (funcall FILTER FILENAME) is non-nil.
 


@@ -730,7 +734,9 @@ Don't use that together with FILTER."
 
 (defun dired-file-name-at-point ()
   "Try to get a file name at point in the current dired buffer.
 
 (defun dired-file-name-at-point ()
   "Try to get a file name at point in the current dired buffer.

-This hook is intended to be put in `file-name-at-point-functions'."
+This hook is intended to be put in `file-name-at-point-functions'.
+Note that it returns an abbreviated name that can't be used
+as an argument to `dired-goto-file'."

   (let ((filename (dired-get-filename nil t)))
     (when filename
       (if (file-directory-p filename)
   (let ((filename (dired-get-filename nil t)))
     (when filename
       (if (file-directory-p filename)


@@ -1242,26 +1248,27 @@ see `dired-use-ls-dired' for more details.")
   (save-excursion
     (goto-char beg)
     (while (< (point) end)
   (save-excursion
     (goto-char beg)
     (while (< (point) end)

-      (condition-case nil
-         (if (not (dired-move-to-filename))
+      (ignore-errors
+       (if (not (dired-move-to-filename))
+           (unless (or (looking-at-p "^$")
+                       (looking-at-p dired-subdir-regexp))

              (put-text-property (line-beginning-position)
                                 (1+ (line-end-position))
              (put-text-property (line-beginning-position)
                                 (1+ (line-end-position))

-                                'invisible 'dired-hide-details-information)
-           (put-text-property (+ (line-beginning-position) 1) (1- (point))
-                              'invisible 'dired-hide-details-detail)
-           (add-text-properties
-            (point)
-            (progn
-              (dired-move-to-end-of-filename)
-              (point))
-            '(mouse-face
-              highlight
-              dired-filename t
-              help-echo "mouse-2: visit this file in other window"))
-           (when (< (+ (point) 4) (line-end-position))
-             (put-text-property (+ (point) 4) (line-end-position)
-                                'invisible 'dired-hide-details-link)))
-       (error nil))
+                                'invisible 'dired-hide-details-information))
+         (put-text-property (+ (line-beginning-position) 1) (1- (point))
+                            'invisible 'dired-hide-details-detail)
+         (add-text-properties
+          (point)
+          (progn
+            (dired-move-to-end-of-filename)
+            (point))
+          '(mouse-face
+            highlight
+            dired-filename t
+            help-echo "mouse-2: visit this file in other window"))
+         (when (< (+ (point) 4) (line-end-position))
+           (put-text-property (+ (point) 4) (line-end-position)
+                              'invisible 'dired-hide-details-link))))

       (forward-line 1))))
 \f
 ;; Reverting a dired buffer
       (forward-line 1))))
 \f
 ;; Reverting a dired buffer


@@ -1401,11 +1408,9 @@ Do so according to the former subdir alist OLD-SUBDIR-ALIST."
          (setq elt (car old-subdir-alist)
                old-subdir-alist (cdr old-subdir-alist)
                dir (car elt))
          (setq elt (car old-subdir-alist)
                old-subdir-alist (cdr old-subdir-alist)
                dir (car elt))

-         (condition-case ()
-             (progn
-               (dired-uncache dir)
-               (dired-insert-subdir dir))
-           (error nil))))))
+         (ignore-errors
+           (dired-uncache dir)
+           (dired-insert-subdir dir))))))

 
 (defun dired-uncache (dir)
   "Remove directory DIR from any directory cache."
 
 (defun dired-uncache (dir)
   "Remove directory DIR from any directory cache."


@@ -1783,22 +1788,22 @@ Do so according to the former subdir alist OLD-SUBDIR-ALIST."
     (define-key map
       [menu-bar operate epa-dired-do-decrypt]
       '(menu-item "Decrypt..." epa-dired-do-decrypt
     (define-key map
       [menu-bar operate epa-dired-do-decrypt]
       '(menu-item "Decrypt..." epa-dired-do-decrypt

-                 :help "Decrypt file at cursor"))
+                 :help "Decrypt current or marked files"))

 
     (define-key map
       [menu-bar operate epa-dired-do-verify]
       '(menu-item "Verify" epa-dired-do-verify
 
     (define-key map
       [menu-bar operate epa-dired-do-verify]
       '(menu-item "Verify" epa-dired-do-verify

-                 :help "Verify digital signature of file at cursor"))
+                 :help "Verify digital signature of current or marked files"))

 
     (define-key map
       [menu-bar operate epa-dired-do-sign]
       '(menu-item "Sign..." epa-dired-do-sign
 
     (define-key map
       [menu-bar operate epa-dired-do-sign]
       '(menu-item "Sign..." epa-dired-do-sign

-                 :help "Create digital signature of file at cursor"))
+                 :help "Create digital signature of current or marked files"))

 
     (define-key map
       [menu-bar operate epa-dired-do-encrypt]
       '(menu-item "Encrypt..." epa-dired-do-encrypt
 
     (define-key map
       [menu-bar operate epa-dired-do-encrypt]
       '(menu-item "Encrypt..." epa-dired-do-encrypt

-                 :help "Encrypt file at cursor"))
+                 :help "Encrypt current or marked files"))

 
     (define-key map [menu-bar operate dashes-3]
       '("--"))
 
     (define-key map [menu-bar operate dashes-3]
       '("--"))


@@ -2043,7 +2048,9 @@ Optional prefix ARG says how many lines to move; default is one line."
 (defun dired-up-directory (&optional other-window)
   "Run Dired on parent directory of current directory.
 Find the parent directory either in this buffer or another buffer.
 (defun dired-up-directory (&optional other-window)
   "Run Dired on parent directory of current directory.
 Find the parent directory either in this buffer or another buffer.

-Creates a buffer if necessary."
+Creates a buffer if necessary.
+If OTHER-WINDOW (the optional prefix arg), display the parent
+directory in another window."

   (interactive "P")
   (let* ((dir (dired-current-directory))
         (up (file-name-directory (directory-file-name dir))))
   (interactive "P")
   (let* ((dir (dired-current-directory))
         (up (file-name-directory (directory-file-name dir))))


@@ -2131,7 +2138,8 @@ Otherwise, display it in another buffer."
 (defun dired-display-file ()
   "In Dired, display this file or directory in another window."
   (interactive)
 (defun dired-display-file ()
   "In Dired, display this file or directory in another window."
   (interactive)

-  (display-buffer (find-file-noselect (dired-get-file-for-visit))))
+  (display-buffer (find-file-noselect (dired-get-file-for-visit))
+                 t))

 \f
 ;;; Functions for extracting and manipulating file names in Dired buffers.
 
 \f
 ;;; Functions for extracting and manipulating file names in Dired buffers.
 


@@ -2265,10 +2273,13 @@ unchanged."
       (substring file (match-end 0))
     file))
 \f
       (substring file (match-end 0))
     file))
 \f

-;;; Minor mode for hiding details
-;;;###autoload

 (define-minor-mode dired-hide-details-mode
 (define-minor-mode dired-hide-details-mode

-  "Hide details in Dired mode."
+  "Toggle visibility of detailed information in current Dired buffer.
+When this minor mode is enabled, details such as file ownership and
+permissions are hidden from view.
+
+See options: `dired-hide-details-hide-symlink-targets' and
+`dired-hide-details-hide-information-lines'."

   :group 'dired
   (unless (derived-mode-p 'dired-mode)
     (error "Not a Dired buffer"))
   :group 'dired
   (unless (derived-mode-p 'dired-mode)
     (error "Not a Dired buffer"))


@@ -2763,7 +2774,7 @@ It runs the hook `dired-initial-position-hook'."
   (and (featurep 'dired-x) dired-find-subdir
        (dired-goto-subdir dirname))
   (if dired-trivial-filenames (dired-goto-next-nontrivial-file))
   (and (featurep 'dired-x) dired-find-subdir
        (dired-goto-subdir dirname))
   (if dired-trivial-filenames (dired-goto-next-nontrivial-file))

-  (run-hooks 'dired-initial-point-hook))
+  (run-hooks 'dired-initial-position-hook))

 \f
 ;; These are hooks which make tree dired work.
 ;; They are in this file because other parts of dired need to call them.
 \f
 ;; These are hooks which make tree dired work.
 ;; They are in this file because other parts of dired need to call them.


@@ -2898,11 +2909,7 @@ non-empty directories is allowed."
   (let* ((files (mapcar (function car) l))
         (count (length l))
         (succ 0)
   (let* ((files (mapcar (function car) l))
         (count (length l))
         (succ 0)

-        (trashing (and trash delete-by-moving-to-trash))
-        (progress-reporter
-         (make-progress-reporter
-          (if trashing "Trashing..." "Deleting...")
-          succ count)))
+        (trashing (and trash delete-by-moving-to-trash)))

     ;; canonicalize file list for pop up
     (setq files (nreverse (mapcar (function dired-make-relative) files)))
     (if (dired-mark-pop-up
     ;; canonicalize file list for pop up
     (setq files (nreverse (mapcar (function dired-make-relative) files)))
     (if (dired-mark-pop-up


@@ -2911,7 +2918,11 @@ non-empty directories is allowed."
                 (if trashing "Trash" "Delete")
                 (dired-mark-prompt arg files)))
        (save-excursion
                 (if trashing "Trash" "Delete")
                 (dired-mark-prompt arg files)))
        (save-excursion

-         (let (failures);; files better be in reverse order for this loop!
+         (let ((progress-reporter
+                (make-progress-reporter
+                 (if trashing "Trashing..." "Deleting...")
+                 succ count))
+               failures) ;; files better be in reverse order for this loop!

            (while l
              (goto-char (cdr (car l)))
              (let ((inhibit-read-only t))
            (while l
              (goto-char (cdr (car l)))
              (let ((inhibit-read-only t))


@@ -2924,7 +2935,7 @@ non-empty directories is allowed."
                      (dired-fun-in-all-buffers
                       (file-name-directory fn) (file-name-nondirectory fn)
                       (function dired-delete-entry) fn))
                      (dired-fun-in-all-buffers
                       (file-name-directory fn) (file-name-nondirectory fn)
                       (function dired-delete-entry) fn))

-                 (error;; catch errors from failed deletions
+                 (error ;; catch errors from failed deletions

                   (dired-log "%s\n" err)
                   (setq failures (cons (car (car l)) failures)))))
              (setq l (cdr l)))
                   (dired-log "%s\n" err)
                   (setq failures (cons (car (car l)) failures)))))
              (setq l (cdr l)))


@@ -3079,24 +3090,23 @@ argument or confirmation)."
       (apply function args)
     (let ((buffer (get-buffer-create (or buffer-or-name " *Marked Files*"))))
       (with-current-buffer buffer
       (apply function args)
     (let ((buffer (get-buffer-create (or buffer-or-name " *Marked Files*"))))
       (with-current-buffer buffer

-       (let ((split-height-threshold 0))
-         (with-temp-buffer-window
-          buffer
-          (cons 'display-buffer-below-selected
-                '((window-height . fit-window-to-buffer)))
-          #'(lambda (window _value)
-              (with-selected-window window
-                (unwind-protect
-                    (apply function args)
-                  (when (window-live-p window)
-                    (quit-restore-window window 'kill)))))
-          ;; Handle (t FILE) just like (FILE), here.  That value is
-          ;; used (only in some cases), to mean just one file that was
-          ;; marked, rather than the current line file.
-          (dired-format-columns-of-files
-           (if (eq (car files) t) (cdr files) files))
-          (remove-text-properties (point-min) (point-max)
-                                  '(mouse-face nil help-echo nil))))))))
+       (with-current-buffer-window
+        buffer
+        (cons 'display-buffer-below-selected
+              '((window-height . fit-window-to-buffer)))
+        #'(lambda (window _value)
+            (with-selected-window window
+              (unwind-protect
+                  (apply function args)
+                (when (window-live-p window)
+                  (quit-restore-window window 'kill)))))
+        ;; Handle (t FILE) just like (FILE), here.  That value is
+        ;; used (only in some cases), to mean just one file that was
+        ;; marked, rather than the current line file.
+        (dired-format-columns-of-files
+         (if (eq (car files) t) (cdr files) files))
+        (remove-text-properties (point-min) (point-max)
+                                '(mouse-face nil help-echo nil)))))))

 
 (defun dired-format-columns-of-files (files)
   (let ((beg (point)))
 
 (defun dired-format-columns-of-files (files)
   (let ((beg (point)))


@@ -3136,7 +3146,9 @@ argument or confirmation)."
   (save-excursion (not (dired-move-to-filename))))
 
 (defun dired-next-marked-file (arg &optional wrap opoint)
   (save-excursion (not (dired-move-to-filename))))
 
 (defun dired-next-marked-file (arg &optional wrap opoint)

-  "Move to the next marked file, wrapping around the end of the buffer."
+  "Move to the next marked file.
+If WRAP is non-nil, wrap around to the beginning of the buffer if
+we reach the end."

   (interactive "p\np")
   (or opoint (setq opoint (point)));; return to where interactively started
   (if (if (> arg 0)
   (interactive "p\np")
   (or opoint (setq opoint (point)));; return to where interactively started
   (if (if (> arg 0)


@@ -3153,7 +3165,9 @@ argument or confirmation)."
       (dired-next-marked-file arg nil opoint))))
 
 (defun dired-prev-marked-file (arg &optional wrap)
       (dired-next-marked-file arg nil opoint))))
 
 (defun dired-prev-marked-file (arg &optional wrap)

-  "Move to the previous marked file, wrapping around the end of the buffer."
+  "Move to the previous marked file.
+If WRAP is non-nil, wrap around to the end of the buffer if we
+reach the beginning of the buffer."

   (interactive "p\np")
   (dired-next-marked-file (- arg) wrap))
 
   (interactive "p\np")
   (dired-next-marked-file (- arg) wrap))
 


@@ -3273,6 +3287,7 @@ As always, hidden subdirs are not affected."
   "History list of regular expressions used in Dired commands.")
 
 (defun dired-read-regexp (prompt &optional default history)
   "History list of regular expressions used in Dired commands.")
 
 (defun dired-read-regexp (prompt &optional default history)

+  "Read a regexp using `read-regexp'."

   (read-regexp prompt default (or history 'dired-regexp-history)))
 
 (defun dired-mark-files-regexp (regexp &optional marker-char)
   (read-regexp prompt default (or history 'dired-regexp-history)))
 
 (defun dired-mark-files-regexp (regexp &optional marker-char)


@@ -3627,6 +3642,7 @@ With a prefix argument, edit the current listing switches instead."
        ;; Remove a switch of the form -XtY for some X and Y.
        (setq dired-actual-switches
              (replace-match "" t t dired-actual-switches 3))))
        ;; Remove a switch of the form -XtY for some X and Y.
        (setq dired-actual-switches
              (replace-match "" t t dired-actual-switches 3))))

+

     ;; Now, if we weren't sorting by date before, add the -t switch.
     ;; Some simple-minded ls implementations (eg ftp servers) only
     ;; allow a single option string, so try not to add " -t" if possible.
     ;; Now, if we weren't sorting by date before, add the -t switch.
     ;; Some simple-minded ls implementations (eg ftp servers) only
     ;; allow a single option string, so try not to add " -t" if possible.


@@ -3833,7 +3849,7 @@ Ask means pop up a menu for the user to select one of copy, move or link."
   (let* ((dired-dir (car misc-data))
          (dir (if (consp dired-dir) (car dired-dir) dired-dir)))
     (if (file-directory-p (file-name-directory dir))
   (let* ((dired-dir (car misc-data))
          (dir (if (consp dired-dir) (car dired-dir) dired-dir)))
     (if (file-directory-p (file-name-directory dir))

-        (progn
+        (with-demoted-errors "Desktop: Problem restoring directory: %S"

           (dired dired-dir)
           ;; The following elements of `misc-data' are the keys
           ;; from `dired-subdir-alist'.
           (dired dired-dir)
           ;; The following elements of `misc-data' are the keys
           ;; from `dired-subdir-alist'.


@@ -3849,7 +3865,7 @@ Ask means pop up a menu for the user to select one of copy, move or link."
 \f
 ;;; Start of automatically extracted autoloads.
 \f
 \f
 ;;; Start of automatically extracted autoloads.
 \f

-;;;### (autoloads nil "dired-aux" "dired-aux.el" "555c067fcab27f5a377536db407803ab")
+;;;### (autoloads nil "dired-aux" "dired-aux.el" "1a8e2a4a9117ab3a2586aa001358d3fb")

 ;;; Generated autoloads from dired-aux.el
 
 (autoload 'dired-diff "dired-aux" "\
 ;;; Generated autoloads from dired-aux.el
 
 (autoload 'dired-diff "dired-aux" "\


@@ -4352,7 +4368,7 @@ instead.
 
 ;;;***
 \f
 
 ;;;***
 \f

-;;;### (autoloads nil "dired-x" "dired-x.el" "1419d865898f84c17f172320e578380c")
+;;;### (autoloads nil "dired-x" "dired-x.el" "291bc6e869bf72c900604c45d40f45ed")

 ;;; Generated autoloads from dired-x.el
 
 (autoload 'dired-jump "dired-x" "\
 ;;; Generated autoloads from dired-x.el
 
 (autoload 'dired-jump "dired-x" "\