[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[elpa] externals/denote 170a8234ae 3/3: Merge pull request #473 from jea
From: |
ELPA Syncer |
Subject: |
[elpa] externals/denote 170a8234ae 3/3: Merge pull request #473 from jeanphilippegg/link-descriptions |
Date: |
Mon, 4 Nov 2024 00:57:52 -0500 (EST) |
branch: externals/denote
commit 170a8234ae638b052719504d8e435844179f3dea
Merge: a05ed292bf 18e8bb9ece
Author: Protesilaos Stavrou <info@protesilaos.com>
Commit: GitHub <noreply@github.com>
Merge pull request #473 from jeanphilippegg/link-descriptions
Link descriptions
---
README.org | 10 ++++---
denote.el | 96 ++++++++++++++++++++++++++++++++++----------------------------
2 files changed, 59 insertions(+), 47 deletions(-)
diff --git a/README.org b/README.org
index eb72267a45..afa7987a48 100644
--- a/README.org
+++ b/README.org
@@ -3353,15 +3353,15 @@ select commands.
The user option ~denote-link-description-format~ controls how the
command ~denote-link~ and related functions create a link description
-by default, when no region is active. If the region is active, its
-text is used as the link's description when that is relevant (for
-example, some linking commands insert many links, so those do not
-consider the active region).
+by default.
The value can be either a function or a string. If it is a function,
it is called with one argument, the file, and should return a string
representing the link description.
+The default is a function that returns the active region or the title of
+the note (with the signature if present).
+
If the value is a string, it treats specially the following specifiers:
- The =%t= is the Denote =TITLE= of the file.
@@ -3388,6 +3388,8 @@ Any other text in the string it taken as-is. Users may
want, for
example, to include some text that makes Denote links stand out, such
as a =[D]= prefix.
+If the region is active, its text is used as the link's description.
+
* Choose which commands to prompt for
:PROPERTIES:
:CUSTOM_ID: h:98c732ac-da0e-4ebd-a0e3-5c47f9075e51
diff --git a/denote.el b/denote.el
index ca5968e548..e9802e39a6 100644
--- a/denote.el
+++ b/denote.el
@@ -865,18 +865,18 @@ have been warned."
;; FIXME 2024-11-03: This breaks `denote-link-with-signature'. Check
;; the FIXME above that function to decide how best to proceed.
-(defcustom denote-link-description-format "%t"
+(defcustom denote-link-description-format
#'denote-link-description-with-signature-and-title
"The format of a link description text.
This determines how `denote-link' and related functions create a link
-description by default, when no region is active. If the region is
-active, its text is used as the link's description when that is
-relevant (e.g. some linking commands insert many links, so those do not
-consider the active region).
+description by default.
The value can be either a function or a string. If it is a function, it
is called with one argument, the file, and should return a string
representing the link description.
+The default is a function that returns the active region or the title of
+the note (with the signature if present).
+
If the value is a string, it treats specially the following specifiers:
- The %t is the Denote TITLE of the file.
@@ -901,10 +901,12 @@ When combined all together, the above are written thus:
Any other text in the string it taken as-is. Users may want, for
example, to include some text that makes Denote links stand out, such as
-a [D] prefix."
+a [D] prefix.
+
+If the region is active, its text is used as the link's description."
:type '(choice
(string :tag "String with treats format specifiers specially")
- (function :tag "Custom function like `denote-get-link-description'"))
+ (function :tag "Custom function like
`denote-link-description-with-signature-and-title'"))
:package-version '(denote . "3.2.0")
:group 'denote)
@@ -4087,10 +4089,29 @@ With optional INCLUDE-DATE, convert the identifier using
(make-obsolete 'denote-link-signature-format nil "2.3.0")
-(make-obsolete
- 'denote-link-description-with-signature-and-title
- 'denote-get-link-description
- "3.2.0: Also see the user option `denote-link-description-format'.")
+(defun denote-link-description-with-signature-and-title (file)
+ "Return link description for FILE.
+
+- If the region is active, use it as the description.
+
+- If FILE has a signature, then format the description as a sequence of
+ the signature text and the title with two spaces between them.
+
+- If FILE does not have a signature, then use its title as the
+ description.
+
+This is useful as the value of the user option
+`denote-link-description-function'."
+ (let* ((file-type (denote-filetype-heuristics file))
+ (signature (denote-retrieve-filename-signature file))
+ (title (denote-retrieve-title-or-filename file file-type))
+ (region-text (denote--get-active-region-content)))
+ (cond
+ (region-text region-text)
+ ((and signature title) (format "%s %s" signature title))
+ (title (format "%s" title))
+ (signature (format "%s" signature))
+ (t ""))))
(defun denote--get-active-region-content ()
"Return the text of the active region, else nil."
@@ -4106,13 +4127,8 @@ With optional INCLUDE-DATE, convert the identifier using
(end (region-end)))
(delete-region beg end)))
-;; FIXME 2024-11-03: This breaks `denote-link-with-signature'. Check
-;; the FIXME above that function to decide how best to proceed.
-
-(defun denote-get-link-description (file &optional ignore-region)
+(defun denote-get-link-description (file)
"Return a link description for FILE.
-If the region is active, use it as the description, unless optional
-IGNORE-REGION is non-nil.
If `denote-link-description-format' is a function, call it with FILE as
an argument. The function should return a string, representing the link
@@ -4120,25 +4136,26 @@ description.
If the user option `denote-link-description-format' is a string, parse
it to substitute any format specifiers therein with their respective
-values (see the documentation of that user option)."
+values (see the documentation of that user option). If the region is
+active, use it as the description."
(cond
- ((unless ignore-region
- (denote--get-active-region-content)))
((functionp denote-link-description-format)
(funcall denote-link-description-format file))
((stringp denote-link-description-format)
- (string-trim
- (format-spec denote-link-description-format
- (list (cons ?t (cond
- ((denote-retrieve-front-matter-title-value
file (denote-filetype-heuristics file)))
- ((denote-retrieve-filename-title file))
- (t "")))
- (cons ?i (or (denote-retrieve-filename-identifier
file) ""))
- (cons ?d (or (denote-retrieve-filename-identifier
file) ""))
- (cons ?s (or (denote-retrieve-filename-signature file)
""))
- (cons ?k (or (denote-retrieve-filename-keywords file)
""))
- (cons ?% "%"))
- 'delete)))
+ (if-let* ((region (denote--get-active-region-content)))
+ region
+ (string-trim
+ (format-spec denote-link-description-format
+ (list (cons ?t (cond
+ ((denote-retrieve-front-matter-title-value
file (denote-filetype-heuristics file)))
+ ((denote-retrieve-filename-title file))
+ (t "")))
+ (cons ?i (or (denote-retrieve-filename-identifier
file) ""))
+ (cons ?d (or (denote-retrieve-filename-identifier
file) ""))
+ (cons ?s (or (denote-retrieve-filename-signature
file) ""))
+ (cons ?k (or (denote-retrieve-filename-keywords
file) ""))
+ (cons ?% "%"))
+ 'delete))))
(t
(error "The `denote-link-description-format' must be a function or
string"))))
@@ -4156,8 +4173,9 @@ 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-format', according to the function
-`denote-get-link-description'.
+`denote-link-description-format'. The default is to return the text of
+the active region or the title of the note (with the signature if
+present).
With optional ID-ONLY as a non-nil argument, such as with a universal
prefix (\\[universal-argument]), insert links with just the identifier
@@ -4189,14 +4207,6 @@ Also see `denote-link-with-signature'."
(defalias 'denote-insert-link 'denote-link
"Alias for `denote-link' command.")
-;; FIXME 2024-11-03: This is now broken by the
-;; `denote-get-link-description', which only reads the
-;; `denote-link-description-format'. How best to ensure we keep the
-;; behaviour that was there before? Maybe make the user option accept
-;; an alist and have `denote-get-link-description' try to read that if
-;; given a non-nil value for a CONSIDER-SIGNATURE parameter (or
-;; something along those lines)?
-
;;;###autoload
(defun denote-link-with-signature ()
"Insert link to file with signature.
@@ -4765,7 +4775,7 @@ Otherwise sort lines while accounting for
`denote-link-add-links-sort'.
Optional INCLUDE-DATE has the same meaning as in `denote-format-link'."
(let ((links))
(dolist (file files)
- (let* ((description (denote-get-link-description file :ignore-region))
+ (let* ((description (denote-get-link-description file))
(link (denote-format-link file description current-file-type
id-only include-date))
(link-as-list-item (format denote-link--prepare-links-format
link)))
(push link-as-list-item links)))