[Orgmode] Re: Confusion about tags-todo matches and TODO keywords

[Carsten Dominik]

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
address@hidden  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}).
address@hidden TODO list}, for more information.
 @kindex address@hidden
 @item address@hidden
 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
address@hidden, 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
address@hidden, 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
address@hidden 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
address@hidden  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
address@hidden).  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
address@hidden searches}.
 @end table

 The commands available in the tags list are described in @ref{Agenda



> Thanks,
> Bernt

- Carsten