bug#12314: 24.2.50; `add-to-history': use `setq' with `delete'

["Drew Adams" <drew.adams@oracle.com>]

> > It is not enough, if you need the variable to reflect the 
> > updated list contents.
> 
> Then the manual should be corrected to state that much more explicitly
> than it does now.  Perhaps it shouldn't even talk about destructive
> removal, as that will surely spread confusion.  For me "destructive"
> means "in-place", and no amount of describing how 'delete' works
> internally will ever be able to countermand that.  Besides, if all I
> need is a quick reminder about the semantics, I'm unlikely to read all
> the verbiage, let alone go up to read more under 'delq'.  So the most
> important facts should be right there at the beginning, not hidden
> away under "note that" etc.

Go for it.  I suggest mentioning something like this in node `Modifying Lists'
(and then cross-ref'ing that node from other nodes about functions that are
destructive of list structure):

Typically, you want a variable whose value is a list to reflect the result of
any destructive operation on that list.  To achieve that, set the variable value
to the value returned by that operation.

The reason for this is that operations that modify list structure do not also
update any variables that might point to such structure.  They are concerned
only with changing list structure.

Then give the `delq' example as an illustration of this.  Point out why  the
variable's value no longer reflects the updated list content.  (Perhaps even use
a cons-cell diagram to illustrate.)

  When `delq' deletes elements from the front of the list, it
  does so simply by advancing down the list and returning a
  sublist that starts after those elements:

     (setq sample-list '(a b c (4)))
          => (a b c (4))

     (delq 'a sample-list) => (b c (4))
     sample-list           => (a b c (4))

Mention explicitly that the same thing is involved with *ALL* list-modification
operations.  The only things guaranteed by such operations are (a) the
modification of the list structure takes place as advertised, and (b) the return
value reflects the modified list structure correctly.

So if you want a variable to reflect the list correctly as modified then set its
value to the return value of the modification function.