Re: [O] links-9.0 v3

[John Kitchin]

Sounds good. Thanks for your patience, I learned a lot doing this! I
look forward to using it in the wild ;)

Nicolas Goaziou writes:

> John Kitchin  writes:
>
>> Ok. I have attached 20 patches with the updates below.
>
> Applied, with minor tweaks (trailing white spaces and too wide lines).
> Thank you for all this work.
>
> Ultimately, I removed `org--open-file-link' altogether since default
> behaviour for file+apps links DTRT. I also started to deprecate
> file+apps links, i.e., they are still supported but we start suggesting
> to use plain "file" links instead.
>
> Regards,


-- 
Professor John Kitchin
Doherty Hall A207F
Department of Chemical Engineering
Carnegie Mellon University
Pittsburgh, PA 15213
412-268-7803
@johnkitchin
http://kitchingroup.cheme.cmu.edu

Re: [O] links-9.0 v3

[Nicolas Goaziou]

John Kitchin  writes:

> Ok. I have attached 20 patches with the updates below.

Applied, with minor tweaks (trailing white spaces and too wide lines).
Thank you for all this work.

Ultimately, I removed `org--open-file-link' altogether since default
behaviour for file+apps links DTRT. I also started to deprecate
file+apps links, i.e., they are still supported but we start suggesting
to use plain "file" links instead.

Regards,

Re: [O] links-9.0 v3

[John Kitchin]

Nicolas Goaziou writes:

> John Kitchin  writes:
>
>> I am not sure what you mean for this. Let me know if it isn't fixed in
>> the attached patches. I thought I had squashed everything into a concise
>> history.
>
> No worries. Let's just apply the 21 patches.

Ok. I have attached 20 patches with the updates below.

