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

[Štěpán Němec]

On Sat, 18 Apr 2020 16:01:14 -0400 (EDT)
Paul Eggert wrote:

> branch: emacs-27
> commit eebfb72c906755c0a80d92c11deee7ac9faf5f4b
> Author: Paul Eggert <address@hidden>
> Commit: Paul Eggert <address@hidden>
>
>     Document constant vs mutable objects better

I think this is great, except for a few places mentioned below.

> @@ -9547,7 +9557,7 @@ part of which is the address of the next pair.  The 
> very last box
>  points to the symbol @code{nil}, which marks the end of the list.
>  
>  @need 1200
> -When a variable is set to a list with a function such as @code{setq},
> +When a variable is set to a list via @code{setq},

I understand you wanted to avoid implying that `setq' was a function,
but how about "setq or a similar function", "e.g. setq", or just leave
it at "set to a list"? Otherwise some people might wonder if `setq' is
somehow special (and the original formulation apparently tried to avoid
giving that impression).

>  it stores the address of the first box in the variable.  Thus,
>  evaluation of the expression
>  
> @@ -17092,7 +17102,7 @@ reminders.
>  
>  @cindex Mail aliases
>  @noindent
> -This @code{setq} command sets the value of the variable
> +This @code{setq} sets the value of the variable
>  @code{mail-aliases} to @code{t}.  Since @code{t} means true, the line
>  says, in effect, ``Yes, use mail aliases.''
>  
> @@ -17130,8 +17140,8 @@ The following turns off Indent Tabs mode:
>  @end smallexample
>  
>  Note that this line uses @code{setq-default} rather than the
> -@code{setq} command that we have seen before.  The @code{setq-default}
> -command sets values only in buffers that do not have their own local
> +@code{setq} that we have seen before.  The @code{setq-default}
                                          ^^^
With the following "command" removed, the article now seems
superfluous/awkward.

> +sets values only in buffers that do not have their own local
>  values for the variable.
>  

> -However, the other arguments (all but the last) must be lists.
> +However, the other arguments (all but the last) must be mutable lists.
                                                           ^^^^^^^
I don't think this is a good formulation, for reasons explained at the
bottom.

> @@ -1353,7 +1363,7 @@ Compare this with @code{memq}:
>       @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} are not @code{eq}.}
> +(memq (list 2) '((1) (2)))  ; @r{@code{(list 2)} and @code{(2)} are not 
> @code{eq}.}

I think this is missing the point, which is numeric comparison with `eq'
vs `eql' ("floating-point elements are compared by value"); no
mutability issues involved.

>       @result{} nil
>  @end group
>  @end example
> @@ -1373,11 +1383,11 @@ Compare this with @code{memq}:
>  
>  @example
>  @group
> -(member '(2) '((1) (2)))  ; @r{@code{(2)} and @code{(2)} are @code{equal}.}
> +(member (list 2) '((1) (2)))  ; @r{@code{(list 2)} and @code{(2)} are 
> @code{equal}.}
>       @result{} ((2))
>  @end group
>  @group
> -(memq '(2) '((1) (2)))    ; @r{@code{(2)} and @code{(2)} are not @code{eq}.}
> +(memq (list 2) '((1) (2)))    ; @r{@code{(list 2)} and @code{(2)} are not 
> @code{eq}.}

Not sure about this, either.

> @@ -1618,9 +1628,9 @@ keys may not be symbols:
>        '(("simple leaves" . oak)
>          ("compound leaves" . horsechestnut)))
>  
> -(assq "simple leaves" leaves)
> +(assq (copy-sequence "simple leaves") leaves)
>       @result{} nil
> -(assoc "simple leaves" leaves)
> +(assoc (copy-sequence "simple leaves") leaves)

This seems strange to me. Using `copy-sequence' just to get a key for
comparison?

> @@ -1237,7 +1237,8 @@ w
>  @end group
>  
>  @group
> -(setq x "asdfasfd")
> +;; @r{@code{copy-sequence} creates a mutable string.}

I think this comment is unnecessarily misleading, as it seems to imply
that literal strings are not mutable. IOW, "mutable" and "safely
mutable"/"mutating it is a good idea" should be distinguished.

> +(setq x (copy-sequence "asdfasfd"))
>       @result{} "asdfasfd"
>  (aset x 3 ?Z)
>       @result{} 90
> @@ -1246,6 +1247,10 @@ x
>  @end group
>  @end example
>  
> +The @var{array} should be mutable; that is, it should not be a constant,

Similarly here. There are languages, Lisps even, that distinguish
mutable and immutable strings/conses. In such languages, trying to
mutate an immutable data structure leads to an error being signalled.
Conflating "mutable" with "safely mutable" is IMO bound to induce
confusion.

> +such as the constants created via quoting or via self-evaluating forms.
> +@xref{Self-Evaluating Forms}.

  Thanks,

  Štěpán