File: otodo-mode.el.html

Mode Description

TODO is a major mode for EMACS which offers functionality to treat most lines in one buffer as a list of items one has to do. There are facilities to add new items, which are categorized, to edit or even delete items from the buffer. The buffer contents are currently compatible with the diary, so that the list of todo-items will show up in the FANCY diary mode.

Notice: Besides the major mode, this file also exports the function todo-show which will change to the one specific TODO file that has been specified in the todo-file-do variable. If this file does not conform to the TODO mode conventions, the todo-show function will add the appropriate header and footer. I don't anticipate this to cause much grief, but be warned, in case you attempt to read a plain text file.

 Preface, Quickstart Installation

     To get this to work, make Emacs execute the line

         (autoload 'todo-mode "todo-mode"
                   "Major mode for editing TODO lists." t)
         (autoload 'todo-show "todo-mode"
                   "Show TODO items." t)
         (autoload 'todo-insert-item "todo-mode"
                   "Add TODO item." t)

     You may now enter new items by typing "M-x todo-insert-item",
     or enter your TODO list file by typing "M-x todo-show".

     The TODO list file has a special format and some auxiliary
     information, which will be added by the todo-show function if
     it attempts to visit an un-initialized file. Hence it is
     recommended to use the todo-show function for the first time,
     in order to initialize the file, but it is not necessary
     afterwards.

     As these commands are quite long to type, I would recommend
     the addition of two bindings to your to your global keymap. I
     personally have the following in my initialization file:

         (global-set-key "\\C-ct" 'todo-show) ; switch to TODO buffer
    (global-set-key "\\C-ci" 'todo-insert-item) ; insert new item

     Note, however, that this recommendation has prompted some
     criticism, since the keys C-c LETTER are reserved for user
     functions. I believe my recommendation is acceptable, since
     the Emacs Lisp Manual *Tips* section also details that the
     mode itself should not bind any functions to those keys. The
     express aim of the above two bindings is to work outside the
     mode, which doesn't need the show function and offers a
     different binding for the insert function. They serve as
     shortcuts and are not even needed (since the TODO mode will be
     entered by visiting the TODO file, and later by switching to
     its buffer).

     If you are an advanced user of this package, please consult
     the whole source code for autoloads, because there are several
     extensions that are not explicitly listed in the above quick
     installation.

 Pre-Requisites

     This package will require the following packages to be
     available on the load-path:

         time-stamp
         easymenu

 Operation

You will have the following facilities available:

    M-x todo-show will enter the todo list screen, here type

    + to go to next category
         - to go to previous category
         d to file the current entry, including a
                                    comment and timestamp
         e to edit the current entry
         E to edit a multi-line entry
         f to file the current entry, including a
                                    comment and timestamp
         i to insert a new entry, with prefix, omit category
         I to insert a new entry at current cursor position
    j jump to category
         k to kill the current entry
         l to lower the current entry's priority
         n for the next entry
         p for the previous entry
    P print
         q to save the list and exit the buffer
         r to raise the current entry's priority
         s to save the list
         S to save the list of top priorities
    t show top priority items for each category

When you add a new entry, you are asked for the text and then for the category. I for example have categories for things that I want to do in the office (like mail my mum), that I want to do in town (like buy cornflakes) and things I want to do at home (move my suitcases). The categories can be selected with the cursor keys and if you type in the name of a category which didn't exist before, an empty category of the desired name will be added and filled with the new entry.

 Configuration

 Variable todo-prefix

I would like to recommend that you use the prefix "*/*" (by leaving the variable 'todo-prefix' untouched) so that the diary displays each entry every day.

To understand what I mean, please read the documentation that goes with the calendar since that will tell you how you can set up the fancy diary display and use the #include command to include your todo list file as part of your diary.

If you have the diary package set up to usually display more than one day's entries at once, consider using

    "&%%(equal (calendar-current-date) date)"

as the value of todo-prefix. Please note that this may slow down the processing of your diary file some.

     Carsten Dominik <dominik@strw.LeidenUniv.nl> suggested that

         "&%%(todo-cp)"

     might be nicer and to that effect a function has been declared
     further down in the code. You may wish to auto-load this.

     Carsten also writes that *changing* the prefix after the
     todo list is already established is not as simple as changing
     the variable - the todo files have to be changed by hand.

 Variable todo-file-do

This variable is fairly self-explanatory. You have to store your TODO list somewhere. This variable tells the package where to go and find this file.

 Variable todo-file-done

Even when you're done, you may wish to retain the entries. Given that they're timestamped and you are offered to add a comment, this can make a useful diary of past events. It will even blend in with the EMACS diary package. So anyway, this variable holds the name of the file for the filed todo-items.

 Variable todo-file-top

     File storing the top priorities of your TODO list when
     todo-save-top-priorities is non-nil. Nice to include in your
     diary instead of the complete TODO list.

 Variable todo-mode-hook

Just like other modes, too, this mode offers to call your functions before it goes about its business. This variable will be inspected for any functions you may wish to have called once the other TODO mode preparations have been completed.

 Variable todo-insert-threshold

        Another nifty feature is the insertion accuracy. If you have
        8 items in your TODO list, then you may get asked 4 questions
        by the binary insertion algorithm. However, you may not
        really have a need for such accurate priorities amongst your
        TODO items. If you now think about the binary insertion
        halving the size of the window each time, then the threshold
        is the window size at which it will stop. If you set the
        threshold to zero, the upper and lower bound will coincide at
        the end of the loop and you will insert your item just before
        that point. If you set the threshold to, e.g. 8, it will stop
        as soon as the window size drops below that amount and will
        insert the item in the approximate center of that window. I
        got the idea for this feature after reading a very helpful
        e-mail reply from Trey Jackson <trey@cs.berkeley.edu> who
        corrected some of my awful coding and pointed me towards some
        good reading. Thanks Trey!

 Things to do

     These originally were my ideas, but now also include all the
     suggestions that I included before forgetting them:

     o Fancy fonts for todo/top-priority buffer
     o Remove todo-prefix option in todo-top-priorities
     o Rename category
     o Move entry from one category to another one
     o Entries which both have the generic */* prefix and a
         "deadline" entry which are understood by diary, indicating
         an event (unless marked by &)
     o The optional COUNT variable of todo-forward-item should be
         applied to the other functions performing similar tasks
     o Modularization could be done for repeated elements of
         the code, like the completing-read lines of code.
o license / version function
o export to diary file
o todo-report-bug
o GNATS support
o elide multiline (as in bbdb, or, to a lesser degree, in
         outline mode)
o rewrite complete package to store data as Lisp objects
         and have display modes for display, for diary export,
         etc. (Richard Stallman pointed out this is a bad idea)
     o so base todo-mode.el on generic-mode.el instead

 History and Gossip

Many thanks to all the ones who have contributed to the
evolution of this package! I hope I have listed all of you
somewhere in the documentation or at least in the RCS history!

Enjoy this package and express your gratitude by sending nice things to my parents' address!

Oliver Seidel
(Lessingstr. 8, 65760 Eschborn, Federal Republic of Germany)

Defined variables (28)

Defined functions (51)

Defined faces (0)