Info Catalog org: Add-on packages org: Hacking org: Adding export back-ends

org: Adding hyperlink types

 
 A.3 Adding hyperlink types
 ==========================
 
 Org has a large number of hyperlink types built-in (Hyperlinks).
 If you would like to add new link types, Org provides an interface for
 doing so.  Let’s 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)
 
 Let’s 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’, 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’.
 
    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 ‘C-c C-l’.  Such a
 function should not accept any arguments, and return the full link with
 prefix.
 

Info Catalog org: Add-on packages org: Hacking org: Adding export back-ends