Function: denote-get-link-description

denote-get-link-description is a byte-compiled function defined in denote.el.

Signature

(denote-get-link-description FILE &optional FILE-TYPE)

Documentation

Return a link description for FILE.

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.

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.

Aliases

denote--link-get-description (obsolete since 4.0.0)

Source Code

;; Defined in ~/.emacs.d/elpa/denote-4.2.3/denote.el
(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 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.

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
   ((functionp denote-link-description-format)
    ;; NOTE 2025-11-23: `denote-link-description-format' used to
    ;; accept a function with a single parameter.  Now we expect two
    ;; arguments, but must be backward compatible.
    (if (> (cdr (func-arity denote-link-description-format)) 1)
        (funcall denote-link-description-format file file-type)
      (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 (or file-type (denote-filetype-heuristics file))))
        (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 ?T (or (denote-retrieve-filename-title file) ""))
                            (cons ?i (or (denote-retrieve-filename-identifier file) ""))
                            ;; TODO 2025-04-03: Maybe we can have something like `denote-date-format' here,
                            ;; but I think we are okay with a hardcoded value.
                            (cons ?I (or (when-let* ((id (denote-retrieve-filename-identifier file))
                                                     (_ (denote-date-identifier-p id)))
                                           (format-time-string "%A, %e %B %Y" (date-to-time (denote-id-to-date id))))
                                         ""))
                            (cons ?D (cond
                                      ((denote-retrieve-front-matter-title-value file type))
                                      ((denote-retrieve-filename-title file))
                                      ((when-let* ((id (denote-retrieve-filename-identifier file)))
                                         (if (denote-date-identifier-p id)
                                             (format-time-string "%A, %e %B %Y" (date-to-time (denote-id-to-date id)))
                                           id)))
                                      (t  "")))
                            (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"))))