bug#52901: 26.3; (emacs) `Completion Styles': provide more guidance

bug#52901: 26.3; (emacs) `Completion Styles': provide more guidance

[Drew Adams]

In this node each predefined completion style is described.  But these
two bits of guidance are missing - please consider adding them:

1. Mention `completion-styles-alist', as does the doc string of
   `completion-styles'.  (We do mention `completion-category-overrides',
   at least.)

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.

In GNU Emacs 26.3 (build 1, x86_64-w64-mingw32)
 of 2019-08-29
Repository revision: 96dd0196c28bc36779584e47fffcca433c9309cd
Windowing system distributor `Microsoft Corp.', version 10.0.19042
Configured using:
 `configure --without-dbus --host=x86_64-w64-mingw32
 --without-compress-install 'CFLAGS=-O2 -static -g3''

bug#52901: 26.3; (emacs) `Completion Styles': provide more guidance

[Eli Zaretskii]

> From: Drew Adams <drew.adams@oracle.com>
> Date: Thu, 30 Dec 2021 17:25:01 +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.

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

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

[Drew Adams]

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

bug#52901: 26.3; (emacs) `Completion Styles': provide more guidance

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

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

No specific suggestions were proffered, so I think it's unlikely to be
more progress in this bug report, and I'm therefore closing it.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

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

[Drew Adams]

> No specific suggestions were proffered, so I think it's unlikely to be
> more progress in this bug report, and I'm therefore closing it.

As I said:

  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.

`completion-styles' work together.  It's not a great
design.  The first styles tries to complete.  If it
fails, the next tries, and so on.

Clearly, this favors completing when possible, as
opposed to giving more control over how the styles
are to be combined.  But it is what it is.

This behavior of combining styles, and the fact that
styles often overlap in the sets of completions they
arrive at for a given input and candidates-set, means
that users could really use some guidance about what
the predefined styles do _when used together_.  They
after all have to choose a sequence of styles to use.

IMO it's a disservice to users to brush this aside
just because those who currently have the know-how
to write this up aren't so inclined.  Far better to
leave this open, in hopes that someone will come
along with both the necessary knowledge and will to
help users with this.