[elpa] externals/denote 75374dc5dd 2/3: Add optional :include-date parameter to Org dynamic blocks that show links to files

[ELPA Syncer]

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

    Add optional :include-date parameter to Org dynamic blocks that show links 
to files
    
    Thanks to Sergio Rey for describing this idea to me. This was done via
    a private channel and this information is shared with permission.
---
 README.org           | 12 +++++------
 denote-org-extras.el | 18 ++++++++++------
 denote.el            | 60 ++++++++++++++++++++++++++++++++++------------------
 3 files changed, 57 insertions(+), 33 deletions(-)

diff --git a/README.org b/README.org
index e302a08a4e..0888f09423 100644
--- a/README.org
+++ b/README.org
@@ -6192,12 +6192,12 @@ Denote is meant to be a collective effort.  Every bit 
of help matters.
   Jousimies, Juanjo Presa, Julian Hoch, Kai von Fintel, Kaushal Modi,
   Kolmas, M. Hadi Timachi, Maikol Solis, Mark Olson, Mirko Hernandez,
   Niall Dooley, Nick Bell, Paul van Gelder, Peter Prevos, Peter Smith,
-  Samuel W. Flint, Suhail Singh, Shreyas Ragavan, Stefan Thesing,
-  Summer Emacs, Sven Seebeck, Taoufik, TJ Stankus, Vick (VicZz),
-  Viktor Haag, Wade Mealing, Yi Liu, Ypot, atanasj, azegas, babusri,
-  coherentstate, doolio, duli, drcxd, elge70, fingerknight, hpgisler,
-  mentalisttraceur, pRot0ta1p, rbenit68, relict007, sienic, skissue,
-  sundar bp, yetanotherfossman, zadca123
+  Samuel W. Flint, Sergio Rey, Suhail Singh, Shreyas Ragavan, Stefan
+  Thesing, Summer Emacs, Sven Seebeck, Taoufik, TJ Stankus, Vick
+  (VicZz), Viktor Haag, Wade Mealing, Yi Liu, Ypot, atanasj, azegas,
+  babusri, coherentstate, doolio, duli, drcxd, elge70, fingerknight,
+  hpgisler, mentalisttraceur, pRot0ta1p, rbenit68, relict007, sienic,
+  skissue, sundar bp, yetanotherfossman, zadca123
 
 Special thanks to Peter Povinec who helped refine the file-naming
 scheme, which is the cornerstone of this project.
diff --git a/denote-org-extras.el b/denote-org-extras.el
index f89c8b4465..9ce6f0f3b8 100644
--- a/denote-org-extras.el
+++ b/denote-org-extras.el
@@ -384,7 +384,8 @@ Also see `denote-org-extras-dblock--files'."
                            :excluded-dirs-regexp nil
                            :sort-by-component nil
                            :reverse-sort nil
-                           :id-only nil))
+                           :id-only nil
+                           :include-date nil))
   (org-update-dblock))
 
 ;; NOTE 2024-03-30: This is how the autoload is done in org.el.
@@ -401,12 +402,13 @@ Used by `org-dblock-update' with PARAMS provided by the 
dynamic block."
          (rx (if (listp regexp) (macroexpand `(rx ,regexp)) regexp))
          (sort (plist-get params :sort-by-component))
          (reverse (plist-get params :reverse-sort))
+         (include-date (plist-get params :include-date))
          (block-name (plist-get params :block-name))
          (denote-excluded-directories-regexp (or (plist-get params 
:excluded-dirs-regexp)
                                                  
denote-excluded-directories-regexp))
          (files (denote-org-extras-dblock--files rx sort reverse)))
     (when block-name (insert "#+name: " block-name "\n"))
-    (denote-link--insert-links files 'org (plist-get params :id-only) 
:no-other-sorting)
+    (denote-link--insert-links files 'org (plist-get params :id-only) 
:no-other-sorting include-date)
     (join-line))) ; remove trailing empty line
 
 ;;;;; Dynamic block to insert missing links
@@ -423,7 +425,8 @@ Used by `org-dblock-update' with PARAMS provided by the 
dynamic block."
                            :excluded-dirs-regexp nil
                            :sort-by-component nil
                            :reverse-sort nil
-                           :id-only nil))
+                           :id-only nil
+                           :include-date nil))
   (org-update-dblock))
 
 ;; NOTE 2024-03-30: This is how the autoload is done in org.el.
@@ -440,12 +443,13 @@ Used by `org-dblock-update' with PARAMS provided by the 
dynamic block."
          (rx (if (listp regexp) (macroexpand `(rx ,regexp)) regexp))
          (sort (plist-get params :sort-by-component))
          (reverse (plist-get params :reverse-sort))
+         (include-date (plist-get params :include-date))
          (block-name (plist-get params :block-name))
          (denote-excluded-directories-regexp (or (plist-get params 
:excluded-dirs-regexp)
                                                  
denote-excluded-directories-regexp))
          (files (denote-org-extras-dblock--files-missing-only rx sort 
reverse)))
     (when block-name (insert "#+name: " block-name "\n"))
-    (denote-link--insert-links files 'org (plist-get params :id-only) 
:no-other-sorting)
+    (denote-link--insert-links files 'org (plist-get params :id-only) 
:no-other-sorting include-date)
     (join-line))) ; remove trailing empty line
 
 ;;;;; Dynamic block to insert backlinks
