[elpa] externals/denote 3061a7387f 2/2: Rename 'denote-silo-extras.el', document and refine everything

[ELPA Syncer]

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

    Rename 'denote-silo-extras.el', document and refine everything
    
    This is discussed on the mailing list with the participation of Vedang
    Manerikar: <https://lists.sr.ht/~protesilaos/denote/patches/43255>.
---
 README.org            |  44 ++++++++++++++++++
 denote-silo-extra.el  |  89 -----------------------------------
 denote-silo-extras.el | 125 ++++++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 169 insertions(+), 89 deletions(-)

diff --git a/README.org b/README.org
index 98c8c274d3..717a7df4f2 100644
--- a/README.org
+++ b/README.org
@@ -803,6 +803,11 @@ sufficient.  The manual shall be expanded accordingly.
 :CUSTOM_ID: h:0f72e6ea-97f0-42e1-8fd4-0684af0422e0
 :END:
 
+[ As part of {{{development-version}}}, the contents of this section
+  are formally provided in the file =denote-silo-extras.el=.  We keep
+  this here for existing users.  Otherwise consult the new entry in
+  the manual ([[#h:e43baf95-f201-4fec-8620-c0eb5eaa1c85][The 
=denote-silo-extras.el=]]). ]
+
 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, if
@@ -870,6 +875,45 @@ To see another example of a wrapper function that uses
 
 [[#h:d0c7cb79-21e5-4176-a6af-f4f68578c8dd][Extending Denote: Split an Org 
subtree into its own note]].
 
