GNU bug report logs - #50394
Improve "Completion List Mode" NEWS entry

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 50394 in the body.
You can then email your comments to 50394 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: Stefan Kangas <stefan <at> marxist.se>
To: bug-gnu-emacs <at> gnu.org
Subject: Improve "Completion List Mode" NEWS entry
Date: Sun, 5 Sep 2021 07:27:50 +0200

Severity: wishlist
X-Debbugs-CC: Gregory Heytings <ghe <at> sdf.org>

Could we please make this NEWS entry easier to understand:

** Completion List Mode
New key bindings have been added: 'n' and 'p' to navigate completions,
and 'M-g M-c' to switch to the minibuffer, and you can also switch back
to the completion list buffer with 'M-g M-c'.

I suspect that most users have no idea what is "completion list mode",
as IIUC it is an implementation detail. They would be helped more if
this instead referred to "the default completion window" or somesuch
(assuming that's what this is about).

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: ghe <at> sdf.org, 50394 <at> debbugs.gnu.org
Subject: Re: bug#50394: Improve "Completion List Mode" NEWS entry
Date: Sun, 05 Sep 2021 09:41:20 +0300

> From: Stefan Kangas <stefan <at> marxist.se>
> Date: Sun, 5 Sep 2021 07:27:50 +0200
> Cc: gregory heytings <ghe <at> sdf.org>
> 
> ** Completion List Mode
> New key bindings have been added: 'n' and 'p' to navigate completions,
> and 'M-g M-c' to switch to the minibuffer, and you can also switch back
> to the completion list buffer with 'M-g M-c'.
> 
> I suspect that most users have no idea what is "completion list mode",

If they don't, they could just do

  C-h f completion-list-mode RET

and read there.

> as IIUC it is an implementation detail.

??? No, it's a complete major mode, according to its doc string.

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: ghe <at> sdf.org, 50394 <at> debbugs.gnu.org, Stefan Kangas <stefan <at> marxist.se>
Subject: Re: bug#50394: Improve "Completion List Mode" NEWS entry
Date: Sun, 05 Sep 2021 09:52:31 +0200

Eli Zaretskii <eliz <at> gnu.org> writes:

>> as IIUC it is an implementation detail.
>
> ??? No, it's a complete major mode, according to its doc string.

I was also confused by that entry -- perhaps changing it to something to
emphasise that it's an actual mode would help.  I.e.:

** Completion List Mode

New key bindings have been added to 'completion-list-mode': 'n' and 'p'
to navigate completions, (etc)


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

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: ghe <at> sdf.org, 50394 <at> debbugs.gnu.org, stefan <at> marxist.se
Subject: Re: bug#50394: Improve "Completion List Mode" NEWS entry
Date: Sun, 05 Sep 2021 12:25:45 +0300

> From: Lars Ingebrigtsen <larsi <at> gnus.org>
> Cc: Stefan Kangas <stefan <at> marxist.se>,  ghe <at> sdf.org,  50394 <at> debbugs.gnu.org
> Date: Sun, 05 Sep 2021 09:52:31 +0200
> 
> Eli Zaretskii <eliz <at> gnu.org> writes:
> 
> >> as IIUC it is an implementation detail.
> >
> > ??? No, it's a complete major mode, according to its doc string.
> 
> I was also confused by that entry -- perhaps changing it to something to
> emphasise that it's an actual mode would help.  I.e.:
> 
> ** Completion List Mode
> 
> New key bindings have been added to 'completion-list-mode': 'n' and 'p'
> to navigate completions, (etc)

Sure, if that helps, why not.  I thought the conversion from a mode's
name to its Lisp symbol was something widely known.

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: ghe <at> sdf.org, 50394 <at> debbugs.gnu.org, stefan <at> marxist.se
Subject: Re: bug#50394: Improve "Completion List Mode" NEWS entry
Date: Sun, 05 Sep 2021 11:32:46 +0200

Eli Zaretskii <eliz <at> gnu.org> writes:

>> ** Completion List Mode
>> 
>> New key bindings have been added to 'completion-list-mode': 'n' and 'p'
>> to navigate completions, (etc)
>
> Sure, if that helps, why not.  I thought the conversion from a mode's
> name to its Lisp symbol was something widely known.

It is -- it's just that this mode's name sounds like it might be
something else, i.e., not a "mode" in the Emacs sense, but a way to
change the way completion works.  I'll update the NEWS entry.

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

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

From: Stefan Kangas <stefan <at> marxist.se>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: Gregory Heytings <ghe <at> sdf.org>, Eli Zaretskii <eliz <at> gnu.org>,
 50394 <at> debbugs.gnu.org
Subject: Re: bug#50394: Improve "Completion List Mode" NEWS entry
Date: Sun, 5 Sep 2021 11:57:51 +0200

Lars Ingebrigtsen <larsi <at> gnus.org> writes:

> It is -- it's just that this mode's name sounds like it might be
> something else, i.e., not a "mode" in the Emacs sense, but a way to
> change the way completion works.  I'll update the NEWS entry.

Thanks.

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

From: Stefan Kangas <stefan <at> marxist.se>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: Gregory Heytings <ghe <at> sdf.org>, 50394 <at> debbugs.gnu.org
Subject: Re: bug#50394: Improve "Completion List Mode" NEWS entry
Date: Sun, 5 Sep 2021 20:22:03 +0200

Eli Zaretskii <eliz <at> gnu.org> writes:

> > ** Completion List Mode
> > New key bindings have been added: 'n' and 'p' to navigate completions,
> > and 'M-g M-c' to switch to the minibuffer, and you can also switch back
> > to the completion list buffer with 'M-g M-c'.
> >
> > I suspect that most users have no idea what is "completion list mode",
>
> If they don't, they could just do
>
>   C-h f completion-list-mode RET
>
> and read there.

I don't think that should be needed for such basic functionality.

I changed the headline from the nondescript 'Completion List Mode' to
'Improved navigation in the "*Completions*" buffer"'.  I think that
makes things sufficiently clear without having to look elsewhere.

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: ghe <at> sdf.org, 50394 <at> debbugs.gnu.org
Subject: Re: bug#50394: Improve "Completion List Mode" NEWS entry
Date: Sun, 05 Sep 2021 21:30:47 +0300

> From: Stefan Kangas <stefan <at> marxist.se>
> Date: Sun, 5 Sep 2021 20:22:03 +0200
> Cc: 50394 <at> debbugs.gnu.org, Gregory Heytings <ghe <at> sdf.org>
> 
> Eli Zaretskii <eliz <at> gnu.org> writes:
> 
> > > ** Completion List Mode
> > > New key bindings have been added: 'n' and 'p' to navigate completions,
> > > and 'M-g M-c' to switch to the minibuffer, and you can also switch back
> > > to the completion list buffer with 'M-g M-c'.
> > >
> > > I suspect that most users have no idea what is "completion list mode",
> >
> > If they don't, they could just do
> >
> >   C-h f completion-list-mode RET
> >
> > and read there.
> 
> I don't think that should be needed for such basic functionality.

Which basic functionality are you alluding to here?

> I changed the headline from the nondescript 'Completion List Mode' to
> 'Improved navigation in the "*Completions*" buffer"'.  I think that
> makes things sufficiently clear without having to look elsewhere.

Sorry, I don't follow.  This is in the section whose headline is
"Changes in Specialized Modes and Packages in Emacs 28.1", right?  And
each item in that section names a mode or a package, right?  So what's
wrong with having a headline there which says "Completion List Mode"?
it's a mode, right?

Or what am I missing?

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

From: Stefan Kangas <stefan <at> marxist.se>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: Gregory Heytings <ghe <at> sdf.org>, 50394 <at> debbugs.gnu.org
Subject: Re: bug#50394: Improve "Completion List Mode" NEWS entry
Date: Sun, 5 Sep 2021 21:16:06 +0200

Eli Zaretskii <eliz <at> gnu.org> writes:

> Which basic functionality are you alluding to here?

Command completion, 'M-x TAB'.

> > I changed the headline from the nondescript 'Completion List Mode' to
> > 'Improved navigation in the "*Completions*" buffer"'.  I think that
> > makes things sufficiently clear without having to look elsewhere.
>
> Sorry, I don't follow.  This is in the section whose headline is
> "Changes in Specialized Modes and Packages in Emacs 28.1", right?  And
> each item in that section names a mode or a package, right?  So what's
> wrong with having a headline there which says "Completion List Mode"?
> it's a mode, right?
>
> Or what am I missing?

Sorry to be unclear.  Because this is about basic functionality it
should not be under "Specialized Modes and Packages" but under
"Changes in Emacs".  So I moved it there (or that is my intention, at
least).

Even if we kept it there, things under there usually do not have this format:

    * Changes in Specialized Modes and Packages in Emacs 28.1
    ...
    ** Library Name
    Text describing a particular feature

See NEWS.27, etc. for examples.

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: ghe <at> sdf.org, 50394 <at> debbugs.gnu.org
Subject: Re: bug#50394: Improve "Completion List Mode" NEWS entry
Date: Sun, 05 Sep 2021 22:23:23 +0300

> From: Stefan Kangas <stefan <at> marxist.se>
> Date: Sun, 5 Sep 2021 21:16:06 +0200
> Cc: 50394 <at> debbugs.gnu.org, Gregory Heytings <ghe <at> sdf.org>
> 
> Eli Zaretskii <eliz <at> gnu.org> writes:
> 
> > Which basic functionality are you alluding to here?
> 
> Command completion, 'M-x TAB'.
> 
> > > I changed the headline from the nondescript 'Completion List Mode' to
> > > 'Improved navigation in the "*Completions*" buffer"'.  I think that
> > > makes things sufficiently clear without having to look elsewhere.
> >
> > Sorry, I don't follow.  This is in the section whose headline is
> > "Changes in Specialized Modes and Packages in Emacs 28.1", right?  And
> > each item in that section names a mode or a package, right?  So what's
> > wrong with having a headline there which says "Completion List Mode"?
> > it's a mode, right?
> >
> > Or what am I missing?
> 
> Sorry to be unclear.  Because this is about basic functionality it
> should not be under "Specialized Modes and Packages" but under
> "Changes in Emacs".  So I moved it there (or that is my intention, at
> least).

But the entry specifically talks about key bindings in that particular
mode, so I still don't see why you think it should in a more general
section.

> Even if we kept it there, things under there usually do not have this format:
> 
>     * Changes in Specialized Modes and Packages in Emacs 28.1
>     ...
>     ** Library Name
>     Text describing a particular feature
> 
> See NEWS.27, etc. for examples.

Are the examples you have in mind in NEWS (i.e. Emacs 28) or in
NEWS.27?  Or maybe just show a couple of examples of "Library Name" so
I wouldn't need to look them up?  And in any case, is that relevant to
the issue at hand, or is that a separate issue?

Thanks.

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

From: Stefan Kangas <stefan <at> marxist.se>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: Gregory Heytings <ghe <at> sdf.org>, 50394 <at> debbugs.gnu.org
Subject: Re: bug#50394: Improve "Completion List Mode" NEWS entry
Date: Mon, 6 Sep 2021 10:21:14 +0200

Eli Zaretskii <eliz <at> gnu.org> writes:

> But the entry specifically talks about key bindings in that particular
> mode, so I still don't see why you think it should in a more general
> section.

This is often the problem with trying to find a good taxonomy: things
end up fitting in more than one category.  In this case, I am trying
to think about where a user would be most helped by seeing it.  I
believe this change will be visible enough all over Emacs to warrant a
more prominent location.

If that doesn't convince, I suppose it will have to be where it is.

The important part that remains is an explanation along the lines
"Improved navigation in the "*Completions*" buffer".  If this is
uncontroversial, I intend to add such a clarification.

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: Gregory Heytings <ghe <at> sdf.org>, Eli Zaretskii <eliz <at> gnu.org>,
 50394 <at> debbugs.gnu.org
Subject: Re: bug#50394: Improve "Completion List Mode" NEWS entry
Date: Mon, 06 Sep 2021 10:27:28 +0200

Stefan Kangas <stefan <at> marxist.se> writes:

> The important part that remains is an explanation along the lines
> "Improved navigation in the "*Completions*" buffer".  If this is
> uncontroversial, I intend to add such a clarification.

That's a good clarification.  I guess most users won't be aware of there
being a particular major mode in the *Completions* buffer.

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

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

From: Stefan Kangas <stefan <at> marxist.se>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: Gregory Heytings <ghe <at> sdf.org>, Eli Zaretskii <eliz <at> gnu.org>,
 50394 <at> debbugs.gnu.org
Subject: Re: bug#50394: Improve "Completion List Mode" NEWS entry
Date: Tue, 7 Sep 2021 01:50:16 +0200

Lars Ingebrigtsen <larsi <at> gnus.org> writes:

> > The important part that remains is an explanation along the lines
> > "Improved navigation in the "*Completions*" buffer".  If this is
> > uncontroversial, I intend to add such a clarification.
>
> That's a good clarification.  I guess most users won't be aware of there
> being a particular major mode in the *Completions* buffer.

Thanks, now pushed to master.

This makes it even more clear that the entry is still in the wrong
place IMO, but there we are.

Previous Next

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