mirror of
https://git.savannah.gnu.org/git/emacs.git
synced 2024-12-17 10:06:13 +00:00
5c7dd8a783
Run admin/update-copyright.
1922 lines
81 KiB
Plaintext
1922 lines
81 KiB
Plaintext
\input texinfo.tex @c -*-texinfo-*-
|
|
@c %**start of header
|
|
@setfilename ../../info/todo-mode.info
|
|
@settitle Todo Mode User Manual
|
|
@include docstyle.texi
|
|
@syncodeindex fn cp
|
|
@syncodeindex vr cp
|
|
@syncodeindex ky cp
|
|
@c %**end of header
|
|
|
|
@copying
|
|
Copyright @copyright{} 2013-2018 Free Software Foundation, Inc.
|
|
|
|
@quotation
|
|
Permission is granted to copy, distribute and/or modify this document
|
|
under the terms of the GNU Free Documentation License, Version 1.3 or
|
|
any later version published by the Free Software Foundation; with no
|
|
Invariant Sections, with the Front-Cover Texts being ``A GNU Manual'',
|
|
and with the Back-Cover Texts as in (a) below. A copy of the license
|
|
is included in the section entitled ``GNU Free Documentation License''.
|
|
|
|
(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
|
|
modify this GNU manual.''
|
|
@end quotation
|
|
@end copying
|
|
|
|
@dircategory Emacs misc features
|
|
@direntry
|
|
* Todo Mode: (todo-mode). Make and maintain todo lists.
|
|
@end direntry
|
|
|
|
@titlepage
|
|
@title Todo Mode User Manual
|
|
@subtitle Facilities for making and maintaining todo lists.
|
|
|
|
@author Stephen Berman
|
|
@page
|
|
|
|
@vskip 0pt plus 1filll
|
|
@insertcopying
|
|
@end titlepage
|
|
|
|
@contents
|
|
|
|
@ifnottex
|
|
|
|
@node Top
|
|
@top Todo Mode User Manual
|
|
|
|
This manual describes the version of Todo mode first appearing in
|
|
Emacs 24.4.
|
|
|
|
@insertcopying
|
|
@end ifnottex
|
|
|
|
@menu
|
|
* Overview::
|
|
* Todo Mode Entry Points::
|
|
* Key Binding Conventions::
|
|
* Navigation:: Moving within and between categories.
|
|
* Editing:: Adding, deleting and changing todo
|
|
files, categories and items.
|
|
* Todo Archives:: Files of done todo items.
|
|
* Marked Items:: Acting on multiple items simultaneously.
|
|
* Todo Categories Mode:: Table of categories and item counts.
|
|
* Searching for Items::
|
|
* Todo Filtered Items Mode:: Making virtual categories of items from
|
|
different categories and files.
|
|
* Todo Display Features::
|
|
* Printing Todo Buffers::
|
|
* Legacy Todo Mode Files:: Converting old-style todo files.
|
|
|
|
* GNU Free Documentation License::
|
|
|
|
@detailmenu
|
|
--- The Detailed Node Listing ---
|
|
|
|
Overview
|
|
|
|
* Levels of Organization::
|
|
* Todo Items as Diary Entries::
|
|
|
|
Editing
|
|
|
|
* File Editing::
|
|
* Category Editing::
|
|
* Item Editing::
|
|
|
|
Item Editing
|
|
|
|
* Inserting New Items::
|
|
* Editing Item Headers and Text::
|
|
* Relocating and Removing Items::
|
|
|
|
Relocating and Removing Items
|
|
|
|
* Reprioritizing Items::
|
|
* Moving and Deleting Items::
|
|
* Done Items::
|
|
|
|
Todo Archives
|
|
|
|
* Creating and Visiting Archives::
|
|
* Todo Archive Mode::
|
|
|
|
Todo Categories Mode
|
|
|
|
* Table of Item Counts::
|
|
* Reordering Categories::
|
|
|
|
Todo Filtered Items Mode
|
|
|
|
* Filtering Items::
|
|
* Todo Filtered Items Mode Commands::
|
|
* Files of Filtered Items::
|
|
|
|
Todo Display Features
|
|
|
|
* Faces::
|
|
* Item Prefix::
|
|
* Other Display Commands and Options::
|
|
@end detailmenu
|
|
@end menu
|
|
|
|
@node Overview, Todo Mode Entry Points, Top, Top
|
|
@chapter Overview
|
|
|
|
The Todo mode package provides facilities for making and maintaining
|
|
todo lists. A todo list is a list of todo items---things to do (in the
|
|
widest sense)---arranged in order of priority, with the highest priority
|
|
item at the top of the list and the lowest priority item at the bottom.
|
|
|
|
This manual describes the Todo mode user interface. Todo mode comprises
|
|
a large number of commands and user options for creating, displaying,
|
|
navigating and editing todo lists, distributed across five major modes.
|
|
The principle major mode is Todo mode; the other four (Todo Edit mode,
|
|
Todo Archive mode, Todo Categories mode, and Todo Filtered Items mode)
|
|
are subsidiary to and accessible from Todo mode.
|
|
|
|
This version of Todo mode greatly expands on, and in significant ways
|
|
differs from, the original version; for details and consequences of the
|
|
most important differences, @ref{Legacy Todo Mode Files}.
|
|
|
|
@menu
|
|
* Levels of Organization::
|
|
* Todo Items as Diary Entries::
|
|
@end menu
|
|
|
|
@node Levels of Organization, Todo Items as Diary Entries, , Overview
|
|
@section Levels of Organization
|
|
|
|
In Todo mode each todo list is identified with a named category, so you
|
|
can group together thematically related todo items. Each category is
|
|
stored in a file, which thus provides a further level of organization.
|
|
You can create as many todo files, and in each as many categories, as
|
|
you want.
|
|
|
|
All todo files reside in a single directory, whose location is specified
|
|
by the user option @code{todo-directory}. This directory may also
|
|
contain other types of Todo files, which are discussed later
|
|
(@pxref{Todo Archive Mode} and @ref{Todo Filtered Items Mode}).
|
|
@c Emacs recognizes Todo files by their extension, so when you visit
|
|
@c the files the buffer is in the appropriate mode and the current
|
|
@c category is correctly displayed.
|
|
When you use a Todo mode command to create a todo file, the extension
|
|
@samp{.todo} is automatically added to the base name you choose (as a
|
|
rule, this name is also used for the other types of Todo files, which
|
|
have their own extensions). As a user, you only have to deal with the
|
|
base name of a Todo file.
|
|
|
|
When you create a new todo file, you must also add at least one category
|
|
to it, and each todo item belongs to a category. It is not possible to
|
|
have an uncategorized todo list, but you can always make a catch-all
|
|
category with a generic name like ``Todo'', which is in fact the default
|
|
name assigned to the first category when you create a new todo file, if
|
|
you don't provide a different name; you can change the default by
|
|
customizing @code{todo-initial-category}.
|
|
|
|
The most basic level of organization is the todo item itself, since it
|
|
contains the information about what you want to do. As detailed in
|
|
subsequent sections of this manual, most Todo mode commands and user
|
|
options concern ways of classifying and deploying this information by
|
|
associating various kinds of metadata with it, e.g., the category it
|
|
belongs to, its priority, whether it is to be included in the Emacs
|
|
diary, date and time stamps, whether it is done or still to do.
|
|
|
|
@node Todo Items as Diary Entries, , Levels of Organization, Overview
|
|
@section Todo Items as Diary Entries
|
|
|
|
You can have todo items show up in the Emacs Fancy Diary display by
|
|
including the todo file in your diary file (@pxref{Fancy Diary
|
|
Display,,, emacs}). This effectively augments the Emacs diary with
|
|
categorized diary entries. All items in an included todo file will
|
|
appear in the Fancy Diary display except for those that are marked
|
|
with @code{todo-nondiary-marker}. You can add or omit this marking
|
|
upon creating a new todo item, or you can do so by editing an existing
|
|
item, see @ref{Inserting New Items} and @ref{Editing Item Headers and
|
|
Text} for details.
|
|
|
|
To ensure the proper display of todo items in the Fancy Diary display,
|
|
they must have the format of diary entries, i.e., they have to begin
|
|
with a date string recognized by the Emacs diary,@footnote{Two types of
|
|
dates recognized by the Emacs diary are not supported in the current
|
|
Todo mode implementation: sexp diary entries and date strings in which
|
|
the year is omitted (however, the latter type is equivalent to using
|
|
@samp{*} for an arbitrary year, which Todo mode does support).} and if
|
|
they are longer than one line, all lines but the first must begin with
|
|
white space. Todo mode ensures that these requirements are satisfied
|
|
(@pxref{Other Display Commands and Options}).
|
|
|
|
The Fancy Diary display is also Todo mode aware: if it contains an item
|
|
from a Todo mode file, clicking or typing @key{RET} on this item will
|
|
switch to the buffer visiting that file and properly display the item's
|
|
category, with point on the item.
|
|
|
|
@node Todo Mode Entry Points, Key Binding Conventions, Overview, Top
|
|
@chapter Todo Mode Entry Points
|
|
|
|
To initialize your first todo file, invoke the command @code{todo-show}.
|
|
This prompts you for a file name (defaulting to the value of
|
|
@code{todo-initial-file}), prompts you for the name of the first
|
|
category (defaulting to the value of @code{todo-initial-category}),
|
|
creates and visits the file and displays the category in Todo mode, and
|
|
then prompts you to enter the first item. If you choose not to enter an
|
|
item now, simply type @kbd{C-g}, which leaves the category empty but
|
|
otherwise well-formed. If you prefer not to be prompted to enter an
|
|
item on adding a new category, disable the option
|
|
@code{todo-add-item-if-new-category}.
|
|
|
|
Once at least one todo file exists, invoking @code{todo-show} enters
|
|
Todo mode. Invoked with a prefix argument, the command prompts for
|
|
which todo file to visit. Otherwise, the first invocation of this
|
|
command after loading the Todo mode package visits the default todo file
|
|
(option @code{todo-default-todo-file}) and shows its first category.
|
|
(You can get a different display with the first invocation of
|
|
@code{todo-show} by customizing the option @code{todo-show-first};
|
|
@pxref{Todo Categories Mode} and @ref{Files of Filtered Items}.)
|
|
|
|
If you leave Todo mode and later invoke @code{todo-show} to re-enter it,
|
|
by default this returns you to the current (i.e., last displayed)
|
|
category of the current todo file, which is the one in the most recently
|
|
selected and still live buffer visiting a todo file. If you disable the
|
|
option @code{todo-show-current-file}, then non-initial invocations of
|
|
@code{todo-show} always return to the first or current category of the
|
|
default todo file.
|
|
|
|
If you want to enter Todo mode and go directly to a specific category
|
|
instead the first or current category in the current or default todo
|
|
file, use the command @code{todo-jump-to-category}; @ref{Navigation},
|
|
for details. You can also enter Todo mode by invoking the command
|
|
@code{todo-insert-item}; @ref{Inserting New Items}, for details.
|
|
|
|
The most convenient way to use these commands to enter Todo mode is to
|
|
define global key bindings for them in your init file. Good choices
|
|
are @kbd{C-c t} for @code{todo-show}, @kbd{C-c j} for
|
|
@code{todo-jump-to-category} and @kbd{C-c i} for
|
|
@code{todo-insert-item}, since these commands are bound to @kbd{t},
|
|
@kbd{j} and @kbd{i}, respectively, in Todo mode.
|
|
|
|
@c You can also visit a Todo file via @code{find-file} or Dired, like any
|
|
@c other file, and since Emacs recognizes it, the buffer will automatically
|
|
@c be in the appropriate Todo mode. Moreover, as long as the command you
|
|
@c use to visit the file is listed in the option
|
|
@c @code{todo-visit-files-commands} (which by default contains
|
|
@c @code{find-file} and @code{dired-find-file}), it will also correctly
|
|
@c display the file's first category on first visiting the file (otherwise
|
|
@c you have to use one of the commands for navigating between categories in
|
|
@c order to get a proper display).
|
|
|
|
You can leave Todo mode by typing @kbd{q} (@code{todo-quit}), which
|
|
buries the current todo file buffer. Doing this also saves any changes
|
|
you have made to the file, and leaves both the file and the category
|
|
that was displayed on quitting current for subsequent Todo mode commands
|
|
(unless the buffer made current by quitting is visiting another file and
|
|
category in Todo mode, in which case the latter become current for Todo
|
|
mode commands).
|
|
|
|
@node Key Binding Conventions, Navigation, Todo Mode Entry Points, Top
|
|
@chapter Key Binding Conventions
|
|
|
|
For Todo mode commands to function properly, it is essential to maintain
|
|
the correct format at all three levels of organization---item, category,
|
|
and file. Todo mode tries to minimize the risk of format corruption by
|
|
hiding certain parts of the format from the user, making the buffer
|
|
read-only and suppressing the self-insertion keys. Consequently, it is
|
|
normally impossible to make changes to your todo files without
|
|
explicitly invoking Todo mode commands.
|
|
|
|
A beneficial side effect of this restrictiveness is that you can invoke
|
|
almost all Todo commands by typing ordinary printing characters, either
|
|
singly or in specified sequences, without using modifier keys, except
|
|
for the shift key for capitalization and the raw prefix argument
|
|
@kbd{C-u}; numeric prefix arguments can be entered just by typing a
|
|
number key.
|
|
|
|
The predefined key bindings in Todo are more or less mnemonic. As a
|
|
rule, key sequences beginning with @kbd{C} (capital @samp{C}, not the
|
|
control key) are bound to commands applying to categories, sequences
|
|
beginning with @kbd{F} apply to (non-archive) file-level commands, and
|
|
those beginning with @kbd{A} apply to archives (a special type of Todo
|
|
file; @ref{Todo Archive Mode}). Todo commands applying to items,
|
|
which constitute the majority, are bound to lower case key sequences.
|
|
|
|
@node Navigation, Editing, Key Binding Conventions, Top
|
|
@chapter Navigation
|
|
|
|
The navigation commands are for making another todo file, category, or
|
|
item the current one by moving point to it.@footnote{Many editing
|
|
commands can also do this by side effect, but since that is not their
|
|
main function, they are not included in this section.} Since these
|
|
commands are likely to be used frequently and repetitively, it is
|
|
convenient for their key bindings to be single lower case keys, even for
|
|
navigation commands applying to categories and files.
|
|
|
|
Two of the navigation commands were already mentioned in @ref{Todo
|
|
Mode Entry Points}:
|
|
|
|
@table @kbd
|
|
|
|
@item t
|
|
Display another todo file in the selected window (@code{todo-show}).
|
|
When you invoke this command in Todo mode, it prompts for a file name,
|
|
which you can choose via minibuffer completion (like invoking
|
|
@code{todo-show} with a prefix argument outside of Todo mode). If a
|
|
buffer is already visiting that file, it displays its current category;
|
|
if invoking @kbd{t} opens the file, it display its first category (by
|
|
default; see the option @code{todo-show-first} for other possibilities).
|
|
|
|
@item j
|
|
Display another todo category in the selected window
|
|
(@code{todo-jump-to-category}). When you invoke this command, it
|
|
prompts for a category name, which you can choose via minibuffer
|
|
completion. The candidates for completion include the categories in the
|
|
current todo file as well as those in the files listed in the option
|
|
@code{todo-category-completions-files}. If you type @key{RET} without
|
|
choosing a category, the current category of the current todo file is
|
|
automatically selected (this can be a useful shortcut when you invoke
|
|
@code{todo-jump-to-category} outside of Todo mode). If you type the
|
|
name of a non-existing category, you can add this to the file as a new
|
|
category and jump to it. If you invoke this command with a prefix
|
|
argument, it first you prompts for which todo file to jump to (which you
|
|
can also choose with minibuffer completion) and then for which category
|
|
from that file; in this case, completion is only against the categories
|
|
in the selected file.
|
|
@end table
|
|
|
|
It is also convenient to navigate back and forth sequentially between
|
|
the categories of a single todo file. The categories of a todo file are
|
|
numbered consecutively starting with @samp{1}.@footnote{A category's
|
|
number is automatically assigned when the category is created: the
|
|
category is appended to the end of the file, so its number is simply the
|
|
highest until another category is added. There is no command in Todo
|
|
mode to reorder the numbering of the categories in a todo file, but this
|
|
is possible from the file's table of categories; @ref{Todo Categories
|
|
Mode}.} The current category's number and name appear in the mode line.
|
|
|
|
@table @kbd
|
|
|
|
@item f
|
|
Move point to the first item of the category numerically directly
|
|
following the current category (@code{todo-forward-category}).
|
|
|
|
@item b
|
|
Move point to the first item of the category numerically directly
|
|
preceding the current category (@code{todo-backward-category}).
|
|
@end table
|
|
|
|
With @kbd{f} and @kbd{b} you can cycle through the categories, so for example,
|
|
if the last category is current and you type @kbd{f}, then the first
|
|
category becomes current.
|
|
|
|
You can also navigate between the items in the current category:
|
|
|
|
@table @kbd
|
|
|
|
@item n
|
|
Move point down to the next item below the current one (i.e., to the
|
|
item with the next lower priority) (@code{todo-next-item}).
|
|
|
|
@item p
|
|
Move point up to the item directly above the current one (i.e., to the
|
|
item with the next higher priority) (@code{todo-previous-item}).
|
|
@end table
|
|
|
|
These commands also accept a positive numeric prefix argument; e.g.,
|
|
typing @kbd{5 n} or @kbd{5 p} navigates in one step to the item five items lower
|
|
or higher than the current one.
|
|
|
|
Navigation to other types of Todo files is discussed in the relevant
|
|
sections below.
|
|
|
|
@node Editing, Todo Archives, Navigation, Top
|
|
@chapter Editing
|
|
|
|
Editing in Todo mode means making structural or textual changes at one
|
|
of the levels of organization (file, category, or item). Structural
|
|
editing includes adding, relocating and removing units of information
|
|
at a level; textual editing includes renaming files or categories and
|
|
changing an item's content or date/time stamp, or adding certain kinds
|
|
of marks or tags to items. Todo mode provides commands, detailed in
|
|
the following sections, which enable you to quickly and safely make
|
|
changes to your todo lists, without having to worry about preserving
|
|
the file format.
|
|
|
|
To save changes you make to the current todo file,
|
|
type @kbd{s} (@code{todo-save}). Changes are also saved on quitting
|
|
Todo mode with @kbd{q}.
|
|
|
|
@menu
|
|
* File Editing::
|
|
* Category Editing::
|
|
* Item Editing::
|
|
@end menu
|
|
|
|
@node File Editing, Category Editing, , Editing
|
|
@section File Editing and Todo Edit Mode
|
|
|
|
There are four file-level editing commands:
|
|
|
|
@table @kbd
|
|
|
|
@item F a
|
|
Add a new todo file (@code{todo-add-file}). This command prompts for
|
|
a name and creates the file in @code{todo-directory}, adding the
|
|
@samp{.todo} extension (so you should not include the extension in the
|
|
name you enter). The command also prompts for the file's first
|
|
category and, if option @code{todo-add-item-if-new-category} is
|
|
enabled (the default), for that category's first item.
|
|
|
|
@item F r
|
|
Rename the current todo file (@code{todo-rename-file}). If called with
|
|
a prefix argument, prompt for a todo file and rename it. If the todo
|
|
file has an archive (@pxref{Todo Archive Mode}) or there are
|
|
corresponding filtered items files (@pxref{Todo Filtered Items Mode}),
|
|
this command renames these accordingly. If there are live buffers
|
|
visiting any of these files, the command also renames them accordingly.
|
|
|
|
@item F k
|
|
Delete the current todo file (@code{todo-delete-file}).@footnote{The key
|
|
binding of this command is mnemonic for ``kill'' to parallel the binding
|
|
@kbd{k} for item deletion, since @kbd{d} is bound to another item
|
|
editing command (@pxref{Done Items}).} If the todo file has an archive
|
|
(@pxref{Todo Archive Mode}), prompt for whether to delete that as well.
|
|
This command also kills the buffers visiting the deleted files.
|
|
|
|
@item F e
|
|
This command (@code{todo-edit-file}) changes the buffer's major mode to
|
|
Todo Edit mode. In this mode the entire file is visible, the buffer is
|
|
writable and you can use the self-insertion keys and standard Emacs
|
|
editing commands to make changes. To return to Todo mode, type @kbd{C-x
|
|
C-q} (@code{todo-edit-quit}).
|
|
|
|
The command @kbd{F e} is not intended for normal editing of items and
|
|
categories, as it circumvents the restrictions that Todo imposes to
|
|
protect against file format corruption (i.e., all categories, not just
|
|
the current one, and all internal formatting are exposed and editable).
|
|
It is provided primarily as a convenience for two types of use cases
|
|
that are likely to arise infrequently. One is to be able to use
|
|
standard Emacs commands like @code{query-replace} to replace a piece of
|
|
text that occurs in different categories throughout the file. The other
|
|
use case is to recover from a mistake, such as accidentally deleting an
|
|
item, since this cannot be undone in Todo mode.
|
|
|
|
Using @kbd{C-x C-q} to quit Todo Edit mode provides a measure of
|
|
safety, since it runs a file format check, signaling an error if the
|
|
format has become invalid. However, this check cannot tell if the
|
|
number of items or categories changed, which could result in the file
|
|
containing inconsistent information (see the cautionary note in
|
|
@ref{Reordering Categories}, for more details). Invoking @kbd{F e}
|
|
displays a warning to this effect.
|
|
@end table
|
|
|
|
@node Category Editing, Item Editing, File Editing, Editing
|
|
@section Category Editing
|
|
|
|
The following commands are available for editing specifically at the
|
|
category level (for two other category-editing commands, which are
|
|
extensions of item commands, @pxref{Editing Item Headers and Text}):
|
|
|
|
@table @kbd
|
|
|
|
@item C a
|
|
Add a new category to the current todo file and make that category
|
|
current (@code{todo-add-category}). If called with a prefix argument,
|
|
prompt for a file name and add the new category to that file. This
|
|
command is similar to using @kbd{j}, but it only accepts category names
|
|
that are not the name of an existing category in the file.
|
|
|
|
@item C r
|
|
Rename the current category (@code{todo-rename-category}). If this
|
|
category's file has an archive (@pxref{Todo Archive Mode}) with a
|
|
corresponding category, rename the category there as well.
|
|
|
|
@item C m
|
|
Move the current category (with all its items) to another todo file
|
|
(@code{todo-move-category}). If this category's file has an archive
|
|
(@pxref{Todo Archive Mode}) with a corresponding category, this command
|
|
also moves that category to the archive file corresponding to the moved
|
|
to todo file; if there is no such archive file, the command creates it
|
|
and adds the category.
|
|
|
|
@item C k
|
|
Delete the current category (@code{todo-delete-category}).@footnote{This
|
|
binding is mnemonic for ``kill'' to parallel the binding @kbd{k} for
|
|
item deletion, since @kbd{d} is bound to another item editing command
|
|
(@pxref{Done Items}).} To delete a category that contains items, you
|
|
have to confirm your intent; if the category is empty, deletion is
|
|
immediate.
|
|
|
|
@item C g
|
|
Merge the items of one category into another category, delete the first
|
|
category and make the second category current
|
|
(@code{todo-merge-category}). If both the first and second categories
|
|
also have archived items (@pxref{Todo Archive Mode}), merge the former
|
|
to the latter. If only the first category has archived items, rename
|
|
the archive category to the merged to category. Minibuffer completion
|
|
of the name of the category merged to works as with the navigation
|
|
command @kbd{j}, and as with that command, passing a prefix argument,
|
|
i.e., typing @kbd{C-u C g}, prompts for a file and confines merging to a
|
|
category in that file.
|
|
@end table
|
|
|
|
@node Item Editing, , Category Editing, Editing
|
|
@section Item Editing
|
|
|
|
Todo mode provides commands for adding new items as well as textually
|
|
changing, deleting and relocating existing items. The commands and
|
|
associated options for adding and editing items, in particular, offer
|
|
you a lot of flexibility to fine-tune these operations to your needs.
|
|
|
|
@menu
|
|
* Inserting New Items::
|
|
* Editing Item Headers and Text::
|
|
* Relocating and Removing Items::
|
|
@end menu
|
|
|
|
@node Inserting New Items, Editing Item Headers and Text, , Item Editing
|
|
@subsection Inserting New Items
|
|
|
|
To add a new todo item to a category, type @kbd{i}, which is bound to
|
|
the command @code{todo-insert-item}.
|
|
|
|
@table @kbd
|
|
|
|
@item i
|
|
This command is the entry point for inserting new items into a
|
|
category (@code{todo-insert-item}). It prompts for additional keys
|
|
until reaching a complete key sequence, which specifies the insertion
|
|
parameters you wish to apply (see below). It then prompts for the
|
|
text of the item, which you enter in the minibuffer.@footnote{There
|
|
are two insertion parameters that override prompting for and manually
|
|
entering the new item's text, see below.} Called with one prefix
|
|
argument, it also prompts for a category, and called with two prefix
|
|
arguments, it prompts for both a file and a category from that file,
|
|
and inserts the item accordingly; category name completion works as
|
|
with the navigation command @kbd{j}. Finally, it inserts the item
|
|
into the current or selected category of the current or selected todo
|
|
file at the position in the list corresponding to the priority you
|
|
choose, which also depends on the insertion parameters.
|
|
@end table
|
|
|
|
@noindent
|
|
The name of this command reflects the fact that you can insert a new
|
|
item into the category at any position, giving each new item any
|
|
priority in the list, whereas speaking of adding an item to a category
|
|
suggests appending it to the top or bottom.
|
|
|
|
In addition to its file and category, each newly inserted todo item
|
|
has a priority in the category and begins with a header string, which
|
|
includes at least the current date in the same format used by
|
|
@code{diary-insert-entry} (@pxref{Date Formats,,, emacs}). You can
|
|
specify the priority and the content of the header string in two ways.
|
|
First, you can set the following item insertion options, which apply
|
|
on every invocation of @code{todo-insert-item}.
|
|
|
|
@itemize @bullet
|
|
|
|
@item
|
|
@code{todo-default-priority} is for automatically assigning a new item
|
|
the highest or lowest priority in the category, if you do not
|
|
explicitly assign it a priority on invoking @code{todo-insert-item}.
|
|
By default, such new items are given highest priority, i.e., inserted
|
|
at the top of the list.
|
|
|
|
@item
|
|
@code{todo-always-add-time-string} is for including or omitting the
|
|
current time in the new item's header. By default, this time string
|
|
is omitted.
|
|
|
|
@item
|
|
@code{todo-include-in-diary} is for specifying whether the item
|
|
appears in the Fancy Diary display (when the todo file is included in
|
|
the Emacs diary file) by adding or omitting
|
|
@code{todo-nondiary-marker}. By default, new todo items are so
|
|
marked, thus excluded from the diary.
|
|
|
|
@item
|
|
@code{todo-diary-nonmarking} is for adding or omitting
|
|
@code{diary-nonmarking-symbol} to items displayed in the diary, to
|
|
control whether they are marked in the calendar (@pxref{Format of
|
|
Diary File,,, emacs}). By default, todo items that are diary entries
|
|
lack this symbol, thus are marked in the calendar.
|
|
@end itemize
|
|
|
|
Beside setting these options, for more flexibility you can also pass
|
|
certain parameters on each invocation of @code{todo-insert-item}.
|
|
These parameters concern not only the new item's priority and header,
|
|
but also its textual content. You pass these parameters by typing a
|
|
sequence of one or more keys after the initial @kbd{i}.
|
|
|
|
Here is a list of the item insertion parameters together with their
|
|
mnemonically associated keys@footnote{The non-mnemonic choice of
|
|
@kbd{i} for the parameter @samp{default} is motivated by the
|
|
convenience of repeating the @kbd{i} used to invoke
|
|
@code{todo-insert-item}.} and descriptions of their effect in
|
|
@code{todo-insert-item}:
|
|
|
|
@enumerate
|
|
|
|
@item
|
|
@samp{default} (@kbd{i}): Prompt for the new item's priority
|
|
(a number between 1 and one more than the number of items already in
|
|
the category) and add a header string conforming to the values of the
|
|
above options.
|
|
|
|
@samp{copy} (@kbd{p}): Make an exact copy of the item at point,
|
|
including its header string, and prompt for its priority. (This is
|
|
useful for quickly making a new todo item whose text or header you
|
|
want to differ only partly from that of an existing item: after
|
|
inserting the copy, you can quickly edit it as needed by using
|
|
operations described in the next section.)
|
|
|
|
@item
|
|
@samp{diary} (@kbd{y}): Override the option
|
|
@code{todo-include-in-diary}; that is, add @code{todo-nondiary-marker}
|
|
if the option is non-@code{nil}, omit this marker if the option is @code{nil}.
|
|
|
|
@samp{nonmarking} (@kbd{k}): Override the option
|
|
@code{todo-diary-nonmarking}; that is, add
|
|
@code{diary-nonmarking-symbol} if the option is non-@code{nil}, omit this
|
|
symbol if the option is @code{nil}. Since this symbol only applies to diary
|
|
items, the new item is automatically marked as such, i.e., lacks
|
|
@code{todo-nondiary-marker}.
|
|
|
|
@item
|
|
@samp{calendar} (@kbd{c}): Pop up the Emacs calendar and click a date
|
|
in it to use that date in the new todo item's header.
|
|
|
|
@samp{date} (@kbd{d}): Prompt for entering in the minibuffer
|
|
the year, month (with completion) and day number components of the
|
|
header.
|
|
|
|
@samp{dayname} (@kbd{n}): Prompt for entering in the minibuffer
|
|
a weekday name as the date header instead of a year-month-day string.
|
|
|
|
@item
|
|
@samp{time} (@kbd{t}): Prompt for entering a time string in
|
|
the minibuffer instead of automatically inserting the current time;
|
|
however, typing @key{RET} at the prompt enters the current time if
|
|
@code{todo-always-add-time-string} is non-@code{nil}, otherwise it enters the
|
|
empty string (i.e., no time string).
|
|
|
|
@item
|
|
@samp{here} (@kbd{h}): Insert the new item in the position of
|
|
the item at point, pushing that and all lower items in the category
|
|
down, i.e., lowering their priority, by one.
|
|
|
|
@samp{region} (@kbd{r}): Use the text of the selected region as the
|
|
text of the new item, and insert this in accordance with the item
|
|
insertion options and other parameters passed. If the option
|
|
@code{todo-use-only-highlighted-region} is non-@code{nil}, then use the
|
|
region only when it is highlighted; otherwise, use the region
|
|
regardless of highlighting.
|
|
@end enumerate
|
|
|
|
Note that the parameters are divided into five numbered groups; within
|
|
a group, the parameters are mutually exclusive. Hence, to build a
|
|
complete insertion operation, you select at most one parameter from at
|
|
least one of these groups, by typing the corresponding key. If you
|
|
want to apply more than one parameter, you must type the corresponding
|
|
keys in the order of the numbered groups, subject to the following
|
|
constraints.
|
|
|
|
The keys of groups 2-4 are continuation keys, that is, each can be
|
|
followed by a key from a following group. If you want to finish the
|
|
sequence with a continuation key, you must double the final key. For
|
|
example, @kbd{i y} is not a complete key sequence; rather, you must
|
|
type @kbd{i y y}.
|
|
|
|
By contrast, the keys of groups 1 and 5 are final keys; for example,
|
|
@kbd{i i} and @kbd{i h} are complete sequences. The reason for making
|
|
two separate groups of the final keys is that the parameters
|
|
@samp{default} and @samp{copy} cannot be combined with any other
|
|
parameters, while @samp{here} and @samp{region} can be combined with
|
|
any of the parameters from groups 2-4.
|
|
|
|
To aid you in building item insertion key sequences, when you type an
|
|
insertion key, this displays a prompt in the echo area showing pairs
|
|
of the remaining possible keys and their associated parameters,
|
|
grouped and ordered in accordance with the above list. The initial
|
|
prompt, after typing @kbd{i} to invoke @code{todo-insert-item}, looks
|
|
like this:
|
|
|
|
@example
|
|
Press a key (so far @kbd{i}): @{ i=>default p=>copy @} @{ y=>diary k=>nonmarking @} @{ c=>calendar d=>date n=>dayname @} t=>time @{ h=>here r=>region @}
|
|
@end example
|
|
|
|
@noindent If you now type @kbd{y}, the prompt changes to this:
|
|
|
|
@example
|
|
Press a key (so far @kbd{i y}): y=>diary:GO! @{ c=>calendar d=>date n=>dayname @} t=>time @{ h=>here r=>region @}
|
|
@end example
|
|
|
|
@noindent Notice that the pair @samp{k=>nonmarking} is now absent, since it
|
|
belongs to the same group as the selected pair @samp{y=>diary}, hence
|
|
is no longer available for this sequence. Since @kbd{y} is a
|
|
continuation key, it is still available, but now the string
|
|
@samp{:GO!} is appended to the pair to remind you that pressing this
|
|
key again will complete the sequence.
|
|
|
|
|
|
|
|
@c Here are some examples of item insertion command key sequences:
|
|
|
|
@c @itemize @bullet
|
|
|
|
@c @item
|
|
@c @kbd{i h} inserts a new item at the position of the item at point (pushing
|
|
@c the latter down) with a header containing the current date and,
|
|
@c depending on the values of the mentioned options, possibly the current
|
|
@c time and diary-related markings.
|
|
@c @item
|
|
@c @kbd{i y h} does the same as the preceding command, except that
|
|
@c @code{todo-nondiary-marker} is added if @code{todo-include-in-diary} is
|
|
@c non-@code{nil} and omitted if that option is @code{nil}; that is,
|
|
@c the diary key @kbd{y} @c overrides the setting of this option.
|
|
@c @item
|
|
@c @kbd{i y t h} does the same as the preceding command, except that it
|
|
@c prompts for a time string instead of automatically inserting the
|
|
@c current time; however, typing @key{RET} at the prompt returns the
|
|
@c current time if @code{todo-always-add-time-string} is non-@code{nil},
|
|
@c otherwise the empty string (i.e., no time string).
|
|
@c @item
|
|
@c @kbd{i y t t} does the same as the preceding command, except that it
|
|
@c prompts for the item's priority and inserts it accordingly.
|
|
@c @end itemize
|
|
|
|
|
|
An alternative to the key sequence @kbd{i c c} for choosing the item's
|
|
date from the calendar is also available: when point is already on a
|
|
date in the calendar, typing @kbd{i t}
|
|
(@code{todo-insert-item-from-calendar}) prompts for a new item and its
|
|
priority and inserts it in the current category. This command, like
|
|
@code{todo-insert-item}, also accepts one or two prefix arguments for
|
|
choosing the category via minibuffer completion. Note, however, that
|
|
the key sequence @kbd{i t} is not defined in Todo mode but in the
|
|
Calendar mode keymap. It is a convenient shortcut if you happen to be
|
|
using the calendar when you decide to make a new todo item. (Contrast
|
|
this with passing the @samp{calendar} parameter, which pops open the
|
|
calendar after you have entered the item's text, and then you can
|
|
choose a date from the calendar.)
|
|
|
|
|
|
@node Editing Item Headers and Text, Relocating and Removing Items, Inserting New Items, Item Editing
|
|
@subsection Editing Item Headers and Text
|
|
|
|
To make changes to an existing item's content or header, type @kbd{e},
|
|
which is bound to the command @code{todo-edit-item}.
|
|
|
|
@table @kbd
|
|
|
|
@item e
|
|
This command is the entry point for textually editing existing items
|
|
in a category (@code{todo-edit-item}). It prompts for additional keys
|
|
until reaching a complete key sequence, which specifies the editing
|
|
parameters you wish to apply (see below), and then executes the
|
|
editing operation accordingly.
|
|
@end table
|
|
|
|
Here is a list of the item editing parameters together with their
|
|
mnemonically associated keys and descriptions of their effect in
|
|
@code{todo-edit-item}. The list is divided into three groups, for
|
|
reasons explained below.
|
|
|
|
@enumerate 1
|
|
|
|
@item
|
|
@samp{edit} (@kbd{e}): Edit the text of the current item in the
|
|
minibuffer; the item's header is omitted.
|
|
|
|
@samp{header} (@kbd{h}): Edit the text and header of the current item
|
|
in the minibuffer.
|
|
|
|
@samp{multiline} (@kbd{m}): Edit the text of the current item in a
|
|
special buffer in Todo Edit mode. After editing, type @kbd{C-x C-q}
|
|
to return to Todo mode.@footnote{This runs a format check to ensure
|
|
the item is well-formed. However, unlike the command @kbd{F e}
|
|
(@pxref{File Editing}), @kbd{e m} does not expose you to the risk of
|
|
putting the file in an inconsistent state, since it puts only the
|
|
current item in Todo Edit mode.}
|
|
|
|
@samp{diary} (@kbd{y}): Change the current item's diary inclusion
|
|
status by adding @code{todo-nondiary-marker} if the item lacks this,
|
|
or by removing it if present.
|
|
|
|
@samp{nonmarking} (@kbd{k}): Change the current item's calendar
|
|
marking status by adding @code{diary-nonmarking-symbol} if the item
|
|
lacks this, or by removing it if present. Since this symbol only
|
|
applies to diary items, the item is automatically marked as such,
|
|
i.e., if @code{todo-nondiary-marker} is present, it is removed.
|
|
|
|
@samp{date} (@kbd{d}): Prompt for a final key from the second group
|
|
of item editing parameters to edit the current item's date string.
|
|
|
|
@samp{time} (@kbd{t}): Edit the current item's time string, if
|
|
present; otherwise, add one. Typing @key{RET} at the prompt enters
|
|
the current time if @code{todo-always-add-time-string} is non-@code{nil},
|
|
otherwise it enters the empty string (i.e., no time string).
|
|
@end enumerate
|
|
|
|
@noindent
|
|
Editing the text of a lengthy item in the minibuffer can be
|
|
inconvenient; therefore, if you type @kbd{e e} or @kbd{e h} on an item
|
|
whose text contains more than one logical line, the effect is the same
|
|
as if you had typed @kbd{e m}, that is, you switch a special buffer in
|
|
Todo Edit mode.
|
|
|
|
When you pass any of the parameters of the preceding group, except for
|
|
the @samp{date} parameter, this completes the item editing invocation
|
|
begun by typing @kbd{e}. Pressing @kbd{d} to pass the @samp{date}
|
|
parameter, however, prompts you with the following parameters and
|
|
their associated keys, and pressing any of these completes the
|
|
invocation.
|
|
|
|
@enumerate 2
|
|
|
|
@item
|
|
@samp{full} (@kbd{f}): Successively prompt for editing the year, month
|
|
(with completion) and day number parts of the current item's date
|
|
string, and, if the option @code{todo-always-add-time-string} is
|
|
non-@code{nil}, also for editing its time string.
|
|
|
|
@samp{calendar} (@kbd{c}): This pops up the Emacs calendar, and after
|
|
you type @key{RET} on a date in the calendar makes that date the
|
|
item's date.
|
|
|
|
@samp{today} (@kbd{a}): Make the item's date today's date.
|
|
|
|
@samp{dayname} (@kbd{n}): Prompt for a weekday name (with completion)
|
|
and make it the item's date header. Note that this replaces an
|
|
existing date string, it does not add the day name to the date string.
|
|
|
|
@samp{year} (@kbd{y}): Edit just the year component of the current
|
|
item's date string.
|
|
|
|
@samp{month} (@kbd{m}): Edit just the month component of the current
|
|
item's date string (with completion).
|
|
|
|
@samp{daynum} (@kbd{d}): Edit just the day number component of the
|
|
current item's date string.
|
|
@end enumerate
|
|
|
|
@noindent
|
|
With the latter three parameters you can add a positive or negative
|
|
numeric prefix argument to the invocation: this increments or
|
|
decrements the selected date component by the given number and
|
|
automatically adjusts the other date components if necessary. For
|
|
example, if the item's date string is ``January 1, 2013'', then typing
|
|
@kbd{- 3 e d d} results in ``December 29, 2012''.
|
|
|
|
The first two groups of parameters apply only to todo items that are
|
|
not marked as done (@pxref{Done Items}); the two parameters of the
|
|
third group, in contrast, apply only to done todo items. You cannot
|
|
edit the text of such items, but you can edit or delete the comment
|
|
you may have added on marking the item as done (@pxref{Done Items,
|
|
@code{todo-item-done}},), or retroactively add a comment, by passing
|
|
either of these parameters.
|
|
|
|
@enumerate 3
|
|
|
|
@item
|
|
@samp{add/edit comment} (@kbd{c}): Edit the current done item's
|
|
comment, if it has one; otherwise, prompt for and add a comment.
|
|
|
|
@samp{delete comment} (@kbd{d}): Delete the current done item's
|
|
comment, if it has one.
|
|
@end enumerate
|
|
|
|
The command @code{todo-edit-item} is sensitive to the distinction
|
|
between not done and done todo items. If you type @kbd{e} when point
|
|
is on a done item, this displays the following prompt in the echo
|
|
area:
|
|
|
|
@example
|
|
Press a key (so far @kbd{e}): c=>add/edit comment d=>delete comment
|
|
@end example
|
|
|
|
@noindent
|
|
Only by typing @kbd{c} or @kbd{d} in response to this prompt can you
|
|
complete the invocation. In contrast, if you type @kbd{e} when point
|
|
is on a non-done todo item, this displays the following prompt in the
|
|
echo area, and you can continue or complete the invocation only by
|
|
typing one of the listed keys:
|
|
|
|
@example
|
|
Press a key (so far @kbd{e}): e=>edit h=>header m=>multiline y=>diary k=>nonmarking d=>date t=>time
|
|
@end example
|
|
|
|
As noted above, passing the @samp{date} parameter does not complete
|
|
the invocation of @code{todo-edit-item}; rather, it displays the
|
|
following prompt, and typing any of these keys does complete the
|
|
invocation:
|
|
|
|
@example
|
|
Press a key (so far @kbd{e d}): f=>full c=>calendar a=>today n=>dayname y=>year m=>month d=>daynum
|
|
@end example
|
|
|
|
In addition to the item-level invocations @kbd{e y}, to change the
|
|
current item's diary inclusion status, and @kbd{e k}, to change the
|
|
current item's calendar marking status, Todo mode also has two related
|
|
category-level commands:
|
|
|
|
@table @kbd
|
|
|
|
@item C e y
|
|
@itemx C e k
|
|
Add @code{todo-nondiary-marker} and @code{diary-nonmarking-symbol},
|
|
respectively, to all todo items in the current category; if invoked with
|
|
a prefix argument, these markings are removed from all items in the
|
|
category.
|
|
@end table
|
|
|
|
@noindent
|
|
Like @kbd{e k}, @kbd{C e k} automatically removes @code{todo-nondiary-marker}
|
|
from all items it is present on, since only diary items can bear
|
|
@code{diary-nonmarking-symbol}.
|
|
|
|
Since categories often contain a mix of items marked for diary
|
|
inclusion and exclusion, and of the former, a mix of those to be
|
|
marked and those not to be marked in the calendar, it is more useful
|
|
for these category-level commands, unlike the item-level commands, not
|
|
to be toggles, but to have the same effect on all items in the
|
|
category, and take a prefix argument to reverse the effect. (If you
|
|
really want to toggle the diary-inclusion and calendar-marking status
|
|
of all items in the category, you can do this by marking all the items
|
|
and then invoking @kbd{e y} or @kbd{e k}, @pxref{Marked Items}).
|
|
|
|
@node Relocating and Removing Items, , Editing Item Headers and Text, Item Editing
|
|
@subsection Relocating and Removing Items
|
|
|
|
In addition to inserting a new todo item and changing the text or header
|
|
of an existing item, you can also move an item to another category
|
|
(i.e., recategorize it), change its priority within its category, delete
|
|
it from the category and file, or mark it as a ``done'' item, which
|
|
removes it from the todo list but does not delete it.
|
|
|
|
@menu
|
|
* Reprioritizing Items::
|
|
* Moving and Deleting Items::
|
|
* Done Items::
|
|
@end menu
|
|
|
|
@node Reprioritizing Items, Moving and Deleting Items, , Relocating and Removing Items
|
|
@subsubsection Reprioritizing Items
|
|
|
|
There are three ways to change a todo item's priority:
|
|
|
|
@table @kbd
|
|
|
|
@item r
|
|
Raise the current item's priority by one, exchanging its position in the list
|
|
with that of the item directly above it (@code{todo-raise-item-priority}).
|
|
|
|
@item l
|
|
Lower the current item's priority by one, exchanging its position in the list
|
|
with that of the item directly below it (@code{todo-lower-item-priority}).
|
|
|
|
@item #
|
|
Prompt for a number and relocate the item to the corresponding
|
|
position in the list (@code{todo-set-item-priority}). For example,
|
|
entering @kbd{3} at the prompt makes the item the third in the
|
|
category, i.e., gives it third highest priority; all lower priority
|
|
items are pushed down by one. You can also pass the desired priority
|
|
as a numeric prefix argument, e.g., @kbd{3 #} gives the item third
|
|
highest priority without prompting. (Prefix arguments have no effect
|
|
with @kbd{r} or @kbd{l}.)
|
|
@end table
|
|
|
|
@node Moving and Deleting Items, Done Items, Reprioritizing Items, Relocating and Removing Items
|
|
@subsubsection Moving and Deleting Items
|
|
|
|
You can move an item to another category, thereby recategorizing it:
|
|
|
|
@table @kbd
|
|
|
|
@item m
|
|
Move the item at point to another category (@code{todo-move-item}).
|
|
This prompts for a category to move the item to, displays that category,
|
|
prompts for the priority of the moved item in the category moved to and
|
|
inserts the item accordingly. Minibuffer completion of the name of the
|
|
category moved to works as with the navigation command @kbd{j}, and as
|
|
with that command, passing a prefix argument prompts for a file and
|
|
moves the item to a category in that file; and if the category name you
|
|
enter is new, then you are asked whether to add the category to the
|
|
file, and if you affirm, the item is moved to the new category.
|
|
@end table
|
|
|
|
You can delete an item, thereby permanently (and, as far as Todo mode
|
|
is concerned, irrevocably) removing it from the todo file:
|
|
|
|
@table @kbd
|
|
|
|
@item k
|
|
Delete the todo item at point (@code{todo-delete-item}; the binding is
|
|
mnemonic for ``kill'', since @kbd{d} is used for marking items as done
|
|
(@pxref{Done Items}); but note that @kbd{k} does not put the item into
|
|
the kill ring). This command requires confirmation that you want to
|
|
delete the item, since you cannot undo the deletion in Todo mode. (You
|
|
could use @kbd{F e} to recover the item, but be aware that this would
|
|
put the file in an inconsistent state, which you can recover from, but
|
|
not without a risk; cf.@: the cautionary note in @ref{Reordering
|
|
Categories}.)
|
|
@end table
|
|
|
|
@quotation Note
|
|
Todo commands that require user confirmation, such as @kbd{k}, use a
|
|
modified form of @code{y-or-n-p}, which by default only accepts @kbd{y}
|
|
or @kbd{Y}, but not @key{SPC}, as an affirmative answer. This is to
|
|
diminish the risk of unintentionally executing the command, which is
|
|
especially important with commands that do deletion, since there is no
|
|
Todo command to undo a deletion. If you want to be able to use @key{SPC} for
|
|
confirmation, enable the option @code{todo-y-with-space}.
|
|
@end quotation
|
|
|
|
@node Done Items, , Moving and Deleting Items, Relocating and Removing Items
|
|
@subsubsection Done Items
|
|
|
|
When the activity or thing that a todo item is about has been done, it
|
|
is natural to eliminate the item from the todo list. But instead of
|
|
deleting it permanently, you may prefer to keep a record of your
|
|
accomplishments by marking the item as done. In Todo mode, this removes
|
|
the done item from the todo list, so as not to clutter it up, and stores
|
|
it elsewhere. Such stored items form a record or diary of things done.
|
|
The Todo package provides two such stores: the ``done items'' section of
|
|
a Todo category, described here, and done item archives (@pxref{Todo
|
|
Archive Mode}).
|
|
|
|
@table @kbd
|
|
|
|
@anchor{todo-item-done}
|
|
@item d
|
|
This command (@code{todo-item-done}) removes the todo item at point
|
|
from the todo list, appends to the original header a header consisting
|
|
of @code{todo-done-string} (by default @samp{DONE }) and the current
|
|
date, and if @code{todo-always-add-time-string} is enabled, also the
|
|
current time, and adds the resulting done item to the top of the done
|
|
items section of the category. Invoked with a prefix argument, it
|
|
also prompts you to enter a comment, which is appended to the end of
|
|
the done item, prefixed with @code{todo-comment-string} (by default
|
|
@samp{COMMENT: }).
|
|
@end table
|
|
|
|
A category's done items section is located below the last todo (i.e.,
|
|
not done) item in the category. By default this section is hidden from
|
|
view. There are two commands for viewing and hiding done items; since
|
|
these are toggle commands, for convenience they also have a single key
|
|
binding:
|
|
|
|
@table @kbd
|
|
|
|
@item C v
|
|
@itemx v
|
|
Make the done items section of the current category visible if it is
|
|
hidden, or hide it if it is visible
|
|
(@code{todo-toggle-view-done-items}). If you always want to see the
|
|
done items section on entering a category, enable the option
|
|
@code{todo-show-with-done}; you can still use @kbd{C v} or @kbd{v} to
|
|
hide (and unhide) it.
|
|
|
|
@item F V
|
|
@itemx V
|
|
Toggle the standard category display in the current todo file, i.e.,
|
|
display only the done items section of each category in the file, or if
|
|
this is visible, hide it again and display only the todo items section
|
|
(@code{todo-toggle-view-done-only}).
|
|
@end table
|
|
|
|
Since done items are meant to be a record of your finished todo items,
|
|
you cannot apply to them the same kinds of editing operations
|
|
available to unfinished todo items. However, as explained in
|
|
@ref{Editing Item Headers and Text} and repeated below for
|
|
convenience, you can edit or delete a done item's comment, or
|
|
retroactively add a comment. You can also relocate a done item, and
|
|
you can revert its done status, making it an unfinished item again.
|
|
|
|
@table @kbd
|
|
|
|
@item e c
|
|
Edit the current done item's comment, if it has one; otherwise, prompt
|
|
for and add a comment.
|
|
|
|
@item e d
|
|
Delete the current done item's comment, if it has one.
|
|
|
|
@item m
|
|
Move the done item at point to the top of the done items section of
|
|
another category (@code{todo-move-item}). This is useful in case,
|
|
after having finished a todo item and relocated it to its category's
|
|
done items section, you create a category that is better suited to the
|
|
content of the done item than its current category; in other words,
|
|
you can retroactively recategorize the done item.
|
|
|
|
@item u
|
|
If you decide the done item at point is not done after all, this command
|
|
``undoes'' it, i.e., restores it to the todo list of its category, with
|
|
the priority you choose for it (@code{todo-item-undone}). If the done
|
|
item has a comment, you are asked whether to delete it from the restored
|
|
item.
|
|
@end table
|
|
|
|
@node Todo Archives, Marked Items, Editing, Top
|
|
@chapter Todo Archives
|
|
|
|
When the done items section of a category itself starts to become
|
|
cluttered, or if you just want to store some accomplished todo items in
|
|
a separate file, you can move them to a Todo archive. This is a file
|
|
with exactly the same structure as a todo file, i.e., divided into
|
|
categories, but differs in that the categories contain only done items.
|
|
Todo archives reside, like todo files, in @code{todo-directory} but have
|
|
the extension @samp{.toda} instead of @samp{.todo}.
|
|
|
|
@menu
|
|
* Creating and Visiting Archives::
|
|
* Todo Archive Mode::
|
|
@end menu
|
|
|
|
@node Creating and Visiting Archives, Todo Archive Mode, , Todo Archives
|
|
@section Creating and Visiting Archives
|
|
|
|
Todo mode provides the following command for archiving items:
|
|
|
|
@table @kbd
|
|
|
|
@item A d
|
|
This command (@code{todo-archive-done-item}) archives the done item at point.
|
|
Invoked with a prefix argument, it archives all done items in the
|
|
current todo category. If an archive for the current todo file
|
|
already exists and contains a category with the same name as the
|
|
current todo category, then this command moves the done item to the
|
|
top of the corresponding archive category. If the archive exists but
|
|
it does not have a corresponding category, this command creates the
|
|
category in the archive and moves the done item to it. If no archive
|
|
for the todo file exists, the command creates both the archive file,
|
|
using the same base name as that of the todo file, as well as the
|
|
category, and moves the done item to it.
|
|
@end table
|
|
|
|
Typing @kbd{A d} is also the only way within the Todo mode package to
|
|
create an archive file and its categories. Consequently, as a rule each
|
|
archive file corresponds to exactly one todo file and has the same base
|
|
name as this file, and each category in an archive file corresponds to
|
|
and has the same name as a category in the corresponding todo file.
|
|
Exceptions can only arise if you delete a todo file but not the
|
|
corresponding archive, or if you delete a category in a todo file that
|
|
has a corresponding category in an archive.
|
|
|
|
You might be inclined to do the latter if you have archived all the
|
|
items from a given todo category and you don't plan to add new items to
|
|
it. In particular, if you have numerous such empty categories in a todo
|
|
file, this can make sequential navigation in the file annoying. You can
|
|
avoid this annoyance by deleting these categories, but only at the cost
|
|
of putting the todo file out of synch with the archive file.
|
|
|
|
You may find it preferable not to delete empty todo categories but to
|
|
enable the option @code{todo-skip-archived-categories}. When this is
|
|
non-@code{nil}, such empty todo categories are skipped over by the sequential
|
|
category navigation commands @kbd{f} and @kbd{b}, so they don't distract you
|
|
while navigating and you maintain the structural correspondence between
|
|
todo and archive files (you can also still jump to empty todo categories
|
|
with @kbd{j}).
|
|
|
|
If you rename a todo category that has a corresponding category in an
|
|
archive, the archive category is also automatically identically renamed.
|
|
Likewise, if you move such a todo category to another file; in this
|
|
case, if there is no archive file corresponding to the todo file the
|
|
category is moved to, then the archive is automatically created and the
|
|
archived category is moved to it.
|
|
|
|
There are two commands in Todo mode for visiting archive files:
|
|
|
|
@table @kbd
|
|
|
|
@item A f
|
|
Switch to a buffer displaying the archived category corresponding to the
|
|
current todo category (@code{todo-find-archive}). If the todo category
|
|
has no archived items, the command asks if you want to visit the archive
|
|
anyway. If there is no archive for this todo file, it asks if you want
|
|
to visit another archive, which you can select via minibuffer
|
|
completion.
|
|
|
|
@item A c
|
|
Choose an archive to visit, whether or not the current todo file has an
|
|
archive (@code{todo-choose-archive}).
|
|
@end table
|
|
|
|
As with todo files, you can also visit a Todo archive by invoking a
|
|
standard Emacs file-visiting command; this displays the first (on the
|
|
initial invocation) or current category of the archive.
|
|
|
|
@node Todo Archive Mode, , Creating and Visiting Archives, Todo Archives
|
|
@section Todo Archive Mode
|
|
|
|
When you visit a Todo archive, the buffer is in Todo Archive mode. It
|
|
displays categories just as in Todo mode, except that they only contain
|
|
done items. It provides the same sequential navigation commands as
|
|
Todo mode: @kbd{f} and @kbd{b} navigate between the categories of the current
|
|
archive, and @kbd{n} and @kbd{p} navigate between the done items of the current
|
|
archive category.
|
|
|
|
The commands @kbd{t} and @kbd{j} are also available in Todo Archive
|
|
mode, and they work the same as in Todo mode, which means they can only
|
|
be used to return to Todo mode: @kbd{t} prompt for and switch to a todo
|
|
file, and with @kbd{j} you can only jump to a todo category. These
|
|
commands exclude archives because an archive file has the same base name
|
|
as the corresponding todo file, and category name completion uses only
|
|
the base names, so the commands cannot know which type of file you want
|
|
to visit. For this reason, there is a special command in Todo Archive
|
|
mode for jumping to another archive category or visiting another archive
|
|
file:
|
|
|
|
@table @kbd
|
|
|
|
@item a
|
|
This command (@code{todo-jump-to-archive-category}) prompts for a category in the
|
|
current archive and jumps to it. Called with a prefix argument, it
|
|
prompts for another archive, then for a category in it and jumps to
|
|
that category.
|
|
@end table
|
|
|
|
None of the Todo mode editing commands are available in Todo Archive
|
|
mode, since archives are meant to be static records of accomplished todo
|
|
items. Should you, however, archive an item by mistake or simply change
|
|
your mind about the archival status of an item, you can ``unarchive'' it:
|
|
|
|
@table @kbd
|
|
|
|
@item u
|
|
Restore the done item at point to the top of the done items section of
|
|
the corresponding category in the corresponding todo file, i.e., an
|
|
unarchived item remains a done item (@code{todo-unarchive-items}). When
|
|
the last item in an archive category has been unarchived, the category
|
|
is automatically deleted from the archive. If this was the only
|
|
category in the archive, the archive file is also automatically deleted.
|
|
@end table
|
|
|
|
Since it is natural to visit an archive from the corresponding todo
|
|
file, it would be convenient to easily return to the todo file when you
|
|
have finished browsing the archive. If you type @kbd{q} to quit Todo
|
|
Archive mode, this switches to the corresponding todo file and shows the
|
|
todo category corresponding to the archive category you were just
|
|
visiting.
|
|
|
|
The command @kbd{F k} (@pxref{File Editing}) is also available in Todo
|
|
Archive mode. It deletes the current archive file and prompts you
|
|
whether to delete the corresponding todo file.
|
|
|
|
@node Marked Items, Todo Categories Mode, Todo Archives, Top
|
|
@chapter Marked Items
|
|
|
|
For many item editing commands it can make sense and be convenient to
|
|
apply them simultaneously to more than one item in the current category.
|
|
Todo facilitates this by means of marked items.
|
|
|
|
@table @kbd
|
|
|
|
@item *
|
|
Mark the item at point if it is unmarked, and remove the mark it is
|
|
already marked (@code{todo-toggle-mark-item}). The mark is a string
|
|
specified by the option @code{todo-item-mark} (by default @samp{*})
|
|
appended in front of the item header (more precisely, in front of the
|
|
item's priority number or prefix; see @ref{Todo Display Features}, for
|
|
details of the latter). After marking the current item, the command
|
|
advances point to the next item. It also accepts a numeric prefix
|
|
argument, which allows toggling the mark of multiple consecutive items.
|
|
|
|
@item C *
|
|
Mark all todo items in the current category.
|
|
|
|
@item C u
|
|
Unmark all todo item in the current category.
|
|
@end table
|
|
|
|
You can also use the last two commands to mark or unmark all done items in
|
|
the category, but only when only the done items section is being
|
|
displayed, i.e., after invoking @kbd{C V} or @kbd{V}.
|
|
|
|
The following commands operate on marked items:
|
|
|
|
@itemize @bullet
|
|
|
|
@item
|
|
@kbd{k} (deleting)
|
|
@item
|
|
@kbd{m} (moving to another category)
|
|
@item
|
|
@kbd{d} (moving to the done items section; note that @kbd{C-u d} adds
|
|
the same comment to all marked items)
|
|
@item
|
|
@kbd{A d} (archiving)
|
|
@item
|
|
@kbd{u} (both in Todo mode for undoing a done item and in Todo Archive
|
|
mode for unarchiving an item)
|
|
@item
|
|
the commands for editing the item header (those beginning with the
|
|
prefix @kbd{e d} as well as @kbd{e t}, @kbd{e y} and @kbd{e k})
|
|
@end itemize
|
|
|
|
@noindent
|
|
The item insertion, textual editing and priority changing commands do
|
|
not operate on marked items.
|
|
|
|
If you use @kbd{m}, @kbd{d}, @kbd{A d} or @kbd{u} on multiple
|
|
noncontiguous marked items, the relocated items retain their relative
|
|
order but are now listed consecutively en bloc.
|
|
|
|
You can mark both todo and done items, but note that only @kbd{m} and
|
|
@kbd{k} can apply to both; other commands only affect either marked
|
|
todo or marked done items, so if both types of items are marked,
|
|
invoking these commands has no effect and informs you of your
|
|
erroneous attempt.
|
|
|
|
@node Todo Categories Mode, Searching for Items, Marked Items, Top
|
|
@chapter Todo Categories Mode
|
|
|
|
It can be helpful to have a compact overview of the categories in a
|
|
todo file and the types of items it contains; the Todo package
|
|
provides a tabular view of this information.
|
|
|
|
@table @kbd
|
|
|
|
@item F c
|
|
Typing this command (@code{todo-show-categories-table}) in Todo mode or Todo
|
|
Archive mode switches to a buffer displaying a table that gives an
|
|
overview of the categories in the current todo or archive file. This
|
|
buffer is in Todo Categories mode.
|
|
@end table
|
|
|
|
The table consists of a column containing the names of the categories in
|
|
the file, followed by columns containing counts of certain types of
|
|
items in each category. With todo files there are four count types: all
|
|
todo (i.e., not done) items, diary items (i.e., those todo items lacking
|
|
the @code{todo-nondiary-marker}, which hence can appear in the Fancy Diary
|
|
display), done (but not archived) items, and archived items. With
|
|
archive files all items are done, so the table only has a column for
|
|
this count. The final row of the table gives total item counts across
|
|
all categories in the file.
|
|
|
|
Aside from explicitly invoking @kbd{F c} to display the table of
|
|
categories, you can also arrange to have it displayed on the first
|
|
invocation of @code{todo-show} for a given file (i.e., either using
|
|
@code{todo-show} to initiate a Todo session, or calling it in Todo mode
|
|
to visit another todo file). To do this customize the option
|
|
@code{todo-show-first}.
|
|
|
|
@menu
|
|
* Table of Item Counts::
|
|
* Reordering Categories::
|
|
@end menu
|
|
|
|
@node Table of Item Counts, Reordering Categories, , Todo Categories Mode
|
|
@section Table of Item Counts
|
|
|
|
Above each column of the table is a labeled button you can press by
|
|
clicking with the mouse or by typing @key{RET} on it. Pressing an item
|
|
count button sorts the table alternately in ascending or descending
|
|
order according to the type of count. Pressing the category button
|
|
alternates between the initial numerical order of the categories and
|
|
alphabetical order. In numerical order the column of category names is
|
|
preceded by a column containing the corresponding category numbers; this
|
|
column is not displayed in the alphabetical listing. Instead of
|
|
pressing the buttons, you can also sort the table by typing the
|
|
following keys:
|
|
|
|
@itemize
|
|
|
|
@item @kbd{c}
|
|
to sort by category numerically or alphabetically;
|
|
@item @kbd{t}
|
|
to sort by todo item counts;
|
|
@item @kbd{y}
|
|
to sort by diary item counts;
|
|
@item @kbd{d}
|
|
to sort by done item counts;
|
|
@item @kbd{a}
|
|
to sort by archived item counts.
|
|
@end itemize
|
|
|
|
Each row of the table is also buttonized; pressing one of these exits
|
|
the buffer (killing it), returns to the buffer of the file from which
|
|
you had invoked @kbd{F c}, and displays the category that was named in
|
|
the row button you pressed (i.e., pressing this button jumps to that
|
|
category). However, if the category named in the row is in a todo
|
|
file and all of its items have been archived, and you have enabled the
|
|
option @code{todo-skip-archived-categories}, then pressing the button
|
|
jumps to the archive category instead of the empty todo category. You
|
|
can recognize such categories by their items counts in the table---all
|
|
columns but the archived one have counts of zero---and in addition,
|
|
their lines in the table are also distinguished from the others by a
|
|
different face (@pxref{Faces}).
|
|
|
|
You can navigate around the table:
|
|
|
|
@table @kbd
|
|
|
|
@item n
|
|
@itemx @key{TAB}
|
|
Advance point to the next button.
|
|
|
|
@item p
|
|
@itemx S-@key{TAB}
|
|
Put point on the previous button.
|
|
@end table
|
|
|
|
These commands are cyclic, e.g., when point is on the last button,
|
|
pressing @kbd{n} moves it to the first button.
|
|
|
|
Typing @kbd{q} exits Todo Categories mode, killing the buffer and returning
|
|
to the current category in the Todo mode or Todo Archive mode buffer
|
|
from which you had invoked @kbd{F c}.
|
|
|
|
@node Reordering Categories, , Table of Item Counts, Todo Categories Mode
|
|
@section Reordering Categories
|
|
|
|
Todo Categories mode provide commands with which you can change the
|
|
numbering of the categories in the current file. This renumbering has
|
|
the effect of reordering the categories for sequential navigation by
|
|
@kbd{f} and @kbd{b} in Todo mode and Todo Archive mode. These commands
|
|
are only operative when the table displays the categories in their
|
|
numerical order. They work just like reprioritizing items in Todo mode,
|
|
hence have the same key bindings:
|
|
|
|
@table @kbd
|
|
|
|
@item r
|
|
Raise the current line of the table (the one the cursor is on),
|
|
decreasing the category's number by one (@code{todo-raise-category}).
|
|
This command exchanges lines, and hence the numbers, of the category at
|
|
point and the one above it before invoking the command.
|
|
|
|
@item l
|
|
Lower the current line of the table, increasing the category's number by
|
|
one (@code{todo-lower-category}). This command exchanges lines, and
|
|
hence the numbers, of the category at point and the one below it before
|
|
invoking the command.
|
|
|
|
@item #
|
|
Prompt for a number between 1 and the number of categories in the file
|
|
and reorder the table accordingly (@code{todo-set-category-number}). If
|
|
called with a numeric prefix argument within the allowed range, reorder
|
|
the table without prompting.
|
|
@end table
|
|
|
|
The reordering done by these commands remains in effect when you return
|
|
to Todo mode or Todo Archive mode and, as long as you save the todo
|
|
or archive file after reordering, in subsequent sessions as well.
|
|
|
|
@quotation @strong{Caution}
|
|
It is important to be aware that renumbering the categories does not
|
|
change the textual order of the categories in the file. This is
|
|
significant if you should invoke @kbd{F e} to edit the entire file
|
|
manually and in so doing alter the number of categories or the number
|
|
of items in a category: this will make the information shown in the
|
|
table of categories of this file inconsistent with its actual state.
|
|
You can repair this inconsistency by invoking the command
|
|
@code{todo-repair-categories-sexp} (which lacks a key binding, since
|
|
it is meant to be a rarely needed rescue operation). But this will
|
|
revert any renumbering of the categories you have made, so you will
|
|
have to renumber them again. This is one reason why you should
|
|
exercise caution when using @kbd{F e}.
|
|
@end quotation
|
|
|
|
@node Searching for Items, Todo Filtered Items Mode, Todo Categories Mode, Top
|
|
@chapter Searching for Items
|
|
|
|
It can be useful to be able to locate and examine all todo items that
|
|
fit certain criteria, regardless of which category they belong to. One
|
|
way to do this in Todo mode is by sequentially searching in the file:
|
|
|
|
@table @kbd
|
|
|
|
@item S
|
|
This command (@code{todo-search}; the key is capital @kbd{S}) prompts for a
|
|
regular expression, searches from the beginning of the current todo file
|
|
and displays the category containing the first match it finds, with the
|
|
match highlighted. If there are further matches, a message saying how
|
|
many are left is displayed and you are asked if you want to go to the
|
|
next match. When you reach the last match, or if you decide not to go
|
|
to further matches, you are asked whether the match highlighting should
|
|
be removed.
|
|
|
|
@item X
|
|
This command (@code{todo-clear-matches}) removes any highlighting added by @kbd{S}.
|
|
This is so you can leave the matches highlighted at the end of the
|
|
search and remove the highlighting later.
|
|
@end table
|
|
|
|
These commands are also available in Todo Archive mode.
|
|
|
|
@node Todo Filtered Items Mode, Todo Display Features, Searching for Items, Top
|
|
@chapter Todo Filtered Items Mode
|
|
|
|
A more powerful alternative to sequential searching is item filtering,
|
|
by which items from different categories that match specified criteria
|
|
are gathered and displayed in a new buffer as a kind of virtual
|
|
category in a distinct mode, Todo Filtered Items mode.
|
|
|
|
@menu
|
|
* Filtering Items::
|
|
* Todo Filtered Items Mode Commands::
|
|
* Files of Filtered Items::
|
|
@end menu
|
|
|
|
@node Filtering Items, Todo Filtered Items Mode Commands, , Todo Filtered Items Mode
|
|
@section 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 @code{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:@footnote{The use of @kbd{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.}
|
|
|
|
@itemize @bullet
|
|
|
|
@item
|
|
@kbd{F x x} (@code{todo-filter-regexp-items})
|
|
@item
|
|
@kbd{F x m} (@code{todo-filter-regexp-items-multifile})
|
|
@item
|
|
@kbd{F y y} (@code{todo-filter-diary-items})
|
|
@item
|
|
@kbd{F y m} (@code{todo-filter-diary-items-multifile})
|
|
@item
|
|
@kbd{F t t} (@code{todo-filter-top-priorities})
|
|
@item
|
|
@kbd{F t m} (@code{todo-filter-top-priorities-multifile})
|
|
@end itemize
|
|
|
|
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 @code{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
|
|
@code{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 @code{todo-filter-done-items}.
|
|
Then @kbd{F x x} and @kbd{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 @kbd{F t t} and @kbd{F t m}:
|
|
|
|
@itemize @bullet
|
|
|
|
@item
|
|
The option @code{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.
|
|
@item
|
|
The option @code{todo-top-priorities-overrides} lists file-wide overrides
|
|
of @code{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 @kbd{F t s} and @kbd{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 @kbd{F t t}
|
|
and @kbd{F t m}, set the number to @samp{0}.
|
|
@item
|
|
You can invoke @kbd{F t t} and @kbd{F t m} with a numeric prefix argument,
|
|
which specifies the number of top priorities in each category just for
|
|
this invocation, overriding both @code{todo-top-priorities-overrides} and
|
|
@code{todo-top-priorities}.
|
|
@end itemize
|
|
|
|
@node Todo Filtered Items Mode Commands, Files of Filtered Items, Filtering Items, Todo Filtered Items Mode
|
|
@section Todo Filtered Items Mode Commands
|
|
|
|
The output of the item filtering commands looks similar to a regular
|
|
Todo category, but it is not contained in any todo file and does not
|
|
have a name on being created, so it is not a ``real'' category but a
|
|
``virtual'' category. Another difference is the lack of a done items
|
|
section; either there are no done items in the list (when the filtered
|
|
items are diary or top priority items), or these are displayed in the
|
|
same list as todo items (if you filtered by regular expression and
|
|
allowed done items). A further difference is that the items have an
|
|
additional header, between the item's date/time header and its text,
|
|
specifying which category (and if you invoked a multifile command, also
|
|
which file) the item comes from, and if you filtered by regular
|
|
expression, also whether the item comes from a Todo archive.
|
|
|
|
The sequential item navigation commands @kbd{n} and @kbd{p} work the same in
|
|
Todo Filtered Items mode as in Todo mode, as do the file and category
|
|
jumping commands @kbd{t} and @kbd{j}; however, the sequential category
|
|
navigation commands are unavailable, since virtual categories of
|
|
filtered items are not ordered with respect to ``real'' categories. In
|
|
addition, Todo Filtered Items mode provides a special navigation
|
|
command:
|
|
|
|
@table @kbd
|
|
|
|
@item g
|
|
@itemx @key{RET}
|
|
If you type this command (@code{todo-go-to-source-item}) with point on a
|
|
filtered item, the buffer switches to the item's source file (in Todo
|
|
mode or Todo Archive mode, as the case may be) and displays its
|
|
category, with point on the item.
|
|
@end table
|
|
|
|
Filtered items cannot be textually edited, moved to another category,
|
|
marked done or archived like items in a real todo category, since these
|
|
would then be out of synch with each other. But there is one type of
|
|
editing command that does work in Todo Filtered Items mode: changing an
|
|
item's priority:
|
|
|
|
@table @kbd
|
|
|
|
@item r
|
|
@itemx l
|
|
@itemx #
|
|
These commands raise, lower, or set, respectively, the current item's
|
|
priority in the virtual category.
|
|
@end table
|
|
|
|
@noindent
|
|
Using these commands, you can create a cross-category (and even
|
|
cross-file) prioritized list of filtered items. However, there is a
|
|
restriction on these commands in Todo Filtered Items mode: you cannot
|
|
change the relative priorities of items from the same real category,
|
|
since that would make the filtered list inconsistent with the source
|
|
todo list.
|
|
|
|
@node Files of Filtered Items, , Todo Filtered Items Mode Commands, Todo Filtered Items Mode
|
|
@section Files of Filtered Items
|
|
|
|
Typing @kbd{s} in Todo Filtered Items mode saves the buffer of filtered
|
|
items to a file in @code{todo-directory}. Files of items filtered by
|
|
regular expression have the extension @samp{.todr}, those with filtered
|
|
diary items have the extension @samp{.tody} and those with filtered top
|
|
priorities have the extension @samp{.todt}. The extensions are added
|
|
automatically the first time you save the buffer to a file.
|
|
|
|
With filtered top priority or diary items, the file is automatically
|
|
named on first saving it, using as the base name either the same base
|
|
name as the single todo file it was generated from, or combining the
|
|
base names of the todo files used in multifile filtering commands.
|
|
With items filtered by regular expression, it can be useful to save
|
|
separate lists generated from the same file(s) using different regular
|
|
expressions, so when saving such a list, you are prompted for a short
|
|
identifying string to add to the file name.
|
|
|
|
When you invoke one of the item filtering commands without a prefix
|
|
argument and a corresponding file already exists, the command visits
|
|
this file (if, for the current file or chosen files, there are multiple
|
|
files of items filtered by regular expression, you are prompted to
|
|
choose one). To force generation of a new filtered list, invoke the
|
|
command with a prefix argument (in the case of top priority items,
|
|
either numeric as described above, or the raw prefix argument @kbd{C-u} to
|
|
use the values of @code{todo-top-priorities-overrides} or
|
|
@code{todo-top-priorities}).
|
|
|
|
Aside from explicitly invoking an item filtering command to display a
|
|
saved list of items filtered by a given method from given todo files,
|
|
there are two other ways to visit a saved file of filtered items. You
|
|
can invoke a command similar to @code{find-file}:
|
|
|
|
@table @kbd
|
|
@item F f
|
|
Visit a saved file of filtered items, which you choose via minibuffer
|
|
completion (@code{todo-find-filtered-items-file}).
|
|
@end table
|
|
|
|
@noindent
|
|
Alternatively, as with tables of categories, by customizing
|
|
@code{todo-show-first} you can have the first invocation of
|
|
@code{todo-show} for a given todo file display the corresponding saved
|
|
file of filtered items. If there is no saved filtered items list for
|
|
the file, @code{todo-show} simply defaults to visiting the file and
|
|
displaying its first category, as usual.
|
|
|
|
The command @kbd{F k} (@pxref{File Editing}) is also available in Todo
|
|
Filtered Items mode. It deletes the current filtered items file.
|
|
|
|
@node Todo Display Features, Printing Todo Buffers, Todo Filtered Items Mode, Top
|
|
@chapter Todo Display Features
|
|
|
|
You can change the appearance of Todo mode buffers in a variety of ways.
|
|
|
|
@menu
|
|
* Faces::
|
|
* Item Prefix::
|
|
* Other Display Commands and Options::
|
|
@end menu
|
|
|
|
@node Faces, Item Prefix, , Todo Display Features
|
|
@section Faces
|
|
|
|
Each of the Todo modes uses faces to distinguish various aspects of
|
|
the display, both structural and informational. For example, the
|
|
faces for the date and time strings of todo item headers
|
|
(@code{todo-date} and @code{todo-time}, respectively) by default
|
|
inherit the attributes of the corresponding faces used by the Emacs
|
|
diary; but when the date and time of a Todo diary item (i.e., an item
|
|
lacking @code{todo-nondiary-marker}) is earlier than the current date
|
|
and time, they are displayed in a different face
|
|
(@code{todo-diary-expired}). In this way, you can readily recognize
|
|
diary items that have ``expired'' and act accordingly (e.g., by
|
|
tagging them as done or by updating the deadlines).
|
|
|
|
Another example of an informational face is the face used to
|
|
distinguish top priority items (@code{todo-top-priority}). A third
|
|
case is the face used in Todo Categories mode to mark rows of the
|
|
table containing categories with only archived items
|
|
(@code{todo-archived-only}).
|
|
|
|
The @code{todo-faces} customization group contains a complete list of
|
|
Todo mode faces and brief descriptions of their use.
|
|
|
|
|
|
@node Item Prefix, Other Display Commands and Options, Faces, Todo Display Features
|
|
@section Item Prefix
|
|
|
|
In the default display of (real or virtual) categories in Todo mode,
|
|
Todo Archive mode and Todo Filtered Item mode the items are visually
|
|
numbered in ascending order, starting with @samp{1} on the top item,
|
|
displayed to the left of its header (date/time string). With todo items
|
|
the numbers indicate each item's priority in the list, so when you
|
|
reprioritize an item with @kbd{#} or move it with @kbd{m}, these numbers make
|
|
it easier to choose the item's new priority. The numbering also lets
|
|
you to see at a glance how many items there are in the list. When an
|
|
item is inserted, deleted, or moved, the numbering is automatically
|
|
updated. In Todo mode, the todo and done items sections in each
|
|
category are separately numbered.
|
|
|
|
If you prefer not to have item numbering displayed, disable the option
|
|
@code{todo-number-prefix}; then the display of each item starts by default
|
|
simply with its header. But you can also replace the numbering with a
|
|
visually distinctive string of your choice by customizing the option
|
|
@code{todo-prefix} (the empty string by default). Another alternative is to
|
|
temporarily hide the item numbering:
|
|
|
|
@table @kbd
|
|
|
|
@item F N
|
|
@itemx N
|
|
Toggle between displaying item numbering and displaying the
|
|
@code{todo-prefix} string in the current Todo file (todo, archive, or
|
|
saved virtual category of filtered items). (This command also works in
|
|
buffers of filtered items that have not yet been written to a file.)
|
|
@end table
|
|
|
|
In the todo items section of each Todo mode category, the item prefix
|
|
(whether a priority number or a fixed string) of the top priority
|
|
items (determined as specified in @pxref{Filtering Items}) is
|
|
displayed in a face (@code{todo-top-priority}) different from the face
|
|
of the prefix of non-top-priority items, so you see at a glance how
|
|
many items in the category are top priorities.
|
|
|
|
@node Other Display Commands and Options, , Item Prefix, Todo Display Features
|
|
@section Other Display Commands and Options
|
|
|
|
There are two additional toggle commands that affect display in the
|
|
current file:
|
|
|
|
@table @kbd
|
|
|
|
@item F h
|
|
@itemx h
|
|
Hide the item headers if visible, or show them if they are hidden.
|
|
With done items, only the done header (i.e., the done tag and date-time
|
|
string inserted when the item was marked done) is hidden, the original
|
|
date-time string is not. With filtered items, the category (or
|
|
category-file) tag is not hidden.
|
|
|
|
@item F H
|
|
@itemx H
|
|
Highlight the current item (with the face @code{hl-line}) if
|
|
unhighlighted, or remove its highlighting. When item highlighting is
|
|
enabled, it follows navigation by @kbd{n} or @kbd{p}. If you want to
|
|
have current item highlighting by default, enable the option
|
|
@code{todo-highlight-item}. @kbd{F H} or @kbd{H} will still toggle
|
|
it.
|
|
@end table
|
|
|
|
There are two options which affect the display of items whose content is
|
|
longer than one screen line:
|
|
|
|
@itemize @bullet{}
|
|
|
|
@item
|
|
@code{todo-indent-to-here} sets the amount of indentation for all lines
|
|
after the first in multiline todo items, which is necessary in order
|
|
for todo diary items to be fully visible in the Fancy Diary display.
|
|
The default indentation is 3 spaces. For a uniform appearance this
|
|
option applies to all items, i.e., diary and nondiary todo items and
|
|
also done items.
|
|
|
|
@item
|
|
@code{todo-wrap-lines} allows you to choose, for the purposes of
|
|
insertion and editing, between treating multiline todo items as
|
|
containing multiple logical lines with hard line breaks or as multiple
|
|
visual lines using Visual Line mode; the latter is the default. Since
|
|
multiparagraph items also contain hard line breaks in Visual Line mode,
|
|
for a uniform appearance this display shows indentation on wrapped lines
|
|
by using a wrap-prefix of @code{todo-indent-to-here} spaces.
|
|
@end itemize
|
|
|
|
The indentation inserted after a hard newline is actually a tab
|
|
character, and the Todo modes that display items bind @code{tab-width} to
|
|
@code{todo-indent-to-here}, so if you change the default value of the
|
|
latter, the next time you visit a Todo file, the indentation will
|
|
reflect your change.
|
|
|
|
By default, the todo and done items sections of a todo category are
|
|
visually separated by a line as wide as the window the buffer is
|
|
displayed in. You can change the appearance and width of the separator
|
|
by customizing @code{todo-done-separator-string}; you can also change the
|
|
face of the separator string (@code{todo-done-sep}).
|
|
|
|
There are also several options for changing the appearance in Todo
|
|
Categories mode and Todo Filtered Items mode, beyond those mentioned
|
|
above in the sections on these modes; see the customization groups
|
|
@code{todo-categories} and @code{todo-filtered} for details.
|
|
|
|
@node Printing Todo Buffers, Legacy Todo Mode Files, Todo Display Features, Top
|
|
@chapter Printing Todo Buffers
|
|
|
|
If you print a Todo buffer using one of the standard Emacs printing
|
|
commands, it does not look exactly like what you see in the buffer.
|
|
This is because some of the display features are non-printable
|
|
(specifically, those using overlays, word-wrap and wrap-prefix). Todo
|
|
mode provides two print commands that produce output which includes
|
|
printable counterparts of such display features:
|
|
|
|
@table @kbd
|
|
|
|
@item P B
|
|
Send the printable buffer output directly to your printer.
|
|
|
|
@item P F
|
|
Prompt for a file name and write the printable output to that file.
|
|
@end table
|
|
|
|
By default, Todo uses @code{ps-print-buffer-with-faces} to make the
|
|
printable version; you can change this by setting the option
|
|
@code{todo-print-function}.
|
|
|
|
@node Legacy Todo Mode Files, GNU Free Documentation License, Printing Todo Buffers, Top
|
|
@chapter Legacy Todo Mode Files
|
|
|
|
Users of the original version of Todo mode will recognize from the
|
|
description in this user manual that, although the new version shares
|
|
with the original version the same basic user interface and handling of
|
|
todo items, there are some incompatible differences between them, such
|
|
as the done items sections (there are also other file format
|
|
incompatibilities behind the scenes that are normally not visible to
|
|
users).
|
|
|
|
The most significant incompatibility concerns the item prefix. In the
|
|
earlier version of Todo mode the prefix was the initial part of the item
|
|
string itself, so in order for the item to be displayable in the Emacs
|
|
diary, the prefix had to be a date/time pattern recognizable by the
|
|
diary (although the todo item also has its own date/time header).
|
|
Moreover, since all items had the same prefix string in the original
|
|
version, this means that either only all or no items could appear in the
|
|
Fancy Diary display on any given date. This considerably restricts the
|
|
practicality of including todo items in the diary. In contrast, the
|
|
current version of Todo mode uses overlays for item priority numbering
|
|
or prefixes, and item-specific diary-compatible date/time headers and
|
|
special marks for todo items to be excluded from the diary, so you can
|
|
determine for each item whether and when it appears in the Fancy Diary
|
|
display.
|
|
|
|
Due to these incompatibilities, files created with the original version
|
|
of Todo mode cannot be displayed or edited with the current version.
|
|
However, this version provides a function that converts the two main
|
|
types of files used by the original version into new-style valid todo
|
|
and archive files, respectively, and saves them in
|
|
@code{todo-directory}.@footnote{The original version of Todo mode also
|
|
allowed saving a file of top priority items, but since you can readily
|
|
create such a file with the new version, which is also more flexible,
|
|
no conversion is provided for this file.}
|
|
|
|
This conversion function is automatically called the first time you
|
|
invoke @code{todo-show} (i.e., before you have created a todo file with
|
|
the new version), and if it finds the old-style files, it offers to
|
|
convert them, making them the first new-style todo and archive files.
|
|
If you choose not to convert the old-style files at this time, you can
|
|
do so later by invoking the command @code{todo-convert-legacy-files}
|
|
(there is no key binding for it, since it shouldn't be necessary to use
|
|
it often). (A delicate part of the conversion concerns the customizable
|
|
format of item date/time headers in the old-style; see the documentation
|
|
string of @code{todo-legacy-date-time-regexp} for details.)
|
|
|
|
@node GNU Free Documentation License, , Legacy Todo Mode Files, Top
|
|
@appendix GNU Free Documentation License
|
|
@include doclicense.texi
|
|
|
|
@bye
|
|
|
|
@c End:
|