emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
* [Bug] Doc string for org-clock-into-drawer truncated?
@ 2011-06-20 19:32 Achim Gratz
  2011-06-21  7:49 ` Carsten Dominik
  0 siblings, 1 reply; 9+ messages in thread
From: Achim Gratz @ 2011-06-20 19:32 UTC (permalink / raw)
  To: emacs-orgmode


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

^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: [Bug] Doc string for org-clock-into-drawer truncated?
  2011-06-20 19:32 [Bug] Doc string for org-clock-into-drawer truncated? Achim Gratz
@ 2011-06-21  7:49 ` Carsten Dominik
  2011-06-21  9:18   ` Ian Barton
                     ` (2 more replies)
  0 siblings, 3 replies; 9+ messages in thread
From: Carsten Dominik @ 2011-06-21  7:49 UTC (permalink / raw)
  To: Achim Gratz; +Cc: emacs-orgmode


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

^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: [Bug] Doc string for org-clock-into-drawer truncated?
  2011-06-21  7:49 ` Carsten Dominik
@ 2011-06-21  9:18   ` Ian Barton
  2011-06-26 15:27     ` Achim Gratz
  2011-06-22 21:11   ` Achim Gratz
  2011-06-26 16:10   ` [PATCH] Introduce CLOCK_INTO_DRAWER property like the existing LOG_INTO_DRAWER (was: [Bug] Doc string for org-clock-into-drawer truncated?) Achim Gratz
  2 siblings, 1 reply; 9+ messages in thread
From: Ian Barton @ 2011-06-21  9:18 UTC (permalink / raw)
  To: emacs-orgmode

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.

^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: [Bug] Doc string for org-clock-into-drawer truncated?
  2011-06-21  7:49 ` Carsten Dominik
  2011-06-21  9:18   ` Ian Barton
@ 2011-06-22 21:11   ` Achim Gratz
  2011-06-26 16:10   ` [PATCH] Introduce CLOCK_INTO_DRAWER property like the existing LOG_INTO_DRAWER (was: [Bug] Doc string for org-clock-into-drawer truncated?) Achim Gratz
  2 siblings, 0 replies; 9+ messages in thread
From: Achim Gratz @ 2011-06-22 21:11 UTC (permalink / raw)
  To: emacs-orgmode

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

^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: [Bug] Doc string for org-clock-into-drawer truncated?
  2011-06-21  9:18   ` Ian Barton
@ 2011-06-26 15:27     ` Achim Gratz
  0 siblings, 0 replies; 9+ messages in thread
From: Achim Gratz @ 2011-06-26 15:27 UTC (permalink / raw)
  To: emacs-orgmode

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

^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: [PATCH] Introduce CLOCK_INTO_DRAWER property like the existing LOG_INTO_DRAWER (was: [Bug] Doc string for org-clock-into-drawer truncated?)
  2011-06-21  7:49 ` Carsten Dominik
  2011-06-21  9:18   ` Ian Barton
  2011-06-22 21:11   ` Achim Gratz
@ 2011-06-26 16:10   ` Achim Gratz
  2011-06-27 10:14     ` [PATCH] Introduce CLOCK_INTO_DRAWER property like the existing LOG_INTO_DRAWER Bastien
  2 siblings, 1 reply; 9+ messages in thread
From: Achim Gratz @ 2011-06-26 16:10 UTC (permalink / raw)
  To: emacs-orgmode

[-- 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

^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: [PATCH] Introduce CLOCK_INTO_DRAWER property like the existing LOG_INTO_DRAWER
  2011-06-26 16:10   ` [PATCH] Introduce CLOCK_INTO_DRAWER property like the existing LOG_INTO_DRAWER (was: [Bug] Doc string for org-clock-into-drawer truncated?) Achim Gratz
@ 2011-06-27 10:14     ` Bastien
  2011-06-27 19:52       ` Achim Gratz
  0 siblings, 1 reply; 9+ messages in thread
From: Bastien @ 2011-06-27 10:14 UTC (permalink / raw)
  To: Achim Gratz; +Cc: emacs-orgmode

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

^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: [PATCH] Introduce CLOCK_INTO_DRAWER property like the existing LOG_INTO_DRAWER
  2011-06-27 10:14     ` [PATCH] Introduce CLOCK_INTO_DRAWER property like the existing LOG_INTO_DRAWER Bastien
@ 2011-06-27 19:52       ` Achim Gratz
  2011-06-28 16:38         ` Bastien
  0 siblings, 1 reply; 9+ messages in thread
From: Achim Gratz @ 2011-06-27 19:52 UTC (permalink / raw)
  To: emacs-orgmode

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

^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: [PATCH] Introduce CLOCK_INTO_DRAWER property like the existing LOG_INTO_DRAWER
  2011-06-27 19:52       ` Achim Gratz
@ 2011-06-28 16:38         ` Bastien
  0 siblings, 0 replies; 9+ messages in thread
From: Bastien @ 2011-06-28 16:38 UTC (permalink / raw)
  To: Achim Gratz; +Cc: emacs-orgmode

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

^ permalink raw reply	[flat|nested] 9+ messages in thread

end of thread, other threads:[~2011-06-28 16:38 UTC | newest]

Thread overview: 9+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2011-06-20 19:32 [Bug] Doc string for org-clock-into-drawer truncated? Achim Gratz
2011-06-21  7:49 ` Carsten Dominik
2011-06-21  9:18   ` Ian Barton
2011-06-26 15:27     ` Achim Gratz
2011-06-22 21:11   ` Achim Gratz
2011-06-26 16:10   ` [PATCH] Introduce CLOCK_INTO_DRAWER property like the existing LOG_INTO_DRAWER (was: [Bug] Doc string for org-clock-into-drawer truncated?) Achim Gratz
2011-06-27 10:14     ` [PATCH] Introduce CLOCK_INTO_DRAWER property like the existing LOG_INTO_DRAWER Bastien
2011-06-27 19:52       ` Achim Gratz
2011-06-28 16:38         ` Bastien

Code repositories for project(s) associated with this inbox:

	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).