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

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

[Niall Dooley]

[-- Attachment #1: Type: text/plain, Size: 1196 bytes --]

Firstly, I've searched online and even posted to both the emacs and orgmode
subreddits but to no avail.

Consider the following snippet:

(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?

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?

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?

Thank you.

[-- Attachment #2: Type: text/html, Size: 1657 bytes --]

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

[Kyle Meyer]

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