bug#40671: [DOC] modify literal objects

[Paul Eggert]

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.

0001-Improve-mutability-doc.patch
Description: Text Data