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

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

[MON KEY]

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\

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

[Stefan Monnier]

> 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

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

[MON KEY]

On Sat, Nov 27, 2010 at 1:35 PM, Stefan Monnier
<monnier@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\

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

[Drew Adams]

> > 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).

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

[Stefan Monnier]

> 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

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

[MON KEY]

On Sun, Nov 28, 2010 at 8:35 PM, Stefan Monnier
<monnier@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\

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

[Chong Yidong]

MON KEY <monkey@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.