doc/org.texi (Filtering/limiting agenda items): New subsection

* doc/org.texi (Filtering/limiting agenda items): New subsection.
Document the use of `org-agenda-max-*' options and
`org-agenda-limit-interactively' from the agenda.
(Agenda commands): Move details about filtering commands to
the new section, only include a summary here.
(Customizing tables in ODT export)
(System-wide header arguments, Conflicts, Dynamic blocks): Use
spaces for indentation.

1 files changed, 234 insertions, 129 deletions

diff --git a/doc/org.texi b/doc/org.texi
index 5c2dd97..1a9eada 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -537,7 +537,8 @@ Presentation and sorting
 
 * Categories::                  Not all tasks are equal
 * Time-of-day specifications::  How the agenda knows the time
-* Sorting of agenda items::     The order of things
+* Sorting agenda items::        The order of things
+* Filtering/limiting agenda items:: Dynamically narrow the agenda
 
 Custom agenda views
 
@@ -8207,7 +8208,8 @@ associated with the item.
 @menu
 * Categories::                  Not all tasks are equal
 * Time-of-day specifications::  How the agenda knows the time
-* Sorting of agenda items::     The order of things
+* Sorting agenda items::        The order of things
+* Filtering/limiting agenda items:: Dynamically narrow the agenda
 @end menu
 
 @node Categories, Time-of-day specifications, Presentation and sorting, Presentation and sorting
@@ -8244,7 +8246,7 @@ longer than 10 characters.
 You can set up icons for category by customizing the
 @code{org-agenda-category-icon-alist} variable.
 
-@node Time-of-day specifications, Sorting of agenda items, Categories, Presentation and sorting
+@node Time-of-day specifications, Sorting agenda items, Categories, Presentation and sorting
 @subsection Time-of-day specifications
 @cindex time-of-day specification
 
@@ -8295,8 +8297,8 @@ The time grid can be turned on and off with the variable
 @code{org-agenda-use-time-grid}, and can be configured with
 @code{org-agenda-time-grid}.
 
-@node Sorting of agenda items,  , Time-of-day specifications, Presentation and sorting
-@subsection Sorting of agenda items
+@node Sorting agenda items, Filtering/limiting agenda items, Time-of-day specifications, Presentation and sorting
+@subsection Sorting agenda items
 @cindex sorting, of agenda items
 @cindex priorities, of agenda items
 Before being inserted into a view, the items are sorted.  How this is
@@ -8329,6 +8331,189 @@ Sorting can be customized using the variable
 @code{org-agenda-sorting-strategy}, and may also include criteria based on
 the estimated effort of an entry (@pxref{Effort estimates}).
 
+@node Filtering/limiting agenda items,  , Sorting agenda items, Presentation and sorting
+@subsection Filtering/limiting agenda items
+
+Agenda built-in or customized commands are statically defined.  Agenda
+filters and limits provide two ways of dynamically narrowing down the list of
+agenda entries: @emph{fitlers} and @emph{limits}.  Filters only act on the
+display of the items, while limits take effect before the list of agenda
+entries is built.  Filter are more often used interactively, while limits are
+mostly useful when defined as local variables within custom agenda commands.
+
+@subsubheading Filtering in the agenda
+@cindex filtering, by tag, category, top headline and effort, in agenda
+@cindex tag filtering, in agenda
+@cindex category filtering, in agenda
+@cindex top headline filtering, in agenda
+@cindex effort filtering, in agenda
+@cindex query editing, in agenda
+
+@table @kbd
+@orgcmd{/,org-agenda-filter-by-tag}
+@vindex org-agenda-tag-filter-preset
+Filter the agenda view with respect to a tag and/or effort estimates.  The
+difference between this and a custom agenda command is that filtering is very
+fast, so that you can switch quickly between different filters without having
+to recreate the agenda.@footnote{Custom commands can preset a filter by
+binding the variable @code{org-agenda-tag-filter-preset} as an option.  This
+filter will then be applied to the view and persist as a basic filter through
+refreshes and more secondary filtering.  The filter is a global property of
+the entire agenda view---in a block agenda, you should only set this in the
+global options section, not in the section of an individual block.}
+
+You will be prompted for a tag selection letter; @key{SPC} will mean any tag at
+all.  Pressing @key{TAB} at that prompt will offer use completion to select a
+tag (including any tags that do not have a selection character).  The command
+then hides all entries that do not contain or inherit this tag.  When called
+with prefix arg, remove the entries that @emph{do} have the tag.  A second
+@kbd{/} at the prompt will turn off the filter and unhide any hidden entries.
+If the first key you press is either @kbd{+} or @kbd{-}, the previous filter
+will be narrowed by requiring or forbidding the selected additional tag.
+Instead of pressing @kbd{+} or @kbd{-} after @kbd{/}, you can also
+immediately use the @kbd{\} command.
+
+@vindex org-sort-agenda-noeffort-is-high
+In order to filter for effort estimates, you should set up allowed
+efforts globally, for example
+@lisp
+(setq org-global-properties
+    '(("Effort_ALL". "0 0:10 0:30 1:00 2:00 3:00 4:00")))
+@end lisp
+You can then filter for an effort by first typing an operator, one of
+@kbd{<}, @kbd{>}, and @kbd{=}, and then the one-digit index of an effort
+estimate in your array of allowed values, where @kbd{0} means the 10th value.
+The filter will then restrict to entries with effort smaller-or-equal, equal,
+or larger-or-equal than the selected value.  If the digits 0--9 are not used
+as fast access keys to tags, you can also simply press the index digit
+directly without an operator.  In this case, @kbd{<} will be assumed.  For
+application of the operator, entries without a defined effort will be treated
+according to the value of @code{org-sort-agenda-noeffort-is-high}.  To filter
+for tasks without effort definition, press @kbd{?} as the operator.
+
+Org also supports automatic, context-aware tag filtering.  If the variable
+@code{org-agenda-auto-exclude-function} is set to a user-defined function,
+that function can decide which tags should be excluded from the agenda
+automatically.  Once this is set, the @kbd{/} command then accepts @kbd{RET}
+as a sub-option key and runs the auto exclusion logic.  For example, let's
+say you use a @code{Net} tag to identify tasks which need network access, an
+@code{Errand} tag for errands in town, and a @code{Call} tag for making phone
+calls.  You could auto-exclude these tags based on the availability of the
+Internet, and outside of business hours, with something like this:
+
+@smalllisp
+@group
+(defun org-my-auto-exclude-function (tag)
+  (and (cond
+        ((string= tag "Net")
+         (/= 0 (call-process "/sbin/ping" nil nil nil
+                             "-c1" "-q" "-t1" "mail.gnu.org")))
+        ((or (string= tag "Errand") (string= tag "Call"))
+         (let ((hour (nth 2 (decode-time))))
+           (or (< hour 8) (> hour 21)))))
+       (concat "-" tag)))
+
+(setq org-agenda-auto-exclude-function 'org-my-auto-exclude-function)
+@end group
+@end smalllisp
+
+@orgcmd{\\,org-agenda-filter-by-tag-refine}
+Narrow the current agenda filter by an additional condition.  When called with
+prefix arg, remove the entries that @emph{do} have the tag, or that do match
+the effort criterion.  You can achieve the same effect by pressing @kbd{+} or
+@kbd{-} as the first key after the @kbd{/} command.
+
+@c
+@kindex [
+@kindex ]
+@kindex @{
+@kindex @}
+@item [ ] @{ @}
+@table @i
+@item @r{in} search view
+add new search words (@kbd{[} and @kbd{]}) or new regular expressions
+(@kbd{@{} and @kbd{@}}) to the query string.  The opening bracket/brace will
+add a positive search term prefixed by @samp{+}, indicating that this search
+term @i{must} occur/match in the entry.  The closing bracket/brace will add a
+negative search term which @i{must not} occur/match in the entry for it to be
+selected.
+@end table
+
+@orgcmd{<,org-agenda-filter-by-category}
+@vindex org-agenda-category-filter-preset
+
+Filter the current agenda view with respect to the category of the item at
+point.  Pressing @code{<} another time will remove this filter.  You can add
+a filter preset through the option @code{org-agenda-category-filter-preset}
+(see below.)
+
+@orgcmd{^,org-agenda-filter-by-top-headline}
+Filter the current agenda view and only display the siblings and the parent
+headline of the one at point.
+
+@orgcmd{=,org-agenda-filter-by-regexp}
+@vindex org-agenda-regexp-filter-preset
+
+Filter the agenda view by a regular expression: only show agenda entries
+matching the regular expression the user entered.  When called with a prefix
+argument, it will filter @emph{out} entries matching the regexp.  With two
+universal prefix arguments, it will remove all the regexp filters, which can
+be accumulated.  You can add a filter preset through the option
+@code{org-agenda-category-filter-preset} (see below.)
+
+@orgcmd{|,org-agenda-filter-remove-all}
+Remove all filters in the current agenda view.
+@end table
+
+@subsubheading Setting limits for the agenda
+@cindex limits, in agenda
+@vindex org-agenda-max-entries
+@vindex org-agenda-max-effort
+@vindex org-agenda-max-todos
+@vindex org-agenda-max-tags
+
+Here is a list of options that you can set, either globally, or locally in
+your custom agenda views@pxref{Custom agenda views}.
+
+@table @var
+@item org-agenda-max-entries
+Limit the number of entries.
+@item org-agenda-max-effort
+Limit the duration of accumulated efforts (as minutes).
+@item org-agenda-max-todos
+Limit the number of entries with TODO keywords.
+@item org-agenda-max-tags
+Limit the number of tagged entries.
+@end table
+
+When set to a positive integer, each option will exclude entries from other
+catogories: for example, @code{(setq org-agenda-max-effort 100)} will limit
+the agenda to 100 minutes of effort and exclude any entry that as no effort
+property.  If you want to include entries with no effort property, use a
+negative value for @var{org-agenda-max-effort}.
+
+One useful setup is to use @var{org-agenda-max-entries} locally in a custom
+command.  For example, this custom command will display the next five entries
+with a @code{NEXT} TODO keyword.
+
+@smalllisp
+(setq org-agenda-custom-commands
+      '(("n" todo "NEXT"
+         ((org-agenda-max-entries 5)))))
+@end smalllisp
+
+Once you mark one of these five entry as @code{DONE}, rebuilding the agenda
+will again the next five entries again, including the first entry that was
+excluded so far.
+
+You can also dynamically set temporary limits@footnote{Those temporary limits
+are lost when rebuilding the agenda.}:
+
+@table @kbd
+@orgcmd{~,org-agenda-limit-interactively}
+This prompts for the type of limit to apply and its value.
+@end table
+
 @node Agenda commands, Custom agenda views, Presentation and sorting, Agenda Views
 @section Commands in the agenda buffer
 @cindex commands, in agenda buffer
