bug#66147: 28.2; Doc of completion functions: (elisp) `Basic Completion'

bug#66147: 28.2; Doc of completion functions: (elisp) `Basic Completion'

[Drew Adams]

What seems missing from this doc (and likewise from the relevant doc
strings) is any description of what it means for a string to _match_
entries in the completion table.

(To be included in an `all-completions' result, or for `try-completion'
or `test-completion' to succeed, successful matches _also_ need to
satisfy the regexps in `completion-regexp-list' and satisfy the
PREDICATE arg.  But those additional, optional conditions are well
enough described - not a problem.)

The information I think is missing is that the basic _matching_ is
literal-prefix completion, that is, string equality between the input
STRING and a prefix of a COLLECTION element (with symbols being treated
as their names etc.).

This should be explicitly pointed out, I think.  There's no regexp
matching, and no substring matching, for example -- nothing but
comparison of the INPUT string literally against the prefixes of the
candidates.

IOW (I think), the matching is this:

 (string-match-p (format "\\`%s" (regexp-quote STRING)) CANDIDATE)

Whether or not that's exactly the matching used, the point is that
whatever kind of matching is used is _not described/specified_.  It
needs to be, for users to understand how these "basic completion
functions" behave.

(One could even mistakenly guess that these functions are sensitive to
the value of `completion-style', so that if that's `substring' then
substring matching would be used.)

In the beginning, Emacs completion used _only_ such literal-prefix
completion, so maybe back then not specifying how an input string is
matched against a completion candidate might not have been so
important.  But nowadays users encounter all kinds of matching when
completing: from substring to flex to regexp,...  They're familiar with
that interactively, as Emacs users, typically long before they encounter
programming with the completion functions described here.


In GNU Emacs 28.2 (build 2, x86_64-w64-mingw32)
 of 2022-09-13 built on AVALON
Windowing system distributor 'Microsoft Corp.', version 10.0.19045
System Description: Microsoft Windows 10 Pro (v10.0.2009.19045.3324)

Configured using:
 'configure --with-modules --without-dbus --with-native-compilation
 --without-compress-install CFLAGS=-O2'

Configured features:
ACL GIF GMP GNUTLS HARFBUZZ JPEG JSON LCMS2 LIBXML2 MODULES NATIVE_COMP
NOTIFY W32NOTIFY PDUMPER PNG RSVG SOUND THREADS TIFF TOOLKIT_SCROLL_BARS
XPM ZLIB

(NATIVE_COMP present but libgccjit not available)

bug#66147: 28.2; Doc of completion functions: (elisp) `Basic Completion'

[Eli Zaretskii]

> From: Drew Adams <drew.adams@oracle.com>
> Date: Thu, 21 Sep 2023 21:45:32 +0000
> 
> What seems missing from this doc (and likewise from the relevant doc
> strings) is any description of what it means for a string to _match_
> entries in the completion table.

"Basic Completion" is a subsection of "Completion".  The parent
section explains what it means to match, by describing what does it
mean to "complete" something.

So I think you are looking for a problem where there is none, by
taking a single word (which generally has many different meanings in
Emacs) and trying to interpret it by looking at the manual through a
loophole, instead of taking the broader view by going to the beginning
of the section and reading from there.

IOW, if someone reads on "Basic Completion", he or she needs to
understand the terminology already; otherwise, they should start from
the parent section.

> In the beginning, Emacs completion used _only_ such literal-prefix
> completion, so maybe back then not specifying how an input string is
> matched against a completion candidate might not have been so
> important.  But nowadays users encounter all kinds of matching when
> completing: from substring to flex to regexp,...  They're familiar with
> that interactively, as Emacs users, typically long before they encounter
> programming with the completion functions described here.

This seems to talk about something other than basic completion, so is
not relevant here.  And when a completion style does something other
than the simple prefix matching, the style's documentation should
state that (and it does).

So I don't think we should do anything here that we haven't already
done.

bug#66147: 28.2; Doc of completion functions: (elisp) `Basic Completion'

[Drew Adams]

