bug#31628: 26.1; Problem in read-multiple-choice's docstring

bug#31628: 26.1; Problem in read-multiple-choice's docstring

[Damien Cassou]

[-- Attachment #1: Type: text/plain, Size: 361 bytes --]

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

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-lisp-emacs-lisp-rmc.el-read-multiple-choice-Improve-.patch --]
[-- Type: text/x-patch, Size: 1430 bytes --]

From 255c09ac20c940140e20d199b1f715fc98264da5 Mon Sep 17 00:00:00 2001
From: Damien Cassou <damien@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.
 
 This function translates user input into responses by consulting
 the bindings in `query-replace-map'; see the documentation of
-- 
2.17.0

bug#31628: 26.1; Problem in read-multiple-choice's docstring

[Basil L. Contovounesios]

Damien Cassou <damien@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@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

bug#31628: 26.1; Problem in read-multiple-choice's docstring

[Damien Cassou]

[-- Attachment #1: Type: text/plain, Size: 349 bytes --]

"Basil L. Contovounesios" <contovob@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

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-lisp-emacs-lisp-rmc.el-read-multiple-choice-Improve-.patch --]
[-- Type: text/x-patch, Size: 1773 bytes --]

From bad5de6b568d7730c4b3f48ae255a57eb91af421 Mon Sep 17 00:00:00 2001
From: Damien Cassou <damien@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 | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/lisp/emacs-lisp/rmc.el b/lisp/emacs-lisp/rmc.el
index 3dd3508903..6a0031cc4c 100644
--- a/lisp/emacs-lisp/rmc.el
+++ b/lisp/emacs-lisp/rmc.el
@@ -30,12 +30,12 @@ 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.
 
 This function translates user input into responses by consulting
 the bindings in `query-replace-map'; see the documentation of
@@ -46,7 +46,7 @@ read-multiple-choice
 again.
 
 When `use-dialog-box' is t (the default), this function can pop
-up a dialog window to collect the user input. That functionality
+up a dialog window to collect the user input.  That functionality
 requires `display-popup-menus-p' to return t. Otherwise, a text
 dialog will be used.
 
-- 
2.17.0

bug#31628: 26.1; Problem in read-multiple-choice's docstring

[Noam Postavsky]

severity 31628 minor
tags 31628 fixed
close 31628 26.2
quit

Damien Cassou <damien@cassou.me> writes:

> "Basil L. Contovounesios" <contovob@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

bug#31628: 26.1; Problem in read-multiple-choice's docstring

[Drew Adams]

> 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.

bug#31628: 26.1; Problem in read-multiple-choice's docstring

[Basil L. Contovounesios]

Drew Adams <drew.adams@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