[elpa] externals/denote dc84ed95e2 3/4: Rewrite section about links

[ELPA Syncer]

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

    Rewrite section about links
    
    * Add subsections to make it easier to find information.
    * Document 'denote-link-dired-marked-notes'.
    * Clarify that links are only to what we count as "notes".
---
 README.org | 219 +++++++++++++++++++++++++++++++++++++++++--------------------
 1 file changed, 149 insertions(+), 70 deletions(-)

diff --git a/README.org b/README.org
index 2a800b8e8d..ed3e4b9ae0 100644
--- a/README.org
+++ b/README.org
@@ -723,6 +723,22 @@ in the doc string of ~format-time-string~..
 :CUSTOM_ID: h:fc913d54-26c8-4c41-be86-999839e8ad31
 :END:
 
+Denote offers several commands for linking between notes.
+
+All links target files which are Denote notes.  This means that they
+have our file-naming scheme, are writable/regular (not directory, named
+pipe, etc.), and use the appropriate file type extension (per
+~denote-file-type~).  Furthermore, the files need to be inside the
+~denote-directory~ or one of its subdirectories.  No other file is
+recognised.
+
+The following sections delve into the details.
+
+** Adding a single link
+:PROPERTIES:
+:CUSTOM_ID: h:5e5e3370-12ab-454f-ba09-88ff44214324
+:END:
+
 #+findex: denote-link
 The ~denote-link~ command inserts a link at point to an entry specified
 at the minibuffer prompt.  Links are formatted depending on the file
@@ -750,62 +766,13 @@ Org):
 The ~denote-link-buttonize-buffer~ is also an interactive function in
 case the user needs it [ this is part of {{{development-version}}} ].
 
