From 99e22650f88652de1c5192bf19d6ff4c9a0781ca Mon Sep 17 00:00:00 2001 From: Carsten Dominik Date: Wed, 5 Mar 2008 09:14:59 +0100 Subject: [PATCH] Improved the documentation for per-state logging settings. Why? Because it was still hard to understand. Still is, kind of. --- org.el | 15 ++++++++++----- org.texi | 12 ++++++------ 2 files changed, 16 insertions(+), 11 deletions(-) diff --git a/org.el b/org.el index a6a94d895..a30507f00 100644 --- a/org.el +++ b/org.el @@ -1715,11 +1715,16 @@ and specifiers for state change logging, using the same syntax that is used in the \"#+TODO:\" lines. For example, \"WAIT(w)\" says that the WAIT state can be selected with the \"w\" key. \"WAIT(w!)\" indicates to record a time stamp each time this state is selected. -\"WAIT(w@)\" says that the user should in addition be prompted for a -note, and \"WAIT(w@/@)\" says that a note should be taken both when -entering and when leaving this state. The last double-setting is -only a backup, to force a note even if the target state has no -logging configured. + +Each keyword may also specify if a timestamp or a note should be +recorded when entering or leaving the state, by adding additional +characters in the parenthesis after the keyword. This looks like this: +\"WAIT(w@/!)\". \"@\" means to add a note (with time), \"!\" means to +record only the time of the state change. With X and Y being either +\"@\" or \"!\", \"X/Y\" means use X when entering the state, and use +Y when leaving the state if and only if the *target* state does not +define X. You may omit any of the fast-selection key or X or /Y, +so WAIT(w@), WAIT(w/@) and WAIT(@/@) are all valid. For backward compatibility, this variable may also be just a list of keywords - in this case the interptetation (sequence or type) will be diff --git a/org.texi b/org.texi index c567fcf6b..c5bde89b9 100644 --- a/org.texi +++ b/org.texi @@ -3015,12 +3015,12 @@ the @samp{Closing Note}.}, and that a note is recorded when switching to WAIT or CANCELED. The setting for WAIT is even more special: The @samp{!} after the slash means that in addition to the note taken when entering the state, a time stamp should be recorded when @i{leaving} the -WAIT state. This second logging setting only comes into play when -switching to a state that has no logging set up. So it has no effect -when switching from WAIT to DONE, because DONE is configured to record a -timestamp only. But when switching from WAIT back to TODO, the -@samp{/!} in the WAIT setting now triggers a timestamp even though TODO -has no logging configured. +WAIT state, if and only if the @i{target} state does not configure +logging for entering it. So it has no effect when switching from WAIT +to DONE, because DONE is configured to record a timestamp only. But +when switching from WAIT back to TODO, the @samp{/!} in the WAIT +setting now triggers a timestamp even though TODO has no logging +configured. You can use the exact same syntax for setting logging preferences local to a buffer: