summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorNicolas Goaziou <mail@nicolasgoaziou.fr>2018-02-18 10:58:21 +0100
committerNicolas Goaziou <mail@nicolasgoaziou.fr>2018-02-18 11:00:49 +0100
commit328406eb2ca49c173fbda0f75f63378afb806b10 (patch)
tree230a8431b40f5bccfcf3b0f19e050145bf39c300
parent1c6e72c086f74d8730827885da54262646d42387 (diff)
downloadorg-mode-328406eb2ca49c173fbda0f75f63378afb806b10.tar.gz
manual: Update "Adding Hyperlink Types" section
-rw-r--r--contrib/manual.org92
1 files changed, 45 insertions, 47 deletions
diff --git a/contrib/manual.org b/contrib/manual.org
index ec3ca27..1db816d 100644
--- a/contrib/manual.org
+++ b/contrib/manual.org
@@ -19200,37 +19200,35 @@ information is at: https://orgmode.org/worg/org-contrib/.
#+cindex: hyperlinks, adding new types
Org has many built-in hyperlink types (see [[*Hyperlinks]]), and an
-interface for adding new link types. The example file, =org-man.el=,
-shows the process of adding Org links to Unix man pages, which look
-like this
+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]]
-#+begin_src emacs-lisp
- ;;; org-man.el - Support for links to manpages in Org
+#+texinfo: @noindent
+The following =org-man.el= file implements it
+#+begin_src emacs-lisp
+ ;;; org-man.el - Support for links to man pages in Org mode
(require 'org)
- (org-add-link-type "man" 'org-man-open)
- (add-hook 'org-store-link-functions 'org-man-store-link)
+ (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-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."
+ "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
+ ;; 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)))
+ (description (format "Man page for %s" page)))
(org-store-link-props
:type "man"
:link link
@@ -19243,13 +19241,24 @@ like this
(match-string 1 (buffer-name))
(error "Cannot create link to this man page")))
- (provide 'org-man)
+ (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
#+end_src
#+texinfo: @noindent
-To activate links to man pages in Org, enter this in the init file:
+To activate links to man pages in Org, enter this in the Emacs init
+file:
#+begin_src emacs-lisp
(require 'org-man)
@@ -19260,37 +19269,26 @@ A review of =org-man.el=:
1. First, ~(require 'org)~ ensures =org.el= is loaded.
-2. Then ~org-add-link-type~ defines a new link type with =man= prefix.
- The call contains the function to call that follows the link type.
+2.
-3.
- #+vindex: org-store-link-functions
- The next line adds a function to ~org-store-link-functions~ that
- records a useful link with the command {{{kbd(C-c l)}}} in a buffer
- displaying a man page.
-
-The rest of the file defines necessary variables and functions. First
-is the customization variable ~org-man-command~. It has two options,
-~man~ and ~woman~. Next is a function whose argument is the link
-path, which for man pages is the topic of the man command. To follow
-the link, the function calls the ~org-man-command~ to display the man
-page.
-
-{{{kbd(C-c l)}}} constructs and stores the link.
-
-{{{kbd(C-c l)}}} calls the function ~org-man-store-link~, which first
-checks if the ~major-mode~ is appropriate. If check fails, the
-function returns ~nil~. Otherwise the function makes a link string by
-combining the =man:= prefix with the man topic. The function then
-calls ~org-store-link-props~ with ~:type~ and ~:link~ properties.
-A ~:description~ property is an optional string that is displayed when
-the function inserts the link in the Org buffer.
-
-{{{kbd(C-c C-l)}}} inserts the stored link.
-
-To define new link types, define a function that implements completion
-support with {{{kbd(C-c C-l)}}}. This function should not accept any
-arguments but return the appropriate prefix and complete link string.
+ #+findex: org-link-set-parameters
+ #+vindex: org-link-parameters
+ 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.
** Adding Export Back-ends
:PROPERTIES: