Merge branch 'maint'
[org-mode.git] / lisp / org-info.el
blob7f859f9040d2ececbf512d15e5d4d6dca236541c
1 ;;; org-info.el --- Support for Links to Info Nodes -*- lexical-binding: t; -*-
3 ;; Copyright (C) 2004-2017 Free Software Foundation, Inc.
5 ;; Author: Carsten Dominik <carsten at orgmode dot org>
6 ;; Keywords: outlines, hypermedia, calendar, wp
7 ;; Homepage: http://orgmode.org
8 ;;
9 ;; This file is part of GNU Emacs.
11 ;; GNU Emacs is free software: you can redistribute it and/or modify
12 ;; it under the terms of the GNU General Public License as published by
13 ;; the Free Software Foundation, either version 3 of the License, or
14 ;; (at your option) any later version.
16 ;; GNU Emacs is distributed in the hope that it will be useful,
17 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
18 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 ;; GNU General Public License for more details.
21 ;; You should have received a copy of the GNU General Public License
22 ;; along with GNU Emacs. If not, see <https://www.gnu.org/licenses/>.
23 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
25 ;;; Commentary:
27 ;; This file implements links to Info nodes from within Org mode.
28 ;; Org mode loads this module by default - if this is not what you want,
29 ;; configure the variable `org-modules'.
31 ;;; Code:
33 (require 'org)
35 ;; Declare external functions and variables
37 (declare-function Info-find-node "info"
38 (filename nodename &optional no-going-back strict-case))
39 (defvar Info-current-file)
40 (defvar Info-current-node)
42 ;; Install the link type
43 (org-link-set-parameters "info"
44 :follow #'org-info-open
45 :export #'org-info-export
46 :store #'org-info-store-link)
48 ;; Implementation
49 (defun org-info-store-link ()
50 "Store a link to an Info file and node."
51 (when (eq major-mode 'Info-mode)
52 (let ((link (concat "info:"
53 (file-name-nondirectory Info-current-file)
54 "#" Info-current-node))
55 (desc (concat (file-name-nondirectory Info-current-file)
56 "#" Info-current-node)))
57 (org-store-link-props :type "info" :file Info-current-file
58 :node Info-current-node
59 :link link :desc desc)
60 link)))
62 (defun org-info-open (path)
63 "Follow an Info file and node link specified by PATH."
64 (org-info-follow-link path))
67 (defun org-info-follow-link (name)
68 "Follow an Info file and node link specified by NAME."
69 (if (or (string-match "\\(.*\\)[#:]:?\\(.*\\)" name)
70 (string-match "\\(.*\\)" name))
71 (let ((filename (match-string 1 name))
72 (nodename-or-index (or (match-string 2 name) "Top")))
73 (require 'info)
74 ;; If nodename-or-index is invalid node name, then look it up
75 ;; in the index.
76 (condition-case nil
77 (Info-find-node filename nodename-or-index)
78 (user-error (Info-find-node filename "Top")
79 (condition-case nil
80 (Info-index nodename-or-index)
81 (user-error "Could not find '%s' node or index entry"
82 nodename-or-index)))))
83 (user-error "Could not open: %s" name)))
85 (defconst org-info-emacs-documents
86 '("ada-mode" "auth" "autotype" "bovine" "calc" "ccmode" "cl" "dbus" "dired-x"
87 "ebrowse" "ede" "ediff" "edt" "efaq-w32" "efaq" "eieio" "eintr" "elisp"
88 "emacs-gnutls" "emacs-mime" "emacs" "epa" "erc" "ert" "eshell" "eudc" "eww"
89 "flymake" "forms" "gnus" "htmlfontify" "idlwave" "ido" "info" "mairix-el"
90 "message" "mh-e" "newsticker" "nxml-mode" "octave-mode" "org" "pcl-cvs"
91 "pgg" "rcirc" "reftex" "remember" "sasl" "sc" "semantic" "ses" "sieve"
92 "smtpmail" "speedbar" "srecode" "todo-mode" "tramp" "url" "vip" "viper"
93 "widget" "wisent" "woman")
94 "List of emacs documents available.
95 Taken from <https://www.gnu.org/software/emacs/manual/html_mono/.>")
97 (defconst org-info-other-documents
98 '(("libc" . "https://www.gnu.org/software/libc/manual/html_mono/libc.html")
99 ("make" . "https://www.gnu.org/software/make/manual/make.html"))
100 "Alist of documents generated from Texinfo source.
101 When converting info links to HTML, links to any one of these manuals are
102 converted to use these URL.")
104 (defun org-info-map-html-url (filename)
105 "Return URL or HTML file associated to Info FILENAME.
106 If FILENAME refers to an official GNU document, return a URL pointing to
107 the official page for that document, e.g., use \"gnu.org\" for all Emacs
108 related documents. Otherwise, append \".html\" extension to FILENAME.
109 See `org-info-emacs-documents' and `org-info-other-documents' for details."
110 (cond ((member filename org-info-emacs-documents)
111 (format "https://www.gnu.org/software/emacs/manual/html_mono/%s.html"
112 filename))
113 ((cdr (assoc filename org-info-other-documents)))
114 (t (concat filename ".html"))))
116 (defun org-info--expand-node-name (node)
117 "Expand Info NODE to HTML cross reference."
118 ;; See (info "(texinfo) HTML Xref Node Name Expansion") for the
119 ;; expansion rule.
120 (let ((node (replace-regexp-in-string
121 "\\([ \t\n\r]+\\)\\|\\([^a-zA-Z0-9]\\)"
122 (lambda (m)
123 (if (match-end 1) "-" (format "_%04x" (string-to-char m))))
124 (org-trim node))))
125 (cond ((string= node "") "")
126 ((string-match-p "\\`[0-9]" node) (concat "g_t" node))
127 (t node))))
129 (defun org-info-export (path desc format)
130 "Export an info link.
131 See `org-link-parameters' for details about PATH, DESC and FORMAT."
132 (let* ((parts (split-string path "[#:]:?"))
133 (manual (car parts))
134 (node (or (nth 1 parts) "Top")))
135 (pcase format
136 (`html
137 (format "<a href=\"%s#%s\">%s</a>"
138 (org-info-map-html-url manual)
139 (org-info--expand-node-name node)
140 (or desc path)))
141 (`texinfo
142 (let ((title (or desc "")))
143 (format "@ref{%s,%s,,%s,}" node title manual)))
144 (_ nil))))
146 (provide 'org-info)
148 ;;; org-info.el ends here