Bug: Bad doc [7.4]

Bug: Bad doc [7.4]

[Dave Abrahams]

Remember to cover the basics, that is, what you expected to happen and
what in fact did happen.  You don't know how to make a good report?  See

     http://orgmode.org/manual/Feedback.html#Feedback

Your bug report will be posted to the Org-mode mailing list.
------------------------------------------------------------------------

Th' manual sez:

  9.1.3 Capture templates
  -----------------------

  You can use templates for different types of capture items, and for
  different target locations.  The easiest way to create such templates is
  through the customize interface.

  `C-c c C'
       Customize the variable `org-capture-templates'.

I don't know where that keybinding is supposed to come from, but as
far as I can tell, it isn't set anywhere.  In fact, if we take the
manual's suggested `C-c c' binding for org-capture, the `C' above just
does a self-insert in the capture buffer.

Emacs  : GNU Emacs 23.2.1 (x86_64-apple-darwin, NS apple-appkit-1038.29)
 of 2010-05-08 on black.local
Package: Org-mode version 7.4

-- 
Dave Abrahams
BoostPro Computing
http://www.boostpro.com

Re: Bug: Bad doc [7.4]

[Leo]

On 2010-12-20 06:12 +0000, Dave Abrahams wrote:
> Th' manual sez:
>
>   9.1.3 Capture templates
>   -----------------------
>
>   You can use templates for different types of capture items, and for
>   different target locations.  The easiest way to create such templates is
>   through the customize interface.
>
>   `C-c c C'
>        Customize the variable `org-capture-templates'.
>
> I don't know where that keybinding is supposed to come from, but as
> far as I can tell, it isn't set anywhere.  In fact, if we take the
> manual's suggested `C-c c' binding for org-capture, the `C' above just
> does a self-insert in the capture buffer.

No problem here, running 7.4 on 23.2.91.

You should see something like: http://imgur.com/Bfwlh.png

Cheers,
Leo

-- 
Oracle is the new evil

Re: Bug: Bad doc [7.4]

[Noorul Islam K M]

Dave Abrahams <dave@boostpro.com> writes:

> Remember to cover the basics, that is, what you expected to happen and
> what in fact did happen.  You don't know how to make a good report?  See
>
>      http://orgmode.org/manual/Feedback.html#Feedback
>
> Your bug report will be posted to the Org-mode mailing list.
> ------------------------------------------------------------------------
>
> Th' manual sez:
>
>   9.1.3 Capture templates
>   -----------------------
>
>   You can use templates for different types of capture items, and for
>   different target locations.  The easiest way to create such templates is
>   through the customize interface.
>
>   `C-c c C'
>        Customize the variable `org-capture-templates'.
>
> I don't know where that keybinding is supposed to come from, but as
> far as I can tell, it isn't set anywhere.  In fact, if we take the
> manual's suggested `C-c c' binding for org-capture, the `C' above just
> does a self-insert in the capture buffer.
>

For me it works fine. I have 'C-c r' bound to (org-capture) and when I
hit C-c r C, I get customize frame.

Thanks and Regards
Noorul

Re: Bug: Bad doc [7.4]

[Nick Dokos]

Dave Abrahams <dave@boostpro.com> wrote:

>   `C-c c C'
>        Customize the variable `org-capture-templates'.
> 
> I don't know where that keybinding is supposed to come from, but as
> far as I can tell, it isn't set anywhere.  In fact, if we take the
> manual's suggested `C-c c' binding for org-capture, the `C' above just
> does a self-insert in the capture buffer.
> 

Works fine here.

It's not a run-of-the-mill keybinding: it's actually dynamically "bound"
(in a manner of speaking) when org-capture gets executed. Assuming you
have bound C-c c to org-capture, then you should get a menu somewhat
like this with C-c c (but note that it will reflect *your* definition of
org-capture-templates; and note also that the menu is constructed at
runtime):

,----
| Select a capture template
| =========================
| 
| [t]     
| [a]     Appts
| [h]     Home
| [w]     Work
| [n]     Notes
| -------------------------------------------------------------------------------
| [C]     Customize org-capture-templates
| [q]     Abort
`----


`C' and `q' are predefined in this menu. The org-capture
code itself looks like this:

