branch: externals/denote
commit f2a6fed82b357abce5e9c9b7e8caf628426fb941
Author: Protesilaos Stavrou <i...@protesilaos.com>
Commit: Protesilaos Stavrou <i...@protesilaos.com>
Document how to use tree-based file prompt on demand
This is my solution to a request made by Mirko Hernandez on the
possible use of the old Denote file prompt. It is better not to
introduce a user option for this case, nor to keep multiple variants
of the 'denote-file-prompt' in denote.el, as we want to avoid
confusing the users.
Mirko's feedback was provided in issue 121 on the GitHub mirror:
<https://github.com/protesilaos/denote/issues/121>.
---
README.org | 40 ++++++++++++++++++++++++++++++++++++++++
1 file changed, 40 insertions(+)
diff --git a/README.org b/README.org
index 00df5e87ef..7bfe77911e 100644
--- a/README.org
+++ b/README.org
@@ -2426,6 +2426,46 @@ For templates, refer to `denote-templates'."
(call-interactively #'denote-link-or-create)))
#+end_src
+** Using the tree-based file prompt for select commands
+:PROPERTIES:
+:CUSTOM_ID: h:8f9e0971-8b30-4e7b-af79-8fed257dbcfa
+:END:
+
+Older versions of Denote had a file prompt that resembled that of the
+standard ~find-file~ command (bound to =C-x C-f= by default). This
+means that it used a tree-based method of navigating the filesystem by
+selecting the specific directory and then the given file.
+
+Currently, Denote flattens the file prompt so that every file in the
+~denote-directory~ and its subdirectories can be matched from anywhere
+using the power of Emacs' minibuffer completion (such as with the help
+of the ~orderless~ package in addition to built-in options).
+
+Users who need the old behaviour on a per-command basis can define
+their own wrapper functions as shown in the following code block.
+
+#+begin_src emacs-lisp
+;; This is the old `denote-file-prompt' that we renamed to
+;; `denote-file-prompt-original' for clarity.
+(defun denote-file-prompt-original (&optional initial-text)
+ "Prompt for file with identifier in variable `denote-directory'.
+With optional INITIAL-TEXT, use it to prepopulate the minibuffer."
+ (read-file-name "Select note: " (denote-directory) nil nil initial-text
+ (lambda (f)
+ (or (denote-file-has-identifier-p f)
+ (file-directory-p f)))))
+
+;; Our wrapper command that changes the current `denote-file-prompt'
+;; to the functionality of `denote-file-prompt-original' only when
+;; this command is used.
+(defun my-denote-link ()
+ "Call `denote-link' but use Denote's original file prompt.
+See `denote-file-prompt-original'."
+ (interactive)
+ (cl-letf (((symbol-function 'denote-file-prompt)
#'denote-file-prompt-original))
+ (call-interactively #'denote-link)))
+#+end_src
+
* Installation
:PROPERTIES:
:CUSTOM_ID: h:f3bdac2c-4704-4a51-948c-a789a2589790
