[emacs-wiki-discuss] [patch] planner-rank.el document

[Dryice Liu]

This is my first writing in texinfo, so welcome comments, on both the
format and the English.

I also changed the planner-rank.el comments a little bit to cache up
the code changes.

These are also on patch-23 at http://dryice.3322.org/arch

======================================================================

  A  
{arch}/planner/planner--dev/planner--dev--1.0/address@hidden/patch-log/patch-23
  M  planner-el.texi
  M  planner-rank.el
                                                                        


--- orig/planner-el.texi
+++ mod/planner-el.texi
@@ -115,6 +115,7 @@
 * Task IDs::                    
 * Cyclic Tasks::                
 * Deadlines::                   
+* Task Ranks::
 * <tasks> tag::                 
 
 More about Notes
@@ -1457,6 +1458,7 @@
 * Task IDs::                    
 * Cyclic Tasks::                
 * Deadlines::                   
+* Task Ranks::
 * <tasks> tag::                 
 @end menu
 
@@ -2197,7 +2199,7 @@
 
 @file{planner-cyclic.el} does not define any keybindings.
 
address@hidden Deadlines, <tasks> tag, Cyclic Tasks, More about Tasks
address@hidden Deadlines, Task Ranks, Cyclic Tasks, More about Tasks
 @comment  node-name,  next,  previous,  up
 @subsection Deadlines
 @cindex tasks, deadlines for
@@ -2237,7 +2239,114 @@
 Change the deadline of current task to @var{date}. If @var{date} is nil, 
remove deadline.
 @end defun
 
address@hidden <tasks> tag,  , Deadlines, More about Tasks
address@hidden Task Ranks, <tasks> tag, Deadlines, More about Tasks
address@hidden  node-name,  next,  previous,  up
address@hidden Task Ranks
address@hidden tasks, deadlines for
address@hidden deadlines, task
address@hidden @file{planner-deadline.el}, using
+
address@hidden models Franklin Covey's Urgency and Importance
+principle. When you think about a task, there are two aspects in
+consideration: Urgency and Importance. You may want to do the most
+urgent things first, like answering an email, or you may want to do the
+most important things first, like reading this manual. Or much better,
+balance between Urgency and Importance, and decide what to
+do. 
+
address@hidden will help you doing the balance.
+
+For both Urgency and Importance, you measure them by scores 0-9. The
+higher the score, the more you want to do it first. Namely 9 stands for
+``I should have done this'' and 0 stands for ``I can forget this''.
+
+If you are using the planner @ref{Deadlines} feature. The Urgency score
+is calculated from how many days are left to meet the deadline. By
+default, it will score 9 if the task is overdue and 0 if the deadline is
+years away. Please refer the docstring of
address@hidden for detail.
+
+The task rank (the balancing result) is calculated from Urgency and
+Importanc scores. As different people holds different ways and policies
+balancing them, there are a bunch of planner-rank-calculate-rank-*
+functions pre-baked. The algorithm vary from a simple (a+b)/2 to
+something like a weighted root mean square deviation.
+
+The planner-rank-calculate-rank-*-aggressive functions will make sure if
+one of Urgency and Importanc is high, the resulting Rank will get a high
+score. And planner-rank-calculate-rank-weighted-* functions looks
+differently on the Urgency and Important score, depending on
address@hidden 
+
+Call @code{planner-rank-test-algorithm} on each of the functions and
+check the result tables to see which one you like most, and set it to
address@hidden
+
+Once the Rank is calculated, the @ref{Task Priorities} will be
+automaticaly reset. If the Rank is greater than or equal to
address@hidden, the task priority will be
address@hidden, if the Rank is between @code{planner-rank-priority-A-valve}
+and @code{planner-rank-priority-B-valve}, the priority will be @samp{B},
+else it will be @samp{C}.
+
+So after setting the task important and deadline, you can leave it as
+is. As the deadline comes, the task priority will raise automaticly and
+catch your eyes.
+
+And if you are using @code{planner-sort-tasks} (see @pxref{Making Files
+Pretty}), you can set @code{planner-sort-tasks-key-function} to one of
address@hidden,
address@hidden, and @code{planner-sort-tasks-by-urgency}.
+
address@hidden planner-rank-change-hook
+Functions to run after @code{planner-rank-change}.
address@hidden defopt
+
address@hidden planner-rank-priority-A-valve
+Tasks with rank greater than or equal to this value will be in priority
address@hidden
address@hidden defopt
+
address@hidden planner-rank-priority-B-valve
+Tasks with rank greater than or equal to this value and less than
address@hidden will be in priority @samp{B}. Tasks with
+rank less than this value will be in priority @samp{C}.
address@hidden defopt
+
address@hidden planner-rank-deadline-urgency-map-list
+Defines how to calculate the Urgency score according to how many days
+are left to meet the deadline.
address@hidden defopt
+
address@hidden planner-rank-default-importance
+Default importance value for newly added rank.
address@hidden defopt
+
address@hidden planner-rank-default-urgency
+Default urgency value for newly added rank.
address@hidden defopt
+
address@hidden planner-rank-importance-vs-urgency-factor
+How much do you think importance is more "important" than urgency. This
+will be used in planner-rank-calculate-rank-weighted-* functions.
address@hidden defopt
+
address@hidden planner-rank-rank-calculate-function
+Define the function called to calculate rank.
address@hidden defopt
+
address@hidden planner-rank-change &optional importance urgency
+Set the Importance and Urgency of the current task.
address@hidden defun
+
address@hidden planner-rank-update-current-task
+Re-calculate rank for the current task.
address@hidden defun
+
address@hidden planner-rank-update-all
+Re-calculate rank for all tasks in the current page
address@hidden defun
address@hidden <tasks> tag,  , Task Ranks, More about Tasks
 @subsection <tasks> tag
 
 @samp{<tasks>} is replaced by a report of tasks over all day pages in


--- orig/planner-rank.el
+++ mod/planner-rank.el
@@ -26,7 +26,7 @@
 
 ;;; Commentary:
 ;; This file models Franklin Covey's Urgency and Importance
-;; principal. Where for both Urgency and Importance, you can measure
+;; principle. Where for both Urgency and Importance, you can measure
 ;; them with number 0-9. 9 means "I should have done this from
 ;; Emergency/Important point of view" while 0 means "I can forget this
 ;; from Emergency/Important point of view".
@@ -40,12 +40,8 @@
 ;; your favoriate algorithm by setting
 ;; `planner-rank-rank-calculate-function'. Took a look at the
 ;; planner-rank-calculate-rank-* functions to see which one you like
-;; most. Note the result tables in the doc string are generated with
-;; default `planner-rank-priority-A-valve' and
-;; `planner-rank-priority-B-valve'. If you change these two or make
-;; your own calculate function, you can always use
-;; `planner-rank-test-algorithm' to get the same table and see how it
-;; works.
+;; most. Call `planner-rank-test-algorithm' to get the result tables
+;; and see how it works.
 ;; 
 ;; The three planner-sort-tasks-by-* functions in this file is
 ;; suitable for `planner-sort-tasks-key-function'.




======================================================================

-- 
Dryice @ http://dryice.3322.org

Please avoid sending me Word or PowerPoint attachments.
See http://www.fsf.org/philosophy/sylvester-response.html