org-iswitchb documentation

org-iswitchb documentation

[Stephen Eglen]

Dear all,

As the author of iswitchb, I was very happy to see M-x org-iswitchb
included.  Further, it is recommended as a default keybinding in the
manual:

----------------------------------------------------------------------
1.3 Activation
==============

...
     (add-to-list 'auto-mode-alist '("\\.org\\'" . org-mode))
     (global-set-key "\C-cl" 'org-store-link)
     (global-set-key "\C-ca" 'org-agenda)
     (global-set-key "\C-cb" 'org-iswitchb)
----------------------------------------------------------------------

So I was surprised when trying org-iswitchb that I didn't see the
iswitchb feedback when typing buffer names.  I eventually found that I
needed to set either of the following variables to t so that this would
work:

  org-completion-use-iswitchb, org-completion-use-ido

These variables are not mentioned in the docstrings of either
org-iswitchb or org-icompleting-read.   Here is a suggested patch to the
docstring for org-iswitchb.

Thanks for all the good work, as ever!

Stephen

$ git diff org.el

diff --git a/lisp/org.el b/lisp/org.el
index 7bb4f45..67e0278 100644
--- a/lisp/org.el
+++ b/lisp/org.el
@@ -15201,7 +15201,13 @@ changes from another.  I believe the procedure must be l
 (defun org-iswitchb (&optional arg)
   "Use `org-icompleting-read' to prompt for an Org buffer to switch to.
 With a prefix argument, restrict available to files.
-With two prefix arguments, restrict available buffers to agenda files."
+With two prefix arguments, restrict available buffers to agenda files.
+
+To see feedback whilst typing the buffer name, you can use the
+facilities of either the ido or iswitchb package.  Set either
+`org-completion-use-iswitchb' or `org-completion-use-ido' to
+non-nil and see documentation of those variables for further
+details."
   (interactive "P")
   (let ((blist (cond ((equal arg '(4))  (org-buffer-list 'files))
                      ((equal arg '(16)) (org-buffer-list 'agenda))

Re: org-iswitchb documentation

[Livin Stephen Sharma]

Thanks for mentioning these variables!
 I checked and found that the 'completion' variables were set in a way that gave me the C-c b behavior that i did not like/want.

I have now added this to my org init file:
> (setq org-completion-use-iswitchb t)
> (setq org-completion-use-ido nil)


Regards
Livin Stephen Sharma

On Jun 28, 2010, at 15:49:50 , Stephen Eglen wrote:

> Dear all,
> 
> As the author of iswitchb, I was very happy to see M-x org-iswitchb
> included.  Further, it is recommended as a default keybinding in the
> manual:
> 
> ----------------------------------------------------------------------
> 1.3 Activation
> ==============
> 
> ...
>     (add-to-list 'auto-mode-alist '("\\.org\\'" . org-mode))
>     (global-set-key "\C-cl" 'org-store-link)
>     (global-set-key "\C-ca" 'org-agenda)
>     (global-set-key "\C-cb" 'org-iswitchb)
> ----------------------------------------------------------------------
> 
> So I was surprised when trying org-iswitchb that I didn't see the
> iswitchb feedback when typing buffer names.  I eventually found that I
> needed to set either of the following variables to t so that this would
> work:
> 
>  org-completion-use-iswitchb, org-completion-use-ido
> 
> These variables are not mentioned in the docstrings of either
> org-iswitchb or org-icompleting-read.   Here is a suggested patch to the
> docstring for org-iswitchb.
> 
> Thanks for all the good work, as ever!
> 
> Stephen
> 
> $ git diff org.el
> 
> diff --git a/lisp/org.el b/lisp/org.el
> index 7bb4f45..67e0278 100644
> --- a/lisp/org.el
> +++ b/lisp/org.el
> @@ -15201,7 +15201,13 @@ changes from another.  I believe the procedure must be l
> (defun org-iswitchb (&optional arg)
>   "Use `org-icompleting-read' to prompt for an Org buffer to switch to.
> With a prefix argument, restrict available to files.
> -With two prefix arguments, restrict available buffers to agenda files."
> +With two prefix arguments, restrict available buffers to agenda files.
> +
> +To see feedback whilst typing the buffer name, you can use the
> +facilities of either the ido or iswitchb package.  Set either
> +`org-completion-use-iswitchb' or `org-completion-use-ido' to
> +non-nil and see documentation of those variables for further
> +details."
>   (interactive "P")
>   (let ((blist (cond ((equal arg '(4))  (org-buffer-list 'files))
>                      ((equal arg '(16)) (org-buffer-list 'agenda))
> 
> _______________________________________________
> 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: org-iswitchb documentation

[Carsten Dominik]

Hi Stephen,

I think this is actually a bug.  Since the command is called ...- 
iswitchb,
I am sure the intention was to use iswitchbe.  Later, when we added ido
support as well, the function was rewritten using
org-icompleting-read, and in this way the iswitchb support was lost.


How about the following solution:

Check if either of org-completion-use-\(ido\|iswitchb\) is set.  If not,
bind org-completion-use-iswitchb around the call to org-icompleting- 
read.

- Carsten

On Jun 28, 2010, at 12:19 PM, Stephen Eglen wrote:

> Dear all,
>
> As the author of iswitchb, I was very happy to see M-x org-iswitchb
> included.  Further, it is recommended as a default keybinding in the
> manual:
>
> ----------------------------------------------------------------------
> 1.3 Activation
> ==============
>
> ...
>     (add-to-list 'auto-mode-alist '("\\.org\\'" . org-mode))
>     (global-set-key "\C-cl" 'org-store-link)
>     (global-set-key "\C-ca" 'org-agenda)
>     (global-set-key "\C-cb" 'org-iswitchb)
> ----------------------------------------------------------------------
>
> So I was surprised when trying org-iswitchb that I didn't see the
> iswitchb feedback when typing buffer names.  I eventually found that I
> needed to set either of the following variables to t so that this  
> would
> work:
>
>  org-completion-use-iswitchb, org-completion-use-ido
>
> These variables are not mentioned in the docstrings of either
> org-iswitchb or org-icompleting-read.   Here is a suggested patch to  
> the
> docstring for org-iswitchb.
>
> Thanks for all the good work, as ever!
>
> Stephen
>
> $ git diff org.el
>
> diff --git a/lisp/org.el b/lisp/org.el
> index 7bb4f45..67e0278 100644
> --- a/lisp/org.el
> +++ b/lisp/org.el
> @@ -15201,7 +15201,13 @@ changes from another.  I believe the  
> procedure must be l
> (defun org-iswitchb (&optional arg)
>   "Use `org-icompleting-read' to prompt for an Org buffer to switch  
> to.
> With a prefix argument, restrict available to files.
> -With two prefix arguments, restrict available buffers to agenda  
> files."
> +With two prefix arguments, restrict available buffers to agenda  
> files.
> +
> +To see feedback whilst typing the buffer name, you can use the
> +facilities of either the ido or iswitchb package.  Set either
> +`org-completion-use-iswitchb' or `org-completion-use-ido' to
> +non-nil and see documentation of those variables for further
> +details."
>   (interactive "P")
>   (let ((blist (cond ((equal arg '(4))  (org-buffer-list 'files))
>                      ((equal arg '(16)) (org-buffer-list 'agenda))
>
> _______________________________________________
> 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

- Carsten

Re: org-iswitchb documentation

[Stephen Eglen]

Carsten Dominik <carsten.dominik@gmail.com> wrote:

> I think this is actually a bug.  Since the command is called ...-
> iswitchb,
> I am sure the intention was to use iswitchbe.  Later, when we added ido
> support as well, the function was rewritten using
> org-icompleting-read, and in this way the iswitchb support was lost.
> 
> 
> How about the following solution:
> 
> Check if either of org-completion-use-\(ido\|iswitchb\) is set.  If not,
> bind org-completion-use-iswitchb around the call to org-icompleting-
> read.

Ok, now that makes a lot more sense!  I wondered why the
'out-of-the-box' behaviour didn't show iswitchb like behaviour.

Stephen

Re: org-iswitchb documentation

[Stephen Eglen]

Carsten Dominik <carsten.dominik@gmail.com> wrote:

> Hi Stephen,
> 
> I think this is actually a bug.  Since the command is called ...-
> iswitchb,
> I am sure the intention was to use iswitchbe.  Later, when we added ido
> support as well, the function was rewritten using
> org-icompleting-read, and in this way the iswitchb support was lost.

p.s. one day I might imagine that iswitchb.el might disappear and be
replaced by ido.el, which might make life easier, assuming that iswitchb
hasn't diverged too much since Kim first made ido.el.

What do you think Kim - should we just have ido.el in the emacs sources,
and have iswitchb-mode configure ido.el to just do buffer searching?

(Sorry Kim, this is a thread on emacs-orgmode,
http://article.gmane.org/gmane.emacs.orgmode/26723)

best wishes, Stephen

Re: org-iswitchb documentation

[Kim F. Storm]

Stephen Eglen <S.J.Eglen@damtp.cam.ac.uk> writes:

> Carsten Dominik <carsten.dominik@gmail.com> wrote:
>
>> Hi Stephen,
>> 
>> I think this is actually a bug.  Since the command is called ...-
>> iswitchb,
>> I am sure the intention was to use iswitchbe.  Later, when we added ido
>> support as well, the function was rewritten using
>> org-icompleting-read, and in this way the iswitchb support was lost.
>
> p.s. one day I might imagine that iswitchb.el might disappear and be
> replaced by ido.el, which might make life easier, assuming that iswitchb
> hasn't diverged too much since Kim first made ido.el.

I haven't really followed iswitchb developments since I branched ido
from it (many full moons ago), so I don't know how much they have
diverted since them. I may have added some stuff on request from users,
but that was also a long time ago...

>
> What do you think Kim - should we just have ido.el in the emacs
>sources, and have iswitchb-mode configure ido.el to just do buffer
>searching?

This sounds like a good idea - but I don't have time to look at it
anytime soon.

I guess the main task (besides migrating any newer features of iswitchb
to ido) is to find out which ido settings should be used for iswitchb
customizations.

>
> (Sorry Kim, this is a thread on emacs-orgmode,
> http://article.gmane.org/gmane.emacs.orgmode/26723)
>
> best wishes, Stephen
>
>

-- 
Kim F. Storm  http://www.cua.dk

Re: org-iswitchb documentation

[Carsten Dominik]

On Jun 28, 2010, at 2:26 PM, Stephen Eglen wrote:

> Carsten Dominik <carsten.dominik@gmail.com> wrote:
>
>> I think this is actually a bug.  Since the command is called ...-
>> iswitchb,
>> I am sure the intention was to use iswitchbe.  Later, when we added  
>> ido
>> support as well, the function was rewritten using
>> org-icompleting-read, and in this way the iswitchb support was lost.
>>
>>
>> How about the following solution:
>>
>> Check if either of org-completion-use-\(ido\|iswitchb\) is set.  If  
>> not,
>> bind org-completion-use-iswitchb around the call to org-icompleting-
>> read.
>
> Ok, now that makes a lot more sense!  I wondered why the
> 'out-of-the-box' behaviour didn't show iswitchb like behaviour.

THe doc string now reads:

   "Use `org-icompleting-read' to prompt for an Org buffer to switch to.
With a prefix argument, restrict available to files.
With two prefix arguments, restrict available buffers to agenda files.

This will either use ido or iswitchb for buffer name completion,
depending on the variables `org-completion-use-iswitchb' and
`org-completion-use-ido'.  If both are nil, we will still use iswitchb
for this special application."

Agreed?

- Carsten

Re: org-iswitchb documentation

[Stephen Eglen]

> THe doc string now reads:
> 
>   "Use `org-icompleting-read' to prompt for an Org buffer to switch to.
> With a prefix argument, restrict available to files.
> With two prefix arguments, restrict available buffers to agenda files.
> 
> This will either use ido or iswitchb for buffer name completion,
> depending on the variables `org-completion-use-iswitchb' and
> `org-completion-use-ido'.  If both are nil, we will still use iswitchb
> for this special application."

Hmmm... this sounds a bit confusing!  why not just have
org-completion-use-ido, and if that is non-nil, we use ido, else we use
iswitchb.  Unless these variables are also used in other contexts (which
I doubt)?

how about changing the 2nd para to:

  This will use iswitchb for buffer name completion, unless 
  `org-completion-use-ido' is non-nil, to select ido completion

Stephen

Re: org-iswitchb documentation

[Carsten Dominik]

On Jun 29, 2010, at 10:14 AM, Stephen Eglen wrote:

>> THe doc string now reads:
>>
>>  "Use `org-icompleting-read' to prompt for an Org buffer to switch  
>> to.
>> With a prefix argument, restrict available to files.
>> With two prefix arguments, restrict available buffers to agenda  
>> files.
>>
>> This will either use ido or iswitchb for buffer name completion,
>> depending on the variables `org-completion-use-iswitchb' and
>> `org-completion-use-ido'.  If both are nil, we will still use  
>> iswitchb
>> for this special application."
>
> Hmmm... this sounds a bit confusing!  why not just have
> org-completion-use-ido, and if that is non-nil, we use ido, else we  
> use
> iswitchb.  Unless these variables are also used in other contexts  
> (which
> I doubt)?

Oh yes, the are used in *many* contexts.  Whenever Org offers
completion which would not be made worse by using one of these packages,
it will offer that special kind of completion.

>
> how about changing the 2nd para to:
>
>  This will use iswitchb for buffer name completion, unless
>  `org-completion-use-ido' is non-nil, to select ido completion

Yes, this is much better.

Thanks

- Carsten

>
> Stephen
>
>

- Carsten

Re: org-iswitchb documentation

[Richard Riley]

Carsten Dominik <carsten.dominik@gmail.com> writes:

> On Jun 29, 2010, at 10:14 AM, Stephen Eglen wrote:
>
>>> THe doc string now reads:
>>>
>>>  "Use `org-icompleting-read' to prompt for an Org buffer to switch  
>>> to.
>>> With a prefix argument, restrict available to files.
>>> With two prefix arguments, restrict available buffers to agenda  
>>> files.
>>>
>>> This will either use ido or iswitchb for buffer name completion,
>>> depending on the variables `org-completion-use-iswitchb' and
>>> `org-completion-use-ido'.  If both are nil, we will still use  
>>> iswitchb
>>> for this special application."
>>
>> Hmmm... this sounds a bit confusing!  why not just have
>> org-completion-use-ido, and if that is non-nil, we use ido, else we  
>> use
>> iswitchb.  Unless these variables are also used in other contexts  
>> (which
>> I doubt)?
>
> Oh yes, the are used in *many* contexts.  Whenever Org offers
> completion which would not be made worse by using one of these packages,
> it will offer that special kind of completion.
>
>>
>> how about changing the 2nd para to:
>>
>>  This will use iswitchb for buffer name completion, unless
>>  `org-completion-use-ido' is non-nil, to select ido completion

I would suggest changing the function name to org-switchb (alias
org-iswitchb to use it) and then the documentation reads:

,----
| Switches between org buffers. Defaults to  iswitchb for buffer name
| completion. Set `org-completion-use-ido' to  non nil to use ido
| completion instead.
`----

As an aside I found iswitchb to be a subset of ido and the ido fuzzy
completion invaluable in refiling to various org targets.

Re: Re: org-iswitchb documentation

[Carsten Dominik]

On Jun 29, 2010, at 11:44 AM, Richard Riley wrote:

> Carsten Dominik <carsten.dominik@gmail.com> writes:
>
>> On Jun 29, 2010, at 10:14 AM, Stephen Eglen wrote:
>>
>>>> THe doc string now reads:
>>>>
>>>> "Use `org-icompleting-read' to prompt for an Org buffer to switch
>>>> to.
>>>> With a prefix argument, restrict available to files.
>>>> With two prefix arguments, restrict available buffers to agenda
>>>> files.
>>>>
>>>> This will either use ido or iswitchb for buffer name completion,
>>>> depending on the variables `org-completion-use-iswitchb' and
>>>> `org-completion-use-ido'.  If both are nil, we will still use
>>>> iswitchb
>>>> for this special application."
>>>
>>> Hmmm... this sounds a bit confusing!  why not just have
>>> org-completion-use-ido, and if that is non-nil, we use ido, else we
>>> use
>>> iswitchb.  Unless these variables are also used in other contexts
>>> (which
>>> I doubt)?
>>
>> Oh yes, the are used in *many* contexts.  Whenever Org offers
>> completion which would not be made worse by using one of these  
>> packages,
>> it will offer that special kind of completion.
>>
>>>
>>> how about changing the 2nd para to:
>>>
>>> This will use iswitchb for buffer name completion, unless
>>> `org-completion-use-ido' is non-nil, to select ido completion
>
> I would suggest changing the function name to org-switchb (alias
> org-iswitchb to use it) and then the documentation reads:

This is a good proposal, but I prefer to not change the names of
commands unless really necessary.  Changing it will break the
config of users.

- Carsten

>
> ,----
> | Switches between org buffers. Defaults to  iswitchb for buffer name
> | completion. Set `org-completion-use-ido' to  non nil to use ido
> | completion instead.
> `----
>
> As an aside I found iswitchb to be a subset of ido and the ido fuzzy
> completion invaluable in refiling to various org targets.
>
>
>
> _______________________________________________
> 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

- Carsten

Re: org-iswitchb documentation

[Eric S Fraga]

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

On Tue, 29 Jun 2010 09:26:57 +0200, Carsten Dominik <carsten.dominik@gmail.com> wrote:

[...]

> THe doc string now reads:
> 
>   "Use `org-icompleting-read' to prompt for an Org buffer to switch to.
> With a prefix argument, restrict available to files.
> With two prefix arguments, restrict available buffers to agenda files.

Carsten,

apologies if I'm being a little slow here but I really do not
understand this first paragraph!  Specifically, I believe the grammar
to be wrong in the last 2 sentences, possibly because you mean
"availability" instead of "available" or "to available" instead of
"available to", but I cannot be sure nor can I suggest an improvement
because I actually do not know what they are intending to say.  Sorry!

[-- Attachment #2: Type: text/plain, Size: 75 bytes --]

-- 
Eric S Fraga
GnuPG: 8F5C 279D 3907 E14A 5C29  570D C891 93D8 FFFC F67D

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

_______________________________________________
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: Re: org-iswitchb documentation

[Carsten Dominik]

On Jun 29, 2010, at 11:44 AM, Richard Riley wrote:

> Carsten Dominik <carsten.dominik@gmail.com> writes:
>
>> On Jun 29, 2010, at 10:14 AM, Stephen Eglen wrote:
>>
>>>> THe doc string now reads:
>>>>
>>>> "Use `org-icompleting-read' to prompt for an Org buffer to switch
>>>> to.
>>>> With a prefix argument, restrict available to files.
>>>> With two prefix arguments, restrict available buffers to agenda
>>>> files.
>>>>
>>>> This will either use ido or iswitchb for buffer name completion,
>>>> depending on the variables `org-completion-use-iswitchb' and
>>>> `org-completion-use-ido'.  If both are nil, we will still use
>>>> iswitchb
>>>> for this special application."
>>>
>>> Hmmm... this sounds a bit confusing!  why not just have
>>> org-completion-use-ido, and if that is non-nil, we use ido, else we
>>> use
>>> iswitchb.  Unless these variables are also used in other contexts
>>> (which
>>> I doubt)?
>>
>> Oh yes, the are used in *many* contexts.  Whenever Org offers
>> completion which would not be made worse by using one of these  
>> packages,
>> it will offer that special kind of completion.
>>
>>>
>>> how about changing the 2nd para to:
>>>
>>> This will use iswitchb for buffer name completion, unless
>>> `org-completion-use-ido' is non-nil, to select ido completion
>
> I would suggest changing the function name to org-switchb (alias
> org-iswitchb to use it) and then the documentation reads:
>
> ,----
> | Switches between org buffers. Defaults to  iswitchb for buffer name
> | completion. Set `org-completion-use-ido' to  non nil to use ido
> | completion instead.
> `----

Richard, Eric, sorry for not listening earlier, you are right, and I am
npw following Richard's proposal for both naming and docstring.

- Carsten