Org 内置多种超链接类型(见 Hyperlinks),并提供用于添加新链接类型的接口。下面示例展示为 Unix 手册页添加 Org 链接的过程,形式如下:
[[man:printf][The printf manual]]
下面的 ‘ol-man.el’ 文件实现了该功能:
;;; ol-man.el - Support for links to man pages in Org mode
(require 'ol)
(org-link-set-parameters "man"
:follow #'org-man-open
:export #'org-man-export
:store #'org-man-store-link)
(defcustom org-man-command 'man
"用于显示手册页的 Emacs 命令。"
:group 'org-link
:type '(choice (const man) (const woman)))
(defun org-man-open (path _)
"打开 PATH 对应的手册页。
PATH 应为可被 man 命令处理的主题。"
(funcall org-man-command path))
(defun org-man-store-link (&optional _interactive?)
"存储指向手册页的链接。"
(when (memq major-mode '(Man-mode woman-mode))
;; 当前为手册页缓冲区,创建该链接
(let* ((page (org-man-get-page-name))
(link (concat "man:" page))
(description (format "Man page for %s" page)))
(org-link-store-props
:type "man"
:link link
:description description))))
(defun org-man-get-page-name ()
"从缓冲区名称中提取手册页名称。"
;; 同时适用于 `Man-mode' 和 `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 _)
"从 Org 文件导出手册页链接。"
(let ((path (format "http://man.he.net/?topic=%s§ion=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 ol-man)
;;; ol-man.el ends here
要在 Org 中启用手册页链接,在 Emacs 初始化文件中添加:
(require 'ol-man)
对 ‘ol-man.el’ 的说明
org-link-set-parameters 定义以 ‘man’ 为前缀的新链接类型,并关联用于打开、导出和存储该类链接的函数。完整的可关联项列表可查看变量 org-link-parameters 。
例如,在显示手册页的缓冲区中调用 org-store-link (见 Handling Links)时, org-man-store-link 负责存储链接。该函数接收参数 interactive? 但并未使用,不过其他存储函数在用户交互式存储链接时会有不同行为。函数首先检查主模式是否匹配,若不匹配则返回 nil ,表示不负责为当前缓冲区创建链接;否则将 ‘man:’ 前缀与手册主题拼接生成链接字符串,并提供默认描述。后续可通过函数 org-insert-link 将其插入回 Org 缓冲区。