> > What seems missing from this doc (and likewise from the relevant doc
> > strings) is any description of what it means for a string to _match_
> > entries in the completion table.
> 
> "Basic Completion" is a subsection of "Completion".  The parent
> section explains what it means to match, by describing what does it
> mean to "complete" something.

I disagree that node `Completion' in any way
describes, specifies, or even suggests what
matching means for completion, in particular
for basic completion: literal-string prefix
matching.

And if it did, then that would be the wrong
place to do so, IMO.  Completion can involve
any number of ways to match (and then complete)
some input pattern.

IMO, `Basic Completion' is the right place to
specify what the "basic matching" is that's
then used for basic completion.  And no, it's
not yet described anywhere, AFAICS.

This, e.g., doesn't cut the mustard:

  "Completion" is a feature that fills in the
  rest of a name starting from an abbreviation
  for it.

That might be OK as an intro to describing
completion, but it certainly doesn't prescribe
literal-string prefix completion or matching.

It simply says that completion takes a pattern
and uses it to somehow come up with a string
that's more "complete".  (And "fills in" isn't
necessarily the case.  But it's maybe OK for
the first sentence of an intro.)

Likewise:

  Completion works by comparing the user's
  input ... and determining how much of the
  name is determined uniquely by what the
  user has typed.

says nothing about how the determination is
made, i.e., just _what kind of matching_ is
involved.

Not to mention that "name" isn't clear here.
The user provides some text as input, not
necessarily a "name".  And that text/string
is somehow matched against a set of other
texts/strings.  Matched how? "Basic matching"
- but just what is that?

This maybe comes a bit closer:

  returns the longest determined completion
  of a given initial string, with a given
  set of strings to match against.

but only by accident/confusion.  The "initial
string" really means just "input string", and
says nothing about the fact that that string
is taken _literally_ and matched _as a prefix_
against candidates.  "Initial", here, isn't
about "prefix".

There really is nothing in node `Completion'
that suggests, let alone declares/specifies
that the basic matching it assumes later is
literal-string matching as a prefix.

> So I think you are looking for a problem where there is none, by
> taking a single word (which generally has many different meanings in
> Emacs) and trying to interpret it by looking at the manual through a
> loophole, instead of taking the broader view by going to the beginning
> of the section and reading from there.

What single word are you thinking of?
"Match"?

The kind of matching used for what's called
"basic completion" is pretty important to
understand, I think.  And no, it's not
obvious.  There are a zillion-zillion ways
to match a pattern against text candidates.

> IOW, if someone reads on "Basic Completion", he or she needs to
> understand the terminology already; otherwise, they should start from
> the parent section.

"Needs to understand the terminology" is
what this bug report is about.  It's about
the terminology for "basic completion",
and that starts with an understanding of
the "basic matching" that's used.

> > In the beginning, Emacs completion used _only_ such literal-prefix
> > completion, so maybe back then not specifying how an input string is
> > matched against a completion candidate might not have been so
> > important.  But nowadays users encounter all kinds of matching when
> > completing: from substring to flex to regexp,...  They're familiar with
> > that interactively, as Emacs users, typically long before they encounter
> > programming with the completion functions described here.
> 
> This seems to talk about something other than basic completion, so is
> not relevant here.

No, it's talking exactly about basic completion.
In fact, literal-string prefix completion is
exactly the `completion-style' named `basic'.

And yes, it was all we had, to start with - back
almost when this Info section was first written.

Back in Emacs 20, we said (more clearly than now):

  If you type `M-x au <TAB>', the <TAB> looks for
  alternatives (in this case, command names) that
  start with `au'.
  ^^^^^^^^^^^^^^^

> And when a completion style does something other
> than the simple prefix matching, the style's
> documentation should state that (and it does).

I think you misunderstood the reason I mentioned
completion styles etc.  It was to excuse the text
as having been written when all Emacs had was
"basic" (aka literal-prefix) completion.

And to point out that this is no longer the case,
so it's even more important now to make clear what
the "basic" completion is: literal-string prefix
matching, and then replacing (or doing something
else) with a given match.

IOW, the text might have been excusable when
written, but there's no longer any excuse for not
saying what kind matching we're talking about.

> So I don't think we should do anything here that
> we haven't already done.

Please consider thinking about it some more.