Re: [PATCH] Correct some docstrings

[Carsten Dominik <carsten.dominik@gmail.com>]

On Jul 15, 2010, at 5:26 PM, Philip Rooke wrote:

> 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

Awesome, thanks!

- Carsten

>
> -- 
>
> lisp/org-agenda.el         |   71 ++++++++++++++++++++ 
> +----------------------
> lisp/org-ascii.el          |    5 ++-
> lisp/org-bbdb.el           |    2 +-
> lisp/org-beamer.el         |   21 +++++++-----
> lisp/org-capture.el        |   33 ++++++++++----------
> lisp/org-clock.el          |   32 +++++++++++--------
> lisp/org-colview-xemacs.el |   23 +++++++-------
> lisp/org-colview.el        |   17 +++++-----
> lisp/org-compat.el         |    6 ++--
> lisp/org-crypt.el          |   18 ++++++-----
> lisp/org-ctags.el          |   56 ++++++++++++++++++----------------
> 11 files changed, 148 insertions(+), 136 deletions(-)
>
> diff --git a/lisp/org-agenda.el b/lisp/org-agenda.el
> index 191ee52..1134558 100644
> --- a/lisp/org-agenda.el
> +++ b/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
> @@ -3773,7 +3772,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
> @@ -3785,7 +3784,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."
> @@ -3796,7 +3795,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
> @@ -4425,7 +4424,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
> @@ -4819,9 +4818,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)
> @@ -5429,8 +5428,8 @@ 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)))
> @@ -5587,7 +5586,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))
> @@ -6080,7 +6079,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))
> @@ -6093,7 +6092,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))
> @@ -6474,7 +6473,7 @@ 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
> +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)
> diff --git a/lisp/org-ascii.el b/lisp/org-ascii.el
> index fd8ed6f..2409178 100644
> --- a/lisp/org-ascii.el
> +++ b/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
> diff --git a/lisp/org-bbdb.el b/lisp/org-bbdb.el
> index 13b0913..7470912 100644
> --- a/lisp/org-bbdb.el
> +++ b/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)))
> diff --git a/lisp/org-beamer.el b/lisp/org-beamer.el
> index 5afc4ee..e51a81b 100644
> --- a/lisp/org-beamer.el
> +++ b/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")
> )
> diff --git a/lisp/org-capture.el b/lisp/org-capture.el
> index 0f3a29b..afb56ba 100644
> --- a/lisp/org-capture.el
> +++ b/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))
> diff --git a/lisp/org-clock.el b/lisp/org-clock.el
> index 6bd1d39..682348a 100644
> --- a/lisp/org-clock.el
> +++ b/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))
>
> diff --git a/lisp/org-colview-xemacs.el b/lisp/org-colview-xemacs.el
> index 152d9fe..07549ce 100644
> --- a/lisp/org-colview-xemacs.el
> +++ b/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)))
> diff --git a/lisp/org-colview.el b/lisp/org-colview.el
> index c820be0..78b2193 100644
> --- a/lisp/org-colview.el
> +++ b/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)))
> diff --git a/lisp/org-compat.el b/lisp/org-compat.el
> index 573b9ff..18a356a 100644
> --- a/lisp/org-compat.el
> +++ b/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)
> diff --git a/lisp/org-crypt.el b/lisp/org-crypt.el
> index 6ffd7dc..eb6cafe 100644
> --- a/lisp/org-crypt.el
> +++ b/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 that will 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))))
> diff --git a/lisp/org-ctags.el b/lisp/org-ctags.el
> index 35f432f..000f5b1 100644
> --- a/lisp/org-ctags.el
> +++ b/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)
>
> _______________________________________________
> Emacs-orgmode mailing list
> Please use `Reply All' to send replies to the list.
> Emacs-orgmode@gnu.org
> http://lists.gnu.org/mailman/listinfo/emacs-orgmode

- Carsten