[O] [PATCH] Documentation for "Tracking TODO state changes"

[Jason Dunsmore]

suvayu ali <address@hidden> writes:

> Hi Jason,
>
> On Wed, Nov 9, 2011 at 15:56, Jason Dunsmore <address@hidden> wrote:
>> After reading http://orgmode.org/org.html#Tracking-TODO-state-changes, I
>> expected the "@!" TODO syntax, eg. TODO(address@hidden), to do the following:
>>
>> - Log timestamp when entering state
>> - Add note when entering state
>>
>> This syntax appears to break the functionality, because it does neither.
>> The state is changed with no logging or note prompt.  Is this a bug?
>>
>> I verified that the TODO(t@/!) syntax does work as indicated in the
>> manual.
>>
>> - Add note when entering state
>> - Log timestamp when entering state
>> - Log timestamp when exiting state
>>
>> This is with the latest org-mode (commit a4273cbe0e0) and Emacs 23.2.1.
>>
>
> I believe the above should be:
>
> - Add note _with timestamp_ when entering state
> - Log timestamp when exiting state
>
> That said, you can simply hit C-c C-c to simply log the timestamp
> without a note. In other words, '@' is equivalent to '!' + note, so just
> enter a blank note. :)

Ah, I understand now.  Thanks for the explanation.  Here's a patch to to
the documentation:

--8<---------------cut here---------------start------------->8---
diff --git a/doc/org.texi b/doc/org.texi
index 4a547d0..e1167eb 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -4032,14 +4032,18 @@ also overrule the setting of this variable for a
subtree
 
 Since it is normally too much to record a note for every state,
 Org-mode
 expects configuration on a per-keyword basis for this.  This is
 achieved by
-adding special markers @samp{!} (for a timestamp) and @samp{@@} (for a
 note)
-in parentheses after each keyword.  For example, with the setting
+adding special markers @samp{!} (for a timestamp) or @samp{@@} (for a
 note
+with timestamp) in parentheses after each keyword.  For example, with
 the
+setting
 
 @lisp
 (setq org-todo-keywords
   '((sequence "TODO(t)" "WAIT(w@@/!)" "|" "DONE(d!)" "CANCELED(c@@)")))
 @end lisp
 
+To record a timestamp without a note for TODO keywords configured with
address@hidden@@}, just type @kbd{C-c C-c} to enter a blank note when prompted.
+
 @noindent
 @vindex org-log-done
 you not only define global TODO keywords and fast access keys, but also
--8<---------------cut here---------------end--------------->8---