@@ -8519,22 +8704,28 @@ that entry would be in the original buffer (taken from a property, from a
 Remove the restriction lock on the agenda, if it is currently restricted to a
 file or subtree (@pxref{Agenda files}).
 
-@tsubheading{Secondary filtering and query editing}
-@cindex filtering, by tag category and effort, in agenda
-@cindex tag filtering, in agenda
-@cindex category filtering, in agenda
-@cindex effort filtering, in agenda
-@cindex query editing, in agenda
+@tsubheading{Secondary filtering and query editing@footnote{See
+@pxref{Filtering/limiting agenda items} for a detailed description of these
+commands.}}
+
+@orgcmd{/,org-agenda-filter-by-tag}
+@vindex org-agenda-tag-filter-preset
+Filter the agenda view with respect to a tag and/or effort estimates.
+
+@orgcmd{\\,org-agenda-filter-by-tag-refine}
+Narrow the current agenda filter by an additional condition.
 
 @orgcmd{<,org-agenda-filter-by-category}
 @vindex org-agenda-category-filter-preset
 
 Filter the current agenda view with respect to the category of the item at
-point.  Pressing @code{<} another time will remove this filter.  You can add
-a filter preset through the option @code{org-agenda-category-filter-preset}
-(see below.)
+point.  Pressing @code{<} another time will remove this filter.
+
+@orgcmd{^,org-agenda-filter-by-top-headline}
+Filter the current agenda view and only display the siblings and the parent
+headline of the one at point.
 
-@orgcmd{|,org-agenda-filter-by-regexp}
+@orgcmd{=,org-agenda-filter-by-regexp}
 @vindex org-agenda-regexp-filter-preset
 
 Filter the agenda view by a regular expression: only show agenda entries
@@ -8544,94 +8735,8 @@ universal prefix arguments, it will remove all the regexp filters, which can
 be accumulated.  You can add a filter preset through the option
 @code{org-agenda-category-filter-preset} (see below.)
 
-@orgcmd{/,org-agenda-filter-by-tag}
-@vindex org-agenda-tag-filter-preset
-Filter the agenda view with respect to a tag and/or effort estimates.  The
-difference between this and a custom agenda command is that filtering is very
-fast, so that you can switch quickly between different filters without having
-to recreate the agenda.@footnote{Custom commands can preset a filter by
-binding the variable @code{org-agenda-tag-filter-preset} as an option.  This
-filter will then be applied to the view and persist as a basic filter through
-refreshes and more secondary filtering.  The filter is a global property of
-the entire agenda view---in a block agenda, you should only set this in the
-global options section, not in the section of an individual block.}
-
-You will be prompted for a tag selection letter; @key{SPC} will mean any tag at
-all.  Pressing @key{TAB} at that prompt will offer use completion to select a
-tag (including any tags that do not have a selection character).  The command
-then hides all entries that do not contain or inherit this tag.  When called
-with prefix arg, remove the entries that @emph{do} have the tag.  A second
-@kbd{/} at the prompt will turn off the filter and unhide any hidden entries.
-If the first key you press is either @kbd{+} or @kbd{-}, the previous filter
-will be narrowed by requiring or forbidding the selected additional tag.
-Instead of pressing @kbd{+} or @kbd{-} after @kbd{/}, you can also
-immediately use the @kbd{\} command.
-
-@vindex org-sort-agenda-noeffort-is-high
-In order to filter for effort estimates, you should set up allowed
-efforts globally, for example
-@lisp
-(setq org-global-properties
-    '(("Effort_ALL". "0 0:10 0:30 1:00 2:00 3:00 4:00")))
-@end lisp
-You can then filter for an effort by first typing an operator, one of
-@kbd{<}, @kbd{>}, and @kbd{=}, and then the one-digit index of an effort
-estimate in your array of allowed values, where @kbd{0} means the 10th value.
-The filter will then restrict to entries with effort smaller-or-equal, equal,
-or larger-or-equal than the selected value.  If the digits 0--9 are not used
-as fast access keys to tags, you can also simply press the index digit
-directly without an operator.  In this case, @kbd{<} will be assumed.  For
-application of the operator, entries without a defined effort will be treated
-according to the value of @code{org-sort-agenda-noeffort-is-high}.  To filter
-for tasks without effort definition, press @kbd{?} as the operator.
-
-Org also supports automatic, context-aware tag filtering.  If the variable
-@code{org-agenda-auto-exclude-function} is set to a user-defined function,
-that function can decide which tags should be excluded from the agenda
-automatically.  Once this is set, the @kbd{/} command then accepts @kbd{RET}
-as a sub-option key and runs the auto exclusion logic.  For example, let's
-say you use a @code{Net} tag to identify tasks which need network access, an
-@code{Errand} tag for errands in town, and a @code{Call} tag for making phone
-calls.  You could auto-exclude these tags based on the availability of the
-Internet, and outside of business hours, with something like this:
-
-@smalllisp
-@group
-(defun org-my-auto-exclude-function (tag)
-  (and (cond
-        ((string= tag "Net")
-         (/= 0 (call-process "/sbin/ping" nil nil nil
-                             "-c1" "-q" "-t1" "mail.gnu.org")))
-        ((or (string= tag "Errand") (string= tag "Call"))
-         (let ((hour (nth 2 (decode-time))))
-           (or (< hour 8) (> hour 21)))))
-       (concat "-" tag)))
-
-(setq org-agenda-auto-exclude-function 'org-my-auto-exclude-function)
-@end group
-@end smalllisp
-
-@orgcmd{\\,org-agenda-filter-by-tag-refine}
-Narrow the current agenda filter by an additional condition.  When called with
-prefix arg, remove the entries that @emph{do} have the tag, or that do match
-the effort criterion.  You can achieve the same effect by pressing @kbd{+} or
-@kbd{-} as the first key after the @kbd{/} command.
-
-@c
-@kindex [
-@kindex ]
-@kindex @{
-@kindex @}
-@item [ ] @{ @}
-@table @i
-@item @r{in} search view
-add new search words (@kbd{[} and @kbd{]}) or new regular expressions
-(@kbd{@{} and @kbd{@}}) to the query string.  The opening bracket/brace will
-add a positive search term prefixed by @samp{+}, indicating that this search
-term @i{must} occur/match in the entry.  The closing bracket/brace will add a
-negative search term which @i{must not} occur/match in the entry for it to be
-selected.
-@end table
+@orgcmd{|,org-agenda-filter-remove-all}
+Remove all filters in the current agenda view.
 
 @tsubheading{Remote editing}
 @cindex remote editing, from agenda
@@ -8826,15 +8931,15 @@ example, the function below sets the CATEGORY property of the entries to web.
 (defun set-category ()
   (interactive "P")
   (let* ((marker (or (org-get-at-bol 'org-hd-marker)
-		     (org-agenda-error)))
-	 (buffer (marker-buffer marker)))
+                     (org-agenda-error)))
+         (buffer (marker-buffer marker)))
     (with-current-buffer buffer
       (save-excursion
-	(save-restriction
-	  (widen)
-	  (goto-char marker)
-	  (org-back-to-heading t)
-	  (org-set-property "CATEGORY" "web"))))))
+        (save-restriction
+          (widen)
+          (goto-char marker)
+          (org-back-to-heading t)
+          (org-set-property "CATEGORY" "web"))))))
 @end group
 @end lisp
 @end table
