From 039c2131462f5454f2804e809e085a055b5bf552 Mon Sep 17 00:00:00 2001 From: Hugo Heagren Date: Mon, 28 Mar 2022 23:18:45 +0100 Subject: [PATCH 1/2] ol.el: add description format parameter to org-link-parameters * ol.el (org-link-parameters): Add parameter `:insert-description', a string or a function. * (org-insert-link): If no description is provided (pre-existing or as an argument), next option is to use the `:insert-description' (if non-nil) parameter to generate one. * (org-link-make-description-function): Add documentation to describe behaviour of nil return value, like that of `:insert-description'. Default descriptions are predictable within a link type, but because link types are quite diverse, are NOT predictable across many types. A type-parameter is thus a good place to store information on the default description. --- etc/ORG-NEWS | 7 +++++ lisp/ol.el | 79 ++++++++++++++++++++++++++++++++++++++-------------- 2 files changed, 65 insertions(+), 21 deletions(-) diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS index 35af94f92..86128d100 100644 --- a/etc/ORG-NEWS +++ b/etc/ORG-NEWS @@ -322,6 +322,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 d4bd0e40c..abea2af5e 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) @@ -1804,11 +1819,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)) @@ -1818,7 +1836,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) @@ -1859,9 +1880,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 @@ -1958,17 +1976,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)))) -- 2.20.1