branch: externals/denote
commit a3109ed9b41f4bb99878c620027677ee9de8e0d8
Author: Protesilaos Stavrou <[email protected]>
Commit: Protesilaos Stavrou <[email protected]>
Call function of denote-link-description-format with two arguments
I still support the old calling convention to not break existing code,
but we should move to the new one eventually. This way we can pass the
file type as an argument to not have to calculate it more than once
while calling 'denote-link' and related.
---
README.org | 34 +++++++++++++++++++++-------------
denote.el | 58 ++++++++++++++++++++++++++++++++++++++++------------------
2 files changed, 61 insertions(+), 31 deletions(-)
diff --git a/README.org b/README.org
index b8e57e0696..8ab8aa73d8 100644
--- a/README.org
+++ b/README.org
@@ -3639,11 +3639,17 @@ command ~denote-link~ and related functions create a
link 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.
+it is called with two argument, the file and file type, 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).
-The default is a function that returns the active region or the title of
-the note (with the signature if present).
+For backward compatibility, the function can also take a single
+parameter, the given file. In that case, it is responsible for
+figuring out the file type in order to return the correct description.
+
+[ The calling convention for the function with two arguments is
+ introduced as part of {{{development-version}}}. ]
If the value is a string, it treats specially the following specifiers:
@@ -6047,22 +6053,24 @@ there will be no corresponding prompt.
#+findex: denote-link-description-with-signature-and-title
+ Function ~denote-link-description-with-signature-and-title~ :: Return
- link description for =FILE=. Produce a description as follows:
+ link description for =FILE= with =FILE-TYPE=. For backward
+ compatibility, =FILE-TYPE= is an optional parameter. If it is ~nil~,
+ then compute =FILE-TYPE= internally. [ =FILE-TYPE= is added as part
+ of {{{development-version}}}. ]
- If the region is active, use it as the description.
- - If =FILE= as a signature, then use the
- ~denote-link-signature-format~. By default, this looks like
- "signature title".
+ - 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.
-#+vindex: denote-link-description-function
-+ Variable ~denote-link-description-function~ :: Function to use to
- create the description of links. The function specified should take
- a =FILE= argument and should return the description as a string. By
- default, the title of the file is returned as the description.
+ - If none of the above works, return an empty string.
+
+ This function is useful as the value of the user option
+ ~denote-link-description-format~ (which can optionally be bound to a
+ function).
** Xref interface for developers or advanced users
:PROPERTIES:
diff --git a/denote.el b/denote.el
index dcb15736be..45d736e301 100644
--- a/denote.el
+++ b/denote.el
@@ -907,11 +907,14 @@ This determines how `denote-link' and related functions
create a link
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.
+is called with two arguments, the file and file type as a symbol among
+`denote-file-types'. It 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).
-The default is a function that returns the active region or the title of
-the note (with the signature if present).
+For backward compatibility, the function can also take a single
+parameter, the given file. In that case, it is responsible for figuring
+out the file type in order to return the correct description.
If the value is a string, it treats specially the following specifiers:
@@ -5233,8 +5236,13 @@ See the `:link' property of `denote-file-types'."
(denote-retrieve-filename-identifier file)
description))
-(defun denote-link-description-with-signature-and-title (file)
- "Return link description for FILE.
+;; NOTE 2025-11-23: The only reason I have &optional is because I want
+;; it to be backward compatible. We used to have a single FILE
+;; parameter.
+(defun denote-link-description-with-signature-and-title (file &optional
file-type)
+ "Return link description for FILE with FILE-TYPE.
+For backward compatibility, FILE-TYPE is an optional parameter. If it
+is nil, then compute FILE-TYPE internally.
- If the region is active, use it as the description.
@@ -5244,14 +5252,14 @@ See the `:link' property of `denote-file-types'."
- 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'."
- ;; FIXME 2025-11-22: Hwere we are doing `denote-filetype-heuristics'
- ;; when `denote-link' has already done it. We have to avoid such
- ;; duplication.
- (let* ((file-type (denote-filetype-heuristics file))
+- If none of the above works, return an empty string.
+
+This function is useful as the value of the user option
+`denote-link-description-format' (which can optionally be bound to a
+function)."
+ (let* ((type (or file-type (denote-filetype-heuristics file)))
(signature (denote-retrieve-filename-signature file))
- (title (denote-retrieve-title-or-filename file file-type))
+ (title (denote-retrieve-title-or-filename file type))
(region-text (denote--get-active-region-content)))
(cond
(region-text region-text)
@@ -5276,24 +5284,38 @@ This is useful as the value of the user option
(end (region-end)))
(delete-region beg end)))
-(defun denote-get-link-description (file)
+(defun denote-get-link-description (file &optional file-type)
"Return a link description for FILE.
-If `denote-link-description-format' is a function, call it with FILE as
-an argument. The function should return a string, representing the link
+If `denote-link-description-format' is a function, call it with FILE and
+FILE-TYPE as argument. It should return a string, representing the link
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). If the region is
-active, use it as the description."
+active, use it as the description.
+
+For backward compatibility, support the scenario where the function
+assigned to `denote-link-description-format' accepts a single FILE
+argument. In that case, the function takes care to find the TYPE on its
+own to return the appropriate description."
(cond
+ ((when-let* ((_ (and file-type (functionp denote-link-description-format)))
+ ;; NOTE 2025-11-23: We used to have
+ ;; `denote-link-description-format' accept a function
+ ;; with a single parameter. Now we expect two
+ ;; arguments, but must be backward compatible.
+ (description (ignore-error wrong-number-of-arguments
+ (funcall denote-link-description-format file
file-type))))
+ description))
((functionp denote-link-description-format)
+ (display-warning 'denote "The `denote-link-description-format' function is
now called with FILE and FILE-TYPE" :warning)
(funcall denote-link-description-format file))
((stringp denote-link-description-format)
(if-let* ((region (denote--get-active-region-content)))
region
- (let ((type (denote-filetype-heuristics file)))
+ (let ((type (or file-type (denote-filetype-heuristics file))))
(string-trim
(format-spec denote-link-description-format
(list (cons ?t (cond
