diff --git a/contrib/manual.org b/contrib/manual.org index ec3ca2708..1db816dfe 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§ion=all" link)) + (desc (or description link))) + (pcase format + (`html (format "%s" 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: