Using completion in ref links

Posted March 06, 2014 at 07:11 PM | categories: org-mode | tags:

I came across this interesting post on using completion in links: http://draketo.de/light/english/free-software/custom-link-completion-org-mode-25-lines-emacs . I like the idea, but the type-flow for is not how I usually insert links. For the method there to work, you have to enter a link with C-c C-l, partially enter the link type, press enter, and then partially enter the description, which can be completed with tab. That is a lot of typing to me, compared to what I usually do which is type the link in directly. That habit does not work too well in large documents, and always has the possibility of a typo in the link, which then does not work or export correctly.

Here I explore how to make a 

ref:label
link using a function that provides all the options available as labels. The idea is to write a function that generates a list of labels in the buffer, which you can make a link to. Let us try an interactive function with a list of arguments. We are first going to generate a list of labels from the buffer. We use this code to get a list of labels in the buffer. You will get to choose which label you want a link to, and the function will insert it for you. Here it is: 

label:code-example

(defun get-labels ()
  (interactive)
  (save-excursion
    (goto-char (point-min))
    (let ((matches '()))
      (while (re-search-forward "label:\\(.*\\)" (point-max) t)
        (add-to-list 'matches (match-string-no-properties 1) t))
      matches)))

(defun org-insert-ref-link (&optional arg)
  (interactive (list (completing-read "label: " (get-labels))))
  (insert (format "ref:%s" arg)))

org-insert-ref-link

So, here you run the command with M-x org-insert-ref-link, press tab, and select the label you want to use. A link like this gets inserted in your buffer 

ref:code-example
. This is pretty nice. It should reduce the number of ref link mistakes, and make it easier to find the labels in the whole buffer.

Copyright (C) 2014 by John Kitchin. See the License for information about copying.

org-mode source

Org-mode version = 8.2.5h

Discuss on Twitter