GNU bug report logs - #21644
24.4; completing-read acts differently on functional collection

Previous Next

Full log

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Dmitry Gutov <dgutov <at> yandex.ru>, "Ryan C. Thompson" <rct <at> thompsonclan.org>,
 Oleh Krehel <ohwoeowho <at> gmail.com>
Cc: 21644 <at> debbugs.gnu.org
Subject: RE: bug#21644: 24.4; completing-read acts differently on functional
 collection
Date: Thu, 15 Oct 2015 13:28:50 -0700 (PDT)

> > If the bug is that a user will not know the details for a
> > function-valued COLLECTION argument to `completing-read' then the
> > right place to send a reader for __that information__ is node
> > `Programmed Completion'.
> 
> _This_ bug was about that. That doesn't mean we should fix it by
> introducing another bug.

No one has said anything that would introduce another bug.
It's about fixing this bug, by getting users to the information
about function-valued COLLECTION.  And that info is in node
`Programmed Completion'.

No one has said that users should not consult `Basic Completion'
for info about `all-completions', `try-completion', and
`test-completion'.

> > And I said, regarding general info about COLLECTION:
> >    It doesn't hurt to send them to both nodes or to only
> >    their parent, `Completion'.
> 
> I think that asking the user to read the whole Completion section is too
> much. 

No one is asking users to read the whole `Completion' section.
That is the section that covers all of the info about
`completing-read', _if_ you insist on pointing to only one section.

If you send them to only one section then a section that talks
only about the low-level functions `*-completion[s]' is not the
right destination.

Again: "It doesn't hurt to send them to both nodes".

> Basic Completion already contains the necessary information,

No, it does not.  It says *nothing* about `completing-read'.
Doesn't even mention it.

> or links to it.

As does `Completion'.

Really what should be done is to link from the `completing-read'
doc string only to node `Minibuffer Completion', which is the
node that documents `completing-read'.

But that node should document COLLECTION (it does not), and that
doc of COLLECTION should point to node `Programmed Completion'
for details about function-valued COLLECTION.

It is a bug (IMHO) that the node that documents `completing-read'
does not specify parameter COLLECTION - which is arguably the
*most important* parameter.

Fix that bug and link to node `Minibuffer Completion' from the
doc string, and you will have fixed this bug as well.

Previous Next

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