Confusion about tags-todo matches and TODO keywords

Confusion about tags-todo matches and TODO keywords

[Bernt Hansen]

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 :)

Thanks,
Bernt

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
+@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



>
> Thanks,
> Bernt

- Carsten

Re: Confusion about tags-todo matches and TODO keywords

[Bernt Hansen]

Carsten Dominik <carsten.dominik@gmail.com> writes:

> Hi Bernt,
>
> On Jun 22, 2010, at 1:39 AM, Bernt Hansen wrote:
>
>> 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.
>

Hi Carsten.

The patch you sent was whitespace damaged so I couldn't apply it to my
repository.  Reading through the changes I think this helps a lot to
clarify things.

The only additional change I can think of that would be useful would be
to explicitly state that using the agenda tags-todo or a tags search
with /! will only match not-done TODO keywords.

Maybe something like this?

(This adds one sentence before "Examples:" and reformats the paragraph)


--8<---------------cut here---------------start------------->8---
diff --git a/doc/org.texi b/doc/org.texi
index 17615e0..550394d 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -7009,12 +7009,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
--8<---------------cut here---------------end--------------->8---


Thanks,
Bernt

Re: Confusion about tags-todo matches and TODO keywords

[Carsten Dominik]

Applied, thanks!

- Carsten

On Jun 22, 2010, at 1:24 PM, Bernt Hansen wrote:

> Carsten Dominik <carsten.dominik@gmail.com> writes:
>
>> Hi Bernt,
>>
>> On Jun 22, 2010, at 1:39 AM, Bernt Hansen wrote:
>>
>>> 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.
>>
>
> Hi Carsten.
>
> The patch you sent was whitespace damaged so I couldn't apply it to my
> repository.  Reading through the changes I think this helps a lot to
> clarify things.
>
> The only additional change I can think of that would be useful would  
> be
> to explicitly state that using the agenda tags-todo or a tags search
> with /! will only match not-done TODO keywords.
>
> Maybe something like this?
>
> (This adds one sentence before "Examples:" and reformats the  
> paragraph)
>
>
> --8<---------------cut here---------------start------------->8---
> diff --git a/doc/org.texi b/doc/org.texi
> index 17615e0..550394d 100644
> --- a/doc/org.texi
> +++ b/doc/org.texi
> @@ -7009,12 +7009,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
> --8<---------------cut here---------------end--------------->8---
>
>
> Thanks,
> Bernt
>

- Carsten