# HG changeset patch
# User Richard M. Stallman <rms@gnu.org>
# Date 1064926823 0
# Node ID 3c9835a0d5b4858589ec87805e25581f9f687768
# Parent  f1ba36825faa97b1ba883e172ed3fc4cd9c1e07b
(Association Lists): Clarify `assq-delete-all'.

diff -r f1ba36825faa -r 3c9835a0d5b4 lispref/lists.texi
--- a/lispref/lists.texi	Tue Sep 30 12:59:20 2003 +0000
+++ b/lispref/lists.texi	Tue Sep 30 13:00:23 2003 +0000
@@ -1670,14 +1670,19 @@
 @defun assq-delete-all key alist
 @tindex assq-delete-all
 This function deletes from @var{alist} all the elements whose @sc{car}
-is @code{eq} to @var{key}.  It returns @var{alist}, modified
-in this way.  Note that it modifies the original list structure
-of @var{alist}.
+is @code{eq} to @var{key}, much as if you used @code{delq} to delete
+such each element one by one.  It returns the shortened alist, and
+often modifies the original list structure of @var{alist}.  For
+correct results, use the return value of @code{assq-delete-all} rather
+than looking at the saved value of @var{alist}.
 
 @example
-(assq-delete-all 'foo
-                 '((foo 1) (bar 2) (foo 3) (lose 4)))
+(setq alist '((foo 1) (bar 2) (foo 3) (lose 4)))
+     @result{} ((foo 1) (bar 2) (foo 3) (lose 4))
+(assq-delete-all 'foo alist)
      @result{} ((bar 2) (lose 4))
+alist
+     @result{} ((foo 1) (bar 2) (lose 4))
 @end example
 @end defun