todo-mode: Inserting New Items
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’ (
(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 (
(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 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’.
Info Catalog
todo-mode: Item Editing
todo-mode: Editing Item Headers and Text