Todo Mode User Manual
*********************

This manual describes the version of Todo mode first appearing in Emacs
24.4.

   Copyright © 2013–2024 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.”

— The Detailed Node Listing —

Overview

Editing

Item Editing

Relocating and Removing Items

Todo Archives

Todo Categories Mode

Todo Filtered Items Mode

Todo Display Features

1 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, see Legacy Todo Mode Files.

1.1 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 ‘todo-directory’.  This directory may also
contain other types of Todo files, which are discussed later (see Todo Archive Mode
and Todo Filtered Items Mode).  When you use a
Todo mode command to create a todo file, the extension ‘.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 ‘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.

1.2 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 (see 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
‘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
Inserting New Items and 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,(1) 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 (see
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 <RET> on this item will
switch to the buffer visiting that file and properly display the item’s
category, with point on the item.

   ---------- Footnotes ----------

   (1) 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 ‘*’ for an arbitrary year, which Todo mode does
support).

2 Todo Mode Entry Points
************************

To initialize your first todo file, invoke the command ‘todo-show’.
This prompts you for a file name (defaulting to the value of
‘todo-initial-file’), prompts you for the name of the first category
(defaulting to the value of ‘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 ‘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 ‘todo-add-item-if-new-category’.

   Once at least one todo file exists, invoking ‘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
‘todo-default-todo-file’) and shows its first category.  (You can get a
different display with the first invocation of ‘todo-show’ by
customizing the option ‘todo-show-first’; see Todo Categories Mode
and Files of Filtered Items.)

   If you leave Todo mode and later invoke ‘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 ‘todo-show-current-file’, then non-initial invocations of
‘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 ‘todo-jump-to-category’; see Navigation, for
details.  You can also enter Todo mode by invoking the command
‘todo-insert-item’; see 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 ‘C-c t’ for ‘todo-show’, ‘C-c j’ for ‘todo-jump-to-category’ and
‘C-c i’ for ‘todo-insert-item’, since these commands are bound to ‘t’,
‘j’ and ‘i’, respectively, in Todo mode.

   You can leave Todo mode by typing ‘q’ (‘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).

3 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
‘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 ‘C’ (capital ‘C’, not the control
key) are bound to commands applying to categories, sequences beginning
with ‘F’ apply to (non-archive) file-level commands, and those beginning
with ‘A’ apply to archives (a special type of Todo file; see Todo Archive Mode).
Todo commands applying to items, which constitute the
majority, are bound to lower case key sequences.

4 Navigation
************

The navigation commands are for making another todo file, category, or
item the current one by moving point to it.(1)  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 Todo Mode Entry Points:

‘t’
     Display another todo file in the selected window (‘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
     ‘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 ‘t’ opens the file, it display its first
     category (by default; see the option ‘todo-show-first’ for other
     possibilities).

‘j’
     Display another todo category in the selected window
     (‘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 ‘todo-category-completions-files’.  If you type <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 ‘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.

   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 ‘1’.(2)  The current category’s
number and name appear in the mode line.

‘f’
     Move point to the first item of the category numerically directly
     following the current category (‘todo-forward-category’).

‘b’
     Move point to the first item of the category numerically directly
     preceding the current category (‘todo-backward-category’).

   With ‘f’ and ‘b’ you can cycle through the categories, so for
example, if the last category is current and you type ‘f’, then the
first category becomes current.

   You can also navigate between the items in the current category:

‘n’
     Move point down to the next item below the current one (i.e., to
     the item with the next lower priority) (‘todo-next-item’).

‘p’
     Move point up to the item directly above the current one (i.e., to
     the item with the next higher priority) (‘todo-previous-item’).

   These commands also accept a positive numeric prefix argument; e.g.,
typing ‘5 n’ or ‘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.

   ---------- Footnotes ----------

   (1) 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.

   (2) 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;
see Todo Categories Mode.

5 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 ‘s’
(‘todo-save’).  Changes are also saved on quitting Todo mode with ‘q’.

5.1 File Editing and Todo Edit Mode
===================================

There are four file-level editing commands:

‘F a’
     Add a new todo file (‘todo-add-file’).  This command prompts for a
     name and creates the file in ‘todo-directory’, adding the ‘.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 ‘todo-add-item-if-new-category’ is enabled (the
     default), for that category’s first item.

‘F r’
     Rename the current todo file (‘todo-rename-file’).  If called with
     a prefix argument, prompt for a todo file and rename it.  If the
     todo file has an archive (see Todo Archive Mode) or there are
     corresponding filtered items files (see 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.

‘F k’
     Delete the current todo file (‘todo-delete-file’).(1)  If the todo
     file has an archive (see Todo Archive Mode), prompt for whether
     to delete that as well.  This command also kills the buffers
     visiting the deleted files.

‘F e’
     This command (‘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 ‘C-x C-q’ (‘todo-edit-quit’).

     The command ‘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 ‘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 ‘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 Reordering Categories, for more details).  Invoking
     ‘F e’ displays a warning to this effect.

   ---------- Footnotes ----------

   (1) The key binding of this command is mnemonic for “kill” to
parallel the binding ‘k’ for item deletion, since ‘d’ is bound to
another item editing command (see Done Items).

5.2 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, see Editing Item Headers and Text):

‘C a’
     Add a new category to the current todo file and make that category
     current (‘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 ‘j’, but it only accepts category names
     that are not the name of an existing category in the file.

‘C r’
     Rename the current category (‘todo-rename-category’).  If this
     category’s file has an archive (see Todo Archive Mode) with a
     corresponding category, rename the category there as well.

‘C m’
     Move the current category (with all its items) to another todo file
     (‘todo-move-category’).  If this category’s file has an archive
     (see 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.

‘C k’
     Delete the current category (‘todo-delete-category’).(1)  To delete
     a category that contains items, you have to confirm your intent; if
     the category is empty, deletion is immediate.

‘C g’
     Merge the items of one category into another category, delete the
     first category and make the second category current
     (‘todo-merge-category’).  If both the first and second categories
     also have archived items (see 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 ‘j’, and as with that command,
     passing a prefix argument, i.e., typing ‘C-u C g’, prompts for a
     file and confines merging to a category in that file.

   ---------- Footnotes ----------

   (1) This binding is mnemonic for “kill” to parallel the binding ‘k’
for item deletion, since ‘d’ is bound to another item editing command
(see Done Items).

5.3 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.

5.3.1 Inserting New Items
-------------------------

To add a new todo item to a category, type ‘i’, which is bound to the
command ‘todo-insert-item’.

‘i’
     This command is the entry point for inserting new items into a
     category (‘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.(1)  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 ‘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.

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
‘diary-insert-entry’ (see 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 ‘todo-insert-item’.

   • ‘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 ‘todo-insert-item’.  By
     default, such new items are given highest priority, i.e., inserted
     at the top of the list.

   • ‘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.

   • ‘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 ‘todo-nondiary-marker’.  By
     default, new todo items are so marked, thus excluded from the
     diary.

   • ‘todo-diary-nonmarking’ is for adding or omitting
     ‘diary-nonmarking-symbol’ to items displayed in the diary, to
     control whether they are marked in the calendar (see
     Format of Diary File (emacs)).  By default, todo items that are
     diary entries lack this symbol, thus are marked in the calendar.

   Beside setting these options, for more flexibility you can also pass
certain parameters on each invocation of ‘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 ‘i’.

   Here is a list of the item insertion parameters together with their
mnemonically associated keys(2) and descriptions of their effect in
‘todo-insert-item’:

  1. ‘default’ (‘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.

     ‘copy’ (‘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.)

  2. ‘diary’ (‘y’): Override the option ‘todo-include-in-diary’; that
     is, add ‘todo-nondiary-marker’ if the option is non-‘nil’, omit
     this marker if the option is ‘nil’.

     ‘nonmarking’ (‘k’): Override the option ‘todo-diary-nonmarking’;
     that is, add ‘diary-nonmarking-symbol’ if the option is non-‘nil’,
     omit this symbol if the option is ‘nil’.  Since this symbol only
     applies to diary items, the new item is automatically marked as
     such, i.e., lacks ‘todo-nondiary-marker’.

  3. ‘calendar’ (‘c’): Pop up the Emacs calendar and click a date in it
     to use that date in the new todo item’s header.

     ‘date’ (‘d’): Prompt for entering in the minibuffer the year, month
     (with completion) and day number components of the header.

     ‘dayname’ (‘n’): Prompt for entering in the minibuffer a weekday
     name as the date header instead of a year-month-day string.

  4. ‘time’ (‘t’): Prompt for entering a time string in the minibuffer
     instead of automatically inserting the current time; however,
     typing <RET> at the prompt enters the current time if
     ‘todo-always-add-time-string’ is non-‘nil’, otherwise it enters the
     empty string (i.e., no time string).

  5. ‘here’ (‘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.

     ‘region’ (‘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
     ‘todo-use-only-highlighted-region’ is non-‘nil’, then use the
     region only when it is highlighted; otherwise, use the region
     regardless of highlighting.

   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, ‘i y’ is not a complete key sequence; rather, you must type ‘i
y y’.

   By contrast, the keys of groups 1 and 5 are final keys; for example,
‘i i’ and ‘i h’ are complete sequences.  The reason for making two
separate groups of the final keys is that the parameters ‘default’ and
‘copy’ cannot be combined with any other parameters, while ‘here’ and
‘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 ‘i’ to invoke ‘todo-insert-item’, looks like this:

     Press a key (so far i):  { i=>default p=>copy } { y=>diary k=>nonmarking } { c=>calendar d=>date n=>dayname } t=>time { h=>here r=>region }

If you now type ‘y’, the prompt changes to this:

     Press a key (so far i y):  y=>diary:GO! { c=>calendar d=>date n=>dayname } t=>time { h=>here r=>region }

Notice that the pair ‘k=>nonmarking’ is now absent, since it belongs to
the same group as the selected pair ‘y=>diary’, hence is no longer
available for this sequence.  Since ‘y’ is a continuation key, it is
still available, but now the string ‘:GO!’ is appended to the pair to
remind you that pressing this key again will complete the sequence.

   An alternative to the key sequence ‘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 ‘i t’ (‘todo-insert-item-from-calendar’)
prompts for a new item and its priority and inserts it in the current
category.  This command, like ‘todo-insert-item’, also accepts one or
two prefix arguments for choosing the category via minibuffer
completion.  Note, however, that the key sequence ‘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 ‘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.)

   ---------- Footnotes ----------

   (1) There are two insertion parameters that override prompting for
and manually entering the new item’s text, see below.

   (2) The non-mnemonic choice of ‘i’ for the parameter ‘default’ is
motivated by the convenience of repeating the ‘i’ used to invoke
‘todo-insert-item’.

5.3.2 Editing Item Headers and Text
-----------------------------------

To make changes to an existing item’s content or header, type ‘e’, which
is bound to the command ‘todo-edit-item’.

‘e’
     This command is the entry point for textually editing existing
     items in a category (‘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.

   Here is a list of the item editing parameters together with their
mnemonically associated keys and descriptions of their effect in
‘todo-edit-item’.  The list is divided into three groups, for reasons
explained below.

  1. ‘edit’ (‘e’): Edit the text of the current item in the minibuffer;
     the item’s header is omitted.

     ‘header’ (‘h’): Edit the text and header of the current item in the
     minibuffer.

     ‘multiline’ (‘m’): Edit the text of the current item in a special
     buffer in Todo Edit mode.  After editing, type ‘C-x C-q’ to return
     to Todo mode.(1)

     ‘diary’ (‘y’): Change the current item’s diary inclusion status by
     adding ‘todo-nondiary-marker’ if the item lacks this, or by
     removing it if present.

     ‘nonmarking’ (‘k’): Change the current item’s calendar marking
     status by adding ‘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
     ‘todo-nondiary-marker’ is present, it is removed.

     ‘date’ (‘d’): Prompt for a final key from the second group of item
     editing parameters to edit the current item’s date string.

     ‘time’ (‘t’): Edit the current item’s time string, if present;
     otherwise, add one.  Typing <RET> at the prompt enters the current
     time if ‘todo-always-add-time-string’ is non-‘nil’, otherwise it
     enters the empty string (i.e., no time string).

Editing the text of a lengthy item in the minibuffer can be
inconvenient; therefore, if you type ‘e e’ or ‘e h’ on an item whose
text contains more than one logical line, the effect is the same as if
you had typed ‘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 ‘date’ parameter, this completes the item editing invocation
begun by typing ‘e’.  Pressing ‘d’ to pass the ‘date’ parameter,
however, prompts you with the following parameters and their associated
keys, and pressing any of these completes the invocation.

  2. ‘full’ (‘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 ‘todo-always-add-time-string’ is non-‘nil’, also
     for editing its time string.

     ‘calendar’ (‘c’): This pops up the Emacs calendar, and after you
     type <RET> on a date in the calendar makes that date the item’s
     date.

     ‘today’ (‘a’): Make the item’s date today’s date.

     ‘dayname’ (‘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.

     ‘year’ (‘y’): Edit just the year component of the current item’s
     date string.

     ‘month’ (‘m’): Edit just the month component of the current item’s
     date string (with completion).

     ‘daynum’ (‘d’): Edit just the day number component of the current
     item’s date string.

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 ‘- 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 (see 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 (see ‘todo-item-done’),
or retroactively add a comment, by passing either of these parameters.

  3. ‘add/edit comment’ (‘c’): Edit the current done item’s comment, if
     it has one; otherwise, prompt for and add a comment.

     ‘delete comment’ (‘d’): Delete the current done item’s comment, if
     it has one.

   The command ‘todo-edit-item’ is sensitive to the distinction between
not done and done todo items.  If you type ‘e’ when point is on a done
item, this displays the following prompt in the echo area:

     Press a key (so far e): c=>add/edit comment d=>delete comment

Only by typing ‘c’ or ‘d’ in response to this prompt can you complete
the invocation.  In contrast, if you type ‘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:

     Press a key (so far e): e=>edit h=>header m=>multiline y=>diary k=>nonmarking d=>date t=>time

   As noted above, passing the ‘date’ parameter does not complete the
invocation of ‘todo-edit-item’; rather, it displays the following
prompt, and typing any of these keys does complete the invocation:

     Press a key (so far e d): f=>full c=>calendar a=>today n=>dayname y=>year m=>month d=>daynum

   In addition to the item-level invocations ‘e y’, to change the
current item’s diary inclusion status, and ‘e k’, to change the current
item’s calendar marking status, Todo mode also has two related
category-level commands:

‘C e y’
‘C e k’
     Add ‘todo-nondiary-marker’ and ‘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.

Like ‘e k’, ‘C e k’ automatically removes ‘todo-nondiary-marker’ from
all items it is present on, since only diary items can bear
‘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
‘e y’ or ‘e k’, see Marked Items).

   ---------- Footnotes ----------

   (1) This runs a format check to ensure the item is well-formed.
However, unlike the command ‘F e’ (see File Editing), ‘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.

5.3.3 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.

5.3.3.1 Reprioritizing Items
............................

There are three ways to change a todo item’s priority:

‘r’
     Raise the current item’s priority by one, exchanging its position
     in the list with that of the item directly above it
     (‘todo-raise-item-priority’).

‘l’
     Lower the current item’s priority by one, exchanging its position
     in the list with that of the item directly below it
     (‘todo-lower-item-priority’).

‘#’
     Prompt for a number and relocate the item to the corresponding
     position in the list (‘todo-set-item-priority’).  For example,
     entering ‘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., ‘3 #’ gives the item
     third highest priority without prompting.  (Prefix arguments have
     no effect with ‘r’ or ‘l’.)

5.3.3.2 Moving and Deleting Items
.................................

You can move an item to another category, thereby recategorizing it:

‘m’
     Move the item at point to another category (‘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 ‘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.

   You can delete an item, thereby permanently (and, as far as Todo mode
is concerned, irrevocably) removing it from the todo file:

‘k’
     Delete the todo item at point (‘todo-delete-item’; the binding is
     mnemonic for “kill”, since ‘d’ is used for marking items as done
     (see Done Items); but note that ‘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 ‘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
     Reordering Categories.)

     Note: Todo commands that require user confirmation, such as ‘k’,
     use a modified form of ‘y-or-n-p’, which by default only accepts
     ‘y’ or ‘Y’, but not <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 <SPC> for confirmation, enable the option ‘todo-y-with-space’.

5.3.3.3 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 (see Todo Archive Mode).

‘d’
     This command (‘todo-item-done’) removes the todo item at point from
     the todo list, appends to the original header a header consisting
     of ‘todo-done-string’ (by default ‘DONE ’) and the current date,
     and if ‘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 ‘todo-comment-string’ (by default
     ‘COMMENT: ’).

   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:

‘C v’
‘v’
     Make the done items section of the current category visible if it
     is hidden, or hide it if it is visible
     (‘todo-toggle-view-done-items’).  If you always want to see the
     done items section on entering a category, enable the option
     ‘todo-show-with-done’; you can still use ‘C v’ or ‘v’ to hide (and
     unhide) it.

‘F V’
‘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 (‘todo-toggle-view-done-only’).

   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
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.

‘e c’
     Edit the current done item’s comment, if it has one; otherwise,
     prompt for and add a comment.

‘e d’
     Delete the current done item’s comment, if it has one.

‘m’
     Move the done item at point to the top of the done items section of
     another category (‘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.

‘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 (‘todo-item-undone’).
     If the done item has a comment, you are asked whether to delete it
     from the restored item.

6 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 ‘todo-directory’ but have the
extension ‘.toda’ instead of ‘.todo’.

6.1 Creating and Visiting Archives
==================================

Todo mode provides the following command for archiving items:

‘A d’
     This command (‘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.

   Typing ‘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 ‘todo-skip-archived-categories’.  When this is
non-‘nil’, such empty todo categories are skipped over by the sequential
category navigation commands ‘f’ and ‘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 ‘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:

‘A f’
     Switch to a buffer displaying the archived category corresponding
     to the current todo category (‘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.

‘A c’
     Choose an archive to visit, whether or not the current todo file
     has an archive (‘todo-choose-archive’).

   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.

6.2 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: ‘f’ and ‘b’ navigate between the categories of the current
archive, and ‘n’ and ‘p’ navigate between the done items of the current
archive category.

   The commands ‘t’ and ‘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: ‘t’ prompt for and switch to a todo file, and with
‘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:

‘a’
     This command (‘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.

   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:

‘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 (‘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.

   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 ‘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 ‘F k’ (see 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.

7 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.

‘*’
     Mark the item at point if it is unmarked, and remove the mark it is
     already marked (‘todo-toggle-mark-item’).  The mark is a string
     specified by the option ‘todo-item-mark’ (by default ‘*’) appended
     in front of the item header (more precisely, in front of the item’s
     priority number or prefix; see 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.

‘C *’
     Mark all todo items in the current category.

‘C u’
     Unmark all todo item in the current category.

   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 ‘C V’ or ‘V’.

   The following commands operate on marked items:

   • ‘k’ (deleting)
   • ‘m’ (moving to another category)
   • ‘d’ (moving to the done items section; note that ‘C-u d’ adds the
     same comment to all marked items)
   • ‘A d’ (archiving)
   • ‘u’ (both in Todo mode for undoing a done item and in Todo Archive
     mode for unarchiving an item)
   • the commands for editing the item header (those beginning with the
     prefix ‘e d’ as well as ‘e t’, ‘e y’ and ‘e k’)

The item insertion, textual editing and priority changing commands do
not operate on marked items.

   If you use ‘m’, ‘d’, ‘A d’ or ‘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 ‘m’ and ‘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.

8 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.

‘F c’
     Typing this command (‘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.

   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 ‘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 ‘F c’ to display the table of
categories, you can also arrange to have it displayed on the first
invocation of ‘todo-show’ for a given file (i.e., either using
‘todo-show’ to initiate a Todo session, or calling it in Todo mode to
visit another todo file).  To do this customize the option
‘todo-show-first’.

8.1 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 <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:

   • ‘c’ to sort by category numerically or alphabetically;
   • ‘t’ to sort by todo item counts;
   • ‘y’ to sort by diary item counts;
   • ‘d’ to sort by done item counts;
   • ‘a’ to sort by archived item counts.

   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 ‘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
‘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 (see
Faces).

   You can navigate around the table:

‘n’
‘<TAB>’
     Advance point to the next button.

‘p’
‘S-<TAB>’
     Put point on the previous button.

   These commands are cyclic, e.g., when point is on the last button,
pressing ‘n’ moves it to the first button.

   Typing ‘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 ‘F c’.

8.2 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 ‘f’
and ‘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:

‘r’
     Raise the current line of the table (the one the cursor is on),
     decreasing the category’s number by one (‘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.

‘l’
     Lower the current line of the table, increasing the category’s
     number by one (‘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.

‘#’
     Prompt for a number between 1 and the number of categories in the
     file and reorder the table accordingly
     (‘todo-set-category-number’).  If called with a numeric prefix
     argument within the allowed range, reorder the table without
     prompting.

   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.

     *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 ‘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 ‘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 ‘F
     e’.

9 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:

‘S’
     This command (‘todo-search’; the key is capital ‘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.

‘X’
     This command (‘todo-clear-matches’) removes any highlighting added
     by ‘S’.  This is so you can leave the matches highlighted at the
     end of the search and remove the highlighting later.

   These commands are also available in Todo Archive mode.

10 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.

10.1 Filtering Items
====================

Todo mode provides three ways to filter items: a general filter for
items matching a user-entered regular expression, as with the search
command; and two specific filters, one for diary-displayable items
(i.e., those lacking ‘todo-nondiary-marker’) and one for top priority
items (more on the latter below).  The commands for each filter come in
pairs, one for filtering just the current todo file and one for
filtering a user-specified list of todo files.  Thus, there are six item
filtering commands:(1)

   • ‘F x x’ (‘todo-filter-regexp-items’)
   • ‘F x m’ (‘todo-filter-regexp-items-multifile’)
   • ‘F y y’ (‘todo-filter-diary-items’)
   • ‘F y m’ (‘todo-filter-diary-items-multifile’)
   • ‘F t t’ (‘todo-filter-top-priorities’)
   • ‘F t m’ (‘todo-filter-top-priorities-multifile’)

   There are two ways to specify which files the multifile filtering
commands apply to.  If there are files you want to filter every time you
use these commands, customize the option ‘todo-filter-files’.  If you
leave this option empty (the default), invoking a multifile filtering
command pops up a buffer similar to the Customization buffer for
‘todo-filter-files’, in which you can select files to filter just for
this invocation.

   Diary and top priority items are by definition non-done todo items,
but when filtering by regular expression, you can extend the scope of
the command to done items by enabling the option
‘todo-filter-done-items’.  Then ‘F x x’ and ‘F x m’ will gather both
matching todo and matching done items (including done items from any
archive files corresponding to the selected todo files) into the virtual
category of filtered items.

   There are several ways to specify how many items in each category
count as top priorities and hence get filtered by ‘F t t’ and ‘F t m’:

   • The option ‘todo-top-priorities’ specifies a single default number
     for all categories and all todo files; its default value is 1,
     which means just the highest priority item in every category is
     filtered, unless otherwise specified.
   • The option ‘todo-top-priorities-overrides’ lists file-wide
     overrides of ‘todo-top-priorities’ as well as category-specific
     overrides.  It is empty by default.  However, using the Custom
     facility to set this option would be tedious and error-prone, so
     instead you should use the commands ‘F t s’ and ‘C t s’.  The
     former sets (i.e., overrides) the default number of top priorities
     for all categories in the current todo file, and the latter sets
     the number of top priorities for the current category.  To exclude
     a category or file from filtering by ‘F t t’ and ‘F t m’, set the
     number to ‘0’.
   • You can invoke ‘F t t’ and ‘F t m’ with a numeric prefix argument,
     which specifies the number of top priorities in each category just
     for this invocation, overriding both
     ‘todo-top-priorities-overrides’ and ‘todo-top-priorities’.

   ---------- Footnotes ----------

   (1) The use of ‘F’ in the key sequences of these commands naturally
recalls “filter”, but is also consistent with the Todo mode mnemonic key
binding convention, since the commands involve one or more whole files.

10.2 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 ‘n’ and ‘p’ work the same in
Todo Filtered Items mode as in Todo mode, as do the file and category
jumping commands ‘t’ and ‘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:

‘g’
‘<RET>’
     If you type this command (‘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.

   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:

‘r’
‘l’
‘#’
     These commands raise, lower, or set, respectively, the current
     item’s priority in the virtual category.

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.

10.3 Files of Filtered Items
============================

Typing ‘s’ in Todo Filtered Items mode saves the buffer of filtered
items to a file in ‘todo-directory’.  Files of items filtered by regular
expression have the extension ‘.todr’, those with filtered diary items
have the extension ‘.tody’ and those with filtered top priorities have
the extension ‘.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 ‘C-u’ to
use the values of ‘todo-top-priorities-overrides’ or
‘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 ‘find-file’:

‘F f’
     Visit a saved file of filtered items, which you choose via
     minibuffer completion (‘todo-find-filtered-items-file’).

Alternatively, as with tables of categories, by customizing
‘todo-show-first’ you can have the first invocation of ‘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, ‘todo-show’
simply defaults to visiting the file and displaying its first category,
as usual.

   The command ‘F k’ (see File Editing) is also available in Todo
Filtered Items mode.  It deletes the current filtered items file.

11 Todo Display Features
************************

You can change the appearance of Todo mode buffers in a variety of ways.

11.1 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 (‘todo-date’ and
‘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 ‘todo-nondiary-marker’) is
earlier than the current date and time, they are displayed in a
different face (‘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 (‘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 (‘todo-archived-only’).

   The ‘todo-faces’ customization group contains a complete list of Todo
mode faces and brief descriptions of their use.

11.2 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 ‘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 ‘#’ or move it with ‘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 ‘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 ‘todo-prefix’ (the empty string by default).  Another alternative
is to temporarily hide the item numbering:

‘F N’
‘N’
     Toggle between displaying item numbering and displaying the
     ‘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.)

   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 Filtering Items) is displayed in a
face (‘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.

11.3 Other Display Commands and Options
=======================================

There are two additional toggle commands that affect display in the
current file:

‘F h’
‘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.

‘F H’
‘H’
     Highlight the current item (with the face ‘hl-line’) if
     unhighlighted, or remove its highlighting.  When item highlighting
     is enabled, it follows navigation by ‘n’ or ‘p’.  If you want to
     have current item highlighting by default, enable the option
     ‘todo-highlight-item’.  ‘F H’ or ‘H’ will still toggle it.

   There are two options which affect the display of items whose content
is longer than one screen line:

   • ‘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.

   • ‘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
     ‘todo-indent-to-here’ spaces.

   The indentation inserted after a hard newline is actually a tab
character, and the Todo modes that display items bind ‘tab-width’ to
‘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 ‘todo-done-separator-string’; you can also change the
face of the separator string (‘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
‘todo-categories’ and ‘todo-filtered’ for details.

12 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:

‘P B’
     Send the printable buffer output directly to your printer.

‘P F’
     Prompt for a file name and write the printable output to that file.

   By default, Todo uses ‘ps-print-buffer-with-faces’ to make the
printable version; you can change this by setting the option
‘todo-print-function’.

13 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
‘todo-directory’.(1)

   This conversion function is automatically called the first time you
invoke ‘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 ‘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
‘todo-legacy-date-time-regexp’ for details.)

   ---------- Footnotes ----------

   (1) 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.

Appendix A GNU Free Documentation License
*****************************************

                     Version 1.3, 3 November 2008

     Copyright © 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
     <https://fsf.org/>

     Everyone is permitted to copy and distribute verbatim copies
     of this license document, but changing it is not allowed.

  0. PREAMBLE

     The purpose of this License is to make a manual, textbook, or other
     functional and useful document “free” in the sense of freedom: to
     assure everyone the effective freedom to copy and redistribute it,
     with or without modifying it, either commercially or
     noncommercially.  Secondarily, this License preserves for the
     author and publisher a way to get credit for their work, while not
     being considered responsible for modifications made by others.

     This License is a kind of “copyleft”, which means that derivative
     works of the document must themselves be free in the same sense.
     It complements the GNU General Public License, which is a copyleft
     license designed for free software.

     We have designed this License in order to use it for manuals for
     free software, because free software needs free documentation: a
     free program should come with manuals providing the same freedoms
     that the software does.  But this License is not limited to
     software manuals; it can be used for any textual work, regardless
     of subject matter or whether it is published as a printed book.  We
     recommend this License principally for works whose purpose is
     instruction or reference.

  1. APPLICABILITY AND DEFINITIONS

     This License applies to any manual or other work, in any medium,
     that contains a notice placed by the copyright holder saying it can
     be distributed under the terms of this License.  Such a notice
     grants a world-wide, royalty-free license, unlimited in duration,
     to use that work under the conditions stated herein.  The
     “Document”, below, refers to any such manual or work.  Any member
     of the public is a licensee, and is addressed as “you”.  You accept
     the license if you copy, modify or distribute the work in a way
     requiring permission under copyright law.

     A “Modified Version” of the Document means any work containing the
     Document or a portion of it, either copied verbatim, or with
     modifications and/or translated into another language.

     A “Secondary Section” is a named appendix or a front-matter section
     of the Document that deals exclusively with the relationship of the
     publishers or authors of the Document to the Document’s overall
     subject (or to related matters) and contains nothing that could
     fall directly within that overall subject.  (Thus, if the Document
     is in part a textbook of mathematics, a Secondary Section may not
     explain any mathematics.)  The relationship could be a matter of
     historical connection with the subject or with related matters, or
     of legal, commercial, philosophical, ethical or political position
     regarding them.

     The “Invariant Sections” are certain Secondary Sections whose
     titles are designated, as being those of Invariant Sections, in the
     notice that says that the Document is released under this License.
     If a section does not fit the above definition of Secondary then it
     is not allowed to be designated as Invariant.  The Document may
     contain zero Invariant Sections.  If the Document does not identify
     any Invariant Sections then there are none.

     The “Cover Texts” are certain short passages of text that are
     listed, as Front-Cover Texts or Back-Cover Texts, in the notice
     that says that the Document is released under this License.  A
     Front-Cover Text may be at most 5 words, and a Back-Cover Text may
     be at most 25 words.

     A “Transparent” copy of the Document means a machine-readable copy,
     represented in a format whose specification is available to the
     general public, that is suitable for revising the document
     straightforwardly with generic text editors or (for images composed
     of pixels) generic paint programs or (for drawings) some widely
     available drawing editor, and that is suitable for input to text
     formatters or for automatic translation to a variety of formats
     suitable for input to text formatters.  A copy made in an otherwise
     Transparent file format whose markup, or absence of markup, has
     been arranged to thwart or discourage subsequent modification by
     readers is not Transparent.  An image format is not Transparent if
     used for any substantial amount of text.  A copy that is not
     “Transparent” is called “Opaque”.

     Examples of suitable formats for Transparent copies include plain
     ASCII without markup, Texinfo input format, LaTeX input format,
     SGML or XML using a publicly available DTD, and standard-conforming
     simple HTML, PostScript or PDF designed for human modification.
     Examples of transparent image formats include PNG, XCF and JPG.
     Opaque formats include proprietary formats that can be read and
     edited only by proprietary word processors, SGML or XML for which
     the DTD and/or processing tools are not generally available, and
     the machine-generated HTML, PostScript or PDF produced by some word
     processors for output purposes only.

     The “Title Page” means, for a printed book, the title page itself,
     plus such following pages as are needed to hold, legibly, the
     material this License requires to appear in the title page.  For
     works in formats which do not have any title page as such, “Title
     Page” means the text near the most prominent appearance of the
     work’s title, preceding the beginning of the body of the text.

     The “publisher” means any person or entity that distributes copies
     of the Document to the public.

     A section “Entitled XYZ” means a named subunit of the Document
     whose title either is precisely XYZ or contains XYZ in parentheses
     following text that translates XYZ in another language.  (Here XYZ
     stands for a specific section name mentioned below, such as
     “Acknowledgements”, “Dedications”, “Endorsements”, or “History”.)
     To “Preserve the Title” of such a section when you modify the
     Document means that it remains a section “Entitled XYZ” according
     to this definition.

     The Document may include Warranty Disclaimers next to the notice
     which states that this License applies to the Document.  These
     Warranty Disclaimers are considered to be included by reference in
     this License, but only as regards disclaiming warranties: any other
     implication that these Warranty Disclaimers may have is void and
     has no effect on the meaning of this License.

  2. VERBATIM COPYING

     You may copy and distribute the Document in any medium, either
     commercially or noncommercially, provided that this License, the
     copyright notices, and the license notice saying this License
     applies to the Document are reproduced in all copies, and that you
     add no other conditions whatsoever to those of this License.  You
     may not use technical measures to obstruct or control the reading
     or further copying of the copies you make or distribute.  However,
     you may accept compensation in exchange for copies.  If you
     distribute a large enough number of copies you must also follow the
     conditions in section 3.

     You may also lend copies, under the same conditions stated above,
     and you may publicly display copies.

  3. COPYING IN QUANTITY

     If you publish printed copies (or copies in media that commonly
     have printed covers) of the Document, numbering more than 100, and
     the Document’s license notice requires Cover Texts, you must
     enclose the copies in covers that carry, clearly and legibly, all
     these Cover Texts: Front-Cover Texts on the front cover, and
     Back-Cover Texts on the back cover.  Both covers must also clearly
     and legibly identify you as the publisher of these copies.  The
     front cover must present the full title with all words of the title
     equally prominent and visible.  You may add other material on the
     covers in addition.  Copying with changes limited to the covers, as
     long as they preserve the title of the Document and satisfy these
     conditions, can be treated as verbatim copying in other respects.

     If the required texts for either cover are too voluminous to fit
     legibly, you should put the first ones listed (as many as fit
     reasonably) on the actual cover, and continue the rest onto
     adjacent pages.

     If you publish or distribute Opaque copies of the Document
     numbering more than 100, you must either include a machine-readable
     Transparent copy along with each Opaque copy, or state in or with
     each Opaque copy a computer-network location from which the general
     network-using public has access to download using public-standard
     network protocols a complete Transparent copy of the Document, free
     of added material.  If you use the latter option, you must take
     reasonably prudent steps, when you begin distribution of Opaque
     copies in quantity, to ensure that this Transparent copy will
     remain thus accessible at the stated location until at least one
     year after the last time you distribute an Opaque copy (directly or
     through your agents or retailers) of that edition to the public.

     It is requested, but not required, that you contact the authors of
     the Document well before redistributing any large number of copies,
     to give them a chance to provide you with an updated version of the
     Document.

  4. MODIFICATIONS

     You may copy and distribute a Modified Version of the Document
     under the conditions of sections 2 and 3 above, provided that you
     release the Modified Version under precisely this License, with the
     Modified Version filling the role of the Document, thus licensing
     distribution and modification of the Modified Version to whoever
     possesses a copy of it.  In addition, you must do these things in
     the Modified Version:

       A. Use in the Title Page (and on the covers, if any) a title
          distinct from that of the Document, and from those of previous
          versions (which should, if there were any, be listed in the
          History section of the Document).  You may use the same title
          as a previous version if the original publisher of that
          version gives permission.

       B. List on the Title Page, as authors, one or more persons or
          entities responsible for authorship of the modifications in
          the Modified Version, together with at least five of the
          principal authors of the Document (all of its principal
          authors, if it has fewer than five), unless they release you
          from this requirement.

       C. State on the Title page the name of the publisher of the
          Modified Version, as the publisher.

       D. Preserve all the copyright notices of the Document.

       E. Add an appropriate copyright notice for your modifications
          adjacent to the other copyright notices.

       F. Include, immediately after the copyright notices, a license
          notice giving the public permission to use the Modified
          Version under the terms of this License, in the form shown in
          the Addendum below.

       G. Preserve in that license notice the full lists of Invariant
          Sections and required Cover Texts given in the Document’s
          license notice.

       H. Include an unaltered copy of this License.

       I. Preserve the section Entitled “History”, Preserve its Title,
          and add to it an item stating at least the title, year, new
          authors, and publisher of the Modified Version as given on the
          Title Page.  If there is no section Entitled “History” in the
          Document, create one stating the title, year, authors, and
          publisher of the Document as given on its Title Page, then add
          an item describing the Modified Version as stated in the
          previous sentence.

       J. Preserve the network location, if any, given in the Document
          for public access to a Transparent copy of the Document, and
          likewise the network locations given in the Document for
          previous versions it was based on.  These may be placed in the
          “History” section.  You may omit a network location for a work
          that was published at least four years before the Document
          itself, or if the original publisher of the version it refers
          to gives permission.

       K. For any section Entitled “Acknowledgements” or “Dedications”,
          Preserve the Title of the section, and preserve in the section
          all the substance and tone of each of the contributor
          acknowledgements and/or dedications given therein.

       L. Preserve all the Invariant Sections of the Document, unaltered
          in their text and in their titles.  Section numbers or the
          equivalent are not considered part of the section titles.

       M. Delete any section Entitled “Endorsements”.  Such a section
          may not be included in the Modified Version.

       N. Do not retitle any existing section to be Entitled
          “Endorsements” or to conflict in title with any Invariant
          Section.

       O. Preserve any Warranty Disclaimers.

     If the Modified Version includes new front-matter sections or
     appendices that qualify as Secondary Sections and contain no
     material copied from the Document, you may at your option designate
     some or all of these sections as invariant.  To do this, add their
     titles to the list of Invariant Sections in the Modified Version’s
     license notice.  These titles must be distinct from any other
     section titles.

     You may add a section Entitled “Endorsements”, provided it contains
     nothing but endorsements of your Modified Version by various
     parties—for example, statements of peer review or that the text has
     been approved by an organization as the authoritative definition of
     a standard.

     You may add a passage of up to five words as a Front-Cover Text,
     and a passage of up to 25 words as a Back-Cover Text, to the end of
     the list of Cover Texts in the Modified Version.  Only one passage
     of Front-Cover Text and one of Back-Cover Text may be added by (or
     through arrangements made by) any one entity.  If the Document
     already includes a cover text for the same cover, previously added
     by you or by arrangement made by the same entity you are acting on
     behalf of, you may not add another; but you may replace the old
     one, on explicit permission from the previous publisher that added
     the old one.

     The author(s) and publisher(s) of the Document do not by this
     License give permission to use their names for publicity for or to
     assert or imply endorsement of any Modified Version.

  5. COMBINING DOCUMENTS

     You may combine the Document with other documents released under
     this License, under the terms defined in section 4 above for
     modified versions, provided that you include in the combination all
     of the Invariant Sections of all of the original documents,
     unmodified, and list them all as Invariant Sections of your
     combined work in its license notice, and that you preserve all
     their Warranty Disclaimers.

     The combined work need only contain one copy of this License, and
     multiple identical Invariant Sections may be replaced with a single
     copy.  If there are multiple Invariant Sections with the same name
     but different contents, make the title of each such section unique
     by adding at the end of it, in parentheses, the name of the
     original author or publisher of that section if known, or else a
     unique number.  Make the same adjustment to the section titles in
     the list of Invariant Sections in the license notice of the
     combined work.

     In the combination, you must combine any sections Entitled
     “History” in the various original documents, forming one section
     Entitled “History”; likewise combine any sections Entitled
     “Acknowledgements”, and any sections Entitled “Dedications”.  You
     must delete all sections Entitled “Endorsements.”

  6. COLLECTIONS OF DOCUMENTS

     You may make a collection consisting of the Document and other
     documents released under this License, and replace the individual
     copies of this License in the various documents with a single copy
     that is included in the collection, provided that you follow the
     rules of this License for verbatim copying of each of the documents
     in all other respects.

     You may extract a single document from such a collection, and
     distribute it individually under this License, provided you insert
     a copy of this License into the extracted document, and follow this
     License in all other respects regarding verbatim copying of that
     document.

  7. AGGREGATION WITH INDEPENDENT WORKS

     A compilation of the Document or its derivatives with other
     separate and independent documents or works, in or on a volume of a
     storage or distribution medium, is called an “aggregate” if the
     copyright resulting from the compilation is not used to limit the
     legal rights of the compilation’s users beyond what the individual
     works permit.  When the Document is included in an aggregate, this
     License does not apply to the other works in the aggregate which
     are not themselves derivative works of the Document.

     If the Cover Text requirement of section 3 is applicable to these
     copies of the Document, then if the Document is less than one half
     of the entire aggregate, the Document’s Cover Texts may be placed
     on covers that bracket the Document within the aggregate, or the
     electronic equivalent of covers if the Document is in electronic
     form.  Otherwise they must appear on printed covers that bracket
     the whole aggregate.

  8. TRANSLATION

     Translation is considered a kind of modification, so you may
     distribute translations of the Document under the terms of section
     4.  Replacing Invariant Sections with translations requires special
     permission from their copyright holders, but you may include
     translations of some or all Invariant Sections in addition to the
     original versions of these Invariant Sections.  You may include a
     translation of this License, and all the license notices in the
     Document, and any Warranty Disclaimers, provided that you also
     include the original English version of this License and the
     original versions of those notices and disclaimers.  In case of a
     disagreement between the translation and the original version of
     this License or a notice or disclaimer, the original version will
     prevail.

     If a section in the Document is Entitled “Acknowledgements”,
     “Dedications”, or “History”, the requirement (section 4) to
     Preserve its Title (section 1) will typically require changing the
     actual title.

  9. TERMINATION

     You may not copy, modify, sublicense, or distribute the Document
     except as expressly provided under this License.  Any attempt
     otherwise to copy, modify, sublicense, or distribute it is void,
     and will automatically terminate your rights under this License.

     However, if you cease all violation of this License, then your
     license from a particular copyright holder is reinstated (a)
     provisionally, unless and until the copyright holder explicitly and
     finally terminates your license, and (b) permanently, if the
     copyright holder fails to notify you of the violation by some
     reasonable means prior to 60 days after the cessation.

     Moreover, your license from a particular copyright holder is
     reinstated permanently if the copyright holder notifies you of the
     violation by some reasonable means, this is the first time you have
     received notice of violation of this License (for any work) from
     that copyright holder, and you cure the violation prior to 30 days
     after your receipt of the notice.

     Termination of your rights under this section does not terminate
     the licenses of parties who have received copies or rights from you
     under this License.  If your rights have been terminated and not
     permanently reinstated, receipt of a copy of some or all of the
     same material does not give you any rights to use it.

  10. FUTURE REVISIONS OF THIS LICENSE

     The Free Software Foundation may publish new, revised versions of
     the GNU Free Documentation License from time to time.  Such new
     versions will be similar in spirit to the present version, but may
     differ in detail to address new problems or concerns.  See
     <https://www.gnu.org/licenses/>.

     Each version of the License is given a distinguishing version
     number.  If the Document specifies that a particular numbered
     version of this License “or any later version” applies to it, you
     have the option of following the terms and conditions either of
     that specified version or of any later version that has been
     published (not as a draft) by the Free Software Foundation.  If the
     Document does not specify a version number of this License, you may
     choose any version ever published (not as a draft) by the Free
     Software Foundation.  If the Document specifies that a proxy can
     decide which future versions of this License can be used, that
     proxy’s public statement of acceptance of a version permanently
     authorizes you to choose that version for the Document.

  11. RELICENSING

     “Massive Multiauthor Collaboration Site” (or “MMC Site”) means any
     World Wide Web server that publishes copyrightable works and also
     provides prominent facilities for anybody to edit those works.  A
     public wiki that anybody can edit is an example of such a server.
     A “Massive Multiauthor Collaboration” (or “MMC”) contained in the
     site means any set of copyrightable works thus published on the MMC
     site.

     “CC-BY-SA” means the Creative Commons Attribution-Share Alike 3.0
     license published by Creative Commons Corporation, a not-for-profit
     corporation with a principal place of business in San Francisco,
     California, as well as future copyleft versions of that license
     published by that same organization.

     “Incorporate” means to publish or republish a Document, in whole or
     in part, as part of another Document.

     An MMC is “eligible for relicensing” if it is licensed under this
     License, and if all works that were first published under this
     License somewhere other than this MMC, and subsequently
     incorporated in whole or in part into the MMC, (1) had no cover
     texts or invariant sections, and (2) were thus incorporated prior
     to November 1, 2008.

     The operator of an MMC Site may republish an MMC contained in the
     site under CC-BY-SA on the same site at any time before August 1,
     2009, provided the MMC is eligible for relicensing.

ADDENDUM: How to use this License for your documents
====================================================

To use this License in a document you have written, include a copy of
the License in the document and put the following copyright and license
notices just after the title page:

       Copyright (C)  YEAR  YOUR NAME.
       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, no Front-Cover Texts, and no Back-Cover
       Texts.  A copy of the license is included in the section entitled ``GNU
       Free Documentation License''.

   If you have Invariant Sections, Front-Cover Texts and Back-Cover
Texts, replace the “with...Texts.” line with this:

         with the Invariant Sections being LIST THEIR TITLES, with
         the Front-Cover Texts being LIST, and with the Back-Cover Texts
         being LIST.

   If you have Invariant Sections without Cover Texts, or some other
combination of the three, merge those two alternatives to suit the
situation.

   If your document contains nontrivial examples of program code, we
recommend releasing these examples in parallel under your choice of free
software license, such as the GNU General Public License, to permit
their use in free software.