bug#24663: 24.5; doc string of `completion-at-point-functions'

bug#24663: 24.5; doc string of `completion-at-point-functions'

[Drew Adams]

1. Some lines are too long.  Please use fill-column=70 for ordinary
paragraphs.

2. Typo: "in turns" should be ", in turn," (no "s").

3. "the thing at point" means nothing.  Thing at point means something
only for a given type of THING.  There is not just one ("the") thing
at point.

Presumably what is meant here is not a thing at point but some text
preceding point.  It is some text before point that is completed.

4. Add a comma after "nil".

5. Typo: "function of no argument" should be "function of no arguments".

6. " where" should be ", where:" (and that sentence is run-on (too
long).

7. "responsible to preserve" should be "responsible for preserving".


In GNU Emacs 24.5.1 (i686-pc-mingw32)
 of 2015-04-11 on LEG570
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --prefix=/c/usr --host=i686-pc-mingw32'

bug#24663: 24.5; doc string of `completion-at-point-functions'

[Eli Zaretskii]

> Date: Mon, 10 Oct 2016 14:14:52 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> 
> 1. Some lines are too long.  Please use fill-column=70 for ordinary
> paragraphs.

Done.

> 2. Typo: "in turns" should be ", in turn," (no "s").

This was already fixed in Emacs 25.1.

> 3. "the thing at point" means nothing.  Thing at point means something
> only for a given type of THING.  There is not just one ("the") thing
> at point.
> 
> Presumably what is meant here is not a thing at point but some text
> preceding point.  It is some text before point that is completed.

I don't understand what are you saying here.  Sure, it's some text at
point, but the form of that text might describe a symbol, an
expression, a string, etc.

I changed that to say "the entity at point" because the rest of the
doc string refers to that.

> 4. Add a comma after "nil".

Added.

> 5. Typo: "function of no argument" should be "function of no arguments".

Fixed.

> 6. " where" should be ", where:" (and that sentence is run-on (too
> long).

Done.

> 7. "responsible to preserve" should be "responsible for preserving".

Done.

Thanks.

bug#24663: 24.5; doc string of `completion-at-point-functions'

[Drew Adams]

> > 3. "the thing at point" means nothing.  Thing at point means something
> > only for a given type of THING.  There is not just one ("the") thing
> > at point.
> >
> > Presumably what is meant here is not a thing at point but some text
> > preceding point.  It is some text before point that is completed.
> 
> I don't understand what are you saying here.  Sure, it's some text at
> point, but the form of that text might describe a symbol, an
> expression, a string, etc.
> 
> I changed that to say "the entity at point" because the rest of the
> doc string refers to that.

1. It cannot be "THE" thing (or THE entity) at point.  Which one?
You can get different kinds of thing at point.  You must provide
the desired THING type, for "thing at point" to mean anything.
How is the type of thing (or entity) decided, here?  If the user
is not specifying it (which I think is the case) then the doc
should say something about how the type is chosen.

2. I don't see how/why saying "entity" changes anything, here.
"THE" entity?  What is that?

3. It is not text AT point that is completed.  It is text BEFORE
point that is completed.  AT can only refer to characters after
point, not before.

bug#24663: 24.5; doc string of `completion-at-point-functions'

[Eli Zaretskii]

> Date: Thu, 13 Oct 2016 12:46:19 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 24663-done@debbugs.gnu.org
> 
> > I changed that to say "the entity at point" because the rest of the
> > doc string refers to that.
> 
> 1. It cannot be "THE" thing (or THE entity) at point.  Which one?

The one at point.

> You can get different kinds of thing at point.  You must provide
> the desired THING type, for "thing at point" to mean anything.

My understanding is that it's up to the hooks.

> 2. I don't see how/why saying "entity" changes anything, here.
> "THE" entity?  What is that?

Then I guess I will say that I don't want to fix that part.

> 3. It is not text AT point that is completed.  It is text BEFORE
> point that is completed.  AT can only refer to characters after
> point, not before.

The doc string doesn't say "text", it says "entity".  IOW, it doesn't
talk about characters.

bug#24663: 24.5; doc string of `completion-at-point-functions'

[Drew Adams]

> > > I changed that to say "the entity at point" because the rest of the
> > > doc string refers to that.
> >
> > 1. It cannot be "THE" thing (or THE entity) at point.  Which one?
> 
> The one at point.

The symbol? word? file name? URL? ... (yes, ... - there are any
number of kinds of things, most of which - nay, all of which - 
could be completed.

> > You can get different kinds of thing at point.  You must provide
> > the desired THING type, for "thing at point" to mean anything.
> 
> My understanding is that it's up to the hooks.

Then them most that the doc can & should say is that SOMETHING
(some text) BEFORE point, is susceptible to completion.

> > 2. I don't see how/why saying "entity" changes anything, here.
> > "THE" entity?  What is that?
> 
> Then I guess I will say that I don't want to fix that part.

I got that.

> > 3. It is not text AT point that is completed.  It is text BEFORE
> > point that is completed.  AT can only refer to characters after
> > point, not before.
> 
> The doc string doesn't say "text", it says "entity".  IOW, it doesn't
> talk about characters.

What else is before point, besides characters?  What else gets
completed, besides text?

OK, presumably a face or other text or overlay property, or a marker,
before point could perhaps lead to some kind of completion.  What
that might amount to is anyone's guess.  I don't think non-text
completion is really what `completion-at-point-functions' is about
(or has been about).  It certainly isn't something that the doc
string should imagine.

bug#24663: 24.5; doc string of `completion-at-point-functions'

[Dmitry Gutov]

On 13.10.2016 23:33, Drew Adams wrote:

>>> 1. It cannot be "THE" thing (or THE entity) at point.  Which one?
>>
>> The one at point.
>
> The symbol? word? file name? URL? ... (yes, ... - there are any
> number of kinds of things, most of which - nay, all of which -
> could be completed.

The code in the hooks decides that. In practice, it's a part of a major 
or a minor mode.

>> My understanding is that it's up to the hooks.
>
> Then them most that the doc can & should say is that SOMETHING

What does that mean?

> (some text) BEFORE point, is susceptible to completion.

AROUND point.

bug#24663: 24.5; doc string of `completion-at-point-functions'

[Drew Adams]

> >>> 1. It cannot be "THE" thing (or THE entity) at point.  Which one?
> >>
> >> The one at point.
> >
> > The symbol? word? file name? URL? ... (yes, ... - there are any
> > number of kinds of things, most of which - nay, all of which -
> > could be completed.
> 
> The code in the hooks decides that. In practice, it's a part of a major
> or a minor mode.

Exactly.  That's what should be said.

Some text before point can get completed.  The completing code
decides (1) WHICH text before point (what kind of thing, if you
want to think of it that way) and (2) what the possible
COMPLETIONS of it are.

> >> My understanding is that it's up to the hooks.
> >
> > Then them most that the doc can & should say is that SOMETHING
> 
> What does that mean?
> 
> > (some text) BEFORE point, is susceptible to completion.
> 
> AROUND point.

Really?  In that case, that's what needs to be said in the doc.

Of course, if it is AROUND point then presumably any text in the
buffer can be used to determine what's to be completed (and in
turn what the possible completions are).  It could use only the
first two or last six characters of the buffer, ignoring the
text immediately surrounding point.

It sounds like the real point (sic) is this: The completion
functions (1) are passed point, and (2) they can do anything
they want, to complete any bits of text existing anywhere in
the buffer (or even perhaps ignoring all text in the buffer).
And presumably, after the user chooses one of the completion
candidates, that candidate is inserted at point.

If this (or similar0 is the behavior then it is what should
be said in the doc.  There should be nothing additional and
gratuitous, that implies that the text immediately preceding
or following (or both) point is what gets completed.  And
it certainly should not speak in terms of any "thing" or
"entity" at (or before or after or around) point.

bug#24663: 24.5; doc string of `completion-at-point-functions'

[Dmitry Gutov]

On 14.10.2016 00:18, Drew Adams wrote:

>> AROUND point.
>
> Really?  In that case, that's what needs to be said in the doc.
>
> Of course, if it is AROUND point then presumably any text in the
> buffer can be used to determine what's to be completed (and in
> turn what the possible completions are).  It could use only the
> first two or last six characters of the buffer, ignoring the
> text immediately surrounding point.

Not really. The region to complete has to include the point.

bug#24663: 24.5; doc string of `completion-at-point-functions'

[Drew Adams]

> >> AROUND point.
> >
> > Really?  In that case, that's what needs to be said in the doc.
> >
> > Of course, if it is AROUND point then presumably any text in the
> > buffer can be used to determine what's to be completed (and in
> > turn what the possible completions are).  It could use only the
> > first two or last six characters of the buffer, ignoring the
> > text immediately surrounding point.
> 
> Not really. The region to complete has to include the point.

The entire text in the buffer is AROUND point and includes point.

But maybe you are mentioning another part of the behavior: some
text around point is REPLACED by one of the completion candidates.

If that is part of the behavior then that too should be mentioned
in the doc.