todo-mode: Editing Item Headers and Text
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 (
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 (‘todo-item-done’ Done Items,),
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’, Marked Items).
---------- Footnotes ----------
(1) This runs a format check to ensure the item is well-formed.
However, unlike the command ‘F e’ (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.
Info Catalog
todo-mode: Inserting New Items
todo-mode: Item Editing
todo-mode: Relocating and Removing Items