@@ -11985,7 +12090,7 @@ custom @samp{PageBreak} style as shown below.
 
 @example
 <style:style style:name="PageBreak" style:family="paragraph"
-	     style:parent-style-name="Text_20_body">
+             style:parent-style-name="Text_20_body">
   <style:paragraph-properties fo:break-before="page"/>
 </style:style>
 @end example
@@ -12031,12 +12136,12 @@ export the table that follows:
 @lisp
 (setq org-odt-table-styles
       (append org-odt-table-styles
-	      '(("TableWithHeaderRowAndColumn" "Custom"
-		 ((use-first-row-styles . t)
-		  (use-first-column-styles . t)))
-		("TableWithFirstRowandLastRow" "Custom"
-		 ((use-first-row-styles . t)
-		  (use-last-row-styles . t))))))
+            '(("TableWithHeaderRowAndColumn" "Custom"
+                ((use-first-row-styles . t)
+                 (use-first-column-styles . t)))
+                ("TableWithFirstRowandLastRow" "Custom"
+                 ((use-first-row-styles . t)
+                 (use-last-row-styles . t))))))
 @end lisp
 
 @example
@@ -12152,12 +12257,12 @@ effect by selectively activating the individual cell styles in that template.
 @lisp
 (setq org-odt-table-styles
       (append org-odt-table-styles
-	      '(("TableWithHeaderRowAndColumn" "Custom"
-		 ((use-first-row-styles . t)
-		  (use-first-column-styles . t)))
-		("TableWithFirstRowandLastRow" "Custom"
-		 ((use-first-row-styles . t)
-		  (use-last-row-styles . t))))))
+              '(("TableWithHeaderRowAndColumn" "Custom"
+                 ((use-first-row-styles . t)
+                  (use-first-column-styles . t)))
+                ("TableWithFirstRowandLastRow" "Custom"
+                 ((use-first-row-styles . t)
+                  (use-last-row-styles . t))))))
 @end lisp
 
 @item
