[elpa] externals/denote 31e5eb3af8 346/355: Update documentation about links

[ELPA Syncer]

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

    Update documentation about links
---
 README.org | 47 ++++++++++++++++++++++++++++++++---------------
 1 file changed, 32 insertions(+), 15 deletions(-)

diff --git a/README.org b/README.org
index 5fe953f56e..dc542aa5a9 100644
--- a/README.org
+++ b/README.org
@@ -422,25 +422,29 @@ want to lift that restriction once everything works as 
intended.
 :END:
 
 Notes have their own "front matter".  This is a block of data at the top
-of the file, which is automatically generated at the creation of a new
-note. The front matter includes the title and keywords (aka "tags" or
-"filetags", depending on the file type) which the user specified at the
-relevant prompt, as well as the date and unique identifier which are
-derived automatically.
+of the file, with no empty lines between the entries, which is
+automatically generated at the creation of a new note. The front matter
+includes the title and keywords (aka "tags" or "filetags", depending on
+the file type) which the user specified at the relevant prompt, as well
+as the date and unique identifier which are derived automatically.
 
 This is how it looks for Org mode (~denote-file-type~ is nil):
 
 #+begin_src org
 :PROPERTIES:
-:ID: 20220610T202537
+:ID:           20220610T202537
 :END:
 ,#+title:      This is a sample note
 ,#+date:       2022-06-10
 ,#+filetags:   denote  testing
 #+end_src
 
-For Markdown with YAML, it looks like this (~denote-file-type~ has the
-=markdown-yaml= value):
+Org notes use a =PROPERTIES= drawer at the top of the file for maximum
+compatibility with the Org ecosystem, particularly for linking to notes
+and exporting them ([[#h:fc913d54-26c8-4c41-be86-999839e8ad31][Linking 
notes]]).
+
+For Markdown with YAML, the front matter looks like this
+(~denote-file-type~ has the =markdown-yaml= value):
 
 #+begin_src md
 ---
@@ -633,11 +637,21 @@ When ~denote-link~ is called with a prefix argument 
(=C-u= by default)
 it formats links like =[[denote:IDENTIFIER]]=.  The user might prefer
 its simplicity.
 
+#+vindex: denote-link-use-org-id
+When the user option ~denote-link-use-org-id~ is set to non-nil (default
+is nil), inserted links in Org notes that target other Org notes will
+use the standard =id:= type so the format is =[[id:IDENTIFIER][TITLE]]=
+(the title is omitted is ~denote-link~ is called with a prefix argument,
+as explained above).  When, however, an Org note links to a note in
+another file, the link with use our own =denote:= type as there is no
+standard for this case.
+
 Inserted links are automatically buttonized and remain active for as
 long as the buffer is available.  In Org this is handled automatically
-as Denote creates its own custom hyperlink: the =denote:= type which
-works exactly like the =file:=.  In Markdown and plain text, Denote
-handles the buttonization of those links.
+as Denote either uses the standard =id:= link type or creates its own
+custom hyperlink: the =denote:= type which works exactly like the
+=file:=.  In Markdown and plain text, Denote handles the buttonization
+of those links.
 
 To buttonize links in existing files while visiting them, the user must
 add this snippet to their setup:
@@ -715,14 +729,17 @@ note is excluded from the matching entries (adding a link 
to itself is
 pointless).
 
 When called with a prefix argument (=C-u=) ~denote-link-add-links~ will
-format all links as =[[denote:IDENTIFIER]]=, hence a typographic list:
+format all links as =[[TYPE:IDENTIFIER]]=, hence a typographic list:
 
 #+begin_example
-- [[denote:IDENTIFIER-1]]
-- [[denote:IDENTIFIER-2]]
-- [[denote:IDENTIFIER-3]]
+- [[TYPE:IDENTIFIER-1]]
+- [[TYPE:IDENTIFIER-2]]
+- [[TYPE:IDENTIFIER-3]]
 #+end_example
 
+The =TYPE= is either =denote:= or =id:=, exactly as we explained above
+for the ~denote-link~ command.
+
 Same examples of a regular expression that can be used with this
 command: