[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[elpa] externals/org e3a05d09b7 1/5: ol.el: add description format param
From: |
ELPA Syncer |
Subject: |
[elpa] externals/org e3a05d09b7 1/5: ol.el: add description format parameter to org-link-parameters |
Date: |
Sat, 6 Aug 2022 02:57:50 -0400 (EDT) |
branch: externals/org
commit e3a05d09b7398b46e8ef724ae7609eeb8a35346e
Author: Hugo Heagren <hugo@heagren.com>
Commit: Ihor Radchenko <yantar92@gmail.com>
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 4cbac2311b..700dd4a26c 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 02c9e1009f..04da3a686c 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))))