[elpa] externals/denote 0d27b6ef20 12/32: Rename user option to denote-org-store-link-to-heading and document it better

[ELPA Syncer]

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

    Rename user option to denote-org-store-link-to-heading and document it 
better
    
    The new name is more descriptive and better describes what the effect is.
---
 README.org | 44 +++++++++++++++++++++++++-------------------
 denote.el  | 49 +++++++++++++++++++++++++++++++++----------------
 2 files changed, 58 insertions(+), 35 deletions(-)

diff --git a/README.org b/README.org
index 46621e2119..d71235f738 100644
--- a/README.org
+++ b/README.org
@@ -1736,7 +1736,7 @@ The following sections delve into the details.
 
 #+findex: denote-link
 The ~denote-link~ command inserts a link at point to a file specified
-at the minibuffer prompt ([[#h:d99de1fb-b1b7-4a74-8667-575636a4d6a4][The 
~denote-link-to-org-headings~ user option]]).
+at the minibuffer prompt ([[#h:d99de1fb-b1b7-4a74-8667-575636a4d6a4][The 
~denote-org-store-link-to-heading~ user option]]).
 Links are formatted depending on the file type of the current note. In
 Org and plain text buffers, links are formatted thus:
 =[[denote:IDENTIFIER][TITLE]]=. While in Markdown they are expressed
@@ -1777,40 +1777,46 @@ 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
+** The ~denote-org-store-link-to-heading~ user option
 :PROPERTIES:
 :CUSTOM_ID: h:d99de1fb-b1b7-4a74-8667-575636a4d6a4
 :END:
 
 [ 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.
+The user option ~denote-org-store-link-to-heading~ determines whether
+~org-store-link~ links to the current Org heading.
 
-If ~denote-link-to-org-headings~ is set to nil, the command
-~org-store-link~ only store a link 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.
+When its value is non-nil, ~org-store-link~ stores a link to the
+current Org heading inside the Denote file. If the heading does not
+have a =CUSTOM_ID=, it creates it and includes it in the heading's
+=PROPERTIES= drawer. If a =CUSTOM_ID= exists, ~org-store-link~ use it
+as-is.
 
-When we inspect the links, the difference is this:
+This make the resulting link a combination of the =denote:= link type,
+pointing to the identifier of the current file, plus the value of the
+heading's =CUSTOM_ID=, such as:
 
-- =[[denote:20231125T060608][Some test]]=
-- =[[denote:20231125T060608::#h:eed0fb8e-4cc7-478f-acb6-f0aa1a8bffcd][Some 
test]]=
+- =[[denote:20240118T060608][Some test]]=
+- =[[denote:20240118T060608::#h:eed0fb8e-4cc7-478f-acb6-f0aa1a8bffcd][Some 
test]]=
 
 Both lead to the same Denote file, but the latter jumps to the heading
-with the given identifier.
+with the given =CUSTOM_ID=.
 
 The value of the =CUSTOM_ID= is determined by the Org user option
 ~org-id-method~. The sample shown above uses the default UUID
 infrastructure.
 
-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.
+If ~denote-org-store-link-to-heading~ is set to a nil value, the
+command ~org-store-link~ only stores 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 feature only works in Org mode files, as other file types do
+  not have a linking mechanism that handles unique identifiers for
+  headings or other patterns to jump to. If ~org-store-link~ is
+  invoked in one such file, it captures only the Denote identifier of
+  the file, even if this user option is set to a non-nil value. ]"
 
 ** Insert links matching a regexp
 :PROPERTIES:
diff --git a/denote.el b/denote.el
index 5cecff2ed2..77185ce24f 100644
--- a/denote.el
+++ b/denote.el
@@ -362,21 +362,38 @@ 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."
+(defcustom denote-org-store-link-to-heading t
+  "Determine whether `org-store-link' links to the current Org heading.
+
+When non-nil store link to the current Org heading inside the
+Denote file.  If the heading does not have a CUSTOM_ID, create it
+and include it in its PROPERTIES drawer.  If a CUSTOM_ID exists,
+take it as-is.
+
+Make the resulting link a combination of the `denote:' link type,
+pointing to the identifier of the current file, plus the value of
+the heading's CUSTOM_ID, such as:
+
+- [[denote:20240118T060608][Some test]]
+- [[denote:20240118T060608::#h:eed0fb8e-4cc7-478f-acb6-f0aa1a8bffcd][Some 
test]]
+
+Both lead to the same Denote file, but the latter jumps to the heading
+with the given CUSTOM_ID.
+
+The value of the CUSTOM_ID is determined by the Org user option
+`org-id-method'.  The sample shown above uses the default UUID
+infrastructure.
+
+If this user option is set to 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 feature only works in Org mode files, as other file types
+  do not have a linking mechanism that handles unique identifiers
+  for headings or other patterns to jump to.  If `org-store-link'
+  is invoked in one such file, it captures only the Denote
+  identifier of the file, even if this user option is set to a
+  non-nil value.  ]"
   :group 'denote
   :package-version '(denote . "3.0.0")
   :type 'boolean)
@@ -4025,7 +4042,7 @@ create a new one."
     (org-link-store-props
      :type "denote"
      :description file-title
-     :link (if (and denote-link-to-org-headings (derived-mode-p 'org-mode))
+     :link (if (and denote-org-store-link-to-heading (derived-mode-p 
'org-mode))
                (format "denote:%s::#%s" file-id (denote-link-ol-get-id))
              (concat "denote:" file-id)))
     org-store-link-plist))