[elpa] externals/denote 3a9404cd37 04/12: Add new denote-link-with-signature command

[ELPA Syncer]

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

    Add new denote-link-with-signature command
    
    Thanks to Mark Olson for mentioning this idea.  It was done in issue
    167 on the GitHub mirror:
    <https://github.com/protesilaos/denote/issues/167>.
---
 README.org | 29 +++++++++++++++++++++++++----
 denote.el  | 29 +++++++++++++++++++++++++++++
 2 files changed, 54 insertions(+), 4 deletions(-)

diff --git a/README.org b/README.org
index c13e3f0bf6..bf26f0811d 100644
--- a/README.org
+++ b/README.org
@@ -1721,6 +1721,26 @@ above is for interactive usage.
 Links are created only for files which qualify as a "note" for our
 purposes ([[#h:fc913d54-26c8-4c41-be86-999839e8ad31][Linking notes]]).
 
+** Insert link to file with signature
+:PROPERTIES:
+:CUSTOM_ID: h:066e5221-9844-474b-8858-398398646f86
+:END:
+
+[ Part of {{{development-version}}}. ]
+
+#+findex: denote-link-with-signature
+The command ~denote-link-with-signature~ prompts for a file among
+those that contain a ===SIGNATURE= and inserts a link to it.  The
+description of the link includes the text of the signature and that of
+the file's title, if any.  For example, a link to the following file:
+
+: 20230925T144303==abc--my-first-signature-note__denote_testing.txt
+
+will get this link: =[[denote:20230925T144303][abc My first signature note]]=.
+
+For more advanced uses, especially when called from Lisp, refer to the
+doc string of the ~denote-link~ function.
+
 ** Insert links, but only those missing from current buffer
 :PROPERTIES:
 :CUSTOM_ID: h:0c1fdaab-5a6b-4792-9694-fed53cd042e6
@@ -4538,10 +4558,11 @@ Denote is meant to be a collective effort.  Every bit 
of help matters.
   Frank Ehmsen, Guo Yong, Hanspeter Gisler, Jack Baty, Jay Rajput,
   Jean-Charles Bagneris, Jeremy Friesen, Jonathan Sahar, Johan
   Bolmsjö, Juanjo Presa, Kai von Fintel, Kaushal Modi, M. Hadi
-  Timachi, Mirko Hernandez, Niall Dooley, Paul van Gelder, Peter
-  Prevos, Shreyas Ragavan, Stefan Thesing, Summer Emacs, Sven Seebeck,
-  Taoufik, Viktor Haag, Wade Mealing, Yi Liu, Ypot, atanasj, doolio,
-  drcxd, hpgisler, pRot0ta1p, rbenit68, relict007, sienic, sundar bp.
+  Timachi, Mark Olson, Mirko Hernandez, Niall Dooley, Paul van Gelder,
+  Peter Prevos, Shreyas Ragavan, Stefan Thesing, Summer Emacs, Sven
+  Seebeck, Taoufik, Viktor Haag, Wade Mealing, Yi Liu, Ypot, atanasj,
+  doolio, drcxd, hpgisler, pRot0ta1p, rbenit68, relict007, sienic,
+  sundar bp.
 
 Special thanks to Peter Povinec who helped refine the file-naming
 scheme, which is the cornerstone of this project.
diff --git a/denote.el b/denote.el
index a36eda6189..8391a4cdcd 100644
--- a/denote.el
+++ b/denote.el
@@ -3022,6 +3022,35 @@ treats the active region specially, is up to it."
 (defalias 'denote-insert-link 'denote-link
   "Alias for `denote-link' command.")
 
+(defun denote--link-get-description-with-signature (file file-type)
+  "Return `denote-link-with-signature' description.
+Retrieve the title and signature from FILE with FILE-TYPE."
+  (let* ((signature (denote-retrieve-filename-signature file))
+         (title (denote-retrieve-title-value file file-type))
+         (specifiers (if (and title
+                              (not (string-empty-p title)))
+                         "%s %s"
+                       "%s")))
+    (format specifiers signature title)))
+
+;;;###autoload
+(defun denote-link-with-signature ()
+  "Insert link to file with signature.
+Prompt for file using minibuffer completion, limiting the list of
+candidates to files with a signature in their file name.
+
+The description of the link includes the signature followed by
+the file's title, if any.  For this case, the signature is
+assumed present.
+
+For more advanced uses, especially when called from Lisp, refer
+to the `denote-link' function."
+  (declare (interactive-only t))
+  (interactive)
+  (let ((file (denote-file-prompt "="))
+        (type (denote-filetype-heuristics (buffer-file-name))))
+    (denote-link file type (denote--link-get-description-with-signature file 
type))))
+
 (defun denote-link--collect-identifiers (regexp)
   "Return collection of identifiers in buffer matching REGEXP."
   (let (matches)