@@ -13225,7 +13330,7 @@ blocks.
 @lisp
 (setq org-babel-default-header-args
       (cons '(:noweb . "yes")
-	    (assq-delete-all :noweb org-babel-default-header-args)))
+            (assq-delete-all :noweb org-babel-default-header-args)))
 @end lisp
 
 @node Language-specific header arguments, Buffer-wide header arguments, System-wide header arguments, Using header arguments
@@ -15556,10 +15661,10 @@ Then, tell Org mode what to do with the new function:
 @lisp
 (add-hook 'org-mode-hook
           (lambda ()
-	    (make-variable-buffer-local 'yas/trigger-key)
-	    (setq yas/trigger-key [tab])
-	    (add-to-list 'org-tab-first-hook 'yas/org-very-safe-expand)
-	    (define-key yas/keymap [tab] 'yas/next-field)))
+            (make-variable-buffer-local 'yas/trigger-key)
+            (setq yas/trigger-key [tab])
+            (add-to-list 'org-tab-first-hook 'yas/org-very-safe-expand)
+            (define-key yas/keymap [tab] 'yas/next-field)))
 @end lisp
 
 @item @file{windmove.el} by Hovav Shacham
@@ -16234,7 +16339,7 @@ The corresponding block writer function could look like this:
 (defun org-dblock-write:block-update-time (params)
   (let ((fmt (or (plist-get params :format) "%d. %m. %Y")))
     (insert "Last block update at: "
-	    (format-time-string fmt (current-time)))))
+            (format-time-string fmt (current-time)))))
 @end lisp
 
 If you want to make sure that all dynamic blocks are always up-to-date,