Commit 016d3f7d authored by Stephen Berman's avatar Stephen Berman

Add Todo mode user manual.

* doc/misc/ (INFO_TARGETS, DVI_TARGETS, PDF_TARGETS): Add todo-mode.
(todo-mode, $(buildinfodir)/todo-mode$(INFO_EXT)):
(todo-mode.dvi, todo-mode.pdf): New rules.

* doc/misc/todo-mode.texi: New file.

* info/dir: Add todo-mode.
parent 671d5c16
2013-08-04 Stephen Berman <>
* info/dir: Add todo-mode.
2013-08-04 Paul Eggert <>
Fix some minor races in hosts lacking mkostemp (Bug#15015).
2013-08-04 Stephen Berman <>
(todo-mode, $(buildinfodir)/todo-mode$(INFO_EXT)):
(todo-mode.dvi, todo-mode.pdf): New rules.
* todo-mode.texi: New file.
2013-08-01 Lars Magne Ingebrigtsen <>
* gnus.texi (Basic Usage): Mention that warp means jump here.
......@@ -48,7 +48,7 @@ INFO_TARGETS = ada-mode auth autotype bovine calc ccmode cl \
flymake forms gnus emacs-gnutls htmlfontify idlwave ido \
mairix-el message mh-e newsticker nxml-mode \
org pcl-cvs pgg rcirc remember reftex sasl \
sc semantic ses sieve smtpmail speedbar srecode tramp \
sc semantic ses sieve smtpmail speedbar srecode todo-mode tramp \
url vip viper widget wisent woman
......@@ -100,6 +100,7 @@ DVI_TARGETS = \
smtpmail.dvi \
speedbar.dvi \
srecode.dvi \
todo-mode.dvi \
tramp.dvi \
url.dvi \
vip.dvi \
......@@ -157,6 +158,7 @@ PDF_TARGETS = \
smtpmail.pdf \
speedbar.pdf \
srecode.pdf \
todo-mode.pdf \
tramp.pdf \
url.pdf \
vip.pdf \
......@@ -645,6 +647,15 @@ srecode.dvi: ${srcdir}/srecode.texi ${gfdl}
srecode.pdf: ${srcdir}/srecode.texi ${gfdl}
$(ENVADD) $(TEXI2PDF) ${srcdir}/srecode.texi
todo-mode : $(buildinfodir)/todo-mode$(INFO_EXT)
$(buildinfodir)/todo-mode$(INFO_EXT): ${srcdir}/todo-mode.texi ${gfdl}
$(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/todo-mode.texi
todo-mode.dvi: ${srcdir}/todo-mode.texi ${gfdl}
$(ENVADD) $(TEXI2DVI) ${srcdir}/todo-mode.texi
todo-mode.pdf: ${srcdir}/todo-mode.texi ${gfdl}
$(ENVADD) $(TEXI2PDF) ${srcdir}/todo-mode.texi
tramp : $(buildinfodir)/tramp$(INFO_EXT)
$(buildinfodir)/tramp$(INFO_EXT): ${srcdir}/tramp.texi ${srcdir}/trampver.texi ${gfdl}
\input texinfo.tex @c -*-texinfo-*-
@c %**start of header
@setfilename ../../info/todo-mode
@settitle Todo Mode User Manual
@syncodeindex fn cp
@syncodeindex vr cp
@syncodeindex ky cp
@c %**end of header
Copyright @copyright{} 2013 Free Software Foundation, Inc.
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
* Todo Mode: (todo-mode). Make and maintain todo lists.
@end direntry
@title Todo Mode User Manual
@subtitle Facilities for making and maintaining todo lists.
@author Stephen Berman
@vskip 0pt plus 1filll
@end titlepage
@node Top
@top Todo Mode User Manual
This manual describes the version of Todo mode first appearing in
Emacs 24.4.
@end ifnottex
* 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::
--- The Detailed Node Listing ---
* Levels of Organization::
* Todo Items as Diary Entries::
* 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, @xref{Legacy Todo Mode Files}.
* 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}). Emacs
recognizes Todo files by their extension, so when you visit the files
the buffer is in the appropriate mode and the current 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
Each todo item is also a potential diary item: if you include a todo
file in the Emacs diary file (@pxref{Fancy Diary Display,,, emacs}), the
Fancy Diary display will show those todo items that are not marked with
@code{todo-nondiary-marker}. This effectively augments the Emacs diary
with categorized diary entries. For the various options available for
making a todo item a diary entry, @ref{Inserting New Items} and
@xref{Editing Item Headers and Text}.
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
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 a todo item insertion
command; @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
for @code{todo-show} and @code{todo-jump-to-category} are @kbd{C-c t}
and @kbd{C-c j}, since these commands are bound to @kbd{t} and @kbd{j},
respectively, in Todo mode. For invoking item insertion from outside of
Todo mode, it is useful to bind @code{todo-insertion-map}, which is the
key map containing the bindings of all Todo item insertion commands, to
@kbd{C-c i}, since it is bound to @kbd{i} in Todo mode; to complete the
invocation, supply the rest of the key sequence (@pxref{Inserting New
You can also visit a Todo file via @code{find-file} or Dired, like any
other file, and since Emacs recognizes it, the buffer will automatically
be in the appropriate Todo mode. Moreover, as long as the command you
use to visit the file is listed in the option
@code{todo-visit-files-commands} (which by default contains
@code{find-file} and @code{dired-find-file}), it will also correctly
display the file's first category on first visiting the file (otherwise
you have to use one of the commands for navigating between categories in
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} 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 the section on
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, textual editing includes
renaming files or categories and changing an item's content or date, or
adding certain kinds of marks or tags to items. 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}.
* 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 rename them accordingly.
@item F k
Delete the current todo file (@code{todo-delete-file}).@footnote{The key
binding of this command is mnenomic 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 whether to delete that as well.
This command also kill 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
writeable 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
changed, which could result in the file containing inconsistent
information (see the cautionary note in @ref{Reordering Categories} for
more details). For this reason @kbd{F e} should be used with caution.
@end table
@node Category Editing, Item Editing, File Editing, Editing
@section Category Editing
The following commands are available for editing at the category level
(for additional 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 mnenomic 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
@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 a wide variety of commands for adding and textually
changing items, as well as for deleting and relocating items.
* 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
There are many commands for adding new todo items. The command names
contain the word ``insert'' instead of ``add'' and their key bindings are
sequences beginning with @kbd{i}. The motivation for this terminology is
that speaking of adding an item to a category suggests appending it to
the top or bottom, whereas you can insert an item into the category
anywhere, giving each new item any priority in the list.
@table @kbd
@item i i
This is the basic command for inserting new items into a category
(@code{todo-insert-item}). Called without a prefix argument, it prompts
for the text of the item and its priority (a number between 1 and one
more than the number of items already in the category), both of which
you enter in the minibuffer, and inserts the item into the current
category of the current todo file at the position in the list
corresponding to the priority you chose. 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}.
@end table
Each invocation of @kbd{i i} adds a header string to the item, which
includes at least the current date in the same format used by
@code{diary-insert-entry} (@pxref{Date Formats,,, emacs}). You can
control what other information is included in the header by customizing
the following options:
@itemize @bullet
@code{todo-always-add-time-string} is for including or omitting the
current time. The time string is omitted by default.
@code{todo-include-in-diary} is for specifying whether the item appears
in the Fancy Diary display by adding or omitting
@code{todo-nondiary-marker}. By default, new todo items are marked for
exclusion from the diary.
@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 are
marked in the calendar.
@end itemize
Instead of always adding the same header information to a new item, you
can use more specific insertion commands that let you decide what to
include in the item header each time you insert a new item. And instead
of always being prompted to choose the new item's priority, you can
invoke a command to insert it at the position (hence with the priority)
of the item at point. Finally, instead of always typing the text of the
new item in the minibuffer, you can invoke a command that makes the
selected region in an Emacs buffer automatically become the new item's
text. The following paragraphs discuss how to invoke these commands by
typing certain key sequences.
There are eight parameters of item insertion in Todo mode, six
concerning the item header, and one each concerning its priority and its
text. Each unique combination of these parameters produces a different
insertion command. The command @kbd{i i} realizes one of these
combinations. For the commands that realize the remaining combinations
it is convenient to associate each parameter with a mnenomically chosen
key. Then by typing certain sequences of these keys, you complete the
insertion command invocation that realizes the specified combination.
As with @kbd{i i}, the effect of many of these commands also depends on
the values of the item insertion options mentioned above (see the
examples below).
Here is a list of the parameters and their associated keys, in the order
in which you must type them when building a key sequence (this order
roughly reflects the order in which the corresponding parts of the item
occur in a category listing):
@kbd{y} for diary (non)inclusion;
@kbd{k} for adding or omitting `diary-nonmarking-symbol';
@kbd{c} for adding the date header by clicking a date in the Emacs