GNU bug report logs - #9482
Documentation bug: Emacs Lisp Manual should say quoting does not cons explicitly in quoting section. related to bug#9469

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 9482 in the body.
You can then email your comments to 9482 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Le Wang <l26wang <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: Documentation bug: Emacs Lisp Manual should say quoting does not cons
	explicitly in quoting section. related to bug#9469
Date: Mon, 12 Sep 2011 23:01:23 +0800

Relevant page here:
http://www.gnu.org/s/emacs/manual/html_node/elisp/Quoting.html

I was confused and always assumed that

'(a . b)

is simply short hand for

(cons 'a 'b)

Reading stackexchange, it seems at least some other people are under
this impression as well.  This works a majority of the time, but when
it fails it's really surprising.

In fact, the manual already has an example of this pit-fall in the
nconc section: http://www.gnu.org/software/emacs/elisp/html_node/Rearrangement.html

I think the quoting section should give an explicit warning with a
reference to the nconc example.



-- 
Le

Message #8 received at 9482 <at> debbugs.gnu.org (full text, mbox):

From: Le Wang <l26wang <at> gmail.com>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: 9482 <at> debbugs.gnu.org
Subject: specific manual text suggestion
Date: Tue, 13 Sep 2011 21:25:28 +0800

Hi Stefan,

As I mentioned in this bug.  The manual already has an example of this
trap in the nconc section.  Maybe just a pointer to it.

So my suggestion for specific text would be:

"WARNING: '(a . b) is not short-hand for (cons 'a 'b).  The former
does not cons.  Quoting should be reserved for constants that will
*NEVER* change.  See <link>nconc</link> for example of unexpected
results when a quoted object is modified."

My terminology may be not quite right, but if I read something like
this, the difference would be much clearer.

-- 
Le

Message #13 received at 9482-done <at> debbugs.gnu.org (full text, mbox):

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Le Wang <l26wang <at> gmail.com>
Cc: 9482-done <at> debbugs.gnu.org
Subject: Re: specific manual text suggestion
Date: Fri, 16 Sep 2011 10:14:39 -0400

> My terminology may be not quite right, but if I read something like
> this, the difference would be much clearer.

Thanks for your sample text.  I tweaked it a bit to make it hopefully
even more explicit, see patch below.


        Stefan


--- src/eval.c	2011-09-09 01:06:52 +0000
+++ src/eval.c	2011-09-16 14:09:39 +0000
@@ -475,6 +475,14 @@
 
 DEFUN ("quote", Fquote, Squote, 1, UNEVALLED, 0,
        doc: /* Return the argument, without evaluating it.  `(quote x)' yields `x'.
+Warning: `quote' does not construct its return value, but just returns
+the value that was pre-constructed by the Lisp reader (see info node
+`(elisp)Printed Representation').
+This means that '(a . b) is not identical to (cons 'a 'b): the former
+does not cons.  Quoting should be reserved for constants that will
+never be modified by side-effects, unless you like self-modifying
+code.  See the common pitfall in info node `(elisp)Rearrangement' for
+an example of unexpected results when a quoted object is modified.
 usage: (quote ARG)  */)
   (Lisp_Object args)
 {

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.