Add org-clock-in-prepare-hook. Doc update.

This hook is called in org-clock-in earlier than the existing
org-clock-in-hook.  This is useful for functions that need to
modify the Effort property, for example.

doc/ChangeLog

@@ -1,3 +1,10 @@
+2009-07-17  Bastien Guerry  <bzg@altern.org>
+
+	* org.texi (Clocking work time): Add documentation about
+	displaying the current clocking time against the effort estimate.
+	Also add a footnote about using `org-clock-in-prepare-hook' to add
+	an effort estimate on the fly, just before clocking it.
+
 2009-07-03  Carsten Dominik  <carsten.dominik@gmail.com>
 
 	* org.texi (Footnotes): Document automatic renumbering and

doc/org.texi

@@ -5330,18 +5330,20 @@ with letter @kbd{d}.@*
 @vindex org-clock-modeline-total
 While the clock is running, the current clocking time is shown in the mode
 line, along with the title of the task.  The clock time shown will be all
-time ever clocked for this task and its children.  If the task is a repeating
-one (@pxref{Repeated tasks}), only the time since the last reset of the task
-@footnote{as recorded by the @code{LAST_REPEAT} property} will be shown.
-More control over what time is shown can be exercised with the
-@code{CLOCK_MODELINE_TOTAL} property.  It may have the values @code{current}
-to show only the current clocking instance, @code{today} to show all time
-clocked on this tasks today (see also the variable
+time ever clocked for this task and its children.  If the task has an effort
+estimate (@pxref{Effort estimates}), the mode line displays the current
+clocking time against it@footnote{To add an effort estimate ``on the fly'',
+hook a function doing this to @code{org-clock-in-prepare-hook}.}  If the task
+is a repeating one (@pxref{Repeated tasks}), only the time since the last
+reset of the task @footnote{as recorded by the @code{LAST_REPEAT} property}
+will be shown.  More control over what time is shown can be exercised with
+the @code{CLOCK_MODELINE_TOTAL} property.  It may have the values
+@code{current} to show only the current clocking instance, @code{today} to
+show all time clocked on this tasks today (see also the variable
 @code{org-extend-today-until}), @code{all} to include all time, or
 @code{auto} which is the default@footnote{See also the variable
-@code{org-clock-modeline-total}.}.@*
-Clicking with @kbd{mouse-1} onto the mode line entry will pop up a menu with
-clocking options.
+@code{org-clock-modeline-total}.}.@* Clicking with @kbd{mouse-1} onto the
+mode line entry will pop up a menu with clocking options.
 @kindex C-c C-x C-o
 @item C-c C-x C-o
 @vindex org-log-note-clock-out

lisp/ChangeLog

@@ -1,3 +1,8 @@
+2009-07-17  Bastien Guerry  <bzg@altern.org>
+
+	* org-clock.el (org-clock-in-prepare-hook): New hook.
+	(org-clock-in): Use this new hook.
+
 2009-07-16  Bastien Guerry  <bzg@altern.org>
 
 	* org.el (org-special-ctrl-a/e): Explicitely bind the value

lisp/org-clock.el

@@ -192,6 +192,11 @@ auto     Automtically, either `all', or `repeat' for repeating tasks"
 	  (const :tag "All task time" all)
 	  (const :tag "Automatically, `all' or since `repeat'" auto)))
 
+(defvar org-clock-in-prepare-hook nil
+  "Hook run when preparing the clock.
+This hook is run before anything happens to the task that
+you want to clock in.  For example, you can use this hook
+to add an effort property.")
 (defvar org-clock-in-hook nil
   "Hook run when starting the clock.")
 (defvar org-clock-out-hook nil
@@ -496,6 +501,7 @@ the clocking selection, associated with the letter `d'."
 	(org-clock-mark-default-task))
 
       (setq target-pos (point))  ;; we want to clock in at this location
+      (run-hooks 'org-clock-in-prepare-hook)
       (save-excursion
 	(when (and selected-task (marker-buffer selected-task))
 	  ;; There is a selected task, move to the correct buffer