This is the official manual for the latest Org-mode release.
Org has a large number of hyperlink types built-in (see 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
Let's go through the file and see what it does.
(require 'org)to make sure that org.el has been loaded.
org-add-link-typeto 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.
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,
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
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
and set the
: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.