>
>> I think this code below (which should be in the patches) handles the
>> option correctly.
>>
>> (defun org--open-file-link (path app)
>
> It should, but I didn't see it in the previous patch, hence my remark.
>
>> -(defvar org-store-link-functions nil
>> -  "List of functions that are called to create and store a link.
>>  Each function will be called in turn until one returns a non-nil
>> -value.  Each function should check if it is responsible for creating
>> -this link (for example by looking at the major mode).
>> -If not, it must exit and return nil.
>> -If yes, it should return a non-nil value after a calling
>> -`org-store-link-props' with a list of properties and values.
>> -Special properties are:
>> +value.  Each function should check if it is responsible for
>> +creating this link (for example by looking at the major mode).  If
>> +not, it must exit and return nil.  If yes, it should return a
>> +non-nil value after a calling `org-store-link-props' with a list
>> +of properties and values. Special properties are:
>
> Missing a space after the full stop above.
>
>> +(defun org--open-file-link (path app)
>> +  "Open PATH using APP.
>> +
>> +PATH is from a file link, and can have the following syntax:
>> + [[file:~/code/main.c::255]]
>> + [[file:~/xx.org::My Target]]
>> + [[file:~/xx.org::*My Target]]
>> + [[file:~/xx.org::#my-custom-id]]
>> + [[file:~/xx.org::/regexp/]]
>> +
>> +APP is '(4) to open the PATH in Emacs, or 'system to use a system
>> application."
>
> Maybe something like:
>
>   Called it with \\[universal-argument] to open PATH in Emacs. If ARG is
>   `system', use a system application instead.
>
>
> Regards,
>From 9255b7f7b5462a82fb720720fc10eb5a1bd17297 Mon Sep 17 00:00:00 2001
From: John Kitchin 
Date: Thu, 7 Jul 2016 09:58:29 -0400
Subject: [PATCH 01/20] Create `org-link-parameters'

* lisp/org-element.el: Replace `org-link-types' variable with
  `org-link-types' function.

* lisp/org.el: Replace the `org-link-types' variable with
  `org-link-types' function. Create `org-link-get-parameter' and
  `org-link-set-parameters' functions. Remove `org-add-link-type'. Add
  `org-store-link-functions' function and remove
  `org-store-link-functions' variable. Add `org--open-file-link' for use
  as a :follow function for file type links.

* lisp/org.el: Set :follow functions for file links in `org-link-parameters.
Define `org-open-file-link' that opens a file link with an app.

* testing/lisp/test-ox.el: Remove usage of the `org-link-types'
  variable.

* lisp/org-compat.el: Move `org-add-link-type' and mark it as obsolete.

* lisp/ox.el: Change org-add-link-type comment in ox.el.
---
 lisp/org-compat.el  |  31 +
 lisp/org-element.el |   4 +-
 lisp/org.el | 168 
 lisp/ox.el  |   2 +-
 testing/lisp/test-ox.el |  16 ++---
 5 files changed, 156 insertions(+), 65 deletions(-)

diff --git a/lisp/org-compat.el b/lisp/org-compat.el
index 92fdb1c..a856ff7 100644
--- a/lisp/org-compat.el
+++ b/lisp/org-compat.el
@@ -374,6 +374,37 @@ Implements `define-error' for older emacsen."
 (put name 'error-conditions
 	 (copy-sequence (cons name (get 'error 'error-conditions))
 
+(defun org-add-link-type (type  follow export)
+  "Add a new TYPE link.
+FOLLOW and EXPORT are two functions.
+
+FOLLOW should take the link path as the single argument and do whatever
+is necessary to follow the link, for example find a file or display
+a mail message.
+
+EXPORT should format the link path for export to one of the export formats.
+It should be a function accepting three arguments:
+
+  paththe path of the link, the text after the prefix (like \"http:\")
+  descthe description of the link, if any
+  format  the export format, a symbol like `html' or `latex' or `ascii'.
+
+The function may use the FORMAT information to return different values
+depending on the format.  The return value will be put literally into
+the exported file.  If the return value is nil, this means Org should
+do what it normally does with links which do not have EXPORT defined.
+
+Org mode has a built-in default for exporting links.  If you are happy with
+this default, there is no need to define an export function for the link
+type.  For a simple example of an export function, see `org-bbdb.el'.
+
+If TYPE already exists, update it with the arguments.
+See `org-link-parameters' for documentation on the other parameters."
+  (org-link-add type :follow follow :export export) 
+  (message "Created %s link." type))
+
+(make-obsolete 'org-add-link-type 

Re: [O] links-9.0 v3

[Nicolas Goaziou]

John Kitchin  writes:

> I am not sure what you mean for this. Let me know if it isn't fixed in
> the attached patches. I thought I had squashed everything into a concise
> history.

No worries. Let's just apply the 21 patches.

> I think this code below (which should be in the patches) handles the
> option correctly.
>
> (defun org--open-file-link (path app)

It should, but I didn't see it in the previous patch, hence my remark.

> -(defvar org-store-link-functions nil
> -  "List of functions that are called to create and store a link.
>  Each function will be called in turn until one returns a non-nil
> -value.  Each function should check if it is responsible for creating
> -this link (for example by looking at the major mode).
> -If not, it must exit and return nil.
> -If yes, it should return a non-nil value after a calling
> -`org-store-link-props' with a list of properties and values.
> -Special properties are:
> +value.  Each function should check if it is responsible for
> +creating this link (for example by looking at the major mode).  If
> +not, it must exit and return nil.  If yes, it should return a
> +non-nil value after a calling `org-store-link-props' with a list
> +of properties and values. Special properties are:

Missing a space after the full stop above.

> +(defun org--open-file-link (path app)
> +  "Open PATH using APP.
> +
> +PATH is from a file link, and can have the following syntax:
> + [[file:~/code/main.c::255]]
> + [[file:~/xx.org::My Target]]
> + [[file:~/xx.org::*My Target]]
> + [[file:~/xx.org::#my-custom-id]]
> + [[file:~/xx.org::/regexp/]]
> +
> +APP is '(4) to open the PATH in Emacs, or 'system to use a system
> application."

Maybe something like:

  Called it with \\[universal-argument] to open PATH in Emacs. If ARG is
  `system', use a system application instead.


Regards,

Re: [O] links-9.0 v3

[John Kitchin]

Nicolas Goaziou writes:

> Hello,
>
> John Kitchin  writes:
>
>> Here are my current suggestions for the org-link 9.0.
>
> Thank you.

I think I fixed the points you made in the previous email.

>
>> Let me know what the best way to send these might be. It looks like it
>> might be 21 patches right now.
>
> AFAIU, many among them introduce code that no longer exists in the final
> draft. It would be nice to make them disappear, using interactive
> rebasing, as suggested earlier in this thread.

I am not sure what you mean for this. Let me know if it isn't fixed in
the attached patches. I thought I had squashed everything into a concise
history. 

>
> If that's not possible, just send them over here, I'll apply them.
>
> BTW sent patch doesn't seem to include an option handler. Am I missing
> something?

What do you mean by an option handler?

Do you mean for this file:path::option

I think this code below (which should be in the patches) handles the
option correctly.

(defun org--open-file-link (path app)
  "Open PATH using APP.

PATH is from a file link, and can have the following syntax:
 [[file:~/code/main.c::255]]
 [[file:~/xx.org::My Target]]
 [[file:~/xx.org::*My Target]]
 [[file:~/xx.org::#my-custom-id]]
 [[file:~/xx.org::/regexp/]]

APP is '(4) to open the PATH in Emacs, or 'system to use a system application."
  (let* ((fields (split-string path "::")) 
 (option (and (cdr fields)
  (mapconcat #'identity (cdr fields) ""
(apply #'org-open-file
   (car fields)
   app
   (cond ((not option) nil)
 ((string-match-p "\\`[0-9]+\\'" option)
  (list (string-to-number option)))
 (t (list nil
  (org-link-unescape option)))


>
> Regards,

>From ddc863fc16b8fe4b430e2f86b7ad96a0e90219cc Mon Sep 17 00:00:00 2001
From: John Kitchin 
Date: Thu, 7 Jul 2016 09:58:29 -0400
Subject: [PATCH 01/20] Create `org-link-parameters'

* lisp/org-element.el: Replace `org-link-types' variable with
  `org-link-types' function.

* lisp/org.el: Replace the `org-link-types' variable with
  `org-link-types' function. Create `org-link-get-parameter' and
  `org-link-set-parameters' functions. Remove `org-add-link-type'. Add
  `org-store-link-functions' function and remove
  `org-store-link-functions' variable. Add `org--open-file-link' for use
  as a :follow function for file type links.

* lisp/org.el: Set :follow functions for file links in `org-link-parameters.
Define `org-open-file-link' that opens a file link with an app.

* testing/lisp/test-ox.el: Remove usage of the `org-link-types'
  variable.

* lisp/org-compat.el: Move `org-add-link-type' and mark it as obsolete.

* lisp/ox.el: Change org-add-link-type comment in ox.el.
---
 lisp/org-compat.el  |  31 +
 lisp/org-element.el |   4 +-
 lisp/org.el | 167 
 lisp/ox.el  |   2 +-
 testing/lisp/test-ox.el |  16 ++---
 5 files changed, 155 insertions(+), 65 deletions(-)

diff --git a/lisp/org-compat.el b/lisp/org-compat.el
index 92fdb1c..a856ff7 100644
--- a/lisp/org-compat.el
+++ b/lisp/org-compat.el
@@ -374,6 +374,37 @@ Implements `define-error' for older emacsen."
 (put name 'error-conditions
 	 (copy-sequence (cons name (get 'error 'error-conditions))
 
+(defun org-add-link-type (type  follow export)
+  "Add a new TYPE link.
+FOLLOW and EXPORT are two functions.
+
+FOLLOW should take the link path as the single argument and do whatever
+is necessary to follow the link, for example find a file or display
+a mail message.
+
+EXPORT should format the link path for export to one of the export formats.
+It should be a function accepting three arguments:
+
+  paththe path of the link, the text after the prefix (like \"http:\")
+  descthe description of the link, if any
+  format  the export format, a symbol like `html' or `latex' or `ascii'.
+
+The function may use the FORMAT information to return different values
+depending on the format.  The return value will be put literally into
+the exported file.  If the return value is nil, this means Org should
+do what it normally does with links which do not have EXPORT defined.
+
+Org mode has a built-in default for exporting links.  If you are happy with
+this default, there is no need to define an export function for the link
+type.  For a simple example of an export function, see `org-bbdb.el'.
+
+If TYPE already exists, update it with the arguments.
+See `org-link-parameters' for documentation on the other parameters."
+  (org-link-add type :follow follow :export export) 
+  (message "Created %s link." type))
+
+(make-obsolete 'org-add-link-type "org-link-add." "Org 9.0")
+
 (provide 'org-compat)
 
 ;;; org-compat.el ends here
diff --git a/lisp/org-element.el b/lisp/org-element.el
index 269bc7d..9452641 100644
--- 

Re: [O] links-9.0 v3

[Nicolas Goaziou]

John Kitchin  writes:

> What do you think of this approach:
>
>  (defcustom org-link-parameters
> -  '(("file"  :complete 'org-file-complete-link)
> -("file+emacs" :follow (lambda (path) (org-open-file path '(4
> -("file+sys" :follow (lambda (path) (org-open-file path 'system)))
> +  '(("file"  :complete #'org-file-complete-link)
> +("file+emacs" :follow (lambda (path) (org-open-file-link path '(4
> +("file+sys" :follow (lambda (path) (org-open-file-link path 'system)))

It could work, but I suggest to rename it `org--open-file-link' or some
such, i.e., make it an internal function, because it could be confusing
with `org-open-link-from-string'.

>  ("http") ("https") ("ftp") ("mailto")
>  ("news") ("shell") ("elisp")
>  ("doi") ("message") ("help"))
> @@ -10732,6 +10732,30 @@ they must return nil.")
>  
>  (defvar org-link-search-inhibit-query nil) ;; dynamically scoped
>  (defvar clean-buffer-list-kill-buffer-names) ; Defined in midnight.el
> +
> +(defun org-open-file-link (path app)
> +  "Open PATH using APP.
> +
> +PATH is from a file link, and can have the following

missing "syntax"?

> + [[file:~/code/main.c::255]]
> + [[file:~/xx.org::My Target]]
> + [[file:~/xx.org::*My Target]]
> + [[file:~/xx.org::#my-custom-id]]
> + [[file:~/xx.org::/regexp/]]
> +
> +APP is '(4) to open the PATH in Emacs, or 'system to use a system 
> application."
> +  (let* ((fields (split-string path "::"))  
> +  (option (when (cdr fields)
> +(mapconcat 'identity (cdr fields) ""

(and (cdr field)
 (mapconcat #'identity (cdr fields) ""))
 
> +(apply #'org-open-file
> +(car fields)
> +app
> +(cond ((not option) nil)
> +  ((org-string-match-p "\\`[0-9]+\\'" option)

org-string-match-p -> string-match-p


Regards,

Re: [O] links-9.0 v3

[Nicolas Goaziou]

Hello,

John Kitchin  writes:

> Here are my current suggestions for the org-link 9.0.

Thank you.

> Let me know what the best way to send these might be. It looks like it
> might be 21 patches right now.

AFAIU, many among them introduce code that no longer exists in the final
draft. It would be nice to make them disappear, using interactive
rebasing, as suggested earlier in this thread.

If that's not possible, just send them over here, I'll apply them.

BTW sent patch doesn't seem to include an option handler. Am I missing 
something?

Regards,

-- 
Nicolas Goaziou

Re: [O] links-9.0 v3

[John Kitchin]

Here are my current suggestions for the org-link 9.0. Let me know what
the best way to send these might be. It looks like it might be 21
patches right now. Thanks,

17 files changed, 187 insertions(+), 87 deletions(-)
contrib/orgmanual.org |  27 +
doc/org.texi  |  27 +
etc/ORG-NEWS  |   2 +
lisp/org-bbdb.el  |   8 ++-
lisp/org-bibtex.el|   5 +-
lisp/org-docview.el   |   6 +-
lisp/org-element.el   |   4 +-
lisp/org-eshell.el|   5 +-
lisp/org-gnus.el  |   3 +-
lisp/org-id.el|   2 +-
lisp/org-info.el  |   8 ++-
lisp/org-irc.el   |   4 +-
lisp/org-mhe.el   |   3 +-
lisp/org-rmail.el |   3 +-
lisp/org-w3m.el   |   2 +-
lisp/org.el   | 163 ++
lisp/ox.el|   2 +-

modified   contrib/orgmanual.org
@@ -3300,12 +3300,16 @@ can define them in the file with
   ,#+LINK: googlehttp://www.google.com/search?q=%s
 #+end_src
 
-{{{noindent}}} In-buffer completion (see [[Completion]]) can be used after
-{{{samp([)}}} to complete link abbreviations.  You may also define a
-function ~org-PREFIX-complete-link~ that implements special (e.g.,
-completion) support for inserting such a link with {{{kbd(C-c C-l)}}}.
-Such a function should not accept any arguments, and return the full
-link with prefix.
+{{{noindent}}} In-buffer completion (see [[Completion]]) can be used
+after {{{samp([)}}} to complete link abbreviations.  You may also
+define a function that implements special (e.g., completion) support
+for inserting such a link with {{{kbd(C-c C-l)}}}.  Such a function
+should not accept any arguments, and return the full link with
+prefix.  You can set the link completion function like this:
+
+#+BEGIN_SRC emacs-lisp
+(org-link-set-parameter "type" :complete #'some-completion-function)
+#+END_SRC
 
 ** Search options
:PROPERTIES:
@@ -16998,10 +17002,9 @@ description when the link is later inserted into an 
Org buffer with
 {{{kbd(C-c C-l)}}}.
 
 When it makes sense for your new link type, you may also define a
-function ~org-PREFIX-complete-link~ that implements special (e.g.,
-completion) support for inserting such a link with {{{kbd(C-c C-l)}}}.
-Such a function should not accept any arguments, and return the full
-link with prefix.
+function that implements special (e.g., completion) support for
+inserting such a link with {{{kbd(C-c C-l)}}}.  Such a function should
+not accept any arguments, and return the full link with prefix.
 
 ** Context-sensitive commands
:PROPERTIES:
@@ -19181,8 +19184,8 @@ from the list of stored links.  To keep it in the list 
later use, use a
 triple {{{kbd(C-u)}}} prefix argument to {{{kbd(C-c C-l)}}}, or
 configure the option ~org-keep-stored-link-after-insertion~.
 
-[fn:37] This works by calling a special function
-~org-PREFIX-complete-link~.
+[fn:37] This works if a function has been defined in the :complete
+property of a link in ~org-link-parameters~.
 
 [fn:38] See the variable ~org-display-internal-link-with-indirect-buffer~.
 
modified   doc/org.texi
@@ -3711,11 +3711,11 @@ them with @key{up} and @key{down} (or @kbd{M-p/n}).
 valid link prefixes like @samp{http:} or @samp{ftp:}, including the prefixes
 defined through link abbreviations (@pxref{Link abbreviations}).  If you
 press @key{RET} after inserting only the @var{prefix}, Org will offer
-specific completion support for some link types@footnote{This works by
-calling a special function @code{org-PREFIX-complete-link}.}  For
-example, if you type @kbd{file @key{RET}}, file name completion (alternative
-access: @kbd{C-u C-c C-l}, see below) will be offered, and after @kbd{bbdb
-@key{RET}} you can complete contact names.
+specific completion support for some link types@footnote{This works if a
+completion function is defined in the :complete property of a link in
+@var{org-link-parameters}.}  For example, if you type @kbd{file @key{RET}},
+file name completion (alternative access: @kbd{C-u C-c C-l}, see below) will
+be offered, and after @kbd{bbdb @key{RET}} you can complete contact names.
 @orgkey C-u C-c C-l
 @cindex file name completion
 @cindex completion, of file names
@@ -3887,10 +3887,13 @@ can define them in the file with
 
 @noindent
 In-buffer completion (@pxref{Completion}) can be used after @samp{[} to
-complete link abbreviations.  You may also define a function
-@code{org-PREFIX-complete-link} that implements special (e.g., completion)
-support for inserting such a link with @kbd{C-c C-l}.  Such a function should
-not accept any arguments, and return the full link with prefix.
+complete link abbreviations.  You may also define a function that implements
+special (e.g., completion) support for inserting such a link with @kbd{C-c
+C-l}.  Such a function should not accept any arguments, and return the full
+link with prefix.  You can add a completion function to a link like this:
+
+@code{(org-link-set-parameters ``type'' :complete #'some-function)}
+
 
 @node Search 

Re: [O] links-9.0 v3

[John Kitchin]

What do you think of this approach:

 (defcustom org-link-parameters
-  '(("file"  :complete 'org-file-complete-link)
-("file+emacs" :follow (lambda (path) (org-open-file path '(4
-("file+sys" :follow (lambda (path) (org-open-file path 'system)))
+  '(("file"  :complete #'org-file-complete-link)
+("file+emacs" :follow (lambda (path) (org-open-file-link path '(4
+("file+sys" :follow (lambda (path) (org-open-file-link path 'system)))
 ("http") ("https") ("ftp") ("mailto")
 ("news") ("shell") ("elisp")
 ("doi") ("message") ("help"))
@@ -10732,6 +10732,30 @@ they must return nil.")
 
 (defvar org-link-search-inhibit-query nil) ;; dynamically scoped
 (defvar clean-buffer-list-kill-buffer-names) ; Defined in midnight.el
+
+(defun org-open-file-link (path app)
+  "Open PATH using APP.
+
+PATH is from a file link, and can have the following 
+ [[file:~/code/main.c::255]]
+ [[file:~/xx.org::My Target]]
+ [[file:~/xx.org::*My Target]]
+ [[file:~/xx.org::#my-custom-id]]
+ [[file:~/xx.org::/regexp/]]
+
+APP is '(4) to open the PATH in Emacs, or 'system to use a system application."
+  (let* ((fields (split-string path "::"))
+(option (when (cdr fields)
+  (mapconcat 'identity (cdr fields) ""
+(apply #'org-open-file
+  (car fields)
+  app
+  (cond ((not option) nil)
+((org-string-match-p "\\`[0-9]+\\'" option)
+ (list (string-to-number option)))
+(t (list nil
+ (org-link-unescape option)))
+
 (defun org-open-at-point ( arg reference-buffer)
   "Open link, timestamp, footnote or tags at point.


Nicolas Goaziou writes:

> John Kitchin  writes:
>
>> Here are the new revisions that implement the previous solution you
>> suggested and that incorporate the commit merges as far as I can see.
>
> Thank you.
>
>> +(defcustom org-link-parameters
>> +  '(("file"  :complete 'org-file-complete-link)
>
> #'org-file-complete-link
>
>> +("file+emacs" :follow (lambda (path) (org-open-file path '(4
>> +("file+sys" :follow (lambda (path) (org-open-file path 'system)))
>
> This will ignore so-called "option" part, e.g.
>
>   [[file:test.org::3]]
>
> :follow functions need to extract it somehow.
>
> Once this issue is resolved, I think the whole change-set can be pushed
> to master, AFAIC.


-- 
Professor John Kitchin
Doherty Hall A207F
Department of Chemical Engineering
Carnegie Mellon University
Pittsburgh, PA 15213
412-268-7803
@johnkitchin
http://kitchingroup.cheme.cmu.edu

Re: [O] links-9.0 v3

[John Kitchin]

K

On Friday, July 8, 2016, Nicolas Goaziou  wrote:

> John Kitchin > writes:
>
> > Here are the new revisions that implement the previous solution you
> > suggested and that incorporate the commit merges as far as I can see.
>
> Thank you.
>
> > +(defcustom org-link-parameters
> > +  '(("file"  :complete 'org-file-complete-link)
>
> #'org-file-complete-link
>
> > +("file+emacs" :follow (lambda (path) (org-open-file path '(4
> > +("file+sys" :follow (lambda (path) (org-open-file path 'system)))
>
> This will ignore so-called "option" part, e.g.
>
>   [[file:test.org::3]]
>
> :follow functions need to extract it somehow.


Good catch. I can probably do that tomorrow. Thanks!

>
> Once this issue is resolved, I think the whole change-set can be pushed
> to master, AFAIC.
>


-- 
John

---
Professor John Kitchin
Doherty Hall A207F
Department of Chemical Engineering
Carnegie Mellon University
Pittsburgh, PA 15213
412-268-7803
@johnkitchin
http://kitchingroup.cheme.cmu.edu

Re: [O] links-9.0 v3

[Nicolas Goaziou]

John Kitchin  writes:

> Here are the new revisions that implement the previous solution you
> suggested and that incorporate the commit merges as far as I can see.

Thank you.

> +(defcustom org-link-parameters
> +  '(("file"  :complete 'org-file-complete-link)

#'org-file-complete-link

> +("file+emacs" :follow (lambda (path) (org-open-file path '(4
> +("file+sys" :follow (lambda (path) (org-open-file path 'system)))

This will ignore so-called "option" part, e.g.

  [[file:test.org::3]]

:follow functions need to extract it somehow.

Once this issue is resolved, I think the whole change-set can be pushed
to master, AFAIC.

Re: [O] links-9.0 v3

[Nicolas Goaziou]

Hello,

John Kitchin  writes:

> I don't understand what you mean here. The contents of org-link
> protocols (in master) looks a lot like a list of (link-type :follow
> :export), e.g.

You're right. Keys in `org-link-protocols' are types.

>>   (nth 1 (assoc app org-link-protocols))
>
> I see that these are not the same, since type != app.

Per the above, this snippet from `org-open-at-point' is suspicious.

> I was referring to the optional parameter, although I reconsider it
> here.  I don't understand how does the "application" get to the
> follow functions of links other than file+sys and file+emacs. It seems
> like we would need to allow type+application:path as a link syntax and
> extend the link-parser to get the application. Right now it looks like
> the parser only adds application properties to file type links.

file+sys and file+emacs predate the parser. Since the manual doesn't
seem to generalize them, parser support for them is rather minimalist.

I really hope this syntax is not going to be extended, because it
doesn't sound right to define the application opening a link at the
syntax level.

> I don't mind this (it makes links more flexible after all ;) OTOH, we
> would have to "register" each type+application for the link regexp, and
> then each type can have its own follow function, so it seems unnecessary
> to me.

I agree. As long as we need the regexp (because of plain links,
actually), my suggestion is a false good idea.

> My understanding of your statement of the problem is that the
> link-parser recognizes file:path, file+sys:path, and file+emacs:path as
> links of type "file", with different "application" properties. In the
> implementation of org-open-at-point on master, there is a cond branch
> for the "file" type link, and inside that the application is checked.
> Hence, without your suggestion at the end, there is not a way to access
> the :follow function of file+sys or file+emacs.
>
> To me this seems to be an unnecessary distinction from a link point of
> view since those three file links could just be defined as regular links
> with different follow/export functions. OTOH, perhaps there are other
> places in org-mode that rely on being able to tell when a link is a
> file, even if they are labeled file+sys or file+emacs that I am not
> aware of?

Any use not relying on :follow does not care above "+sys" or "+emacs".
E.g., during export, file+sys and file+emacs are treated the same.

> If I compare this to what exists in org-ref, for example, there
> are close to 40 different types of citations one can use, but they are
> all fundamentally "cite" types. They all share a common follow action,
> but have different export functions. When defined as separate links, I
> use them like cite:key citenum:key, citet:key, autocite:key, etc...
>
> Even here while I can see some utility for an application, e.g. perhaps
> to open the key in zotero, or mendeley or bibtex, I would normally
> associate that action with the :follow function. Am I missing
> something?

I think file+app was designed to override :follow function, so
associating the action with the :follow function wouldn't help.

> I only mentioned it because it seems to be in there in master via this line:
>
> (regexp-opt (cons "coderef" org-link-types)
>
> but it looks like it is in there in a different sort of way. It doesn't
> seem important here.

The line above creates a regexp matching types, as stored by the parser,
as returned by (org-element-property :type link). This can be "coderef".

OTOH (regexp-opt org-link-types) is meant to match links in an Org
buffer, where there is no "coderef".

Regards,

-- 
Nicolas Goaziou

Re: [O] links-9.0 v3

[John Kitchin]

Here are the new revisions that implement the previous solution you
suggested and that incorporate the commit merges as far as I can see.
WDYT?


commit 290213ef3eee86175d5a6b15c7b6173afd0c1616
Author: John Kitchin 
Date:   Tue Jul 5 10:38:42 2016 -0400

Update the contrib manual

diff --git a/contrib/orgmanual.org b/contrib/orgmanual.org
index e48ae97..07d9e8d 100644
--- a/contrib/orgmanual.org
+++ b/contrib/orgmanual.org
@@ -3300,12 +3300,16 @@ can define them in the file with
   ,#+LINK: googlehttp://www.google.com/search?q=%s
 #+end_src
 
-{{{noindent}}} In-buffer completion (see [[Completion]]) can be used after
-{{{samp([)}}} to complete link abbreviations.  You may also define a
-function ~org-PREFIX-complete-link~ that implements special (e.g.,
-completion) support for inserting such a link with {{{kbd(C-c C-l)}}}.
-Such a function should not accept any arguments, and return the full
-link with prefix.
+{{{noindent}}} In-buffer completion (see [[Completion]]) can be used
+after {{{samp([)}}} to complete link abbreviations.  You may also
+define a function that implements special (e.g., completion) support
+for inserting such a link with {{{kbd(C-c C-l)}}}.  Such a function
+should not accept any arguments, and return the full link with
+prefix.  You can set the link completion function like this:
+
+#+BEGIN_SRC emacs-lisp
+(org-link-set-parameter "type" :complete #'some-completion-function)
+#+END_SRC
 
 ** Search options
:PROPERTIES:
@@ -16998,10 +17002,9 @@ description when the link is later inserted into an 
Org buffer with
 {{{kbd(C-c C-l)}}}.
 
 When it makes sense for your new link type, you may also define a
-function ~org-PREFIX-complete-link~ that implements special (e.g.,
-completion) support for inserting such a link with {{{kbd(C-c C-l)}}}.
-Such a function should not accept any arguments, and return the full
-link with prefix.
+function that implements special (e.g., completion) support for
+inserting such a link with {{{kbd(C-c C-l)}}}.  Such a function should
+not accept any arguments, and return the full link with prefix.
 
 ** Context-sensitive commands
:PROPERTIES:
@@ -19181,8 +19184,8 @@ from the list of stored links.  To keep it in the list 
later use, use a
 triple {{{kbd(C-u)}}} prefix argument to {{{kbd(C-c C-l)}}}, or
 configure the option ~org-keep-stored-link-after-insertion~.
 
-[fn:37] This works by calling a special function
-~org-PREFIX-complete-link~.
+[fn:37] This works if a function has been defined in the :complete
+property of a link in ~org-link-parameters~.
 
 [fn:38] See the variable ~org-display-internal-link-with-indirect-buffer~.
 

commit 8e51c2ff4b37524dcc489d58a6769fd8430c5593
Author: John Kitchin 
Date:   Tue Jul 5 10:31:30 2016 -0400

Update NEWS with link announcement

diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index 9909910..6ff7442 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -353,6 +353,8 @@ first footnote.
 *** The ~org-block~ face is inherited by ~src-blocks~
 This works also when =org-src-fontify-natively= is non-nil.  It is also
 possible to specify per-languages faces.  See the manual for details.
+*** Links are now customizable
+Links can now have custom colors, tooltips, keymaps, display behavior, etc... 
Links are now centralized in ~org-link-parameters~.
 ** New functions
 *** ~org-next-line-empty-p~
 It replaces the deprecated ~next~ argument to ~org-previous-line-empty-p~.

commit 246539109bac10f8de227adbc491bdeb94e80ba0
Author: John Kitchin 
Date:   Tue Jul 5 10:29:07 2016 -0400

Update the texinfo for link parameters documentation

diff --git a/doc/org.texi b/doc/org.texi
index e92788f..f962a58 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -3711,11 +3711,11 @@ them with @key{up} and @key{down} (or @kbd{M-p/n}).
 valid link prefixes like @samp{http:} or @samp{ftp:}, including the prefixes
 defined through link abbreviations (@pxref{Link abbreviations}).  If you
 press @key{RET} after inserting only the @var{prefix}, Org will offer
-specific completion support for some link types@footnote{This works by
-calling a special function @code{org-PREFIX-complete-link}.}  For
-example, if you type @kbd{file @key{RET}}, file name completion (alternative
-access: @kbd{C-u C-c C-l}, see below) will be offered, and after @kbd{bbdb
-@key{RET}} you can complete contact names.
+specific completion support for some link types@footnote{This works if a
+completion function is defined in the :complete property of a link in
+@var{org-link-parameters}.}  For example, if you type @kbd{file @key{RET}},
+file name completion (alternative access: @kbd{C-u C-c C-l}, see below) will
+be offered, and after @kbd{bbdb @key{RET}} you can complete contact names.
 @orgkey C-u C-c C-l
 @cindex file name completion
 @cindex completion, of file names
@@ -3887,10 +3887,13 @@ can define them in the file with
 
 @noindent
 In-buffer completion (@pxref{Completion}) can be used 

Re: [O] links-9.0 v3

[John Kitchin]

Let me preface my reply that I think your last suggestion:

>   (org-link-get-parameter (if app (concat type "+" app) type) :follow)

Is the thing to do for this set of changes for now. I think it would
wrap up this set of changes. I will send a new set of diffs that
implement this shortly after this mail.

I have some other responses below because there are some things I don't
totally understand yet.

Nicolas Goaziou writes:

> John Kitchin  writes:
>
>>> Here is the gotcha. `type' is "file", not "file+sys" or "file+emacs",
>>> so, when checking `dedicated-function' first, we cannot tell the
>>> difference between "file+sys" and "file+emacs".
>>
>> I don't follow this. Why can't these be three types?
>
> The type is "file". "sys" or "emacs" are indications about how to follow
> them. "docview" is also an indication, but it really points to a "file".
>
>> They define 3 different follow actions right? Those are basically
>> equal to pressing RET, C-u RET and C-u C-u RET on a link. We could
>> just define three :follow functions, and one :export function for
>> them.
>
> It doesn't mean they cannot have an entry in `org-link-parameters'.
> Actually they should.
>
> However `org-link-protocols' keys are applications, not types. So

I don't understand what you mean here. The contents of org-link
protocols (in master) looks a lot like a list of (link-type :follow
:export), e.g.

#+BEGIN_SRC emacs-lisp :results code
(assoc "bbdb" org-link-protocols)
#+END_SRC

#+RESULTS:
#+BEGIN_SRC emacs-lisp
("bbdb" org-bbdb-open org-bbdb-export)
#+END_SRC

There doesn't seem to be a "sys" or "emacs" defined in
org-link-protocols in master. So there is no dedicated function being
called as far as I can tell.

#+BEGIN_SRC emacs-lisp :results code
(assoc "sys" org-link-protocols)
#+END_SRC

#+RESULTS:
#+BEGIN_SRC emacs-lisp
nil
#+END_SRC

>  (org-link-get-parameter type :follow)
>
> is not a drop-in replacement for
>
>   (nth 1 (assoc app org-link-protocols))

I see that these are not the same, since type != app.

With app, this would try to look up (org-link-get-parameter "sys"
:follow), which currently would return nil. That seems consistent with
what is currently in master too. I concede that if a "sys" link was
defined it would do something, but that isn't currently the case AFAICT.
Your solution solves this nicely though.

>> With the patches I sent, the three types actually work as they used to,
>> e.g. file:some.pptx opens the powerpoint file in emacs (not convenient
>> ;), file+sys:some.pptx opens it in powerpoint. This seems to be because
>> org-element-context (via org-element-link-parser) sees file+sys and
>> file+emacs as a file type.
>
> Which is correct.
>
>> Overall, this is an inconsistency to me. On one hand, we need file+sys
>> and file+emacs in org-link-parameters so that they are built into the
>> link regexps (or they would have to be hard-coded in the function that
>> makes the regexp.
>
> [...]
>
>> On the other hand, the org-open-at-point
>> function bypasses the link properties, so it is not possible to change
>> the :follow function for file+sys and file+emacs.
>
> Of course it is possible. I suggested two solutions already.
>
>>> One solution is to swap the logic order. First, if app is non-nil, we
>>> use it. If it isn't, we look after `dedicated-function'.
>>>
>>> Another solution is to add an optional parameter to the signature of
>>> the :follow function, which would be the "app" (e.g. "emacs", "sys",
>>> "docview"...) to use. I tend to think this solution is slightly better,
>>> since it doesn't require to hard-code logic in `org-open-at-point'.
>>>
>>> WDYT?
>>
>> I am not crazy about this solution,
>
> Which one? I suggested two of them.
I was referring to the optional parameter, although I reconsider it
here.  I don't understand how does the "application" get to the
follow functions of links other than file+sys and file+emacs. It seems
like we would need to allow type+application:path as a link syntax and
extend the link-parser to get the application. Right now it looks like
the parser only adds application properties to file type links.

>
>> since it only applies to one type of link,
>
> Does it? Every type can benefit from this change, i.e. instead of
> calling follow function with a single argument, it is called with two,
> the second one being the application (e.g., "sys", "emacs"...) or nil.

I don't mind this (it makes links more flexible after all ;) OTOH, we
would have to "register" each type+application for the link regexp, and
then each type can have its own follow function, so it seems unnecessary
to me.

I would leave this on the table for future consideration, but consider
it outside the current scope of this set of changes. I think with your
final suggestion it isn't necessary to consider this now. 

>
>> and I can't see how to use it for other follow functions. It would be
>> better IMO to define :follow functions maybe like this:
>>
>> "file" :follow 

Re: [O] links-9.0 v3

[Nicolas Goaziou]

John Kitchin  writes:

>> Here is the gotcha. `type' is "file", not "file+sys" or "file+emacs",
>> so, when checking `dedicated-function' first, we cannot tell the
>> difference between "file+sys" and "file+emacs".
>
> I don't follow this. Why can't these be three types?

The type is "file". "sys" or "emacs" are indications about how to follow
them. "docview" is also an indication, but it really points to a "file".

> They define 3 different follow actions right? Those are basically
> equal to pressing RET, C-u RET and C-u C-u RET on a link. We could
> just define three :follow functions, and one :export function for
> them.

It doesn't mean they cannot have an entry in `org-link-parameters'.
Actually they should.

However `org-link-protocols' keys are applications, not types. So

  (org-link-get-parameter type :follow)

is not a drop-in replacement for

  (nth 1 (assoc app org-link-protocols))

> With the patches I sent, the three types actually work as they used to,
> e.g. file:some.pptx opens the powerpoint file in emacs (not convenient
> ;), file+sys:some.pptx opens it in powerpoint. This seems to be because
> org-element-context (via org-element-link-parser) sees file+sys and
> file+emacs as a file type.

Which is correct.

> Overall, this is an inconsistency to me. On one hand, we need file+sys
> and file+emacs in org-link-parameters so that they are built into the
> link regexps (or they would have to be hard-coded in the function that
> makes the regexp.

[...]

> On the other hand, the org-open-at-point
> function bypasses the link properties, so it is not possible to change
> the :follow function for file+sys and file+emacs.

Of course it is possible. I suggested two solutions already.

>> One solution is to swap the logic order. First, if app is non-nil, we
>> use it. If it isn't, we look after `dedicated-function'.
>>
>> Another solution is to add an optional parameter to the signature of
>> the :follow function, which would be the "app" (e.g. "emacs", "sys",
>> "docview"...) to use. I tend to think this solution is slightly better,
>> since it doesn't require to hard-code logic in `org-open-at-point'.
>>
>> WDYT?
>
> I am not crazy about this solution,

Which one? I suggested two of them.

> since it only applies to one type of link,

Does it? Every type can benefit from this change, i.e. instead of
calling follow function with a single argument, it is called with two,
the second one being the application (e.g., "sys", "emacs"...) or nil.

> and I can't see how to use it for other follow functions. It would be
> better IMO to define :follow functions maybe like this:
>
> "file" :follow #'org-open-at-point
> "file+sys" :follow (lambda (_) (org-open-at-point '(4)))
> "file+emacs" :follow (lambda (_) (org-open-at-point '(16)))
>
> and make them be honored in org-open-at-point. Then we could eliminate
> the logic code in org-open-at-point.

You may be misunderstanding the problem. 

The issue is that `org-open-at-point', at the moment, cannot call
the :follow function for "file+emacs" or "file+sys" since the common
type is "file", even if `org-link-parameters' distinguish them. IOW the
first :follow function would always be called.

Also, `org-open-at-point' shouldn't be part of a follow function, since
`org-open-at-point' calls follow functions. It can call `org-open-file',
tho, as currently done in `org-open-at-point'.

Actually, I can think of a third solution, which may well follow the
path of least resistance. Instead of calling

  (org-link-get-parameter type :follow)

we would call

  (org-link-get-parameter (if app (concat type "+" app) type) :follow)

and get the appropriate follow function. This solution is local to
`org-open-at-point', but I don't think other places need :follow
function.

>>>(let ((data (assoc type org-link-parameters)))
>>> -(if data
>>> -   (cl-loop for (key val) on parameters by #'cddr
>>> -do
>>> -(setf (cl-getf (cdr data) key)
>>> -  val))
>>> +(if data (setcdr data (org-combine-plists (cdr data) parameters))
>>>(push (cons type parameters) org-link-parameters)
>>>(org-make-link-regexps)
>>>(org-element-update-syntax
>>
>> This change can be merged with `org-link-set-parameters' definition.
>
> I am not sure how to do that. It is like a hunk in one commit that I
> want to move to another commit.

I would edit the commit defining `org-link-set-parameters' and install
that change there. Then, upon rebasing, I would make sure this change is
preserved.

>>> +(defcustom org-link-parameters
>>> +  '(("http") ("https") ("ftp") ("mailto")
>>> +("file" :complete 'org-file-complete-link)
>>> +("file+emacs") ("file+sys")
>>> +("news") ("shell") ("elisp")
>>> +("doi") ("message") ("help"))
>>
>> See above about "file+emacs" and "file+sys", which are not valid types.
>
> Those either need to be here for link regexps, or hard-coded somewhere
> else though.

Re: [O] links-9.0 v3

[John Kitchin]

>
> That's great. I realized there's one gotcha left.
>
>>(let* ((option (org-element-property :search-option link))
>>   (app (org-element-property :application link))
>>   (dedicated-function
>> -  (nth 1 (assoc app org-link-protocols
>> +  (org-link-get-parameter type :follow)))
>>  (if dedicated-function
>
> Here is the gotcha. `type' is "file", not "file+sys" or "file+emacs",
> so, when checking `dedicated-function' first, we cannot tell the
> difference between "file+sys" and "file+emacs".

I don't follow this. Why can't these be three types? They
define 3 different follow actions right? Those are basically equal to
pressing RET, C-u RET and C-u C-u RET on a link. We could just define
three :follow functions, and one :export function for them.

With the patches I sent, the three types actually work as they used to,
e.g. file:some.pptx opens the powerpoint file in emacs (not convenient
;), file+sys:some.pptx opens it in powerpoint. This seems to be because
org-element-context (via org-element-link-parser) sees file+sys and
file+emacs as a file type.

Overall, this is an inconsistency to me. On one hand, we need file+sys
and file+emacs in org-link-parameters so that they are built into the
link regexps (or they would have to be hard-coded in the function that
makes the regexp. E.g. (cons "coderef" (org-link-types)) is already done
that way for some reason). On the other hand, the org-open-at-point
function bypasses the link properties, so it is not possible to change
the :follow function for file+sys and file+emacs.

> One solution is to swap the logic order. First, if app is non-nil, we
> use it. If it isn't, we look after `dedicated-function'.
>
> Another solution is to add an optional parameter to the signature of
> the :follow function, which would be the "app" (e.g. "emacs", "sys",
> "docview"...) to use. I tend to think this solution is slightly better,
> since it doesn't require to hard-code logic in `org-open-at-point'.
>
> WDYT?

I am not crazy about this solution, since it only applies to one type of
link, and I can't see how to use it for other follow functions. It would be
better IMO to define :follow functions maybe like this:

"file" :follow #'org-open-at-point
"file+sys" :follow (lambda (_) (org-open-at-point '(4)))
"file+emacs" :follow (lambda (_) (org-open-at-point '(16)))

and make them be honored in org-open-at-point. Then we could eliminate
the logic code in org-open-at-point.

>
>>(let ((data (assoc type org-link-parameters)))
>> -(if data
>> -(cl-loop for (key val) on parameters by #'cddr
>> - do
>> - (setf (cl-getf (cdr data) key)
>> -   val))
>> +(if data (setcdr data (org-combine-plists (cdr data) parameters))
>>(push (cons type parameters) org-link-parameters)
>>(org-make-link-regexps)
>>(org-element-update-syntax
>
> This change can be merged with `org-link-set-parameters' definition.

I am not sure how to do that. It is like a hunk in one commit that I
want to move to another commit.

>
>> +(defcustom org-link-parameters
>> +  '(("http") ("https") ("ftp") ("mailto")
>> +("file" :complete 'org-file-complete-link)
>> +("file+emacs") ("file+sys")
>> +("news") ("shell") ("elisp")
>> +("doi") ("message") ("help"))
>
> See above about "file+emacs" and "file+sys", which are not valid types.

Those either need to be here for link regexps, or hard-coded somewhere
else though. Speaking of which, should coderef be a link type, so it can
be removed as a hard-coded string that I referenced above?

> Regards,


-- 
Professor John Kitchin
Doherty Hall A207F
Department of Chemical Engineering
Carnegie Mellon University
Pittsburgh, PA 15213
412-268-7803
@johnkitchin
http://kitchingroup.cheme.cmu.edu

Re: [O] links-9.0 v3

[Nicolas Goaziou]

Hello,

John Kitchin  writes:

> I think I have addressed these. Revised commits appended and at 
> https://github.com/jkitchin/org-mode/tree/link-9.0-v3.
>
> The new org-link-set-parameters function you suggested works fine as far
> as I can tell. WDYT?

That's great. I realized there's one gotcha left.

> (let* ((option (org-element-property :search-option link))
>(app (org-element-property :application link))
>(dedicated-function
> -   (nth 1 (assoc app org-link-protocols
> +   (org-link-get-parameter type :follow)))
>   (if dedicated-function

Here is the gotcha. `type' is "file", not "file+sys" or "file+emacs",
so, when checking `dedicated-function' first, we cannot tell the
difference between "file+sys" and "file+emacs".

One solution is to swap the logic order. First, if app is non-nil, we
use it. If it isn't, we look after `dedicated-function'.

Another solution is to add an optional parameter to the signature of
the :follow function, which would be the "app" (e.g. "emacs", "sys",
"docview"...) to use. I tend to think this solution is slightly better,
since it doesn't require to hard-code logic in `org-open-at-point'.

WDYT?

>(let ((data (assoc type org-link-parameters)))
> -(if data
> - (cl-loop for (key val) on parameters by #'cddr
> -  do
> -  (setf (cl-getf (cdr data) key)
> -val))
> +(if data (setcdr data (org-combine-plists (cdr data) parameters))
>(push (cons type parameters) org-link-parameters)
>(org-make-link-regexps)
>(org-element-update-syntax

This change can be merged with `org-link-set-parameters' definition.

> +(defcustom org-link-parameters
> +  '(("http") ("https") ("ftp") ("mailto")
> +("file" :complete 'org-file-complete-link)
> +("file+emacs") ("file+sys")
> +("news") ("shell") ("elisp")
> +("doi") ("message") ("help"))

See above about "file+emacs" and "file+sys", which are not valid types.

Regards,

-- 
Nicolas Goaziou

Re: [O] links-9.0 v3

[John Kitchin]

I think I have addressed these. Revised commits appended and at 
https://github.com/jkitchin/org-mode/tree/link-9.0-v3.

The new org-link-set-parameters function you suggested works fine as far
as I can tell. WDYT?

commit f8bb180150514b92535506601c747001da305610
Author: John Kitchin 
Date:   Tue Jul 5 10:38:42 2016 -0400

Update the contrib manual

diff --git a/contrib/orgmanual.org b/contrib/orgmanual.org
index e48ae97..07d9e8d 100644
--- a/contrib/orgmanual.org
+++ b/contrib/orgmanual.org
@@ -3300,12 +3300,16 @@ can define them in the file with
   ,#+LINK: googlehttp://www.google.com/search?q=%s
 #+end_src
 
-{{{noindent}}} In-buffer completion (see [[Completion]]) can be used after
-{{{samp([)}}} to complete link abbreviations.  You may also define a
-function ~org-PREFIX-complete-link~ that implements special (e.g.,
-completion) support for inserting such a link with {{{kbd(C-c C-l)}}}.
-Such a function should not accept any arguments, and return the full
-link with prefix.
+{{{noindent}}} In-buffer completion (see [[Completion]]) can be used
+after {{{samp([)}}} to complete link abbreviations.  You may also
+define a function that implements special (e.g., completion) support
+for inserting such a link with {{{kbd(C-c C-l)}}}.  Such a function
+should not accept any arguments, and return the full link with
+prefix.  You can set the link completion function like this:
+
+#+BEGIN_SRC emacs-lisp
+(org-link-set-parameter "type" :complete #'some-completion-function)
+#+END_SRC
 
 ** Search options
:PROPERTIES:
@@ -16998,10 +17002,9 @@ description when the link is later inserted into an 
Org buffer with
 {{{kbd(C-c C-l)}}}.
 
 When it makes sense for your new link type, you may also define a
-function ~org-PREFIX-complete-link~ that implements special (e.g.,
-completion) support for inserting such a link with {{{kbd(C-c C-l)}}}.
-Such a function should not accept any arguments, and return the full
-link with prefix.
+function that implements special (e.g., completion) support for
+inserting such a link with {{{kbd(C-c C-l)}}}.  Such a function should
+not accept any arguments, and return the full link with prefix.
 
 ** Context-sensitive commands
:PROPERTIES:
@@ -19181,8 +19184,8 @@ from the list of stored links.  To keep it in the list 
later use, use a
 triple {{{kbd(C-u)}}} prefix argument to {{{kbd(C-c C-l)}}}, or
 configure the option ~org-keep-stored-link-after-insertion~.
 
-[fn:37] This works by calling a special function
-~org-PREFIX-complete-link~.
+[fn:37] This works if a function has been defined in the :complete
+property of a link in ~org-link-parameters~.
 
 [fn:38] See the variable ~org-display-internal-link-with-indirect-buffer~.
 

commit d5db3a80b3e6eab98935a329d8633a85f398ee3a
Author: John Kitchin 
Date:   Tue Jul 5 10:31:30 2016 -0400

Update NEWS with link announcement

diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index 9909910..6ff7442 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -353,6 +353,8 @@ first footnote.
 *** The ~org-block~ face is inherited by ~src-blocks~
 This works also when =org-src-fontify-natively= is non-nil.  It is also
 possible to specify per-languages faces.  See the manual for details.
+*** Links are now customizable
+Links can now have custom colors, tooltips, keymaps, display behavior, etc... 
Links are now centralized in ~org-link-parameters~.
 ** New functions
 *** ~org-next-line-empty-p~
 It replaces the deprecated ~next~ argument to ~org-previous-line-empty-p~.

commit 74d6817ea942b9b20b9a15f47d259ef71ddb83a3
Author: John Kitchin 
Date:   Tue Jul 5 10:29:07 2016 -0400

Update the texinfo for link parameters documentation

diff --git a/doc/org.texi b/doc/org.texi
index e92788f..f962a58 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -3711,11 +3711,11 @@ them with @key{up} and @key{down} (or @kbd{M-p/n}).
 valid link prefixes like @samp{http:} or @samp{ftp:}, including the prefixes
 defined through link abbreviations (@pxref{Link abbreviations}).  If you
 press @key{RET} after inserting only the @var{prefix}, Org will offer
-specific completion support for some link types@footnote{This works by
-calling a special function @code{org-PREFIX-complete-link}.}  For
-example, if you type @kbd{file @key{RET}}, file name completion (alternative
-access: @kbd{C-u C-c C-l}, see below) will be offered, and after @kbd{bbdb
-@key{RET}} you can complete contact names.
+specific completion support for some link types@footnote{This works if a
+completion function is defined in the :complete property of a link in
+@var{org-link-parameters}.}  For example, if you type @kbd{file @key{RET}},
+file name completion (alternative access: @kbd{C-u C-c C-l}, see below) will
+be offered, and after @kbd{bbdb @key{RET}} you can complete contact names.
 @orgkey C-u C-c C-l
 @cindex file name completion
 @cindex completion, of file names
@@ -3887,10 +3887,13 @@ can define them in the file 

Re: [O] links-9.0 v3

[John Kitchin]

Thanks. I responded to some below. I didn't respond to all of them. I
will revise the commits accordingly and send a new version.

Nicolas Goaziou writes:

> Hello,
>
> John Kitchin  writes:
>
>> Your version doesn't let you add properties to links with no
>> existing properties, e.g. ("http")
>
> There was a typo (spurious `cdr'), the correct version is
>
>   (defun org-link-set-parameters (type  parameters)
> "Set link TYPE properties to PARAMETERS.
>   PARAMETERS should be :key val pairs."
> (let ((data (assoc type org-link-parameters)))
>   (if data (setcdr data (org-combine-plists (cdr data) parameters))
> (push (cons type parameters) org-link-parameters)
> (org-make-link-regexps)
> (org-element-update-syntax
>
>> and it also didn't work as expected to set properties to nil.

I will give this a try.
>
> Not sure to understand what you mean here. Could you give an example?

If I ran the previous function a few times like this

(org-link-set-parameters "http" :follow nil)

I would get
("http" :follow :follow nil nil nil...)

probably because of the bug. I will let you know if it works.

>> I think I have squashed everything together that makes sense. Let me
>> know if you have further thoughts.
>
> OK. Some comments follow.
>
>> +{{{noindent}}} In-buffer completion (see [[Completion]]) can be used
>> +after {{{samp([)}}} to complete link abbreviations.  You may also
>> +define a function that implements special (e.g., completion) support
>> +for inserting such a link with {{{kbd(C-c C-l)}}}.  Such a function
>> +should not accept any arguments, and return the full link with
>> +prefix. You can set the link completion function like this:
>
> Mind the spaces after sentences.
I will fix these.

>
> In any case, updating contrib manual is not top priority, since many
> section needs to be updated anyway.
>
>> +[fn:37] This works if a function has been defined in the :complete
>> +property of a link in org-link-parameters.
>
> ~org-link-parameters~
>
>> -(org-add-link-type "id" 'org-id-open)
>> +(org-link-set-parameters "id" :follow 'org-id-open)
>
> Nitpick: #'org-id-open
>
>> -(add-hook 'org-store-link-functions 'org-w3m-store-link)
>> +(org-link-set-parameters "w3m" :store 'org-w3m-store-link)
>
> #'org-w3m-store-link
>
> You get the idea, I will not comment the other occurrences.

Just to make sure I get it, all functions should be sharp quoted like this?

>
>> +   (type (save-match-data
>> +   (if (string-match org-plain-link-re hl)
>> +   (match-string-no-properties 1 hl)
>> + nil)))
>
> Nitpick
>
>   (save-match-data
> (and (string-match org-plain-link-re hl)
>  (match-string-no-properties 1 hl)))
>
>> +   (path (save-match-data
>> +   (if (string-match org-plain-link-re hl)
>> +   (match-string-no-properties 2 hl)
>> + nil)))
>
> Ditto.

ok

>
>> -   ((assoc type org-link-parameters)
>> +   ((and (assoc type org-link-parameters)
>> + (functionp (org-link-get-parameter type :follow)))
>
> I think (functionp ...) is sufficient, no need for the `and' and 
> (assoc type org-link-parameters), which `org-link-get-parameters'
> already takes case of.  So
>
>   ((functionp (org-link-get-parameters type :follow)
>...)
>
>> * lisp/org.el: Replace the variable `org-store-link-functions' with a
>>   function by the same name.
>
> You need to add the name of the function being modified.
>
>> Update org-add-link-type
>> 
>> * lisp/org.el org-add-link-type: deprecated and now calls
>>   `org-link-add'.
>> 
>> Create a new `org-link-add' function for making links.
>
> You probably mean `org-link-set-parameters', since `org-link-add' would
> be but a lesser version of the former.
>
>> +  (org-link-add type :follow follow :export export)
>
> See above.
>
>> +(defun org-store-link-functions ()
>> +  "Returns a list of functions that are called to create and store a link.
>> +The functions in the variable `org-store-link-functions' come
>> +first. These may be user-defined for different contexts. Then
>> +comes the functions defined in the :store property of
>> +org-link-parameters.
>> +
>> +Each function will be called in turn until one returns a non-nil
>> +value. Each function should check if it is responsible for
>> +creating this link (for example by looking at the major mode). If
>> +not, it must exit and return nil. If yes, it should return a
>> +non-nil value after a calling `org-store-link-props' with a list
>> +of properties and values. Special properties are:
>
> Mind the spaces between sentences.
>
> I don't understand why we need to both preserve
> `org-store-link-functions' and use :store property. Wouldn't one
> location be enough?
>

It probably isn't necessary. I will take it out.

>> +:type The link prefix, like \"http\".  This must be given.
>> +:link  

Re: [O] links-9.0 v3

[Nicolas Goaziou]

Hello,

John Kitchin  writes:

> Your version doesn't let you add properties to links with no
> existing properties, e.g. ("http")

There was a typo (spurious `cdr'), the correct version is

  (defun org-link-set-parameters (type  parameters)
"Set link TYPE properties to PARAMETERS.
  PARAMETERS should be :key val pairs."
(let ((data (assoc type org-link-parameters)))
  (if data (setcdr data (org-combine-plists (cdr data) parameters))
(push (cons type parameters) org-link-parameters)
(org-make-link-regexps)
(org-element-update-syntax

> and it also didn't work as expected to set properties to nil.

Not sure to understand what you mean here. Could you give an example?

> I think I have squashed everything together that makes sense. Let me
> know if you have further thoughts.

OK. Some comments follow.

> +{{{noindent}}} In-buffer completion (see [[Completion]]) can be used
> +after {{{samp([)}}} to complete link abbreviations.  You may also
> +define a function that implements special (e.g., completion) support
> +for inserting such a link with {{{kbd(C-c C-l)}}}.  Such a function
> +should not accept any arguments, and return the full link with
> +prefix. You can set the link completion function like this:

Mind the spaces after sentences.

In any case, updating contrib manual is not top priority, since many
section needs to be updated anyway.

> +[fn:37] This works if a function has been defined in the :complete
> +property of a link in org-link-parameters.

~org-link-parameters~

> -(org-add-link-type "id" 'org-id-open)
> +(org-link-set-parameters "id" :follow 'org-id-open)

Nitpick: #'org-id-open

> -(add-hook 'org-store-link-functions 'org-w3m-store-link)
> +(org-link-set-parameters "w3m" :store 'org-w3m-store-link)

#'org-w3m-store-link

You get the idea, I will not comment the other occurrences.

> +(type (save-match-data
> +(if (string-match org-plain-link-re hl)
> +(match-string-no-properties 1 hl)
> +  nil)))

Nitpick

  (save-match-data
(and (string-match org-plain-link-re hl)
 (match-string-no-properties 1 hl)))

> +(path (save-match-data
> +(if (string-match org-plain-link-re hl)
> +(match-string-no-properties 2 hl)
> +  nil)))

Ditto.

> -((assoc type org-link-parameters)
> +((and (assoc type org-link-parameters)
> +  (functionp (org-link-get-parameter type :follow)))

I think (functionp ...) is sufficient, no need for the `and' and 
(assoc type org-link-parameters), which `org-link-get-parameters'
already takes case of.  So

  ((functionp (org-link-get-parameters type :follow)
   ...)

> * lisp/org.el: Replace the variable `org-store-link-functions' with a
>   function by the same name.

You need to add the name of the function being modified.

> Update org-add-link-type
> 
> * lisp/org.el org-add-link-type: deprecated and now calls
>   `org-link-add'.
> 
> Create a new `org-link-add' function for making links.

You probably mean `org-link-set-parameters', since `org-link-add' would
be but a lesser version of the former.

> +  (org-link-add type :follow follow :export export)

See above.

> +(defun org-store-link-functions ()
> +  "Returns a list of functions that are called to create and store a link.
> +The functions in the variable `org-store-link-functions' come
> +first. These may be user-defined for different contexts. Then
> +comes the functions defined in the :store property of
> +org-link-parameters.
> +
> +Each function will be called in turn until one returns a non-nil
> +value. Each function should check if it is responsible for
> +creating this link (for example by looking at the major mode). If
> +not, it must exit and return nil. If yes, it should return a
> +non-nil value after a calling `org-store-link-props' with a list
> +of properties and values. Special properties are:

Mind the spaces between sentences.

I don't understand why we need to both preserve
`org-store-link-functions' and use :store property. Wouldn't one
location be enough?

> +:type The link prefix, like \"http\".  This must be given.
> +:link The link, like \"http://www.astro.uva.nl/~dominik\;.
> +  This is obligatory as well.
> +:description  Optional default description for the second pair
> +  of brackets in an Org-mode link.  The user can still change
> +  this when inserting this link into an Org-mode buffer.

Org-mode -> Org mode

> +In addition to these, any additional properties can be specified
> +and then used in capture templates."
> +  (append
> +   org-store-link-functions
> +   (cl-loop for link in org-link-parameters
> + with store-func
> + do (setq store-func (org-link-get-parameter (car link) :store))
> + if store-func
> + collect store-func)))