Re: emacs-30 8064b2a6798: Document undocumented completion commands

Re: emacs-30 8064b2a6798: Document undocumented completion commands

[Eshel Yaron]

Hi,

Eli Zaretskii <eliz@gnu.org> writes:

> branch: emacs-30
> commit 8064b2a67988e815c52e289fe2a235ce1008776f
> Author: Eli Zaretskii <eliz@gnu.org>
> Commit: Eli Zaretskii <eliz@gnu.org>
>
>     Document undocumented completion commands

Thanks for this.

> diff --git a/src/minibuf.c b/src/minibuf.c
> index f16880011f7..83b1fa024f8 100644
> --- a/src/minibuf.c
> +++ b/src/minibuf.c
> @@ -1293,6 +1293,11 @@ barf_if_interaction_inhibited (void)
>  DEFUN ("read-from-minibuffer", Fread_from_minibuffer,
>         Sread_from_minibuffer, 1, 7, 0,
>         doc: /* Read a string from the minibuffer, prompting with string PROMPT.
> +While in the minibuffer, you can use \\<minibuffer-local-completion-map>\\[minibuffer-complete] and \\[minibuffer-complete-word] to complete your input.
> +You can also use \\<minibuffer-local-map>\\[minibuffer-complete-history] to complete using history items in the
> +input history HIST, and you can use \\[minibuffer-complete-defaults] to complete using
> +the default items in DEFAULT-VALUE.
> +
>  The optional second arg INITIAL-CONTENTS is an obsolete alternative to
>    DEFAULT-VALUE.  It normally should be nil in new code, except when
>    HIST is a cons.  It is discussed in more detail below.

This part isn't quite right: read-from-minibuffer does not provide
completion with minibuffer-complete[-word] by default.

How about just dropping these references?  Something like:

diff --git a/src/minibuf.c b/src/minibuf.c
index 6ac3216a62f..becc3a9f26c 100644
--- a/src/minibuf.c
+++ b/src/minibuf.c
@@ -1297,8 +1297,7 @@ barf_if_interaction_inhibited (void)
 DEFUN ("read-from-minibuffer", Fread_from_minibuffer,
        Sread_from_minibuffer, 1, 7, 0,
        doc: /* Read a string from the minibuffer, prompting with string PROMPT.
-While in the minibuffer, you can use \\<minibuffer-local-completion-map>\\[minibuffer-complete] and \\[minibuffer-complete-word] to complete your input.
-You can also use \\<minibuffer-local-map>\\[minibuffer-complete-history] to complete using history items in the
+While in the minibuffer, you can use \\<minibuffer-local-map>\\[minibuffer-complete-history] to complete using history items in the
 input history HIST, and you can use \\[minibuffer-complete-defaults] to complete using
 the default items in DEFAULT-VALUE.
 

Re: emacs-30 8064b2a6798: Document undocumented completion commands

[Eli Zaretskii]

> From: Eshel Yaron <me@eshelyaron.com>
> Cc: Eli Zaretskii <eliz@gnu.org>
> Date: Sun, 05 Jan 2025 09:06:04 +0100
> 
> > diff --git a/src/minibuf.c b/src/minibuf.c
> > index f16880011f7..83b1fa024f8 100644
> > --- a/src/minibuf.c
> > +++ b/src/minibuf.c
> > @@ -1293,6 +1293,11 @@ barf_if_interaction_inhibited (void)
> >  DEFUN ("read-from-minibuffer", Fread_from_minibuffer,
> >         Sread_from_minibuffer, 1, 7, 0,
> >         doc: /* Read a string from the minibuffer, prompting with string PROMPT.
> > +While in the minibuffer, you can use \\<minibuffer-local-completion-map>\\[minibuffer-complete] and \\[minibuffer-complete-word] to complete your input.
> > +You can also use \\<minibuffer-local-map>\\[minibuffer-complete-history] to complete using history items in the
> > +input history HIST, and you can use \\[minibuffer-complete-defaults] to complete using
> > +the default items in DEFAULT-VALUE.
> > +
> >  The optional second arg INITIAL-CONTENTS is an obsolete alternative to
> >    DEFAULT-VALUE.  It normally should be nil in new code, except when
> >    HIST is a cons.  It is discussed in more detail below.
> 
> This part isn't quite right: read-from-minibuffer does not provide
> completion with minibuffer-complete[-word] by default.
> 
> How about just dropping these references?

Sorry, I don't want to drop them, they are important.

Why do you say these are not supported by default?  I can use them in
"emacs -Q", so what did I miss?

In any case, if these commands need something to enable them, I prefer
to spell that out in the doc string.  These commands are important,
and having them undocumented is not acceptable, IMO.

Re: emacs-30 8064b2a6798: Document undocumented completion commands

[Eshel Yaron]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Eshel Yaron <me@eshelyaron.com>
>> Cc: Eli Zaretskii <eliz@gnu.org>
>> Date: Sun, 05 Jan 2025 09:06:04 +0100
>> 
>> > diff --git a/src/minibuf.c b/src/minibuf.c
>> > index f16880011f7..83b1fa024f8 100644
>> > --- a/src/minibuf.c
>> > +++ b/src/minibuf.c
>> > @@ -1293,6 +1293,11 @@ barf_if_interaction_inhibited (void)
>> >  DEFUN ("read-from-minibuffer", Fread_from_minibuffer,
>> >         Sread_from_minibuffer, 1, 7, 0,
>> >         doc: /* Read a string from the minibuffer, prompting with string PROMPT.
>> > +While in the minibuffer, you can use \\<minibuffer-local-completion-map>\\[minibuffer-complete] and \\[minibuffer-complete-word] to complete your input.
>> > +You can also use \\<minibuffer-local-map>\\[minibuffer-complete-history] to complete using history items in the
>> > +input history HIST, and you can use \\[minibuffer-complete-defaults] to complete using
>> > +the default items in DEFAULT-VALUE.
>> > +
>> >  The optional second arg INITIAL-CONTENTS is an obsolete alternative to
>> >    DEFAULT-VALUE.  It normally should be nil in new code, except when
>> >    HIST is a cons.  It is discussed in more detail below.
>> 
>> This part isn't quite right: read-from-minibuffer does not provide
>> completion with minibuffer-complete[-word] by default.
>> 
>> How about just dropping these references?
>
> Sorry, I don't want to drop them, they are important.
>
> Why do you say these are not supported by default?  I can use them in
> "emacs -Q", so what did I miss?

Hmm, C-h f read-from-minibuffer now says "While in the minibuffer, you can
use TAB and SPC to complete your input."  But read-from-minibuffer doesn't
provide such completion, by default it uses minibuffer-local-map, in which
both keys are self-inserting.  Do you see something different?

Re: emacs-30 8064b2a6798: Document undocumented completion commands

[Eli Zaretskii]

> From: Eshel Yaron <me@eshelyaron.com>
> Cc: emacs-devel@gnu.org
> Date: Sun, 05 Jan 2025 12:36:27 +0100
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> From: Eshel Yaron <me@eshelyaron.com>
> >> Cc: Eli Zaretskii <eliz@gnu.org>
> >> Date: Sun, 05 Jan 2025 09:06:04 +0100
> >> 
> >> > diff --git a/src/minibuf.c b/src/minibuf.c
> >> > index f16880011f7..83b1fa024f8 100644
> >> > --- a/src/minibuf.c
> >> > +++ b/src/minibuf.c
> >> > @@ -1293,6 +1293,11 @@ barf_if_interaction_inhibited (void)
> >> >  DEFUN ("read-from-minibuffer", Fread_from_minibuffer,
> >> >         Sread_from_minibuffer, 1, 7, 0,
> >> >         doc: /* Read a string from the minibuffer, prompting with string PROMPT.
> >> > +While in the minibuffer, you can use \\<minibuffer-local-completion-map>\\[minibuffer-complete] and \\[minibuffer-complete-word] to complete your input.
> >> > +You can also use \\<minibuffer-local-map>\\[minibuffer-complete-history] to complete using history items in the
> >> > +input history HIST, and you can use \\[minibuffer-complete-defaults] to complete using
> >> > +the default items in DEFAULT-VALUE.
> >> > +
> >> >  The optional second arg INITIAL-CONTENTS is an obsolete alternative to
> >> >    DEFAULT-VALUE.  It normally should be nil in new code, except when
> >> >    HIST is a cons.  It is discussed in more detail below.
> >> 
> >> This part isn't quite right: read-from-minibuffer does not provide
> >> completion with minibuffer-complete[-word] by default.
> >> 
> >> How about just dropping these references?
> >
> > Sorry, I don't want to drop them, they are important.
> >
> > Why do you say these are not supported by default?  I can use them in
> > "emacs -Q", so what did I miss?
> 
> Hmm, C-h f read-from-minibuffer now says "While in the minibuffer, you can
> use TAB and SPC to complete your input."  But read-from-minibuffer doesn't
> provide such completion, by default it uses minibuffer-local-map, in which
> both keys are self-inserting.  Do you see something different?

Please help me make this accurate without losing the important
information about these commands.  Okay?

Re: emacs-30 8064b2a6798: Document undocumented completion commands

[Eshel Yaron]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Eshel Yaron <me@eshelyaron.com>
>> Cc: emacs-devel@gnu.org
>> Date: Sun, 05 Jan 2025 12:36:27 +0100
>> 
>> Eli Zaretskii <eliz@gnu.org> writes:
>> 
>> >> From: Eshel Yaron <me@eshelyaron.com>
>> >> Cc: Eli Zaretskii <eliz@gnu.org>
>> >> Date: Sun, 05 Jan 2025 09:06:04 +0100
>> >> 
>> >> >  DEFUN ("read-from-minibuffer", Fread_from_minibuffer,
>> >> >         Sread_from_minibuffer, 1, 7, 0,
>> >> >         doc: /* Read a string from the minibuffer, prompting with string PROMPT.
>> >> > +While in the minibuffer, you can use \\<minibuffer-local-completion-map>\\[minibuffer-complete] and \\[minibuffer-complete-word] to complete your input.
>> >> 
>> >> This part isn't quite right: read-from-minibuffer does not provide
>> >> completion with minibuffer-complete[-word] by default.
>> >> 
>> >> How about just dropping these references?
>> >
>> > Sorry, I don't want to drop them, they are important.
>> >
>> > Why do you say these are not supported by default?  I can use them in
>> > "emacs -Q", so what did I miss?
>> 
>> Hmm, C-h f read-from-minibuffer now says "While in the minibuffer, you can
>> use TAB and SPC to complete your input."  But read-from-minibuffer doesn't
>> provide such completion, by default it uses minibuffer-local-map, in which
>> both keys are self-inserting.  Do you see something different?
>
> Please help me make this accurate without losing the important
> information about these commands.  Okay?

AFAICT it would be more accurate (and relevant) to mention these
commands in the docstring of completing-read, not read-from-minibuffer.
But they are also pretty well documented in both the Emacs manual and
the ELisp manual, so I'm not sure I see the importance of mentioning
them there as well...


Best,

Eshel