* Confusion about tags-todo matches and TODO keywords
@ 2010-06-21 23:39 Bernt Hansen
2010-06-22 8:51 ` Carsten Dominik
0 siblings, 1 reply; 4+ messages in thread
From: Bernt Hansen @ 2010-06-21 23:39 UTC (permalink / raw)
To: Carsten Dominik; +Cc: emacs-orgmode, jeff stern
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
^ permalink raw reply [flat|nested] 4+ messages in thread* Re: Confusion about tags-todo matches and TODO keywords 2010-06-21 23:39 Confusion about tags-todo matches and TODO keywords Bernt Hansen @ 2010-06-22 8:51 ` Carsten Dominik 2010-06-22 11:24 ` Bernt Hansen 0 siblings, 1 reply; 4+ messages in thread From: Carsten Dominik @ 2010-06-22 8:51 UTC (permalink / raw) To: Bernt Hansen; +Cc: Carsten Dominik, emacs-orgmode, jeff stern 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 ^ permalink raw reply related [flat|nested] 4+ messages in thread
* Re: Confusion about tags-todo matches and TODO keywords 2010-06-22 8:51 ` Carsten Dominik @ 2010-06-22 11:24 ` Bernt Hansen 2010-06-22 12:47 ` Carsten Dominik 0 siblings, 1 reply; 4+ messages in thread From: Bernt Hansen @ 2010-06-22 11:24 UTC (permalink / raw) To: Carsten Dominik; +Cc: Carsten Dominik, emacs-orgmode, jeff stern 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 ^ permalink raw reply related [flat|nested] 4+ messages in thread
* Re: Confusion about tags-todo matches and TODO keywords 2010-06-22 11:24 ` Bernt Hansen @ 2010-06-22 12:47 ` Carsten Dominik 0 siblings, 0 replies; 4+ messages in thread From: Carsten Dominik @ 2010-06-22 12:47 UTC (permalink / raw) To: Bernt Hansen; +Cc: Carsten Dominik, emacs-orgmode, jeff stern 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 ^ permalink raw reply [flat|nested] 4+ messages in thread
end of thread, other threads:[~2010-06-22 13:14 UTC | newest] Thread overview: 4+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2010-06-21 23:39 Confusion about tags-todo matches and TODO keywords Bernt Hansen 2010-06-22 8:51 ` Carsten Dominik 2010-06-22 11:24 ` Bernt Hansen 2010-06-22 12:47 ` Carsten Dominik
Code repositories for project(s) associated with this public inbox https://git.savannah.gnu.org/cgit/emacs/org-mode.git This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).