GNU bug report logs - #76199
30.0.93; completing-read-multiple is not documented in the manual

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 76199 in the body.
You can then email your comments to 76199 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: Daniel Mendler <mail <at> daniel-mendler.de>
To: bug-gnu-emacs <at> gnu.org
Subject: 30.0.93; completing-read-multiple is not documented in the manual
Date: Tue, 11 Feb 2025 11:25:24 +0100

Since documentation came up in bug#76028, it seems that
`completing-read-multiple' is not documented in the Elisp
manual, in particular in doc/lispref/minibuf.texi.

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Daniel Mendler <mail <at> daniel-mendler.de>
Cc: 76199 <at> debbugs.gnu.org
Subject: Re: bug#76199: 30.0.93;
 completing-read-multiple is not documented in the manual
Date: Tue, 11 Feb 2025 15:30:20 +0200

> Date: Tue, 11 Feb 2025 11:25:24 +0100
> From:  Daniel Mendler via "Bug reports for GNU Emacs,
>  the Swiss army knife of text editors" <bug-gnu-emacs <at> gnu.org>
> 
> Since documentation came up in bug#76028, it seems that
> `completing-read-multiple' is not documented in the Elisp
> manual, in particular in doc/lispref/minibuf.texi.

We don't necessarily document every function.  Is this one important
enough to be in the manual?

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

From: Daniel Mendler <mail <at> daniel-mendler.de>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 76199 <at> debbugs.gnu.org
Subject: Re: bug#76199: 30.0.93; completing-read-multiple is not documented
 in the manual
Date: Tue, 11 Feb 2025 14:37:56 +0100

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

>> Date: Tue, 11 Feb 2025 11:25:24 +0100
>> From:  Daniel Mendler via "Bug reports for GNU Emacs,
>>  the Swiss army knife of text editors" <bug-gnu-emacs <at> gnu.org>
>> 
>> Since documentation came up in bug#76028, it seems that
>> `completing-read-multiple' is not documented in the Elisp
>> manual, in particular in doc/lispref/minibuf.texi.
>
> We don't necessarily document every function.  Is this one important
> enough to be in the manual?

I think so. It is not as important as `completing-read' but still useful
in scenarios where multiple strings should be read via completion. I can
send a patch for the manual if there is interest.

Daniel

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

From: Heime <heimeborgia <at> protonmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: Daniel Mendler <mail <at> daniel-mendler.de>, 76199 <at> debbugs.gnu.org
Subject: Re: bug#76199: 30.0.93;
 completing-read-multiple is not documented in the manual
Date: Tue, 11 Feb 2025 13:40:23 +0000

Sent with Proton Mail secure email.

On Wednesday, February 12th, 2025 at 1:30 AM, Eli Zaretskii <eliz <at> gnu.org> wrote:

> > Date: Tue, 11 Feb 2025 11:25:24 +0100
> > From: Daniel Mendler via "Bug reports for GNU Emacs,
> > the Swiss army knife of text editors" bug-gnu-emacs <at> gnu.org
> > 
> > Since documentation came up in bug#76028, it seems that
> > `completing-read-multiple' is not documented in the Elisp
> > manual, in particular in doc/lispref/minibuf.texi.
> 
> 
> We don't necessarily document every function. Is this one important
> enough to be in the manual?


I have used it, and would like it to be in the manual.

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Daniel Mendler <mail <at> daniel-mendler.de>
Cc: 76199 <at> debbugs.gnu.org
Subject: Re: bug#76199: 30.0.93; completing-read-multiple is not documented
 in the manual
Date: Tue, 11 Feb 2025 15:51:47 +0200

> From: Daniel Mendler <mail <at> daniel-mendler.de>
> Cc: 76199 <at> debbugs.gnu.org
> Date: Tue, 11 Feb 2025 14:37:56 +0100
> 
> Eli Zaretskii <eliz <at> gnu.org> writes:
> 
> >> Date: Tue, 11 Feb 2025 11:25:24 +0100
> >> From:  Daniel Mendler via "Bug reports for GNU Emacs,
> >>  the Swiss army knife of text editors" <bug-gnu-emacs <at> gnu.org>
> >> 
> >> Since documentation came up in bug#76028, it seems that
> >> `completing-read-multiple' is not documented in the Elisp
> >> manual, in particular in doc/lispref/minibuf.texi.
> >
> > We don't necessarily document every function.  Is this one important
> > enough to be in the manual?
> 
> I think so.

