[Bug] Doc string for org-clock-into-drawer truncated?

[Bug] Doc string for org-clock-into-drawer truncated?

[Achim Gratz]

In org-clock.el, the following definition is found:

(defcustom org-clock-into-drawer org-log-into-drawer
  "Should clocking info be wrapped into a drawer?
When t, clocking info will always be inserted into a :LOGBOOK: drawer.
If necessary, the drawer will be created.
When nil, the drawer will not be created, but used when present.
When an integer and the number of clocking entries in an item
reaches or exceeds this number, a drawer will be created.
When a string, it names the drawer to be used.

The default for this variable is the value of `org-log-into-drawer',
which see."
…

I can't make much sense of the last sentence which looks truncated.


As an aside, while the value for org-log-into-drawer can be changed for
a subtree by setting a property, this setting is not honored for
clocking in the same subtree, which will still use the value of
org-log-into-drawer in global or local scope or the LOGBOOK drawer, if
present.  In org-clock.el:

      (if org-clock-into-drawer
	  (let ((logbook
		 (if (stringp org-clock-into-drawer)
		     (concat ":" org-clock-into-drawer ":")
		   ":LOGBOOK:")))

But no defun to check a property like that used for logging in org.el:

(defun org-log-into-drawer ()
  "Return the value of `org-log-into-drawer', but let properties overrule.
If the current entry has or inherits a LOG_INTO_DRAWER property, it will be
used instead of the default value."
  (let ((p (org-entry-get nil "LOG_INTO_DRAWER" 'inherit)))
    (cond
     ((or (not p) (equal p "nil")) org-log-into-drawer)
     ((equal p "t") "LOGBOOK")
     (t p))))

For symmetry it seems that one should be able to specify a property
CLOCK_INTO_DRAWER specifically for clocking or fall back onto LOG_INTO
DRAWER, just like the customization variables allow one to do.


Regards,
Achim.
-- 
+<[Q+ Matrix-12 WAVE#46+305 Neuron microQkb Andromeda XTk Blofeld]>+

Wavetables for the Waldorf Blofeld:
http://Synth.Stromeko.net/Downloads.html#BlofeldUserWavetables

Re: [Bug] Doc string for org-clock-into-drawer truncated?

[Carsten Dominik]

On Jun 20, 2011, at 9:32 PM, Achim Gratz wrote:

> 
> In org-clock.el, the following definition is found:
> 
> (defcustom org-clock-into-drawer org-log-into-drawer
>  "Should clocking info be wrapped into a drawer?
> When t, clocking info will always be inserted into a :LOGBOOK: drawer.
> If necessary, the drawer will be created.
> When nil, the drawer will not be created, but used when present.
> When an integer and the number of clocking entries in an item
> reaches or exceeds this number, a drawer will be created.
> When a string, it names the drawer to be used.
> 
> The default for this variable is the value of `org-log-into-drawer',
> which see."
> …
> 
> I can't make much sense of the last sentence which looks truncated.

It means, please look at the variable org-log-into-drawer for
more information.  I have seen this idiom in Emacs
in a number of places, so I assumed it is OK.

> 
> As an aside, while the value for org-log-into-drawer can be changed for
> a subtree by setting a property, this setting is not honored for
> clocking in the same subtree, which will still use the value of
> org-log-into-drawer in global or local scope or the LOGBOOK drawer, if
> present.  In org-clock.el:
> 
>      (if org-clock-into-drawer
> 	  (let ((logbook
> 		 (if (stringp org-clock-into-drawer)
> 		     (concat ":" org-clock-into-drawer ":")
> 		   ":LOGBOOK:")))
> 
> But no defun to check a property like that used for logging in org.el:
> 
> (defun org-log-into-drawer ()
>  "Return the value of `org-log-into-drawer', but let properties overrule.
> If the current entry has or inherits a LOG_INTO_DRAWER property, it will be
> used instead of the default value."
>  (let ((p (org-entry-get nil "LOG_INTO_DRAWER" 'inherit)))
>    (cond
>     ((or (not p) (equal p "nil")) org-log-into-drawer)
>     ((equal p "t") "LOGBOOK")
>     (t p))))
> 
> For symmetry it seems that one should be able to specify a property
> CLOCK_INTO_DRAWER specifically for clocking or fall back onto LOG_INTO
> DRAWER, just like the customization variables allow one to do.


This does make sense, can you make a patch?

- Carsten

Re: [Bug] Doc string for org-clock-into-drawer truncated?

[Ian Barton]

On 21/06/11 08:49, Carsten Dominik wrote:
>
> On Jun 20, 2011, at 9:32 PM, Achim Gratz wrote:
>
>>
>> In org-clock.el, the following definition is found:
>>
>> (defcustom org-clock-into-drawer org-log-into-drawer
>>   "Should clocking info be wrapped into a drawer?
>> When t, clocking info will always be inserted into a :LOGBOOK: drawer.
>> If necessary, the drawer will be created.
>> When nil, the drawer will not be created, but used when present.
>> When an integer and the number of clocking entries in an item
>> reaches or exceeds this number, a drawer will be created.
>> When a string, it names the drawer to be used.
>>
>> The default for this variable is the value of `org-log-into-drawer',
>> which see."
>> …
>>
>> I can't make much sense of the last sentence which looks truncated.
>
> It means, please look at the variable org-log-into-drawer for
> more information.  I have seen this idiom in Emacs
> in a number of places, so I assumed it is OK.
>

I agree with Achim, that idiom makes no sense to a native English 
speaker. To make sense it should say something like ".... for which see 
the doc string for `org-log-into-drawer', or even better the way Achim's 
patch is worded.

Having just been picky, I must say that I am astounded by the general 
high standard of English both on this list and in the org documentation, 
from many people for whom it must be a second language. If only many of 
our native English writers could communicate so clearly and with correct 
grammar!

Ian.

Re: [Bug] Doc string for org-clock-into-drawer truncated?

[Achim Gratz]

Ian Barton <lists@wilkesley.net> writes:
>>> The default for this variable is the value of `org-log-into-drawer',
>>> which see."
>>> …
>>>
>>> I can't make much sense of the last sentence which looks truncated.
>>
>> It means, please look at the variable org-log-into-drawer for
>> more information.  I have seen this idiom in Emacs
>> in a number of places, so I assumed it is OK.
>>
>
> I agree with Achim, that idiom makes no sense to a native English
> speaker. To make sense it should say something like ".... for which
> see the doc string for `org-log-into-drawer', or even better the way
> Achim's patch is worded.

I've looked through some Emacs documentation and it is indeed the case
that ", which see." or "(which see)" is used in many places to make
reference to the documentation of a variable or function that has been
mentioned by name.  I'll just leave it at that and suggest it might be
discussed on an appropriate Emacs list if necessary.


Regards,
Achim.
-- 
+<[Q+ Matrix-12 WAVE#46+305 Neuron microQkb Andromeda XTk Blofeld]>+

SD adaptation for Waldorf microQ V2.22R2:
http://Synth.Stromeko.net/Downloads.html#WaldorfSDada

Re: [Bug] Doc string for org-clock-into-drawer truncated?

[Achim Gratz]

Carsten Dominik <carsten.dominik@gmail.com> writes:
>> For symmetry it seems that one should be able to specify a property
>> CLOCK_INTO_DRAWER specifically for clocking or fall back onto LOG_INTO
>> DRAWER, just like the customization variables allow one to do.
>
>
> This does make sense, can you make a patch?

I've had a closer look at the code and would think yes, hopefully I'll
find a hour or two to work on this over the weekend.


Regards,
Achim.
-- 
+<[Q+ Matrix-12 WAVE#46+305 Neuron microQkb Andromeda XTk Blofeld]>+

SD adaptations for KORG EX-800 and Poly-800MkII V0.9:
http://Synth.Stromeko.net/Downloads.html#KorgSDada

Re: [PATCH] Introduce CLOCK_INTO_DRAWER property like the existing LOG_INTO_DRAWER (was: [Bug] Doc string for org-clock-into-drawer truncated?)

[Achim Gratz]

[-- Attachment #1: Type: text/plain, Size: 327 bytes --]

Carsten Dominik <carsten.dominik@gmail.com> writes:
>> For symmetry it seems that one should be able to specify a property
>> CLOCK_INTO_DRAWER specifically for clocking or fall back onto LOG_INTO
>> DRAWER, just like the customization variables allow one to do.
>
>
> This does make sense, can you make a patch?

Here it is:


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: CLOCK_INTO_DRAWER property --]
[-- Type: text/x-patch, Size: 6002 bytes --]

From 8a07f2fae381196242b3c3af50e0b1d7364ba504 Mon Sep 17 00:00:00 2001
From: Achim Gratz <Stromeko@Stromeko.DE>
Date: Sat, 25 Jun 2011 17:25:41 +0200
Subject: [PATCH] Introduce CLOCK_INTO_DRAWER property like the existing
 LOG_INTO_DRAWER

* lisp/org.el (defcustom org-log-into-drawer): correct typo
* lisp/org-clock.el: new function org-clock-into-drawer to change
  the location of clock events based on properties CLOCK_INTO_DRAWER
  or, as fallback, LOG_INTO_DRAWER, like it is already possible for
  state change logs.
* lisp/org-clock.el (org-clock-jump-to-current-clock): add statement
  to let clause to bind org-clock-into-drawer to result of function
  eval
* lisp/org-clock.el (org-clock-find-position): add statement
  to let clause to bind org-clock-into-drawer to result of function
  eval, change let to let* since the binding is used later in the
  same clause
* doc/org.texi: document that both CLOCK_INTO_DRAWER and
  LOG_INTO_DRAWER can be used to override the contents of variable
  org-clock-into-drawer (or if unset, org-log-into-drawer)
* doc/org.texi: @xref->@pxref
---
 doc/org.texi      |    8 ++++++--
 lisp/org-clock.el |   40 +++++++++++++++++++++++++++++-----------
 lisp/org.el       |    2 +-
 3 files changed, 36 insertions(+), 14 deletions(-)

diff --git a/doc/org.texi b/doc/org.texi
index a397a7e..274a133 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -5759,11 +5759,15 @@ what to do with it.
 @table @kbd
 @orgcmd{C-c C-x C-i,org-clock-in}
 @vindex org-clock-into-drawer
+@cindex property, LOG_INTO_DRAWER
 Start the clock on the current item (clock-in).  This inserts the CLOCK
 keyword together with a timestamp.  If this is not the first clocking of
 this item, the multiple CLOCK lines will be wrapped into a
 @code{:LOGBOOK:} drawer (see also the variable
-@code{org-clock-into-drawer}).  When called with a @kbd{C-u} prefix argument,
+@code{org-clock-into-drawer}).  You can also overrule
+the setting of this variable for a subtree by setting a
+@code{CLOCK_INTO_DRAWER} or @code{LOG_INTO_DRAWER} property.
+When called with a @kbd{C-u} prefix argument,
 select the task from a list of recently clocked tasks.  With two @kbd{C-u
 C-u} prefixes, clock into the task at point and mark it as the default task.
 The default task will always be available when selecting a clocking task,
@@ -8950,7 +8954,7 @@ If the syntax for the label format conflicts with the language syntax, use a
 @code{-l} switch to change the format, for example @samp{#+BEGIN_SRC pascal
 -n -r -l "((%s))"}.  See also the variable @code{org-coderef-label-format}.
 
-HTML export also allows examples to be published as text areas (@xref{Text
+HTML export also allows examples to be published as text areas (@pxref{Text
 areas in HTML export}).
 
 Because the @code{#+BEGIN_...} and @code{#+END_...} patterns need to be added
diff --git a/lisp/org-clock.el b/lisp/org-clock.el
index abab70c..6e8295f 100644
--- a/lisp/org-clock.el
+++ b/lisp/org-clock.el
@@ -64,6 +64,22 @@ which see."
 	  (const :tag "Into LOGBOOK drawer" "LOGBOOK")
 	  (string :tag "Into Drawer named...")))
 
+(defun org-clock-into-drawer ()
+  "Return the value of `org-clock-into-drawer', but let properties overrule.
+If the current entry has or inherits a CLOCK_INTO_DRAWER
+property, it will be used instead of the default value; otherwise
+if the current entry has or inherits a LOG_INTO_DRAWER property,
+it will be used instead of the default value.
+The default is the value of the customizable variable `org-clock-into-drawer',
+which see."
+  (let ((p (org-entry-get nil "CLOCK_INTO_DRAWER" 'inherit))
+	(q (org-entry-get nil "LOG_INTO_DRAWER" 'inherit)))
+    (cond
+     ((or (not (or p q)) (equal p "nil") (equal q "nil")) org-clock-into-drawer)
+     ((or (equal p "t") (equal q "t")) "LOGBOOK")
+     ((not p) q)
+     (t p))))
+
 (defcustom org-clock-out-when-done t
   "When non-nil, clock will be stopped when the clocked entry is marked DONE.
 DONE here means any DONE-like state.
@@ -761,7 +777,8 @@ If necessary, clock-out of the currently active clock."
 
 (defun org-clock-jump-to-current-clock (&optional effective-clock)
   (interactive)
-  (let ((clock (or effective-clock (cons org-clock-marker
+  (let ((org-clock-into-drawer (org-clock-into-drawer))
+	(clock (or effective-clock (cons org-clock-marker
 					 org-clock-start-time))))
     (unless (marker-buffer (car clock))
       (error "No clock is currently running"))
@@ -1216,16 +1233,17 @@ When FIND-UNCLOSED is non-nil, first check if there is an unclosed clock
 line and position cursor in that line."
   (org-back-to-heading t)
   (catch 'exit
-    (let ((beg (save-excursion
-		 (beginning-of-line 2)
-		 (or (bolp) (newline))
-		 (point)))
-	  (end (progn (outline-next-heading) (point)))
-	  (re (concat "^[ \t]*" org-clock-string))
-	  (cnt 0)
-	  (drawer (if (stringp org-clock-into-drawer)
-		      org-clock-into-drawer "LOGBOOK"))
-	  first last ind-last)
+    (let* ((org-clock-into-drawer (org-clock-into-drawer))
+	   (beg (save-excursion
+		  (beginning-of-line 2)
+		  (or (bolp) (newline))
+		  (point)))
+	   (end (progn (outline-next-heading) (point)))
+	   (re (concat "^[ \t]*" org-clock-string))
+	   (cnt 0)
+	   (drawer (if (stringp org-clock-into-drawer)
+		       org-clock-into-drawer "LOGBOOK"))
+	   first last ind-last)
       (goto-char beg)
       (when (and find-unclosed
 		 (re-search-forward
diff --git a/lisp/org.el b/lisp/org.el
index 257bf4e..9cc3c94 100644
--- a/lisp/org.el
+++ b/lisp/org.el
@@ -2375,7 +2375,7 @@ When nil, state changes notes will be inserted after the headline and
 any scheduling and clock lines, but not inside a drawer.
 
 The value of this variable should be the name of the drawer to use.
-LOGBOOK is proposed at the default drawer for this purpose, you can
+LOGBOOK is proposed as the default drawer for this purpose, you can
 also set this to a string to define the drawer of your choice.
 
 A value of t is also allowed, representing \"LOGBOOK\".
-- 
1.7.5.4


[-- Attachment #3: Type: text/plain, Size: 290 bytes --]


It has survived my limited testing and I've provided minimal info
documentation.


Regards,
Achim.
-- 
+<[Q+ Matrix-12 WAVE#46+305 Neuron microQkb Andromeda XTk Blofeld]>+

Factory and User Sound Singles for Waldorf Q+, Q and microQ:
http://Synth.Stromeko.net/Downloads.html#WaldorfSounds

Re: [PATCH] Introduce CLOCK_INTO_DRAWER property like the existing LOG_INTO_DRAWER

[Bastien]

Hi Achim,

Achim Gratz <Stromeko@nexgo.de> writes:

> From: Achim Gratz <Stromeko@Stromeko.DE>
> Date: Sat, 25 Jun 2011 17:25:41 +0200
> Subject: [PATCH] Introduce CLOCK_INTO_DRAWER property like the existing
>  LOG_INTO_DRAWER

Applied, thanks a lot.  Let take at least one day to let people test
this patch -- feedback welcome.

Thanks,

-- 
 Bastien

Re: [PATCH] Introduce CLOCK_INTO_DRAWER property like the existing LOG_INTO_DRAWER

[Achim Gratz]

Bastien <bzg@altern.org> writes:
> Applied, thanks a lot.  Let take at least one day to let people test
> this patch -- feedback welcome.

Here's a template I've been using for testing.  Try it with different
settings for both global and file local variables.

--8<---------------cut here---------------start------------->8---
#+DRAWERS:    LOGBOOK GLOBLOG GLOBCLOCK FILELOG FILECLOCK FANCYLOG FANCYCLOCK PROPERTIES
#+STARTUP:    lognotestate
#+SEQ_TODO:   TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)

* Example Project Log

Try state changes and clocking into the two different project trees.
Project 1 has properties overriding logging and clocking, both with
fallback and explicit configuration (subproject 1.1), inherited along
the hierarchy.

** Project 1
   :PROPERTIES:
   :LOG_INTO_DRAWER: FANCYLOG
   :END:

*** Subproject 1.1
   :PROPERTIES:
   :CLOCK_INTO_DRAWER: FANCYCLOCK
   :END:

**** Subproject 1.1.1

     Inherits two properties.

** Project 2

   No inheritance, using either global scope or file local variables,
   depending on how you load the file.

* Global variables

  Try with different customizations for these variables (apply "for this
  session only"):

  - org-log-into-drawer: "GLOBALLOG"
  - org-clock-into-drawer: "GLOBALCLOCK"


### Local Variables:
### org-log-into-drawer: "FILELOG"
### org-clock-into-drawer: "FILECLOCK"
### End:
--8<---------------cut here---------------end--------------->8---


Regards,
Achim.
-- 
+<[Q+ Matrix-12 WAVE#46+305 Neuron microQkb Andromeda XTk Blofeld]>+

DIY Stuff:
http://Synth.Stromeko.net/DIY.html

Re: [PATCH] Introduce CLOCK_INTO_DRAWER property like the existing LOG_INTO_DRAWER

[Bastien]

Hi Achim,

Achim Gratz <Stromeko@nexgo.de> writes:

> Bastien <bzg@altern.org> writes:
>> Applied, thanks a lot.  Let take at least one day to let people test
>> this patch -- feedback welcome.
>
> Here's a template I've been using for testing.  Try it with different
> settings for both global and file local variables.

Works well here, thanks for sharing this.

-- 
 Bastien