todo-mode: Filtering Items
10.1 Filtering Items
====================
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:(1)
• ‘F x x’ (‘todo-filter-regexp-items’)
• ‘F x m’ (‘todo-filter-regexp-items-multifile’)
• ‘F y y’ (‘todo-filter-diary-items’)
• ‘F y m’ (‘todo-filter-diary-items-multifile’)
• ‘F t t’ (‘todo-filter-top-priorities’)
• ‘F t m’ (‘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’:
• The option ‘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.
• The option ‘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’.
• You can invoke ‘F t t’ and ‘F t m’ with a numeric prefix argument,
which specifies the number of top priorities in each category just
for this invocation, overriding both
‘todo-top-priorities-overrides’ and ‘todo-top-priorities’.
---------- Footnotes ----------
(1) 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.
Info Catalog
todo-mode: Todo Filtered Items Mode
todo-mode: Todo Filtered Items Mode Commands