From mboxrd@z Thu Jan 1 00:00:00 1970 From: Carsten Dominik Subject: Re: Confusion about tags-todo matches and TODO keywords Date: Tue, 22 Jun 2010 10:51:22 +0200 Message-ID: <9485A6F0-9345-4A44-BA8B-0751E6060991@gmail.com> References: <87fx0ggdl1.fsf@gollum.intra.norang.ca> Mime-Version: 1.0 (Apple Message framework v936) Content-Type: text/plain; charset=US-ASCII; format=flowed; delsp=yes Content-Transfer-Encoding: 7bit Return-path: Received: from [140.186.70.92] (port=35007 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1OQzQA-0007d3-Rb for emacs-orgmode@gnu.org; Tue, 22 Jun 2010 05:05:33 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.69) (envelope-from ) id 1OQzCZ-0001Zy-FC for emacs-orgmode@gnu.org; Tue, 22 Jun 2010 04:51:28 -0400 Received: from mail-wy0-f169.google.com ([74.125.82.169]:53365) by eggs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1OQzCZ-0001Zr-8S for emacs-orgmode@gnu.org; Tue, 22 Jun 2010 04:51:27 -0400 Received: by wyf28 with SMTP id 28so3549629wyf.0 for ; Tue, 22 Jun 2010 01:51:26 -0700 (PDT) In-Reply-To: <87fx0ggdl1.fsf@gollum.intra.norang.ca> List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org To: Bernt Hansen Cc: Carsten Dominik , emacs-orgmode@gnu.org, 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