Next: Adding Hyperlink preview, Previous: Add-on Packages, Up: Hacking   [Contents][Index]


A.3 Adding Hyperlink Types ¶

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&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 ol-man)
;;; ol-man.el ends here

要在 Org 中启用手册页链接,在 Emacs 初始化文件中添加:

(require 'ol-man)

对 ‘ol-man.el’ 的说明

  1. 首先, ‘(require 'ol)’ 确保加载 ‘ol.el’ 。
  2. 随后 org-link-set-parameters 定义以 ‘man’ 为前缀的新链接类型,并关联用于打开、导出和存储该类链接的函数。完整的可关联项列表可查看变量 org-link-parameters 。
  3. 文件其余部分实现所需变量与函数。

    例如,在显示手册页的缓冲区中调用 org-store-link (见 Handling Links)时, org-man-store-link 负责存储链接。该函数接收参数 interactive? 但并未使用,不过其他存储函数在用户交互式存储链接时会有不同行为。函数首先检查主模式是否匹配,若不匹配则返回 nil ,表示不负责为当前缓冲区创建链接;否则将 ‘man:’ 前缀与手册主题拼接生成链接字符串,并提供默认描述。后续可通过函数 org-insert-link 将其插入回 Org 缓冲区。


Next: Adding Hyperlink preview, Previous: Add-on Packages, Up: Hacking   [Contents][Index]