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

[Drew Adams <drew.adams@oracle.com>]

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