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 (emacs)Date Formats). 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 (emacs)Format of
Diary File). 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 keys7 and descriptions of their effect in
todo-insert-item
:
- ‘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.)
- ‘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
.
- ‘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.
- ‘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).
- ‘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.)
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.
- ‘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.8
‘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.
- ‘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.
- ‘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).
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 and Todo Edit Mode) 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:9
- 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
.
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 and Todo Edit Mode) 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 see 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
.10
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.)
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.
- 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.
- 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.
- 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.
- 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.
- 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:
- 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.
- 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.
- State on the Title page the name of the publisher of the
Modified Version, as the publisher.
- Preserve all the copyright notices of the Document.
- Add an appropriate copyright notice for your modifications
adjacent to the other copyright notices.
- 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.
- Preserve in that license notice the full lists of Invariant Sections
and required Cover Texts given in the Document’s license notice.
- Include an unaltered copy of this License.
- 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.
- 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.
- 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.
- 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.
- Delete any section Entitled “Endorsements”. Such a section
may not be included in the Modified Version.
- Do not retitle any existing section to be Entitled “Endorsements” or
to conflict in title with any Invariant Section.
- 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.
- 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.”
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.