+*** The =denote-silo-extras.el=
+:PROPERTIES:
+:CUSTOM_ID: h:e43baf95-f201-4fec-8620-c0eb5eaa1c85
+:END:
+
+[ Part of {{{development-version}}}. ]
+
+The =denote-silo-extras.el= provides optional convenience functions for
+working with silos ([[#h:15719799-a5ff-4e9a-9f10-4ca03ef8f6c5][Maintain 
separate directory silos for notes]]).
+Start by loading the relevant library:
+
+#+begin_src emacs-lisp
+;; Register Denote's Org dynamic blocks
+(require 'denote-silo-extras)
+#+end_src
+
+#+vindex: denote-silo-extras-directories
+The user option ~denote-silo-extras-directories~ specifies a list of
+directories that the user has set up as ~denote-directory~ silos.
+
+#+findex: denote-silo-extras-create-note
+The command ~denote-silo-extras-create-note~ prompts for a directory
+among ~denote-silo-extras-directories~ and runs the ~denote~ command
+from there.
+
+#+findex: denote-silo-extras-open-or-create
+Similar to the above, the command ~denote-silo-extras-open-or-create~
+prompts for a directory among ~denote-silo-extras-directories~ and runs
+the ~denote-open-or-create~ command from there.
+
+#+findex: denote-silo-extras-select-silo-then-command
+#+vindex: denote-silo-extras-commands
+The command ~denote-silo-extras-select-silo-then-command~ prompts with
+minibuffer completion for a directory among ~denote-silo-extras-directories~.
+Once the user selects a silo, a second prompt asks for a Denote
+note-creation command to call from inside that silo 
([[#h:17896c8c-d97a-4faa-abf6-31df99746ca6][Points of entry]]).
+The list of available commands is specified in the user option
+~denote-silo-extras-commands~.
+
 ** Exclude certain directories from all operations
 :PROPERTIES:
 :CUSTOM_ID: h:8458f716-f9c2-4888-824b-2bf01cc5850a
diff --git a/denote-silo-extra.el b/denote-silo-extra.el
deleted file mode 100644
index 7063fa3424..0000000000
--- a/denote-silo-extra.el
+++ /dev/null
@@ -1,89 +0,0 @@
-;;; denote-silo-extra.el --- Convenience functions for using Denote in 
multiple silos  -*- lexical-binding: t; -*-
-
-;; Copyright (C) 2023  Free Software Foundation, Inc.
-
-;; Author: Protesilaos Stavrou <info@protesilaos.com>
-;; Maintainer: Denote Development <~protesilaos/denote@lists.sr.ht>
-;; URL: https://git.sr.ht/~protesilaos/denote
-;; Mailing-List: https://lists.sr.ht/~protesilaos/denote
-
-;; This file is NOT part of GNU Emacs.
-
-;; This program is free software; you can redistribute it and/or modify
-;; it under the terms of the GNU General Public License as published by
-;; the Free Software Foundation, either version 3 of the License, or
-;; (at your option) any later version.
-
-;; This program is distributed in the hope that it will be useful,
-;; but WITHOUT ANY WARRANTY; without even the implied warranty of
-;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-;; GNU General Public License for more details.
-
-;; You should have received a copy of the GNU General Public License
-;; along with this program.  If not, see <https://www.gnu.org/licenses/>.
-
-;;; Commentary:
-
-;;
-
-;;; Code:
-
-(require 'denote)
-
-(defgroup denote-silo-extra nil
-  "Make it easier to use Denote across Silos."
-  :group 'denote
-  :link '(info-link "(denote) Top")
-  :link '(url-link :tag "Homepage" "https://protesilaos.com/emacs/denote";))
-
-(defcustom denote-silo-extra-directories
-  `(,denote-directory)
-  "List of file paths pointing to my Denote silos."
-  :group 'denote-silo-extra
-  :link '(info-link "(denote) Maintain separate directories for notes")
-  :type '(repeat directory))
-
-(defvar denote-silo-extra-commands-for-silos
-  '(denote
-    denote-date
-    denote-subdirectory
-    denote-template
-    denote-type
-    denote-signature)
-  "List of commands to call after selecting a silo.")
-
-(defun denote-silo-extra-pick-silo-then-command (silo command)
-  "Select SILO and run Denote COMMAND in it.
-SILO is a file path from `denote-silo-extra-directories', while
-COMMAND is one among `denote-silo-extra-commands-for-silos'."
-  (interactive
-   (list (completing-read "Select a silo: "
-                          denote-silo-extra-directories nil t)
-         (intern
-          (completing-read "Run command in silo: "
-                           denote-silo-extra-commands-for-silos nil t))))
-  (let ((denote-user-enforced-denote-directory silo))
-    (call-interactively command)))
-
-(defun denote-silo-extra-create (&optional silo)
-  "Select SILO and run `denote' in it.
-SILO is a file path from `denote-silo-extra-directories'."
-  (interactive
-   (list (when current-prefix-arg
-           (completing-read "Select a silo: "
-                            denote-silo-extra-directories nil t))))
-  (let ((denote-user-enforced-denote-directory silo))
-    (call-interactively #'denote)))
-
-(defun denote-silo-extra-open-or-create (&optional silo)
-  "Select SILO and run `denote-open-or-create' in it.
-SILO is a file path from `denote-silo-extra-directories'."
-  (interactive
-   (list (when current-prefix-arg
-           (completing-read "Select a silo: "
-                            denote-silo-extra-directories nil t))))
-  (let ((denote-user-enforced-denote-directory silo))
-    (call-interactively #'denote-open-or-create)))
-
-(provide 'denote-silo-extra)
-;;; denote-silo-extra.el ends here
diff --git a/denote-silo-extras.el b/denote-silo-extras.el
new file mode 100644
index 0000000000..a198ca1411
--- /dev/null
+++ b/denote-silo-extras.el
@@ -0,0 +1,125 @@
+;;; denote-silo-extras.el --- Convenience functions for using Denote in 
multiple silos  -*- lexical-binding: t; -*-
+
+;; Copyright (C) 2023  Free Software Foundation, Inc.
+
+;; Author: Protesilaos Stavrou <info@protesilaos.com>
+;; Maintainer: Denote Development <~protesilaos/denote@lists.sr.ht>
+;; URL: https://git.sr.ht/~protesilaos/denote
+;; Mailing-List: https://lists.sr.ht/~protesilaos/denote
+
+;; This file is NOT part of GNU Emacs.
+
+;; This program is free software; you can redistribute it and/or modify
+;; it under the terms of the GNU General Public License as published by
+;; the Free Software Foundation, either version 3 of the License, or
+;; (at your option) any later version.
+
+;; This program is distributed in the hope that it will be useful,
+;; but WITHOUT ANY WARRANTY; without even the implied warranty of
+;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+;; GNU General Public License for more details.
+
+;; You should have received a copy of the GNU General Public License
+;; along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+;;; Commentary:
+
+;; This is a set of convenience functions that used to be provided in
+;; the Denote manual.  A "silo" is a `denote-directory' that is
+;; self-contained.  Users can maintain multiple silos.  Consult the
+;; manual for the details.  With the Denote package installed,
+;; evaluate the following to read the relevant node:
+;;
+;;     (info "(denote) Maintain separate directory silos for notes")
+
+;;; Code:
+
+(require 'denote)
+
+(defgroup denote-silo-extras nil
+  "Make it easier to use Denote across Silos."
+  :group 'denote
+  :link '(info-link "(denote) Top")
+  :link '(url-link :tag "Homepage" "https://protesilaos.com/emacs/denote";))
+
+(defcustom denote-silo-extras-directories
+  `(,denote-directory)
+  "List of file paths pointing to Denote silos.
+Each file path points to a directory, which takes the same value
+as the variable `denote-directory'."
+  :group 'denote-silo-extras
+  :link '(info-link "(denote) Maintain separate directories for notes")
+  :type '(repeat directory))
+
+(defcustom denote-silo-extras-commands
+  '(denote
+    denote-date
+    denote-subdirectory
+    denote-template
+    denote-type
+    denote-signature)
+  "List of commands to call after selecting a silo.
+This is used by the `denote-silo-extras-select-silo-then-command'
+command."
+  :group 'denote-silo-extras
+  :link '(info-link "(denote) Maintain separate directories for notes")
+  :type '(repeat function))
+
+(defvar denote-silo-extras--directory-history nil
+  "Minibuffer history for `denote-silo-extras--directory-prompt'.")
+
+(defun denote-silo-extras--directory-prompt ()
+  "Prompt for directory among `denote-silo-extras-directories'."
+  (let ((default (car denote-silo-extras--directory-history)))
+    (completing-read
+     (format-prompt "Select a silo" default)
+     denote-silo-extras-directories nil :require-match
+     nil 'denote-silo-extras--directory-history)))
+
+(defvar denote-silo-extras--command-history nil
+  "Minibuffer history for `denote-silo-extras--command-prompt'.")
+
+(defun denote-silo-extras--command-prompt ()
+  "Prompt for command among `denote-silo-extras-commands'."
+  (let ((default (car denote-silo-extras--command-history)))
+    (completing-read
+     (format-prompt "Run command in silo" default)
+     denote-silo-extras-commands nil :require-match
+     nil 'denote-silo-extras--command-history)))
+
+;;;###autoload
+(defun denote-silo-extras-create-note (&optional silo)
+  "Select SILO and run `denote' in it.
+SILO is a file path from `denote-silo-extras-directories'."
+  (interactive
+   (list
+    (when current-prefix-arg
+      (denote-silo-extras--directory-prompt))))
+  (let ((denote-user-enforced-denote-directory silo))
+    (call-interactively #'denote)))
+
+;;;###autoload
+(defun denote-silo-extras-open-or-create (&optional silo)
+  "Select SILO and run `denote-open-or-create' in it.
+SILO is a file path from `denote-silo-extras-directories'."
+  (interactive
+   (list
+    (when current-prefix-arg
+      (denote-silo-extras--directory-prompt))))
+  (let ((denote-user-enforced-denote-directory silo))
+    (call-interactively #'denote-open-or-create)))
+
+;;;###autoload
+(defun denote-silo-extras-select-silo-then-command (silo command)
+  "Select SILO and run Denote COMMAND in it.
+SILO is a file path from `denote-silo-extras-directories', while
+COMMAND is one among `denote-silo-extras-commands'."
+  (interactive
+   (list
+    (denote-silo-extras--directory-prompt)
+    (denote-silo-extras--command-prompt)))
+  (let ((denote-user-enforced-denote-directory silo))
+    (call-interactively command)))
+
+(provide 'denote-silo-extras)
+;;; denote-silo-extras.el ends here