forked from mirrors/org-mode
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.
This commit is contained in:
parent
5a1b050310
commit
e3a05d09b7
|
@ -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
|
||||
|
|
79
lisp/ol.el
79
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))))
|
||||
|
|
Loading…
Reference in a new issue