bug#40671: [DOC] modify literal objects

["Mattias Engdegård" <mattiase@acm.org>]

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

tags 40671 patch
stop

[Sorry about the truncated message.]

> Can we modify literal objects? 

No, and the manual should do a much better job at explaining this. At the very least it should not promulgate bad ideas by including mutation of literals in example code. Patch attached, suggested for emacs-27.

We should not even try to show what happens when the user breaks the rule, because it is undefined.



[-- Attachment #2: 0001-Don-t-mutate-literals-in-manual-examples-bug-40671.patch --]
[-- Type: application/octet-stream, Size: 8588 bytes --]

From 9801ee1b12574f8b1b50ba5b76b7ee41a7fb8bc4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Mattias=20Engdeg=C3=A5rd?= <mattiase@acm.org>
Date: Fri, 17 Apr 2020 18:00:34 +0200
Subject: [PATCH] Don't mutate literals in manual examples (bug#40671)

* doc/lispref/edebug.texi (Printing in Edebug):
* doc/lispref/keymaps.texi (Changing Key Bindings):
* doc/lispref/lists.texi (Setcar, Setcdr, Rearrangement, Sets And Lists)
(Association Lists, Plist Access):
* doc/lispref/sequences.texi (Sequence Functions, Array Functions):
* doc/lispref/strings.texi (Text Comparison):
Rewrite example code to not mutate constant (literal) lists, vectors
or strings.  Noticed by Kevin Vigouroux.
---
 doc/lispref/edebug.texi    |  2 +-
 doc/lispref/keymaps.texi   |  8 ++---
 doc/lispref/lists.texi     | 62 +++++++++-----------------------------
 doc/lispref/sequences.texi | 26 ++++++++--------
 doc/lispref/strings.texi   |  4 +--
 5 files changed, 34 insertions(+), 68 deletions(-)

diff --git a/doc/lispref/edebug.texi b/doc/lispref/edebug.texi
index cfef5c12d1..5970e7cf80 100644
--- a/doc/lispref/edebug.texi
+++ b/doc/lispref/edebug.texi
@@ -858,7 +858,7 @@ Printing in Edebug
   Here is an example of code that creates a circular structure:
 
 @example
-(setq a '(x y))
+(setq a (list 'x 'y))
 (setcar a a)
 @end example
 
diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi
index 2c90d208c0..fd207a184e 100644
--- a/doc/lispref/keymaps.texi
+++ b/doc/lispref/keymaps.texi
@@ -1441,10 +1441,10 @@ Changing Key Bindings
 
 @smallexample
 @group
-(setq map '(keymap
-            (?1 . olddef-1)
-            (?2 . olddef-2)
-            (?3 . olddef-1)))
+(setq map (list 'keymap
+                (cons ?1 'olddef-1)
+                (cons ?2 'olddef-2)
+                (cons ?3 'olddef-1)))
 @result{} (keymap (49 . olddef-1) (50 . olddef-2) (51 . olddef-1))
 @end group
 
diff --git a/doc/lispref/lists.texi b/doc/lispref/lists.texi
index 27fa5385e3..d1a12e9819 100644
--- a/doc/lispref/lists.texi
+++ b/doc/lispref/lists.texi
@@ -906,7 +906,7 @@ Setcar
 
 @example
 @group
-(setq x '(1 2))
+(setq x (list 1 2))
      @result{} (1 2)
 @end group
 @group
@@ -927,7 +927,7 @@ Setcar
 @example
 @group
 ;; @r{Create two lists that are partly shared.}
-(setq x1 '(a b c))
+(setq x1 (list 'a 'b 'c))
      @result{} (a b c)
 (setq x2 (cons 'z (cdr x1)))
      @result{} (z b c)
@@ -1017,7 +1017,7 @@ Setcdr
 
 @example
 @group
-(setq x '(1 2 3))
+(setq x (list 1 2 3))
      @result{} (1 2 3)
 @end group
 @group
@@ -1037,7 +1037,7 @@ Setcdr
 
 @example
 @group
-(setq x1 '(a b c))
+(setq x1 (list 'a 'b 'c))
      @result{} (a b c)
 (setcdr x1 (cdr (cdr x1)))
      @result{} (c)
@@ -1069,7 +1069,7 @@ Setcdr
 
 @example
 @group
-(setq x1 '(a b c))
+(setq x1 (list 'a 'b 'c))
      @result{} (a b c)
 (setcdr x1 (cons 'd (cdr x1)))
      @result{} (d b c)
@@ -1130,7 +1130,7 @@ Rearrangement
 
 @example
 @group
-(setq x '(1 2 3))
+(setq x (list 1 2 3))
      @result{} (1 2 3)
 @end group
 @group
@@ -1150,7 +1150,7 @@ Rearrangement
 
 @example
 @group
-(setq x '(1 2 3))
+(setq x (list 1 2 3))
      @result{} (1 2 3)
 @end group
 @group
@@ -1163,41 +1163,7 @@ Rearrangement
 @end group
 @end example
 
-However, the other arguments (all but the last) must be lists.
-
-A common pitfall is to use a quoted constant list as a non-last
-argument to @code{nconc}.  If you do this, your program will change
-each time you run it!  Here is what happens:
-
-@smallexample
-@group
-(defun add-foo (x)            ; @r{We want this function to add}
-  (nconc '(foo) x))           ;   @r{@code{foo} to the front of its arg.}
-@end group
-
-@group
-(symbol-function 'add-foo)
-     @result{} (lambda (x) (nconc '(foo) x))
-@end group
-
-@group
-(setq xx (add-foo '(1 2)))    ; @r{It seems to work.}
-     @result{} (foo 1 2)
-@end group
-@group
-(setq xy (add-foo '(3 4)))    ; @r{What happened?}
-     @result{} (foo 1 2 3 4)
-@end group
-@group
-(eq xx xy)
-     @result{} t
-@end group
-
-@group
-(symbol-function 'add-foo)
-     @result{} (lambda (x) (nconc '(foo 1 2 3 4) x))
-@end group
-@end smallexample
+However, the other arguments (all but the last) must be non-constant lists.
 @end defun
 
 @node Sets And Lists
@@ -1260,7 +1226,7 @@ Sets And Lists
 
 @example
 @group
-(delq 'a '(a b c)) @equiv{} (cdr '(a b c))
+(delq 'a (list 'a 'b 'c)) @equiv{} (cdr (list 'a 'b 'c))
 @end group
 @end example
 
@@ -1270,7 +1236,7 @@ Sets And Lists
 
 @example
 @group
-(setq sample-list '(a b c (4)))
+(setq sample-list (list 'a 'b 'c '(4)))
      @result{} (a b c (4))
 @end group
 @group
@@ -1407,7 +1373,7 @@ Sets And Lists
 
 @example
 @group
-(setq l '((2) (1) (2)))
+(setq l (list '(2) '(1) '(2)))
 (delete '(2) l)
      @result{} ((1))
 l
@@ -1416,7 +1382,7 @@ Sets And Lists
 ;; @r{write @code{(setq l (delete '(2) l))}.}
 @end group
 @group
-(setq l '((2) (1) (2)))
+(setq l (list '(2) '(1) '(2)))
 (delete '(1) l)
      @result{} ((2) (2))
 l
@@ -1759,7 +1725,7 @@ Association Lists
 than looking at the saved value of @var{alist}.
 
 @example
-(setq alist '((foo 1) (bar 2) (foo 3) (lose 4)))
+(setq alist (list '(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))
@@ -1926,7 +1892,7 @@ Plist Access
 in the place where you got @var{plist}.  For example,
 
 @example
-(setq my-plist '(bar t foo 4))
+(setq my-plist (list 'bar t 'foo 4))
      @result{} (bar t foo 4)
 (setq my-plist (plist-put my-plist 'foo 69))
      @result{} (bar t foo 69)
diff --git a/doc/lispref/sequences.texi b/doc/lispref/sequences.texi
index 1a3a04f680..d35b4d05e3 100644
--- a/doc/lispref/sequences.texi
+++ b/doc/lispref/sequences.texi
@@ -183,7 +183,7 @@ Sequence Functions
 
 @example
 @group
-(setq bar '(1 2))
+(setq bar (list 1 2))
      @result{} (1 2)
 @end group
 @group
@@ -278,7 +278,7 @@ Sequence Functions
 
 @example
 @group
-(setq x '(a b c))
+(setq x (list 'a 'b 'c))
      @result{} (a b c)
 @end group
 @group
@@ -374,11 +374,11 @@ Sequence Functions
 
 @example
 @group
-(setq nums '(1 3 2 6 5 4 0))
+(setq nums (list 1 3 2 6 5 4 0))
      @result{} (1 3 2 6 5 4 0)
 @end group
 @group
-(sort nums '<)
+(sort nums #'<)
      @result{} (0 1 2 3 4 5 6)
 @end group
 @group
@@ -396,7 +396,7 @@ Sequence Functions
 the variable that held the original list:
 
 @example
-(setq nums (sort nums '<))
+(setq nums (sort nums #'<))
 @end example
 
 For the better understanding of what stable sort is, consider the following
@@ -1228,7 +1228,7 @@ Array Functions
 
 @example
 @group
-(setq w [foo bar baz])
+(setq w (vector 'foo 'bar 'baz))
      @result{} [foo bar baz]
 (aset w 0 'fu)
      @result{} fu
@@ -1237,12 +1237,12 @@ Array Functions
 @end group
 
 @group
-(setq x "asdfasfd")
-     @result{} "asdfasfd"
+(setq x (string ?a ?b ?c ?d ?e))
+     @result{} "abcde"
 (aset x 3 ?Z)
      @result{} 90
 x
-     @result{} "asdZasfd"
+     @result{} "abcZe"
 @end group
 @end example
 
@@ -1257,7 +1257,7 @@ Array Functions
 
 @example
 @group
-(setq a [a b c d e f g])
+(setq a (vector 'a 'b 'c 'd 'e 'f 'g))
      @result{} [a b c d e f g]
 (fillarray a 0)
      @result{} [0 0 0 0 0 0 0]
@@ -1265,10 +1265,10 @@ Array Functions
      @result{} [0 0 0 0 0 0 0]
 @end group
 @group
-(setq s "When in the course")
-     @result{} "When in the course"
+(setq s (string ?S ?e ?c ?r ?e ?t))
+     @result{} "Secret"
 (fillarray s ?-)
-     @result{} "------------------"
+     @result{} "------"
 @end group
 @end example
 
diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi
index 14cabc5d79..3d375409a9 100644
--- a/doc/lispref/strings.texi
+++ b/doc/lispref/strings.texi
@@ -591,7 +591,7 @@ Text Comparison
 
 @example
 @group
-(sort '("11" "12" "1 1" "1 2" "1.1" "1.2") 'string-collate-lessp)
+(sort (list "11" "12" "1 1" "1 2" "1.1" "1.2") 'string-collate-lessp)
      @result{} ("11" "1 1" "1.1" "12" "1 2" "1.2")
 @end group
 @end example
@@ -608,7 +608,7 @@ Text Comparison
 
 @example
 @group
-(sort '("11" "12" "1 1" "1 2" "1.1" "1.2")
+(sort (list "11" "12" "1 1" "1 2" "1.1" "1.2")
       (lambda (s1 s2) (string-collate-lessp s1 s2 "POSIX")))
      @result{} ("1 1" "1 2" "1.1" "1.2" "11" "12")
 @end group
-- 
2.21.1 (Apple Git-122.3)