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

[Bernt Hansen]

Carsten Dominik <address@hidden> 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