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