Commit | Line | Data |
---|---|---|
016d3f7d SB |
1 | \input texinfo.tex @c -*-texinfo-*- |
2 | @c %**start of header | |
29993416 | 3 | @setfilename ../../info/todo-mode.info |
016d3f7d SB |
4 | @settitle Todo Mode User Manual |
5 | @syncodeindex fn cp | |
6 | @syncodeindex vr cp | |
7 | @syncodeindex ky cp | |
c6ab4664 | 8 | @documentencoding UTF-8 |
016d3f7d SB |
9 | @c %**end of header |
10 | ||
11 | @copying | |
ba318903 | 12 | Copyright @copyright{} 2013-2014 Free Software Foundation, Inc. |
016d3f7d SB |
13 | |
14 | @quotation | |
15 | Permission is granted to copy, distribute and/or modify this document | |
16 | under the terms of the GNU Free Documentation License, Version 1.3 or | |
17 | any later version published by the Free Software Foundation; with no | |
551a89e1 | 18 | Invariant Sections, with the Front-Cover Texts being ``A GNU Manual'', |
016d3f7d SB |
19 | and with the Back-Cover Texts as in (a) below. A copy of the license |
20 | is included in the section entitled ``GNU Free Documentation License''. | |
21 | ||
22 | (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and | |
23 | modify this GNU manual.'' | |
24 | @end quotation | |
25 | @end copying | |
26 | ||
2a024334 | 27 | @dircategory Emacs misc features |
016d3f7d | 28 | @direntry |
f9405d87 | 29 | * Todo Mode: (todo-mode). Make and maintain todo lists. |
016d3f7d SB |
30 | @end direntry |
31 | ||
32 | @titlepage | |
33 | @title Todo Mode User Manual | |
34 | @subtitle Facilities for making and maintaining todo lists. | |
35 | ||
36 | @author Stephen Berman | |
37 | @page | |
38 | ||
39 | @vskip 0pt plus 1filll | |
40 | @insertcopying | |
41 | @end titlepage | |
42 | ||
43 | @contents | |
44 | ||
45 | @ifnottex | |
46 | ||
47 | @node Top | |
48 | @top Todo Mode User Manual | |
49 | ||
50 | This manual describes the version of Todo mode first appearing in | |
51 | Emacs 24.4. | |
52 | ||
53 | @insertcopying | |
54 | @end ifnottex | |
55 | ||
56 | @menu | |
57 | * Overview:: | |
58 | * Todo Mode Entry Points:: | |
59 | * Key Binding Conventions:: | |
60 | * Navigation:: Moving within and between categories. | |
61 | * Editing:: Adding, deleting and changing todo | |
62 | files, categories and items. | |
63 | * Todo Archives:: Files of done todo items. | |
64 | * Marked Items:: Acting on multiple items simultaneously. | |
65 | * Todo Categories Mode:: Table of categories and item counts. | |
66 | * Searching for Items:: | |
67 | * Todo Filtered Items Mode:: Making virtual categories of items from | |
68 | different categories and files. | |
69 | * Todo Display Features:: | |
70 | * Printing Todo Buffers:: | |
71 | * Legacy Todo Mode Files:: Converting old-style todo files. | |
72 | ||
73 | * GNU Free Documentation License:: | |
74 | ||
75 | @detailmenu | |
76 | --- The Detailed Node Listing --- | |
77 | ||
78 | Overview | |
79 | ||
80 | * Levels of Organization:: | |
81 | * Todo Items as Diary Entries:: | |
82 | ||
83 | Editing | |
84 | ||
85 | * File Editing:: | |
86 | * Category Editing:: | |
87 | * Item Editing:: | |
88 | ||
89 | Item Editing | |
90 | ||
91 | * Inserting New Items:: | |
92 | * Editing Item Headers and Text:: | |
93 | * Relocating and Removing Items:: | |
94 | ||
95 | Relocating and Removing Items | |
96 | ||
97 | * Reprioritizing Items:: | |
98 | * Moving and Deleting Items:: | |
99 | * Done Items:: | |
100 | ||
101 | Todo Archives | |
102 | ||
103 | * Creating and Visiting Archives:: | |
104 | * Todo Archive Mode:: | |
105 | ||
106 | Todo Categories Mode | |
107 | ||
108 | * Table of Item Counts:: | |
109 | * Reordering Categories:: | |
110 | ||
111 | Todo Filtered Items Mode | |
112 | ||
113 | * Filtering Items:: | |
114 | * Todo Filtered Items Mode Commands:: | |
115 | * Files of Filtered Items:: | |
116 | ||
117 | Todo Display Features | |
118 | ||
119 | * Faces:: | |
120 | * Item Prefix:: | |
121 | * Other Display Commands and Options:: | |
122 | @end detailmenu | |
123 | @end menu | |
124 | ||
125 | @node Overview, Todo Mode Entry Points, Top, Top | |
126 | @chapter Overview | |
127 | ||
128 | The Todo mode package provides facilities for making and maintaining | |
129 | todo lists. A todo list is a list of todo items---things to do (in the | |
130 | widest sense)---arranged in order of priority, with the highest priority | |
131 | item at the top of the list and the lowest priority item at the bottom. | |
132 | ||
133 | This manual describes the Todo mode user interface. Todo mode comprises | |
134 | a large number of commands and user options for creating, displaying, | |
135 | navigating and editing todo lists, distributed across five major modes. | |
136 | The principle major mode is Todo mode; the other four (Todo Edit mode, | |
137 | Todo Archive mode, Todo Categories mode, and Todo Filtered Items mode) | |
138 | are subsidiary to and accessible from Todo mode. | |
139 | ||
140 | This version of Todo mode greatly expands on, and in significant ways | |
141 | differs from, the original version; for details and consequences of the | |
2a024334 | 142 | most important differences, @ref{Legacy Todo Mode Files}. |
016d3f7d SB |
143 | |
144 | @menu | |
145 | * Levels of Organization:: | |
146 | * Todo Items as Diary Entries:: | |
147 | @end menu | |
148 | ||
149 | @node Levels of Organization, Todo Items as Diary Entries, , Overview | |
150 | @section Levels of Organization | |
151 | ||
152 | In Todo mode each todo list is identified with a named category, so you | |
153 | can group together thematically related todo items. Each category is | |
154 | stored in a file, which thus provides a further level of organization. | |
155 | You can create as many todo files, and in each as many categories, as | |
156 | you want. | |
157 | ||
158 | All todo files reside in a single directory, whose location is specified | |
159 | by the user option @code{todo-directory}. This directory may also | |
160 | contain other types of Todo files, which are discussed later | |
161 | (@pxref{Todo Archive Mode} and @ref{Todo Filtered Items Mode}). Emacs | |
162 | recognizes Todo files by their extension, so when you visit the files | |
163 | the buffer is in the appropriate mode and the current category is | |
164 | correctly displayed. | |
165 | ||
166 | When you use a Todo mode command to create a todo file, the extension | |
167 | @samp{.todo} is automatically added to the base name you choose (as a | |
168 | rule, this name is also used for the other types of Todo files, which | |
169 | have their own extensions). As a user, you only have to deal with the | |
170 | base name of a Todo file. | |
171 | ||
172 | When you create a new todo file, you must also add at least one category | |
173 | to it, and each todo item belongs to a category. It is not possible to | |
174 | have an uncategorized todo list, but you can always make a catch-all | |
175 | category with a generic name like ``Todo'', which is in fact the default | |
176 | name assigned to the first category when you create a new todo file, if | |
177 | you don't provide a different name; you can change the default by | |
178 | customizing @code{todo-initial-category}. | |
179 | ||
180 | The most basic level of organization is the todo item itself, since it | |
181 | contains the information about what you want to do. As detailed in | |
182 | subsequent sections of this manual, most Todo mode commands and user | |
183 | options concern ways of classifying and deploying this information by | |
184 | associating various kinds of metadata with it, e.g., the category it | |
185 | belongs to, its priority, whether it is to be included in the Emacs | |
186 | diary, date and time stamps, whether it is done or still to do. | |
187 | ||
188 | @node Todo Items as Diary Entries, , Levels of Organization, Overview | |
189 | @section Todo Items as Diary Entries | |
190 | ||
cb9af965 SB |
191 | You can have todo items show up in the Emacs Fancy Diary display by |
192 | including the todo file in your diary file (@pxref{Fancy Diary | |
193 | Display,,, emacs}). This effectively augments the Emacs diary with | |
194 | categorized diary entries. All items in an included todo file will | |
195 | appear in the Fancy Diary display except for those that are marked | |
196 | with @code{todo-nondiary-marker}. You can add or omit this marking | |
197 | upon creating a new todo item, or you can do so by editing an existing | |
198 | item, see @ref{Inserting New Items} and @ref{Editing Item Headers and | |
199 | Text} for details. | |
016d3f7d SB |
200 | |
201 | To ensure the proper display of todo items in the Fancy Diary display, | |
202 | they must have the format of diary entries, i.e., they have to begin | |
203 | with a date string recognized by the Emacs diary,@footnote{Two types of | |
204 | dates recognized by the Emacs diary are not supported in the current | |
205 | Todo mode implementation: sexp diary entries and date strings in which | |
206 | the year is omitted (however, the latter type is equivalent to using | |
207 | @samp{*} for an arbitrary year, which Todo mode does support).} and if | |
208 | they are longer than one line, all lines but the first must begin with | |
209 | white space. Todo mode ensures that these requirements are satisfied | |
210 | (@pxref{Other Display Commands and Options}). | |
211 | ||
212 | The Fancy Diary display is also Todo mode aware: if it contains an item | |
213 | from a Todo mode file, clicking or typing @key{RET} on this item will | |
214 | switch to the buffer visiting that file and properly display the item's | |
215 | category, with point on the item. | |
216 | ||
217 | @node Todo Mode Entry Points, Key Binding Conventions, Overview, Top | |
218 | @chapter Todo Mode Entry Points | |
219 | ||
220 | To initialize your first todo file, invoke the command @code{todo-show}. | |
221 | This prompts you for a file name (defaulting to the value of | |
222 | @code{todo-initial-file}), prompts you for the name of the first | |
223 | category (defaulting to the value of @code{todo-initial-category}), | |
224 | creates and visits the file and displays the category in Todo mode, and | |
225 | then prompts you to enter the first item. If you choose not to enter an | |
226 | item now, simply type @kbd{C-g}, which leaves the category empty but | |
227 | otherwise well-formed. If you prefer not to be prompted to enter an | |
228 | item on adding a new category, disable the option | |
229 | @code{todo-add-item-if-new-category}. | |
230 | ||
231 | Once at least one todo file exists, invoking @code{todo-show} enters | |
232 | Todo mode. Invoked with a prefix argument, the command prompts for | |
233 | which todo file to visit. Otherwise, the first invocation of this | |
234 | command after loading the Todo mode package visits the default todo file | |
235 | (option @code{todo-default-todo-file}) and shows its first category. | |
236 | (You can get a different display with the first invocation of | |
237 | @code{todo-show} by customizing the option @code{todo-show-first}; | |
238 | @pxref{Todo Categories Mode} and @ref{Files of Filtered Items}.) | |
239 | ||
240 | If you leave Todo mode and later invoke @code{todo-show} to re-enter it, | |
241 | by default this returns you to the current (i.e., last displayed) | |
242 | category of the current todo file, which is the one in the most recently | |
243 | selected and still live buffer visiting a todo file. If you disable the | |
244 | option @code{todo-show-current-file}, then non-initial invocations of | |
245 | @code{todo-show} always return to the first or current category of the | |
246 | default todo file. | |
247 | ||
248 | If you want to enter Todo mode and go directly to a specific category | |
249 | instead the first or current category in the current or default todo | |
cb9af965 SB |
250 | file, use the command @code{todo-jump-to-category}; @ref{Navigation}, |
251 | for details. You can also enter Todo mode by invoking the command | |
252 | @code{todo-insert-item}; @ref{Inserting New Items}, for details. | |
016d3f7d SB |
253 | |
254 | The most convenient way to use these commands to enter Todo mode is to | |
cb9af965 SB |
255 | define global key bindings for them in your init file. Good choices |
256 | are @kbd{C-c t} for @code{todo-show}, @kbd{C-c j} for | |
257 | @code{todo-jump-to-category} and @kbd{C-c i} for | |
258 | @code{todo-insert-item}, since these commands are bound to @kbd{t}, | |
259 | @kbd{j} and @kbd{i}, respectively, in Todo mode. | |
016d3f7d | 260 | |
903204bb SB |
261 | @c You can also visit a Todo file via @code{find-file} or Dired, like any |
262 | @c other file, and since Emacs recognizes it, the buffer will automatically | |
263 | @c be in the appropriate Todo mode. Moreover, as long as the command you | |
264 | @c use to visit the file is listed in the option | |
265 | @c @code{todo-visit-files-commands} (which by default contains | |
266 | @c @code{find-file} and @code{dired-find-file}), it will also correctly | |
267 | @c display the file's first category on first visiting the file (otherwise | |
268 | @c you have to use one of the commands for navigating between categories in | |
269 | @c order to get a proper display). | |
016d3f7d SB |
270 | |
271 | You can leave Todo mode by typing @kbd{q} (@code{todo-quit}), which | |
272 | buries the current todo file buffer. Doing this also saves any changes | |
273 | you have made to the file, and leaves both the file and the category | |
274 | that was displayed on quitting current for subsequent Todo mode commands | |
275 | (unless the buffer made current by quitting is visiting another file and | |
276 | category in Todo mode, in which case the latter become current for Todo | |
277 | mode commands). | |
278 | ||
279 | @node Key Binding Conventions, Navigation, Todo Mode Entry Points, Top | |
280 | @chapter Key Binding Conventions | |
281 | ||
282 | For Todo mode commands to function properly, it is essential to maintain | |
283 | the correct format at all three levels of organization---item, category, | |
284 | and file. Todo mode tries to minimize the risk of format corruption by | |
285 | hiding certain parts of the format from the user, making the buffer | |
286 | read-only and suppressing the self-insertion keys. Consequently, it is | |
287 | normally impossible to make changes to your todo files without | |
288 | explicitly invoking Todo mode commands. | |
289 | ||
290 | A beneficial side effect of this restrictiveness is that you can invoke | |
291 | almost all Todo commands by typing ordinary printing characters, either | |
292 | singly or in specified sequences, without using modifier keys, except | |
293 | for the shift key for capitalization and the raw prefix argument | |
294 | @kbd{C-u}; numeric prefix arguments can be entered just by typing a | |
295 | number key. | |
296 | ||
297 | The predefined key bindings in Todo are more or less mnemonic. As a | |
903204bb | 298 | rule, key sequences beginning with @kbd{C} (capital @samp{C}, not the |
cb9af965 SB |
299 | control key) are bound to commands applying to categories, sequences |
300 | beginning with @kbd{F} apply to (non-archive) file-level commands, and | |
301 | those beginning with @kbd{A} apply to archives (a special type of Todo | |
302 | file; @ref{Todo Archive Mode}). Todo commands applying to items, | |
303 | which constitute the majority, are bound to lower case key sequences. | |
016d3f7d SB |
304 | |
305 | @node Navigation, Editing, Key Binding Conventions, Top | |
306 | @chapter Navigation | |
307 | ||
308 | The navigation commands are for making another todo file, category, or | |
309 | item the current one by moving point to it.@footnote{Many editing | |
310 | commands can also do this by side effect, but since that is not their | |
311 | main function, they are not included in this section.} Since these | |
312 | commands are likely to be used frequently and repetitively, it is | |
313 | convenient for their key bindings to be single lower case keys, even for | |
314 | navigation commands applying to categories and files. | |
315 | ||
cb9af965 SB |
316 | Two of the navigation commands were already mentioned in @ref{Todo |
317 | Mode Entry Points}: | |
016d3f7d SB |
318 | |
319 | @table @kbd | |
320 | ||
321 | @item t | |
322 | Display another todo file in the selected window (@code{todo-show}). | |
323 | When you invoke this command in Todo mode, it prompts for a file name, | |
324 | which you can choose via minibuffer completion (like invoking | |
325 | @code{todo-show} with a prefix argument outside of Todo mode). If a | |
326 | buffer is already visiting that file, it displays its current category; | |
327 | if invoking @kbd{t} opens the file, it display its first category (by | |
328 | default; see the option @code{todo-show-first} for other possibilities). | |
329 | ||
330 | @item j | |
331 | Display another todo category in the selected window | |
332 | (@code{todo-jump-to-category}). When you invoke this command, it | |
333 | prompts for a category name, which you can choose via minibuffer | |
334 | completion. The candidates for completion include the categories in the | |
335 | current todo file as well as those in the files listed in the option | |
336 | @code{todo-category-completions-files}. If you type @key{RET} without | |
337 | choosing a category, the current category of the current todo file is | |
338 | automatically selected (this can be a useful shortcut when you invoke | |
339 | @code{todo-jump-to-category} outside of Todo mode). If you type the | |
340 | name of a non-existing category, you can add this to the file as a new | |
341 | category and jump to it. If you invoke this command with a prefix | |
342 | argument, it first you prompts for which todo file to jump to (which you | |
343 | can also choose with minibuffer completion) and then for which category | |
344 | from that file; in this case, completion is only against the categories | |
345 | in the selected file. | |
346 | @end table | |
347 | ||
348 | It is also convenient to navigate back and forth sequentially between | |
349 | the categories of a single todo file. The categories of a todo file are | |
350 | numbered consecutively starting with @samp{1}.@footnote{A category's | |
351 | number is automatically assigned when the category is created: the | |
352 | category is appended to the end of the file, so its number is simply the | |
353 | highest until another category is added. There is no command in Todo | |
354 | mode to reorder the numbering of the categories in a todo file, but this | |
355 | is possible from the file's table of categories; @ref{Todo Categories | |
356 | Mode}.} The current category's number and name appear in the mode line. | |
357 | ||
358 | @table @kbd | |
359 | ||
360 | @item f | |
361 | Move point to the first item of the category numerically directly | |
362 | following the current category (@code{todo-forward-category}). | |
363 | ||
364 | @item b | |
365 | Move point to the first item of the category numerically directly | |
366 | preceding the current category (@code{todo-backward-category}). | |
367 | @end table | |
368 | ||
369 | With @kbd{f} and @kbd{b} you can cycle through the categories, so for example, | |
370 | if the last category is current and you type @kbd{f}, then the first | |
371 | category becomes current. | |
372 | ||
373 | You can also navigate between the items in the current category: | |
374 | ||
375 | @table @kbd | |
376 | ||
377 | @item n | |
378 | Move point down to the next item below the current one (i.e., to the | |
379 | item with the next lower priority) (@code{todo-next-item}). | |
380 | ||
381 | @item p | |
382 | Move point up to the item directly above the current one (i.e., to the | |
383 | item with the next higher priority) (@code{todo-previous-item}). | |
384 | @end table | |
385 | ||
386 | These commands also accept a positive numeric prefix argument; e.g., | |
387 | typing @kbd{5 n} or @kbd{5 p} navigates in one step to the item five items lower | |
388 | or higher than the current one. | |
389 | ||
390 | Navigation to other types of Todo files is discussed in the relevant | |
391 | sections below. | |
392 | ||
393 | @node Editing, Todo Archives, Navigation, Top | |
394 | @chapter Editing | |
395 | ||
396 | Editing in Todo mode means making structural or textual changes at one | |
397 | of the levels of organization (file, category, or item). Structural | |
cb9af965 SB |
398 | editing includes adding, relocating and removing units of information |
399 | at a level; textual editing includes renaming files or categories and | |
400 | changing an item's content or date/time stamp, or adding certain kinds | |
401 | of marks or tags to items. Todo mode provides commands, detailed in | |
402 | the following sections, which enable you to quickly and safely make | |
403 | changes to your todo lists, without having to worry about preserving | |
404 | the file format. | |
405 | ||
406 | To save changes you make to the current todo file, | |
407 | type @kbd{s} (@code{todo-save}). Changes are also saved on quitting | |
408 | Todo mode with @kbd{q}. | |
016d3f7d SB |
409 | |
410 | @menu | |
411 | * File Editing:: | |
412 | * Category Editing:: | |
413 | * Item Editing:: | |
414 | @end menu | |
415 | ||
416 | @node File Editing, Category Editing, , Editing | |
417 | @section File Editing and Todo Edit Mode | |
418 | ||
419 | There are four file-level editing commands: | |
420 | ||
421 | @table @kbd | |
422 | ||
423 | @item F a | |
cb9af965 SB |
424 | Add a new todo file (@code{todo-add-file}). This command prompts for |
425 | a name and creates the file in @code{todo-directory}, adding the | |
016d3f7d | 426 | @samp{.todo} extension (so you should not include the extension in the |
cb9af965 SB |
427 | name you enter). The command also prompts for the file's first |
428 | category and, if option @code{todo-add-item-if-new-category} is | |
429 | enabled (the default), for that category's first item. | |
016d3f7d SB |
430 | |
431 | @item F r | |
432 | Rename the current todo file (@code{todo-rename-file}). If called with | |
433 | a prefix argument, prompt for a todo file and rename it. If the todo | |
434 | file has an archive (@pxref{Todo Archive Mode}) or there are | |
435 | corresponding filtered items files (@pxref{Todo Filtered Items Mode}), | |
436 | this command renames these accordingly. If there are live buffers | |
cb9af965 | 437 | visiting any of these files, the command also renames them accordingly. |
016d3f7d SB |
438 | |
439 | @item F k | |
440 | Delete the current todo file (@code{todo-delete-file}).@footnote{The key | |
526e5233 | 441 | binding of this command is mnemonic for ``kill'' to parallel the binding |
016d3f7d SB |
442 | @kbd{k} for item deletion, since @kbd{d} is bound to another item |
443 | editing command (@pxref{Done Items}).} If the todo file has an archive | |
cb9af965 SB |
444 | (@pxref{Todo Archive Mode}), prompt for whether to delete that as well. |
445 | This command also kills the buffers visiting the deleted files. | |
016d3f7d SB |
446 | |
447 | @item F e | |
448 | This command (@code{todo-edit-file}) changes the buffer's major mode to | |
449 | Todo Edit mode. In this mode the entire file is visible, the buffer is | |
ae93878a | 450 | writable and you can use the self-insertion keys and standard Emacs |
016d3f7d SB |
451 | editing commands to make changes. To return to Todo mode, type @kbd{C-x |
452 | C-q} (@code{todo-edit-quit}). | |
453 | ||
454 | The command @kbd{F e} is not intended for normal editing of items and | |
455 | categories, as it circumvents the restrictions that Todo imposes to | |
456 | protect against file format corruption (i.e., all categories, not just | |
457 | the current one, and all internal formatting are exposed and editable). | |
458 | It is provided primarily as a convenience for two types of use cases | |
459 | that are likely to arise infrequently. One is to be able to use | |
460 | standard Emacs commands like @code{query-replace} to replace a piece of | |
461 | text that occurs in different categories throughout the file. The other | |
462 | use case is to recover from a mistake, such as accidentally deleting an | |
463 | item, since this cannot be undone in Todo mode. | |
464 | ||
cb9af965 SB |
465 | Using @kbd{C-x C-q} to quit Todo Edit mode provides a measure of |
466 | safety, since it runs a file format check, signaling an error if the | |
467 | format has become invalid. However, this check cannot tell if the | |
468 | number of items or categories changed, which could result in the file | |
469 | containing inconsistent information (see the cautionary note in | |
470 | @ref{Reordering Categories}, for more details). Invoking @kbd{F e} | |
471 | displays a warning to this effect. | |
016d3f7d SB |
472 | @end table |
473 | ||
474 | @node Category Editing, Item Editing, File Editing, Editing | |
475 | @section Category Editing | |
476 | ||
cb9af965 SB |
477 | The following commands are available for editing specifically at the |
478 | category level (for two other category-editing commands, which are | |
479 | extensions of item commands, @pxref{Editing Item Headers and Text}): | |
016d3f7d SB |
480 | |
481 | @table @kbd | |
482 | ||
483 | @item C a | |
484 | Add a new category to the current todo file and make that category | |
485 | current (@code{todo-add-category}). If called with a prefix argument, | |
486 | prompt for a file name and add the new category to that file. This | |
487 | command is similar to using @kbd{j}, but it only accepts category names | |
488 | that are not the name of an existing category in the file. | |
489 | ||
490 | @item C r | |
491 | Rename the current category (@code{todo-rename-category}). If this | |
492 | category's file has an archive (@pxref{Todo Archive Mode}) with a | |
493 | corresponding category, rename the category there as well. | |
494 | ||
495 | @item C m | |
496 | Move the current category (with all its items) to another todo file | |
497 | (@code{todo-move-category}). If this category's file has an archive | |
498 | (@pxref{Todo Archive Mode}) with a corresponding category, this command | |
499 | also moves that category to the archive file corresponding to the moved | |
500 | to todo file; if there is no such archive file, the command creates it | |
501 | and adds the category. | |
502 | ||
503 | @item C k | |
504 | Delete the current category (@code{todo-delete-category}).@footnote{This | |
526e5233 | 505 | binding is mnemonic for ``kill'' to parallel the binding @kbd{k} for |
016d3f7d SB |
506 | item deletion, since @kbd{d} is bound to another item editing command |
507 | (@pxref{Done Items}).} To delete a category that contains items, you | |
508 | have to confirm your intent; if the category is empty, deletion is | |
509 | immediate. | |
510 | ||
511 | @item C g | |
512 | Merge the items of one category into another category, delete the first | |
513 | category and make the second category current | |
514 | (@code{todo-merge-category}). If both the first and second categories | |
515 | also have archived items (@pxref{Todo Archive Mode}), merge the former | |
516 | to the latter. If only the first category has archived items, rename | |
517 | the archive category to the merged to category. Minibuffer completion | |
518 | of the name of the category merged to works as with the navigation | |
519 | command @kbd{j}, and as with that command, passing a prefix argument, | |
520 | i.e., typing @kbd{C-u C g}, prompts for a file and confines merging to a | |
521 | category in that file. | |
522 | @end table | |
523 | ||
524 | @node Item Editing, , Category Editing, Editing | |
525 | @section Item Editing | |
526 | ||
cb9af965 SB |
527 | Todo mode provides commands for adding new items as well as textually |
528 | changing, deleting and relocating existing items. The commands and | |
529 | associated options for adding and editing items, in particular, offer | |
530 | you a lot of flexibility to fine-tune these operations to your needs. | |
016d3f7d SB |
531 | |
532 | @menu | |
533 | * Inserting New Items:: | |
534 | * Editing Item Headers and Text:: | |
535 | * Relocating and Removing Items:: | |
536 | @end menu | |
537 | ||
538 | @node Inserting New Items, Editing Item Headers and Text, , Item Editing | |
539 | @subsection Inserting New Items | |
540 | ||
cb9af965 SB |
541 | To add a new todo item to a category, type @kbd{i}, which is bound to |
542 | the command @code{todo-insert-item}. | |
016d3f7d SB |
543 | |
544 | @table @kbd | |
545 | ||
cb9af965 SB |
546 | @item i |
547 | This command is the entry point for inserting new items into a | |
548 | category (@code{todo-insert-item}). It prompts for additional keys | |
549 | until reaching a complete key sequence, which specifies the insertion | |
550 | parameters you wish to apply (see below). It then prompts for the | |
551 | text of the item, which you enter in the minibuffer.@footnote{There | |
552 | are two insertion parameters that override prompting for and manually | |
553 | entering the new item's text, see below.} Called with one prefix | |
016d3f7d | 554 | argument, it also prompts for a category, and called with two prefix |
cb9af965 SB |
555 | arguments, it prompts for both a file and a category from that file, |
556 | and inserts the item accordingly; category name completion works as | |
557 | with the navigation command @kbd{j}. Finally, it inserts the item | |
558 | into the current or selected category of the current or selected todo | |
559 | file at the position in the list corresponding to the priority you | |
560 | choose, which also depends on the insertion parameters. | |
016d3f7d SB |
561 | @end table |
562 | ||
cb9af965 SB |
563 | @noindent |
564 | The name of this command reflects the fact that you can insert a new | |
565 | item into the category at any position, giving each new item any | |
566 | priority in the list, whereas speaking of adding an item to a category | |
567 | suggests appending it to the top or bottom. | |
568 | ||
569 | In addition to its file and category, each newly inserted todo item | |
570 | has a priority in the category and begins with a header string, which | |
016d3f7d SB |
571 | includes at least the current date in the same format used by |
572 | @code{diary-insert-entry} (@pxref{Date Formats,,, emacs}). You can | |
cb9af965 SB |
573 | specify the priority and the content of the header string in two ways. |
574 | First, you can set the following item insertion options, which apply | |
575 | on every invocation of @code{todo-insert-item}. | |
016d3f7d SB |
576 | |
577 | @itemize @bullet | |
578 | ||
cb9af965 SB |
579 | @item |
580 | @code{todo-default-priority} is for automatically assigning a new item | |
581 | the highest or lowest priority in the category, if you do not | |
582 | explicitly assign it a priority on invoking @code{todo-insert-item}. | |
583 | By default, such new items are given highest priority, i.e., inserted | |
584 | at the top of the list. | |
585 | ||
016d3f7d SB |
586 | @item |
587 | @code{todo-always-add-time-string} is for including or omitting the | |
cb9af965 SB |
588 | current time in the new item's header. By default, this time string |
589 | is omitted. | |
016d3f7d SB |
590 | |
591 | @item | |
cb9af965 SB |
592 | @code{todo-include-in-diary} is for specifying whether the item |
593 | appears in the Fancy Diary display (when the todo file is included in | |
594 | the Emacs diary file) by adding or omitting | |
595 | @code{todo-nondiary-marker}. By default, new todo items are so | |
596 | marked, thus excluded from the diary. | |
016d3f7d SB |
597 | |
598 | @item | |
599 | @code{todo-diary-nonmarking} is for adding or omitting | |
600 | @code{diary-nonmarking-symbol} to items displayed in the diary, to | |
cb9af965 SB |
601 | control whether they are marked in the calendar (@pxref{Format of |
602 | Diary File,,, emacs}). By default, todo items that are diary entries | |
603 | lack this symbol, thus are marked in the calendar. | |
016d3f7d SB |
604 | @end itemize |
605 | ||
cb9af965 SB |
606 | Beside setting these options, for more flexibility you can also pass |
607 | certain parameters on each invocation of @code{todo-insert-item}. | |
608 | These parameters concern not only the new item's priority and header, | |
609 | but also its textual content. You pass these parameters by typing a | |
610 | sequence of one or more keys after the initial @kbd{i}. | |
611 | ||
612 | Here is a list of the item insertion parameters together with their | |
613 | mnemonically associated keys@footnote{The non-mnemonic choice of | |
614 | @kbd{i} for the parameter @samp{default} is motivated by the | |
615 | convenience of repeating the @kbd{i} used to invoke | |
616 | @code{todo-insert-item}.} and descriptions of their effect in | |
617 | @code{todo-insert-item}: | |
016d3f7d SB |
618 | |
619 | @enumerate | |
620 | ||
621 | @item | |
cb9af965 SB |
622 | @samp{default} (@kbd{i}): Prompt for the new item's priority |
623 | (a number between 1 and one more than the number of items already in | |
624 | the category) and add a header string conforming to the values of the | |
625 | above options. | |
626 | ||
627 | @samp{copy} (@kbd{p}): Make an exact copy of the item at point, | |
628 | including its header string, and prompt for its priority. (This is | |
629 | useful for quickly making a new todo item whose text or header you | |
630 | want to differ only partly from that of an existing item: after | |
631 | inserting the copy, you can quickly edit it as needed by using | |
632 | operations described in the next section.) | |
633 | ||
016d3f7d | 634 | @item |
cb9af965 SB |
635 | @samp{diary} (@kbd{y}): Override the option |
636 | @code{todo-include-in-diary}; that is, add @code{todo-nondiary-marker} | |
4181427f | 637 | if the option is non-@code{nil}, omit this marker if the option is @code{nil}. |
cb9af965 SB |
638 | |
639 | @samp{nonmarking} (@kbd{k}): Override the option | |
640 | @code{todo-diary-nonmarking}; that is, add | |
4181427f GM |
641 | @code{diary-nonmarking-symbol} if the option is non-@code{nil}, omit this |
642 | symbol if the option is @code{nil}. Since this symbol only applies to diary | |
cb9af965 SB |
643 | items, the new item is automatically marked as such, i.e., lacks |
644 | @code{todo-nondiary-marker}. | |
645 | ||
016d3f7d | 646 | @item |
cb9af965 SB |
647 | @samp{calendar} (@kbd{c}): Pop up the Emacs calendar and click a date |
648 | in it to use that date in the new todo item's header. | |
649 | ||
650 | @samp{date} (@kbd{d}): Prompt for entering in the minibuffer | |
651 | the year, month (with completion) and day number components of the | |
652 | header. | |
653 | ||
654 | @samp{dayname} (@kbd{n}): Prompt for entering in the minibuffer | |
655 | a weekday name as the date header instead of a year-month-day string. | |
656 | ||
016d3f7d | 657 | @item |
cb9af965 SB |
658 | @samp{time} (@kbd{t}): Prompt for entering a time string in |
659 | the minibuffer instead of automatically inserting the current time; | |
660 | however, typing @key{RET} at the prompt enters the current time if | |
4181427f | 661 | @code{todo-always-add-time-string} is non-@code{nil}, otherwise it enters the |
cb9af965 SB |
662 | empty string (i.e., no time string). |
663 | ||
016d3f7d | 664 | @item |
cb9af965 SB |
665 | @samp{here} (@kbd{h}): Insert the new item in the position of |
666 | the item at point, pushing that and all lower items in the category | |
667 | down, i.e., lowering their priority, by one. | |
668 | ||
669 | @samp{region} (@kbd{r}): Use the text of the selected region as the | |
670 | text of the new item, and insert this in accordance with the item | |
671 | insertion options and other parameters passed. If the option | |
4181427f | 672 | @code{todo-use-only-highlighted-region} is non-@code{nil}, then use the |
903204bb SB |
673 | region only when it is highlighted; otherwise, use the region |
674 | regardless of highlighting. | |
016d3f7d SB |
675 | @end enumerate |
676 | ||
cb9af965 SB |
677 | Note that the parameters are divided into five numbered groups; within |
678 | a group, the parameters are mutually exclusive. Hence, to build a | |
679 | complete insertion operation, you select at most one parameter from at | |
680 | least one of these groups, by typing the corresponding key. If you | |
681 | want to apply more than one parameter, you must type the corresponding | |
682 | keys in the order of the numbered groups, subject to the following | |
683 | constraints. | |
684 | ||
685 | The keys of groups 2-4 are continuation keys, that is, each can be | |
686 | followed by a key from a following group. If you want to finish the | |
687 | sequence with a continuation key, you must double the final key. For | |
688 | example, @kbd{i y} is not a complete key sequence; rather, you must | |
689 | type @kbd{i y y}. | |
690 | ||
691 | By contrast, the keys of groups 1 and 5 are final keys; for example, | |
692 | @kbd{i i} and @kbd{i h} are complete sequences. The reason for making | |
693 | two separate groups of the final keys is that the parameters | |
694 | @samp{default} and @samp{copy} cannot be combined with any other | |
695 | parameters, while @samp{here} and @samp{region} can be combined with | |
696 | any of the parameters from groups 2-4. | |
697 | ||
698 | To aid you in building item insertion key sequences, when you type an | |
699 | insertion key, this displays a prompt in the echo area showing pairs | |
700 | of the remaining possible keys and their associated parameters, | |
701 | grouped and ordered in accordance with the above list. The initial | |
702 | prompt, after typing @kbd{i} to invoke @code{todo-insert-item}, looks | |
703 | like this: | |
704 | ||
705 | @example | |
706 | 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 @} | |
707 | @end example | |
708 | ||
709 | @noindent If you now type @kbd{y}, the prompt changes to this: | |
710 | ||
711 | @example | |
712 | Press a key (so far `i y'): y=>diary:GO! @{ c=>calendar d=>date n=>dayname @} t=>time @{ h=>here r=>region @} | |
713 | @end example | |
714 | ||
715 | @noindent Notice that the pair @samp{k=>nonmarking} is now absent, since it | |
716 | belongs to the same group as the selected pair @samp{y=>diary}, hence | |
717 | is no longer available for this sequence. Since @kbd{y} is a | |
903204bb SB |
718 | continuation key, it is still available, but now the string |
719 | @samp{:GO!} is appended to the pair to remind you that pressing this | |
720 | key again will complete the sequence. | |
cb9af965 SB |
721 | |
722 | ||
723 | ||
724 | @c Here are some examples of item insertion command key sequences: | |
725 | ||
726 | @c @itemize @bullet | |
727 | ||
728 | @c @item | |
729 | @c @kbd{i h} inserts a new item at the position of the item at point (pushing | |
730 | @c the latter down) with a header containing the current date and, | |
731 | @c depending on the values of the mentioned options, possibly the current | |
732 | @c time and diary-related markings. | |
733 | @c @item | |
734 | @c @kbd{i y h} does the same as the preceding command, except that | |
735 | @c @code{todo-nondiary-marker} is added if @code{todo-include-in-diary} is | |
4181427f GM |
736 | @c non-@code{nil} and omitted if that option is @code{nil}; that is, |
737 | @c the diary key @kbd{y} @c overrides the setting of this option. | |
cb9af965 SB |
738 | @c @item |
739 | @c @kbd{i y t h} does the same as the preceding command, except that it | |
740 | @c prompts for a time string instead of automatically inserting the | |
741 | @c current time; however, typing @key{RET} at the prompt returns the | |
4181427f GM |
742 | @c current time if @code{todo-always-add-time-string} is non-@code{nil}, |
743 | @c otherwise the empty string (i.e., no time string). | |
cb9af965 SB |
744 | @c @item |
745 | @c @kbd{i y t t} does the same as the preceding command, except that it | |
746 | @c prompts for the item's priority and inserts it accordingly. | |
747 | @c @end itemize | |
748 | ||
749 | ||
750 | An alternative to the key sequence @kbd{i c c} for choosing the item's | |
751 | date from the calendar is also available: when point is already on a | |
752 | date in the calendar, typing @kbd{i t} | |
753 | (@code{todo-insert-item-from-calendar}) prompts for a new item and its | |
754 | priority and inserts it in the current category. This command, like | |
755 | @code{todo-insert-item}, also accepts one or two prefix arguments for | |
756 | choosing the category via minibuffer completion. Note, however, that | |
757 | the key sequence @kbd{i t} is not defined in Todo mode but in the | |
758 | Calendar mode keymap. It is a convenient shortcut if you happen to be | |
759 | using the calendar when you decide to make a new todo item. (Contrast | |
760 | this with passing the @samp{calendar} parameter, which pops open the | |
761 | calendar after you have entered the item's text, and then you can | |
762 | choose a date from the calendar.) | |
016d3f7d | 763 | |
016d3f7d | 764 | |
cb9af965 SB |
765 | @node Editing Item Headers and Text, Relocating and Removing Items, Inserting New Items, Item Editing |
766 | @subsection Editing Item Headers and Text | |
016d3f7d | 767 | |
cb9af965 SB |
768 | To make changes to an existing item's content or header, type @kbd{e}, |
769 | which is bound to the command @code{todo-edit-item}. | |
016d3f7d SB |
770 | |
771 | @table @kbd | |
772 | ||
cb9af965 SB |
773 | @item e |
774 | This command is the entry point for textually editing existing items | |
775 | in a category (@code{todo-edit-item}). It prompts for additional keys | |
776 | until reaching a complete key sequence, which specifies the editing | |
777 | parameters you wish to apply (see below), and then executes the | |
778 | editing operation accordingly. | |
016d3f7d SB |
779 | @end table |
780 | ||
cb9af965 SB |
781 | Here is a list of the item editing parameters together with their |
782 | mnemonically associated keys and descriptions of their effect in | |
783 | @code{todo-edit-item}. The list is divided into three groups, for | |
784 | reasons explained below. | |
016d3f7d | 785 | |
cb9af965 | 786 | @enumerate 1 |
016d3f7d | 787 | |
cb9af965 SB |
788 | @item |
789 | @samp{edit} (@kbd{e}): Edit the text of the current item in the | |
790 | minibuffer; the item's header is omitted. | |
016d3f7d | 791 | |
cb9af965 SB |
792 | @samp{header} (@kbd{h}): Edit the text and header of the current item |
793 | in the minibuffer. | |
016d3f7d | 794 | |
cb9af965 SB |
795 | @samp{multiline} (@kbd{m}): Edit the text of the current item in a |
796 | special buffer in Todo Edit mode. After editing, type @kbd{C-x C-q} | |
797 | to return to Todo mode.@footnote{This runs a format check to ensure | |
798 | the item is well-formed. However, unlike the command @kbd{F e} | |
016d3f7d SB |
799 | (@pxref{File Editing}), @kbd{e m} does not expose you to the risk of |
800 | putting the file in an inconsistent state, since it puts only the | |
801 | current item in Todo Edit mode.} | |
016d3f7d | 802 | |
cb9af965 SB |
803 | @samp{diary} (@kbd{y}): Change the current item's diary inclusion |
804 | status by adding @code{todo-nondiary-marker} if the item lacks this, | |
805 | or by removing it if present. | |
016d3f7d | 806 | |
cb9af965 SB |
807 | @samp{nonmarking} (@kbd{k}): Change the current item's calendar |
808 | marking status by adding @code{diary-nonmarking-symbol} if the item | |
809 | lacks this, or by removing it if present. Since this symbol only | |
810 | applies to diary items, the item is automatically marked as such, | |
811 | i.e., if @code{todo-nondiary-marker} is present, it is removed. | |
016d3f7d | 812 | |
cb9af965 SB |
813 | @samp{date} (@kbd{d}): Prompt for a final key from the second group |
814 | of item editing parameters to edit the current item's date string. | |
815 | ||
816 | @samp{time} (@kbd{t}): Edit the current item's time string, if | |
817 | present; otherwise, add one. Typing @key{RET} at the prompt enters | |
4181427f | 818 | the current time if @code{todo-always-add-time-string} is non-@code{nil}, |
cb9af965 SB |
819 | otherwise it enters the empty string (i.e., no time string). |
820 | @end enumerate | |
016d3f7d | 821 | |
cb9af965 SB |
822 | @noindent |
823 | Editing the text of a lengthy item in the minibuffer can be | |
903204bb SB |
824 | inconvenient; therefore, if you type @kbd{e e} or @kbd{e h} on an item |
825 | whose text contains more than one logical line, the effect is the same | |
826 | as if you had typed @kbd{e m}, that is, you switch a special buffer in | |
827 | Todo Edit mode. | |
016d3f7d | 828 | |
cb9af965 SB |
829 | When you pass any of the parameters of the preceding group, except for |
830 | the @samp{date} parameter, this completes the item editing invocation | |
831 | begun by typing @kbd{e}. Pressing @kbd{d} to pass the @samp{date} | |
832 | parameter, however, prompts you with the following parameters and | |
833 | their associated keys, and pressing any of these completes the | |
834 | invocation. | |
016d3f7d | 835 | |
cb9af965 SB |
836 | @enumerate 2 |
837 | ||
838 | @item | |
839 | @samp{full} (@kbd{f}): Successively prompt for editing the year, month | |
840 | (with completion) and day number parts of the current item's date | |
841 | string, and, if the option @code{todo-always-add-time-string} is | |
4181427f | 842 | non-@code{nil}, also for editing its time string. |
cb9af965 SB |
843 | |
844 | @samp{calendar} (@kbd{c}): This pops up the Emacs calendar, and after | |
845 | you type @key{RET} on a date in the calendar makes that date the | |
846 | item's date. | |
847 | ||
848 | @samp{today} (@kbd{a}): Make the item's date today's date. | |
849 | ||
850 | @samp{dayname} (@kbd{n}): Prompt for a weekday name (with completion) | |
851 | and make it the item's date header. Note that this replaces an | |
852 | existing date string, it does not add the day name to the date string. | |
853 | ||
854 | @samp{year} (@kbd{y}): Edit just the year component of the current | |
855 | item's date string. | |
856 | ||
857 | @samp{month} (@kbd{m}): Edit just the month component of the current | |
858 | item's date string (with completion). | |
859 | ||
860 | @samp{daynum} (@kbd{d}): Edit just the day number component of the | |
861 | current item's date string. | |
862 | @end enumerate | |
016d3f7d SB |
863 | |
864 | @noindent | |
cb9af965 SB |
865 | With the latter three parameters you can add a positive or negative |
866 | numeric prefix argument to the invocation: this increments or | |
867 | decrements the selected date component by the given number and | |
868 | automatically adjusts the other date components if necessary. For | |
869 | example, if the item's date string is ``January 1, 2013'', then typing | |
870 | @kbd{- 3 e d d} results in ``December 29, 2012''. | |
871 | ||
872 | The first two groups of parameters apply only to todo items that are | |
873 | not marked as done (@pxref{Done Items}); the two parameters of the | |
874 | third group, in contrast, apply only to done todo items. You cannot | |
875 | edit the text of such items, but you can edit or delete the comment | |
876 | you may have added on marking the item as done (@pxref{Done Items, | |
877 | @code{todo-item-done}},), or retroactively add a comment, by passing | |
878 | either of these parameters. | |
879 | ||
880 | @enumerate 3 | |
016d3f7d | 881 | |
cb9af965 SB |
882 | @item |
883 | @samp{add/edit comment} (@kbd{c}): Edit the current done item's | |
884 | comment, if it has one; otherwise, prompt for and add a comment. | |
016d3f7d | 885 | |
cb9af965 SB |
886 | @samp{delete comment} (@kbd{d}): Delete the current done item's |
887 | comment, if it has one. | |
888 | @end enumerate | |
016d3f7d | 889 | |
cb9af965 SB |
890 | The command @code{todo-edit-item} is sensitive to the distinction |
891 | between not done and done todo items. If you type @kbd{e} when point | |
892 | is on a done item, this displays the following prompt in the echo | |
893 | area: | |
016d3f7d | 894 | |
cb9af965 SB |
895 | @example |
896 | Press a key (so far `e'): c=>add/edit comment d=>delete comment | |
897 | @end example | |
016d3f7d SB |
898 | |
899 | @noindent | |
cb9af965 SB |
900 | Only by typing @kbd{c} or @kbd{d} in response to this prompt can you |
901 | complete the invocation. In contrast, if you type @kbd{e} when point | |
902 | is on a non-done todo item, this displays the following prompt in the | |
903 | echo area, and you can continue or complete the invocation only by | |
904 | typing one of the listed keys: | |
905 | ||
906 | @example | |
907 | Press a key (so far `e'): e=>edit h=>header m=>multiline y=>diary k=>nonmarking d=>date t=>time | |
908 | @end example | |
909 | ||
910 | As noted above, passing the @samp{date} parameter does not complete | |
911 | the invocation of @code{todo-edit-item}; rather, it displays the | |
912 | following prompt, and typing any of these keys does complete the | |
913 | invocation: | |
914 | ||
915 | @example | |
916 | Press a key (so far `e d'): f=>full c=>calendar a=>today n=>dayname y=>year m=>month d=>daynum | |
917 | @end example | |
918 | ||
903204bb SB |
919 | In addition to the item-level invocations @kbd{e y}, to change the |
920 | current item's diary inclusion status, and @kbd{e k}, to change the | |
921 | current item's calendar marking status, Todo mode also has two related | |
922 | category-level commands: | |
016d3f7d SB |
923 | |
924 | @table @kbd | |
925 | ||
926 | @item C e y | |
927 | @itemx C e k | |
928 | Add @code{todo-nondiary-marker} and @code{diary-nonmarking-symbol}, | |
929 | respectively, to all todo items in the current category; if invoked with | |
930 | a prefix argument, these markings are removed from all items in the | |
931 | category. | |
932 | @end table | |
933 | ||
cb9af965 | 934 | @noindent |
903204bb | 935 | Like @kbd{e k}, @kbd{C e k} automatically removes @code{todo-nondiary-marker} |
cb9af965 SB |
936 | from all items it is present on, since only diary items can bear |
937 | @code{diary-nonmarking-symbol}. | |
938 | ||
939 | Since categories often contain a mix of items marked for diary | |
940 | inclusion and exclusion, and of the former, a mix of those to be | |
941 | marked and those not to be marked in the calendar, it is more useful | |
942 | for these category-level commands, unlike the item-level commands, not | |
943 | to be toggles, but to have the same effect on all items in the | |
944 | category, and take a prefix argument to reverse the effect. (If you | |
945 | really want to toggle the diary-inclusion and calendar-marking status | |
946 | of all items in the category, you can do this by marking all the items | |
903204bb | 947 | and then invoking @kbd{e y} or @kbd{e k}, @pxref{Marked Items}). |
cb9af965 | 948 | |
016d3f7d SB |
949 | @node Relocating and Removing Items, , Editing Item Headers and Text, Item Editing |
950 | @subsection Relocating and Removing Items | |
951 | ||
952 | In addition to inserting a new todo item and changing the text or header | |
953 | of an existing item, you can also move an item to another category | |
954 | (i.e., recategorize it), change its priority within its category, delete | |
955 | it from the category and file, or mark it as a ``done'' item, which | |
956 | removes it from the todo list but does not delete it. | |
957 | ||
958 | @menu | |
959 | * Reprioritizing Items:: | |
960 | * Moving and Deleting Items:: | |
961 | * Done Items:: | |
962 | @end menu | |
963 | ||
964 | @node Reprioritizing Items, Moving and Deleting Items, , Relocating and Removing Items | |
965 | @subsubsection Reprioritizing Items | |
966 | ||
967 | There are three ways to change a todo item's priority: | |
968 | ||
969 | @table @kbd | |
970 | ||
971 | @item r | |
972 | Raise the current item's priority by one, exchanging its position in the list | |
973 | with that of the item directly above it (@code{todo-raise-item-priority}). | |
974 | ||
975 | @item l | |
976 | Lower the current item's priority by one, exchanging its position in the list | |
977 | with that of the item directly below it (@code{todo-lower-item-priority}). | |
978 | ||
979 | @item # | |
cb9af965 SB |
980 | Prompt for a number and relocate the item to the corresponding |
981 | position in the list (@code{todo-set-item-priority}). For example, | |
982 | entering @kbd{3} at the prompt makes the item the third in the | |
983 | category, i.e., gives it third highest priority; all lower priority | |
984 | items are pushed down by one. You can also pass the desired priority | |
016d3f7d SB |
985 | as a numeric prefix argument, e.g., @kbd{3 #} gives the item third |
986 | highest priority without prompting. (Prefix arguments have no effect | |
987 | with @kbd{r} or @kbd{l}.) | |
988 | @end table | |
989 | ||
990 | @node Moving and Deleting Items, Done Items, Reprioritizing Items, Relocating and Removing Items | |
991 | @subsubsection Moving and Deleting Items | |
992 | ||
993 | You can move an item to another category, thereby recategorizing it: | |
994 | ||
995 | @table @kbd | |
996 | ||
997 | @item m | |
998 | Move the item at point to another category (@code{todo-move-item}). | |
999 | This prompts for a category to move the item to, displays that category, | |
1000 | prompts for the priority of the moved item in the category moved to and | |
1001 | inserts the item accordingly. Minibuffer completion of the name of the | |
1002 | category moved to works as with the navigation command @kbd{j}, and as | |
1003 | with that command, passing a prefix argument prompts for a file and | |
1004 | moves the item to a category in that file; and if the category name you | |
1005 | enter is new, then you are asked whether to add the category to the | |
1006 | file, and if you affirm, the item is moved to the new category. | |
1007 | @end table | |
1008 | ||
cb9af965 SB |
1009 | You can delete an item, thereby permanently (and, as far as Todo mode |
1010 | is concerned, irrevocably) removing it from the todo file: | |
016d3f7d SB |
1011 | |
1012 | @table @kbd | |
1013 | ||
1014 | @item k | |
1015 | Delete the todo item at point (@code{todo-delete-item}; the binding is | |
526e5233 | 1016 | mnemonic for ``kill'', since @kbd{d} is used for marking items as done |
016d3f7d SB |
1017 | (@pxref{Done Items}); but note that @kbd{k} does not put the item into |
1018 | the kill ring). This command requires confirmation that you want to | |
1019 | delete the item, since you cannot undo the deletion in Todo mode. (You | |
1020 | could use @kbd{F e} to recover the item, but be aware that this would | |
1021 | put the file in an inconsistent state, which you can recover from, but | |
1022 | not without a risk; cf.@: the cautionary note in @ref{Reordering | |
1023 | Categories}.) | |
1024 | @end table | |
1025 | ||
1026 | @quotation Note | |
1027 | Todo commands that require user confirmation, such as @kbd{k}, use a | |
1028 | modified form of @code{y-or-n-p}, which by default only accepts @kbd{y} | |
1029 | or @kbd{Y}, but not @key{SPC}, as an affirmative answer. This is to | |
1030 | diminish the risk of unintentionally executing the command, which is | |
1031 | especially important with commands that do deletion, since there is no | |
52e9721b | 1032 | Todo command to undo a deletion. If you want to be able to use @key{SPC} for |
016d3f7d SB |
1033 | confirmation, enable the option @code{todo-y-with-space}. |
1034 | @end quotation | |
1035 | ||
1036 | @node Done Items, , Moving and Deleting Items, Relocating and Removing Items | |
1037 | @subsubsection Done Items | |
1038 | ||
1039 | When the activity or thing that a todo item is about has been done, it | |
1040 | is natural to eliminate the item from the todo list. But instead of | |
1041 | deleting it permanently, you may prefer to keep a record of your | |
1042 | accomplishments by marking the item as done. In Todo mode, this removes | |
1043 | the done item from the todo list, so as not to clutter it up, and stores | |
1044 | it elsewhere. Such stored items form a record or diary of things done. | |
1045 | The Todo package provides two such stores: the ``done items'' section of | |
1046 | a Todo category, described here, and done item archives (@pxref{Todo | |
1047 | Archive Mode}). | |
1048 | ||
1049 | @table @kbd | |
1050 | ||
cb9af965 | 1051 | @anchor{todo-item-done} |
016d3f7d | 1052 | @item d |
903204bb SB |
1053 | This command (@code{todo-item-done}) removes the todo item at point |
1054 | from the todo list, appends to the original header a header consisting | |
1055 | of @code{todo-done-string} (by default @samp{DONE }) and the current | |
1056 | date, and if @code{todo-always-add-time-string} is enabled, also the | |
1057 | current time, and adds the resulting done item to the top of the done | |
1058 | items section of the category. Invoked with a prefix argument, it | |
1059 | also prompts you to enter a comment, which is appended to the end of | |
1060 | the done item, prefixed with @code{todo-comment-string} (by default | |
1061 | @samp{COMMENT: }). | |
016d3f7d SB |
1062 | @end table |
1063 | ||
1064 | A category's done items section is located below the last todo (i.e., | |
1065 | not done) item in the category. By default this section is hidden from | |
1066 | view. There are two commands for viewing and hiding done items; since | |
1067 | these are toggle commands, for convenience they also have a single key | |
1068 | binding: | |
1069 | ||
1070 | @table @kbd | |
1071 | ||
1072 | @item C v | |
1073 | @itemx v | |
1074 | Make the done items section of the current category visible if it is | |
1075 | hidden, or hide it if it is visible | |
1076 | (@code{todo-toggle-view-done-items}). If you always want to see the | |
1077 | done items section on entering a category, enable the option | |
1078 | @code{todo-show-with-done}; you can still use @kbd{C v} or @kbd{v} to | |
1079 | hide (and unhide) it. | |
1080 | ||
1081 | @item F V | |
1082 | @itemx V | |
1083 | Toggle the standard category display in the current todo file, i.e., | |
1084 | display only the done items section of each category in the file, or if | |
1085 | this is visible, hide it again and display only the todo items section | |
1086 | (@code{todo-toggle-view-done-only}). | |
1087 | @end table | |
1088 | ||
cb9af965 SB |
1089 | Since done items are meant to be a record of your finished todo items, |
1090 | you cannot apply to them the same kinds of editing operations | |
1091 | available to unfinished todo items. However, as explained in | |
1092 | @ref{Editing Item Headers and Text} and repeated below for | |
1093 | convenience, you can edit or delete a done item's comment, or | |
1094 | retroactively add a comment. You can also relocate a done item, and | |
1095 | you can revert its done status, making it an unfinished item again. | |
016d3f7d SB |
1096 | |
1097 | @table @kbd | |
1098 | ||
1099 | @item e c | |
cb9af965 SB |
1100 | Edit the current done item's comment, if it has one; otherwise, prompt |
1101 | for and add a comment. | |
1102 | ||
1103 | @item e d | |
1104 | Delete the current done item's comment, if it has one. | |
016d3f7d SB |
1105 | |
1106 | @item m | |
1107 | Move the done item at point to the top of the done items section of | |
cb9af965 SB |
1108 | another category (@code{todo-move-item}). This is useful in case, |
1109 | after having finished a todo item and relocated it to its category's | |
1110 | done items section, you create a category that is better suited to the | |
1111 | content of the done item than its current category; in other words, | |
1112 | you can retroactively recategorize the done item. | |
016d3f7d SB |
1113 | |
1114 | @item u | |
1115 | If you decide the done item at point is not done after all, this command | |
1116 | ``undoes'' it, i.e., restores it to the todo list of its category, with | |
1117 | the priority you choose for it (@code{todo-item-undone}). If the done | |
1118 | item has a comment, you are asked whether to delete it from the restored | |
1119 | item. | |
1120 | @end table | |
1121 | ||
1122 | @node Todo Archives, Marked Items, Editing, Top | |
1123 | @chapter Todo Archives | |
1124 | ||
1125 | When the done items section of a category itself starts to become | |
1126 | cluttered, or if you just want to store some accomplished todo items in | |
1127 | a separate file, you can move them to a Todo archive. This is a file | |
1128 | with exactly the same structure as a todo file, i.e., divided into | |
1129 | categories, but differs in that the categories contain only done items. | |
1130 | Todo archives reside, like todo files, in @code{todo-directory} but have | |
1131 | the extension @samp{.toda} instead of @samp{.todo}. | |
1132 | ||
1133 | @menu | |
1134 | * Creating and Visiting Archives:: | |
1135 | * Todo Archive Mode:: | |
1136 | @end menu | |
1137 | ||
1138 | @node Creating and Visiting Archives, Todo Archive Mode, , Todo Archives | |
1139 | @section Creating and Visiting Archives | |
1140 | ||
1141 | Todo mode provides the following command for archiving items: | |
1142 | ||
1143 | @table @kbd | |
1144 | ||
1145 | @item A d | |
1146 | This command (@code{todo-archive-done-item}) archives the done item at point. | |
1147 | Invoked with a prefix argument, it archives all done items in the | |
1148 | current todo category. If an archive for the current todo file | |
1149 | already exists and contains a category with the same name as the | |
1150 | current todo category, then this command moves the done item to the | |
1151 | top of the corresponding archive category. If the archive exists but | |
1152 | it does not have a corresponding category, this command creates the | |
1153 | category in the archive and moves the done item to it. If no archive | |
1154 | for the todo file exists, the command creates both the archive file, | |
1155 | using the same base name as that of the todo file, as well as the | |
1156 | category, and moves the done item to it. | |
1157 | @end table | |
1158 | ||
1159 | Typing @kbd{A d} is also the only way within the Todo mode package to | |
1160 | create an archive file and its categories. Consequently, as a rule each | |
1161 | archive file corresponds to exactly one todo file and has the same base | |
1162 | name as this file, and each category in an archive file corresponds to | |
1163 | and has the same name as a category in the corresponding todo file. | |
1164 | Exceptions can only arise if you delete a todo file but not the | |
1165 | corresponding archive, or if you delete a category in a todo file that | |
1166 | has a corresponding category in an archive. | |
1167 | ||
1168 | You might be inclined to do the latter if you have archived all the | |
1169 | items from a given todo category and you don't plan to add new items to | |
1170 | it. In particular, if you have numerous such empty categories in a todo | |
1171 | file, this can make sequential navigation in the file annoying. You can | |
1172 | avoid this annoyance by deleting these categories, but only at the cost | |
1173 | of putting the todo file out of synch with the archive file. | |
1174 | ||
1175 | You may find it preferable not to delete empty todo categories but to | |
1176 | enable the option @code{todo-skip-archived-categories}. When this is | |
4181427f | 1177 | non-@code{nil}, such empty todo categories are skipped over by the sequential |
016d3f7d SB |
1178 | category navigation commands @kbd{f} and @kbd{b}, so they don't distract you |
1179 | while navigating and you maintain the structural correspondence between | |
1180 | todo and archive files (you can also still jump to empty todo categories | |
1181 | with @kbd{j}). | |
1182 | ||
1183 | If you rename a todo category that has a corresponding category in an | |
1184 | archive, the archive category is also automatically identically renamed. | |
1185 | Likewise, if you move such a todo category to another file; in this | |
1186 | case, if there is no archive file corresponding to the todo file the | |
1187 | category is moved to, then the archive is automatically created and the | |
1188 | archived category is moved to it. | |
1189 | ||
1190 | There are two commands in Todo mode for visiting archive files: | |
1191 | ||
1192 | @table @kbd | |
1193 | ||
1194 | @item A f | |
1195 | Switch to a buffer displaying the archived category corresponding to the | |
1196 | current todo category (@code{todo-find-archive}). If the todo category | |
1197 | has no archived items, the command asks if you want to visit the archive | |
1198 | anyway. If there is no archive for this todo file, it asks if you want | |
1199 | to visit another archive, which you can select via minibuffer | |
1200 | completion. | |
1201 | ||
1202 | @item A c | |
1203 | Choose an archive to visit, whether or not the current todo file has an | |
1204 | archive (@code{todo-choose-archive}). | |
1205 | @end table | |
1206 | ||
1207 | As with todo files, you can also visit a Todo archive by invoking a | |
1208 | standard Emacs file-visiting command; this displays the first (on the | |
1209 | initial invocation) or current category of the archive. | |
1210 | ||
1211 | @node Todo Archive Mode, , Creating and Visiting Archives, Todo Archives | |
1212 | @section Todo Archive Mode | |
1213 | ||
1214 | When you visit a Todo archive, the buffer is in Todo Archive mode. It | |
1215 | displays categories just as in Todo mode, except that they only contain | |
1216 | done items. It provides the same sequential navigation commands as | |
1217 | Todo mode: @kbd{f} and @kbd{b} navigate between the categories of the current | |
1218 | archive, and @kbd{n} and @kbd{p} navigate between the done items of the current | |
1219 | archive category. | |
1220 | ||
1221 | The commands @kbd{t} and @kbd{j} are also available in Todo Archive | |
1222 | mode, and they work the same as in Todo mode, which means they can only | |
1223 | be used to return to Todo mode: @kbd{t} prompt for and switch to a todo | |
1224 | file, and with @kbd{j} you can only jump to a todo category. These | |
1225 | commands exclude archives because an archive file has the same base name | |
1226 | as the corresponding todo file, and category name completion uses only | |
1227 | the base names, so the commands cannot know which type of file you want | |
1228 | to visit. For this reason, there is a special command in Todo Archive | |
1229 | mode for jumping to another archive category or visiting another archive | |
1230 | file: | |
1231 | ||
1232 | @table @kbd | |
1233 | ||
1234 | @item a | |
1235 | This command (@code{todo-jump-to-archive-category}) prompts for a category in the | |
1236 | current archive and jumps to it. Called with a prefix argument, it | |
1237 | prompts for another archive, then for a category in it and jumps to | |
1238 | that category. | |
1239 | @end table | |
1240 | ||
1241 | None of the Todo mode editing commands are available in Todo Archive | |
1242 | mode, since archives are meant to be static records of accomplished todo | |
1243 | items. Should you, however, archive an item by mistake or simply change | |
1244 | your mind about the archival status of an item, you can ``unarchive'' it: | |
1245 | ||
1246 | @table @kbd | |
1247 | ||
1248 | @item u | |
1249 | Restore the done item at point to the top of the done items section of | |
1250 | the corresponding category in the corresponding todo file, i.e., an | |
1251 | unarchived item remains a done item (@code{todo-unarchive-items}). When | |
1252 | the last item in an archive category has been unarchived, the category | |
1253 | is automatically deleted from the archive. If this was the only | |
1254 | category in the archive, the archive file is also automatically deleted. | |
1255 | @end table | |
1256 | ||
1257 | Since it is natural to visit an archive from the corresponding todo | |
1258 | file, it would be convenient to easily return to the todo file when you | |
903204bb | 1259 | have finished browsing the archive. If you type @kbd{q} to quit Todo |
016d3f7d SB |
1260 | Archive mode, this switches to the corresponding todo file and shows the |
1261 | todo category corresponding to the archive category you were just | |
1262 | visiting. | |
1263 | ||
1264 | The command @kbd{F k} (@pxref{File Editing}) is also available in Todo | |
1265 | Archive mode. It deletes the current archive file and prompts you | |
1266 | whether to delete the corresponding todo file. | |
1267 | ||
1268 | @node Marked Items, Todo Categories Mode, Todo Archives, Top | |
1269 | @chapter Marked Items | |
1270 | ||
1271 | For many item editing commands it can make sense and be convenient to | |
1272 | apply them simultaneously to more than one item in the current category. | |
1273 | Todo facilitates this by means of marked items. | |
1274 | ||
1275 | @table @kbd | |
1276 | ||
1277 | @item * | |
1278 | Mark the item at point if it is unmarked, and remove the mark it is | |
1279 | already marked (@code{todo-toggle-mark-item}). The mark is a string | |
1280 | specified by the option @code{todo-item-mark} (by default @samp{*}) | |
1281 | appended in front of the item header (more precisely, in front of the | |
2a024334 | 1282 | item's priority number or prefix; see @ref{Todo Display Features}, for |
016d3f7d SB |
1283 | details of the latter). After marking the current item, the command |
1284 | advances point to the next item. It also accepts a numeric prefix | |
1285 | argument, which allows toggling the mark of multiple consecutive items. | |
1286 | ||
1287 | @item C * | |
1288 | Mark all todo items in the current category. | |
1289 | ||
1290 | @item C u | |
1291 | Unmark all todo item in the current category. | |
1292 | @end table | |
1293 | ||
1294 | You can also use the last two commands to mark or unmark all done items in | |
1295 | the category, but only when only the done items section is being | |
1296 | displayed, i.e., after invoking @kbd{C V} or @kbd{V}. | |
1297 | ||
cb9af965 | 1298 | The following commands operate on marked items: |
016d3f7d | 1299 | |
cb9af965 SB |
1300 | @itemize @bullet |
1301 | ||
1302 | @item | |
1303 | @kbd{k} (deleting) | |
1304 | @item | |
1305 | @kbd{m} (moving to another category) | |
1306 | @item | |
1307 | @kbd{d} (moving to the done items section; note that @kbd{C-u d} adds | |
1308 | the same comment to all marked items) | |
1309 | @item | |
1310 | @kbd{A d} (archiving) | |
1311 | @item | |
1312 | @kbd{u} (both in Todo mode for undoing a done item and in Todo Archive | |
1313 | mode for unarchiving an item) | |
1314 | @item | |
1315 | the commands for editing the item header (those beginning with the | |
1316 | prefix @kbd{e d} as well as @kbd{e t}, @kbd{e y} and @kbd{e k}) | |
1317 | @end itemize | |
1318 | ||
1319 | @noindent | |
1320 | The item insertion, textual editing and priority changing commands do | |
1321 | not operate on marked items. | |
1322 | ||
1323 | If you use @kbd{m}, @kbd{d}, @kbd{A d} or @kbd{u} on multiple | |
1324 | noncontiguous marked items, the relocated items retain their relative | |
1325 | order but are now listed consecutively en bloc. | |
016d3f7d SB |
1326 | |
1327 | You can mark both todo and done items, but note that only @kbd{m} can apply | |
1328 | to both; other commands only affect either marked todo or marked done | |
526e5233 | 1329 | items, so if both types of items are marked, invoking these commands |
016d3f7d SB |
1330 | has no effect and informs you of your erroneous attempt. |
1331 | ||
1332 | @node Todo Categories Mode, Searching for Items, Marked Items, Top | |
1333 | @chapter Todo Categories Mode | |
1334 | ||
cb9af965 SB |
1335 | It can be helpful to have a compact overview of the categories in a |
1336 | todo file and the types of items it contains; the Todo package | |
1337 | provides a tabular view of this information. | |
016d3f7d SB |
1338 | |
1339 | @table @kbd | |
1340 | ||
1341 | @item F c | |
1342 | Typing this command (@code{todo-show-categories-table}) in Todo mode or Todo | |
1343 | Archive mode switches to a buffer displaying a table that gives an | |
1344 | overview of the categories in the current todo or archive file. This | |
1345 | buffer is in Todo Categories mode. | |
1346 | @end table | |
1347 | ||
1348 | The table consists of a column containing the names of the categories in | |
1349 | the file, followed by columns containing counts of certain types of | |
1350 | items in each category. With todo files there are four count types: all | |
1351 | todo (i.e., not done) items, diary items (i.e., those todo items lacking | |
1352 | the @code{todo-nondiary-marker}, which hence can appear in the Fancy Diary | |
1353 | display), done (but not archived) items, and archived items. With | |
1354 | archive files all items are done, so the table only has a column for | |
1355 | this count. The final row of the table gives total item counts across | |
1356 | all categories in the file. | |
1357 | ||
1358 | Aside from explicitly invoking @kbd{F c} to display the table of | |
1359 | categories, you can also arrange to have it displayed on the first | |
1360 | invocation of @code{todo-show} for a given file (i.e., either using | |
1361 | @code{todo-show} to initiate a Todo session, or calling it in Todo mode | |
1362 | to visit another todo file). To do this customize the option | |
1363 | @code{todo-show-first}. | |
1364 | ||
1365 | @menu | |
1366 | * Table of Item Counts:: | |
1367 | * Reordering Categories:: | |
1368 | @end menu | |
1369 | ||
1370 | @node Table of Item Counts, Reordering Categories, , Todo Categories Mode | |
1371 | @section Table of Item Counts | |
1372 | ||
526e5233 | 1373 | Above each column of the table is a labeled button you can press by |
016d3f7d SB |
1374 | clicking with the mouse or by typing @key{RET} on it. Pressing an item |
1375 | count button sorts the table alternately in ascending or descending | |
1376 | order according to the type of count. Pressing the category button | |
1377 | alternates between the initial numerical order of the categories and | |
1378 | alphabetical order. In numerical order the column of category names is | |
1379 | preceded by a column containing the corresponding category numbers; this | |
1380 | column is not displayed in the alphabetical listing. Instead of | |
1381 | pressing the buttons, you can also sort the table by typing the | |
1382 | following keys: | |
1383 | ||
1384 | @itemize | |
1385 | ||
1386 | @item @kbd{c} | |
1387 | to sort by category numerically or alphabetically; | |
1388 | @item @kbd{t} | |
1389 | to sort by todo item counts; | |
1390 | @item @kbd{y} | |
1391 | to sort by diary item counts; | |
1392 | @item @kbd{d} | |
1393 | to sort by done item counts; | |
1394 | @item @kbd{a} | |
1395 | to sort by archived item counts. | |
1396 | @end itemize | |
1397 | ||
1398 | Each row of the table is also buttonized; pressing one of these exits | |
1399 | the buffer (killing it), returns to the buffer of the file from which | |
903204bb SB |
1400 | you had invoked @kbd{F c}, and displays the category that was named in |
1401 | the row button you pressed (i.e., pressing this button jumps to that | |
1402 | category). However, if the category named in the row is in a todo | |
1403 | file and all of its items have been archived, and you have enabled the | |
1404 | option @code{todo-skip-archived-categories}, then pressing the button | |
1405 | jumps to the archive category instead of the empty todo category. You | |
1406 | can recognize such categories by their items counts in the table---all | |
016d3f7d SB |
1407 | columns but the archived one have counts of zero---and in addition, |
1408 | their lines in the table are also distinguished from the others by a | |
cb9af965 | 1409 | different face (@pxref{Faces}). |
016d3f7d SB |
1410 | |
1411 | You can navigate around the table: | |
1412 | ||
1413 | @table @kbd | |
1414 | ||
1415 | @item n | |
1416 | @itemx @key{TAB} | |
1417 | Advance point to the next button. | |
1418 | ||
1419 | @item p | |
1420 | @itemx S-@key{TAB} | |
1421 | Put point on the previous button. | |
1422 | @end table | |
1423 | ||
1424 | These commands are cyclic, e.g. when point is on the last button, | |
1425 | pressing @kbd{n} moves it to the first button. | |
1426 | ||
1427 | Typing @kbd{q} exits Todo Categories mode, killing the buffer and returning | |
1428 | to the current category in the Todo mode or Todo Archive mode buffer | |
1429 | from which you had invoked @kbd{F c}. | |
1430 | ||
1431 | @node Reordering Categories, , Table of Item Counts, Todo Categories Mode | |
1432 | @section Reordering Categories | |
1433 | ||
1434 | Todo Categories mode provide commands with which you can change the | |
1435 | numbering of the categories in the current file. This renumbering has | |
1436 | the effect of reordering the categories for sequential navigation by | |
1437 | @kbd{f} and @kbd{b} in Todo mode and Todo Archive mode. These commands | |
1438 | are only operative when the table displays the categories in their | |
1439 | numerical order. They work just like reprioritizing items in Todo mode, | |
1440 | hence have the same key bindings: | |
1441 | ||
1442 | @table @kbd | |
1443 | ||
1444 | @item r | |
1445 | Raise the current line of the table (the one the cursor is on), | |
1446 | decreasing the category's number by one (@code{todo-raise-category}). | |
1447 | This command exchanges lines, and hence the numbers, of the category at | |
1448 | point and the one above it before invoking the command. | |
1449 | ||
1450 | @item l | |
1451 | Lower the current line of the table, increasing the category's number by | |
1452 | one (@code{todo-lower-category}). This command exchanges lines, and | |
1453 | hence the numbers, of the category at point and the one below it before | |
1454 | invoking the command. | |
1455 | ||
1456 | @item # | |
1457 | Prompt for a number between 1 and the number of categories in the file | |
1458 | and reorder the table accordingly (@code{todo-set-category-number}). If | |
1459 | called with a numeric prefix argument within the allowed range, reorder | |
1460 | the table without prompting. | |
1461 | @end table | |
1462 | ||
1463 | The reordering done by these commands remains in effect when you return | |
1464 | to Todo mode or Todo Archive mode and, as long as you save the todo | |
1465 | or archive file after reordering, in subsequent sessions as well. | |
1466 | ||
1467 | @quotation @strong{Caution} | |
1468 | It is important to be aware that renumbering the categories does not | |
1469 | change the textual order of the categories in the file. This is | |
1470 | significant if you should invoke @kbd{F e} to edit the entire file | |
cb9af965 SB |
1471 | manually and in so doing alter the number of categories or the number |
1472 | of items in a category: this will make the information shown in the | |
1473 | table of categories of this file inconsistent with its actual state. | |
1474 | You can repair this inconsistency by invoking the command | |
1475 | @code{todo-repair-categories-sexp} (which lacks a key binding, since | |
1476 | it is meant to be a rarely needed rescue operation). But this will | |
1477 | revert any renumbering of the categories you have made, so you will | |
1478 | have to renumber them again. This is one reason why you should | |
1479 | exercise caution when using @kbd{F e}. | |
016d3f7d SB |
1480 | @end quotation |
1481 | ||
1482 | @node Searching for Items, Todo Filtered Items Mode, Todo Categories Mode, Top | |
1483 | @chapter Searching for Items | |
1484 | ||
1485 | It can be useful to be able to locate and examine all todo items that | |
1486 | fit certain criteria, regardless of which category they belong to. One | |
1487 | way to do this in Todo mode is by sequentially searching in the file: | |
1488 | ||
1489 | @table @kbd | |
1490 | ||
1491 | @item S | |
2a024334 | 1492 | This command (@code{todo-search}; the key is capital @kbd{S}) prompts for a |
016d3f7d SB |
1493 | regular expression, searches from the beginning of the current todo file |
1494 | and displays the category containing the first match it finds, with the | |
1495 | match highlighted. If there are further matches, a message saying how | |
1496 | many are left is displayed and you are asked if you want to go to the | |
1497 | next match. When you reach the last match, or if you decide not to go | |
1498 | to further matches, you are asked whether the match highlighting should | |
1499 | be removed. | |
1500 | ||
1501 | @item X | |
1502 | This command (@code{todo-clear-matches}) removes any highlighting added by @kbd{S}. | |
1503 | This is so you can leave the matches highlighted at the end of the | |
1504 | search and remove the highlighting later. | |
1505 | @end table | |
1506 | ||
1507 | These commands are also available in Todo Archive mode. | |
1508 | ||
1509 | @node Todo Filtered Items Mode, Todo Display Features, Searching for Items, Top | |
1510 | @chapter Todo Filtered Items Mode | |
1511 | ||
1512 | A more powerful alternative to sequential searching is item filtering, | |
1513 | by which items from different categories that match specified criteria | |
1514 | are gathered and displayed in a new buffer as a kind of virtual | |
2a024334 | 1515 | category in a distinct mode, Todo Filtered Items mode. |
016d3f7d SB |
1516 | |
1517 | @menu | |
1518 | * Filtering Items:: | |
1519 | * Todo Filtered Items Mode Commands:: | |
1520 | * Files of Filtered Items:: | |
1521 | @end menu | |
1522 | ||
1523 | @node Filtering Items, Todo Filtered Items Mode Commands, , Todo Filtered Items Mode | |
1524 | @section Filtering Items | |
1525 | ||
1526 | Todo mode provides three ways to filter items: a general filter for | |
1527 | items matching a user-entered regular expression, as with the search | |
1528 | command; and two specific filters, one for diary-displayable items | |
1529 | (i.e., those lacking @code{todo-nondiary-marker}) and one for top | |
1530 | priority items (more on the latter below). The commands for each | |
1531 | filter come in pairs, one for filtering just the current todo file and | |
1532 | one for filtering a user-specified list of todo files. Thus, there | |
1533 | are six item filtering commands:@footnote{The use of @kbd{F} in the key | |
1534 | sequences of these commands naturally recalls ``filter'', but is also | |
526e5233 | 1535 | consistent with the Todo mode mnemonic key binding convention, since the |
016d3f7d SB |
1536 | commands involve one or more whole files.} |
1537 | ||
1538 | @itemize @bullet | |
1539 | ||
1540 | @item | |
1541 | @kbd{F x x} (@code{todo-filter-regexp-items}) | |
1542 | @item | |
1543 | @kbd{F x m} (@code{todo-filter-regexp-items-multifile}) | |
1544 | @item | |
1545 | @kbd{F y y} (@code{todo-filter-diary-items}) | |
1546 | @item | |
1547 | @kbd{F y m} (@code{todo-filter-diary-items-multifile}) | |
1548 | @item | |
1549 | @kbd{F t t} (@code{todo-filter-top-priorities}) | |
1550 | @item | |
1551 | @kbd{F t m} (@code{todo-filter-top-priorities-multifile}) | |
1552 | @end itemize | |
1553 | ||
1554 | There are two ways to specify which files the multifile filtering | |
1555 | commands apply to. If there are files you want to filter every time you | |
1556 | use these commands, customize the option @code{todo-filter-files}. If you | |
1557 | leave this option empty (the default), invoking a multifile filtering | |
1558 | command pops up a buffer similar to the Customization buffer for | |
1559 | @code{todo-filter-files}, in which you can select files to filter just for | |
1560 | this invocation. | |
1561 | ||
1562 | Diary and top priority items are by definition non-done todo items, but | |
1563 | when filtering by regular expression, you can extend the scope of the | |
1564 | command to done items by enabling the option @code{todo-filter-done-items}. | |
1565 | Then @kbd{F x x} and @kbd{F x m} will gather both matching todo and matching | |
1566 | done items (including done items from any archive files corresponding to | |
1567 | the selected todo files) into the virtual category of filtered items. | |
1568 | ||
1569 | There are several ways to specify how many items in each category count | |
1570 | as top priorities and hence get filtered by @kbd{F t t} and @kbd{F t m}: | |
1571 | ||
1572 | @itemize @bullet | |
1573 | ||
1574 | @item | |
1575 | The option @code{todo-top-priorities} specifies a single default number | |
1576 | for all categories and all todo files; its default value is 1, which | |
1577 | means just the highest priority item in every category is filtered, | |
1578 | unless otherwise specified. | |
1579 | @item | |
1580 | The option @code{todo-top-priorities-overrides} lists file-wide overrides | |
1581 | of @code{todo-top-priorities} as well as category-specific overrides. It | |
1582 | is empty by default. However, using the Custom facility to set this | |
1583 | option would be tedious and error-prone, so instead you should use the | |
1584 | commands @kbd{F t s} and @kbd{C t s}. The former sets (i.e., overrides) the | |
1585 | default number of top priorities for all categories in the current | |
1586 | todo file, and the latter sets the number of top priorities for the | |
1587 | current category. To exclude a category or file from filtering by @kbd{F t t} | |
1588 | and @kbd{F t m}, set the number to @samp{0}. | |
1589 | @item | |
903204bb | 1590 | You can invoke @kbd{F t t} and @kbd{F t m} with a numeric prefix argument, |
016d3f7d SB |
1591 | which specifies the number of top priorities in each category just for |
1592 | this invocation, overriding both @code{todo-top-priorities-overrides} and | |
1593 | @code{todo-top-priorities}. | |
1594 | @end itemize | |
1595 | ||
1596 | @node Todo Filtered Items Mode Commands, Files of Filtered Items, Filtering Items, Todo Filtered Items Mode | |
1597 | @section Todo Filtered Items Mode Commands | |
1598 | ||
1599 | The output of the item filtering commands looks similar to a regular | |
1600 | Todo category, but it is not contained in any todo file and does not | |
1601 | have a name on being created, so it is not a ``real'' category but a | |
1602 | ``virtual'' category. Another difference is the lack of a done items | |
1603 | section; either there are no done items in the list (when the filtered | |
1604 | items are diary or top priority items), or these are displayed in the | |
1605 | same list as todo items (if you filtered by regular expression and | |
1606 | allowed done items). A further difference is that the items have an | |
1607 | additional header, between the item's date/time header and its text, | |
1608 | specifying which category (and if you invoked a multifile command, also | |
1609 | which file) the item comes from, and if you filtered by regular | |
1610 | expression, also whether the item comes from a Todo archive. | |
1611 | ||
1612 | The sequential item navigation commands @kbd{n} and @kbd{p} work the same in | |
1613 | Todo Filtered Items mode as in Todo mode, as do the file and category | |
1614 | jumping commands @kbd{t} and @kbd{j}; however, the sequential category | |
1615 | navigation commands are unavailable, since virtual categories of | |
1616 | filtered items are not ordered with respect to ``real'' categories. In | |
1617 | addition, Todo Filtered Items mode provides a special navigation | |
1618 | command: | |
1619 | ||
1620 | @table @kbd | |
1621 | ||
1622 | @item g | |
1623 | @itemx @key{RET} | |
1624 | If you type this command (@code{todo-go-to-source-item}) with point on a | |
1625 | filtered item, the buffer switches to the item's source file (in Todo | |
1626 | mode or Todo Archive mode, as the case may be) and displays its | |
1627 | category, with point on the item. | |
1628 | @end table | |
1629 | ||
1630 | Filtered items cannot be textually edited, moved to another category, | |
1631 | marked done or archived like items in a real todo category, since these | |
1632 | would then be out of synch with each other. But there is one type of | |
1633 | editing command that does work in Todo Filtered Items mode: changing an | |
1634 | item's priority: | |
1635 | ||
1636 | @table @kbd | |
1637 | ||
1638 | @item r | |
1639 | @itemx l | |
1640 | @itemx # | |
1641 | These commands raise, lower, or set, respectively, the current item's | |
1642 | priority in the virtual category. | |
1643 | @end table | |
1644 | ||
1645 | @noindent | |
1646 | Using these commands, you can create a cross-category (and even | |
1647 | cross-file) prioritized list of filtered items. However, there is a | |
1648 | restriction on these commands in Todo Filtered Items mode: you cannot | |
1649 | change the relative priorities of items from the same real category, | |
1650 | since that would make the filtered list inconsistent with the source | |
1651 | todo list. | |
1652 | ||
1653 | @node Files of Filtered Items, , Todo Filtered Items Mode Commands, Todo Filtered Items Mode | |
1654 | @section Files of Filtered Items | |
1655 | ||
1656 | Typing @kbd{s} in Todo Filtered Items mode saves the buffer of filtered | |
1657 | items to a file in @code{todo-directory}. Files of items filtered by | |
1658 | regular expression have the extension @samp{.todr}, those with filtered | |
1659 | diary items have the extension @samp{.tody} and those with filtered top | |
1660 | priorities have the extension @samp{.todt}. The extensions are added | |
1661 | automatically the first time you save the buffer to a file. | |
1662 | ||
1663 | With filtered top priority or diary items, the file is automatically | |
1664 | named on first saving it, using as the base name either the same base | |
1665 | name as the single todo file it was generated from, or combining the | |
1666 | base names of the todo files used in multifile filtering commands. | |
1667 | With items filtered by regular expression, it can be useful to save | |
1668 | separate lists generated from the same file(s) using different regular | |
1669 | expressions, so when saving such a list, you are prompted for a short | |
1670 | identifying string to add to the file name. | |
1671 | ||
1672 | When you invoke one of the item filtering commands without a prefix | |
1673 | argument and a corresponding file already exists, the command visits | |
1674 | this file (if, for the current file or chosen files, there are multiple | |
1675 | files of items filtered by regular expression, you are prompted to | |
1676 | choose one). To force generation of a new filtered list, invoke the | |
1677 | command with a prefix argument (in the case of top priority items, | |
1678 | either numeric as described above, or the raw prefix argument @kbd{C-u} to | |
1679 | use the values of @code{todo-top-priorities-overrides} or | |
1680 | @code{todo-top-priorities}). | |
1681 | ||
1682 | Aside from explicitly invoking an item filtering command to display a | |
1683 | saved list of items filtered by a given method from given todo files, | |
cb9af965 | 1684 | there are two other ways to visit a saved file of filtered items. You |
903204bb | 1685 | can invoke a command similar to @code{find-file}: |
016d3f7d SB |
1686 | |
1687 | @table @kbd | |
1688 | @item F f | |
1689 | Visit a saved file of filtered items, which you choose via minibuffer | |
1690 | completion (@code{todo-find-filtered-items-file}). | |
1691 | @end table | |
1692 | ||
cb9af965 SB |
1693 | @noindent |
1694 | Alternatively, as with tables of categories, by customizing | |
1695 | @code{todo-show-first} you can have the first invocation of | |
1696 | @code{todo-show} for a given todo file display the corresponding saved | |
1697 | file of filtered items. If there is no saved filtered items list for | |
1698 | the file, @code{todo-show} simply defaults to visiting the file and | |
1699 | displaying its first category, as usual. | |
016d3f7d SB |
1700 | |
1701 | The command @kbd{F k} (@pxref{File Editing}) is also available in Todo | |
1702 | Filtered Items mode. It deletes the current filtered items file. | |
1703 | ||
1704 | @node Todo Display Features, Printing Todo Buffers, Todo Filtered Items Mode, Top | |
1705 | @chapter Todo Display Features | |
1706 | ||
526e5233 | 1707 | You can change the appearance of Todo mode buffers in a variety of ways. |
016d3f7d SB |
1708 | |
1709 | @menu | |
1710 | * Faces:: | |
1711 | * Item Prefix:: | |
1712 | * Other Display Commands and Options:: | |
1713 | @end menu | |
1714 | ||
1715 | @node Faces, Item Prefix, , Todo Display Features | |
1716 | @section Faces | |
1717 | ||
cb9af965 SB |
1718 | Each of the Todo modes uses faces to distinguish various aspects of |
1719 | the display, both structural and informational. For example, the | |
1720 | faces for the date and time strings of todo item headers | |
1721 | (@code{todo-date} and @code{todo-time}, respectively) by default | |
1722 | inherit the attributes of the corresponding faces used by the Emacs | |
1723 | diary; but when the date and time of a Todo diary item (i.e., an item | |
1724 | lacking @code{todo-nondiary-marker}) is earlier than the current date | |
1725 | and time, they are displayed in a different face | |
1726 | (@code{todo-diary-expired}). In this way, you can readily recognize | |
1727 | diary items that have ``expired'' and act accordingly (e.g., by | |
1728 | tagging them as done or by updating the deadlines). | |
1729 | ||
1730 | Another example of an informational face is the face used to | |
1731 | distinguish top priority items (@code{todo-top-priority}). A third | |
1732 | case is the face used in Todo Categories mode to mark rows of the | |
1733 | table containing categories with only archived items | |
1734 | (@code{todo-archived-only}). | |
016d3f7d SB |
1735 | |
1736 | The @code{todo-faces} customization group contains a complete list of | |
1737 | Todo mode faces and brief descriptions of their use. | |
1738 | ||
1739 | ||
1740 | @node Item Prefix, Other Display Commands and Options, Faces, Todo Display Features | |
1741 | @section Item Prefix | |
1742 | ||
1743 | In the default display of (real or virtual) categories in Todo mode, | |
1744 | Todo Archive mode and Todo Filtered Item mode the items are visually | |
1745 | numbered in ascending order, starting with @samp{1} on the top item, | |
1746 | displayed to the left of its header (date/time string). With todo items | |
1747 | the numbers indicate each item's priority in the list, so when you | |
1748 | reprioritize an item with @kbd{#} or move it with @kbd{m}, these numbers make | |
1749 | it easier to choose the item's new priority. The numbering also lets | |
1750 | you to see at a glance how many items there are in the list. When an | |
1751 | item is inserted, deleted, or moved, the numbering is automatically | |
1752 | updated. In Todo mode, the todo and done items sections in each | |
1753 | category are separately numbered. | |
1754 | ||
1755 | If you prefer not to have item numbering displayed, disable the option | |
1756 | @code{todo-number-prefix}; then the display of each item starts by default | |
1757 | simply with its header. But you can also replace the numbering with a | |
1758 | visually distinctive string of your choice by customizing the option | |
1759 | @code{todo-prefix} (the empty string by default). Another alternative is to | |
1760 | temporarily hide the item numbering: | |
1761 | ||
1762 | @table @kbd | |
1763 | ||
1764 | @item F N | |
1765 | @itemx N | |
1766 | Toggle between displaying item numbering and displaying the | |
1767 | @code{todo-prefix} string in the current Todo file (todo, archive, or | |
cb9af965 | 1768 | saved virtual category of filtered items). (This command also works in |
016d3f7d SB |
1769 | buffers of filtered items that have not yet been written to a file.) |
1770 | @end table | |
1771 | ||
1772 | In the todo items section of each Todo mode category, the item prefix | |
cb9af965 SB |
1773 | (whether a priority number or a fixed string) of the top priority |
1774 | items (determined as specified in @pxref{Filtering Items}) is | |
1775 | displayed in a face (@code{todo-top-priority}) different from the face | |
1776 | of the prefix of non-top-priority items, so you see at a glance how | |
1777 | many items in the category are top priorities. | |
016d3f7d SB |
1778 | |
1779 | @node Other Display Commands and Options, , Item Prefix, Todo Display Features | |
1780 | @section Other Display Commands and Options | |
1781 | ||
1782 | There are two additional toggle commands that affect display in the | |
1783 | current file: | |
1784 | ||
1785 | @table @kbd | |
1786 | ||
1787 | @item F h | |
1788 | @itemx h | |
1789 | Hide the item headers if visible, or show them if they are hidden. | |
1790 | With done items, only the done header (i.e. the done tag and date-time | |
1791 | string inserted when the item was marked done) is hidden, the original | |
1792 | date-time string is not. With filtered items, the category (or | |
1793 | category-file) tag is not hidden. | |
1794 | ||
1795 | @item F H | |
1796 | @itemx H | |
cb9af965 SB |
1797 | Highlight the current item (with the face @code{hl-line}) if |
1798 | unhighlighted, or remove its highlighting. When item highlighting is | |
1799 | enabled, it follows navigation by @kbd{n} or @kbd{p}. If you want to | |
1800 | have current item highlighting by default, enable the option | |
1801 | @code{todo-highlight-item}. @kbd{F H} or @kbd{H} will still toggle | |
1802 | it. | |
016d3f7d SB |
1803 | @end table |
1804 | ||
1805 | There are two options which affect the display of items whose content is | |
1806 | longer than one screen line: | |
1807 | ||
1808 | @itemize @bullet{} | |
1809 | ||
1810 | @item | |
1811 | @code{todo-indent-to-here} sets the amount of indentation for all lines | |
1812 | after the first in multiline todo items, which is necessary in order | |
1813 | for todo diary items to be fully visible in the Fancy Diary display. | |
1814 | The default indentation is 3 spaces. For a uniform appearance this | |
1815 | option applies to all items, i.e., diary and nondiary todo items and | |
1816 | also done items. | |
1817 | ||
1818 | @item | |
1819 | @code{todo-wrap-lines} allows you to choose, for the purposes of | |
1820 | insertion and editing, between treating multiline todo items as | |
1821 | containing multiple logical lines with hard line breaks or as multiple | |
1822 | visual lines using Visual Line mode; the latter is the default. Since | |
1823 | multiparagraph items also contain hard line breaks in Visual Line mode, | |
1824 | for a uniform appearance this display shows indentation on wrapped lines | |
1825 | by using a wrap-prefix of @code{todo-indent-to-here} spaces. | |
1826 | @end itemize | |
1827 | ||
1828 | The indentation inserted after a hard newline is actually a tab | |
1829 | character, and the Todo modes that display items bind @code{tab-width} to | |
1830 | @code{todo-indent-to-here}, so if you change the default value of the | |
1831 | latter, the next time you visit a Todo file, the indentation will | |
1832 | reflect your change. | |
1833 | ||
1834 | By default, the todo and done items sections of a todo category are | |
1835 | visually separated by a line as wide as the window the buffer is | |
1836 | displayed in. You can change the appearance and width of the separator | |
1837 | by customizing @code{todo-done-separator-string}; you can also change the | |
cb9af965 | 1838 | face of the separator string (@code{todo-done-sep}). |
016d3f7d SB |
1839 | |
1840 | There are also several options for changing the appearance in Todo | |
1841 | Categories mode and Todo Filtered Items mode, beyond those mentioned | |
1842 | above in the sections on these modes; see the customization groups | |
1843 | @code{todo-categories} and @code{todo-filtered} for details. | |
1844 | ||
1845 | @node Printing Todo Buffers, Legacy Todo Mode Files, Todo Display Features, Top | |
1846 | @chapter Printing Todo Buffers | |
1847 | ||
1848 | If you print a Todo buffer using one of the standard Emacs printing | |
1849 | commands, it does not look exactly like what you see in the buffer. | |
1850 | This is because some of the display features are non-printable | |
1851 | (specifically, those using overlays, word-wrap and wrap-prefix). Todo | |
1852 | mode provides two print commands that produce output which includes | |
1853 | printable counterparts of such display features: | |
1854 | ||
1855 | @table @kbd | |
1856 | ||
1857 | @item P B | |
1858 | Send the printable buffer output directly to your printer. | |
1859 | ||
1860 | @item P F | |
1861 | Prompt for a file name and write the printable output to that file. | |
1862 | @end table | |
1863 | ||
1864 | By default, Todo uses @code{ps-print-buffer-with-faces} to make the | |
1865 | printable version; you can change this by setting the option | |
1866 | @code{todo-print-function}. | |
1867 | ||
1868 | @node Legacy Todo Mode Files, GNU Free Documentation License, Printing Todo Buffers, Top | |
1869 | @chapter Legacy Todo Mode Files | |
1870 | ||
1871 | Users of the original version of Todo mode will recognize from the | |
1872 | description in this user manual that, although the new version shares | |
1873 | with the original version the same basic user interface and handling of | |
1874 | todo items, there are some incompatible differences between them, such | |
1875 | as the done items sections (there are also other file format | |
1876 | incompatibilities behind the scenes that are normally not visible to | |
1877 | users). | |
1878 | ||
1879 | The most significant incompatibility concerns the item prefix. In the | |
1880 | earlier version of Todo mode the prefix was the initial part of the item | |
1881 | string itself, so in order for the item to be displayable in the Emacs | |
1882 | diary, the prefix had to be a date/time pattern recognizable by the | |
1883 | diary (although the todo item also has its own date/time header). | |
1884 | Moreover, since all items had the same prefix string in the original | |
1885 | version, this means that either only all or no items could appear in the | |
1886 | Fancy Diary display on any given date. This considerably restricts the | |
1887 | practicality of including todo items in the diary. In contrast, the | |
1888 | current version of Todo mode uses overlays for item priority numbering | |
1889 | or prefixes, and item-specific diary-compatible date/time headers and | |
1890 | special marks for todo items to be excluded from the diary, so you can | |
1891 | determine for each item whether and when it appears in the Fancy Diary | |
1892 | display. | |
1893 | ||
1894 | Due to these incompatibilities, files created with the original version | |
1895 | of Todo mode cannot be displayed or edited with the current version. | |
1896 | However, this version provides a function that converts the two main | |
1897 | types of files used by the original version into new-style valid todo | |
1898 | and archive files, respectively, and saves them in | |
1899 | @code{todo-directory}.@footnote{The original version of Todo mode also | |
1900 | allowed saving a file of top priority items, but since you can readily | |
1901 | create such a file with the new version, which is also more flexible, | |
1902 | no conversion is provided for this file.} | |
1903 | ||
1904 | This conversion function is automatically called the first time you | |
1905 | invoke @code{todo-show} (i.e., before you have created a todo file with | |
1906 | the new version), and if it finds the old-style files, it offers to | |
1907 | convert them, making them the first new-style todo and archive files. | |
1908 | If you choose not to convert the old-style files at this time, you can | |
1909 | do so later by invoking the command @code{todo-convert-legacy-files} | |
1910 | (there is no key binding for it, since it shouldn't be necessary to use | |
1911 | it often). (A delicate part of the conversion concerns the customizable | |
1912 | format of item date/time headers in the old-style; see the documentation | |
cb9af965 | 1913 | string of @code{todo-legacy-date-time-regexp} for details.) |
016d3f7d SB |
1914 | |
1915 | @node GNU Free Documentation License, , Legacy Todo Mode Files, Top | |
1916 | @appendix GNU Free Documentation License | |
1917 | @include doclicense.texi | |
1918 | ||
1919 | @bye | |
1920 | ||
1921 | @c End: |