[elpa] externals/denote bfee3da14c 06/10: Reword the documentation of denote-link

[ELPA Syncer]

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

    Reword the documentation of denote-link
---
 README.org | 44 ++++++++++++++++++++++++++------------------
 denote.el  | 49 +++++++++++++++++++++----------------------------
 2 files changed, 47 insertions(+), 46 deletions(-)

diff --git a/README.org b/README.org
index 9dc86aa994..9b859594b8 100644
--- a/README.org
+++ b/README.org
@@ -2113,30 +2113,38 @@ 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-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][DESCRIPTION]]=. While in Markdown they are expressed
-as =[DESCRIPTION](denote:IDENTIFIER)=.
+at the minibuffer prompt. Links are formatted depending on the file
+type of the current note. In Org and plain text buffers, links are
+formatted thus: =[[denote:IDENTIFIER][DESCRIPTION]]=. While in
+Markdown they are expressed as =[DESCRIPTION](denote:IDENTIFIER)=.
+
+[ We optionally support links to Org headings 
([[#h:d99de1fb-b1b7-4a74-8667-575636a4d6a4][The 
~denote-org-store-link-to-heading~ user option]]).
+  Other file types do not have the features of Org, so we cannot
+  generalise this. ]
 
 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.
+default), it formats links like =[[denote:IDENTIFIER]]=, regardless of
+file type. The user might prefer its simplicity.
+
+By default, the description of the link is determined thus:
 
-By default, the description of the link is taken from the signature of
-the file, if present, and the target file's front matter's title or, if
-that is not available, from the file name.  If the region is active, its
-text is used as the link's description instead.  If the active region
-has no text, the inserted link uses just the identifier, as with the
-=C-u= prefix mentioned above.
+- If the region is active, its text becomes the description of the
+  link. In other words, the region text becomes the link.
+- If the region is active but has no text, the description is empty
+  and so the link is formatted the same way as if using the =C-u=
+  prefix argument.
+- If there is no region active, the description consists of the target
+  file's signature and title. The title is retrieved either from the
+  front matter or the file name.
+- If the target file has no signature, the title is used.
 
 Inserted links are automatically buttonized and remain active for as
-long as the buffer is available.  In Org this is handled by the major
+long as the buffer is available. In Org this is handled by the major
 mode: the =denote:= hyperlink type works exactly like the standard
-=file:=.  In Markdown and plain text, Denote performs the buttonization
-of those links.  To buttonize links in existing files while visiting
-them, the user must add this snippet to their setup (it already excludes
-Org):
+=file:= type. In Markdown and plain text, Denote performs the
+buttonization of those links. To buttonize links in existing files
+while visiting them, the user must add this snippet to their setup (it
+already excludes Org):
 
 #+findex: denote-link-buttonize-buffer
 #+begin_src emacs-lisp
diff --git a/denote.el b/denote.el
index ee1ad4e2b3..04f5d2c614 100644
--- a/denote.el
+++ b/denote.el
@@ -3798,34 +3798,27 @@ This is useful as the value of the user option
 (defun denote-link (file file-type description &optional id-only)
   "Create link to FILE note in variable `denote-directory' with DESCRIPTION.
 
-When called interactively, prompt for FILE using completion.  In
-this case, derive FILE-TYPE from the current buffer.
-
-The DESCRIPTION is returned by the function specified in variable
-`denote-link-description-function'.  If the region is active, its
-content is deleted and can be used as the description of the
-link.  The default value of `denote-link-description-function'
-returns the content of the active region, if any, else the title
-of the linked file is used as the description.  The title comes
-either from the front matter or the file name.  Note that if you
-change the default value of `denote-link-description-function',
-make sure to use the `region-text' parameter.  Regardless of the
-value of this user option, `denote-link' will always replace the
-content of the active region.
-
-With optional ID-ONLY as a non-nil argument, such as with a
-universal prefix (\\[universal-argument]), insert links with just
-the identifier and no further description.  In this case, the
-link format is always [[denote:IDENTIFIER]].  If the DESCRIPTION
-is empty, the link is also as if ID-ONLY were non-nil.  The
-default value of `denote-link-description-function' returns an
-empty string when the region is empty.  Thus, the link will have
-no description in this case.
-
-When called from Lisp, FILE is a string representing a full file
-system path.  FILE-TYPE is a symbol as described in
-`denote-file-type'.  DESCRIPTION is a string.  Whether the caller
-treats the active region specially, is up to it."
+When called interactively, prompt for FILE using completion.  In this
+case, derive FILE-TYPE from the current buffer.  FILE-TYPE is used to
+determine the format of the link.
+
+Return the DESCRIPTION of the link in the format specified by
+`denote-link-description-function'.  The default value of that variable,
+`denote-link-description-with-signature-and-title', uses the active
+region as the DESCRIPTION, or the FILE signature in addition to its
+title, or the FILE title.
+
+With optional ID-ONLY as a non-nil argument, such as with a universal
+prefix (\\[universal-argument]), insert links with just the identifier
+and no further description.  In this case, the link format is always
+[[denote:IDENTIFIER]].
+
+If the DESCRIPTION is empty, format the link the same as with ID-ONLY.
+
+When called from Lisp, FILE is a string representing a full file system
+path.  FILE-TYPE is a symbol as described in `denote-file-type'.
+DESCRIPTION is a string.  Whether the caller treats the active region
+specially, is up to it."
   (interactive
    (let* ((file (denote-file-prompt nil "Link to FILE"))
           (file-type (denote-filetype-heuristics buffer-file-name))