[elpa] externals/denote e9c2e8d73c 1/3: Add documentation to select silo interactively

[ELPA Syncer]

branch: externals/denote
commit e9c2e8d73c98791536b590378ecefa9f0546eee5
Author: Protesilaos Stavrou <info@protesilaos.com>
Commit: Protesilaos Stavrou <info@protesilaos.com>

    Add documentation to select silo interactively
    
    I am providing this in response to a request from GitHub user
    rbenit68.  The discussion took place in issue 127 on the GitHub
    mirror, with the participation of Mirko Hernandez:
    <https://github.com/protesilaos/denote/issues/127>.
    
    The custom code I provide is the expanded version of an idea put forth
    by Mirko, to whom I am thankful.
---
 README.org | 63 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 62 insertions(+), 1 deletion(-)

diff --git a/README.org b/README.org
index 7bfe77911e..535e67c34f 100644
--- a/README.org
+++ b/README.org
@@ -568,6 +568,8 @@ reference.  They will not read the global value of 
~denote-directory~.
 The global value of ~denote-directory~ is read everywhere else except
 the silos.
 
+[[#h:0f72e6ea-97f0-42e1-8fd4-0684af0422e0][Use custom commands to select a 
silo]].
+
 In concrete terms, this is a representation of the directory structures
 (notice the =.dir-locals.el= file is needed only for the silos):
 
@@ -666,6 +668,65 @@ to experiment with the best setup for their workflow.
 Feel welcome to ask for help if the information provided herein is not
 sufficient.  The manual shall be expanded accordingly.
 
+*** Use custom commands to select a silo
+:PROPERTIES:
+:CUSTOM_ID: h:0f72e6ea-97f0-42e1-8fd4-0684af0422e0
+:END:
+
+We implement silos as directory-local values of the user option
+~denote-directory~.  This means that all Denote commands read from the
+local value if they are invoked from that context.  For example, is
+=~/Videos/recordings= is a silo and =~/Documents/notes= is the
+default/global value of ~denote-directory~ all Denote commands will
+read the video's path when called from there (e.g. by using Emacs'
+~dired~); any other context reads the global value.
+
+[[#h:15719799-a5ff-4e9a-9f10-4ca03ef8f6c5][Maintain separate directory silos 
for notes]].
+
+There are cases where the user (i) wants to maintain multiple silos
+and (ii) prefers an interactive way to switch between them without
+going through Dired.  Since this is specific to the user's workflow,
+it is easier to have some custom code for it.  The following should be
+added to the user's Denote configuration:
+
+#+begin_src emacs-lisp
+(defvar my-denote-silo-directories
+  `("/home/prot/Videos/recordings"
+    "/home/prot/Documents/books"
+    ;; You don't actually need to include the `denote-directory' here
+    ;; if you use the regular commands in their global context.  I am
+    ;; including it for completeness.
+    ,denote-directory)
+  "List of file paths pointing to my Denote silos.
+This is a list of strings.")
+
+(defvar my-denote-commands-for-silos
+  '(denote
+    denote-date
+    denote-subdirectory
+    denote-template
+    denote-type)
+  "List of Denote commands to call after selecting a silo.
+This is a list of symbols that specify the note-creating
+interactive functions that Denote provides.")
+
+(defun my-denote-pick-silo-then-command (silo command)
+  "Select SILO and run Denote COMMAND in it.
+SILO is a file path from `my-denote-silo-directories', while
+COMMAND is one among `my-denote-commands-for-silos'."
+  (interactive
+   (list (completing-read "Select a silo: " my-denote-silo-directories nil t)
+         (intern (completing-read
+                  "Run command in silo: "
+                  my-denote-commands-for-silos nil t))))
+  (let ((denote-directory silo))
+    (call-interactively command)))
+#+end_src
+
+With this in place, =M-x my-denote-pick-silo-then-command= will use
+minibuffer completion to select a silo among the predefined options
+and then ask for the command to run in that context.
+
 ** Exclude certain directories from all operations
 :PROPERTIES:
 :CUSTOM_ID: h:8458f716-f9c2-4888-824b-2bf01cc5850a
@@ -3644,7 +3705,7 @@ Denote is meant to be a collective effort.  Every bit of 
help matters.
   Modi, M. Hadi Timachi, Mirko Hernandez, Paul van Gelder, Peter
   Prevos, Shreyas Ragavan, Stefan Thesing, Summer Emacs, Sven Seebeck,
   Taoufik, Viktor Haag, Yi Liu, Ypot, atanasj, hpgisler, pRot0ta1p,
-  sienic, sundar bp.
+  rbenit68, sienic, sundar bp.
 
 Special thanks to Peter Povinec who helped refine the file-naming
 scheme, which is the cornerstone of this project.