Subject: bug#40671: [DOC] modify literal objects

From: Paul Eggert <[email-masked]>
Date: Sun, 19 Apr 2020 13:45:07 -0700

On 4/19/20 6:56 AM, Eli Zaretskii wrote:

> How do you know the patch addresses my concerns

I don't know that; I merely wrote that the patch should address the points you 
raised earlier. The goal was to improve documentation that was obviously 
deficient in this area - there's no serious dispute about that. The changes I 
installed were intended to be an improvement and have been found so by others - 
if you disagree, please feel free to revert or improve them.  Obviously the 
documentation is not perfect in this area and further improvements would be welcome.

> As Štěpán points out, not all of the examples need these changes.

I installed further changes that should address Štěpán's comments.

> For example, the node "Sets and Lists" now sometimes uses literal
> lists and sometimes non-literal ones -- without any explanation why.
> Likewise in "Association Lists" and "Sequence Functions".

This was in response to your request to not change examples if the examples 
didn't strictly need the changes. Although I preferred Mattias's original 
proposal because it switched to the (list ...) style more uniformly, the patch I 
installed mixed the '(...) and (list ...) styles because I thought that was what 
you were asking for.

I installed the attached patch, which attempts to address this issue by adding 
comments that try to explain why (list ...) is needed sometimes. However, in 
hindsight perhaps we should go back to the style used in Mattias's proposal, as 
it's simpler and more consistent and doesn't distract the reader from the focus 
of the documentation. Going back to Mattias's style would let us remove some of 
the comments that the attached patch inserts.

>>   @example
>>   @group
>> -(delq 'a '(a b c)) @equiv{} (cdr '(a b c))
>> +(equal
>> + (delq 'a (list 'a 'b 'c))
>> + (cdr (list 'a 'b 'c)))
>>   @end group
> 
> And here you simply changed the meaning of the example: @equiv{} is
> not the same as 'equal'.

Ah, I missed on that one. Thanks for pointing it out. I reverted that change in 
the attached patch.

As you note, it's not essential that the list be modifiable in this particular 
example. That being said, the documentation should not suggest that it's OK to 
use a destructive operation like delq on a constant, so further improvements 
would be helpful here if someone can find the time.
>From 5805df74f5b919a3f67f3f7d31d6e600e1564e4e Mon Sep 17 00:00:00 2001
From: Paul Eggert <[email-masked]>
Date: Sun, 19 Apr 2020 13:22:10 -0700
Subject: [PATCH] Improve mutability doc
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
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 f1acc85616..1125af7bec 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 62d60156fb..1cb0d05cc7 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.17.1