GNU bug report logs - #31628
26.1; Problem in read-multiple-choice's docstring

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 31628 in the body.
You can then email your comments to 31628 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: Damien Cassou <damien <at> cassou.me>
To: bug-gnu-emacs <at> gnu.org
Subject: 26.1; Problem in read-multiple-choice's docstring
Date: Mon, 28 May 2018 17:23:08 +0200

[Message part 1 (text/plain, inline)]

Attached patch fixes the docstring of read-multiple-choice. Previous
docstring, said CHOICES was an alist which it isn't. The new docstring
fixes that and gives names to components of each choice.

-- 
Damien Cassou
http://damiencassou.seasidehosting.st

"Success is the ability to go from one failure to another without
losing enthusiasm." --Winston Churchill

[0001-lisp-emacs-lisp-rmc.el-read-multiple-choice-Improve-.patch (text/x-patch, attachment)]

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

From: "Basil L. Contovounesios" <contovob <at> tcd.ie>
To: Damien Cassou <damien <at> cassou.me>
Cc: 31628 <at> debbugs.gnu.org
Subject: Re: bug#31628: 26.1; Problem in read-multiple-choice's docstring
Date: Mon, 28 May 2018 19:07:25 +0100

Damien Cassou <damien <at> cassou.me> writes:

> Previous docstring, said CHOICES was an alist which it isn't.

Technically, a list of (A B C) is as much an alist as a list of (A . B),
but I agree that the docstring can be clarified a bit.

> From 255c09ac20c940140e20d199b1f715fc98264da5 Mon Sep 17 00:00:00 2001
> From: Damien Cassou <damien <at> cassou.me>
> Date: Mon, 28 May 2018 17:12:34 +0200
> Subject: [PATCH] * lisp/emacs-lisp/rmc.el (read-multiple-choice): Improve
>  docstring.
>
> ---
>  lisp/emacs-lisp/rmc.el | 11 +++++------
>  1 file changed, 5 insertions(+), 6 deletions(-)
>
> diff --git a/lisp/emacs-lisp/rmc.el b/lisp/emacs-lisp/rmc.el
> index 3dd3508903..9813dcf2e5 100644
> --- a/lisp/emacs-lisp/rmc.el
> +++ b/lisp/emacs-lisp/rmc.el
> @@ -30,12 +30,11 @@ read-multiple-choice
>    "Ask user a multiple choice question.
>  PROMPT should be a string that will be displayed as the prompt.
>  
> -CHOICES is an alist where the first element in each entry is a
> -character to be entered, the second element is a short name for
> -the entry to be displayed while prompting (if there's room, it
> -might be shortened), and the third, optional entry is a longer
> -explanation that will be displayed in a help buffer if the user
> -requests more help.
> +CHOICES is a list of (KEY NAME [DESCRIPTION]). KEY is a character
> +to be entered. NAME a short name for the entry to be displayed
> +while prompting (if there's room, it might be shortened).
> +DESCRIPTION is an optional longer explanation that will be
> +displayed in a help buffer if the user requests more help.

I think the full stops should be followed by two spaces, as per the
default sentence-end-double-space.

-- 
Basil

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

From: Damien Cassou <damien <at> cassou.me>
To: "Basil L. Contovounesios" <contovob <at> tcd.ie>
Cc: 31628 <at> debbugs.gnu.org
Subject: Re: bug#31628: 26.1; Problem in read-multiple-choice's docstring
Date: Tue, 29 May 2018 08:04:49 +0200

[Message part 1 (text/plain, inline)]

"Basil L. Contovounesios" <contovob <at> tcd.ie> writes:
> I think the full stops should be followed by two spaces, as per the
> default sentence-end-double-space.

fixed in attached patch.

-- 
Damien Cassou
http://damiencassou.seasidehosting.st

"Success is the ability to go from one failure to another without
losing enthusiasm." --Winston Churchill

[0001-lisp-emacs-lisp-rmc.el-read-multiple-choice-Improve-.patch (text/x-patch, attachment)]

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

From: Noam Postavsky <npostavs <at> gmail.com>
To: Damien Cassou <damien <at> cassou.me>
Cc: "Basil L. Contovounesios" <contovob <at> tcd.ie>, 31628 <at> debbugs.gnu.org
Subject: Re: bug#31628: 26.1; Problem in read-multiple-choice's docstring
Date: Tue, 29 May 2018 08:18:41 -0400

severity 31628 minor
tags 31628 fixed
close 31628 26.2
quit

Damien Cassou <damien <at> cassou.me> writes:

> "Basil L. Contovounesios" <contovob <at> tcd.ie> writes:
>> I think the full stops should be followed by two spaces, as per the
>> default sentence-end-double-space.
>
> fixed in attached patch.

I added a missing "is" after NAME, and pushed to emacs-26.

[1: 24ba63314f]: 2018-05-29 08:17:32 -0400
  Improve read-multiple-choice docstring (Bug#31628)
  https://git.savannah.gnu.org/cgit/emacs.git/commit/?id=24ba63314f29fdffa9cfe012927e5efd744c138d

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

From: Drew Adams <drew.adams <at> oracle.com>
To: "Basil L. Contovounesios" <contovob <at> tcd.ie>, Damien Cassou
 <damien <at> cassou.me>
Cc: 31628 <at> debbugs.gnu.org
Subject: RE: bug#31628: 26.1; Problem in read-multiple-choice's docstring
Date: Tue, 29 May 2018 06:49:37 -0700 (PDT)

> Technically, a list of (A B C) is as much an alist as a list of (A . B),
> but I agree that the docstring can be clarified a bit.

No - assuming you mean that A, B, and C are elements of the
list and they are atoms, not cons cells.

From (elisp) `Association Lists':

   It is a list of cons cells called "associations": the CAR of
   each cons cell is the "key", and the CDR is the "associated
   value".

Alist elements are cons cells, in Emacs Lisp as in other
Lisps.

It's true that functions that look up an association do not
raise an error if a list element is not a cons.

  In Emacs Lisp, it is _not_ an error if an element of an
  association list is not a cons cell.  The alist search
  functions simply ignore such elements.  Many other versions
  of Lisp signal errors in such cases.

Ignoring such elements, like raising an error for such an
element, does not mean that such an element is an
association or that an alist is just any old list.

And yes, there is even one function, `assoc-default', that
treats an atomic list element as if it were an association.
IOW, `assoc-default' works with any list, not just with alists.

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

From: "Basil L. Contovounesios" <contovob <at> tcd.ie>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: Damien Cassou <damien <at> cassou.me>, 31628 <at> debbugs.gnu.org
Subject: Re: bug#31628: 26.1; Problem in read-multiple-choice's docstring
Date: Tue, 29 May 2018 17:39:43 +0100

Drew Adams <drew.adams <at> oracle.com> writes:

>> Technically, a list of (A B C) is as much an alist as a list of (A . B),
>> but I agree that the docstring can be clarified a bit.
>
> No - assuming you mean that A, B, and C are elements of the
> list and they are atoms, not cons cells.

You misunderstood the wording that Damien and I used.  We both referred
to lists *of elements* (A B C), not lists *of form* (A B C).  In other
words, (A B C) and (A . B) describe the structure of the list's
elements, not that of the list itself.

The preposition "of" in "list of (A B C)" totally disambiguates this
distinction for me; if the wording is not as clear to others, then
perhaps someone will suggest an improvement.

-- 
Basil

Previous Next

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