From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.bugs Subject: bug#12314: 24.2.50; `add-to-history': use `setq' with `delete' Date: Sun, 09 Sep 2012 20:25:56 +0300 Message-ID: <831uibm7kr.fsf@gnu.org> References: <7602D24B74DE42CF9901322634B85CA2@us.oracle.com> <87sjas4mc2.fsf@gnu.org> <83ipbomv6e.fsf@gnu.org> <2C45207ADF0E46BC98AF1B486695F632@us.oracle.com> <83fw6smti6.fsf@gnu.org> <9A8F619FD7584123A6319BD089E444E4@us.oracle.com> <83bohgmrdv.fsf@gnu.org> <83a9x0mq5e.fsf@gnu.org> <8E40573C868D4B339513A16A02588F5E@us.oracle.com> <837gs4mcqy.fsf@gnu.org> <852E534DA6A342708069D17B8C3C3DFF@us.oracle.com> <834nn7nbno.fsf@gnu.org> <87r4qbr5s1.fsf@gnu.org> Reply-To: Eli Zaretskii NNTP-Posting-Host: plane.gmane.org X-Trace: ger.gmane.org 1347211600 4997 80.91.229.3 (9 Sep 2012 17:26:40 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sun, 9 Sep 2012 17:26:40 +0000 (UTC) Cc: 12314@debbugs.gnu.org To: Chong Yidong Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sun Sep 09 19:26:40 2012 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1TAlHL-0003pG-Bc for geb-bug-gnu-emacs@m.gmane.org; Sun, 09 Sep 2012 19:26:39 +0200 Original-Received: from localhost ([::1]:51072 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1TAlHI-0005KA-1x for geb-bug-gnu-emacs@m.gmane.org; Sun, 09 Sep 2012 13:26:36 -0400 Original-Received: from eggs.gnu.org ([208.118.235.92]:48097) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1TAlHF-0005K2-Kg for bug-gnu-emacs@gnu.org; Sun, 09 Sep 2012 13:26:34 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1TAlHE-0004yk-KF for bug-gnu-emacs@gnu.org; Sun, 09 Sep 2012 13:26:33 -0400 Original-Received: from debbugs.gnu.org ([140.186.70.43]:40962) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1TAlHE-0004ya-GP for bug-gnu-emacs@gnu.org; Sun, 09 Sep 2012 13:26:32 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.72) (envelope-from ) id 1TAlHh-00021U-Vm for bug-gnu-emacs@gnu.org; Sun, 09 Sep 2012 13:27:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Eli Zaretskii Original-Sender: debbugs-submit-bounces@debbugs.gnu.org Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sun, 09 Sep 2012 17:27:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 12314 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 12314-submit@debbugs.gnu.org id=B12314.13472115877734 (code B ref 12314); Sun, 09 Sep 2012 17:27:01 +0000 Original-Received: (at 12314) by debbugs.gnu.org; 9 Sep 2012 17:26:27 +0000 Original-Received: from localhost ([127.0.0.1]:50508 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1TAlH8-00020g-L6 for submit@debbugs.gnu.org; Sun, 09 Sep 2012 13:26:26 -0400 Original-Received: from mtaout20.012.net.il ([80.179.55.166]:46210) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1TAlH5-00020Y-RI for 12314@debbugs.gnu.org; Sun, 09 Sep 2012 13:26:25 -0400 Original-Received: from conversion-daemon.a-mtaout20.012.net.il by a-mtaout20.012.net.il (HyperSendmail v2007.08) id <0MA300000F20Z100@a-mtaout20.012.net.il> for 12314@debbugs.gnu.org; Sun, 09 Sep 2012 20:25:52 +0300 (IDT) Original-Received: from HOME-C4E4A596F7 ([87.69.4.28]) by a-mtaout20.012.net.il (HyperSendmail v2007.08) with ESMTPA id <0MA3000RBF34UV10@a-mtaout20.012.net.il>; Sun, 09 Sep 2012 20:25:52 +0300 (IDT) In-reply-to: <87r4qbr5s1.fsf@gnu.org> X-012-Sender: halo1@inter.net.il X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.13 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 2) X-Received-From: 140.186.70.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.bugs:64010 Archived-At: > From: Chong Yidong > Cc: Drew Adams , 12314@debbugs.gnu.org > Date: Sun, 09 Sep 2012 15:53:34 +0800 > > Eli Zaretskii writes: > > > But the manual should cater first and foremost to newbies. The rest > > will get the point when they read the detailed description of how the > > list is modified. > > I modified the manual to hopefully make the situation clearer. In > particular, the descriptions of delq and delete explicitly say that you > typically ought to use the return value. Thanks, the text is much better now. I still think the "destructive modification" part should be retired to later in the description, perhaps as notes, because it invokes mental models that get in the way of interpreting the text correctly. But I won't fight over it. > The docstrings are harder, since they should be succinct. Here is what > I suggest; WDYT? > > > (delq ELT LIST) > > Delete by side effect occurrences of ELT as a member of LIST. > Comparison is done with `eq'. Return the resulting list. > > More precisely, this function skips any occurrences of ELT at the > front of LIST, then removes occurrences of ELT from the remaining > sublist by modifying the list structure, then returns the resulting > sublist. > > Therefore, write `(setq foo (delq element foo))' to be sure of > changing the value of `foo'. I would remove the "by side effect" part, as it doesn't really add anything of importance, and OTOH runs a real risk of confusing the reader. Otherwise, I think this is fine. Thanks. > (delete ELT SEQ) > > Delete occurrence of ELT as a member of SEQ. > SEQ must be a sequence (i.e. a list, a vector, or a string). > Comparison is done with `equal'. Return the resulting sequence. > > If SEQ is a list, this behaves like `delq', except that it compares > with `equal' instead of `eq'. In particular, it may remove elements > by altering the list structure. > > If SEQ is not a list, deletion is not a side effect; this function > creates and returns a new sequence. > > Therefore, write `(setq foo (delete element foo))' > to be sure of changing the value of `foo'. This is also OK, except that I'd prefer an explicit description to a reference to 'delq' in the second paragraph. The corresponding text in the doc string of 'delq' is short enough, so there are no real savings in the reference, while the disadvantage of having to consult another doc string is real.