From: Carsten Dominik <carsten.dominik@gmail.com>
To: Bernt Hansen <bernt@norang.ca>
Cc: Carsten Dominik <carsten@orgmode.org>,
emacs-orgmode@gnu.org, jeff stern <jas@uci.edu>
Subject: Re: Confusion about tags-todo matches and TODO keywords
Date: Tue, 22 Jun 2010 10:51:22 +0200 [thread overview]
Message-ID: <9485A6F0-9345-4A44-BA8B-0751E6060991@gmail.com> (raw)
In-Reply-To: <87fx0ggdl1.fsf@gollum.intra.norang.ca>
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
next prev parent reply other threads:[~2010-06-22 9:05 UTC|newest]
Thread overview: 4+ messages / expand[flat|nested] mbox.gz Atom feed top
2010-06-21 23:39 Confusion about tags-todo matches and TODO keywords Bernt Hansen
2010-06-22 8:51 ` Carsten Dominik [this message]
2010-06-22 11:24 ` Bernt Hansen
2010-06-22 12:47 ` Carsten Dominik
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.orgmode.org/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=9485A6F0-9345-4A44-BA8B-0751E6060991@gmail.com \
--to=carsten.dominik@gmail.com \
--cc=bernt@norang.ca \
--cc=carsten@orgmode.org \
--cc=emacs-orgmode@gnu.org \
--cc=jas@uci.edu \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
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).