bug#21644: 24.4; completing-read acts differently on functional collection

[Drew Adams <drew.adams@oracle.com>]

> > Yes and no, IMO.  `Basic Completion' certainly provides
> > some information about "completion, COLLECTION, and
> > PREDICATE."  But for 3 other functions, not explicitly
> > for `completing-read' - it is not even mentioned there.
> 
> What's not mentioned? Basic Completion mentions the three key functions.

Please reread what I wrote.  I said that `completing-read' is
not mentioned in node `Basic Completion'.  And it is not.

> > As was suggested earlier (see above), node `Programmed
> > Completion' is where we should send someone for information
> > about a function-valued COLLECTION argument.
> 
> Basic Completion references Programmed Completion, twice.

So what?

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'.  That is specifically the purpose of
that node.  And that is the _only_ place that info is provided.

> On the other hand, Programmed Completion assumes that the collection is
> a function from the outset. This is not necessarily true in completing-read.

No one said that that is true.  This bug is about that particular
case.

The point is that mention of a function-valued COLLECTION in the
doc string should get readers to `Programmed Completion'.

Read what I said.  I did not say that we should send users to
`P. C.' for general info about COLLECTION.  I said:

  `Programmed Completion' is where we should send someone for
  information about a function-valued COLLECTION argument.
                      ^^^^^^^^^^^^^^^
And I said, regarding general info about COLLECTION:

  It doesn't hurt to send them to both nodes or to only
  their parent, `Completion'.

What is inadequate for the function-valued COLLECTION case, is
to send readers __only__ to `Basic Completion'.  Especially with
no indication that they need to consult not only `all-completions'
and `try-completion' there, but also `test-completion'.

That's the missing info, if you send them only to `B. C.': no
info that `test-completion' is relevant to the function-valued
COLLECTION case for `completing-read'.