Browse Source

manual: Update "Adding Hyperlink Types" section

Nicolas Goaziou 2 years ago
parent
commit
328406eb2c
1 changed files with 45 additions and 47 deletions
  1. 45 47
      contrib/manual.org

+ 45 - 47
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: