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