Correct some docstrings

This patch makes some straightforward corrections to a number of
docstrings.  Each change is normally to:

- correct a typo, or
- fix up hyperlinks to function or variable names, or
- ensure slightly better conformance with the documentation guidelines
  and tips given in the Elisp manual

No attempt is made to provide missing docstrings or document arguments.

Cheers,

Phil

lisp/org-agenda.el

@@ -142,8 +142,8 @@ specifies the maximum number of lines that will be added for each entry
 that is listed in the agenda view.
 
 Note that this variable is not used during display, only when exporting
-the agenda.  For agenda display, see org-agenda-entry-text-mode and the
-variable `org-agenda-entry-text-maxlines'."
+the agenda.  For agenda display, see the variables `org-agenda-entry-text-mode'
+and `org-agenda-entry-text-maxlines'."
   :group 'org-agenda
   :type 'integer)
 
@@ -595,7 +595,7 @@ to make his option also apply to the tags-todo list."
 There are different motivations for using different values, please think
 carefully when configuring this variable.
 
-This applie when creating the global todo list.
+This applies when creating the global todo list.
 Valid values are:
 
 near    Don't show near deadline entries.  A deadline is near when it is
@@ -762,7 +762,7 @@ Needs to be set before org.el is loaded."
   :type 'boolean)
 
 (defcustom org-agenda-start-with-follow-mode nil
-  "The initial value of follow-mode in a newly created agenda window."
+  "The initial value of follow mode in a newly created agenda window."
   :group 'org-agenda-startup
   :type 'boolean)
 
@@ -1008,7 +1008,7 @@ When this is non-nil, the string will be split on whitespace, and each
 snippet will be searched individually, and all must match in order to
 select an entry.  A snippet is then a single string of non-white
 characters, or a string in double quotes, or a regexp in {} braces.
-If a snippet is preceeded by \"-\", the snippet must *not* match.
+If a snippet is preceded by \"-\", the snippet must *not* match.
 \"+\" is syntactic sugar for positive selection.  Each snippet may
 be found as a full word or a partial word, but see the variable
 `org-agenda-search-view-force-full-words'.
@@ -1018,7 +1018,7 @@ with each space character matching any amount of whitespace, including
 line breaks.
 
 Even when this is nil, you can still switch to Boolean search dynamically
-by preceeding the first snippet with \"+\" or \"-\".  If the first snippet
+by preceding the first snippet with \"+\" or \"-\".  If the first snippet
 is a regexp marked with braces like \"{abc}\", this will also switch to
 boolean search."
   :group 'org-agenda-search-view