-#+findex: denote-link-find-file
-Denote has a major-mode-agnostic mechanism to collect all linked file
-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, 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
-displays the file name of all notes linking to the current one.  Each
-file name appears on its own line and is buttonized so that it performs
-the action of visiting the referenced file.  The backlinks' buffer looks
-like this:
-
-#+begin_example
-Backlinks to "On being honest" (20220614T130812)
-------------------------------------------------
-
-20220614T145606--let-this-glance-become-a-stare__journal.txt
-20220616T182958--not-feeling-butterflies-in-your-stomach__journal.txt
-#+end_example
-
-#+vindex: denote-link-fontify-backlinks
-The backlinks' buffer is fontified by default, though the user has
-access to the ~denote-link-fontify-backlinks~ option to disable this
-effect by setting its value to nil.
-
-#+vindex: denote-link-backlinks-display-buffer-action
-The placement of the backlinks' buffer is subject to the user option
-~denote-link-backlinks-display-buffer-action~.  Due to the nature of the
-underlying ~display-buffer~ mechanism, this inevitably is a relatively
-advanced feature.  By default, the backlinks' buffer is displayed below
-the current window.  The doc string of our user option includes a sample
-configuration that places the buffer in a left side window instead.
-Reproducing it here for the sake of convenience:
-
-#+begin_src emacs-lisp
-(setq denote-link-backlinks-display-buffer-action
-      '((display-buffer-reuse-window
-         display-buffer-in-side-window)
-        (side . left)
-        (slot . 99)
-        (window-width . 0.3)))
-#+end_src
-
-Note that the backlinking facility uses Emacs' built-in Xref
-infrastructure.  On some operating systems, the user may need to add
-certain executables to the relevant environment variable.
+Links are created only for files which qualify as a "note" for our
+purposes ([[#h:fc913d54-26c8-4c41-be86-999839e8ad31][Linking notes]]).
 
-[[#h:42f6b07e-5956-469a-8294-17f9cf62eb2b][Why do I get "Search failed with 
status 1" when I search for backlinks?]]
+** Insert links matching a regexp
+:PROPERTIES:
+:CUSTOM_ID: h:9bec2c83-36ca-4951-aefc-7187c5463f90
+:END:
 
 #+findex: denote-link-add-links
 The command ~denote-link-add-links~ adds links at point matching a
@@ -861,15 +828,88 @@ Remember that regexp constructs only need to be escaped 
once (like =\|=)
 when done interactively but twice when called from Lisp.  What we show
 above is for interactive usage.
 
-#+findex: denote-link-insert-link
-#+findex: denote-link-show-backlinks-buffer
-#+findex: denote-link-insert-links-matching-regexp
-For convenience, the ~denote-link~ command has an alias called
-~denote-link-insert-link~.  The ~denote-link-backlinks~ can also be used
-as ~denote-link-show-backlinks-buffer~.  While ~denote-link-add-links~
-is aliased ~denote-link-insert-links-matching-regexp~.  The purpose of
-these aliases is to offer alternative, more descriptive names of select
-commands.
+Links are created only for files which qualify as a "note" for our
+purposes ([[#h:fc913d54-26c8-4c41-be86-999839e8ad31][Linking notes]]).
+
+** Insert links from marked files in Dired
+:PROPERTIES:
+:CUSTOM_ID: h:9cbb692e-5d8a-44a6-9193-899a07872a07
+:END:
+
+[ The ~denote-link-dired-marked-notes~ is part of {{{development-version}}} ]
+
+#+findex: denote-link-dired-marked-notes
+The command ~denote-link-dired-marked-notes~ is similar to
+~denote-link-add-links~ in that it inserts in the buffer a typographic
+list of links to Denote notes 
([[#h:9bec2c83-36ca-4951-aefc-7187c5463f90][Insert links matching a regexp]]).  
Though
+instead of reading a regular expression, it lets the user mark files in
+Dired and link to them.  This should be easier for users of all skill
+levels, instead of having to write a potentially complex regular
+expression.
+
+If there are multiple buffers that visit a Denote note, this command
+will ask to select one among them, using minibuffer completion.  If
+there is only one buffer, it will operate in it outright.  If there are
+no buffers, it will produce an error.
+
+With optional =ID-ONLY= as a prefix argument (=C-u= by default), the
+command inserts links with just the identifier, which is the same
+principle as with ~denote-link~ and others 
([[#h:5e5e3370-12ab-454f-ba09-88ff44214324][Adding a single link]]).
+
+The command ~denote-link-dired-marked-notes~ is meant to be used from a
+Dired buffer.
+
+As always, links are created only for files which qualify as a "note"
+for our purposes ([[#h:fc913d54-26c8-4c41-be86-999839e8ad31][Linking notes]]).
+
+** The backlinks' buffer
+:PROPERTIES:
+:CUSTOM_ID: h:c73f1f68-e214-49d5-b369-e694f6a5d708
+:END:
+
+#+findex: denote-link-backlinks
+The command ~denote-link-backlinks~ produces a bespoke buffer which
+displays the file name of all notes linking to the current one.  Each
+file name appears on its own line and is buttonized so that it performs
+the action of visiting the referenced file.  The backlinks' buffer looks
+like this:
+
+#+begin_example
+Backlinks to "On being honest" (20220614T130812)
+------------------------------------------------
+
+20220614T145606--let-this-glance-become-a-stare__journal.txt
+20220616T182958--not-feeling-butterflies-in-your-stomach__journal.txt
+#+end_example
+
+#+vindex: denote-link-fontify-backlinks
+The backlinks' buffer is fontified by default, though the user has
+access to the ~denote-link-fontify-backlinks~ option to disable this
+effect by setting its value to nil.
+
+#+vindex: denote-link-backlinks-display-buffer-action
+The placement of the backlinks' buffer is subject to the user option
+~denote-link-backlinks-display-buffer-action~.  Due to the nature of the
+underlying ~display-buffer~ mechanism, this inevitably is a relatively
+advanced feature.  By default, the backlinks' buffer is displayed below
+the current window.  The doc string of our user option includes a sample
+configuration that places the buffer in a left side window instead.
+Reproducing it here for the sake of convenience:
+
+#+begin_src emacs-lisp
+(setq denote-link-backlinks-display-buffer-action
+      '((display-buffer-reuse-window
+         display-buffer-in-side-window)
+        (side . left)
+        (slot . 99)
+        (window-width . 0.3)))
+#+end_src
+
+Note that the backlinking facility uses Emacs' built-in Xref
+infrastructure.  On some operating systems, the user may need to add
+certain executables to the relevant environment variable.
+
+[[#h:42f6b07e-5956-469a-8294-17f9cf62eb2b][Why do I get "Search failed with 
status 1" when I search for backlinks?]]
 
 ** Writing metanotes
 :PROPERTIES:
@@ -883,12 +923,18 @@ insights.  For example, you might want to read your 
journal entries from
 the past year to reflect on your experiences, evolution as a person, and
 the like.
 
-The command ~denote-link-add-links~, which we covered extensively in the
-previous section, is suited for this task 
([[#h:fc913d54-26c8-4c41-be86-999839e8ad31][Linking notes]]).  You will
-create your metanote the way you use Denote ordinarily (metanotes may
-have the =metanote= keyword), write an introduction or however you want
-to go about it, invoke ~denote-link-add-links~ to cite the notes that
-match the given regexp, and continue writing.
+The commands ~denote-link-add-links~, ~denote-link-dired-marked-notes~
+are suited for this task.
+
+[[#h:9bec2c83-36ca-4951-aefc-7187c5463f90][Insert links matching a regexp]].
+
+[[#h:9cbb692e-5d8a-44a6-9193-899a07872a07][Insert links from marked files in 
Dired]].
+
+You will create your metanote the way you use Denote ordinarily
+(metanotes may have the =metanote= keyword, among others), write an
+introduction or however you want to go about it, invoke the command
+which inserts multiple links at once (see the above-cited nodes), and
+continue writing.
 
 Metanotes can serve as entry points to groupings of individual notes.
 They are not the same as a filtered list of files, i.e. what you would
@@ -901,6 +947,39 @@ Your future self will appreciate metanotes for the 
function they serve
 in encapsulating knowledge, while current you will be equipped with the
 knowledge derived from the deliberate self-reflection.
 
+** Visiting linked files via the minibuffer
+:PROPERTIES:
+:CUSTOM_ID: h:1bc2adad-dca3-4878-b9f0-b105d5dec6f4
+:END:
+
+#+findex: denote-link-find-file
+Denote has a major-mode-agnostic mechanism to collect all linked file
+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, 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).
+
+** Miscellaneous information about links
+:PROPERTIES:
+:CUSTOM_ID: h:dd8f2231-8d77-49b9-acc4-af525c68b271
+:END:
+
+#+findex: denote-link-insert-link
+#+findex: denote-link-show-backlinks-buffer
+#+findex: denote-link-insert-links-matching-regexp
+For convenience, the ~denote-link~ command has an alias called
+~denote-link-insert-link~.  The ~denote-link-backlinks~ can also be used
+as ~denote-link-show-backlinks-buffer~.  While ~denote-link-add-links~
+is aliased ~denote-link-insert-links-matching-regexp~.  The purpose of
+these aliases is to offer alternative, more descriptive names of select
+commands.
+
 * Fontification in Dired
 :PROPERTIES:
 :CUSTOM_ID: h:337f9cf0-9f66-45af-b73f-f6370472fb51