Todo mode provides three ways to filter items: a general filter for
items matching a user-entered regular expression, as with the search
command; and two specific filters, one for diary-displayable items
(i.e., those lacking todo-nondiary-marker) and one for top
priority items (more on the latter below). The commands for each
filter come in pairs, one for filtering just the current todo file and
one for filtering a user-specified list of todo files. Thus, there
are six item filtering commands:9
todo-filter-regexp-items)
todo-filter-regexp-items-multifile)
todo-filter-diary-items)
todo-filter-diary-items-multifile)
todo-filter-top-priorities)
todo-filter-top-priorities-multifile)
There are two ways to specify which files the multifile filtering
commands apply to. If there are files you want to filter every time you
use these commands, customize the option todo-filter-files. If you
leave this option empty (the default), invoking a multifile filtering
command pops up a buffer similar to the Customization buffer for
todo-filter-files, in which you can select files to filter just for
this invocation.
Diary and top priority items are by definition non-done todo items, but
when filtering by regular expression, you can extend the scope of the
command to done items by enabling the option todo-filter-done-items.
Then F x x and F x m will gather both matching todo and matching
done items (including done items from any archive files corresponding to
the selected todo files) into the virtual category of filtered items.
There are several ways to specify how many items in each category count as top priorities and hence get filtered by F t t and F t m:
todo-top-priorities specifies a single default number
for all categories and all todo files; its default value is 1, which
means just the highest priority item in every category is filtered,
unless otherwise specified.
todo-top-priorities-overrides lists file-wide overrides
of todo-top-priorities as well as category-specific overrides. It
is empty by default. However, using the Custom facility to set this
option would be tedious and error-prone, so instead you should use the
commands F t s and C t s. The former sets (i.e., overrides) the
default number of top priorities for all categories in the current
todo file, and the latter sets the number of top priorities for the
current category. To exclude a category or file from filtering by F t t
and F t m, set the number to ‘0’.
todo-top-priorities-overrides and
todo-top-priorities.
The use of F in the key sequences of these commands naturally recalls “filter”, but is also consistent with the Todo mode mnemonic key binding convention, since the commands involve one or more whole files.