Can you tell why?

The function is documented in its doc string, so adding it to the
manual needs a reason, like extreme popularity (doesn't seem to be the
case here), or some important aspects of its use that cannot be
easily described  in the doc string.

We could also compromise: mention the function's existence in the
manual, but leave out its description (if that will just repeat what's
in the doc string, it's just redundant).

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Heime <heimeborgia <at> protonmail.com>
Cc: mail <at> daniel-mendler.de, 76199 <at> debbugs.gnu.org
Subject: Re: bug#76199: 30.0.93;
 completing-read-multiple is not documented in the manual
Date: Tue, 11 Feb 2025 15:54:12 +0200

> Date: Tue, 11 Feb 2025 13:40:23 +0000
> From: Heime <heimeborgia <at> protonmail.com>
> Cc: Daniel Mendler <mail <at> daniel-mendler.de>, 76199 <at> debbugs.gnu.org
> 
> > We don't necessarily document every function. Is this one important
> > enough to be in the manual?
> 
> I have used it, and would like it to be in the manual. 

That's not a sufficient reason to add it, sorry.

You need to realize that the ELisp manual is already too large: it
prints in 2 volumes, each volume weighing in at hundreds of pages.  So
we must be judicial in our decisions to add new stuff there.

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

From: Daniel Mendler <mail <at> daniel-mendler.de>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 76199 <at> debbugs.gnu.org
Subject: Re: bug#76199: 30.0.93; completing-read-multiple is not documented
 in the manual
Date: Tue, 11 Feb 2025 15:01:45 +0100

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

>> From: Daniel Mendler <mail <at> daniel-mendler.de>
>> Cc: 76199 <at> debbugs.gnu.org
>> Date: Tue, 11 Feb 2025 14:37:56 +0100
>> 
>> Eli Zaretskii <eliz <at> gnu.org> writes:
>> 
>> >> Date: Tue, 11 Feb 2025 11:25:24 +0100
>> >> From:  Daniel Mendler via "Bug reports for GNU Emacs,
>> >>  the Swiss army knife of text editors" <bug-gnu-emacs <at> gnu.org>
>> >> 
>> >> Since documentation came up in bug#76028, it seems that
>> >> `completing-read-multiple' is not documented in the Elisp
>> >> manual, in particular in doc/lispref/minibuf.texi.
>> >
>> > We don't necessarily document every function.  Is this one important
>> > enough to be in the manual?
>> 
>> I think so.
>
> Can you tell why?

It is sometimes useful to complete multiple strings and
`completing-read-multiple' is a good tool to do that. So it may be
helpful to tell developers about this function. Alternatively one can
use `completing-read' in a loop, which I have also seen multiple times
in the Emacs code base or external packages.

> We could also compromise: mention the function's existence in the
> manual, but leave out its description (if that will just repeat what's
> in the doc string, it's just redundant).

This sounds like a good compromise. A short notice mentioning
`completing-read-multiple' below the documentation of `completing-read'
should suffice.

Daniel

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

From: Christopher Dimech <dimech <at> gmx.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: Daniel Mendler <mail <at> daniel-mendler.de>, 76199 <at> debbugs.gnu.org
Subject: Re: bug#76199: 30.0.93; completing-read-multiple is not documented
 in the manual
Date: Tue, 11 Feb 2025 15:06:45 +0100

> Sent: Wednesday, February 12, 2025 at 1:51 AM
> From: "Eli Zaretskii" <eliz <at> gnu.org>
> To: "Daniel Mendler" <mail <at> daniel-mendler.de>
> Cc: 76199 <at> debbugs.gnu.org
> Subject: bug#76199: 30.0.93; completing-read-multiple is not documented in the manual
>
> > From: Daniel Mendler <mail <at> daniel-mendler.de>
> > Cc: 76199 <at> debbugs.gnu.org
> > Date: Tue, 11 Feb 2025 14:37:56 +0100
> >
> > Eli Zaretskii <eliz <at> gnu.org> writes:
> >
> > >> Date: Tue, 11 Feb 2025 11:25:24 +0100
> > >> From:  Daniel Mendler via "Bug reports for GNU Emacs,
> > >>  the Swiss army knife of text editors" <bug-gnu-emacs <at> gnu.org>
> > >>
> > >> Since documentation came up in bug#76028, it seems that
> > >> `completing-read-multiple' is not documented in the Elisp
> > >> manual, in particular in doc/lispref/minibuf.texi.
> > >
> > > We don't necessarily document every function.  Is this one important
> > > enough to be in the manual?
> >
> > I think so.
>
> Can you tell why?
>
> The function is documented in its doc string, so adding it to the
> manual needs a reason, like extreme popularity (doesn't seem to be the
> case here), or some important aspects of its use that cannot be
> easily described  in the doc string.
>
> We could also compromise: mention the function's existence in the
> manual, but leave out its description (if that will just repeat what's
> in the doc string, it's just redundant).

Reference to it in the manual would assist users in discovering additional
functionality than figuring them out for themselves.

Some information is better than having nothing.  Some summary of additional
things that go beyond the realm of the manual would be of assistance to users.

What do you think about something like the Introduction to Emacs Lisp,
but that discusses things that go beyond the manual like new features,
popular ways of using things, and so on.

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

From: Christopher Dimech <dimech <at> gmx.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: mail <at> daniel-mendler.de, Heime <heimeborgia <at> protonmail.com>,
 76199 <at> debbugs.gnu.org
Subject: Re: bug#76199: 30.0.93; completing-read-multiple is not documented
 in the manual
Date: Tue, 11 Feb 2025 15:21:55 +0100

> Sent: Wednesday, February 12, 2025 at 1:54 AM
> From: "Eli Zaretskii" <eliz <at> gnu.org>
> To: "Heime" <heimeborgia <at> protonmail.com>
> Cc: mail <at> daniel-mendler.de, 76199 <at> debbugs.gnu.org
> Subject: bug#76199: 30.0.93; completing-read-multiple is not documented in the manual
>
> > Date: Tue, 11 Feb 2025 13:40:23 +0000
> > From: Heime <heimeborgia <at> protonmail.com>
> > Cc: Daniel Mendler <mail <at> daniel-mendler.de>, 76199 <at> debbugs.gnu.org
> >
> > > We don't necessarily document every function. Is this one important
> > > enough to be in the manual?
> >
> > I have used it, and would like it to be in the manual.
>
> That's not a sufficient reason to add it, sorry.
>
> You need to realize that the ELisp manual is already too large: it
> prints in 2 volumes, each volume weighing in at hundreds of pages.  So
> we must be judicial in our decisions to add new stuff there.

The manual is not being read as a book but to get information about some
specific feature that makes it easier to use than  looking at docstrings.
The trend is towards a good automatic query search.  The only thing that
should happen is for the manual to increase in volume rather than reduce.

One suggestion would be to have the manual categorised, so one does not have
to search through its entirety to look at information on same aspect.

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Daniel Mendler <mail <at> daniel-mendler.de>
Cc: 76199-done <at> debbugs.gnu.org
Subject: Re: bug#76199: 30.0.93; completing-read-multiple is not documented
 in the manual
Date: Tue, 11 Feb 2025 16:44:22 +0200

> From: Daniel Mendler <mail <at> daniel-mendler.de>
> Cc: 76199 <at> debbugs.gnu.org
> Date: Tue, 11 Feb 2025 15:01:45 +0100
> 
> Eli Zaretskii <eliz <at> gnu.org> writes:
> 
> > We could also compromise: mention the function's existence in the
> > manual, but leave out its description (if that will just repeat what's
> > in the doc string, it's just redundant).
> 
> This sounds like a good compromise. A short notice mentioning
> `completing-read-multiple' below the documentation of `completing-read'
> should suffice.

Thanks, now done on the emacs-30 branch (with the wrong bug number,
sorry), and closing the bug.

Previous Next

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