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

Previous Next

Full log

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.

Previous Next

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