[elpa] externals/denote a062d9a351 294/355: Update link-related docs (cover buttonization)

[ELPA Syncer]

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

    Update link-related docs (cover buttonization)
---
 README.org | 73 +++++++++++++++++++++++---------------------------------------
 1 file changed, 27 insertions(+), 46 deletions(-)

diff --git a/README.org b/README.org
index f50f43927c..fe4acfa355 100644
--- a/README.org
+++ b/README.org
@@ -586,8 +586,9 @@ participate in the development of Denote.
 :END:
 
 DEVELOPMENT NOTE 2022-06-19 22:48 +0300: This is the final part that
-remains to be finalised before the release of the first stable version.
-There still are some updates to be made.
+remains to be finalised before the release of the first stable version
+(planned for 2022-06-22--2022-06-24).  There still are some updates to
+be made.
 
 #+findex: denote-link
 The ~denote-link~ command inserts a link at point to an entry specified
@@ -600,45 +601,19 @@ 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.
 
-How those links behave will depend on the user's preference.  Denote
-provides a simple-minded implementation for such link, which either
-works competently with point-and-click kind of interaction or, at the
-user's discretion, is more rudimentary and depends on Denote commands
-and/or Emacs' standard "future history" heuristics.
-
-  #+vindex: denote-link-register-ol-hyperlink
-+ The "just works" approach depends on Org's ability to open links it
-  recognizes regardless of the current major-mode.  The command for that
-  is ~org-open-at-point-global~.  User may want to bind it to a key of
-  their choosing, with =C-c o= looking like a decent choice.  Denote
-  defines a custom Org hyperlink and Org handles the rest.  The user
-  option ~denote-link-register-ol-hyperlink~ determines whether Denote
-  will register such a hyperlink type.  Users who do not want to load
-  Org, must set the variable to nil before loading denote-link.el.
-
-  The special prefix =denote:= lets us define links with only the
-  identifier.  They are robust and will work even if the file is renamed
-  (~denote-dired-rename-file~ never modifies the identifier).  Otherwise
-  they are familiar Org-style links in ~org-mode~ buffers.  They can be
-  followed with a mouse click or the ~org-open-at-point~ command, and
-  they may be insterted with completion via the ~org-insert-link~
-  command after selecting the =denote:= link type.
-
-+ The "rudimentary" method does not depend on Org's hyperlink
-  infrastructure.  As a general feature of Emacs, any identifier that
-  appears in a note, can be expanded into the corresponding file name at
-  the same directory by leveraging Emacs' notion of "future history"
-  (predicting what the user wants).  With point over the identifier,
-  =M-x find-file= followed by =M-n= will fill the path to that file.
-
-Whatever the user's preference, Denote establishes links using the
-note's identifier which is always unique and will yield the expected
-results whether the user prefers Org, plain text, or even command-line
-utilities.
-
-Everything that follows is independent of the user's preference on
-whether to use the Org hyperlink infrastructure (besides, the
-Org-specific code is less than 30 lines as of 2022-06-15 11:50 +0300).
+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.
+
+To buttonize links in existing files while visiting them, the user must
+add this snippet to their setup:
+
+#+findex: denote-link-buttonize-buffer
+#+begin_src emacs-lisp
+(add-hook 'find-file-hook #'denote-link-buttonize-buffer)
+#+end_src
 
 #+findex: denote-link-find-file
 Denote has a major-mode-agnostic mechanism to collect all linked file
@@ -646,11 +621,12 @@ references in the current buffer and return them as an 
appropriately
 formatted list.  This list can then be used in interactive commands.
 The ~denote-link-find-file~ is such a command.  It uses minibuffer
 completion to visit a file that is linked to from the current note.  The
-candidates have the correct metadata, meaning that a package such as
-=marginalia= will display accurate annotations, while the =embark=
-package will be able to work its magic such as in exporting the list
-into a filtered Dired buffer (i.e. a familiar Dired listing with only
-the files of the current minibuffer session).
+candidates have the correct metadata, which is ideal for integration
+with other standards-compliant tools 
([[#h:8ed2bb6f-b5be-4711-82e9-8bee5bb06ece][Extending Denote]]).  For instance,
+a package such as =marginalia= will display accurate annotations, while
+the =embark= package will be able to work its magic such as in exporting
+the list into a filtered Dired buffer (i.e. a familiar Dired listing
+with only the files of the current minibuffer session).
 
 #+findex: denote-link-backlinks
 The command ~denote-link-backlinks~ produces a bespoke buffer which
@@ -1251,6 +1227,11 @@ Everything is in place to set up the package.
 ;; package is available.
 (require 'denote-retrieve)
 (require 'denote-link)
+
+;; If you use Markdown or plain text files (Org renders links as buttons
+;; right away)
+(add-hook 'find-file-hook #'denote-link-buttonize-buffer)
+
 (require 'denote-dired)
 (setq denote-dired-rename-expert nil)