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

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 52901 in the body.
You can then email your comments to 52901 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: "bug-gnu-emacs <at> gnu.org" <bug-gnu-emacs <at> gnu.org>
Subject: 26.3; (emacs) `Completion Styles': provide more guidance
Date: Thu, 30 Dec 2021 17:25:01 +0000

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

Message #10 received at 52901 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 52901 <at> debbugs.gnu.org
Subject: Re: bug#52901: 26.3;
 (emacs) `Completion Styles': provide more guidance
Date: Thu, 30 Dec 2021 20:07:15 +0200

> From: Drew Adams <drew.adams <at> 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.

Message #13 received at 52901 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: "52901 <at> debbugs.gnu.org" <52901 <at> debbugs.gnu.org>
Subject: RE: [External] : Re: bug#52901: 26.3; (emacs) `Completion Styles':
 provide more guidance
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.

Message #16 received at 52901 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 52901 <at> debbugs.gnu.org, Drew Adams <drew.adams <at> oracle.com>
Subject: Re: bug#52901: 26.3; (emacs) `Completion Styles': provide more
 guidance
Date: Sat, 15 Jan 2022 10:53:05 +0100

Eli Zaretskii <eliz <at> 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

Message #21 received at 52901 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Lars Ingebrigtsen <larsi <at> gnus.org>, Eli Zaretskii <eliz <at> gnu.org>
Cc: "52901 <at> debbugs.gnu.org" <52901 <at> debbugs.gnu.org>
Subject: RE: [External] : Re: bug#52901: 26.3; (emacs) `Completion Styles':
 provide more guidance
Date: Sat, 15 Jan 2022 21:56:19 +0000

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

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.