@@ -471,7 +475,8 @@ Used by `org-dblock-update' with PARAMS provided by the 
dynamic block."
                            :sort-by-component nil
                            :reverse-sort nil
                            :id-only nil
-                           :this-heading-only nil))
+                           :this-heading-only nil
+                           :include-date nil))
   (org-update-dblock))
 
 ;; NOTE 2024-03-30: This is how the autoload is done in org.el.
@@ -489,10 +494,11 @@ Used by `org-dblock-update' with PARAMS provided by the 
dynamic block."
                       (denote-link-return-backlinks))))
     (let* ((sort (plist-get params :sort-by-component))
            (reverse (plist-get params :reverse-sort))
+           (include-date (plist-get params :include-date))
            (denote-excluded-directories-regexp (or (plist-get params 
:excluded-dirs-regexp)
                                                    
denote-excluded-directories-regexp))
            (files (denote-org-extras-dblock--maybe-sort-backlinks files sort 
reverse)))
-      (denote-link--insert-links files 'org (plist-get params :id-only) 
:no-other-sorting)
+      (denote-link--insert-links files 'org (plist-get params :id-only) 
:no-other-sorting include-date)
       (join-line)))) ; remove trailing empty line
 
 ;;;;; Dynamic block to insert entire file contents
diff --git a/denote.el b/denote.el
index c01d22db34..b486c6d75d 100644
--- a/denote.el
+++ b/denote.el
@@ -2056,6 +2056,13 @@ If either that or DATE is nil or an empty string, return
 `current-time'."
   (or (denote-valid-date-p date) (current-time)))
 
+(defun denote--id-to-date (identifier)
+  "Convert IDENTIFIER string to YYYY-MM-DD."
+  (replace-regexp-in-string
+   "\\([0-9]\\{4\\}\\)\\([0-9]\\{2\\}\\)\\([0-9]\\{2\\}\\).*"
+   "\\1-\\2-\\3"
+   identifier))
+
 (defun denote--buffer-file-names ()
   "Return file names of Denote buffers."
   (delq nil
@@ -3814,24 +3821,31 @@ The format of such links is `denote-md-link-format'.")
   "Regexp to match an identifier-only link in its context.
 The format of such links is `denote-id-only-link-format'."  )
 
-(defun denote-format-link (file description file-type id-only)
+(defun denote-format-link (file description file-type id-only &optional 
include-date)
   "Prepare link to FILE using DESCRIPTION.
 
 FILE-TYPE and ID-ONLY are used to get the format of the link.
-See the `:link' property of `denote-file-types'."
-  (format
-   (cond
-    ((or id-only (null description) (string-empty-p description))
-     denote-id-only-link-format)
-    ;; NOTE 2024-05-20: If there is no file type, we want to use the
-    ;; Org format because it is still a usable link with the help of
-    ;; the command `org-open-at-point-global'.
-    ((null file-type)
-     (denote--link-format 'org))
-    (t
-     (denote--link-format file-type)))
-   (denote-retrieve-filename-identifier file)
-   description))
+See the `:link' property of `denote-file-types'.
+
+With optional INCLUDE-DATE, convert the identifier using
+`denote--id-to-date' and append it to DESCRIPTION."
+  (let* ((identifier (denote-retrieve-filename-identifier file))
+         (desc (if include-date
+                   (format "%s (%s)" description (denote--id-to-date 
identifier))
+                description)))
+    (format
+     (cond
+      ((or id-only (null description) (string-empty-p description))
+       denote-id-only-link-format)
+      ;; NOTE 2024-05-20: If there is no file type, we want to use the
+      ;; Org format because it is still a usable link with the help of
+      ;; the command `org-open-at-point-global'.
+      ((null file-type)
+       (denote--link-format 'org))
+      (t
+       (denote--link-format file-type)))
+     identifier
+     desc)))
 
 (make-obsolete 'denote-link-signature-format nil "2.3.0")
 
@@ -4477,23 +4491,25 @@ Place the buffer below the current window or wherever 
the user option
 
 (make-obsolete-variable 'denote-link-add-links-sort nil "3.1.0")
 
-(defun denote-link--prepare-links (files current-file-type id-only &optional 
no-sort)
+(defun denote-link--prepare-links (files current-file-type id-only &optional 
no-sort include-date)
   "Prepare links to FILES from CURRENT-FILE-TYPE.
 When ID-ONLY is non-nil, use a generic link format.
 
 With optional NO-SORT do not try to sort the inserted lines.
-Otherwise sort lines while accounting for `denote-link-add-links-sort'."
+Otherwise sort lines while accounting for `denote-link-add-links-sort'.
+
+Optional INCLUDE-DATE has the same meaning as in `denote-format-link'."
   (let ((links))
     (dolist (file files)
       (let* ((description (denote--link-get-description file))
-             (link (denote-format-link file description current-file-type 
id-only))
+             (link (denote-format-link file description current-file-type 
id-only include-date))
              (link-as-list-item (format denote-link--prepare-links-format 
link)))
          (push link-as-list-item links)))
     (if no-sort
         (nreverse links)
       (sort links #'string-collate-lessp))))
 
-(defun denote-link--insert-links (files current-file-type &optional id-only 
no-sort)
+(defun denote-link--insert-links (files current-file-type &optional id-only 
no-sort include-date)
   "Insert at point a typographic list of links matching FILES.
 
 With CURRENT-FILE-TYPE as a symbol among those specified in
@@ -4504,8 +4520,10 @@ unknown non-nil value, default to the Org notation.
 With ID-ONLY as a non-nil value, produce links that consist only
 of the identifier, thus deviating from CURRENT-FILE-TYPE.
 
-Optional NO-SORT is passed to `denote-link--prepare-links'."
-  (when-let ((links (denote-link--prepare-links files current-file-type 
id-only no-sort)))
+Optional NO-SORT is passed to `denote-link--prepare-links'.
+
+Optional INCLUDE-DATE has the same meaning as in `denote-format-link'."
+  (when-let ((links (denote-link--prepare-links files current-file-type 
id-only no-sort include-date)))
     (dolist (link links)
       (insert link))))