From: Stephen Berman Date: Sun, 4 Aug 2013 21:27:49 +0000 (+0200) Subject: Add Todo mode user manual. X-Git-Tag: emacs-24.3.90~173^2^2~42^2~45^2~387^2~1686^2~431 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=016d3f7ddcc9afd60c455cbf4dd79277080c4d4e;p=emacs.git Add Todo mode user manual. * doc/misc/Makefile.in (INFO_TARGETS, DVI_TARGETS, PDF_TARGETS): Add todo-mode. (todo-mode, $(buildinfodir)/todo-mode$(INFO_EXT)): (todo-mode.dvi, todo-mode.pdf): New rules. * doc/misc/todo-mode.texi: New file. * info/dir: Add todo-mode. --- diff --git a/ChangeLog b/ChangeLog index cd8ce1a25ec..1252a7a15a4 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,7 @@ +2013-08-04 Stephen Berman + + * info/dir: Add todo-mode. + 2013-08-04 Paul Eggert Fix some minor races in hosts lacking mkostemp (Bug#15015). diff --git a/doc/misc/ChangeLog b/doc/misc/ChangeLog index 7f5c70e07e3..979ec83010e 100644 --- a/doc/misc/ChangeLog +++ b/doc/misc/ChangeLog @@ -1,3 +1,11 @@ +2013-08-04 Stephen Berman + + * Makefile.in (INFO_TARGETS, DVI_TARGETS, PDF_TARGETS): Add todo-mode. + (todo-mode, $(buildinfodir)/todo-mode$(INFO_EXT)): + (todo-mode.dvi, todo-mode.pdf): New rules. + + * todo-mode.texi: New file. + 2013-08-01 Lars Magne Ingebrigtsen * gnus.texi (Basic Usage): Mention that warp means jump here. diff --git a/doc/misc/Makefile.in b/doc/misc/Makefile.in index 67a899af8ce..7e08c5a2088 100644 --- a/doc/misc/Makefile.in +++ b/doc/misc/Makefile.in @@ -48,7 +48,7 @@ INFO_TARGETS = ada-mode auth autotype bovine calc ccmode cl \ flymake forms gnus emacs-gnutls htmlfontify idlwave ido info.info \ mairix-el message mh-e newsticker nxml-mode \ org pcl-cvs pgg rcirc remember reftex sasl \ - sc semantic ses sieve smtpmail speedbar srecode tramp \ + sc semantic ses sieve smtpmail speedbar srecode todo-mode tramp \ url vip viper widget wisent woman DVI_TARGETS = \ @@ -100,6 +100,7 @@ DVI_TARGETS = \ smtpmail.dvi \ speedbar.dvi \ srecode.dvi \ + todo-mode.dvi \ tramp.dvi \ url.dvi \ vip.dvi \ @@ -157,6 +158,7 @@ PDF_TARGETS = \ smtpmail.pdf \ speedbar.pdf \ srecode.pdf \ + todo-mode.pdf \ tramp.pdf \ url.pdf \ vip.pdf \ @@ -645,6 +647,15 @@ srecode.dvi: ${srcdir}/srecode.texi ${gfdl} srecode.pdf: ${srcdir}/srecode.texi ${gfdl} $(ENVADD) $(TEXI2PDF) ${srcdir}/srecode.texi +todo-mode : $(buildinfodir)/todo-mode$(INFO_EXT) +$(buildinfodir)/todo-mode$(INFO_EXT): ${srcdir}/todo-mode.texi ${gfdl} + $(mkinfodir) + $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/todo-mode.texi +todo-mode.dvi: ${srcdir}/todo-mode.texi ${gfdl} + $(ENVADD) $(TEXI2DVI) ${srcdir}/todo-mode.texi +todo-mode.pdf: ${srcdir}/todo-mode.texi ${gfdl} + $(ENVADD) $(TEXI2PDF) ${srcdir}/todo-mode.texi + tramp : $(buildinfodir)/tramp$(INFO_EXT) $(buildinfodir)/tramp$(INFO_EXT): ${srcdir}/tramp.texi ${srcdir}/trampver.texi ${gfdl} $(mkinfodir) diff --git a/doc/misc/todo-mode.texi b/doc/misc/todo-mode.texi new file mode 100644 index 00000000000..a14802e9181 --- /dev/null +++ b/doc/misc/todo-mode.texi @@ -0,0 +1,1760 @@ +\input texinfo.tex @c -*-texinfo-*- +@c %**start of header +@setfilename ../../info/todo-mode +@settitle Todo Mode User Manual +@syncodeindex fn cp +@syncodeindex vr cp +@syncodeindex ky cp +@c %**end of header + +@copying +Copyright @copyright{} 2013 Free Software Foundation, Inc. + +@quotation +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with the Front-Cover texts being ``A GNU Manual'', +and with the Back-Cover Texts as in (a) below. A copy of the license +is included in the section entitled ``GNU Free Documentation License''. + +(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and +modify this GNU manual.'' +@end quotation +@end copying + +@dircategory Emacs +@direntry +* Todo Mode: (todo-mode). Make and maintain todo lists. +@end direntry + +@titlepage +@title Todo Mode User Manual +@subtitle Facilities for making and maintaining todo lists. + +@author Stephen Berman +@page + +@vskip 0pt plus 1filll +@insertcopying +@end titlepage + +@contents + +@ifnottex + +@node Top +@top Todo Mode User Manual + +This manual describes the version of Todo mode first appearing in +Emacs 24.4. + +@insertcopying +@end ifnottex + +@menu +* Overview:: +* Todo Mode Entry Points:: +* Key Binding Conventions:: +* Navigation:: Moving within and between categories. +* Editing:: Adding, deleting and changing todo + files, categories and items. +* Todo Archives:: Files of done todo items. +* Marked Items:: Acting on multiple items simultaneously. +* Todo Categories Mode:: Table of categories and item counts. +* Searching for Items:: +* Todo Filtered Items Mode:: Making virtual categories of items from + different categories and files. +* Todo Display Features:: +* Printing Todo Buffers:: +* Legacy Todo Mode Files:: Converting old-style todo files. + +* GNU Free Documentation License:: + +@detailmenu +--- The Detailed Node Listing --- + +Overview + +* Levels of Organization:: +* Todo Items as Diary Entries:: + +Editing + +* File Editing:: +* Category Editing:: +* Item Editing:: + +Item Editing + +* Inserting New Items:: +* Editing Item Headers and Text:: +* Relocating and Removing Items:: + +Relocating and Removing Items + +* Reprioritizing Items:: +* Moving and Deleting Items:: +* Done Items:: + +Todo Archives + +* Creating and Visiting Archives:: +* Todo Archive Mode:: + +Todo Categories Mode + +* Table of Item Counts:: +* Reordering Categories:: + +Todo Filtered Items Mode + +* Filtering Items:: +* Todo Filtered Items Mode Commands:: +* Files of Filtered Items:: + +Todo Display Features + +* Faces:: +* Item Prefix:: +* Other Display Commands and Options:: +@end detailmenu +@end menu + +@node Overview, Todo Mode Entry Points, Top, Top +@chapter Overview + +The Todo mode package provides facilities for making and maintaining +todo lists. A todo list is a list of todo items---things to do (in the +widest sense)---arranged in order of priority, with the highest priority +item at the top of the list and the lowest priority item at the bottom. + +This manual describes the Todo mode user interface. Todo mode comprises +a large number of commands and user options for creating, displaying, +navigating and editing todo lists, distributed across five major modes. +The principle major mode is Todo mode; the other four (Todo Edit mode, +Todo Archive mode, Todo Categories mode, and Todo Filtered Items mode) +are subsidiary to and accessible from Todo mode. + +This version of Todo mode greatly expands on, and in significant ways +differs from, the original version; for details and consequences of the +most important differences, @xref{Legacy Todo Mode Files}. + +@menu +* Levels of Organization:: +* Todo Items as Diary Entries:: +@end menu + +@node Levels of Organization, Todo Items as Diary Entries, , Overview +@section Levels of Organization + +In Todo mode each todo list is identified with a named category, so you +can group together thematically related todo items. Each category is +stored in a file, which thus provides a further level of organization. +You can create as many todo files, and in each as many categories, as +you want. + +All todo files reside in a single directory, whose location is specified +by the user option @code{todo-directory}. This directory may also +contain other types of Todo files, which are discussed later +(@pxref{Todo Archive Mode} and @ref{Todo Filtered Items Mode}). Emacs +recognizes Todo files by their extension, so when you visit the files +the buffer is in the appropriate mode and the current category is +correctly displayed. + +When you use a Todo mode command to create a todo file, the extension +@samp{.todo} is automatically added to the base name you choose (as a +rule, this name is also used for the other types of Todo files, which +have their own extensions). As a user, you only have to deal with the +base name of a Todo file. + +When you create a new todo file, you must also add at least one category +to it, and each todo item belongs to a category. It is not possible to +have an uncategorized todo list, but you can always make a catch-all +category with a generic name like ``Todo'', which is in fact the default +name assigned to the first category when you create a new todo file, if +you don't provide a different name; you can change the default by +customizing @code{todo-initial-category}. + +The most basic level of organization is the todo item itself, since it +contains the information about what you want to do. As detailed in +subsequent sections of this manual, most Todo mode commands and user +options concern ways of classifying and deploying this information by +associating various kinds of metadata with it, e.g., the category it +belongs to, its priority, whether it is to be included in the Emacs +diary, date and time stamps, whether it is done or still to do. + +@node Todo Items as Diary Entries, , Levels of Organization, Overview +@section Todo Items as Diary Entries + +Each todo item is also a potential diary item: if you include a todo +file in the Emacs diary file (@pxref{Fancy Diary Display,,, emacs}), the +Fancy Diary display will show those todo items that are not marked with +@code{todo-nondiary-marker}. This effectively augments the Emacs diary +with categorized diary entries. For the various options available for +making a todo item a diary entry, @ref{Inserting New Items} and +@xref{Editing Item Headers and Text}. + +To ensure the proper display of todo items in the Fancy Diary display, +they must have the format of diary entries, i.e., they have to begin +with a date string recognized by the Emacs diary,@footnote{Two types of +dates recognized by the Emacs diary are not supported in the current +Todo mode implementation: sexp diary entries and date strings in which +the year is omitted (however, the latter type is equivalent to using +@samp{*} for an arbitrary year, which Todo mode does support).} and if +they are longer than one line, all lines but the first must begin with +white space. Todo mode ensures that these requirements are satisfied +(@pxref{Other Display Commands and Options}). + +The Fancy Diary display is also Todo mode aware: if it contains an item +from a Todo mode file, clicking or typing @key{RET} on this item will +switch to the buffer visiting that file and properly display the item's +category, with point on the item. + +@node Todo Mode Entry Points, Key Binding Conventions, Overview, Top +@chapter Todo Mode Entry Points + +To initialize your first todo file, invoke the command @code{todo-show}. +This prompts you for a file name (defaulting to the value of +@code{todo-initial-file}), prompts you for the name of the first +category (defaulting to the value of @code{todo-initial-category}), +creates and visits the file and displays the category in Todo mode, and +then prompts you to enter the first item. If you choose not to enter an +item now, simply type @kbd{C-g}, which leaves the category empty but +otherwise well-formed. If you prefer not to be prompted to enter an +item on adding a new category, disable the option +@code{todo-add-item-if-new-category}. + +Once at least one todo file exists, invoking @code{todo-show} enters +Todo mode. Invoked with a prefix argument, the command prompts for +which todo file to visit. Otherwise, the first invocation of this +command after loading the Todo mode package visits the default todo file +(option @code{todo-default-todo-file}) and shows its first category. +(You can get a different display with the first invocation of +@code{todo-show} by customizing the option @code{todo-show-first}; +@pxref{Todo Categories Mode} and @ref{Files of Filtered Items}.) + +If you leave Todo mode and later invoke @code{todo-show} to re-enter it, +by default this returns you to the current (i.e., last displayed) +category of the current todo file, which is the one in the most recently +selected and still live buffer visiting a todo file. If you disable the +option @code{todo-show-current-file}, then non-initial invocations of +@code{todo-show} always return to the first or current category of the +default todo file. + +If you want to enter Todo mode and go directly to a specific category +instead the first or current category in the current or default todo +file, use the command @code{todo-jump-to-category}; @ref{Navigation} for +details. You can also enter Todo mode by invoking a todo item insertion +command; @ref{Inserting New Items} for details. + +The most convenient way to use these commands to enter Todo mode is to +define global key bindings for them in your init file. Good choices are +for @code{todo-show} and @code{todo-jump-to-category} are @kbd{C-c t} +and @kbd{C-c j}, since these commands are bound to @kbd{t} and @kbd{j}, +respectively, in Todo mode. For invoking item insertion from outside of +Todo mode, it is useful to bind @code{todo-insertion-map}, which is the +key map containing the bindings of all Todo item insertion commands, to +@kbd{C-c i}, since it is bound to @kbd{i} in Todo mode; to complete the +invocation, supply the rest of the key sequence (@pxref{Inserting New +Items}). + +You can also visit a Todo file via @code{find-file} or Dired, like any +other file, and since Emacs recognizes it, the buffer will automatically +be in the appropriate Todo mode. Moreover, as long as the command you +use to visit the file is listed in the option +@code{todo-visit-files-commands} (which by default contains +@code{find-file} and @code{dired-find-file}), it will also correctly +display the file's first category on first visiting the file (otherwise +you have to use one of the commands for navigating between categories in +order to get a proper display). + +You can leave Todo mode by typing @kbd{q} (@code{todo-quit}), which +buries the current todo file buffer. Doing this also saves any changes +you have made to the file, and leaves both the file and the category +that was displayed on quitting current for subsequent Todo mode commands +(unless the buffer made current by quitting is visiting another file and +category in Todo mode, in which case the latter become current for Todo +mode commands). + +@node Key Binding Conventions, Navigation, Todo Mode Entry Points, Top +@chapter Key Binding Conventions + +For Todo mode commands to function properly, it is essential to maintain +the correct format at all three levels of organization---item, category, +and file. Todo mode tries to minimize the risk of format corruption by +hiding certain parts of the format from the user, making the buffer +read-only and suppressing the self-insertion keys. Consequently, it is +normally impossible to make changes to your todo files without +explicitly invoking Todo mode commands. + +A beneficial side effect of this restrictiveness is that you can invoke +almost all Todo commands by typing ordinary printing characters, either +singly or in specified sequences, without using modifier keys, except +for the shift key for capitalization and the raw prefix argument +@kbd{C-u}; numeric prefix arguments can be entered just by typing a +number key. + +The predefined key bindings in Todo are more or less mnemonic. As a +rule, key sequences beginning with @kbd{C} are bound to commands +applying to categories, sequences beginning with @kbd{F} apply to +(non-archive) file-level commands, and those beginning with @kbd{A} +apply to archives (a special type of Todo file; @ref{Todo Archive +Mode}). Todo commands applying to items, which constitute the majority, +are bound to lower case key sequences. + +@node Navigation, Editing, Key Binding Conventions, Top +@chapter Navigation + +The navigation commands are for making another todo file, category, or +item the current one by moving point to it.@footnote{Many editing +commands can also do this by side effect, but since that is not their +main function, they are not included in this section.} Since these +commands are likely to be used frequently and repetitively, it is +convenient for their key bindings to be single lower case keys, even for +navigation commands applying to categories and files. + +Two of the navigation commands were already mentioned in the section on +Todo mode entry points: + +@table @kbd + +@item t +Display another todo file in the selected window (@code{todo-show}). +When you invoke this command in Todo mode, it prompts for a file name, +which you can choose via minibuffer completion (like invoking +@code{todo-show} with a prefix argument outside of Todo mode). If a +buffer is already visiting that file, it displays its current category; +if invoking @kbd{t} opens the file, it display its first category (by +default; see the option @code{todo-show-first} for other possibilities). + +@item j +Display another todo category in the selected window +(@code{todo-jump-to-category}). When you invoke this command, it +prompts for a category name, which you can choose via minibuffer +completion. The candidates for completion include the categories in the +current todo file as well as those in the files listed in the option +@code{todo-category-completions-files}. If you type @key{RET} without +choosing a category, the current category of the current todo file is +automatically selected (this can be a useful shortcut when you invoke +@code{todo-jump-to-category} outside of Todo mode). If you type the +name of a non-existing category, you can add this to the file as a new +category and jump to it. If you invoke this command with a prefix +argument, it first you prompts for which todo file to jump to (which you +can also choose with minibuffer completion) and then for which category +from that file; in this case, completion is only against the categories +in the selected file. +@end table + +It is also convenient to navigate back and forth sequentially between +the categories of a single todo file. The categories of a todo file are +numbered consecutively starting with @samp{1}.@footnote{A category's +number is automatically assigned when the category is created: the +category is appended to the end of the file, so its number is simply the +highest until another category is added. There is no command in Todo +mode to reorder the numbering of the categories in a todo file, but this +is possible from the file's table of categories; @ref{Todo Categories +Mode}.} The current category's number and name appear in the mode line. + +@table @kbd + +@item f +Move point to the first item of the category numerically directly +following the current category (@code{todo-forward-category}). + +@item b +Move point to the first item of the category numerically directly +preceding the current category (@code{todo-backward-category}). +@end table + +With @kbd{f} and @kbd{b} you can cycle through the categories, so for example, +if the last category is current and you type @kbd{f}, then the first +category becomes current. + +You can also navigate between the items in the current category: + +@table @kbd + +@item n +Move point down to the next item below the current one (i.e., to the +item with the next lower priority) (@code{todo-next-item}). + +@item p +Move point up to the item directly above the current one (i.e., to the +item with the next higher priority) (@code{todo-previous-item}). +@end table + +These commands also accept a positive numeric prefix argument; e.g., +typing @kbd{5 n} or @kbd{5 p} navigates in one step to the item five items lower +or higher than the current one. + +Navigation to other types of Todo files is discussed in the relevant +sections below. + +@node Editing, Todo Archives, Navigation, Top +@chapter Editing + +Editing in Todo mode means making structural or textual changes at one +of the levels of organization (file, category, or item). Structural +editing includes adding, relocating and removing, textual editing includes +renaming files or categories and changing an item's content or date, or +adding certain kinds of marks or tags to items. To save changes you +make to the current todo file, type @kbd{s} (@code{todo-save}). Changes +are also saved on quitting Todo mode with @kbd{q}. + +@menu +* File Editing:: +* Category Editing:: +* Item Editing:: +@end menu + +@node File Editing, Category Editing, , Editing +@section File Editing and Todo Edit Mode + +There are four file-level editing commands: + +@table @kbd + +@item F a +Add a new todo file (@code{todo-add-file}). This command prompts for a +name and creates the file in @code{todo-directory}, adding the +@samp{.todo} extension (so you should not include the extension in the +name you enter). The command also prompts for the file's first category and, if +option @code{todo-add-item-if-new-category} is enabled (the default), +for that category's first item. + +@item F r +Rename the current todo file (@code{todo-rename-file}). If called with +a prefix argument, prompt for a todo file and rename it. If the todo +file has an archive (@pxref{Todo Archive Mode}) or there are +corresponding filtered items files (@pxref{Todo Filtered Items Mode}), +this command renames these accordingly. If there are live buffers +visiting any of these files, the command also rename them accordingly. + +@item F k +Delete the current todo file (@code{todo-delete-file}).@footnote{The key +binding of this command is mnenomic for ``kill'' to parallel the binding +@kbd{k} for item deletion, since @kbd{d} is bound to another item +editing command (@pxref{Done Items}).} If the todo file has an archive +(@pxref{Todo Archive Mode}), prompt whether to delete that as well. +This command also kill the buffers visiting the deleted files. + +@item F e +This command (@code{todo-edit-file}) changes the buffer's major mode to +Todo Edit mode. In this mode the entire file is visible, the buffer is +writeable and you can use the self-insertion keys and standard Emacs +editing commands to make changes. To return to Todo mode, type @kbd{C-x +C-q} (@code{todo-edit-quit}). + +The command @kbd{F e} is not intended for normal editing of items and +categories, as it circumvents the restrictions that Todo imposes to +protect against file format corruption (i.e., all categories, not just +the current one, and all internal formatting are exposed and editable). +It is provided primarily as a convenience for two types of use cases +that are likely to arise infrequently. One is to be able to use +standard Emacs commands like @code{query-replace} to replace a piece of +text that occurs in different categories throughout the file. The other +use case is to recover from a mistake, such as accidentally deleting an +item, since this cannot be undone in Todo mode. + +Using @kbd{C-x C-q} to quit Todo Edit mode provides a measure of safety, +since it runs a file format check, signaling an error if the format has +become invalid. However, this check cannot tell if the number of items +changed, which could result in the file containing inconsistent +information (see the cautionary note in @ref{Reordering Categories} for +more details). For this reason @kbd{F e} should be used with caution. +@end table + +@node Category Editing, Item Editing, File Editing, Editing +@section Category Editing + +The following commands are available for editing at the category level +(for additional category-editing commands, which are extensions of item +commands, @pxref{Editing Item Headers and Text}): + +@table @kbd + +@item C a +Add a new category to the current todo file and make that category +current (@code{todo-add-category}). If called with a prefix argument, +prompt for a file name and add the new category to that file. This +command is similar to using @kbd{j}, but it only accepts category names +that are not the name of an existing category in the file. + +@item C r +Rename the current category (@code{todo-rename-category}). If this +category's file has an archive (@pxref{Todo Archive Mode}) with a +corresponding category, rename the category there as well. + +@item C m +Move the current category (with all its items) to another todo file +(@code{todo-move-category}). If this category's file has an archive +(@pxref{Todo Archive Mode}) with a corresponding category, this command +also moves that category to the archive file corresponding to the moved +to todo file; if there is no such archive file, the command creates it +and adds the category. + +@item C k +Delete the current category (@code{todo-delete-category}).@footnote{This +binding is mnenomic for ``kill'' to parallel the binding @kbd{k} for +item deletion, since @kbd{d} is bound to another item editing command +(@pxref{Done Items}).} To delete a category that contains items, you +have to confirm your intent; if the category is empty, deletion is +immediate. + +@item C g +Merge the items of one category into another category, delete the first +category and make the second category current +(@code{todo-merge-category}). If both the first and second categories +also have archived items (@pxref{Todo Archive Mode}), merge the former +to the latter. If only the first category has archived items, rename +the archive category to the merged to category. Minibuffer completion +of the name of the category merged to works as with the navigation +command @kbd{j}, and as with that command, passing a prefix argument, +i.e., typing @kbd{C-u C g}, prompts for a file and confines merging to a +category in that file. +@end table + +@node Item Editing, , Category Editing, Editing +@section Item Editing + +Todo mode provides a wide variety of commands for adding and textually +changing items, as well as for deleting and relocating items. + +@menu +* Inserting New Items:: +* Editing Item Headers and Text:: +* Relocating and Removing Items:: +@end menu + +@node Inserting New Items, Editing Item Headers and Text, , Item Editing +@subsection Inserting New Items + +There are many commands for adding new todo items. The command names +contain the word ``insert'' instead of ``add'' and their key bindings are +sequences beginning with @kbd{i}. The motivation for this terminology is +that speaking of adding an item to a category suggests appending it to +the top or bottom, whereas you can insert an item into the category +anywhere, giving each new item any priority in the list. + +@table @kbd + +@item i i +This is the basic command for inserting new items into a category +(@code{todo-insert-item}). Called without a prefix argument, it prompts +for the text of the item and its priority (a number between 1 and one +more than the number of items already in the category), both of which +you enter in the minibuffer, and inserts the item into the current +category of the current todo file at the position in the list +corresponding to the priority you chose. Called with one prefix +argument, it also prompts for a category, and called with two prefix +arguments, it prompts for both a file and a category from that file, and +inserts the item accordingly. Category name completion works as with +the navigation command @kbd{j}. +@end table + +Each invocation of @kbd{i i} adds a header string to the item, which +includes at least the current date in the same format used by +@code{diary-insert-entry} (@pxref{Date Formats,,, emacs}). You can +control what other information is included in the header by customizing +the following options: + +@itemize @bullet + +@item +@code{todo-always-add-time-string} is for including or omitting the +current time. The time string is omitted by default. + +@item +@code{todo-include-in-diary} is for specifying whether the item appears +in the Fancy Diary display by adding or omitting +@code{todo-nondiary-marker}. By default, new todo items are marked for +exclusion from the diary. + +@item +@code{todo-diary-nonmarking} is for adding or omitting +@code{diary-nonmarking-symbol} to items displayed in the diary, to +control whether they are marked in the calendar (@pxref{Format of Diary +File,,, emacs}). By default, todo items that are diary entries are +marked in the calendar. +@end itemize + +Instead of always adding the same header information to a new item, you +can use more specific insertion commands that let you decide what to +include in the item header each time you insert a new item. And instead +of always being prompted to choose the new item's priority, you can +invoke a command to insert it at the position (hence with the priority) +of the item at point. Finally, instead of always typing the text of the +new item in the minibuffer, you can invoke a command that makes the +selected region in an Emacs buffer automatically become the new item's +text. The following paragraphs discuss how to invoke these commands by +typing certain key sequences. + +There are eight parameters of item insertion in Todo mode, six +concerning the item header, and one each concerning its priority and its +text. Each unique combination of these parameters produces a different +insertion command. The command @kbd{i i} realizes one of these +combinations. For the commands that realize the remaining combinations +it is convenient to associate each parameter with a mnenomically chosen +key. Then by typing certain sequences of these keys, you complete the +insertion command invocation that realizes the specified combination. +As with @kbd{i i}, the effect of many of these commands also depends on +the values of the item insertion options mentioned above (see the +examples below). + +Here is a list of the parameters and their associated keys, in the order +in which you must type them when building a key sequence (this order +roughly reflects the order in which the corresponding parts of the item +occur in a category listing): + +@enumerate + +@item +@kbd{y} for diary (non)inclusion; +@item +@kbd{k} for adding or omitting `diary-nonmarking-symbol'; +@item +@kbd{c} for adding the date header by clicking a date in the Emacs +calendar, or@* +@kbd{d} for interactively entering the date header as a string of year, +month and day number components in the minibuffer, or@* +@kbd{n} for interactively entering the date header as a weekday name in +the minibuffer; +@item +@kbd{t} for adding a time string to the header in the minibuffer +(including the empty string, which amounts to omitting the time); +@item +@kbd{h} for inserting the new item in the position of the item at point +(``here''), or@* +@kbd{r} to use the text of the selected region as the item's text. +@end enumerate + +Each insertion command key sequence begins (disregarding prefix +arguments) with @kbd{i}, followed by one or more of these eight keys, in +the order listed. But as you can see in the above table, since some of +the insertion parameters are mutually exclusive, they occupy only five +positions, so the complete (unprefixed) sequences are maximally six keys +long. Shorter sequences are also possible, since a parameter may be +omitted. But since the order in any key sequence is fixed, if the last +key in the sequence could be followed by another insertion key, i.e., if +the last key is not @kbd{h} or @kbd{r}, it has to be doubled to complete +the sequence, otherwise it would be interpreted as a prefix sequence +(this is why the binding for the basic item insertion command is @kbd{i +i} and not @kbd{i}). + +Here are some examples of item insertion command key sequences: + +@itemize @bullet + +@item +@kbd{i h} inserts a new item at the position of the item at point (pushing +the latter down) with a header containing the current date and, +depending on the values of the mentioned options, possibly the current +time and diary-related markings. +@item +@kbd{i y h} does the same as the preceding command, except that +@code{todo-nondiary-marker} is added if @code{todo-include-in-diary} is +non-nil and omitted if that option is nil; that is, the diary key @kbd{y} +overrides the setting of this option. +@item +@kbd{i y t h} does the same as the preceding command, except that it +prompts for a time string instead of automatically inserting the +current time; however, typing @key{RET} at the prompt returns the +current time if @code{todo-always-add-time-string} is non-nil, otherwise +the empty string (i.e., no time string). +@item +@kbd{i y t t} does the same as the preceding command, except that it +prompts for the item's priority and inserts it accordingly. +@end itemize + +Note that the commands whose key sequences include @kbd{y}, @kbd{k} or @kbd{t} +reverse the effect of the options @code{todo-include-in-diary}, +@code{todo-diary-nonmarking} and @code{todo-always-add-time-string}, +respectively, thus temporarily overriding their values. + +The names of the item insertion commands correspond to their key +bindings, e.g., @kbd{i h} is bound to @code{todo-insert-item-here}, @kbd{i y h} to +@code{todo-insert-item-diary-here}, etc. But since there are so many +combinations, instead of trying to memorize either the names or the key +sequences, you can, as usual, just type an initial part of a key +sequence (minimally @kbd{i}), followed by @kbd{C-h} to see the valid +completions. + +An alternative to using the key @kbd{c} for choosing the item's date +from the calendar is also available: if point is on a date in the +calendar, typing @kbd{i t} (@code{todo-insert-item-from-calendar}) will +prompt for a new item and its priority and insert it in the current +category. Like @kbd{i i} and the other item insertion commands, this +also accepts one or two prefix arguments for choosing the category via +minibuffer completion. Note, however, that the key sequence @kbd{i t} +is not defined in Todo mode but in the Calendar mode keymap. It is a +convenient shortcut if you happen to be using the calendar when you +decide to make a new todo item. (Contrast this with a command like +@kbd{i c c}, which pops open the calendar after you have entered the +item's text, and then you can choose a date from the calendar.) + +There is one more item insertion command, which does not derive from the +item insertion parameters: + +@table @kbd + +@item i p +This command (@code{todo-copy-item}) makes a complete copy of the item +at point, including its header, prompts for its priority in the current +category and inserts it accordingly. +@end table + +@noindent +This command is useful for quickly adding a todo item whose text or +header you want to differ only partly from that of an existing item: +after inserting the copy, you can quickly edit it as needed by using +commands described in the next section. + +@node Editing Item Headers and Text, Relocating and Removing Items, Inserting New Items, Item Editing +@subsection Editing Item Headers and Text + +There are a number of commands for editing an existing item's text or +header; these commands are bound to key sequences with @kbd{e}. + +There are two commands for editing an item's text (and manually editing +its header), one appropriate for short items and simple edits and one +better suited for more complex changes or for editing lengthy items: + +@table @kbd + +@item e e +Edit the text of the current item in the minibuffer +(@code{todo-edit-item}). If called with a prefix argument (@kbd{C-u e +e}), the item's header is also included in the minibuffer and so can be +edited manually. + +@item e m +Edit the text of the current item in a special buffer in Todo Edit mode +(@code{todo-edit-multiline-item}). When you have finished editing, type +@kbd{C-x C-q} to return to Todo mode; this runs a format check to ensure +the item is well-formed.@footnote{Unlike the command @kbd{F e} +(@pxref{File Editing}), @kbd{e m} does not expose you to the risk of +putting the file in an inconsistent state, since it puts only the +current item in Todo Edit mode.} +@end table + +A number of commands are available for interactively editing all or part +of the item header, permitting quick edits and helping avoid formatting +errors. + +The following three commands are for editing any or all of the year, +month and day components of a date header: + +@table @kbd + +@item e d t +Successively prompt for changes to the date's year, month and +day number, and if the option @code{todo-always-add-time-string} is +non-nil, also for editing the time string (see also @kbd{e t} below). + +@item e d a +Change the date to today's date. + +@item e d c +This command pops up the Emacs calendar, and after you type @key{RET} on +a date in the calendar makes that date the item's date. +@end table + +@noindent +You can also use these commands on items whose date header consists of a +weekday name, which then changes to a header with year, month and day +components. + +Each of the following three commands, in contrast to the preceding +three, changes only a single date component and has no effect on a date +header consisting of a weekday name: + +@table @kbd +@item e d y +@itemx e d m +@itemx e d d +Prompt for changing just the year, month or day number, respectively; if +invoked with a positive or negative numeric prefix argument, directly +increment or decrement the date component accordingly and automatically +adjust the other date component if necessary. For example, if the date +string is ``January 1, 2013'', typing @kbd{- 3 e d d} results in +``December 29, 2012''. +@end table + +@table @kbd +@item e d n +Prompt for a weekday name and make it the item's date header. Note that +this replaces an existing date string, it does not add the day name to +the date string. + +@item e t +Edit just the item's time string. A time string can be added both to a +date string and to a weekday name. If you type @key{RET} at the +prompt, this omits a time string from the header, or deletes an existing +time string. + +@item e y y +Change the item's diary inclusion status by adding or removing +@code{todo-nondiary-marker}. + +@item e y k +Change the item's diary marking status by adding or removing +@code{diary-nonmarking-symbol} (this command has an effect only if the +item is not marked for exclusion from the diary). +@end table + +@noindent +Parallel to the latter two item-level commands are the +following category-level commands: + +@table @kbd + +@item C e y +@itemx C e k +Add @code{todo-nondiary-marker} and @code{diary-nonmarking-symbol}, +respectively, to all todo items in the current category; if invoked with +a prefix argument, these markings are removed from all items in the +category. +@end table + +@node Relocating and Removing Items, , Editing Item Headers and Text, Item Editing +@subsection Relocating and Removing Items + +In addition to inserting a new todo item and changing the text or header +of an existing item, you can also move an item to another category +(i.e., recategorize it), change its priority within its category, delete +it from the category and file, or mark it as a ``done'' item, which +removes it from the todo list but does not delete it. + +@menu +* Reprioritizing Items:: +* Moving and Deleting Items:: +* Done Items:: +@end menu + +@node Reprioritizing Items, Moving and Deleting Items, , Relocating and Removing Items +@subsubsection Reprioritizing Items + +There are three ways to change a todo item's priority: + +@table @kbd + +@item r +Raise the current item's priority by one, exchanging its position in the list +with that of the item directly above it (@code{todo-raise-item-priority}). + +@item l +Lower the current item's priority by one, exchanging its position in the list +with that of the item directly below it (@code{todo-lower-item-priority}). + +@item # +Prompt for a number and relocate the item to the corresponding position +in the list (@code{todo-set-item-priority}). For example, entering +@kbd{3} at the prompt makes the item the third in the category, i.e., +gives it third highest priority. You can also pass the desired priority +as a numeric prefix argument, e.g., @kbd{3 #} gives the item third +highest priority without prompting. (Prefix arguments have no effect +with @kbd{r} or @kbd{l}.) +@end table + +@node Moving and Deleting Items, Done Items, Reprioritizing Items, Relocating and Removing Items +@subsubsection Moving and Deleting Items + +You can move an item to another category, thereby recategorizing it: + +@table @kbd + +@item m +Move the item at point to another category (@code{todo-move-item}). +This prompts for a category to move the item to, displays that category, +prompts for the priority of the moved item in the category moved to and +inserts the item accordingly. Minibuffer completion of the name of the +category moved to works as with the navigation command @kbd{j}, and as +with that command, passing a prefix argument prompts for a file and +moves the item to a category in that file; and if the category name you +enter is new, then you are asked whether to add the category to the +file, and if you affirm, the item is moved to the new category. +@end table + +You delete an item, thereby permanently removing it: + +@table @kbd + +@item k +Delete the todo item at point (@code{todo-delete-item}; the binding is +mnenomic for ``kill'', since @kbd{d} is used for marking items as done +(@pxref{Done Items}); but note that @kbd{k} does not put the item into +the kill ring). This command requires confirmation that you want to +delete the item, since you cannot undo the deletion in Todo mode. (You +could use @kbd{F e} to recover the item, but be aware that this would +put the file in an inconsistent state, which you can recover from, but +not without a risk; cf.@: the cautionary note in @ref{Reordering +Categories}.) +@end table + +@quotation Note +Todo commands that require user confirmation, such as @kbd{k}, use a +modified form of @code{y-or-n-p}, which by default only accepts @kbd{y} +or @kbd{Y}, but not @key{SPC}, as an affirmative answer. This is to +diminish the risk of unintentionally executing the command, which is +especially important with commands that do deletion, since there is no +Todo command to undo a deletion. If you want to be able to use SPC for +confirmation, enable the option @code{todo-y-with-space}. +@end quotation + +@node Done Items, , Moving and Deleting Items, Relocating and Removing Items +@subsubsection Done Items + +When the activity or thing that a todo item is about has been done, it +is natural to eliminate the item from the todo list. But instead of +deleting it permanently, you may prefer to keep a record of your +accomplishments by marking the item as done. In Todo mode, this removes +the done item from the todo list, so as not to clutter it up, and stores +it elsewhere. Such stored items form a record or diary of things done. +The Todo package provides two such stores: the ``done items'' section of +a Todo category, described here, and done item archives (@pxref{Todo +Archive Mode}). + +@table @kbd + +@item d +This command (@code{todo-item-done}) removes the todo item at point from +the todo list, appends to the original header a header consisting of +@code{todo-done-string} (by default ``DONE '') and the current date, and +if @code{todo-always-add-time-string} is enabled, also the current time, +and adds the resulting done item to the top of the done items section of +the category. Invoked with a prefix argument, it also prompts you to +enter a comment, which is appended to the end of the done item, prefixed +with @code{todo-comment-string} (by default ``COMMENT: ''). +@end table + +A category's done items section is located below the last todo (i.e., +not done) item in the category. By default this section is hidden from +view. There are two commands for viewing and hiding done items; since +these are toggle commands, for convenience they also have a single key +binding: + +@table @kbd + +@item C v +@itemx v +Make the done items section of the current category visible if it is +hidden, or hide it if it is visible +(@code{todo-toggle-view-done-items}). If you always want to see the +done items section on entering a category, enable the option +@code{todo-show-with-done}; you can still use @kbd{C v} or @kbd{v} to +hide (and unhide) it. + +@item F V +@itemx V +Toggle the standard category display in the current todo file, i.e., +display only the done items section of each category in the file, or if +this is visible, hide it again and display only the todo items section +(@code{todo-toggle-view-done-only}). +@end table + +Three editing commands for done items are available: + +@table @kbd + +@item e c +If you type this command (@code{todo-edit-done-item-comment}) when point is +on a done item that has a comment, you can edit the text of the +comment. If you invoke it with a prefix argument (@kbd{C-u e c}), the +comment is deleted on confirmation. If the done item does not have a +comment, this command allows you to add one. + +@item m +Move the done item at point to the top of the done items section of +another category (@code{todo-move-item}). This is useful in case, after +having relocated an item to its category's done items section, you +create a category that is better suited to the content of the done item +than its current category, so you can recategorize the done item. + +@item u +If you decide the done item at point is not done after all, this command +``undoes'' it, i.e., restores it to the todo list of its category, with +the priority you choose for it (@code{todo-item-undone}). If the done +item has a comment, you are asked whether to delete it from the restored +item. +@end table + +@node Todo Archives, Marked Items, Editing, Top +@chapter Todo Archives + +When the done items section of a category itself starts to become +cluttered, or if you just want to store some accomplished todo items in +a separate file, you can move them to a Todo archive. This is a file +with exactly the same structure as a todo file, i.e., divided into +categories, but differs in that the categories contain only done items. +Todo archives reside, like todo files, in @code{todo-directory} but have +the extension @samp{.toda} instead of @samp{.todo}. + +@menu +* Creating and Visiting Archives:: +* Todo Archive Mode:: +@end menu + +@node Creating and Visiting Archives, Todo Archive Mode, , Todo Archives +@section Creating and Visiting Archives + +Todo mode provides the following command for archiving items: + +@table @kbd + +@item A d +This command (@code{todo-archive-done-item}) archives the done item at point. +Invoked with a prefix argument, it archives all done items in the +current todo category. If an archive for the current todo file +already exists and contains a category with the same name as the +current todo category, then this command moves the done item to the +top of the corresponding archive category. If the archive exists but +it does not have a corresponding category, this command creates the +category in the archive and moves the done item to it. If no archive +for the todo file exists, the command creates both the archive file, +using the same base name as that of the todo file, as well as the +category, and moves the done item to it. +@end table + +Typing @kbd{A d} is also the only way within the Todo mode package to +create an archive file and its categories. Consequently, as a rule each +archive file corresponds to exactly one todo file and has the same base +name as this file, and each category in an archive file corresponds to +and has the same name as a category in the corresponding todo file. +Exceptions can only arise if you delete a todo file but not the +corresponding archive, or if you delete a category in a todo file that +has a corresponding category in an archive. + +You might be inclined to do the latter if you have archived all the +items from a given todo category and you don't plan to add new items to +it. In particular, if you have numerous such empty categories in a todo +file, this can make sequential navigation in the file annoying. You can +avoid this annoyance by deleting these categories, but only at the cost +of putting the todo file out of synch with the archive file. + +You may find it preferable not to delete empty todo categories but to +enable the option @code{todo-skip-archived-categories}. When this is +non-nil, such empty todo categories are skipped over by the sequential +category navigation commands @kbd{f} and @kbd{b}, so they don't distract you +while navigating and you maintain the structural correspondence between +todo and archive files (you can also still jump to empty todo categories +with @kbd{j}). + +If you rename a todo category that has a corresponding category in an +archive, the archive category is also automatically identically renamed. +Likewise, if you move such a todo category to another file; in this +case, if there is no archive file corresponding to the todo file the +category is moved to, then the archive is automatically created and the +archived category is moved to it. + +There are two commands in Todo mode for visiting archive files: + +@table @kbd + +@item A f +Switch to a buffer displaying the archived category corresponding to the +current todo category (@code{todo-find-archive}). If the todo category +has no archived items, the command asks if you want to visit the archive +anyway. If there is no archive for this todo file, it asks if you want +to visit another archive, which you can select via minibuffer +completion. + +@item A c +Choose an archive to visit, whether or not the current todo file has an +archive (@code{todo-choose-archive}). +@end table + +As with todo files, you can also visit a Todo archive by invoking a +standard Emacs file-visiting command; this displays the first (on the +initial invocation) or current category of the archive. + +@node Todo Archive Mode, , Creating and Visiting Archives, Todo Archives +@section Todo Archive Mode + +When you visit a Todo archive, the buffer is in Todo Archive mode. It +displays categories just as in Todo mode, except that they only contain +done items. It provides the same sequential navigation commands as +Todo mode: @kbd{f} and @kbd{b} navigate between the categories of the current +archive, and @kbd{n} and @kbd{p} navigate between the done items of the current +archive category. + +The commands @kbd{t} and @kbd{j} are also available in Todo Archive +mode, and they work the same as in Todo mode, which means they can only +be used to return to Todo mode: @kbd{t} prompt for and switch to a todo +file, and with @kbd{j} you can only jump to a todo category. These +commands exclude archives because an archive file has the same base name +as the corresponding todo file, and category name completion uses only +the base names, so the commands cannot know which type of file you want +to visit. For this reason, there is a special command in Todo Archive +mode for jumping to another archive category or visiting another archive +file: + +@table @kbd + +@item a +This command (@code{todo-jump-to-archive-category}) prompts for a category in the +current archive and jumps to it. Called with a prefix argument, it +prompts for another archive, then for a category in it and jumps to +that category. +@end table + +None of the Todo mode editing commands are available in Todo Archive +mode, since archives are meant to be static records of accomplished todo +items. Should you, however, archive an item by mistake or simply change +your mind about the archival status of an item, you can ``unarchive'' it: + +@table @kbd + +@item u +Restore the done item at point to the top of the done items section of +the corresponding category in the corresponding todo file, i.e., an +unarchived item remains a done item (@code{todo-unarchive-items}). When +the last item in an archive category has been unarchived, the category +is automatically deleted from the archive. If this was the only +category in the archive, the archive file is also automatically deleted. +@end table + +Since it is natural to visit an archive from the corresponding todo +file, it would be convenient to easily return to the todo file when you +have finished browsing the archive. If you type `q' to quit Todo +Archive mode, this switches to the corresponding todo file and shows the +todo category corresponding to the archive category you were just +visiting. + +The command @kbd{F k} (@pxref{File Editing}) is also available in Todo +Archive mode. It deletes the current archive file and prompts you +whether to delete the corresponding todo file. + +@node Marked Items, Todo Categories Mode, Todo Archives, Top +@chapter Marked Items + +For many item editing commands it can make sense and be convenient to +apply them simultaneously to more than one item in the current category. +Todo facilitates this by means of marked items. + +@table @kbd + +@item * +Mark the item at point if it is unmarked, and remove the mark it is +already marked (@code{todo-toggle-mark-item}). The mark is a string +specified by the option @code{todo-item-mark} (by default @samp{*}) +appended in front of the item header (more precisely, in front of the +item's priority number or prefix; @pxref{Todo Display Features} for +details of the latter). After marking the current item, the command +advances point to the next item. It also accepts a numeric prefix +argument, which allows toggling the mark of multiple consecutive items. + +@item C * +Mark all todo items in the current category. + +@item C u +Unmark all todo item in the current category. +@end table + +You can also use the last two commands to mark or unmark all done items in +the category, but only when only the done items section is being +displayed, i.e., after invoking @kbd{C V} or @kbd{V}. + +The following commands operate on marked items: @kbd{k} (deleting), @kbd{m} +(moving to another category), @kbd{d} (moving to the done items section; +note that @kbd{C-u d} adds the same comment to all marked items), @kbd{A d} +(archiving), @kbd{u} (both in Todo mode for undoing a done item and in +Todo Archive mode for unarchiving an item), as well as the commands for +editing the item header (those beginning with the prefix @kbd{e d} as well +as @kbd{e t}, @kbd{e y y} and @kbd{e y k}). The item insertion, textual editing and +priority changing commands do not operate on marked items. + +If you use @kbd{m}, @kbd{d}, @kbd{A d} or @kbd{u} on multiple noncontiguous marked +items, the relocated items retain their relative order but are now +listed consecutively en bloc. + +You can mark both todo and done items, but note that only @kbd{m} can apply +to both; other commands only affect either marked todo or marked done +items, so if both types of items are marked, invoking these commmands +has no effect and informs you of your erroneous attempt. + +@node Todo Categories Mode, Searching for Items, Marked Items, Top +@chapter Todo Categories Mode + +It can be helpful to have a compact overview of the categories in a todo +file and the types of items it contains; Todo provides a tabular view +of this information. + +@table @kbd + +@item F c +Typing this command (@code{todo-show-categories-table}) in Todo mode or Todo +Archive mode switches to a buffer displaying a table that gives an +overview of the categories in the current todo or archive file. This +buffer is in Todo Categories mode. +@end table + +The table consists of a column containing the names of the categories in +the file, followed by columns containing counts of certain types of +items in each category. With todo files there are four count types: all +todo (i.e., not done) items, diary items (i.e., those todo items lacking +the @code{todo-nondiary-marker}, which hence can appear in the Fancy Diary +display), done (but not archived) items, and archived items. With +archive files all items are done, so the table only has a column for +this count. The final row of the table gives total item counts across +all categories in the file. + +Aside from explicitly invoking @kbd{F c} to display the table of +categories, you can also arrange to have it displayed on the first +invocation of @code{todo-show} for a given file (i.e., either using +@code{todo-show} to initiate a Todo session, or calling it in Todo mode +to visit another todo file). To do this customize the option +@code{todo-show-first}. + +@menu +* Table of Item Counts:: +* Reordering Categories:: +@end menu + +@node Table of Item Counts, Reordering Categories, , Todo Categories Mode +@section Table of Item Counts + +Above each column of the table is a labelled button you can press by +clicking with the mouse or by typing @key{RET} on it. Pressing an item +count button sorts the table alternately in ascending or descending +order according to the type of count. Pressing the category button +alternates between the initial numerical order of the categories and +alphabetical order. In numerical order the column of category names is +preceded by a column containing the corresponding category numbers; this +column is not displayed in the alphabetical listing. Instead of +pressing the buttons, you can also sort the table by typing the +following keys: + +@itemize + +@item @kbd{c} +to sort by category numerically or alphabetically; +@item @kbd{t} +to sort by todo item counts; +@item @kbd{y} +to sort by diary item counts; +@item @kbd{d} +to sort by done item counts; +@item @kbd{a} +to sort by archived item counts. +@end itemize + +Each row of the table is also buttonized; pressing one of these exits +the buffer (killing it), returns to the buffer of the file from which +you had invoked `F c', and displays the category that was named in the +row button you pressed (i.e., pressing this button jumps to that +category). However, if the category named in the row is in a todo file +and all of its items have been archived, and you have enabled the option +@code{todo-skip-archived-categories}, then pressing the button jumps to +the archive category instead of the empty todo category. You can +recognize such categories by their items counts in the table---all +columns but the archived one have counts of zero---and in addition, +their lines in the table are also distinguished from the others by a +different face. + +You can navigate around the table: + +@table @kbd + +@item n +@itemx @key{TAB} +Advance point to the next button. + +@item p +@itemx S-@key{TAB} +Put point on the previous button. +@end table + +These commands are cyclic, e.g. when point is on the last button, +pressing @kbd{n} moves it to the first button. + +Typing @kbd{q} exits Todo Categories mode, killing the buffer and returning +to the current category in the Todo mode or Todo Archive mode buffer +from which you had invoked @kbd{F c}. + +@node Reordering Categories, , Table of Item Counts, Todo Categories Mode +@section Reordering Categories + +Todo Categories mode provide commands with which you can change the +numbering of the categories in the current file. This renumbering has +the effect of reordering the categories for sequential navigation by +@kbd{f} and @kbd{b} in Todo mode and Todo Archive mode. These commands +are only operative when the table displays the categories in their +numerical order. They work just like reprioritizing items in Todo mode, +hence have the same key bindings: + +@table @kbd + +@item r +Raise the current line of the table (the one the cursor is on), +decreasing the category's number by one (@code{todo-raise-category}). +This command exchanges lines, and hence the numbers, of the category at +point and the one above it before invoking the command. + +@item l +Lower the current line of the table, increasing the category's number by +one (@code{todo-lower-category}). This command exchanges lines, and +hence the numbers, of the category at point and the one below it before +invoking the command. + +@item # +Prompt for a number between 1 and the number of categories in the file +and reorder the table accordingly (@code{todo-set-category-number}). If +called with a numeric prefix argument within the allowed range, reorder +the table without prompting. +@end table + +The reordering done by these commands remains in effect when you return +to Todo mode or Todo Archive mode and, as long as you save the todo +or archive file after reordering, in subsequent sessions as well. + +@quotation @strong{Caution} +It is important to be aware that renumbering the categories does not +change the textual order of the categories in the file. This is +significant if you should invoke @kbd{F e} to edit the entire file +manually and in so doing alter the number of items in a category: this +will make the item count shown in the table of categories of this file +inconsistent with the actual number. You can repair this inconsistency +by invoking the command @code{todo-repair-categories-sexp} (which lacks +a key binding, since it is meant to be a rarely needed rescue +operation). But this will revert any renumbering of the categories you +have made, so you will have to renumber them again. This is the reason +why you should exercise caution when using @kbd{F e}. +@end quotation + +@node Searching for Items, Todo Filtered Items Mode, Todo Categories Mode, Top +@chapter Searching for Items + +It can be useful to be able to locate and examine all todo items that +fit certain criteria, regardless of which category they belong to. One +way to do this in Todo mode is by sequentially searching in the file: + +@table @kbd + +@item S +This command (@code{todo-search}; the key is capital `S') prompts for a +regular expression, searches from the beginning of the current todo file +and displays the category containing the first match it finds, with the +match highlighted. If there are further matches, a message saying how +many are left is displayed and you are asked if you want to go to the +next match. When you reach the last match, or if you decide not to go +to further matches, you are asked whether the match highlighting should +be removed. + +@item X +This command (@code{todo-clear-matches}) removes any highlighting added by @kbd{S}. +This is so you can leave the matches highlighted at the end of the +search and remove the highlighting later. +@end table + +These commands are also available in Todo Archive mode. + +@node Todo Filtered Items Mode, Todo Display Features, Searching for Items, Top +@chapter Todo Filtered Items Mode + +A more powerful alternative to sequential searching is item filtering, +by which items from different categories that match specified criteria +are gathered and displayed in a new buffer as a kind of virtual +category in a distinct mode, Todo Filtered Items mode. + +@menu +* Filtering Items:: +* Todo Filtered Items Mode Commands:: +* Files of Filtered Items:: +@end menu + +@node Filtering Items, Todo Filtered Items Mode Commands, , Todo Filtered Items Mode +@section Filtering Items + +Todo mode provides three ways to filter items: a general filter for +items matching a user-entered regular expression, as with the search +command; and two specific filters, one for diary-displayable items +(i.e., those lacking @code{todo-nondiary-marker}) and one for top +priority items (more on the latter below). The commands for each +filter come in pairs, one for filtering just the current todo file and +one for filtering a user-specified list of todo files. Thus, there +are six item filtering commands:@footnote{The use of @kbd{F} in the key +sequences of these commands naturally recalls ``filter'', but is also +consistent with the Todo mode mnenomic key binding convention, since the +commands involve one or more whole files.} + +@itemize @bullet + +@item +@kbd{F x x} (@code{todo-filter-regexp-items}) +@item +@kbd{F x m} (@code{todo-filter-regexp-items-multifile}) +@item +@kbd{F y y} (@code{todo-filter-diary-items}) +@item +@kbd{F y m} (@code{todo-filter-diary-items-multifile}) +@item +@kbd{F t t} (@code{todo-filter-top-priorities}) +@item +@kbd{F t m} (@code{todo-filter-top-priorities-multifile}) +@end itemize + +There are two ways to specify which files the multifile filtering +commands apply to. If there are files you want to filter every time you +use these commands, customize the option @code{todo-filter-files}. If you +leave this option empty (the default), invoking a multifile filtering +command pops up a buffer similar to the Customization buffer for +@code{todo-filter-files}, in which you can select files to filter just for +this invocation. + +Diary and top priority items are by definition non-done todo items, but +when filtering by regular expression, you can extend the scope of the +command to done items by enabling the option @code{todo-filter-done-items}. +Then @kbd{F x x} and @kbd{F x m} will gather both matching todo and matching +done items (including done items from any archive files corresponding to +the selected todo files) into the virtual category of filtered items. + +There are several ways to specify how many items in each category count +as top priorities and hence get filtered by @kbd{F t t} and @kbd{F t m}: + +@itemize @bullet + +@item +The option @code{todo-top-priorities} specifies a single default number +for all categories and all todo files; its default value is 1, which +means just the highest priority item in every category is filtered, +unless otherwise specified. +@item +The option @code{todo-top-priorities-overrides} lists file-wide overrides +of @code{todo-top-priorities} as well as category-specific overrides. It +is empty by default. However, using the Custom facility to set this +option would be tedious and error-prone, so instead you should use the +commands @kbd{F t s} and @kbd{C t s}. The former sets (i.e., overrides) the +default number of top priorities for all categories in the current +todo file, and the latter sets the number of top priorities for the +current category. To exclude a category or file from filtering by @kbd{F t t} +and @kbd{F t m}, set the number to @samp{0}. +@item +You can invoke `F t t' and `F t m' with a numeric prefix argument, +which specifies the number of top priorities in each category just for +this invocation, overriding both @code{todo-top-priorities-overrides} and +@code{todo-top-priorities}. +@end itemize + +@node Todo Filtered Items Mode Commands, Files of Filtered Items, Filtering Items, Todo Filtered Items Mode +@section Todo Filtered Items Mode Commands + +The output of the item filtering commands looks similar to a regular +Todo category, but it is not contained in any todo file and does not +have a name on being created, so it is not a ``real'' category but a +``virtual'' category. Another difference is the lack of a done items +section; either there are no done items in the list (when the filtered +items are diary or top priority items), or these are displayed in the +same list as todo items (if you filtered by regular expression and +allowed done items). A further difference is that the items have an +additional header, between the item's date/time header and its text, +specifying which category (and if you invoked a multifile command, also +which file) the item comes from, and if you filtered by regular +expression, also whether the item comes from a Todo archive. + +The sequential item navigation commands @kbd{n} and @kbd{p} work the same in +Todo Filtered Items mode as in Todo mode, as do the file and category +jumping commands @kbd{t} and @kbd{j}; however, the sequential category +navigation commands are unavailable, since virtual categories of +filtered items are not ordered with respect to ``real'' categories. In +addition, Todo Filtered Items mode provides a special navigation +command: + +@table @kbd + +@item g +@itemx @key{RET} +If you type this command (@code{todo-go-to-source-item}) with point on a +filtered item, the buffer switches to the item's source file (in Todo +mode or Todo Archive mode, as the case may be) and displays its +category, with point on the item. +@end table + +Filtered items cannot be textually edited, moved to another category, +marked done or archived like items in a real todo category, since these +would then be out of synch with each other. But there is one type of +editing command that does work in Todo Filtered Items mode: changing an +item's priority: + +@table @kbd + +@item r +@itemx l +@itemx # +These commands raise, lower, or set, respectively, the current item's +priority in the virtual category. +@end table + +@noindent +Using these commands, you can create a cross-category (and even +cross-file) prioritized list of filtered items. However, there is a +restriction on these commands in Todo Filtered Items mode: you cannot +change the relative priorities of items from the same real category, +since that would make the filtered list inconsistent with the source +todo list. + +@node Files of Filtered Items, , Todo Filtered Items Mode Commands, Todo Filtered Items Mode +@section Files of Filtered Items + +Typing @kbd{s} in Todo Filtered Items mode saves the buffer of filtered +items to a file in @code{todo-directory}. Files of items filtered by +regular expression have the extension @samp{.todr}, those with filtered +diary items have the extension @samp{.tody} and those with filtered top +priorities have the extension @samp{.todt}. The extensions are added +automatically the first time you save the buffer to a file. + +With filtered top priority or diary items, the file is automatically +named on first saving it, using as the base name either the same base +name as the single todo file it was generated from, or combining the +base names of the todo files used in multifile filtering commands. +With items filtered by regular expression, it can be useful to save +separate lists generated from the same file(s) using different regular +expressions, so when saving such a list, you are prompted for a short +identifying string to add to the file name. + +When you invoke one of the item filtering commands without a prefix +argument and a corresponding file already exists, the command visits +this file (if, for the current file or chosen files, there are multiple +files of items filtered by regular expression, you are prompted to +choose one). To force generation of a new filtered list, invoke the +command with a prefix argument (in the case of top priority items, +either numeric as described above, or the raw prefix argument @kbd{C-u} to +use the values of @code{todo-top-priorities-overrides} or +@code{todo-top-priorities}). + +Aside from explicitly invoking an item filtering command to display a +saved list of items filtered by a given method from given todo files, +there are two other ways to visit a saved file of filtered items: + +@table @kbd +@item F f +Visit a saved file of filtered items, which you choose via minibuffer +completion (@code{todo-find-filtered-items-file}). +@end table + +@itemize @bullet +@item +As with tables of categories, by customizing @code{todo-show-first} you +can have the first invocation of @code{todo-show} for a given todo file +display the corresponding saved file of filtered items. If there is +no saved filtered items list for the file, @code{todo-show} simply +defaults to visiting the file and displaying its first category, as +usual. +@end itemize + +The command @kbd{F k} (@pxref{File Editing}) is also available in Todo +Filtered Items mode. It deletes the current filtered items file. + +@node Todo Display Features, Printing Todo Buffers, Todo Filtered Items Mode, Top +@chapter Todo Display Features + +You can change the appearance of Todo mode buffers in a variety of ways. + +@menu +* Faces:: +* Item Prefix:: +* Other Display Commands and Options:: +@end menu + +@node Faces, Item Prefix, , Todo Display Features +@section Faces + +Each of the Todo modes uses faces to distinguish various aspects of the +display, both structural and informational. For example, the faces for +the date and time strings of todo item headers by default inherit the +attributes of the corresponding faces used by the Emacs diary; but when +the date and time of a Todo diary item (i.e., an item lacking +@code{todo-nondiary-marker}) is earlier than the current date and time, +they are displayed in a different face. In this way, you can readily +recognize diary items that have ``expired'' and act accordingly (e.g., +by tagging them as done or by updating the deadlines). + +Another example of an informational face is the face used to distinguish +top priority items. A third case is the face used in Todo Categories +mode to mark rows of the table containing categories with only archived +items. + +The @code{todo-faces} customization group contains a complete list of +Todo mode faces and brief descriptions of their use. + + +@node Item Prefix, Other Display Commands and Options, Faces, Todo Display Features +@section Item Prefix + +In the default display of (real or virtual) categories in Todo mode, +Todo Archive mode and Todo Filtered Item mode the items are visually +numbered in ascending order, starting with @samp{1} on the top item, +displayed to the left of its header (date/time string). With todo items +the numbers indicate each item's priority in the list, so when you +reprioritize an item with @kbd{#} or move it with @kbd{m}, these numbers make +it easier to choose the item's new priority. The numbering also lets +you to see at a glance how many items there are in the list. When an +item is inserted, deleted, or moved, the numbering is automatically +updated. In Todo mode, the todo and done items sections in each +category are separately numbered. + +If you prefer not to have item numbering displayed, disable the option +@code{todo-number-prefix}; then the display of each item starts by default +simply with its header. But you can also replace the numbering with a +visually distinctive string of your choice by customizing the option +@code{todo-prefix} (the empty string by default). Another alternative is to +temporarily hide the item numbering: + +@table @kbd + +@item F N +@itemx N +Toggle between displaying item numbering and displaying the +@code{todo-prefix} string in the current Todo file (todo, archive, or +saved virtual category of filtered items. This command also works in +buffers of filtered items that have not yet been written to a file.) +@end table + +In the todo items section of each Todo mode category, the item prefix +(whether a priority number or a fixed string) of the top priority items +(determined as specified in @ref{Filtering Items}) is displayed in a +different face from the prefix of the other items, so you see at a +glance how many items in the category are top priorities. + +@node Other Display Commands and Options, , Item Prefix, Todo Display Features +@section Other Display Commands and Options + +There are two additional toggle commands that affect display in the +current file: + +@table @kbd + +@item F h +@itemx h +Hide the item headers if visible, or show them if they are hidden. +With done items, only the done header (i.e. the done tag and date-time +string inserted when the item was marked done) is hidden, the original +date-time string is not. With filtered items, the category (or +category-file) tag is not hidden. + +@item F H +@itemx H +Highlight the current item if unhighlighted, or remove its highlighting. +When item highlighting is enabled, it follows navigation by @kbd{n} or +@kbd{p}. If you want to have current item highlighting by default, +enable the option @code{todo-highlight-item}. @kbd{F H} or @kbd{H} will +still toggle it. +@end table + +There are two options which affect the display of items whose content is +longer than one screen line: + +@itemize @bullet{} + +@item +@code{todo-indent-to-here} sets the amount of indentation for all lines +after the first in multiline todo items, which is necessary in order +for todo diary items to be fully visible in the Fancy Diary display. +The default indentation is 3 spaces. For a uniform appearance this +option applies to all items, i.e., diary and nondiary todo items and +also done items. + +@item +@code{todo-wrap-lines} allows you to choose, for the purposes of +insertion and editing, between treating multiline todo items as +containing multiple logical lines with hard line breaks or as multiple +visual lines using Visual Line mode; the latter is the default. Since +multiparagraph items also contain hard line breaks in Visual Line mode, +for a uniform appearance this display shows indentation on wrapped lines +by using a wrap-prefix of @code{todo-indent-to-here} spaces. +@end itemize + +The indentation inserted after a hard newline is actually a tab +character, and the Todo modes that display items bind @code{tab-width} to +@code{todo-indent-to-here}, so if you change the default value of the +latter, the next time you visit a Todo file, the indentation will +reflect your change. + +By default, the todo and done items sections of a todo category are +visually separated by a line as wide as the window the buffer is +displayed in. You can change the appearance and width of the separator +by customizing @code{todo-done-separator-string}; you can also change the +face of the separator string. + +There are also several options for changing the appearance in Todo +Categories mode and Todo Filtered Items mode, beyond those mentioned +above in the sections on these modes; see the customization groups +@code{todo-categories} and @code{todo-filtered} for details. + +@node Printing Todo Buffers, Legacy Todo Mode Files, Todo Display Features, Top +@chapter Printing Todo Buffers + +If you print a Todo buffer using one of the standard Emacs printing +commands, it does not look exactly like what you see in the buffer. +This is because some of the display features are non-printable +(specifically, those using overlays, word-wrap and wrap-prefix). Todo +mode provides two print commands that produce output which includes +printable counterparts of such display features: + +@table @kbd + +@item P B +Send the printable buffer output directly to your printer. + +@item P F +Prompt for a file name and write the printable output to that file. +@end table + +By default, Todo uses @code{ps-print-buffer-with-faces} to make the +printable version; you can change this by setting the option +@code{todo-print-function}. + +@node Legacy Todo Mode Files, GNU Free Documentation License, Printing Todo Buffers, Top +@chapter Legacy Todo Mode Files + +Users of the original version of Todo mode will recognize from the +description in this user manual that, although the new version shares +with the original version the same basic user interface and handling of +todo items, there are some incompatible differences between them, such +as the done items sections (there are also other file format +incompatibilities behind the scenes that are normally not visible to +users). + +The most significant incompatibility concerns the item prefix. In the +earlier version of Todo mode the prefix was the initial part of the item +string itself, so in order for the item to be displayable in the Emacs +diary, the prefix had to be a date/time pattern recognizable by the +diary (although the todo item also has its own date/time header). +Moreover, since all items had the same prefix string in the original +version, this means that either only all or no items could appear in the +Fancy Diary display on any given date. This considerably restricts the +practicality of including todo items in the diary. In contrast, the +current version of Todo mode uses overlays for item priority numbering +or prefixes, and item-specific diary-compatible date/time headers and +special marks for todo items to be excluded from the diary, so you can +determine for each item whether and when it appears in the Fancy Diary +display. + +Due to these incompatibilities, files created with the original version +of Todo mode cannot be displayed or edited with the current version. +However, this version provides a function that converts the two main +types of files used by the original version into new-style valid todo +and archive files, respectively, and saves them in +@code{todo-directory}.@footnote{The original version of Todo mode also +allowed saving a file of top priority items, but since you can readily +create such a file with the new version, which is also more flexible, +no conversion is provided for this file.} + +This conversion function is automatically called the first time you +invoke @code{todo-show} (i.e., before you have created a todo file with +the new version), and if it finds the old-style files, it offers to +convert them, making them the first new-style todo and archive files. +If you choose not to convert the old-style files at this time, you can +do so later by invoking the command @code{todo-convert-legacy-files} +(there is no key binding for it, since it shouldn't be necessary to use +it often). (A delicate part of the conversion concerns the customizable +format of item date/time headers in the old-style; see the documentation +string of @code{todo-todo-mode-date-time-regexp} for details.) + +@node GNU Free Documentation License, , Legacy Todo Mode Files, Top +@appendix GNU Free Documentation License +@include doclicense.texi + +@bye + +@c End: diff --git a/info/dir b/info/dir index cecc0d00f47..b6ec2845c3d 100644 --- a/info/dir +++ b/info/dir @@ -36,7 +36,7 @@ Emacs editing modes Java, Pike, AWK, and CORBA IDL code. * IDLWAVE: (idlwave). Major mode and shell for IDL files. * nXML Mode: (nxml-mode). XML editing mode with RELAX NG support. -* Org Mode: (org). Outline-based notes management and organizer +* Org Mode: (org). Outline-based notes management and organizer. Emacs network features * EUDC: (eudc). Emacs client for directory servers (LDAP, PH). @@ -86,6 +86,7 @@ Emacs misc features * Wisent: (wisent). Semantic Wisent parser development. * SES: (ses). Simple Emacs Spreadsheet. * Speedbar: (speedbar). File/Tag summarizing utility. +* Todo Mode: (todo-mode). Make and maintain todo lists. * VIP: (vip). An older VI-emulation for Emacs. * VIPER: (viper). A VI-emulation mode for Emacs. * WoMan: (woman). Browse UN*X Manual Pages "W.O. (without) Man".