bug#23548: 25.0.93; lists.texi (alist-get): Document optional arg 'remove'.

[Tino Calancha]

> You renamed it only in the @defun line.  The description still uses
> 'value', so there's now a disconnect.

> More importantly, I'm sorry to say that this additional text makes no
> sense to me.  It just repeats what the doc string says (which also
> makes no sense).
For me either.  I was following the 'authority principle': someone 
wrote that doc. string because she thought is was clear enough.

You cannot talk about using this function "to set
> the value at KEY", without some explaining, because 'alist-get'
> doesn't itself set anything, it _gets_ a value of KEY.  Right?
Right.  I miss they mention something like: using this function as
PLACE in `setf'.

> I believe this text needs a much longer and more detailed explanation,
> and most probably also an example, to make sense.  (The doc string
> could use some more explanations as well.)
I modified previous patch and added one example.  It may be an start for
getting it more comprehensible.


> From 78fa526404c6ea57e42c44423d1bfecef5b45eea Mon Sep 17 00:00:00 2001
From: Tino Calancha <f92capac@gmail.com>
Date: Tue, 17 May 2016 01:56:15 +0900
Subject: [PATCH] * lists.texi (alist-get): Document optional arg 'remove'

---
 doc/lispref/lists.texi | 23 ++++++++++++++++++-----
 1 file changed, 18 insertions(+), 5 deletions(-)

diff --git a/doc/lispref/lists.texi b/doc/lispref/lists.texi
index c18c408..d9f3d17 100644
--- a/doc/lispref/lists.texi
+++ b/doc/lispref/lists.texi
@@ -1556,12 +1556,25 @@ Association Lists
 @end smallexample
 @end defun

-@defun alist-get key value &optional default
+@defun alist-get key alist &optional default remove
 This function is like @code{assq}, but instead of returning the entire
-association for @var{key}, @code{(@var{key} . @var{value})}, it
-returns just the @var{value}.  It returns @var{default} if @var{key}
-is not found in @var{alist}, defaulting to @code{nil} if @var{default}
-is omitted.
+association for @var{key}, it returns the @sc{cdr}.
+It returns @var{default} if @var{key} is not found in @var{alist},
+defaulting to @code{nil} if @var{default} is omitted.
+
+When using this function in conjunction with @code{setf}
+to set the value of @var{alist} at @var{key} to @var{new-val},
+if @var{remove} evaluates non-@code{nil} and @var{default} is @code{eql}
+to @var{new-val}, then the entry at @var{key} is deleted.
+
+For example:
+
+@smallexample
+(let ((myalist '((a . 1) (b . 2) (c . 3))))
+  (setf (alist-get 'a myalist 1 'remove) 1)
+  myalist)
+@result{} ((b . 2) (c . 3))
+@end smallexample
 @end defun

 @defun rassq value alist
--
2.8.1