Hi Bernt,
On Jun 22, 2010, at 1:39 AM, Bernt Hansen wrote:
Hi Carsten,
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 :)
Indeed, "TODO" is used in two different ways in the documentation.
When I talk about the TODO sparse tree, about the global TODO list (C-
c a t), and the tags-TODO match,
this means not-done TODO items.
However, the phrase TODO keyword certainly includes DONE states. I
think we should keep it like this, and I will add the not-done in a
couple of places where it makes sense.
Here is a patch I am proposing for this. Please take a look if
this would be sufficient to clarify the issue.
Changes at master
Modified doc/org.texi
diff --git a/doc/org.texi b/doc/org.texi
index 17615e0..6697b9f 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -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...@key{ret}
@item s...@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
Thanks,
Bernt
- Carsten
_______________________________________________
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