--8<---------------cut here---------------start------------->8---
      ...
      (cond
       ((equal entry "C")
	(customize-variable 'org-capture-templates))
       ((equal entry "q")
	(error "Abort"))
      ...
--8<---------------cut here---------------end--------------->8---

Hope that clarifies,
Nick

Re: Bug: Bad doc [7.4]

[Dave Abrahams]

At Mon, 20 Dec 2010 06:22:48 +0000,
Leo wrote:
> 
> On 2010-12-20 06:12 +0000, Dave Abrahams wrote:
> > Th' manual sez:
> >
> >   9.1.3 Capture templates
> >   -----------------------
> >
> >   You can use templates for different types of capture items, and for
> >   different target locations.  The easiest way to create such templates is
> >   through the customize interface.
> >
> >   `C-c c C'
> >        Customize the variable `org-capture-templates'.
> >
> > I don't know where that keybinding is supposed to come from, but as
> > far as I can tell, it isn't set anywhere.  In fact, if we take the
> > manual's suggested `C-c c' binding for org-capture, the `C' above just
> > does a self-insert in the capture buffer.
> 
> No problem here, running 7.4 on 23.2.91.
> 
> You should see something like: http://imgur.com/Bfwlh.png

No, I get no menu, (perhaps because I haven't customized org-capture templates?)

emacs -Q

evaluating the following:

 (add-to-list 'load-path "~/.emacs.d/3rd-party/package.d/org-mode/lisp")
 (load-library "org-capture")
 (setq org-default-notes-file (concat org-directory "/notes.org"))
 (define-key global-map "\C-cc" 'org-capture)

and pressing `\C-c c' gets me a buffer called "CAPTURE-notes.org" containing:

  ** TODO 
     [2010-12-19 Sun]

-- 
Dave Abrahams
BoostPro Computing
http://www.boostpro.com

Re: Bug: Bad doc [7.4]

[Carsten Dominik]

On Dec 20, 2010, at 7:12 AM, Dave Abrahams wrote:

>
>
> Remember to cover the basics, that is, what you expected to happen and
> what in fact did happen.  You don't know how to make a good report?   
> See
>
>     http://orgmode.org/manual/Feedback.html#Feedback
>
> Your bug report will be posted to the Org-mode mailing list.
> ------------------------------------------------------------------------
>
> Th' manual sez:
>
>  9.1.3 Capture templates
>  -----------------------
>
>  You can use templates for different types of capture items, and for
>  different target locations.  The easiest way to create such  
> templates is
>  through the customize interface.
>
>  `C-c c C'
>       Customize the variable `org-capture-templates'.
>
> I don't know where that keybinding is supposed to come from, but as
> far as I can tell, it isn't set anywhere.  In fact, if we take the
> manual's suggested `C-c c' binding for org-capture, the `C' above just
> does a self-insert in the capture buffer.


This is a bit tricky and not fully documented.

If you have no or only only a single template defined, then
template selection is bypassed and you do not get a chance
to press C to get to the customization buffer.  This is to
please John Wiegley :) who only uses a single capture template
and rightfully wanted to lose the extra key press.  As soon
as you have at least 2 templates, you will get the menu and
also the chance to press `C'.

I am not quite sure what to do about it, documenting it makes
things look more complicated as they are.

- Carsten

>
> Emacs  : GNU Emacs 23.2.1 (x86_64-apple-darwin, NS apple- 
> appkit-1038.29)
> of 2010-05-08 on black.local
> Package: Org-mode version 7.4
>
> -- 
> Dave Abrahams
> BoostPro Computing
> http://www.boostpro.com
>
>
> _______________________________________________
> Emacs-orgmode mailing list
> Please use `Reply All' to send replies to the list.
> Emacs-orgmode@gnu.org
> http://lists.gnu.org/mailman/listinfo/emacs-orgmode

Re: Bug: Bad doc [7.4]

[Dave Abrahams]

At Mon, 20 Dec 2010 08:40:50 +0100,
Carsten Dominik wrote:
> 
> This is a bit tricky and not fully documented.
> 
> If you have no or only only a single template defined, then
> template selection is bypassed and you do not get a chance
> to press C to get to the customization buffer.  This is to
> please John Wiegley :) who only uses a single capture template

And I'm using his template, practically unmodified :-)

> and rightfully wanted to lose the extra key press.  

And I like that feature myself.

> As soon
> as you have at least 2 templates, you will get the menu and
> also the chance to press `C'.
> 
> I am not quite sure what to do about it, documenting it makes
> things look more complicated as they are.

Hmm, seems to me that it would be more principled to have org-capture
take an optional argument that indicates the template index, and ask
me and John to bind our key to (lambda () (org-capture 0))

-- 
Dave Abrahams
BoostPro Computing
http://www.boostpro.com

Re: Bug: Bad doc [7.4]

[Dave Abrahams]

This be eine test
-- 
Dave Abrahams
BoostPro Computing
http://www.boostpro.com

Re: Bug: Bad doc [7.4]

[Carsten Dominik]

On Dec 20, 2010, at 9:06 AM, Dave Abrahams wrote:

> At Mon, 20 Dec 2010 08:40:50 +0100,
> Carsten Dominik wrote:
>>
>> This is a bit tricky and not fully documented.
>>
>> If you have no or only only a single template defined, then
>> template selection is bypassed and you do not get a chance
>> to press C to get to the customization buffer.  This is to
>> please John Wiegley :) who only uses a single capture template
>
> And I'm using his template, practically unmodified :-)
>
>> and rightfully wanted to lose the extra key press.
>
> And I like that feature myself.
>
>> As soon
>> as you have at least 2 templates, you will get the menu and
>> also the chance to press `C'.
>>
>> I am not quite sure what to do about it, documenting it makes
>> things look more complicated as they are.
>
> Hmm, seems to me that it would be more principled to have org-capture
> take an optional argument that indicates the template index, and ask
> me and John to bind our key to (lambda () (org-capture 0))

You are right, this is better for consistency.
You can do that already, bind something like (org-capture "t")
where "t" is the selection key.

(define-key global-map "\C-c c"
    (lambda () (interactive) (org-capture "t")))

Thanks.

- Carsten

>
> -- 
> Dave Abrahams
> BoostPro Computing
> http://www.boostpro.com
>

Re: Bug: Bad doc [7.4]

[Dave Abrahams]

At Mon, 20 Dec 2010 15:16:28 +0100,
Carsten Dominik wrote:
> 
> > Hmm, seems to me that it would be more principled to have org-capture
> > take an optional argument that indicates the template index, and ask
> > me and John to bind our key to (lambda () (org-capture 0))
> 
> You are right, this is better for consistency.

Plus, it would fix your documentation :-)

Here's a guideline I use: 

  if you're finding it difficult to document the behavior accurately,
  you probably designed it wrong or maybe you don't even really
  understand what it does.

That has happened to me enough times that it was worth making up a
guideline.

> You can do that already, bind something like (org-capture "t")
> where "t" is the selection key.
> 
> (define-key global-map "\C-c c"
>    (lambda () (interactive) (org-capture "t")))

Thanks; if the behavior is ever updated I will switch to that
arrangement.

-- 
Dave Abrahams
BoostPro Computing
http://www.boostpro.com

Re: Bug: Bad doc [7.4]

[Carsten Dominik]

On Dec 20, 2010, at 5:56 PM, Dave Abrahams wrote:

> At Mon, 20 Dec 2010 15:16:28 +0100,
> Carsten Dominik wrote:
>>
>>> Hmm, seems to me that it would be more principled to have org- 
>>> capture
>>> take an optional argument that indicates the template index, and ask
>>> me and John to bind our key to (lambda () (org-capture 0))
>>
>> You are right, this is better for consistency.
>
> Plus, it would fix your documentation :-)
>
> Here's a guideline I use:
>
>  if you're finding it difficult to document the behavior accurately,
>  you probably designed it wrong or maybe you don't even really
>  understand what it does.
>
> That has happened to me enough times that it was worth making up a
> guideline.
>
>> You can do that already, bind something like (org-capture "t")
>> where "t" is the selection key.
>>
>> (define-key global-map "\C-c c"
>>   (lambda () (interactive) (org-capture "t")))
>
> Thanks; if the behavior is ever updated I will switch to that
> arrangement.

It alreay has been changed

- Carsten