Subject: RE: [External] : Re: bug#52901: 26.3; (emacs) `Completion Styles': provide more guidance

From: Drew Adams <[email-masked]>
Date: Thu, 30 Dec 2021 18:53:31 +0000

> > 1. Mention `completion-styles-alist', as does the doc string of
> >    `completion-styles'.  (We do mention `completion-category-overrides',
> >    at least.)
> 
> The alist variable is documented in the ELisp manual, since it is not
> of interest to users.  I added a cross-reference to there.

That's fine, thanks.

> > 2. Say something about combinations of the styles.  The completion
> >    behavior depends on the combination that's the value of option
> >    `completion-styles'.
> >
> >    It's not enough to describe each predefined style individually, and
> >    say that they are tried in order.  Please consider providing some
> >    comparison of the predefined styles: which of them in some sense
> >    include or subsume (or partially so) which others.  Give users an
> >    idea of which they don't need to include if they include this or that
> >    other.
> >
> > In general, a little more guidance for users, please.
> 
> The text already says quite a lot about that (it is not clear to me
> whether you reviewed the latest text, since you don't tell, and the
> Emacs version from which you reported this is quite old).  If you have
> specific suggestions for more detailed descriptions, please present
> them.  Otherwise I see no candidates for picking up the gauntlet, and
> we should just close this bug report, because people who work the most
> on completion are generally reluctant to document more of their work
> in terms that would be understandable by users.

Everything I said applies to the latest Emacs release
also (Emacs 27.2).  (There's no MS Windows binary for
the Emacs 28 pretest.)

Based on your saying that "the text already says quite
a lot" about what's requested, I nevertheless
downloaded the latest (master) *.texi doc for this node.

Unfortunately it, like prior versions, says _nothing_
about the relations among the (predefined) styles.  It
just says that they're tried in sequence till one finds
completions, and it describes each predefined style
individually.  That's always been said.  That's needed
info, but it's not sufficient help.

It's too bad, if those who currently could provide this
guidance aren't willing to do so.  But that's not, IMO,
a reason to close the bug report.  Perhaps at some point
someone who understands the style relations well enough
will offer to fix this.

A _start_ might be to say whether there are some styles
that are useless to specify when a particular other
style precedes them in the list.