Re: completion-all-completions-with-base-size

[Eli Zaretskii <eliz@gnu.org>]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: emacs-devel@gnu.org
> Date: Sat, 18 Oct 2008 15:31:18 -0400
> 
> > This NEWS entry:
> >     *** `all-completions' may now return the base size in the last cdr.
> >     Since this means the returned list is not properly nil-terminated, this
> >     is an incompatible change and is thus enabled by the new variable
> >     completion-all-completions-with-base-size.
> 
> > is inaccurate: `all-completions' does not take into account the value
> > of `completion-all-completions-with-base-size'.
> 
> IIUC, this is not relevant:

Sorry, I'm not following: what isn't relevant, and to what?

> the base-size is always 0 (in which case
> it's not necessary to add it) for all completion tables except
> functional ones.  So of course all-completions doesn't take it into
> account: only the functional completion tables do.
> 
> Still, the value returned by all-completions can contains such `cdr's
> and it depends on completion-all-completions-with-base-size.
> 
> > Only `completion-all-completions' and a couple of internal functions
> > consult that variable.
> 
> `completion-all-completions' does not consult it: it sets it.

Now you lost me completely.  Could you please describe one scenario
and the corresponding sequence of function calls which would cause
all-completions (either what it does or the values it returns) to
depend on completion-all-completions-with-base-size?

> > But `completion-all-completions' is not documented in the ELisp
> > manual, as are most of other APIs in minibuffer.el (should they be
> > documented?),
> 
> I don't see why they should be documented there.  The entry points are
> the same as before (and are documented): minibuffer-complete,
> minibuffer-complete-word, ...

Yes, but all-completions _is_ described, as are try-completion and
test-completion.  The ELisp manual describes not only high-level entry
points, but also the low-level primitives, where that may help a Lisp
programmer to write yet another higher-level completion function.

> > so it sounds like the above NEWS entry does not warrant any
> > documentation in the manuals?  Why then it was added to NEWS?
> 
> Because some functions may call all-completions in a context where
> someone has set completion-all-completions-with-base-size
> (e.g. when all-completions is used internally by a functional
> completion table), in which case it may be surprised by the extra `cdr'
> (which could cause `length' or `mapcar' to signal an error).

Well, I'm probably missing something, because I couldn't see how what
all-completions returns could depend on
completion-all-completions-with-base-size.  Please help me understand
that.

Thanks.