From mboxrd@z Thu Jan 1 00:00:00 1970 From: Carsten Dominik Subject: Re: [PATCH] Correct some docstrings Date: Thu, 15 Jul 2010 19:06:12 +0200 Message-ID: References: Mime-Version: 1.0 (Apple Message framework v936) Content-Type: text/plain; charset=US-ASCII; format=flowed; delsp=yes Content-Transfer-Encoding: 7bit Return-path: Received: from [140.186.70.92] (port=38810 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1OZRtO-0002d6-2s for emacs-orgmode@gnu.org; Thu, 15 Jul 2010 13:06:42 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.69) (envelope-from ) id 1OZRtK-0003su-1U for emacs-orgmode@gnu.org; Thu, 15 Jul 2010 13:06:37 -0400 Received: from mail-ew0-f41.google.com ([209.85.215.41]:36597) by eggs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1OZRtJ-0003sU-Dh for emacs-orgmode@gnu.org; Thu, 15 Jul 2010 13:06:33 -0400 Received: by ewy28 with SMTP id 28so351948ewy.0 for ; Thu, 15 Jul 2010 10:06:28 -0700 (PDT) In-Reply-To: List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org To: Philip Rooke Cc: emacs-orgmode@gnu.org 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.\\ > -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 \\`\\[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 "%s" (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. > - > +\\ > 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