From f2b2c752a5920c1152fd70d917e0fc5a3c9728c4 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Sat, 5 Aug 2023 12:13:47 +0300 Subject: [PATCH] Fix documentation of saveplace facilities for Dired * lisp/saveplace.el (save-place-dired-hook, save-place-alist): * lisp/dired.el (dired-initial-position-hook) (dired-initial-position): Doc fixes. (Bug#65055) --- lisp/dired.el | 8 ++++---- lisp/saveplace.el | 14 +++++++++++++- 2 files changed, 17 insertions(+), 5 deletions(-) diff --git a/lisp/dired.el b/lisp/dired.el index d14cf47ffd5..d0af05d68f0 100644 --- a/lisp/dired.el +++ b/lisp/dired.el @@ -346,7 +346,7 @@ with the buffer narrowed to the listing." :type 'boolean) (defcustom dired-initial-position-hook nil - "This hook is used to position the point. + "Hook used to position point in a new Dired listing display. It is run by the function `dired-initial-position'." :group 'dired :type 'hook @@ -3541,9 +3541,9 @@ as returned by `dired-get-filename'. LIMIT is the search limit." ;; FIXME document whatever dired-x is doing. (defun dired-initial-position (dirname) - "Where point should go in a new listing of DIRNAME. -Point is assumed to be at the beginning of new subdir line. -It runs the hook `dired-initial-position-hook'." + "Return position of point in a new listing of DIRNAME. +Point is assumed to be at the beginning of a new subdir line. +Runs the hook `dired-initial-position-hook'." (end-of-line) (and (featurep 'dired-x) dired-find-subdir (dired-goto-subdir dirname)) diff --git a/lisp/saveplace.el b/lisp/saveplace.el index 7512fc87c5d..71cd8b9bc0e 100644 --- a/lisp/saveplace.el +++ b/lisp/saveplace.el @@ -47,6 +47,17 @@ Each element looks like (FILENAME . POSITION); visiting file FILENAME goes automatically to position POSITION rather than the beginning of the buffer. +A list element can also have the form + + (DIRECTORY (dired-filename . FILENAME)) + +where DIRECTORY is the name of a directory ending in a slash, +and FILENAME is the name of a file in that directory. This +format is used for saving places in Dired buffers, see the +function `save-place-dired-hook'; the FILENAME is the file +where point was located in the Dired listing of DIRECTORY +when the place in that buffer was recorded. + This alist is saved between Emacs sessions.") (defcustom save-place-file (locate-user-emacs-file "places" ".emacs-places") @@ -366,7 +377,8 @@ It runs the hook `save-place-after-find-file-hook'." (declare-function dired-goto-file "dired" (file)) (defun save-place-dired-hook () - "Position the point in a Dired buffer." + "Position point in a Dired buffer according to its saved place. +This is run via `dired-initial-position-hook', which see." (or save-place-loaded (save-place-load-alist-from-file)) (let* ((directory (and (derived-mode-p 'dired-mode) (boundp 'dired-subdir-alist) -- 2.39.2