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
parent
bccda67ce4
commit
57fa03b2da
311
doc/org.texi
311
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-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
|
||||
|
||||
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
|
||||
|
|
|
|||
Loading…
Reference in New Issue