Documentation: Improve and collect documentation about the match view

ORGWEBPAGE/Changes.org

@@ -15,6 +15,17 @@
  :VISIBILITY: content
  :END:
 
+
+** Incompatible changes
+
+*** New key for creating tags/property sparse trees
+
+The key to produce a sparse tree matching tags and properties is
+now =C-c / m= instead of =C-c a T=.  This is also more consistent
+with the =C-c a m= key for the corresponding agenda view.
+=C-c / T= will still work for now, but it is no longer advertised
+in the documentation and may go away at any time in the future.
+
 ** Details
 
 *** PDF export of agenda views
@@ -134,7 +145,7 @@ macros, for example:
 ,my address is {{{myaddress}}}, see you there.
 #+end_src
 
-Macro replacement is the very first thing that happes during
+Macro replacement is the very first thing that happens during
 export, and macros will be replaced even in source code and other
 protected regions.
 
@@ -171,6 +182,12 @@ Thanks to Austin Frank for requesting some of these changes.
 =M-right= and =M-left= now do demote and promote all headlines in
 an active region.
 
+*** The match syntax for tags/properties is now described in a single place
+
+The manual chapters about tags and about properties now only
+refer to the section about agenda views, where the general syntax
+of tag/property matches is described.
+
 * Version 6.23
 ** Overview
 

doc/ChangeLog

