From 5805df74f5b919a3f67f3f7d31d6e600e1564e4e Mon Sep 17 00:00:00 2001 From: Paul Eggert Date: Sun, 19 Apr 2020 13:22:10 -0700 Subject: [PATCH] Improve mutability doc MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit See Eli Zaretskii’s suggestions (Bug#40671#33). * doc/lispref/lists.texi (Setcar, Setcdr, Rearrangement): * doc/lispref/sequences.texi (Sequence Functions) (Array Functions): Add commentary to examples. * doc/lispref/lists.texi (Sets And Lists): Revert change to delq example. --- doc/lispref/lists.texi | 16 +++++++--------- doc/lispref/sequences.texi | 14 ++++++++------ 2 files changed, 15 insertions(+), 15 deletions(-) diff --git a/doc/lispref/lists.texi b/doc/lispref/lists.texi index f1acc85616f..1125af7bec3 100644 --- a/doc/lispref/lists.texi +++ b/doc/lispref/lists.texi @@ -911,7 +911,7 @@ value @var{object}. For example: @example @group -(setq x (list 1 2)) +(setq x (list 1 2)) ; @r{Create a mutable list.} @result{} (1 2) @end group @group @@ -931,7 +931,7 @@ these lists. Here is an example: @example @group -;; @r{Create two lists that are partly shared.} +;; @r{Create two mutable lists that are partly shared.} (setq x1 (list 'a 'b 'c)) @result{} (a b c) (setq x2 (cons 'z (cdr x1))) @@ -1022,11 +1022,11 @@ reached via the @sc{cdr}. @example @group -(setq x (list 1 2 3)) +(setq x (list 1 2 3)) ; @r{Create a mutable list.} @result{} (1 2 3) @end group @group -(setcdr x '(4)) +(setcdr x '(4)) ; @r{Modify the list's tail to be a constant list.} @result{} (4) @end group @group @@ -1135,11 +1135,11 @@ Unlike @code{append} (@pxref{Building Lists}), the @var{lists} are @example @group -(setq x (list 1 2 3)) +(setq x (list 1 2 3)) ; @r{Create a mutable list.} @result{} (1 2 3) @end group @group -(nconc x '(4 5)) +(nconc x '(4 5)) ; @r{Modify the list's tail to be a constant list.} @result{} (1 2 3 4 5) @end group @group @@ -1267,9 +1267,7 @@ after those elements. For example: @example @group -(equal - (delq 'a (list 'a 'b 'c)) - (cdr (list 'a 'b 'c))) +(delq 'a '(a b c)) @equiv{} (cdr '(a b c)) @end group @end example diff --git a/doc/lispref/sequences.texi b/doc/lispref/sequences.texi index 62d60156fbf..1cb0d05cc7b 100644 --- a/doc/lispref/sequences.texi +++ b/doc/lispref/sequences.texi @@ -183,11 +183,11 @@ for other ways to copy sequences. @example @group -(setq bar (list 1 2)) +(setq bar (list 1 2)) ; @r{Create a mutable list.} @result{} (1 2) @end group @group -(setq x (vector 'foo bar)) +(setq x (vector 'foo bar)) ; @r{Create a mutable vector.} @result{} [foo (1 2)] @end group @group @@ -278,7 +278,7 @@ Unlike @code{reverse} the original @var{sequence} may be modified. @example @group -(setq x (list 'a 'b 'c)) +(setq x (list 'a 'b 'c)) ; @r{Create a mutable list.} @result{} (a b c) @end group @group @@ -320,7 +320,7 @@ presented graphically: For the vector, it is even simpler because you don't need setq: @example -(setq x (copy-sequence [1 2 3 4])) +(setq x (copy-sequence [1 2 3 4])) ; @r{Create a mutable vector.} @result{} [1 2 3 4] (nreverse x) @result{} [4 3 2 1] @@ -374,7 +374,7 @@ appears in a different position in the list due to the change of @example @group -(setq nums (list 1 3 2 6 5 4 0)) +(setq nums (list 1 3 2 6 5 4 0)) ; @r{Create a mutable list.} @result{} (1 3 2 6 5 4 0) @end group @group @@ -1228,7 +1228,7 @@ This function sets the @var{index}th element of @var{array} to be @example @group -(setq w (vector 'foo 'bar 'baz)) +(setq w (vector 'foo 'bar 'baz)) ; @r{Create a mutable vector.} @result{} [foo bar baz] (aset w 0 'fu) @result{} fu @@ -1262,6 +1262,7 @@ each element of @var{array} is @var{object}. It returns @var{array}. @example @group +;; @r{Create a mutable vector and then fill it with zeros.} (setq a (copy-sequence [a b c d e f g])) @result{} [a b c d e f g] (fillarray a 0) @@ -1270,6 +1271,7 @@ a @result{} [0 0 0 0 0 0 0] @end group @group +;; @r{Create a mutable string and then fill it with "-".} (setq s (copy-sequence "When in the course")) @result{} "When in the course" (fillarray s ?-) -- 2.39.2