[PATCH] ol.el: add description format parameter to org-link-parameters

[Hugo Heagren]

* ol.el (org-link-parameters): add parameter `:default-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 `:default-description' (if
non-nil) parameter to generate one.

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.
---
 lisp/ol.el | 49 +++++++++++++++++++++++++++++++++++--------------
 1 file changed, 35 insertions(+), 14 deletions(-)

diff --git a/lisp/ol.el b/lisp/ol.el
index 1b2bb9a9a..af0aaaf35 100644
--- a/lisp/ol.el
+++ b/lisp/ol.el
@@ -140,6 +140,13 @@ link.
   Function that inserts a link with completion.  The function
   takes one optional prefix argument.
 
+`:default-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 the full link text as the sole argument, and should
+  return a single string.
+
 `:display'
 
   Value for `invisible' text property on the hidden parts of the
@@ -1761,11 +1768,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 `:default-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))
@@ -1775,7 +1785,7 @@ don't allow to edit the default description."
         (desc region)
         (link link-location)
         (abbrevs org-link-abbrev-alist-local)
-        entry all-prefixes auto-desc)
+        entry all-prefixes auto-desc type)
     (cond
      (link-location)                 ; specified by arg, just use it.
      ((org-in-regexp org-link-bracket-re 1)
@@ -1842,6 +1852,7 @@ Use TAB to complete link prefixes, then RET for 
type-specific completion support
                      (and (equal ":" (substring link -1))
                           (member (substring link 0 -1) all-prefixes)
                           (setq link (substring link 0 -1))))
+              (setq type link)
              (setq link (with-current-buffer origbuf
                           (org-link--try-special-completion link)))))
        (set-window-configuration wcf)
@@ -1918,14 +1929,24 @@ Use TAB to complete link prefixes, then RET for 
type-specific completion support
       (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))))))
+              (desc)
+              ((org-link-get-parameter
+                type
+                :default-description)
+               (let ((def (org-link-get-parameter
+                           type
+                           :default-description)))
+                 (cond
+                  ((stringp def) def)
+                  ((functionp def)
+                   (funcall def link)))))
+             (org-link-make-description-function
+               (funcall org-link-make-description-function link desc))
+              (t (error
+                 (message "Can't get link description from %S"
+                          (symbol-name 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