@@ -1029,8 +1029,7 @@ boolean search."
       'org-agenda-search-view-always-boolean))
 
 (defcustom org-agenda-search-view-force-full-words nil
-  "Non-nil me
-ans, search words must be matches as complete words.
+  "Non-nil means, search words must be matches as complete words.
 When nil, they may also match part of a word."
   :group 'org-agenda-search-view
   :type 'boolean)
@@ -1286,7 +1285,7 @@ range, respectively."
 		  (function))))
 
 (defcustom org-agenda-scheduled-leaders '("Scheduled: " "Sched.%2dx: ")
-  "Text preceeding scheduled items in the agenda view.
+  "Text preceding scheduled items in the agenda view.
 This is a list with two strings.  The first applies when the item is
 scheduled on the current day.  The second applies when it has been scheduled
 previously, it may contain a %d indicating that this is the nth time that
@@ -1299,7 +1298,7 @@ that passed since this item was scheduled first."
 	  (string :tag "Scheduled previously")))
 
 (defcustom org-agenda-inactive-leader "["
-  "Text preceeding item pulled into the agenda by inactive time stamps.
+  "Text preceding item pulled into the agenda by inactive time stamps.
 These entries are added to the agenda when pressing \"[\"."
   :group 'org-agenda-line-format
   :type '(list
@@ -1307,7 +1306,7 @@ These entries are added to the agenda when pressing \"[\"."
 	  (string :tag "Scheduled previously")))
 
 (defcustom org-agenda-deadline-leaders '("Deadline:  " "In %3d d.: ")
-  "Text preceeding deadline items in the agenda view.
+  "Text preceding deadline items in the agenda view.
 This is a list with two strings.  The first applies when the item has its
 deadline on the current day.  The second applies when it is in the past or
 in the future, it may contain %d to capture how many days away the deadline
@@ -1354,7 +1353,7 @@ When non-nil, this must be the number of minutes, e.g. 60 for one hour."
 (defcustom org-agenda-hide-tags-regexp nil
   "Regular expression used to filter away specific tags in agenda views.
 This means that these tags will be present, but not be shown in the agenda
-line.  Secondayt filltering will still work on the hidden tags.
+line.  Secondary filtering will still work on the hidden tags.
 Nil means don't hide any tags."
   :group 'org-agenda-line-format
   :type '(choice
@@ -1389,7 +1388,7 @@ it means that the tags should be flushright to that column.  For example,
 (defcustom org-agenda-fontify-priorities 'cookies
   "Non-nil means highlight low and high priorities in agenda.
 When t, the highest priority entries are bold, lowest priority italic.
-However, settings in org-priority-faces will overrule these faces.
+However, settings in `org-priority-faces' will overrule these faces.
 When this variable is the symbol `cookies', only fontify the
 cookies, not the entire task.
 This may also be an association list of priority faces, whose
@@ -1492,7 +1491,7 @@ works you probably want to add it to `org-agenda-custom-commands' for good."
 (defvar org-agenda-redo-command nil)
 (defvar org-agenda-query-string nil)
 (defvar org-agenda-mode-hook nil
-  "Hook for org-agenda-mode, run after the mode is turned on.")
+  "Hook for `org-agenda-mode', run after the mode is turned on.")
 (defvar org-agenda-type nil)
 (defvar org-agenda-force-single-file nil)
 (defvar org-agenda-bulk-marked-entries) ;; Defined further down in this file
@@ -2260,7 +2259,7 @@ s   Search for keywords                 C   Configure custom agenda commands
 If CMD-KEY is a string of length 1, it is used as a key in
 `org-agenda-custom-commands' and triggers this command.  If it is a
 longer string it is used as a tags/todo match string.
-Paramters are alternating variable names and values that will be bound
+Parameters are alternating variable names and values that will be bound
 before running the agenda command."
   (let (pars)
     (while parameters
@@ -2288,7 +2287,7 @@ before running the agenda command."
 If CMD-KEY is a string of length 1, it is used as a key in
 `org-agenda-custom-commands' and triggers this command.  If it is a
 longer string it is used as a tags/todo match string.
-Paramters are alternating variable names and values that will be bound
+Parameters are alternating variable names and values that will be bound
 before running the agenda command.
 
 The output gives a line for each selected agenda item.  Each
@@ -2343,8 +2342,8 @@ agenda-day   The day in the agenda where this is listed"
 	  (princ "\n"))))))
 
 (defun org-fix-agenda-info (props)
-  "Make sure all properties on an agenda item have a canonical form,
-so the export commands can easily use it."
+  "Make sure all properties on an agenda item have a canonical form.
+This ensures the export commands can easily use it."
   (let (tmp re)
     (when (setq tmp (plist-get props 'tags))
       (setq props (plist-put props 'tags (mapconcat 'identity tmp ":"))))
@@ -2710,7 +2709,7 @@ removed from the entry content.  Currently only `planning' is allowed here."
 (defvar org-agenda-filter nil)
 (defvar org-agenda-filter-preset nil
   "A preset of the tags filter used for secondary agenda filtering.
-This must be a list of strings, each string must be a single tag preceeded
+This must be a list of strings, each string must be a single tag preceded
 by \"+\" or \"-\".
 This variable should not be set directly, but agenda custom commands can
 bind it in the options section.")
@@ -2901,7 +2900,7 @@ This may also be a Lisp form, it will be evaluated.
 Never set this variable using `setq' or so, because then it will apply
 to all future agenda commands.  Instead, bind it with `let' to scope
 it dynamically into the agenda-constructing command.  A good way to set
-it is through options in org-agenda-custom-commands.")
+it is through options in `org-agenda-custom-commands'.")
 
 (defun org-agenda-skip ()
   "Throw to `:skip' in places that should be skipped.
@@ -3131,7 +3130,7 @@ When EMPTY is non-nil, also include days without any entries."
 (defvar org-agenda-start-day nil  ; dynamically scoped parameter
 "Custom commands can set this variable in the options section.")
 (defvar org-agenda-last-arguments nil
-  "The arguments of the previous call to org-agenda")
+  "The arguments of the previous call to `org-agenda'.")
 (defvar org-starting-day nil) ; local variable in the agenda buffer
 (defvar org-agenda-span nil) ; local variable in the agenda buffer
 (defvar org-include-all-loc nil) ; local variable
@@ -3403,7 +3402,7 @@ is, or it can be broken into a number of snippets, each of which must match
 in a Boolean way to select an entry.  The default depends on the variable
 `org-agenda-search-view-always-boolean'.
 Even if this is turned off (the default) you can always switch to
-Boolean search dynamically by preceeding the first word with  \"+\" or \"-\".
+Boolean search dynamically by preceding the first word with  \"+\" or \"-\".
 
 The default is a direct search of the whole phrase, where each space in
 the search string can expand to an arbitrary amount of whitespace,
@@ -3418,9 +3417,9 @@ match whole words, not parts of a word) if
 `org-agenda-search-view-force-full-words' is set (default is nil).
 
 Boolean search snippets enclosed by curly braces are interpreted as
-regular expressions that must or (when preceeded with \"-\") must not
+regular expressions that must or (when preceded with \"-\") must not
 match in the entry.  Snippets enclosed into double quotes will be taken
-as a whole, to incude whitespace.
+as a whole, to include whitespace.
 
 - If the search string starts with an asterisk, search only in headlines.
 - If (possibly after the leading star) the search string starts with an
@@ -3774,7 +3773,7 @@ This variable should not be set directly, but custom commands can bind it
 in the options section.")
 
 (defun org-agenda-skip-entry-when-regexp-matches ()
-  "Checks if the current entry contains match for `org-agenda-skip-regexp'.
+  "Check if the current entry contains match for `org-agenda-skip-regexp'.
 If yes, it returns the end position of this entry, causing agenda commands
 to skip the entry but continuing the search in the subtree.  This is a
 function that can be put into `org-agenda-skip-function' for the duration
@@ -3786,7 +3785,7 @@ of a command."
     (and skip end)))
 
 (defun org-agenda-skip-subtree-when-regexp-matches ()
-  "Checks if the current subtree contains match for `org-agenda-skip-regexp'.
+  "Check if the current subtree contains match for `org-agenda-skip-regexp'.
 If yes, it returns the end position of this tree, causing agenda commands
 to skip this subtree.  This is a function that can be put into
 `org-agenda-skip-function' for the duration of a command."
@@ -3797,7 +3796,7 @@ to skip this subtree.  This is a function that can be put into
     (and skip end)))
 
 (defun org-agenda-skip-entry-when-regexp-matches-in-subtree ()
-  "Checks if the current subtree contains match for `org-agenda-skip-regexp'.
+  "Check if the current subtree contains match for `org-agenda-skip-regexp'.
 If yes, it returns the end position of the current entry (NOT the tree),
 causing agenda commands to skip the entry but continuing the search in
 the subtree.  This is a function that can be put into
@@ -4426,7 +4425,7 @@ the documentation of `org-diary'."
   "Entry applies if date is between dates on DAYNAME, but skips SKIP-WEEKS.
 The order of the first 2 times 3 arguments depends on the variable
 `calendar-date-style' or, if that is not defined, on `european-calendar-style'.
-So for american calendars, give this as MONTH DAY YEAR, for european as
+So for American calendars, give this as MONTH DAY YEAR, for European as
 DAY MONTH YEAR, and for ISO as YEAR MONTH DAY.
 DAYNAME is a number between 0 (Sunday) and 6 (Saturday).  SKIP-WEEKS
 is any number of ISO weeks in the block period for which the item should
@@ -4820,9 +4819,9 @@ The flag is set if the currently compiled format contains a `%T'.")
   "A flag, set by `org-compile-prefix-format'.
 The flag is set if the currently compiled format contains a `%e'.")
 (defvar org-prefix-category-length nil
-  "Used by `org-compile-prefix-format' to remember the category field widh.")
+  "Used by `org-compile-prefix-format' to remember the category field width.")
 (defvar org-prefix-category-max-length nil
-  "Used by `org-compile-prefix-format' to remember the category field widh.")
+  "Used by `org-compile-prefix-format' to remember the category field width.")
 
 (defun org-format-agenda-item (extra txt &optional category tags dotime
 				     noprefix remove-re habitp)
@@ -5430,8 +5429,9 @@ Org-mode buffers visited directly by the user will not be touched."
   (org-agenda-quit))
 
 (defun org-agenda-execute (arg)
-  "Execute another agenda command, keeping same window.\\<global-map>
-So this is just a shortcut for `\\[org-agenda]', available in the agenda."
+  "Execute another agenda command, keeping same window.
+So this is just a shortcut for \\<global-map>`\\[org-agenda]', available
+in the agenda."
   (interactive "P")
   (let ((org-agenda-window-setup 'current-window))
     (org-agenda arg)))
@@ -5588,7 +5588,7 @@ to switch to narrowing."
 
 (defun org-agenda-filter-effort-form (e)
   "Return the form to compare the effort of the current line with what E says.
-E looks line \"+<2:25\"."
+E looks like \"+<2:25\"."
   (let (op)
     (setq e (substring e 1))
     (setq op (string-to-char e) e (substring e 1))
@@ -6081,7 +6081,7 @@ When called with a prefix argument, include all archive files as well."
 			       'org-agenda-type))))
 
 (defun org-agenda-next-line ()
-  "Move cursor to the next line, and show if follow-mode is active."
+  "Move cursor to the next line, and show if follow mode is active."
   (interactive)
   (call-interactively 'next-line)
   (org-agenda-do-context-action))
@@ -6094,7 +6094,7 @@ When called with a prefix argument, include all archive files as well."
   (org-agenda-do-context-action))
 
 (defun org-agenda-do-context-action ()
-  "Show outline path and, maybe, follow-mode window."
+  "Show outline path and, maybe, follow mode window."
   (let ((m (org-get-at-bol 'org-marker)))
     (if (and org-agenda-follow-mode m)
 	(org-agenda-show))
@@ -6475,8 +6475,8 @@ docstring of `org-agenda-show-1'."
 This calls the command `org-tree-to-indirect-buffer' from the original
 Org-mode buffer.
 With numerical prefix arg ARG, go up to this level and then take that tree.
-With a C-u prefix, make a separate frame for this tree (i.e. don't use the
-dedicated frame)."
+With a \\[universal-argument] prefix, make a separate frame for this tree (i.e. don't
+use the dedicated frame)."
   (interactive)
   (org-agenda-check-no-diary)
   (let* ((marker (or (org-get-at-bol 'org-marker)

lisp/org-ascii.el

@@ -26,7 +26,10 @@
 ;;
 ;;; Commentary:
 
+;;; Code:
+
 (require 'org-exp)
+
 (eval-when-compile
   (require 'cl))
 
@@ -541,7 +544,7 @@ publishing directory."
       (current-buffer))))
 
 (defun org-export-ascii-preprocess (parameters)
-  "Do extra work for ASCII export"
+  "Do extra work for ASCII export."
   ;;
   ;; Realign tables to get rid of narrowing
   (when org-export-ascii-table-widen-columns

lisp/org-bbdb.el

@@ -207,7 +207,7 @@ date year)."
 (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."
+italicized, in all other cases it is left unchanged."
   (cond
    ((eq format 'html) (format "<i>%s</i>" (or desc path)))
    ((eq format 'latex) (format "\\textit{%s}" (or desc path)))

lisp/org-beamer.el

@@ -27,8 +27,11 @@
 ;; This library implement the special treatment needed by using the
 ;; beamer class during LaTeX export.
 
+;;; Code:
+
 (require 'org)
 (require 'org-exp)
+
 (defvar org-export-latex-header)
 (defvar org-export-latex-options-plist)
 (defvar org-export-opt-plist)
@@ -47,7 +50,7 @@
   "The level that should be interpreted as a frame.
 The levels above this one will be translated into a sectioning structure.
 Setting this to 2 will allow sections, 3 will allow subsections as well.
-You can se this to 4 as well, if you at the same time set
+You can set this to 4 as well, if you at the same time set
 `org-beamer-use-parts' to make the top levels `\part'."
   :group 'org-beamer
   :type '(choice
@@ -109,7 +112,7 @@ These are just a completion help.")
   "Environments triggered by properties in Beamer export.
 These are the defaults - for user definitions, see
 `org-beamer-environments-extra'.
-\"normal\" is a special fake environment, which emite the heading as
+\"normal\" is a special fake environment, which emit the heading as
 normal text. It is needed when an environment should be surrounded
 by normal text.  Since beamer export converts nodes into environments,
 you need to have a node to end the environment.
@@ -129,7 +132,7 @@ Each entry has 4 elements:
 
 name    Name of the environment
 key     Selection key for `org-beamer-select-environment'
-open    The opening template for the environment, with the following excapes
+open    The opening template for the environment, with the following escapes
         %a   the action/overlay specification
         %A   the default action/overlay specification
         %o   the options argument of the template
@@ -182,7 +185,7 @@ close   The closing string of the environment."
 
 (defun org-beamer-select-environment ()
   "Select the environment to be used by beamer for this entry.
-While this uses (for convenince) a tag selection interface, the result
+While this uses (for convenience) a tag selection interface, the result
 of this command will be that the BEAMER_env *property* of the entry is set.
 
 In addition to this, the command will also set a tag as a visual aid, but
@@ -417,7 +420,7 @@ the value will be inserted right after the documentclass statement."
   (setq org-beamer-export-is-beamer-p nil))
 
 (defun org-beamer-after-initial-vars ()
-  "Find special setings for beamer and store them.
+  "Find special settings for beamer and store them.
 The effect is that these values will be accessible during export."
   ;; First verify that we are exporting using the beamer class
   (setq org-beamer-export-is-beamer-p
@@ -484,7 +487,7 @@ The effect is that these values will be accessible during export."
 
 (defun org-beamer-auto-fragile-frames ()
   "Mark any frames containing verbatim environments as fragile.
-This funcion will run in the final LaTeX document."
+This function will run in the final LaTeX document."
   (when org-beamer-export-is-beamer-p
     (let (opts)
       (goto-char (point-min))
@@ -512,9 +515,9 @@ This funcion will run in the final LaTeX document."
 )
 
 (defcustom org-beamer-outline-frame-options nil
-  "Outline frame options appended after \\begin{frame}.  You might
-want to put e.g. [allowframebreaks=0.9] here.  Remember to include
-square brackets."
+  "Outline frame options appended after \\begin{frame}.
+You might want to put e.g. [allowframebreaks=0.9] here.  Remember to
+include square brackets."
   :group 'org-beamer
   :type '(string :tag "Outline frame options")
 )

lisp/org-capture.el

@@ -25,7 +25,7 @@
 ;;
 ;;; Commentary:
 
-;; This file contains an alternaive implementation of the same functionality
+;; This file contains an alternative implementation of the same functionality
 ;; that is also provided by org-remember.el.  The implementation is more
 ;; streamlined, can produce more target types (e.g. plain list items or
 ;; table lines).  Also, it does not use a temporary buffer for editing
@@ -183,7 +183,7 @@ properties are:
  :table-line-pos     Specification of the location in the table where the
                      new line should be inserted.  It looks like \"II-3\"
                      which means that the new line should become the third
-                     line before the second horizontal separaor line.
+                     line before the second horizontal separator line.
 
 The template defines the text to be inserted.  Often this is an org-mode
 entry (so the first line should start with a star) that will be filed as a
@@ -312,7 +312,7 @@ The remember buffer is still current when this hook runs."
 (defvar org-capture-current-plist nil
   "Local variable holding the plist in a capture buffer.
 This is used to store the plist for use when finishing a capture process.
-Another such process might have changed the global varaible by then.")
+Another such process might have changed the global variable by then.")
 
 (defun org-capture-put (&rest stuff)
   (while stuff
@@ -327,7 +327,7 @@ Another such process might have changed the global varaible by then.")
 ;;; The minor mode
 
 (defvar org-capture-mode-map (make-sparse-keymap)
-  "Keymap for org-capture-mode, a minor mode.
+  "Keymap for `org-capture-mode', a minor mode.
 Use this map to set additional keybindings for when Org-mode is used
 for a Remember buffer.")
 
@@ -350,17 +350,18 @@ for a Remember buffer.")
 ;;;###autoload
 (defun org-capture (&optional goto keys)
   "Capture something.
-
+\\<org-capture-mode-map>
 This will let you select a template from `org-capture-templates', and then
-file new captured information.  The text is immediately inserted at the
-target location, and an indirect buffer is shown where you can edit it.
-Pressing `C-c C-c' brings you back to the previous state of Emacs,
-so that you can continue your work.
+file the newly captured information.  The text is immediately inserted
+at the target location, and an indirect buffer is shown where you can
+edit it.  Pressing \\[org-capture-finalize] brings you back to the previous state
+of Emacs, so that you can continue your work.
 
-When called interactively with a `C-u' prefix argument GOTO, don't capture
+When called interactively with a \\[universal-argument] prefix argument GOTO, don't capture
 anything, just go to the file/headline where the selected template
-stores its notes.  With a double prefix arg `C-u C-u', go to the last
-note stored.
+stores its notes.  With a double prefix argument \
+\\[universal-argument] \\[universal-argument], go to the last note
+stored.
 
 When called with a `C-0' (zero) prefix, insert a template at point.
 
@@ -654,7 +655,7 @@ already gone."
       (find-file-noselect (expand-file-name file org-directory))))
 
 (defun org-capture-steal-local-variables (buffer)
-  "Install Org-mode local variables"
+  "Install Org-mode local variables."
   (mapc (lambda (v)
 	  (ignore-errors (org-set-local (car v) (cdr v))))
 	(buffer-local-variables buffer)))
@@ -916,14 +917,14 @@ already gone."
 	  (move-marker org-capture-last-stored-marker (point)))))))
 
 (defun org-capture-narrow (beg end)
-  "Narrow, unless configuraion says not to narrow."
+  "Narrow, unless configuration says not to narrow."
   (unless (org-capture-get :unnarrowed)
     (narrow-to-region beg end)
     (goto-char beg)))
 
 (defun org-capture-empty-lines-before (&optional n)
   "Arrange for the correct number of empty lines before the insertion point.
-Point will be after the empty lines, so insertion can direcetly be done."
+Point will be after the empty lines, so insertion can directly be done."
   (setq n (or n (org-capture-get :empty-lines) 0))
   (let ((pos (point)))
     (org-back-over-empty-lines)
@@ -998,7 +999,7 @@ The user is queried for the template."
   (let* (org-select-template-temp-major-mode
 	 (entry (org-capture-select-template template-key)))
     (unless entry
-      (error "No capture emplate selected"))
+      (error "No capture template selected"))
     (org-capture-set-plist entry)
     (org-capture-set-target-location)
     (switch-to-buffer (org-capture-get :buffer))

lisp/org-clock.el

@@ -29,6 +29,8 @@
 ;; This file contains the time clocking code for Org-mode
 
 (require 'org)
+;;; Code:
+
 (eval-when-compile
   (require 'cl))
 
@@ -82,7 +84,7 @@ clocking out."
 (defcustom org-clock-in-switch-to-state nil
   "Set task to a special todo state while clocking it.
 The value should be the state to which the entry should be
-switched. If the value is a function, it must take one
+switched.  If the value is a function, it must take one
 parameter (the current TODO state of the item) and return the
 state to switch it to."
   :group 'org-clock
@@ -95,7 +97,7 @@ state to switch it to."
 (defcustom org-clock-out-switch-to-state nil
   "Set task to a special todo state after clocking out.
 The value should be the state to which the entry should be
-switched. If the value is a function, it must take one
+switched.  If the value is a function, it must take one
 parameter (the current TODO state of the item) and return the
 state to switch it to."
   :group 'org-clock
@@ -123,7 +125,7 @@ The function is called with point at the beginning of the headline."
   :type 'function)
 
 (defcustom org-clock-string-limit 0
-  "Maximum length of clock strings in the modeline. 0 means no limit."
+  "Maximum length of clock strings in the modeline.  0 means no limit."
   :group 'org-clock
   :type 'integer)
 
@@ -135,8 +137,8 @@ the clock can be resumed from that point."
   :type 'boolean)
 
 (defcustom org-clock-persist nil
-  "When non-nil, save the running clock when emacs is closed.
-The clock is resumed when emacs restarts.
+  "When non-nil, save the running clock when Emacs is closed.
+The clock is resumed when Emacs restarts.
 When this is t, both the running clock, and the entire clock
 history are saved.  When this is the symbol `clock', only the
 running clock is saved.
@@ -281,7 +283,7 @@ to add an effort property.")
   "If non-nil, user cancelled a clock; this is when leftover time started.")
 
 (defvar org-clock-effort ""
-  "Effort estimate of the currently clocking task")
+  "Effort estimate of the currently clocking task.")
 
 (defvar org-clock-total-time nil
   "Holds total time, spent previously on currently clocked item.
@@ -341,11 +343,11 @@ of a different task.")
 	org-clock-history))
 
 (defun org-clocking-buffer ()
-  "Returns clocking buffer if we are currently clocking a task or nil"
+  "Return the clocking buffer if we are currently clocking a task or nil."
   (marker-buffer org-clock-marker))
 
 (defun org-clocking-p ()
-  "Returns t when clocking a task"
+  "Return t when clocking a task."
   (not (equal (org-clocking-buffer) nil)))
 
 (defun org-clock-select-task (&optional prompt)
@@ -869,11 +871,11 @@ If `only-dangling-p' is non-nil, only ask to resolve dangling
       0)))
 
 (defun org-mac-idle-seconds ()
-  "Return the current Mac idle time in seconds"
+  "Return the current Mac idle time in seconds."
   (string-to-number (shell-command-to-string "ioreg -c IOHIDSystem | perl -ane 'if (/Idle/) {$idle=(pop @F)/1000000000; print $idle; last}'")))
 
 (defun org-x11-idle-seconds ()
-  "Return the current X11 idle time in seconds"
+  "Return the current X11 idle time in seconds."
   (/ (string-to-number (shell-command-to-string "x11idle")) 1000))
 
 (defun org-user-idle-seconds ()
@@ -917,8 +919,10 @@ so long."
 (defun org-clock-in (&optional select start-time)
   "Start the clock on the current item.
 If necessary, clock-out of the currently active clock.
-With prefix arg SELECT, offer a list of recently clocked tasks to
-clock into.  When SELECT is `C-u C-u', clock into the current task and mark
+With a prefix argument SELECT (\\[universal-argument]), offer a list of \
+recently clocked tasks to
+clock into.  When SELECT is \\[universal-argument] \\[universal-argument], \
+clock into the current task and mark
 is as the default task, a special task that will always be offered in
 the clocking selection, associated with the letter `d'."
   (interactive "P")
@@ -1442,7 +1446,7 @@ nil are excluded from the clock summation."
     (set-buffer-modified-p bmp)))
 
 (defun org-clock-sum-current-item (&optional tstart)
-  "Returns time, clocked on current item in total"
+  "Return time, clocked on current item in total."
   (save-excursion
     (save-restriction
       (org-narrow-to-subtree)
@@ -2123,7 +2127,7 @@ The details of what will be saved are regulated by the variable
 
 ;;;###autoload
 (defun org-clock-persistence-insinuate ()
-  "Set up hooks for clock persistence"
+  "Set up hooks for clock persistence."
   (add-hook 'org-mode-hook 'org-clock-load)
   (add-hook 'kill-emacs-hook 'org-clock-save))
 

lisp/org-colview-xemacs.el

@@ -184,10 +184,10 @@
 This is the compiled version of the format.")
 (make-variable-buffer-local 'org-columns-current-fmt-compiled)
 (defvar org-columns-current-widths nil
-  "Loval variable, holds the currently widths of fields.")
+  "Local variable, holds the currently widths of fields.")
 (make-variable-buffer-local 'org-columns-current-widths)
 (defvar org-columns-current-maxwidths nil
-  "Loval variable, holds the currently active maximum column widths.")
+  "Local variable, holds the currently active maximum column widths.")
 (make-variable-buffer-local 'org-columns-current-maxwidths)
 (defvar org-columns-begin-marker (make-marker)
   "Points to the position where last a column creation command was called.")
@@ -467,7 +467,7 @@ This is the compiled version of the format.")
       (org-add-hook 'post-command-hook 'org-columns-hscoll-title nil 'local))))
 
 (defun org-columns-hscoll-title ()
-  "Set the header-line-format so that it scrolls along with the table."
+  "Set the `header-line-format' so that it scrolls along with the table."
   (sit-for .0001) ; need to force a redisplay to update window-hscroll
   (when (not (= (window-hscroll) org-columns-previous-hscroll))
     (setq header-line-format
@@ -919,18 +919,18 @@ around it."
      (lambda (&rest x) (/ (apply '+ x) (float (length x))))
      (lambda (x) (- org-columns-time x))))
   "Operator <-> format,function,calc  map.
- Used to compile/uncompile columns format and completing read in
- interactive function org-columns-new.
+Used to compile/uncompile columns format and completing read in
+interactive function `org-columns-new'.
 
  operator    string used in #+COLUMNS definition describing the
 	     summary type
  format      symbol describing summary type selected interactively in
-	     org-columns-new and internally in
-	     org-columns-number-to-string and
-	     org-columns-string-to-number
+	     `org-columns-new' and internally in
+	     `org-columns-number-to-string' and
+	     `org-columns-string-to-number'
  function    called with a list of values as argument to calculate
 	     the summary value
- calc        function called on every element before summarizing. This is
+ calc        function called on every element before summarizing.  This is
 	     optional and should only be specified if needed")
 
 
@@ -1288,8 +1288,7 @@ operator     the operator if any
 format       the output format for computed results, derived from operator
 printf       a printf format for computed values
 fun          the lisp function to compute summary values, derived from operator
-calc         function to get values from base elements
-"
+calc         function to get values from base elements"
   (let ((start 0) width prop title op op-match f printf fun calc)
     (setq org-columns-current-fmt-compiled nil)
     (while (string-match
@@ -1683,7 +1682,7 @@ This will add overlays to the date lines, to show the summary for each day."
 		  (org-columns-compute (car fm)))))))))))
 
 (defun org-format-time-period (interval)
-  "Convert time in fractional days to days/hours/minutes/seconds"
+  "Convert time in fractional days to days/hours/minutes/seconds."
   (if (numberp interval)
     (let* ((days (floor interval))
 	   (frac-hours (* 24 (- interval days)))

lisp/org-colview.el

@@ -301,7 +301,7 @@ for the duration of the command.")
     (org-add-hook 'post-command-hook 'org-columns-hscoll-title nil 'local)))
 
 (defun org-columns-hscoll-title ()
-  "Set the header-line-format so that it scrolls along with the table."
+  "Set the `header-line-format' so that it scrolls along with the table."
   (sit-for .0001) ; need to force a redisplay to update window-hscroll
   (when (not (= (window-hscroll) org-columns-previous-hscroll))
     (setq header-line-format
@@ -749,17 +749,17 @@ around it."
      (lambda (x) (- org-columns-time x))))
   "Operator <-> format,function,calc  map.
 Used to compile/uncompile columns format and completing read in
-interactive function org-columns-new.
+interactive function `org-columns-new'.
 
 operator    string used in #+COLUMNS definition describing the
 	    summary type
 format      symbol describing summary type selected interactively in
-	    org-columns-new and internally in
-	    org-columns-number-to-string and
-	    org-columns-string-to-number
+	    `org-columns-new' and internally in
+	    `org-columns-number-to-string' and
+	    `org-columns-string-to-number'
 function    called with a list of values as argument to calculate
 	    the summary value
-calc        function called on every element before summarizing. This is
+calc        function called on every element before summarizing.  This is
 	    optional and should only be specified if needed")
 
 (defun org-columns-new (&optional prop title width op fmt fun &rest rest)
@@ -1112,8 +1112,7 @@ operator     the operator if any
 format       the output format for computed results, derived from operator
 printf       a printf format for computed values
 fun          the lisp function to compute summary values, derived from operator
-calc         function to get values from base elements
-"
+calc         function to get values from base elements"
   (let ((start 0) width prop title op op-match f printf fun calc)
     (setq org-columns-current-fmt-compiled nil)
     (while (string-match
@@ -1482,7 +1481,7 @@ This will add overlays to the date lines, to show the summary for each day."
 		  (org-columns-compute (car fm)))))))))))
 
 (defun org-format-time-period (interval)
-  "Convert time in fractional days to days/hours/minutes/seconds"
+  "Convert time in fractional days to days/hours/minutes/seconds."
   (if (numberp interval)
     (let* ((days (floor interval))
 	   (frac-hours (* 24 (- interval days)))

lisp/org-compat.el

@@ -122,7 +122,7 @@ any other entries, and any resulting duplicates will be removed entirely."
     ([mouse-3] . [button3])
     ([C-mouse-4] . [(control mouse-4)])
     ([C-mouse-5] . [(control mouse-5)]))
-  "Translation alist for a couple of keys")
+  "Translation alist for a couple of keys.")
 
 ;; Overlay compatibility functions
 (defun org-detach-overlay (ovl)
@@ -184,7 +184,7 @@ that will be added to PLIST.  Returns the string that was modified."
   "Fit WINDOW to the buffer, but only if it is not a side-by-side window.
 WINDOW defaults to the selected window.  MAX-HEIGHT and MIN-HEIGHT are
 passed through to `fit-window-to-buffer'.  If SHRINK-ONLY is set, call
-`shrink-window-if-larger-than-buffer' instead, the hight limit are
+`shrink-window-if-larger-than-buffer' instead, the height limit is
 ignored in this case."
   (cond ((if (fboundp 'window-full-width-p)
 	     (not (window-full-width-p window))
@@ -267,7 +267,7 @@ Works on both Emacs and XEmacs."
     (move-to-column column force)))
 
 (defun org-get-x-clipboard-compat (value)
-  "Get the clipboard value on XEmacs or Emacs 21"
+  "Get the clipboard value on XEmacs or Emacs 21."
   (cond ((featurep 'xemacs)
 	 (org-no-warnings (get-selection-no-error value)))
 	((fboundp 'x-get-selection)

lisp/org-crypt.el

@@ -67,6 +67,8 @@
 
 (require 'org)
 
+;;; Code:
+
 (declare-function epg-decrypt-string "epg" (context cipher))
 (declare-function epg-list-keys "epg" (context &optional name mode))
 (declare-function epg-make-context "epg"
@@ -81,18 +83,19 @@
   :tag "Org Crypt" :group 'org)
 
 (defcustom org-crypt-tag-matcher "crypt"
-  "The tag matcher used to find headings whose contents should be
-encrypted.  See the \"Match syntax\" section of the org manual
-for more details."
+  "The tag matcher used to find headings whose contents should be encrypted.
+
+See the \"Match syntax\" section of the org manual for more details."
   :type 'string :group 'org-crypt)
 
 (defcustom org-crypt-key nil
-  "The default key to use when encrypting the contents of a
-heading.  This can also be overridden in the CRYPTKEY property."
+  "The default key to use when encrypting the contents of a heading.
+
+This setting can also be overridden in the CRYPTKEY property."
   :type 'string :group 'org-crypt)
 
 (defun org-crypt-key-for-heading ()
-  "Returns the encryption key for the current heading."
+  "Return the encryption key for the current heading."
   (save-excursion
     (org-back-to-heading t)
     (or (org-entry-get nil "CRYPTKEY" 'selective)
@@ -169,8 +172,7 @@ heading.  This can also be overridden in the CRYPTKEY property."
    (cdr (org-make-tags-matcher org-crypt-tag-matcher))))
 
 (defun org-crypt-use-before-save-magic ()
-  "Adds a hook that will automatically encrypt entries before a
-file is saved to disk."
+  "Add a hook to automatically encrypt entries before a file is saved to disk."
   (add-hook
    'org-mode-hook
    (lambda () (add-hook 'before-save-hook 'org-encrypt-entries nil t))))

lisp/org-ctags.el

@@ -134,7 +134,10 @@
 ;;       (message "-- rebuilding tags tables...")
 ;;       (mapc 'org-create-tags tags-table-list))
 
+;;; Code:
+
 (eval-when-compile (require 'cl))
+
 (require 'org)
 
 (defgroup org-ctags nil
@@ -146,8 +149,8 @@
   "Activate ctags support in org mode?")
 
 (defvar org-ctags-tag-regexp "/<<([^>]+)>>/\\1/d,definition/"
-  "Regexp expression used by ctags external program, that matches
-tag destinations in org-mode files.
+  "Regexp expression used by ctags external program.
+The regexp matches tag destinations in org-mode files.
 Format is: /REGEXP/TAGNAME/FLAGS,TAGTYPE/
 See the ctags documentation for more information.")
 
@@ -164,8 +167,7 @@ See the ctags documentation for more information.")
   '(org-ctags-find-tag
     org-ctags-ask-rebuild-tags-file-then-find-tag
     org-ctags-ask-append-topic)
-  "List of functions to be prepended to ORG-OPEN-LINK-FUNCTIONS when
-ORG-CTAGS is active."
+  "List of functions to be prepended to ORG-OPEN-LINK-FUNCTIONS when ORG-CTAGS is active."
   :group 'org-ctags
   :type 'hook
   :options '(org-ctags-find-tag
@@ -179,8 +181,8 @@ ORG-CTAGS is active."
 
 
 (defvar org-ctags-tag-list nil
-  "List of all tags in the active TAGS file. Created as a local
-variable in each buffer.")
+  "List of all tags in the active TAGS file.
+Created as a local variable in each buffer.")
 
 (defcustom org-ctags-new-topic-template
   "* <<%t>>\n\n\n\n\n\n"
@@ -218,12 +220,12 @@ The following patterns are replaced in the string:
     (add-hook 'org-open-link-functions fn t)))
 
 
-;;; General utility functions. ===============================================
+;;; General utility functions.  ===============================================
 ;; These work outside org-ctags mode.
 
 (defun org-ctags-get-filename-for-tag (tag)
-  "TAG is a string. Search the active TAGS file for a matching tag,
-and if found, return a list containing the filename, line number, and
+  "TAG is a string.  Search the active TAGS file for a matching tag.
+If the tag is found, return a list containing the filename, line number, and
 buffer position where the tag is found."
   (interactive "sTag: ")
   (unless tags-file-name
@@ -279,8 +281,8 @@ Return the list."
 
 
 (defun org-ctags-open-file (name &optional title)
-  "Visit or create a file called `NAME.org', and insert a new topic titled
-NAME (or TITLE if supplied)."
+  "Visit or create a file called `NAME.org', and insert a new topic.
+The new topic will be titled NAME (or TITLE if supplied)."
   (interactive "sFile name: ")
   (let ((filename (substitute-in-file-name (expand-file-name name))))
     (condition-case v
@@ -349,7 +351,7 @@ If there is no plausible default, return nil."
 
 (defun org-ctags-find-tag (name)
   "This function is intended to be used in ORG-OPEN-LINK-FUNCTIONS.
-Look for a tag called `NAME' in the current TAGS table. If it is found,
+Look for a tag called `NAME' in the current TAGS table.  If it is found,
 visit the file and location where the tag is found."
   (interactive "sTag: ")
   (let ((old-buf (current-buffer))
@@ -368,11 +370,11 @@ visit the file and location where the tag is found."
 
 (defun org-ctags-visit-buffer-or-file (name &optional create)
   "This function is intended to be used in ORG-OPEN-LINK-FUNCTIONS.
-Visit buffer named `NAME.org'. If there is no such buffer, visit the file
-with the same name if it exists. If the file does not exist, then behaviour
+Visit buffer named `NAME.org'.  If there is no such buffer, visit the file
+with the same name if it exists.  If the file does not exist, then behavior
 depends on the value of CREATE.
 
-If CREATE is nil (default), then return nil. Do not create a new file.
+If CREATE is nil (default), then return nil.  Do not create a new file.
 If CREATE is t, create the new file and visit it.
 If CREATE is the symbol `ask', then ask the user if they wish to create
 the new file."
@@ -453,7 +455,7 @@ Wrapper for org-ctags-rebuild-tags-file-then-find-tag."
   (if (and (buffer-file-name)
              (y-or-n-p
               (format
-               "Tag `%s' not found. Rebuild table `%s/TAGS' and look again?"
+               "Tag `%s' not found.  Rebuild table `%s/TAGS' and look again?"
                name
                (file-name-directory (buffer-file-name)))))
     (org-ctags-rebuild-tags-file-then-find-tag name)
@@ -463,7 +465,7 @@ Wrapper for org-ctags-rebuild-tags-file-then-find-tag."
 (defun org-ctags-fail-silently (name)
   "This function is intended to be used in ORG-OPEN-LINK-FUNCTIONS.
 Put as the last function in the list if you want to prevent org's default
-behaviour of free text search."
+behavior of free text search."
   t)
 
 
@@ -471,14 +473,14 @@ behaviour of free text search."
 
 
 (defun org-ctags-create-tags (&optional directory-name)
-  "(Re)create tags file in the directory of the active buffer,
-containing tag definitions for all the files in the directory and its
-subdirectories which are recognised by ctags. This will include
-files ending in `.org' as well as most other source files (.C,
-.H, .EL, .LISP, etc).  All the resulting tags end up in one file,
-called TAGS, located in the directory.  This function
-may take several seconds to finish if the directory or its
-subdirectories contain large numbers of taggable files."
+  "(Re)create tags file in the directory of the active buffer.
+The file will contain tag definitions for all the files in the
+directory and its subdirectories which are recognized by ctags.
+This will include files ending in `.org' as well as most other
+source files (.C, .H, .EL, .LISP, etc).  All the resulting tags
+end up in one file, called TAGS, located in the directory.  This
+function may take several seconds to finish if the directory or
+its subdirectories contain large numbers of taggable files."
   (interactive)
   (assert (buffer-file-name))
   (let ((dir-name (or directory-name
@@ -509,8 +511,8 @@ subdirectories contain large numbers of taggable files."
   "History of tags visited by org-ctags-find-tag-interactive.")
 
 (defun org-ctags-find-tag-interactive ()
-  "Prompt for the name of a tag, with autocompletion, then visit
-the named tag. Uses ido-mode if available.
+  "Prompt for the name of a tag, with autocompletion, then visit the named tag.
+Uses `ido-mode' if available.
 If the user enters a string that does not match an existing tag, create
 a new topic."
   (interactive)