Subject: RE: bug#18253: 24.4.50; doc string of `remq': correct it per the doc of `remove'

From: Drew Adams <[email-masked]>
Date: Wed, 27 Aug 2014 07:06:51 -0700 (PDT)

> > And most (all other?) Lisps have given it the same behavior as
> > `remove', the only difference being to use `eq' instead of `equal'.
> > IOW, they systematically copy the sequence.
> 
> How about to avoid the use of word `copy' to describe both `remq'
> and `remove'?

Because that is precisely what is important.  Why "avoid" what it
is most important to communicate to users?

> The point of remq/remove is non-destructive operation.  Whether it
> returns a copy or not is not important.  This matches CL's `remove'
> definition.

No, it does not.  From CLTL, section 14.3, "Modifying Sequences":

  The result is a sequence of the same kind as the argument SEQUENCE
  that has the same elements except that those in the subsequence
  delimited by :start and :end and satisfying the test (see above)
  have been removed.  This is a non-destructive operation; the result
  is a copy of the input SEQUENCE, save that some elements are not
  ^^^^^^^^^
  copied.  Elements not removed occur in the same order in the result
  ^^^^^^
  that they did in the argument.

That text was in the original edition of CTLT (1984), and it has not
changed one bit in subsequent revisions.

> Actually, even the current `remove' implementation does
> not return a copy when SEQ is not a list and there is nothing to
> remove.

I did not check the C code, but all descriptions of Elisp `delete'
for a non-list say that it *always* returns a new object.  Perhaps
all of those descriptions are incorrect (?), in which case we have
a bigger doc problem.

> If document explicitly says it returns a copy, reader might think
> destructive operation can be performed on the result of both
> functions while expecting original sequence unmodified.

Which is the case for Common Lisp.  And which should be the case
for Emacs Lisp for the cases that need to be documented as such
(i.e. as copying).