mirror/org-mode
1
0
Fork 0
mirror of https://git.savannah.gnu.org/git/emacs/org-mode.git synced 2024-11-21 06:55:35 +00:00
Code

Doc fixes by Philip Rooke <phil@yax.org.uk>

Browse Source 
A number of small changes.  Mainly they are to pacify
'checkdoc-ispell' (if it seems appropriate) and to standardise the
names of the packages you can link to from within Org-mode.  I am
using the package names as spelt or abbreviated in their own
documentation (if I have been able to find it easily).  Thus, for
example, prefer MH-E over MHE, Rmail over RMAIL etc.
This commit is contained in:
Bastien Guerry 2008-03-21 17:10:23 +01:00
parent f2ab617d2a
commit e16c143089
9 changed files with 111 additions and 79 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
org-bbdb.el
View File

@ -1,4 +1,4 @@
;;; org-bbdb.el - Support for links to bbdb entries in Org-mode
;;; org-bbdb.el --- Support for links to BBDB entries from within Org-mode
;; Copyright (C) 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
@ -27,16 +27,19 @@
;;
;;; Commentary:
;; This file implements links to BBDB database entries for Org-mode.
;; This file implements links to BBDB database entries from within Org-mode.
;; Org-mode loads this module by default - if this is not what you want,
;; configure the variable `org-modules'.
;;; Code:
(require 'org)
;; Declare external functions and variables
(declare-function bbdb "ext:bbdb-com" (string elidep))
(declare-function bbdb-company "ext:bbdb-com" (string elidep))
(declare-function bbdb-current-record "ext:bbdb-com"
(declare-function bbdb-current-record "ext:bbdb-com"
(&optional planning-on-modifying))
(declare-function bbdb-name "ext:bbdb-com" (string elidep))
(declare-function bbdb-record-getprop "ext:bbdb" (record property))
@ -48,7 +51,7 @@
;; Implementation
(defun org-bbdb-store-link ()
"Store a link to a README file."
"Store a link to a BBDB database entry."
(when (eq major-mode 'bbdb-mode)
;; This is BBDB, we make this link!
(let* ((name (bbdb-record-name (bbdb-current-record)))
@ -59,6 +62,9 @@
link)))
(defun org-bbdb-export (path desc format)
"Create the export version of a BBDB link specified by PATH or DESC.
If exporting to either HTML or LaTeX FORMAT the link will be
italicised, in all other cases it is left unchanged."
"Create the exprt verison of a bbdb link."
(cond
((eq format 'html) (format "<i>%s</i>" (or desc path)))

10
org-gnus.el
View File

@ -1,4 +1,4 @@
;;; org-gnus.el - Support for links to GNUS groups and messages in Org-mode
;;; org-gnus.el --- Support for links to Gnus groups and messages from within Org-mode
;; Copyright (C) 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
@ -27,10 +27,12 @@
;;
;;; Commentary:
;; This file implements links to GNUS groups and messages for Org-mode.
;; This file implements links to Gnus groups and messages from within Org-mode.
;; Org-mode loads this module by default - if this is not what you want,
;; configure the variable `org-modules'.
;;; Code:
(require 'org)
(eval-when-compile
(require 'gnus-sum))
@ -58,7 +60,7 @@ negates this setting for the duration of the command."
;; Implementation
(defun org-gnus-store-link ()
"Store a link to an GNUS folder or message."
"Store a link to a Gnus folder or message."
(cond
((eq major-mode 'gnus-group-mode)
(let ((group (cond ((fboundp 'gnus-group-group-name) ; depending on Gnus
@ -104,7 +106,7 @@ negates this setting for the duration of the command."
link))))
(defun org-gnus-open (path)
"Follow an GNUS message or folder link."
"Follow the Gnus message or folder link specified by PATH."
(let (group article)
(if (not (string-match "\\`\\([^#]+\\)\\(#\\(.*\\)\\)?" path))
(error "Error in Gnus link"))

12
org-info.el
View File

@ -1,4 +1,4 @@
;;; org-info.el - Support for links to Info nodes in Org-mode
;;; org-info.el --- Support for links to Info nodes from within Org-Mode
;; Copyright (C) 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
@ -27,13 +27,16 @@
;;
;;; Commentary:
;; This file implements links to Info nodes for Org-mode.
;; This file implements links to Info nodes from within Org-mode.
;; Org-mode loads this module by default - if this is not what you want,
;; configure the variable `org-modules'.
;;; Code:
(require 'org)
;; Declare external functions and variables
(declare-function Info-find-node "info" (filename nodename
&optional no-going-back))
(defvar Info-current-file)
@ -45,6 +48,7 @@
;; Implementation
(defun org-info-store-link ()
"Store a link to an Info file and node."
"Store a link to an INFO folder or message."
(when (eq major-mode 'Info-mode)
(let (link desc)
@ -59,12 +63,12 @@
link)))
(defun org-info-open (path)
"Follow an INFO message link."
"Follow an Info file and node link specified by PATH."
(org-info-follow-link path))
(defun org-info-follow-link (name)
"Follow an info file & node link to NAME."
"Follow an Info file and node link specified by NAME."
(if (or (string-match "\\(.*\\)::?\\(.*\\)" name)
(string-match "\\(.*\\)" name))
(progn

59
org-irc.el
View File

@ -25,15 +25,16 @@
;;; Commentary:
;; Link to an IRC session. Only ERC has been implemented at the
;; moment.
;; This file implements links to an IRC session from within Org-mode.
;; Org-mode loads this module by default - if this is not what you want,
;; configure the variable `org-modules'.
;;
;; This file is loaded by default whenever org.el is loaded. Please
;; customize the variable `org-default-extensions' to select extensions
;; you would like to use, and to deselect those which you don't want.
;; Please customize the variable `org-default-extensions' to select
;; extensions you would like to use, and to deselect those which you don't
;; want.
;;
;; Please note that at the moment only ERC is supported. Other clients
;; shouldn't be diffficult to add though.
;; Please note that at the moment only ERC is supported. Other clients
;; shouldn't be difficult to add though.
;;
;; Then set `org-irc-link-to-logs' to non-nil if you would like a
;; file:/ type link to be created to the current line in the logs or
@ -55,9 +56,9 @@
(require 'erc-log)
(defvar org-irc-client 'erc
"The IRC client to act on")
"The IRC client to act on.")
(defvar org-irc-link-to-logs nil
"non-nil will store a link to the logs, nil will store an irc: style link")
"Non-nil will store a link to the logs, nil will store an irc: style link.")
(defvar erc-default-port) ; dynamically scoped from erc.el
(defvar erc-session-port) ; dynamically scoped form erc-backend.el
@ -71,7 +72,7 @@
(org-add-link-type "irc" 'org-irc-visit nil)
(defun org-irc-visit (link)
"Dispatch to the correct visit function based on the client"
"Parse LINK and dispatch to the correct function based on the client found."
(let ((link (org-irc-parse-link link)))
(cond
((eq org-irc-client 'erc)
@ -80,26 +81,28 @@
(error "erc only known client")))))
(defun org-irc-parse-link (link)
"Get a of irc link attributes where `link' looks like
server:port/chan/user (port, chan and user being optional)."
"Parse an IRC LINK and return the attributes found.
Parse a LINK that looks like server:port/chan/user (port, chan
and user being optional) and return any or the port, channel or user
attributes that are found."
(let* ((parts (split-string link "/" t))
(len (length parts)))
(when (or (< len 1) (> len 3))
(error "Failed to parse link needed 1-3 parts, got %d." len))
(error "Failed to parse link needed 1-3 parts, got %d" len))
(setcar parts (split-string (car parts) ":" t))
parts))
;;;###autoload
(defun org-irc-store-link ()
"Dispatch to the appropreate function to store a link to
something IRC related"
"Dispatch to the appropriate function to store a link to an IRC session."
(cond
((eq major-mode 'erc-mode)
(org-irc-erc-store-link))))
(defun org-irc-elipsify-description (string &optional after)
"Strip starting and ending whitespace and replace any chars
that appear after the value in `after' with '...'"
"Remove unnecessary white space from STRING and add ellipses if necessary.
Strip starting and ending white space from STRING and replace any
chars that the value AFTER with '...'"
(let* ((after (number-to-string (or after 30)))
(replace-map (list (cons "^[ \t]*" "")
(cons "[ \t]*$" "")
@ -114,10 +117,10 @@ that appear after the value in `after' with '...'"
;; ERC specific functions
(defun org-irc-erc-get-line-from-log (erc-line)
"Find the most suitable line to link to from the erc logs. If
the user is on the erc-prompt then search backward for the first
non-blank line, otherwise return the current line. The result is
a cons of the filename and search string."
"Find the best line to link to from the ERC logs given ERC-LINE as a start.
If the user is on the ERC-prompt then search backward for the
first non-blank line, otherwise return the current line. The
result is a cons of the filename and search string."
(erc-save-buffer-in-logs)
(with-current-buffer (find-file-noselect (erc-current-logfile))
(goto-char (point-max))
@ -135,8 +138,9 @@ a cons of the filename and search string."
(point-at-eol)))))))
(defun org-irc-erc-store-link ()
"Depending on the variable `org-irc-link-to-logs' store either
a link to the log file for the current session or an irc: link to
"Store a link to the IRC log file or the session itself.
Depending on the variable `org-irc-link-to-logs' store either a
link to the log file for the current session or an irc: link to
the session itself."
(if org-irc-link-to-logs
(let* ((erc-line (buffer-substring-no-properties
@ -168,7 +172,7 @@ the session itself."
(error "Failed to create ('irc:/' style) ERC link")))))
(defun org-irc-get-erc-link ()
"Return an org compatible irc:/ link from an ERC buffer"
"Return an org compatible irc:/ link from an ERC buffer."
(let* ((session-port (if (numberp erc-session-port)
(number-to-string erc-session-port)
erc-session-port))
@ -183,8 +187,9 @@ the session itself."
(erc-default-target)))))
(defun org-irc-get-current-erc-port ()
"Return the current port as a number. If there is not an
explicit port set then return the erc default."
"Return the current port as a number.
Return the current port number or, if none is set, return the ERC
default."
(cond
((stringp erc-session-port)
(string-to-number erc-session-port))
@ -194,7 +199,7 @@ explicit port set then return the erc default."
erc-default-port)))
(defun org-irc-visit-erc (link)
"Visit an ERC buffer based on criteria from the followed link"
"Visit an ERC buffer based on criteria found in LINK."
(let* ((server (car (car link)))
(port (or (string-to-number (cadr (pop link))) erc-default-port))
(server-buffer)

11
org-mac-message.el
View File

@ -1,4 +1,4 @@
;;; org-mac-message.el --- Support for links to Apple Mail messages by Message-ID
;;; org-mac-message.el --- Support for links to Apple Mail messages from within Org-mode
;; Copyright (C) 2008 Free Software Foundation, Inc.
@ -23,6 +23,11 @@
;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
;; Boston, MA 02110-1301, USA.
;;; Commentary:
;; This file implements links to Apple Mail messages from within Org-mode.
;; Org-mode does not load this module by default - if you would actually like
;; this to happen then configure the variable `org-modules'.
;;; Code:
(require 'org)
@ -44,8 +49,8 @@
(concat "\"" (org-trim return) "\""))))
(defun org-mac-message-open (message-id)
"Visit the message with the given Message-ID.
This will use the command `open' with the message url."
"Visit the message with the given MESSAGE-ID.
This will use the command `open' with the message URL."
(start-process (concat "open message:" message-id) nil
"open" (concat "message://<" (substring message-id 2) ">")))

45
org-mhe.el
View File

@ -1,4 +1,4 @@
;;; org-mhe.el - Support for links to MHE messages in Org-mode
;;; org-mhe.el --- Support for links to MH-E messages from within Org-mode
;; Copyright (C) 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
@ -27,18 +27,23 @@
;;
;;; Commentary:
;; This file implements links to MHE messages for Org-mode.
;; This file implements links to MH-E messages from within Org-mode.
;; Org-mode loads this module by default - if this is not what you want,
;; configure the variable `org-modules'.
;;; Code:
(require 'org)
;; Customization variables
(defcustom org-mhe-search-all-folders nil
"Non-nil means, that the search for the mh-message will be extended to
all folders if the message cannot be found in the folder given in the link.
Searching all folders is very efficient with one of the search engines
supported by MH-E, but will be slow with pick."
"Non-nil means the search for the mh-message may extend to all folders.
When non-nil, the search for a message will extend to all other
folders if it cannot be found in the folder given in the link.
Searching all folders may be slow with the default pick based
search but is very efficient with one of the other search engines
supported by MH-E."
:group 'org-link-follow
:type 'boolean)
@ -75,7 +80,7 @@ supported by MH-E, but will be slow with pick."
;; Implementation
(defun org-mhe-store-link ()
"Store a link to an MHE folder or message."
"Store a link to an MH-E folder or message."
(when (or (equal major-mode 'mh-folder-mode)
(equal major-mode 'mh-show-mode))
(let ((from (org-mhe-get-header "From:"))
@ -92,18 +97,18 @@ supported by MH-E, but will be slow with pick."
link)))
(defun org-mhe-open (path)
"Follow an MHE message link."
"Follow an MH-E message link specified by PATH."
(let (folder article)
(if (not (string-match "\\`\\([^#]+\\)\\(#\\(.*\\)\\)?" path))
(error "Error in MHE link"))
(error "Error in MH-E link"))
(setq folder (match-string 1 path)
article (match-string 3 path))
(org-mhe-follow-link folder article)))
;;; mh-e integration based on planner-mode
(defun org-mhe-get-message-real-folder ()
"Return the name of the current message real folder, so if you use
sequences, it will now work."
"Return the name of the real folder for the current message.
So if you use sequences, it will now work."
(save-excursion
(let* ((folder
(if (equal major-mode 'mh-folder-mode)
@ -134,15 +139,15 @@ sequences, it will now work."
)))
(defun org-mhe-get-message-folder-from-index ()
"Returns the name of the message folder in a index folder buffer."
"Return the name of the message folder in a index folder buffer."
(save-excursion
(mh-index-previous-folder)
(re-search-forward "^\\(+.*\\)$" nil t)
(message "%s" (match-string 1))))
(defun org-mhe-get-message-folder ()
"Return the name of the current message folder. Be careful if you
use sequences."
"Return the name of the current message folder.
Be careful if you use sequences."
(save-excursion
(if (equal major-mode 'mh-folder-mode)
mh-current-folder
@ -150,8 +155,8 @@ use sequences."
mh-show-folder-buffer)))
(defun org-mhe-get-message-num ()
"Return the number of the current message. Be careful if you
use sequences."
"Return the number of the current message.
Be careful if you use sequences."
(save-excursion
(if (equal major-mode 'mh-folder-mode)
(mh-get-msg-num nil)
@ -159,9 +164,9 @@ use sequences."
(mh-show-buffer-message-number))))
(defun org-mhe-get-header (header)
"Return a header of the message in folder mode. This will create a
show buffer for the corresponding message. If you have a more clever
idea..."
"Return the field for HEADER of the message in folder mode.
This will create a show buffer for the corresponding message. If
you have a better idea of how to do this then please let us know."
(let* ((folder (org-mhe-get-message-folder))
(num (org-mhe-get-message-num))
(buffer (get-buffer-create (concat "show-" folder)))
@ -179,7 +184,7 @@ idea..."
header-field)))
(defun org-mhe-follow-link (folder article)
"Follow an MHE link to FOLDER and ARTICLE.
"Follow an MH-E link to FOLDER and ARTICLE.
If ARTICLE is nil FOLDER is shown. If the configuration variable
`org-mhe-search-all-folders' is t and `mh-searcher' is pick,
ARTICLE is searched in all folders. Indexed searches (swish++,

14
org-rmail.el
View File

@ -1,4 +1,4 @@
;;; org-rmail.el - Support for links to RMAIL messages in Org-mode
;;; org-rmail.el --- Support for links to Rmail messages from within Org-mode
;; Copyright (C) 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
@ -27,10 +27,12 @@
;;
;;; Commentary:
;; This file implements links to RMAIL messages for Org-mode.
;; This file implements links to Rmail messages from within Org-mode.
;; Org-mode loads this module by default - if this is not what you want,
;; configure the variable `org-modules'.
;;; Code:
(require 'org)
;; Declare external functions and variables
@ -45,7 +47,7 @@
;; Implementation
(defun org-rmail-store-link ()
"Store a link to an RMAIL folder or message."
"Store a link to an Rmail folder or message."
(when (or (eq major-mode 'rmail-mode)
(eq major-mode 'rmail-summary-mode))
(save-window-excursion
@ -70,16 +72,16 @@
link)))))
(defun org-rmail-open (path)
"Follow an RMAIL message link."
"Follow an Rmail message link to the specified PATH."
(let (folder article)
(if (not (string-match "\\`\\([^#]+\\)\\(#\\(.*\\)\\)?" path))
(error "Error in RMAIL link"))
(error "Error in Rmail link"))
(setq folder (match-string 1 path)
article (match-string 3 path))
(org-rmail-follow-link folder article)))
(defun org-rmail-follow-link (folder article)
"Follow an RMAIL link to FOLDER and ARTICLE."
"Follow an Rmail link to FOLDER and ARTICLE."
(require 'rmail)
(setq article (org-add-angle-brackets article))
(let (message-number)

13
org-vm.el
View File

@ -1,4 +1,4 @@
;;; org-vm.el - Support for links to VM messages in Org-mode
;;; org-vm.el --- Support for links to VM messages from within Org-mode
;; Copyright (C) 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
@ -26,11 +26,12 @@
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;
;;; Commentary:
;; This file implements links to VM messages and folders for Org-mode.
;; This file implements links to VM messages and folders from within Org-mode.
;; Org-mode loads this module by default - if this is not what you want,
;; configure the variable `org-modules'.
;;; Code:
(require 'org)
;; Declare external functions and variables
@ -53,7 +54,7 @@
;; Implementation
(defun org-vm-store-link ()
"Store a link to an VM folder or message."
"Store a link to a VM folder or message."
(when (or (eq major-mode 'vm-summary-mode)
(eq major-mode 'vm-presentation-mode))
(and (eq major-mode 'vm-presentation-mode) (vm-summarize))
@ -80,13 +81,13 @@
link))))
(defun org-vm-open (path)
"Follow an VM message link."
"Follow a VM message link specified by PATH."
(let (folder article)
(if (not (string-match "\\`\\([^#]+\\)\\(#\\(.*\\)\\)?" path))
(error "Error in VM link"))
(setq folder (match-string 1 path)
article (match-string 3 path))
;; The prefix arguemtn will be interpreted as read-only
;; The prefix argument will be interpreted as read-only
(org-vm-follow-link folder article current-prefix-arg)))
(defun org-vm-follow-link (&optional folder article readonly)

12
org-wl.el
View File

@ -1,4 +1,4 @@
;;; org-wl.el - Support for links to Wanderlust messages in Org-mode
;;; org-wl.el --- Support for links to Wanderlust messages from within Org-mode
;; Copyright (C) 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
@ -27,10 +27,12 @@
;;
;;; Commentary:
;; This file implements links to Wanderlust messages for Org-mode.
;; This file implements links to Wanderlust messages from within Org-mode.
;; Org-mode loads this module by default - if this is not what you want,
;; configure the variable `org-modules'.
;;; Code:
(require 'org)
(defgroup org-wl nil
@ -73,7 +75,7 @@
;; Implementation
(defun org-wl-store-link ()
"Store a link to an WL folder or message."
"Store a link to a WL folder or message."
(when (eq major-mode 'wl-summary-mode)
(let* ((msgnum (wl-summary-message-number))
(mark-info (wl-summary-registered-temp-mark msgnum))
@ -110,7 +112,7 @@
link)))
(defun org-wl-open (path)
"Follow an WL message link."
"Follow the WL message link specified by PATH."
;; XXX: The imap-uw's MH folder names start with "%#".
(if (not (string-match "\\`\\(\\(?:%#\\)?[^#]+\\)\\(#\\(.*\\)\\)?" path))
(error "Error in Wanderlust link"))
@ -134,4 +136,4 @@
(provide 'org-wl)
;;; org-wl.el ends here
;;; org-wl.el ends here