Fix problems in the interaction of John's and James' clock restore code

Now the recommendation is to use clock persistence only for the
history, and to use John's code for resolving a clock that has been
idle (either because the user stopped working or exited Emacs).

doc/ChangeLog

@@ -1,3 +1,12 @@
+2009-10-24  Carsten Dominik  <carsten.dominik@gmail.com>
+
+	* org.texi (Clocking work time): Better description on how to save
+	and restore a clock.
+	(Resolving idle time): Mention the x11idle program to get true
+	idleness also under X11.
+	(Resolving idle time): Use @kbd instead of @key for normal
+	letters, because this is how he rest of the manual does this.
+
 2009-10-19  John Wiegley  <johnw@newartisans.com>
 
 	* org.texi (Tracking your habits): Added a new section in the

doc/org.texi

@@ -5329,15 +5329,20 @@ Org mode allows you to clock the time you spend on specific tasks in a
 project.  When you start working on an item, you can start the clock.
 When you stop working on that task, or when you mark the task done, the
 clock is stopped and the corresponding time interval is recorded.  It
-also computes the total time spent on each subtree of a project.
-
-Normally, the clock does not survive exiting and re-entering Emacs, but you
-can arrange for the clock information to persist across Emacs sessions with
+also computes the total time spent on each subtree of a project.  And it
+remembers a history or tasks recently clocked, to that you can jump quickly
+between a number of tasks absorbing your time.
 
+To save the clock history across Emacs sessions, use
 @lisp
-(setq org-clock-persist t)
+(setq org-clock-persist 'history)
 (org-clock-persistence-insinuate)
 @end lisp
+When you clock into a new task after resuming Emacs, the incomplete
+clock@footnote{To resume the clock under the assumption that you have worked
+on this task while outside Emacs, use @code{(setq org-clock-persist t)}.}
+will be found (@pxref{Resolving idle time}) and you will be prompted about
+what to do with it.
 
 @table @kbd
 @kindex C-c C-x C-i
@@ -5521,30 +5526,33 @@ applying it to another one.
 By customizing the variable @code{org-clock-idle-time} to some integer, such
 as 10 or 15, Emacs can alert you when you get back to your computer after
 being idle for that many minutes@footnote{On computers using Mac OS X,
-idleness is based on actual user idleness, not just Emacs' idle time.}, and
-ask what you want to do with the idle time.  There will be a question waiting
-for you when you get back, indicating how much idle time has passed
-(constantly updated with the current amount), as well as a set of choices to
-correct the discrepancy:
+idleness is based on actual user idleness, not just Emacs' idle time.  For
+X11, you can install a utility program @file{x11idle.c}, available in the
+UTILITIES directory of the Org git distribution, to get the same general
+treatment of idleness.  On other systems, idle time refers to Emacs idle time
+only.}, and ask what you want to do with the idle time.  There will be a
+question waiting for you when you get back, indicating how much idle time has
+passed (constantly updated with the current amount), as well as a set of
+choices to correct the discrepancy:
 
 @table @kbd
 @item k
-To keep some or all of the minutes and stay clocked in, press @key{k}.  Org
+To keep some or all of the minutes and stay clocked in, press @kbd{k}.  Org
 will ask how many of the minutes to keep.  Press @key{RET} to keep them all,
 effectively changing nothing, or enter a number to keep that many minutes.
 @item K
-If you use the shift key and press @key{K}, it will keep however many minutes
+If you use the shift key and press @kbd{K}, it will keep however many minutes
 you request and then immediately clock out of that task.  If you keep all of
 the minutes, this is the same as just clocking out of the current task.
 @item s
-To keep none of the minutes, use @key{s} to subtract all the away time from
+To keep none of the minutes, use @kbd{s} to subtract all the away time from
 the clock, and then check back in from the moment you returned.
 @item S
 To keep none of the minutes and just clock out at the start of the away time,
-use the shift key and press @key{S}.  Remember that using shift will always
+use the shift key and press @kbd{S}.  Remember that using shift will always
 leave you clocked out, no matter which option you choose.
 @item C
-To cancel the clock altogether, use @key{C}.  Note that if instead of
+To cancel the clock altogether, use @kbd{C}.  Note that if instead of
 cancelling you subtract the away time, and the resulting clock amount is less
 than a minute, the clock will still be cancelled rather than clutter up the
 log with an empty entry.

lisp/ChangeLog

@@ -1,3 +1,12 @@
+2009-10-24  Carsten Dominik  <carsten.dominik@gmail.com>
+
+	* org-clock.el (org-clock-persist): New value, to store only the
+	clock history.
+	(org-clock-save): Don't save the clock if only the history should
+	be stored.
+	(org-clock-load): Turn off John Wiegley's auto resolving mechanism
+	when restoring a saved clock.
+
 2009-10-24  John Wiegley  <jwiegley@gmail.com>
 
 	* org-clock.el (org-clock-display, org-clock-put-overlay): Use

lisp/org-clock.el

@@ -142,6 +142,7 @@ All this depends on running `org-clock-persistence-insinuate' in .emacs"
   :group 'org-clock
   :type '(choice
 	  (const :tag "Just the running clock" clock)
+	  (const :tag "Just the history" history)
 	  (const :tag "Clock and history" t)
 	  (const :tag "No persistence" nil)))
 
@@ -1832,7 +1833,8 @@ The details of what will be saved are regulated by the variable
 	  (insert (format ";; org-persist.el - %s at %s\n"
 			  system-name (format-time-string
 				       (cdr org-time-stamp-formats))))
-	  (if (and (setq b (marker-buffer org-clock-marker))
+	  (if (and (memq org-clock-persist '(t clock))
+		   (setq b (marker-buffer org-clock-marker))
 		   (setq b (or (buffer-base-buffer b) b))
 		   (buffer-live-p b)
 		   (buffer-file-name b)
@@ -1846,7 +1848,8 @@ The details of what will be saved are regulated by the variable
 		      "))\n"))
 	  ;; Store clocked task history. Tasks are stored reversed to make
 	  ;; reading simpler
-	  (when (and org-clock-history (eq org-clock-persist t))
+	  (when (and (memq org-clock-persist '(t history))
+		     org-clock-history)
 	    (insert
 	     "(setq stored-clock-history '("
 	     (mapconcat
@@ -1902,9 +1905,10 @@ The details of what will be saved are regulated by the variable
 	  (when (file-exists-p (car resume-clock))
 	    (with-current-buffer (find-file (car resume-clock))
 	      (goto-char (cdr resume-clock))
-	      (org-clock-in)
-	      (if (org-invisible-p)
-		  (org-show-context)))))))))
+	      (let ((org-clock-auto-clock-resolution nil))
+		(org-clock-in)
+		(if (org-invisible-p)
+		    (org-show-context))))))))))
 
 ;;;###autoload
 (defun org-clock-persistence-insinuate ()