changeset 19186:023404dbc696

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.
author Oliver Seidel <os10000@seidel-space.de>
date Wed, 06 Aug 1997 08:12:03 +0000
parents 77910f9661a9
children 9d37b4ab16b5
files lisp/calendar/todo-mode.el
diffstat 1 files changed, 176 insertions(+), 92 deletions(-) [+]
line wrap: on
line diff
--- 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 <tjackson@ichips.intel.com>
+;; 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
 ;; <tjackson@ichips.intel.com>; 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 <tjackson@ichips.intel.com>
-;; 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)))