@@ -1,3 +1,8 @@
+2009-03-03  Carsten Dominik  <carsten.dominik@gmail.com>
+
+	* org.texi (Matching tags and properties): Collect all
+	documentation about tags/property matches here.
+
 2009-03-01  Carsten Dominik  <carsten.dominik@gmail.com>
 
 	* org.texi (Setting tags): Document `org-tag-persistent-alist'.

doc/org.texi

@@ -4011,9 +4011,9 @@ information into special lists.
 
 @table @kbd
 @kindex C-c \
-@kindex C-c / T
+@kindex C-c / m
 @item C-c \
-@itemx C-c / T
+@itemx C-c / m
 Create a sparse tree with all headlines matching a tags search.  With a
 @kbd{C-u} prefix argument, ignore headlines that are not a TODO line.
 @kindex C-c a m
@@ -4028,82 +4028,9 @@ only TODO items and force checking subitems (see variable
 @code{org-tags-match-list-sublevels}).
 @end table
 
-@cindex Boolean logic, for tag searches
-A @i{tags} search string can use Boolean operators @samp{&} for AND and
-@samp{|} for OR.  @samp{&} binds more strongly than @samp{|}.
-Parenthesis are currently not implemented.  A tag may also be preceded
-by @samp{-}, to select against it, and @samp{+} is syntactic sugar for
-positive selection.  The AND operator @samp{&} is optional when @samp{+}
-or @samp{-} is present.  Examples:
+The syntax for matching tags is described in @ref{Matching tags and
+properties}.
 
-@table @samp
-@item +work-boss
-Select headlines tagged @samp{:work:}, but discard those also tagged
-@samp{:boss:}.
-@item work|laptop
-Selects lines tagged @samp{:work:} or @samp{:laptop:}.
-@item work|laptop&night
-Like before, but require the @samp{:laptop:} lines to be tagged also
-@samp{:night:}.
-@end table
-
-@cindex TODO keyword matching, with tags search
-You may also test for TODO keywords (@pxref{TODO extensions}) and properties
-(@pxref{Properties and Columns}) at the same time as matching tags.  For a
-guide on how to match properties, see @ref{Property searches}.  To match a
-specific TODO keyword, include an expression like @samp{+TODO="NEXT"} as one
-of the terms in a tags search.
-
-There is also the possibility to end the tags part of the match (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 the tag matches, but should be applied with consideration: For
-example, a positive selection on several TODO keywords can not 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:
-
-@table @samp
-@item work+TODO="WAITING"
-Select @samp{:work:}-tagged TODO lines with the specific TODO
-keyword @samp{WAITING}.
-@item work+TODO="WAITING"|home+TODO="WAITING"
-Waiting tasks both at work and at home.
-@item work/WAITING
-Same as the first example.
-@item work/!-WAITING-NEXT
-Select @samp{:work:}-tagged TODO lines that are neither @samp{WAITING}
-nor @samp{NEXT}
-@item work/!+WAITING|+NEXT
-Select @samp{:work:}-tagged TODO lines that are either @samp{WAITING} or
-@samp{NEXT}.
-@end table
-
-@cindex regular expressions, with tags search
-Any element of the tag/todo match can be a regular expression - in this
-case it must be enclosed in curly braces.  For example,
-@samp{work+@{^boss.*@}} matches headlines that contain the tag
-@samp{:work:} and any tag @i{starting} with @samp{boss}.  You may also use a
-regular expression in @samp{TODO=@{^W@}} which would match TODO keywords
-starting with the letter @samp{W}.
-
-@cindex level, require for tags/property match
-@cindex category, require for tags/property match
-@vindex org-odd-levels-only
-You can also require a headline to be of a certain level or category, by
-tapping into the syntax of property searches (@pxref{Property searches})
-and writing instead of any TAG an expression like @samp{LEVEL=3} or
-@samp{CATEGORY="work"}, respectively.  For example, a search
-@samp{+LEVEL=3+boss/-DONE} lists all level three headlines that have the
-tag @samp{boss} and are @emph{not} marked with the TODO keyword DONE.
-In buffers with @code{org-odd-levels-only} set, @samp{LEVEL} does not
-count the number of stars, but @samp{LEVEL=2} will correspond to 3 stars
-etc.
-
-Accessing TODO, LEVEL, and CATEGORY during a search is fast.  Accessing any
-other properties will slow down the search for the first property
-accessed.  Any additional property tests are cheap.
 
 @node Properties and Columns, Dates and Times, Tags, Top
 @chapter Properties and Columns
@@ -4235,6 +4162,7 @@ used as keys in the properties drawer:
 TODO         @r{The TODO keyword of the entry.}
 TAGS         @r{The tags defined directly in the headline.}
 ALLTAGS      @r{All tags, including inherited ones.}
+CATEGORY     @r{The category of an entry.}
 PRIORITY     @r{The priority of the entry, a string with a single letter.}
 DEADLINE     @r{The deadline time string, without the angular brackets.}
 SCHEDULED    @r{The scheduling time stamp, without the angular brackets.}
@@ -4251,51 +4179,28 @@ CLOCKSUM     @r{The sum of CLOCK intervals in the subtree.  @code{org-clock-sum}
 @cindex searching, of properties
 
 To create sparse trees and special lists with selection based on properties,
-the same commands are used as for tag searches (@pxref{Tag searches}), and
-the same logic applies.  For example, here is a search string:
-
-@example
-+work-boss+PRIORITY="A"+Coffee="unlimited"+Effort<2         \
-         +With=@{Sarah\|Denny@}+SCHEDULED>="<2008-10-11>"
-@end example
-
-@noindent
-The type of comparison will depend on how the comparison value is written:
-@itemize @minus
-@item
-If the comparison value is a plain number, a numerical comparison is done,
-and the allowed operators are @samp{<}, @samp{=}, @samp{>}, @samp{<=},
-@samp{>=}, and @samp{<>}.
-@item
-If the comparison value is enclosed in double
-quotes, a string comparison is done, and the same operators are allowed.
-@item
-If the comparison value is enclosed in double quotes @emph{and} angular
-brackets (like @samp{DEADLINE<="<2008-12-24 18:30>"}), both values are
-assumed to be date/time specifications in the standard Org way, and the
-comparison will be done accordingly.  Special values that will be recognized
-are @code{"<now>"} for now (including time), and @code{"<today>"}, and
-@code{"<tomorrow>"} for these days at 0:00 hours, i.e. without a time
-specification.  Also strings like @code{"<+5d>"} or @code{"<-2m>"} with units
-@code{d}, @code{w}, @code{m}, and @code{y} for day, week, month, and year,
-respectively, can be used.
-@item
-If the comparison value is enclosed
-in curly braces, a regexp match is performed, with @samp{=} meaning that the
-regexp matches the property value, and @samp{<>} meaning that it does not
-match.
-@end itemize
+the same commands are used as for tag searches (@pxref{Tag searches}).
+@table @kbd
+@kindex C-c \
+@kindex C-c / m
+@item C-c \
+@itemx C-c / m
+Create a sparse tree with all matching entries.  With a
+@kbd{C-u} prefix argument, ignore headlines that are not a TODO line.
+@kindex C-c a m
+@item C-c a m
+Create a global list of tag/property  matches from all agenda files.
+@xref{Matching tags and properties}.
+@kindex C-c a M
+@item C-c a M
+@vindex org-tags-match-list-sublevels
+Create a global list of tag matches from all agenda files, but check
+only TODO items and force checking subitems (see variable
+@code{org-tags-match-list-sublevels}).
+@end table
 
-So the search string in the example finds entries tagged @samp{:work:} but
-not @samp{:boss:}, which also have a priority value @samp{A}, a
-@samp{:Coffee:} property with the value @samp{unlimited}, an @samp{Effort}
-property that is numerically smaller than 2, a @samp{:With:} property that is
-matched by the regular expression @samp{Sarah\|Denny}, and that are scheduled
-on or after October 11, 2008.
-
-You can configure Org mode to use property inheritance during a search, but
-beware that this can slow down searches considerably.  See @ref{Property
-inheritance} for details.
+The syntax for the search string is described in @ref{Matching tags and
+properties}.
 
 There is also a special command for creating sparse trees based on a
 single property:
@@ -6183,9 +6088,11 @@ and omit the sublevels from the global list.  Configure the variable
 @cindex tags view
 @cindex match view
 
-If headlines in the agenda files are marked with @emph{tags}
-(@pxref{Tags}), you can select headlines based on the tags that apply
-to them and collect them into an agenda buffer.
+If headlines in the agenda files are marked with @emph{tags} (@pxref{Tags}),
+or have properties @pxref{Properties and Columns}, you can select headlines
+based on this meta data and collect them into an agenda buffer.  The match
+syntax described here also applies when creating sparse trees with @kbd{C-c /
+m}.
 
 @table @kbd
 @kindex C-c a m
@@ -6209,6 +6116,132 @@ keywords together with a tags match is also possible, see @ref{Tag searches}.
 The commands available in the tags list are described in @ref{Agenda
 commands}.
 
+@subsubheading Match syntax
+
+@cindex Boolean logic, for tag/property searches
+A search string can use Boolean operators @samp{&} for AND and @samp{|} for
+OR.  @samp{&} binds more strongly than @samp{|}.  Parenthesis are currently
+not implemented.  Each element in the search is either a tag, a regular
+rexpression matching tags, or an expression like @code{PROPERTY OPERATOR
+VALUE} with a comparison operator, accessing a property value.  Each element
+may be preceded by @samp{-}, to select against it, and @samp{+} is syntactic
+sugar for positive selection.  The AND operator @samp{&} is optional when
+@samp{+} or @samp{-} is present.  Here are some examples, using only tags.
+
+@table @samp
+@item +work-boss
+Select headlines tagged @samp{:work:}, but discard those also tagged
+@samp{:boss:}.
+@item work|laptop
+Selects lines tagged @samp{:work:} or @samp{:laptop:}.
+@item work|laptop+night
+Like before, but require the @samp{:laptop:} lines to be tagged also
+@samp{:night:}.
+@end table
+
+@cindex regular expressions, with tags search
+Instead of a tag, you may also specify a regular expression enclosed in curly
+braces.  For example,
+@samp{work+@{^boss.*@}} matches headlines that contain the tag
+@samp{:work:} and any tag @i{starting} with @samp{boss}.
+
+@cindex TODO keyword matching, with tags search
+@cindex level, require for tags/property match
+@cindex category, require for tags/property match
+@vindex org-odd-levels-only
+You may also test for properties (@pxref{Properties and Columns}) at the same
+time as matching tags.  The properties may be real properties, or special
+properties that represent other meta data (@pxref{Special properties}).  For
+example, the ``property'' @code{TODO} represents the TODO keyword of the
+entry.  Or, the ``property'' @code{LEVEL} represents the level of an entry.
+So a search @samp{+LEVEL=3+boss-TODO="DONE"} lists all level three headlines
+that have the tag @samp{boss} and are @emph{not} marked with the TODO keyword
+DONE.  In buffers with @code{org-odd-levels-only} set, @samp{LEVEL} does not
+count the number of stars, but @samp{LEVEL=2} will correspond to 3 stars etc.
+
+Here are more examples:
+@table @samp
+@item work+TODO="WAITING"
+Select @samp{:work:}-tagged TODO lines with the specific TODO
+keyword @samp{WAITING}.
+@item work+TODO="WAITING"|home+TODO="WAITING"
+Waiting tasks both at work and at home.
+@end table
+
+When matching properties, a number of different operaors can be used to test
+the value of a property.  Here is a complex example:
+
+@example
++work-boss+PRIORITY="A"+Coffee="unlimited"+Effort<2         \
+         +With=@{Sarah\|Denny@}+SCHEDULED>="<2008-10-11>"
+@end example
+
+@noindent
+The type of comparison will depend on how the comparison value is written:
+@itemize @minus
+@item
+If the comparison value is a plain number, a numerical comparison is done,
+and the allowed operators are @samp{<}, @samp{=}, @samp{>}, @samp{<=},
+@samp{>=}, and @samp{<>}.
+@item
+If the comparison value is enclosed in double
+quotes, a string comparison is done, and the same operators are allowed.
+@item
+If the comparison value is enclosed in double quotes @emph{and} angular
+brackets (like @samp{DEADLINE<="<2008-12-24 18:30>"}), both values are
+assumed to be date/time specifications in the standard Org way, and the
+comparison will be done accordingly.  Special values that will be recognized
+are @code{"<now>"} for now (including time), and @code{"<today>"}, and
+@code{"<tomorrow>"} for these days at 0:00 hours, i.e. without a time
+specification.  Also strings like @code{"<+5d>"} or @code{"<-2m>"} with units
+@code{d}, @code{w}, @code{m}, and @code{y} for day, week, month, and year,
+respectively, can be used.
+@item
+If the comparison value is enclosed
+in curly braces, a regexp match is performed, with @samp{=} meaning that the
+regexp matches the property value, and @samp{<>} meaning that it does not
+match.
+@end itemize
+
+So the search string in the example finds entries tagged @samp{:work:} but
+not @samp{:boss:}, which also have a priority value @samp{A}, a
+@samp{:Coffee:} property with the value @samp{unlimited}, an @samp{Effort}
+property that is numerically smaller than 2, a @samp{:With:} property that is
+matched by the regular expression @samp{Sarah\|Denny}, and that are scheduled
+on or after October 11, 2008.
+
+Accessing TODO, LEVEL, and CATEGORY during a search is fast.  Accessing any
+other properties will slow down the search.  However, once you have payed the
+price by accessig one property, testing additional properties is cheap
+again.
+
+You can configure Org mode to use property inheritance during a search, but
+beware that this can slow down searches considerably.  See @ref{Property
+inheritance} for details.
+
+For backward compatibility, and also for typing speed, there is also a
+different way to test TODO states in a search.  For this, terminalte 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 consideration: For example, a positive
+selection on several TODO keywords can not 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:
+
+@table @samp
+@item work/WAITING
+Same as @samp{work+TODO="WAITING"}
+@item work/!-WAITING-NEXT
+Select @samp{:work:}-tagged TODO lines that are neither @samp{WAITING}
+nor @samp{NEXT}
+@item work/!+WAITING|+NEXT
+Select @samp{:work:}-tagged TODO lines that are either @samp{WAITING} or
+@samp{NEXT}.
+@end table
+
 @node Timeline, Keyword search, Matching tags and properties, Built-in agenda views
 @subsection Timeline for a single file
 @cindex timeline, single file

lisp/ChangeLog

@@ -1,3 +1,9 @@
+2009-03-03  Carsten Dominik  <carsten.dominik@gmail.com>
+
+	* org.el (org-match-sparse-tree): Renamed from
+	`org-tags-sparse-tree'.
+	(org-tags-sparse-tree): New alias.
+
 2009-03-02  Carsten Dominik  <carsten.dominik@gmail.com>
 
 	* org.el (org-get-valid-level): Catch the case where the level

