GNU bug report logs - #7499
Documentation: `comint-dynamic-list-filename-completions'

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 7499 in the body.
You can then email your comments to 7499 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: MON KEY <monkey <at> sandpframing.com>
To: bug-gnu-emacs <at> gnu.org
Subject: Documentation: `comint-dynamic-list-filename-completions'
Date: Sat, 27 Nov 2010 12:10:52 -0500

Documentation of `comint-dynamic-list-filename-completions'
current through bzr revision 102504

,---- (documentation 'comint-dynamic-list-filename-completions)
|
| "List in help buffer possible completions of the filename at point."
|
`----

Is the above correct?
On my machine completions appear in "*Completions*" which is only tangentially a
"help buffer".

--
/s_P\

Message #8 received at 7499 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Monnier <monnier <at> IRO.UMontreal.CA>
To: MON KEY <monkey <at> sandpframing.com>
Cc: 7499 <at> debbugs.gnu.org
Subject: Re: bug#7499: Documentation:
	`comint-dynamic-list-filename-completions'
Date: Sat, 27 Nov 2010 13:35:24 -0500

> Documentation of `comint-dynamic-list-filename-completions'
> current through bzr revision 102504

> ,---- (documentation 'comint-dynamic-list-filename-completions)
> |
> | "List in help buffer possible completions of the filename at point."
> |
> `----

> Is the above correct?
> On my machine completions appear in "*Completions*" which is only
> tangentially a "help buffer".

The term "help buffer" is apparently used here loosely to mean
"auxiliary buffer helpful to the user".


        Stefan

Message #11 received at 7499 <at> debbugs.gnu.org (full text, mbox):

From: MON KEY <monkey <at> sandpframing.com>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: 7499 <at> debbugs.gnu.org
Subject: Re: bug#7499: Documentation:
	`comint-dynamic-list-filename-completions'
Date: Sun, 28 Nov 2010 15:46:58 -0500

On Sat, Nov 27, 2010 at 1:35 PM, Stefan Monnier
<monnier <at> iro.umontreal.ca> wrote:

> The term "help buffer" is apparently used here loosely to mean
> "auxiliary buffer helpful to the user".
>

Its less than apparent (to me at least) that such loose usage is helpful. :)

AFAICT `comint-dynamic-list-completions' is hardwired to "*Completions*".

Its docstring is equally suspect:

,---- (documentation 'comint-dynamic-list-completions)
|
|     List in help buffer sorted completions.  The meaning of
|     common-substring is the same as in `display-completion-list'.
|     Typing SPC flushes the help buffer.
|
`----

W/re `comint-dynamic-list-completions',
`comint-dynamic-list-filename-completions' (and any other similar such
comint docstrings), what would prob. be more "helpful to the user"
would be to explicitly document that return value is to
"*Completions*". :)

After all, there is no provision for an alternative destination
stream.  Indeed, it is doubtful such alternatives could be made
available via `comint-dynamic-list-completions' given the complicated
interactions between windows/buffers/configurations and the dynamic bindings of
`standard-output' happening around the internal calls to
`display-completion-list' and `with-output-to-temp-buffer'.

>        Stefan

--
/s_P\

Message #14 received at 7499 <at> debbugs.gnu.org (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: "'MON KEY'" <monkey <at> sandpframing.com>,
	"'Stefan Monnier'" <monnier <at> iro.umontreal.ca>
Cc: 7499 <at> debbugs.gnu.org
Subject: RE: bug#7499: Documentation:
	`comint-dynamic-list-filename-completions'
Date: Sun, 28 Nov 2010 14:42:32 -0800

> > The term "help buffer" is apparently used here loosely to mean
> > "auxiliary buffer helpful to the user".
> 
> Its less than apparent (to me at least) that such loose usage 
> is helpful. :) AFAICT `comint-dynamic-list-completions' is
> hardwired to "*Completions*".

I haven't been following this thread (and no doubt will not follow it).  But if
the buffer is `*Completions*' then it is clearest for the doc to say so
explicitly.  Saying "help buffer" or even "some auxilliary buffer helpful to the
user" just muddies the water.  No need to defend that text; just use "buffer
`*Completions*'" or "window `*Completions*'" (depending on the context).

Message #17 received at 7499 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Monnier <monnier <at> IRO.UMontreal.CA>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: 7499 <at> debbugs.gnu.org, 'MON KEY' <monkey <at> sandpframing.com>
Subject: Re: bug#7499: Documentation:
	`comint-dynamic-list-filename-completions'
Date: Sun, 28 Nov 2010 20:35:52 -0500

> I haven't been following this thread (and no doubt will not follow
> it).  But if the buffer is `*Completions*' then it is clearest for the
> doc to say so explicitly.  Saying "help buffer" or even "some
> auxilliary buffer helpful to the user" just muddies the water.
> No need to defend that text; just use "buffer `*Completions*'" or
> "window `*Completions*'" (depending on the context).

I'd argue instead that there is no reason for that text to say where
it's going to be displayed.
So I'd replace "List in help buffer sorted completions" with something
like "Display sorted completions".


        Stefan

Message #20 received at 7499 <at> debbugs.gnu.org (full text, mbox):

From: MON KEY <monkey <at> sandpframing.com>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: 7499 <at> debbugs.gnu.org, Drew Adams <drew.adams <at> oracle.com>
Subject: Re: bug#7499: Documentation:
	`comint-dynamic-list-filename-completions'
Date: Sun, 28 Nov 2010 22:02:40 -0500

On Sun, Nov 28, 2010 at 8:35 PM, Stefan Monnier
<monnier <at> iro.umontreal.ca> wrote:
>> No need to defend that text; just use "buffer `*Completions*'" or
>> "window `*Completions*'" (depending on the context).
>
> I'd argue instead that there is no reason for that text to say where
> it's going to be displayed.

Once one has left the immediate locus of the `comint-*' callers it is
good to know
what/where these gals do their business.

> So I'd replace "List in help buffer sorted completions" with something
> like "Display sorted completions".

OK. It makes sense to leave from for future changes.
But, there is third party code that uses this feature:
Their users may deserve some consideration...

`slime-maybe-complete-as-filename'
 `-> `comint-replace-by-expanded-filename'
   `-> `comint-dynamic-complete-filename'
     `-> `comint-dynamic-complete-as-filename'
       `-> `comint-dynamic-list-filename-completions'
         `-> `comint-dynamic-list-completions'

Do an occur for "slime-complete-*" in slime.el
Also, take a look at `slime-completions-buffer-name'.

I'm sure there are other non-core libs which make similar use of `comint-*'...

>        Stefan

--
/s_P\

Message #23 received at 7499 <at> debbugs.gnu.org (full text, mbox):

From: Chong Yidong <cyd <at> stupidchicken.com>
To: MON KEY <monkey <at> sandpframing.com>
Cc: 7499 <at> debbugs.gnu.org, Stefan Monnier <monnier <at> iro.umontreal.ca>
Subject: Re: bug#7499: Documentation:
	`comint-dynamic-list-filename-completions'
Date: Sat, 04 Dec 2010 19:55:23 -0500

MON KEY <monkey <at> sandpframing.com> writes:

>> The term "help buffer" is apparently used here loosely to mean
>> "auxiliary buffer helpful to the user".
>>
>
> Its less than apparent (to me at least) that such loose usage is helpful. :)

I've checked in a fix for this, and related docstrings.  Thanks.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.