diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS index 4cbac2311..700dd4a26 100644 --- a/etc/ORG-NEWS +++ b/etc/ORG-NEWS @@ -400,6 +400,13 @@ purpose of the variable. The replacement variable accepts =listings= and =verbatim= in place of =t= and =nil= (which still work, but are no longer listed as valid options). +*** ~org-link-parameters~ has a new ~:insert-description~ parameter + +The value of ~:insert-description~ is used as the initial input when +prompting for a link description. It can be a string (used as-is) or +a function (called with the same arguments as +~org-make-link-description-function~ to return a string to use). + * Version 9.5 ** Important announcements and breaking changes diff --git a/lisp/ol.el b/lisp/ol.el index 02c9e1009..04da3a686 100644 --- a/lisp/ol.el +++ b/lisp/ol.el @@ -141,6 +141,19 @@ link. Function that inserts a link with completion. The function takes one optional prefix argument. +`:insert-description' + + String or function used as a default when prompting users for a + link's description. A string is used as-is, a function is + called with two arguments: the link location (a string such as + \"~/foobar\", \"id:some-org-id\" or \"https://www.foo.com\") + and the description generated by `org-insert-link'. It should + return the description to use (this reflects the behaviour of + `org-link-make-description-function'). If it returns nil, no + default description is used, but no error is thrown (from the + user's perspective, this is equivalent to a default description + of \"\"). + `:display' Value for `invisible' text property on the hidden parts of the @@ -200,7 +213,9 @@ You can interactively set the value of this variable by calling This function must take two parameters: the first one is the link, the second one is the description generated by `org-insert-link'. The function should return the description to -use." +use. If it returns nil, no default description is used, but no +error is thrown (from the user’s perspective, this is equivalent +to a default description of \"\")." :group 'org-link :type '(choice (const nil) (function)) :safe #'null) @@ -1802,11 +1817,14 @@ prefix negates `org-link-keep-stored-after-insertion'. If the LINK-LOCATION parameter is non-nil, this value will be used as the link location instead of reading one interactively. -If the DESCRIPTION parameter is non-nil, this value will be used as the -default description. Otherwise, if `org-link-make-description-function' -is non-nil, this function will be called with the link target, and the -result will be the default link description. When called non-interactively, -don't allow to edit the default description." +If the DESCRIPTION parameter is non-nil, this value will be used +as the default description. If not, and the chosen link type has +a non-nil `:insert-description' parameter, that is used to +generate a description as described in `org-link-parameters' +docstring. Otherwise, if `org-link-make-description-function' is +non-nil, this function will be called with the link target, and +the result will be the default link description. When called +non-interactively, don't allow to edit the default description." (interactive "P") (let* ((wcf (current-window-configuration)) (origbuf (current-buffer)) @@ -1816,7 +1834,10 @@ don't allow to edit the default description." (desc region) (link link-location) (abbrevs org-link-abbrev-alist-local) - entry all-prefixes auto-desc) + (all-prefixes (append (mapcar #'car abbrevs) + (mapcar #'car org-link-abbrev-alist) + (org-link-types))) + entry auto-desc) (cond (link-location) ; specified by arg, just use it. ((org-in-regexp org-link-bracket-re 1) @@ -1857,9 +1878,6 @@ Use TAB to complete link prefixes, then RET for type-specific completion support (unless (pos-visible-in-window-p (point-max)) (org-fit-window-to-buffer)) (and (window-live-p cw) (select-window cw)))) - (setq all-prefixes (append (mapcar #'car abbrevs) - (mapcar #'car org-link-abbrev-alist) - (org-link-types))) (unwind-protect ;; Fake a link history, containing the stored links. (let ((org-link--history @@ -1956,17 +1974,36 @@ Use TAB to complete link prefixes, then RET for type-specific completion support (setq desc path))))) (unless auto-desc - (let ((initial-input - (cond - (description) - ((not org-link-make-description-function) desc) - (t (condition-case nil - (funcall org-link-make-description-function link desc) - (error - (message "Can't get link description from %S" - (symbol-name org-link-make-description-function)) - (sit-for 2) - nil)))))) + (let* ((type + (cond + ((string-match (rx-to-string `(: string-start (submatch (or ,@all-prefixes)) ":")) link) + (match-string 1 link)) + ((file-name-absolute-p link) "file") + ((string-match "\\`\\.\\.?/" link) "file"))) + (initial-input + (cond + (description) + (desc) + ((org-link-get-parameter type :insert-description) + (let ((def (org-link-get-parameter type :insert-description))) + (condition-case nil + (cond + ((stringp def) def) + ((functionp def) + (funcall def link desc))) + (error + (message "Can't get link description from org link parameter `:insert-description': %S" + def) + (sit-for 2) + nil)))) + (org-link-make-description-function + (condition-case nil + (funcall org-link-make-description-function link desc) + (error + (message "Can't get link description from %S" + org-link-make-description-function) + (sit-for 2) + nil)))))) (setq desc (if (called-interactively-p 'any) (read-string "Description: " initial-input) initial-input))))