lisp/org-agenda.el

@@ -330,8 +330,8 @@ should provide a description for the prefix, like
 		  (const :tag "TODO list" alltodo)
 		  (const :tag "Search words" search)
 		  (const :tag "Stuck projects" stuck)
-		  (const :tag "Tags search (all agenda files)" tags)
-		  (const :tag "Tags search of TODO entries (all agenda files)" tags-todo)
+		  (const :tag "Tags/Property match (all agenda files)" tags)
+		  (const :tag "Tags/Property match of TODO entries (all agenda files)" tags-todo)
 		  (const :tag "TODO keyword search (all agenda files)" todo)
 		  (const :tag "Tags sparse tree (current buffer)" tags-tree)
 		  (const :tag "TODO keyword tree (current buffer)" todo-tree)
@@ -1580,7 +1580,7 @@ Pressing `<' twice means to restrict to the current subtree or region
 		(org-let lprops '(org-todo-list match)))
 	       ((eq type 'tags-tree)
 		(org-check-for-org-mode)
-		(org-let lprops '(org-tags-sparse-tree current-prefix-arg match)))
+		(org-let lprops '(org-match-sparse-tree current-prefix-arg match)))
 	       ((eq type 'todo-tree)
 		(org-check-for-org-mode)
 		(org-let lprops

lisp/org.el

@@ -9506,14 +9506,14 @@ This command can create sparse trees.  You first need to select the type
 of match used to create the tree:
 
 t      Show entries with a specific TODO keyword.
-T      Show entries selected by a tags match.
+m      Show entries selected by a tags/property match.
 p      Enter a property name and its value (both with completion on existing
        names/values) and show entries with that property.
 r      Show entries matching a regular expression
 d      Show deadlines due within `org-deadline-warning-days'."
   (interactive "P")
   (let (ans kwd value)
-    (message "Sparse tree: [/]regexp [t]odo-kwd [T]ag [p]roperty [d]eadlines [b]efore-date")
+    (message "Sparse tree: [/]regexp [t]odo-kwd [m]atch [p]roperty [d]eadlines [b]efore-date")
     (setq ans (read-char-exclusive))
     (cond
      ((equal ans ?d)
@@ -9522,8 +9522,8 @@ d      Show deadlines due within `org-deadline-warning-days'."
       (call-interactively 'org-check-before-date))
      ((equal ans ?t)
       (org-show-todo-tree '(4)))
-     ((equal ans ?T)
-      (call-interactively 'org-tags-sparse-tree))
+     ((member ans '(?T ?m))
+      (call-interactively 'org-match-sparse-tree))
      ((member ans '(?p ?P))
       (setq kwd (org-ido-completing-read "Property: "
 				 (mapcar 'list (org-buffer-property-keys))))
@@ -9531,7 +9531,7 @@ d      Show deadlines due within `org-deadline-warning-days'."
 				   (mapcar 'list (org-property-values kwd))))
       (unless (string-match "\\`{.*}\\'" value)
 	(setq value (concat "\"" value "\"")))
-      (org-tags-sparse-tree arg (concat kwd "=" value)))
+      (org-match-sparse-tree arg (concat kwd "=" value)))
      ((member ans '(?r ?R ?/))
       (call-interactively 'org-occur))
      (t (error "No such sparse tree command \"%c\"" ans)))))
@@ -9892,7 +9892,7 @@ only lines with a TODO keyword are included in the output."
 
 (defvar todo-only) ;; dynamically scoped
 
-(defun org-tags-sparse-tree (&optional todo-only match)
+(defun org-match-sparse-tree (&optional todo-only match)
   "Create a sparse tree according to tags string MATCH.
 MATCH can contain positive and negative selection of tags, like
 \"+WORK+URGENT-WITHBOSS\".
@@ -9902,6 +9902,8 @@ also TODO lines."
   (org-prepare-agenda-buffers (list (current-buffer)))
   (org-scan-tags 'sparse-tree (cdr (org-make-tags-matcher match)) todo-only))
 
+(defalias 'org-tags-sparse-tree 'org-match-sparse-tree)
+
 (defvar org-cached-props nil)
 (defun org-cached-entry-get (pom property)
   (if (or (eq t org-use-property-inheritance)
@@ -13237,7 +13239,7 @@ The images can be removed again with \\[org-ctrl-c-ctrl-c]."
 (org-defkey org-mode-map "\C-c\C-v" 'org-show-todo-tree)
 (org-defkey org-mode-map "\C-c\C-w" 'org-refile)
 (org-defkey org-mode-map "\C-c/"    'org-sparse-tree)   ; Minor-mode reserved
-(org-defkey org-mode-map "\C-c\\"   'org-tags-sparse-tree) ; Minor-mode res.
+(org-defkey org-mode-map "\C-c\\"   'org-match-sparse-tree) ; Minor-mode res.
 (org-defkey org-mode-map "\C-c\C-m" 'org-ctrl-c-ret)
 (org-defkey org-mode-map "\M-\C-m"  'org-insert-heading)
 (org-defkey org-mode-map [(control return)] 'org-insert-heading-respect-content)
@@ -14299,7 +14301,7 @@ See the individual commands for more information."
      ["TODO Tree"  org-show-todo-tree t]
      ["Check Deadlines" org-check-deadlines t]
      ["Timeline" org-timeline t]
-     ["Tags Tree" org-tags-sparse-tree t])
+     ["Tags/Property tree" org-match-sparse-tree t])
     "--"
     ("Hyperlinks"
      ["Store Link (Global)" org-store-link t]