B.1 Adding hyperlink types

Org has a large number of hyperlink types built-in (see Hyperlinks). If you would like to add new link types, it provides an interface for doing so. Lets look at an example file org-man.el that will add support for creating links like `[[man:printf][The printf manpage]]' to show Unix manual pages inside emacs:

     ;;; org-man.el - Support for links to manpages in Org
     
     (require 'org)
     
     (org-add-link-type "man" 'org-man-open)
     (add-hook 'org-store-link-functions 'org-man-store-link)
     
     (defcustom org-man-command 'man
       "The Emacs command to be used to display a man page."
       :group 'org-link
       :type '(choice (const man) (const woman)))
     
     (defun org-man-open (path)
       "Visit the manpage on PATH.
     PATH should be a topic that can be thrown at the man command."
       (funcall org-man-command path))
     
     (defun org-man-store-link ()
       "Store a link to a manpage."
       (when (memq major-mode '(Man-mode woman-mode))
         ;; This is a man page, we do make this link
         (let* ((page (org-man-get-page-name))
                (link (concat "man:" page))
                (description (format "Manpage for %s" page)))
           (org-store-link-props
            :type "man"
            :link link
            :description description))))
     
     (defun org-man-get-page-name ()
       "Extract the page name from the buffer name."
       ;; This works for both `Man-mode' and `woman-mode'.
       (if (string-match " \\(\\S-+\\)\\*" (buffer-name))
           (match-string 1 (buffer-name))
         (error "Cannot create link to this man page")))
     
     (provide 'org-man)
     
     ;;; org-man.el ends here

You would activate this new link type in .emacs with

     (require 'org-man)

Lets go through the file and see what it does.

1. It does (require 'org) to make sure that org.el has been loaded.
2. The next line calls org-add-link-type to define a new link type with prefix `man'. The call also contains the name of a function that will be called to follow such a link.
3. The next line adds a function to org-store-link-functions, in order to allow the command C-c l to record a useful link in a buffer displaying a man page.

The rest of the file defines the necessary variables and functions. First there is a customization variable that determines which emacs command should be used to display man pages. There are two options, man and woman. Then the function to follow a link is defined. It gets the link path as an argument - in this case the link path is just a topic for the manual command. The function calls the value of org-man-command to display the man page.

Finally the function org-man-store-link is defined. When you try to store a link with C-c l, also this function will be called to try to make a link. The function must first decide if it is supposed to create the link for this buffer type, we do this by checking the value of the variable major-mode. If not, the function must exit and return the value nil. If yes, the link is created by getting the manual topic from the buffer name and prefixing it with the string `man:'. Then it must call the command org-store-link-props and set the :type and :link properties. Optionally you can also set the :description property to provide a default for the link description when the link is later inserted into an Org buffer with C-c C-l.