forked from mirrors/org-mode
manual: Update "Adding Hyperlink Types" section
This commit is contained in:
Nicolas Goaziou
parent
1c6e72c086
commit
328406eb2c
|
|
@ -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§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 '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.
|
||||
#+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.
|
||||
|
||||
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.
|
||||
3. The rest of the file implements necessary variables and functions.
|
||||
|
||||
{{{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.
|
||||
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:
|
||||
|
|
|
|||
Loading…
Reference in New Issue