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

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

[Tino Calancha]

* doc/lispref/lists.texi (alist-get): Document optional arg. 'remove'.
Rename second argument to 'alist'.


In GNU Emacs 25.0.93.3 (x86_64-pc-linux-gnu, GTK+ Version 2.24.30)
Repository revision: 6de0715f5467d4b925e2dfe082174529ace3b174


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

---
  doc/lispref/lists.texi | 7 ++++++-
  1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/doc/lispref/lists.texi b/doc/lispref/lists.texi
index c18c408..7d411af 100644
--- a/doc/lispref/lists.texi
+++ b/doc/lispref/lists.texi
@@ -1556,12 +1556,17 @@ 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.
+
+When using this function to set the value 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.
  @end defun

  @defun rassq value alist
-- 
2.8.1

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

[Eli Zaretskii]

> Date: Mon, 16 May 2016 23:13:35 +0900 (JST)
> From: Tino Calancha <f92capac@gmail.com>
> 
> * doc/lispref/lists.texi (alist-get): Document optional arg. 'remove'.
> Rename second argument to 'alist'.

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

> +@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.
> +
> +When using this function to set the value 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.

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

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

Thanks.

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

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

[Glenn Morris]

Version: 25.1

Thanks; I tweaked the docs.