summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorCarsten Dominik <carsten.dominik@gmail.com>2010-06-22 08:26:24 +0200
committerCarsten Dominik <carsten.dominik@gmail.com>2010-06-22 14:47:37 +0200
commit2e73ce217779330d446a908627ec19875dc3fd05 (patch)
tree79d3ff1b6cf5fb1e580c7e45a9c22440fb2d0d76
parenteade8e6fa3450e2eddcd8b4491f1f40fd3ba1ac9 (diff)
downloadorg-mode-2e73ce217779330d446a908627ec19875dc3fd05.tar.gz
Clarify that TODO matches only match not-DONE states by default
Bernt Hansen writes: > I was talking to Jeff Stern about tags todo matching offlist and we > think the documentation for tags-todo matching can probably be improved. > > The description of C-c a M at > http://orgmode.org/manual/Matching-tags-and-properties.html > states > > C-c a M > > Like C-c a m, but only select headlines that are also TODO items and > force checking subitems (see variable > org-tags-match-list-sublevels). To exclude scheduled/deadline items, > see the variable org-agenda-tags-todo-honor-ignore-options. Matching > specific TODO keywords together with a tags match is also possible, > see Tag searches. > > When I read this I think TODO items is any todo keyword but this isn't > the case. It is only non-done TODO state keywords. This makes > tags-todo matching not work for finding tasks to archive (normally > DONE | CANCELLED keywords in my setup) > > Should we explicitly state that 'headlines that are also TODO items' > does not match DONE state keywords? Or alternatively should TODO items > and DONE items be separate (and explicitly defined) in the documentation > -- like org-todo-keywords and org-done-keywords? > > I still think 'TODO keyword' matches any todo keyword defined in > org-todo-keywords and maybe I need to be re-educated :) Bernt is right, and this patch tries to clarify the issue.
-rw-r--r--doc/org.texi79
-rw-r--r--lisp/org-agenda.el2
2 files changed, 42 insertions, 39 deletions
diff --git a/doc/org.texi b/doc/org.texi
index 17615e0..e233e05 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -1232,7 +1232,7 @@ as bullets.
@emph{Ordered} list items start with a numeral followed by either a period or
a right parenthesis, such as @samp{1.} or @samp{1)}. If you want a list to
start a different value (e.g. 20), start the text of the item with
-@code{[@@start:20]}.
+@code{[@@start:20]}.
@item
@emph{Description} list items are unordered list items, and contain the
separator @samp{ :: } to separate the description @emph{term} from the
@@ -3293,20 +3293,21 @@ with @code{shift-selection-mode}. See also the variable
@itemx C-c / t
@vindex org-todo-keywords
View TODO items in a @emph{sparse tree} (@pxref{Sparse trees}). Folds the
-entire buffer, but shows all TODO items and the headings hierarchy above
-them. With a prefix argument (or by using @kbd{C-c / T}), search for a
-specific TODO. You will be prompted for the keyword, and you can also give a
-list of keywords like @code{KWD1|KWD2|...} to list entries that match any one
-of these keywords. With numeric prefix argument N, show the tree for the Nth
-keyword in the variable @code{org-todo-keywords}. With two prefix arguments,
-find all TODO and DONE entries.
+entire buffer, but shows all TODO items (with not-DONE state) and the
+headings hierarchy above them. With a prefix argument (or by using @kbd{C-c
+/ T}), search for a specific TODO. You will be prompted for the keyword, and
+you can also give a list of keywords like @code{KWD1|KWD2|...} to list
+entries that match any one of these keywords. With numeric prefix argument
+N, show the tree for the Nth keyword in the variable
+@code{org-todo-keywords}. With two prefix arguments, find all TODO states,
+both un-done and done.
@kindex C-c a t
@item C-c a t
-Show the global TODO list. Collects the TODO items from all agenda
-files (@pxref{Agenda Views}) into a single buffer. The new buffer will
-be in @code{agenda-mode}, which provides commands to examine and
-manipulate the TODO entries from the new buffer (@pxref{Agenda
-commands}). @xref{Global TODO list}, for more information.
+Show the global TODO list. Collects the TODO items (with not-DONE states)
+from all agenda files (@pxref{Agenda Views}) into a single buffer. The new
+buffer will be in @code{agenda-mode}, which provides commands to examine and
+manipulate the TODO entries from the new buffer (@pxref{Agenda commands}).
+@xref{Global TODO list}, for more information.
@kindex S-M-@key{RET}
@item S-M-@key{RET}
Insert a new TODO entry below the current one.
@@ -6816,20 +6817,20 @@ collected into a single place.
@table @kbd
@kindex C-c a t
@item C-c a t
-Show the global TODO list. This collects the TODO items from all
-agenda files (@pxref{Agenda Views}) into a single buffer. The buffer is in
-@code{agenda-mode}, so there are commands to examine and manipulate
-the TODO entries directly from that buffer (@pxref{Agenda commands}).
+Show the global TODO list. This collects the TODO items from all agenda
+files (@pxref{Agenda Views}) into a single buffer. By default, this lists
+items with a state the is not a DONE state. The buffer is in
+@code{agenda-mode}, so there are commands to examine and manipulate the TODO
+entries directly from that buffer (@pxref{Agenda commands}).
@kindex C-c a T
@item C-c a T
@cindex TODO keyword matching
@vindex org-todo-keywords
-Like the above, but allows selection of a specific TODO keyword. You
-can also do this by specifying a prefix argument to @kbd{C-c a t}. With
-a @kbd{C-u} prefix you are prompted for a keyword, and you may also
-specify several keywords by separating them with @samp{|} as the boolean OR
-operator. With a numeric prefix, the nth keyword in
-@code{org-todo-keywords} is selected.
+Like the above, but allows selection of a specific TODO keyword. You can
+also do this by specifying a prefix argument to @kbd{C-c a t}. You are
+prompted for a keyword, and you may also specify several keywords by
+separating them with @samp{|} as the boolean OR operator. With a numeric
+prefix, the nth keyword in @code{org-todo-keywords} is selected.
@kindex r
The @kbd{r} key in the agenda buffer regenerates it, and you can give
a prefix argument to this command to change the selected TODO keyword,
@@ -6891,11 +6892,12 @@ define a custom command for it (@pxref{Agenda dispatcher}).
@item C-c a M
@vindex org-tags-match-list-sublevels
@vindex org-agenda-tags-todo-honor-ignore-options
-Like @kbd{C-c a m}, but only select headlines that are also TODO items and
-force checking subitems (see variable @code{org-tags-match-list-sublevels}).
-To exclude scheduled/deadline items, see the variable
-@code{org-agenda-tags-todo-honor-ignore-options}. Matching specific TODO
-keywords together with a tags match is also possible, see @ref{Tag searches}.
+Like @kbd{C-c a m}, but only select headlines that are also TODO items in a
+not-DONE state and force checking subitems (see variable
+@code{org-tags-match-list-sublevels}). To exclude scheduled/deadline items,
+see the variable @code{org-agenda-tags-todo-honor-ignore-options}. Matching
+specific TODO keywords together with a tags match is also possible, see
+@ref{Tag searches}.
@end table
The commands available in the tags list are described in @ref{Agenda
@@ -7009,12 +7011,13 @@ different way to test TODO states in a search. For this, terminate the
tags/property part of the search string (which may include several terms
connected with @samp{|}) with a @samp{/} and then specify a Boolean
expression just for TODO keywords. The syntax is then similar to that for
-tags, but should be applied with care: for example, a positive
-selection on several TODO keywords cannot meaningfully be combined with
-boolean AND. However, @emph{negative selection} combined with AND can be
-meaningful. To make sure that only lines are checked that actually have any
-TODO keyword (resulting in a speed-up), use @kbd{C-c a M}, or equivalently
-start the TODO part after the slash with @samp{!}. Examples:
+tags, but should be applied with care: for example, a positive selection on
+several TODO keywords cannot meaningfully be combined with boolean AND.
+However, @emph{negative selection} combined with AND can be meaningful. To
+make sure that only lines are checked that actually have any TODO keyword
+(resulting in a speed-up), use @kbd{C-c a M}, or equivalently start the TODO
+part after the slash with @samp{!}. Using @kbd{C-c a M} or @samp{/!} will
+not match TODO keywords in a DONE state. Examples:
@table @samp
@item work/WAITING
@@ -8258,7 +8261,7 @@ summarizes the markup rules used in an Org-mode buffer.
* Images and tables:: Tables and Images will be included
* Literal examples:: Source code examples with special formatting
* Include files:: Include additional files into a document
-* Index entries::
+* Index entries:: Making an index
* Macro replacement:: Use macros to create complex output
* Embedded LaTeX:: LaTeX can be freely used inside Org documents
@end menu
@@ -8652,7 +8655,7 @@ the contains an exclamation mark will create a sub item. See @ref{Generating
an index} for more information.
@example
-* Curriculum Vitae
+* Curriculum Vitae
#+INDEX: CV
#+INDEX: Application!CV
@end example
@@ -10649,7 +10652,7 @@ file is part of any project in @code{org-publish-project-alist}.
@subsection Generating a sitemap
@cindex sitemap, of published pages
-The following properties may be used to control publishing of
+The following properties may be used to control publishing of
a map of files for a given project.
@multitable @columnfractions 0.35 0.65
@@ -12625,7 +12628,7 @@ Emacs about it:
@end lisp
Org-mode has commands to put files for @i{MobileOrg} into that directory,
-and to read captured notes from there.
+and to read captured notes from there.
@node Pushing to MobileOrg, Pulling from MobileOrg, Setting up the staging area, MobileOrg
@section Pushing to MobileOrg
diff --git a/lisp/org-agenda.el b/lisp/org-agenda.el
index 93334b6..dc9abce 100644
--- a/lisp/org-agenda.el
+++ b/lisp/org-agenda.el
@@ -3621,7 +3621,7 @@ in `org-agenda-text-search-extra-files'."
;;;###autoload
(defun org-todo-list (arg)
- "Show all TODO entries from all agenda file in a single list.
+ "Show all (not done) TODO entries from all agenda file in a single list.
The prefix arg can be used to select a specific TODO keyword and limit
the list to these. When using \\[universal-argument], you will be prompted
for a keyword. A numeric prefix directly selects the Nth keyword in