Adding Hyperlink Types (The Org Manual)

Next: Adding Export Back-ends, Previous: Add-on Packages, Up: Hacking [Contents][Index]

### A.3 Adding Hyperlink Types

Org has many built-in hyperlink types (see Hyperlinks), and an interface for adding new link types. The following example shows the process of adding Org links to Unix man pages, which look like this

    [[man:printf][The printf manual]]

The following ‘`org-man.el`’ file implements it

    ;;; org-man.el - Support for links to man pages in Org mode
    (require 'org)

    (org-link-set-parameters "man"
                             :follow org-man-command
                             :export #'org-man-export
                             :store #'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-store-link ()
      "Store a link to a man page."
      (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 "Man page 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")))

    (defun org-man-export (link description format)
      "Export a man page link from Org files."
      (let ((path (format "http://man.he.net/?topic=%s&section=all" link))
            (desc (or description link)))
        (pcase format
          (`html (format "<a target=\"_blank\" href=\"%s\">%s</a>" path desc))
          (`latex (format "\\href{%s}{%s}" path desc))
          (`texinfo (format "@uref{%s,%s}" path desc))
          (`ascii (format "%s (%s)" desc path))
          (t path))))

    (provide 'org-man)
    ;;; org-man.el ends here

To activate links to man pages in Org, enter this in the Emacs init file:

    (require 'org-man)

A review of ‘`org-man.el`’:

1. First, ‘`(require 'org)`’ ensures ‘`org.el`’ is loaded.
2. Then `org-link-set-parameters` defines a new link type with ‘`man`’ prefix and associates functions for following, exporting and storing such links. See the variable `org-link-parameters` for a complete list of possible associations.
3. The rest of the file implements necessary variables and functions.

   For example, `org-man-store-link` is responsible for storing a link when `org-store-link` (see Handling Links) is called from a buffer displaying a man page. It first checks if the major mode is appropriate. If check fails, the function returns `nil`, which means it isn’t responsible for creating a link to the current buffer. Otherwise the function makes a link string by combining the ‘`man:`’ prefix with the man topic. It also provides a default description. The function `org-insert-link` can insert it back into an Org buffer later on.

Next: Adding Export Back-ends, Previous: Add-on Packages, Up: Hacking [Contents][Index]