From 2e73ce217779330d446a908627ec19875dc3fd05 Mon Sep 17 00:00:00 2001 From: Carsten Dominik Date: Tue, 22 Jun 2010 08:26:24 +0200 Subject: [PATCH] Clarify that TODO matches only match not-DONE states by default Bernt Hansen writes: > 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 :) Bernt is right, and this patch tries to clarify the issue. --- doc/org.texi | 79 ++++++++++++++++++++++++++++-------------------------- lisp/org-agenda.el | 2 +- 2 files changed, 42 insertions(+), 39 deletions(-) diff --git a/doc/org.texi b/doc/org.texi index 17615e0fa..e233e058e 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -1232,7 +1232,7 @@ as bullets. @emph{Ordered} list items start with a numeral followed by either a period or a right parenthesis, such as @samp{1.} or @samp{1)}. If you want a list to start a different value (e.g. 20), start the text of the item with -@code{[@@start:20]}. +@code{[@@start:20]}. @item @emph{Description} list items are unordered list items, and contain the separator @samp{ :: } to separate the description @emph{term} from the @@ -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 @@ -7009,12 +7011,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 @@ -8258,7 +8261,7 @@ summarizes the markup rules used in an Org-mode buffer. * Images and tables:: Tables and Images will be included * Literal examples:: Source code examples with special formatting * Include files:: Include additional files into a document -* Index entries:: +* Index entries:: Making an index * Macro replacement:: Use macros to create complex output * Embedded LaTeX:: LaTeX can be freely used inside Org documents @end menu @@ -8652,7 +8655,7 @@ the contains an exclamation mark will create a sub item. See @ref{Generating an index} for more information. @example -* Curriculum Vitae +* Curriculum Vitae #+INDEX: CV #+INDEX: Application!CV @end example @@ -10649,7 +10652,7 @@ file is part of any project in @code{org-publish-project-alist}. @subsection Generating a sitemap @cindex sitemap, of published pages -The following properties may be used to control publishing of +The following properties may be used to control publishing of a map of files for a given project. @multitable @columnfractions 0.35 0.65 @@ -12625,7 +12628,7 @@ Emacs about it: @end lisp Org-mode has commands to put files for @i{MobileOrg} into that directory, -and to read captured notes from there. +and to read captured notes from there. @node Pushing to MobileOrg, Pulling from MobileOrg, Setting up the staging area, MobileOrg @section Pushing to MobileOrg diff --git a/lisp/org-agenda.el b/lisp/org-agenda.el index 93334b696..dc9abce78 100644 --- a/lisp/org-agenda.el +++ b/lisp/org-agenda.el @@ -3621,7 +3621,7 @@ in `org-agenda-text-search-extra-files'." ;;;###autoload (defun org-todo-list (arg) - "Show all TODO entries from all agenda file in a single list. + "Show all (not done) TODO entries from all agenda file in a single list. The prefix arg can be used to select a specific TODO keyword and limit the list to these. When using \\[universal-argument], you will be prompted for a keyword. A numeric prefix directly selects the Nth keyword in -- 2.11.4.GIT