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

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.

9 files changed, 111 insertions, 79 deletions

diff --git a/org-bbdb.el b/org-bbdb.el
index 772a1fe..d385153 100644
--- a/org-bbdb.el
+++ b/org-bbdb.el
@@ -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)))
diff --git a/org-gnus.el b/org-gnus.el
index 2a23f62..bb14d78 100644
--- a/org-gnus.el
+++ b/org-gnus.el
@@ -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"))
diff --git a/org-info.el b/org-info.el
index 3d71b8b..97e9b93 100644
--- a/org-info.el
+++ b/org-info.el
@@ -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
diff --git a/org-irc.el b/org-irc.el
index f9e2b97..0b1a5db 100644
--- a/org-irc.el
+++ b/org-irc.el
@@ -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)
diff --git a/org-mac-message.el b/org-mac-message.el
index 7e26885..b645b9b 100644
--- a/org-mac-message.el
+++ b/org-mac-message.el
@@ -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) ">")))
 
diff --git a/org-mhe.el b/org-mhe.el
index e1d7565..24729ad 100644
--- a/org-mhe.el
+++ b/org-mhe.el
@@ -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++,
diff --git a/org-rmail.el b/org-rmail.el
index 225918c..614ca5b 100644
--- a/org-rmail.el
+++ b/org-rmail.el
@@ -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)
diff --git a/org-vm.el b/org-vm.el
index 636c127..fb17a96 100644
--- a/org-vm.el
+++ b/org-vm.el
@@ -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)
diff --git a/org-wl.el b/org-wl.el
index 7389a22..83477ab 100644
--- a/org-wl.el
+++ b/org-wl.el
@@ -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
\ No newline at end of file
+;;; org-wl.el ends here