# HG changeset patch # User Oliver Seidel # Date 870855123 0 # Node ID 023404dbc696b8d24cc18c756507626a56190ffb # Parent 77910f9661a9f60e7d6a325f493a34657e211795 Improved documentation. Broke some lines to comply with Richard Stallman's email to please keep in sync with the rest of the Emacs distribution files. diff -r 77910f9661a9 -r 023404dbc696 lisp/calendar/todo-mode.el --- a/lisp/calendar/todo-mode.el Wed Aug 06 07:11:59 1997 +0000 +++ b/lisp/calendar/todo-mode.el Wed Aug 06 08:12:03 1997 +0000 @@ -1,4 +1,6 @@ -; todomode.el -- major mode for editing TODO list files +;; todomode.el -- major mode for editing TODO list files + +;; $Id: todomode.el,v 1.8 1997/08/05 22:39:04 os10000 Exp os10000 $ ;; --------------------------------------------------------------------------- @@ -23,12 +25,161 @@ ;; --------------------------------------------------------------------------- -;; Contact information: (address) O Seidel, Lessingstr 8, Eschborn, FRG -;; (e-mail ) Oliver.Seidel@cl.cam.ac.uk (2 Aug 1997) +;; +;; Quickstart Installation: +;; ======================== +;; +;; To get this to work, make emacs execute the line +;; +;; (require 'todomode) ;; load the TODO package +;; +;; I would also recommend executing the following commands +;; so as to extend the bindings in your global keymap: +;; +;; (global-set-key "\C-ct" 'todo-show) ;; switch to TODO buffer +;; (global-set-key "\C-ci" 'todo-cmd-inst) ;; insert new item +;; +;; +;; +;; 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 categorised, 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. +;; +;; +;; +;; Operation: +;; ========== +;; +;; You will have the following facilities available: +;; +;; M-x todo-mode will enter the todo list screen, here type +;; + to go to next category +;; - to go to previous category +;; e to edit the current entry +;; f to file the current entry, including a +;; comment and timestamp +;; i to insert a new entry +;; k to kill the current entry +;; l lower the current entry's priority +;; n for the next entry +;; p for the previous entry +;; q to save the list and exit the buffer +;; r raise current entryk's priority +;; s to save the list +;; +;; 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. +;; +;; +;; +;; Configuration: +;; ============== +;; +;; --- 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. +;; +;; For this, 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. +;; +;; +;; --- 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. +;; +;; +;; --- 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. +;; +;; +;; --- 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. +;; +;; +;; --- todo-ins-thresh +;; +;; 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 halfing the size of the window each time, then +;; the threshhold is the window size at which it will stop. If you set +;; the threshhold 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 threshhold to i.e. 8, it will stop as soon as the window +;; size drops below that amount and will insert the item in the approximate +;; centre of that window. I got the idea for this feature after reading +;; a very helpful e-mail reply from Trey Jackson +;; who corrected some of my awful coding and pointed me towards some good +;; reading. Thanks Trey! +;; +;; +;; +;; History and Gossip: +;; =================== +;; +;; Just for the case that you are wondering about the ugly name of this +;; package: I am one of those unfortunate people who have DOS, LINUX and +;; OS/2 on one of their computers, so part of my home-filespace is shared +;; and stored on a DOS partition, which is accessible to all systems. If +;; you wish, you can of course rename the name of the file (and the "provide" +;; command near the end of this package) to something more aisthetically +;; (please don't argue about this spelling ...) pleasing, like i.e. todo-mode. +;; +;; Enjoy this package and express your gratitude by sending valuables +;; to my parents' address as listed above!!! +;; +;; Oliver Seidel +;; +;; +;; +;; Contact information: +;; ==================== +;; +;; address ....: O Seidel, Lessingstr 8, Eschborn, FRG +;; e-mail .....: Oliver.Seidel@cl.cam.ac.uk (was valid on 2 Aug 1997) +;; -;; $Id: todomode.el,v 1.7 1997/08/05 22:34:14 os10000 Exp os10000 $ +;; --------------------------------------------------------------------------- + ;; ;; $Log: todomode.el,v $ +;; Revision 1.8 1997/08/05 22:39:04 os10000 +;; Made todomode.el available under GPL. +;; ;; Revision 1.7 1997/08/05 22:34:14 os10000 ;; Fixed insertion routine with help from Trey Jackson ;; ; added todo-ins-thresh; @@ -57,90 +208,12 @@ ;; --------------------------------------------------------------------------- -;; Description: -;; -;; To get this to work, make emacs execute the line "(require 'todomode)" -;; and maybe initialise the variables below on startup. -;; -;; Just for the case that you are wondering about the ugly name of this -;; package: I am one of those unfortunate people who have DOS, LINUX and -;; OS/2 on one of their computers, so part of my home-filespace is shared -;; and stored on a DOS partition, which is accessible to all systems. If -;; you wish, you can of course rename the name of the file (and the last -;; command) to something more aisthetically (please don't argue about -;; this spelling ...) pleasing, like i.e. todo-mode. -;; -;; You will have the following facilities available: -;; -;; M-x todo-mode will enter the todo list screen, here type -;; + to go to next category -;; - to go to previous category -;; e to edit the current entry -;; f to file the current entry, including a -;; comment and timestamp -;; i to insert a new entry -;; k to kill the current entry -;; l lower the current entry's priority -;; n for the next entry -;; p for the previous entry -;; q to save the list and exit the buffer -;; r raise current entryk's priority -;; s to save the list -;; -;; 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. -;; -;; I would recommend to add the following bindings to your global keymap: -;; -;; (global-set-key "\C-ct" 'todo-show) -;; (global-set-key "\C-ci" 'todo-cmd-inst) -;; -;; This will enable you to quickly find the todo-list, or to simply add an -;; entry, without changing to it and getting sidetracked from your current -;; project. -;; -;; I would also recommend that use the prefix "*/*" (by leaving the -;; variable 'todo-prefix' untouched) so that the diary displays -;; each entry every day. -;; -;; For this, 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. -;; -;; 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 halfing the size of the window each time, then -;; the threshhold is the window size at which it will stop. If you set -;; the threshhold 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 threshhold to i.e. 8, it will stop as soon as the window -;; size drops below that amount and will insert the item in the approximate -;; centre of that window. I got the idea for this feature after reading -;; a very helpful e-mail reply from Trey Jackson -;; who corrected some of my awful coding and pointed me towards some good -;; reading. Thanks Trey! -;; -;; Enjoy this package and express your gratitude by sending valuables -;; to my parents' address as listed above!!! -;; -;; Oliver Seidel - -;; --------------------------------------------------------------------------- - ;; User-configurable variables: (defvar todo-prefix "*/*" "TODO mode prefix when creating entries") (defvar todo-file-do "~/.todo-do" "TODO mode filename of list file") (defvar todo-file-done "~/.todo-done" "TODO mode filename of archive file") -(defvar todo-mode-hook nil "Hooks invoked when the *TODO* buffer is created.") +(defvar todo-mode-hook nil "Hooks invoked when the TODO mode is entered.") (defvar todo-ins-thresh 0 "TODO mode insertion accuracy.") ;; --------------------------------------------------------------------------- @@ -168,7 +241,8 @@ (defun todo-cat-slct () (let ((todo-category-name (nth todo-category-number todo-cats))) - (setq mode-line-buffer-identification (concat "Category: " todo-category-name)) + (setq mode-line-buffer-identification + (concat "Category: " todo-category-name)) (widen) (goto-char (point-min)) (search-forward (concat "--- " todo-category-name)) @@ -225,7 +299,8 @@ (bury-buffer) ) -(defun todo-line () "Find current line in buffer." (buffer-substring (point-at-bol) (point-at-eol))) +(defun todo-line () "Find current line in buffer." + (buffer-substring (point-at-bol) (point-at-eol))) (defun todo-cmd-edit () "Edit current TODO list entry." (interactive) @@ -249,11 +324,15 @@ (goto-char (point-min)) (let ((posn (search-forward "-*- mode: todo; " 17 t))) (if (not (null posn)) (goto-char posn)) - (if (equal posn nil) (progn (insert "-*- mode: todo; \n") (forward-char -1)) (kill-line)) - ) + (if (equal posn nil) + (progn + (insert "-*- mode: todo; \n") + (forward-char -1)) + (kill-line))) (insert (format "todo-cats: %S; -*-" todo-cats)) (forward-char 1) - (insert (format "%s --- %s\n--- End\n%s %s\n" todo-prefix cat todo-prefix (make-string 75 ?-))) + (insert (format "%s --- %s\n--- End\n%s %s\n" + todo-prefix cat todo-prefix (make-string 75 ?-))) ) 0 ) @@ -262,7 +341,8 @@ "Insert new TODO list entry." (interactive) (beginning-of-line nil) - (let* ((todo-entry (concat todo-prefix " " (read-from-minibuffer "New TODO entry: "))) + (let* ((todo-entry (concat todo-prefix " " + (read-from-minibuffer "New TODO entry: "))) (temp-catgs todo-cats) (todo-hstry (cons 'temp-catgs (+ todo-category-number 1)))) (save-window-excursion @@ -283,7 +363,8 @@ (todo-lst (+ 1 (count-lines (point-min) (point-max))))) (while (> (- todo-lst todo-fst) todo-ins-thresh) (let* ((todo-cur (/ (+ todo-fst todo-lst) 2)) - (todo-ans (if (< todo-cur todo-lst) (todo-ask todo-cur) nil))) + (todo-ans (if (< todo-cur todo-lst) + (todo-ask todo-cur) nil))) (if todo-ans (setq todo-lst todo-cur) (setq todo-fst (+ todo-cur 1))))) @@ -306,7 +387,9 @@ (setq todo-prv-lne lne) (goto-char (point-min)) (forward-line (- todo-prv-lne 1)) - (setq todo-prv-ans (y-or-n-p (concat "More important than '" (todo-line) "'? "))))) + (setq todo-prv-ans (y-or-n-p + (concat "More important than '" + (todo-line) "'? "))))) todo-prv-ans) (defun todo-cmd-kill () "Delete current TODO list entry." @@ -314,7 +397,8 @@ (if (> (count-lines (point-min) (point-max)) 0) (progn (let* ((todo-entry (todo-line)) - (todo-answer (y-or-n-p (concat "Permanently remove '" todo-entry "'? ")))) + (todo-answer (y-or-n-p (concat "Permanently remove '" + todo-entry "'? ")))) (if todo-answer (progn (delete-region (point-at-bol) (+ 1 (point-at-eol)))