[elpa] externals/denote d3e3762fe4: Add optional :this-heading-only parameter for backlinks' Org dynamic block

[ELPA Syncer]

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

    Add optional :this-heading-only parameter for backlinks' Org dynamic block
---
 README.org           | 14 ++++++++++++--
 denote-org-extras.el | 18 ++++++++++++++++--
 2 files changed, 28 insertions(+), 4 deletions(-)

diff --git a/README.org b/README.org
index a573f7b704..43364719af 100644
--- a/README.org
+++ b/README.org
@@ -2837,12 +2837,13 @@ instead. Reproducing it here for the sake of 
convenience:
 :CUSTOM_ID: h:604bf92a-908a-485c-98b8-37ccae559afd
 :END:
 
-The optional =denote-org-extras.el= can produce Denote links to
+The optional =denote-org-extras.el= can generate Denote links to
 individual headings ([[#h:fc1ad245-ec08-41be-8d1e-7153d99daf02][Insert link to 
an Org file with a further pointer to a heading]]).
 It is then possible to produce a corresponding backlinks buffer with
 the command ~denote-org-extras-backlinks-for-heading~. The resulting
 buffer behaves the same way as the standard backlinks buffer we
-provide ([[#h:c73f1f68-e214-49d5-b369-e694f6a5d708][The backlinks' buffer]]).
+provide ([[#h:c73f1f68-e214-49d5-b369-e694f6a5d708][The backlinks' buffer]]). 
An Org dynamic block with backlinks
+to the current heading is also an option 
([[#h:50160fae-6515-4d7d-9737-995ad925e64b][Org dynamic blocks to insert links 
or backlinks]]).
 
 ** Writing metanotes
 :PROPERTIES:
@@ -3317,6 +3318,15 @@ line to update the block.
   with the identifier of the given file. This has the same meaning as
   with the ~denote-link~ command and related facilities 
([[#h:fc913d54-26c8-4c41-be86-999839e8ad31][Linking notes]]).
 
+- The =:this-heading-only= parameter determines if the backlinks are
+  about the file or the heading under which the dynamic block is
+  ([[#h:604bf92a-908a-485c-98b8-37ccae559afd][Backlinks for Org headings]]). 
When this parameter is omitted or nil
+  (the default), then the backlinks are about the whole file, but if
+  this parameter has a ~t~ value then the backlinks are specifically
+  for the heading ([[#h:fc1ad245-ec08-41be-8d1e-7153d99daf02][Insert link to 
an Org file with a further pointer to a heading]]).
+
+  [ The =:this-heading-only= parameter is part of {{{development-version}}}. ]
+
 - An optional =:block-name= parameter can be specified with a string
   value to add a =#+name= to the results. This is useful for further
   processing using Org facilities (a feature that is outside Denote's
diff --git a/denote-org-extras.el b/denote-org-extras.el
index 14386f0419..f89c8b4465 100644
--- a/denote-org-extras.el
+++ b/denote-org-extras.el
@@ -141,6 +141,17 @@ If FILE is nil, use the variable `buffer-file-name'."
   "Format a buffer name for `denote-org-extras-backlinks-for-heading' with 
TEXT."
   (format "*Denote HEADING backlinks for %S*" text))
 
+(defun denote-org-extras--get-backlinks-for-heading (file-and-heading-id)
+  "Get backlinks to FILE-AND-HEADING-ID as a list of strings."
+  (when-let ((xref-alist (xref--analyze
+                          (xref-matches-in-files
+                           file-and-heading-id
+                           (denote-directory-files nil :omit-current 
:text-only)))))
+    (mapcar
+     (lambda (x)
+       (denote-get-file-name-relative-to-denote-directory (car x)))
+     xref-alist)))
+
 ;;;###autoload
 (defun denote-org-extras-backlinks-for-heading ()
   "Produce backlinks for the current heading.
@@ -459,7 +470,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
+                           :this-heading-only nil))
   (org-update-dblock))
 
 ;; NOTE 2024-03-30: This is how the autoload is done in org.el.
@@ -472,7 +484,9 @@ Used by `org-dblock-update' with PARAMS provided by the 
dynamic block."
 (defun org-dblock-write:denote-backlinks (params)
   "Function to update `denote-backlinks' Org Dynamic blocks.
 Used by `org-dblock-update' with PARAMS provided by the dynamic block."
-  (when-let ((files (denote-link-return-backlinks)))
+  (when-let ((files (if (plist-get params :this-heading-only)
+                        (denote-org-extras--get-backlinks-for-heading 
(denote-org-extras--get-file-id-and-heading-id))
+                      (denote-link-return-backlinks))))
     (let* ((sort (plist-get params :sort-by-component))
            (reverse (plist-get params :reverse-sort))
            (denote-excluded-directories-regexp (or (plist-get params 
:excluded-dirs-regexp)