Re: Question on org-agenda-custom-commands tags-todo match syntax

[Kyle Meyer <kyle@kyleam.com>]

Niall Dooley <dooleyn@gmail.com> writes:

> (setq org-agenda-custom-commands
> '(("p" "List Non-done projects"
> tags-todo "-CANCELLED+PROJECT/!+TODO")))
>
> My understanding is that in the tags-todo match that entries to the left of
> the "/" are the tags, those to the right are the todo keywords and that you
> use a "+" to indicate a condition should be satisfied and a "-" when it
> should
> not be satisfied. Is this correct?

That sounds right, though I often forget the details of the match syntax
and have to look it up.  It’s described at

   (info "(org)Matching tags and properties")

The "/" syntax you refer to is talked about at the very end of that
page.

> So in the above snippet the search matches headlines with the tag :PROJECT:
> and not :CANCELLED: and a todo keyword of TODO. With this I have the
> following
> questions which I would appreciate if someone could answer.
>
> Is the "+" on the right hand side before the TODO strictly necessary? I've
> seen snippets which have it and others which do not. Perhaps it is only
> necessary between multiple todo keywords on the right hand side?

AFAIU there’s no reason to distinguish between the behavior of "+" and
"-" on the left and right of "/"; they are the same.  The "/" let’s you
avoid the more verbose TODO="BLAH" form.

At any rate, the "+" isn’t strictly necessary, while "-" is.  If you
have multiple items and you use "+", though, "&" can be dropped.
Combining values with "+" isn’t useful on the RHS of "/", however,
because a TODO keyword can have only one state (i.e., it can’t be "TODO"
and "WAITING").

> What is the significance of the "!" on the right hand side? Should it always
> be present? Again, I've seen snippets with it present and others with it
> absent though it is present more often than not. Would it ever appear on
> the left
> hand side?

From the info page I linked to above:

  Using ‘C-c a M’ or ‘/!’ will not match TODO keywords in a DONE state.

Hope that helps.

-- 
Kyle