[elpa] externals/denote ae11205800 01/32: Add user option and concomitant functionality to link to Org headings

[ELPA Syncer]

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

    Add user option and concomitant functionality to link to Org headings
---
 README.org | 19 +++++++++++++++++++
 denote.el  | 38 +++++++++++++++++++++++++++++++++++++-
 2 files changed, 56 insertions(+), 1 deletion(-)

diff --git a/README.org b/README.org
index 2190bc6a5e..50db8f975f 100644
--- a/README.org
+++ b/README.org
@@ -1776,6 +1776,25 @@ like an ordinary link by default.  This is just a 
convenience for the
 user/theme in case they want =denote:= links to remain distinct from
 other links.
 
+** The ~denote-link-to-org-headings~ user option
+
+[ Part of {{{development-version}}}. ]
+
+When the user option ~denote-link-to-org-headings~ is non-nil store
+link to the current Org heading inside a Denote file. This determines
+how the command ~org-store-link~ behaves when inside a Denote file.
+The heading at point is given a =CUSTOM_ID= value (included in its
+=PROPERTIES= drawer), unless it already has one, in which case it is
+taken as-is.
+
+If nil, only store links to the Denote file (using its identifier),
+but not to the given heading. This is what Denote was doing in
+versions prior to 3.0.0.
+
+This only works in Org mode, as other file types do not have a linking
+mechanism that handles unique identifiers for headings or other
+patterns to jump to.
+
 ** Insert links matching a regexp
 :PROPERTIES:
 :CUSTOM_ID: h:9bec2c83-36ca-4951-aefc-7187c5463f90
diff --git a/denote.el b/denote.el
index e38b2f5810..b97daf10ea 100644
--- a/denote.el
+++ b/denote.el
@@ -362,6 +362,25 @@ and/or when the user invokes the command `denote-date'."
   :package-version '(denote . "0.6.0")
   :type 'boolean)
 
+(defcustom denote-link-to-org-headings t
+  "When non-nil store link to the current Org heading inside a Denote file.
+
+This determines how the command `org-store-link' behaves when
+inside a Denote file.  The heading at point is given a CUSTOM_ID
+value (included in its PROPERTIES drawer), unless it already has
+one, in which case it is taken as-is.
+
+If nil, only store links to the Denote file (using its
+identifier), but not to the given heading.  This is what Denote
+was doing in versions prior to 3.0.0.
+
+This only works in Org mode, as other file types do not have a
+linking mechanism that handles unique identifiers for headings or
+other patterns to jump to."
+  :group 'denote
+  :package-version '(denote . "3.0.0")
+  :type 'boolean)
+
 (defcustom denote-templates nil
   "Alist of content templates for new notes.
 A template is arbitrary text that Denote will add to a newly
@@ -3914,6 +3933,21 @@ interface by first selecting the `denote:' hyperlink 
type."
 (declare-function org-link-store-props "ol.el" (&rest plist))
 (defvar org-store-link-plist)
 
+(declare-function org-entry-put "org" (pom property value))
+(declare-function org-entry-get "org" (pom property &optional inherit 
literal-nil))
+(declare-function org-id-new "org-id" (&optional prefix))
+
+(defun denote--link-ol-id-get-create ()
+  "Create a CUSTOM_ID for current entry under POSITION and return it.
+If the entry already has a CUSTOM_ID, return it as-is."
+  (let* ((pos (point))
+         (id (org-entry-get pos "CUSTOM_ID")))
+    (if (and id (stringp id) (string-match-p "\\S-" id))
+        id
+      (setq id (org-id-new "h"))
+      (org-entry-put pos "CUSTOM_ID" id)
+      id)))
+
 ;;;###autoload
 (defun denote-link-ol-store ()
   "Handler for `org-store-link' adding support for denote: links."
@@ -3925,7 +3959,9 @@ interface by first selecting the `denote:' hyperlink 
type."
     (org-link-store-props
      :type "denote"
      :description file-title
-     :link (concat "denote:" file-id))
+     :link (if denote-link-to-org-headings
+               (format "denote:%s::#%s" file-id 
(denote--link-ol-id-get-create))
+             (concat "denote:" file-id)))
     org-store-link-plist))
 
 ;;;###autoload