ndwarshuis
/
org-mode
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

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.
This commit is contained in:
Bastien Guerry 2013-04-12 12:18:45 +02:00
parent bccda67ce4
commit 57fa03b2da
1 changed files with 234 additions and 129 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

311
doc/org.texi
View File

@ -537,7 +537,8 @@ Presentation and sorting
* Categories:: Not all tasks are equal * Categories:: Not all tasks are equal
* Time-of-day specifications:: How the agenda knows the time * 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 Custom agenda views
@ -8207,7 +8208,8 @@ associated with the item.
@menu @menu
* Categories:: Not all tasks are equal * Categories:: Not all tasks are equal
* Time-of-day specifications:: How the agenda knows the time * 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 @end menu
@node Categories, Time-of-day specifications, Presentation and sorting, Presentation and sorting @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 You can set up icons for category by customizing the
@code{org-agenda-category-icon-alist} variable. @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 @subsection Time-of-day specifications
@cindex time-of-day specification @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-use-time-grid}, and can be configured with
@code{org-agenda-time-grid}. @code{org-agenda-time-grid}.
@node Sorting of agenda items, , Time-of-day specifications, Presentation and sorting @node Sorting agenda items, Filtering/limiting agenda items, Time-of-day specifications, Presentation and sorting
@subsection Sorting of agenda items @subsection Sorting agenda items
@cindex sorting, of agenda items @cindex sorting, of agenda items
@cindex priorities, of agenda items @cindex priorities, of agenda items
Before being inserted into a view, the items are sorted. How this is 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 @code{org-agenda-sorting-strategy}, and may also include criteria based on
the estimated effort of an entry (@pxref{Effort estimates}). 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 @node Agenda commands, Custom agenda views, Presentation and sorting, Agenda Views
@section Commands in the agenda buffer @section Commands in the agenda buffer
@cindex commands, in 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 Remove the restriction lock on the agenda, if it is currently restricted to a
file or subtree (@pxref{Agenda files}). file or subtree (@pxref{Agenda files}).
@tsubheading{Secondary filtering and query editing} @tsubheading{Secondary filtering and query editing@footnote{See
@cindex filtering, by tag category and effort, in agenda @pxref{Filtering/limiting agenda items} for a detailed description of these
@cindex tag filtering, in agenda commands.}}
@cindex category filtering, in agenda
@cindex effort filtering, in agenda @orgcmd{/,org-agenda-filter-by-tag}
@cindex query editing, in agenda @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} @orgcmd{<,org-agenda-filter-by-category}
@vindex org-agenda-category-filter-preset @vindex org-agenda-category-filter-preset
Filter the current agenda view with respect to the category of the item at 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 point. Pressing @code{<} another time will remove this filter.
a filter preset through the option @code{org-agenda-category-filter-preset}
(see below.)
@orgcmd{|,org-agenda-filter-by-regexp} @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 @vindex org-agenda-regexp-filter-preset
Filter the agenda view by a regular expression: only show agenda entries 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 be accumulated. You can add a filter preset through the option
@code{org-agenda-category-filter-preset} (see below.) @code{org-agenda-category-filter-preset} (see below.)
@orgcmd{/,org-agenda-filter-by-tag} @orgcmd{|,org-agenda-filter-remove-all}
@vindex org-agenda-tag-filter-preset Remove all filters in the current agenda view.
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
@tsubheading{Remote editing} @tsubheading{Remote editing}
@cindex remote editing, from agenda @cindex remote editing, from agenda