Re: emacs-27 eebfb72 1/2: Document constant vs mutable objects better

[Paul Eggert <eggert@cs.ucla.edu>]

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

On 5/2/20 5:50 AM, Štěpán Němec wrote:

> I meant the list examples you changed: you would never actually use
> 
>  (memq (list 2) '((1) (2)))
> 
> instead of (memq '(2) '((1) (2))), same as you'd never use
> `copy-sequence' to make sure you have a fresh comparison key.
> 
> Rather, the point of that section is to use `member' instead of `memq',
> analogously to `assoc' vs `assq' above.

I see your point. That's easy enough to fix; I installed the attached patch.

> if you introduce wording
> such as "the other arguments (all but the last) should be mutable
> lists", that (to me, and I'm sure many other readers) implies that you
> are talking about (types of) data structures, i.e. that there is such a
> thing as mutable (and also immutable, because why would you use that
> term otherwise?) lists/conses/strings as opposed to something else, as
> there indeed is in some languages, including Scheme (e.g. SRFI 140) or
> Racket.

That's OK. It's not a misimpression to think of things that way. True, Scheme
SRFI 140 has a lot more detail, with functions like istring? that Elisp lacks,
but the core idea is close enough and it would be nice if Elisp eventually grew
in the same direction as Scheme in this area (though obviously this would be a
much bigger project than merely fiddling with the documentation).

I just checked, and Scheme has gone in the Elisp direction recently in this
area: although R6RS took the strong position that safety is essential, R7RS says
it's not - e.g., R7RS like R5RS says that (car 0) can cause the interpreter to
crash (though of course interpreters are suggested to behave more nicely than
that). This change to the Scheme spec was for performance reasons that Elisp is
not immune to.

[-- Attachment #2: 0001-Make-memq-etc.-examples-more-like-they-were.patch --]
[-- Type: text/x-patch, Size: 2978 bytes --]

From 0a3731feef351f6af47bed1458aefb6cb481b5f9 Mon Sep 17 00:00:00 2001
From: Paul Eggert <eggert@cs.ucla.edu>
Date: Sat, 2 May 2020 13:48:21 -0700
Subject: [PATCH] Make memq etc. examples more like they were
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Problem reported by Štěpán Němec in:
https://lists.gnu.org/r/emacs-devel/2020-05/msg00130.html
* doc/lispref/lists.texi (Sets And Lists, Association Lists):
Revert examples to be more like the way they were, using
self-evaluating expressions.  Be more consistent about listing
unspecified results.
---
 doc/lispref/lists.texi | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/doc/lispref/lists.texi b/doc/lispref/lists.texi
index ea44e01f48..fcaf4386b1 100644
--- a/doc/lispref/lists.texi
+++ b/doc/lispref/lists.texi
@@ -1242,8 +1242,8 @@ compare @var{object} against the elements of the list.  For example:
      @result{} (b c b a)
 @end group
 @group
-(memq '(2) '((1) (2)))    ; @r{@code{(2)} and @code{(2)} are not @code{eq}.}
-     @result{} nil
+(memq '(2) '((1) (2)))    ; @r{The two @code{(2)}s need not be @code{eq}.}
+     @result{} @r{Unspecified; might be @code{nil} or @code{((2))}.}
 @end group
 @end example
 @end defun
@@ -1356,12 +1356,12 @@ Compare this with @code{memq}:
 
 @example
 @group
-(memql 1.2 '(1.1 1.2 1.3))  ; @r{@code{1.2} and @code{1.2} must be @code{eql}.}
+(memql 1.2 '(1.1 1.2 1.3))  ; @r{@code{1.2} and @code{1.2} are @code{eql}.}
      @result{} (1.2 1.3)
 @end group
 @group
-(memq 1.2 '(1.1 1.2 1.3))  ; @r{@code{1.2} and @code{1.2} need not be @code{eq}.}
-     @result{} nil         ; @r{... or it might be @code{(1.2 1.3)}.}
+(memq 1.2 '(1.1 1.2 1.3))  ; @r{The two @code{1.2}s need not be @code{eq}.}
+     @result{} @r{Unspecified; might be @code{nil} or @code{(1.2 1.3)}.}
 @end group
 @end example
 @end defun
@@ -1380,12 +1380,12 @@ Compare this with @code{memq}:
 
 @example
 @group
-(member (list 2) '((1) (2)))  ; @r{@code{(list 2)} and @code{(2)} are @code{equal}.}
+(member '(2) '((1) (2)))  ; @r{@code{(2)} and @code{(2)} are @code{equal}.}
      @result{} ((2))
 @end group
 @group
-(memq (list 2) '((1) (2)))    ; @r{@code{(list 2)} and @code{(2)} are not @code{eq}.}
-     @result{} nil
+(memq '(2) '((1) (2)))    ; @r{The two @code{(2)}s need not be @code{eq}.}
+     @result{} @r{Unspecified; might be @code{nil} or @code{(2)}.}
 @end group
 @group
 ;; @r{Two strings with the same contents are @code{equal}.}
@@ -1626,7 +1626,7 @@ keys may not be symbols:
         ("compound leaves" . horsechestnut)))
 
 (assq "simple leaves" leaves)
-     @result{} @r{Unspecified; might be @code{nil} or non-@code{nil}.}
+     @result{} @r{Unspecified; might be @code{nil} or @code{("simple leaves" . oak)}.}
 (assoc "simple leaves" leaves)
      @result{} ("simple leaves" . oak)
 @end smallexample
-- 
2.17.1