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

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