9:17 p.m.
NOTE: This patch has been committed.
Ar an seachtú lá déag de mí Aibréan, scríobh Stephen J. Turnbull>:
[on my changes to push] This wording is not an improvement;
"add" could
be interpreted to mean "append" or even "insert at some arbitrary,
possibly variable, position." Also, in XEmacs Lisp PLACE need not refer
to a list [...]
[on pushnew] Ditto, except worse since the pseudo-code isn't present.
Okay, points taken on board.
All of the following could be improved by rewriting to refer to
related functions. Eg,
+A cons cell is a Lisp object (an area in memory) comprising two pointers
+called the CAR and the CDR. Each of these pointers can point to any other
+Lisp object. The common Lisp data type, the list, is a specially-structured
+series of cons cells.
A cons cell is a Lisp object containing two references to
arbitrary Lisp objects. The references are accessed with `car'
and `cdr', and mutated with `setcar' and `setcdr' respectively.
For historical reasons, the aliases `rplaca' and `rplacd' (for
`setcar' and `setcdr') are supported. Many structures are built
up from cons cells (lists, alists, plists). [...]
(So much passive voice! Are you sure you were born in the US? :-)
I’ve taken that and the rest of your mail on board, but not in its entirety
as I did for the cl.el changes. I think we can have equally legitimate
differing opinions on questions of prose style.
lisp/ChangeLog addition:
2006-04-23 Aidan Kehoe <kehoea(a)parhasard.net>
* cl.el (push):
* cl.el (pushnew):
Take on board Stephen's criticism of my last changes to the CL
docstrings.
src/ChangeLog addition:
2006-04-23 Aidan Kehoe <kehoea(a)parhasard.net>
* alloc.c:
* data.c:
* data.c (Fconsp):
* data.c (Flistp):
Take on board feedback from Stephen on my last change; move the
explanation of what a cons is to the cons docstring, add cross
references to that from the consp and atomp docstrings.
XEmacs Trunk source patch:
Diff command: cvs -q diff -u
Files affected: src/data.c src/alloc.c lisp/cl.el
Index: lisp/cl.el
===================================================================
RCS file: /pack/xemacscvs/XEmacs/xemacs/lisp/cl.el,v
retrieving revision 1.16
diff -u -u -r1.16 cl.el
--- lisp/cl.el 2006/04/16 15:54:16 1.16
+++ lisp/cl.el 2006/04/23 20:07:35
＠＠ -159,15 +159,17 ＠＠
(cl-do-pop place)))
(defmacro push (newelt listname)
- "Add NEWELT to the list stored in LISTNAME.
-Analogous to (setf LISTNAME (cons NEWELT LISTNAME)), though more careful about
-evaluating each argument only once and in the right order. LISTNAME may
-be a symbol, or any generalized variable allowed by `setf'."
+ "Add NEWELT at the beginning of the list stored in LISTNAME.
+Analogous to (setf LISTNAME (cons NEWELT LISTNAME)), though more careful
+about evaluating each argument only once and in the right order. LISTNAME
+may be a symbol, or any generalized variable allowed by `setf'; that is, it
+does not necessarily have to be a list, though `push' is most often used on
+lists. "
(if (symbolp listname) `(setq ,listname (cons ,newelt ,listname))
(list 'callf2 'cons newelt listname)))
(defmacro pushnew (newelt listname &rest keys)
- "Add NEWELT to the list stored in LISTNAME, unless it's already there.
+ "Add NEWELT at the beginning of LISTNAME, unless it's already in LISTNAME.
Like (push NEWELT LISTNAME), except that the list is unmodified if NEWELT is
`eql' to an element already on the list.
Keywords supported: :test :test-not :key"
Index: src/alloc.c
===================================================================
RCS file: /pack/xemacscvs/XEmacs/xemacs/src/alloc.c,v
retrieving revision 1.125
diff -u -u -r1.125 alloc.c
--- src/alloc.c 2006/03/26 15:24:26 1.125
+++ src/alloc.c 2006/04/23 20:07:39
＠＠ -1255,7 +1255,16 ＠＠
Lisp_Cons);
DEFUN ("cons", Fcons, 2, 2, 0, /*
-Create a new cons, give it CAR and CDR as components, and return it.
+Create a new cons cell, give it CAR and CDR as components, and return it.
+
+A cons cell is a Lisp object (an area in memory) made up of two pointers
+called the CAR and the CDR. Each of these pointers can point to any other
+Lisp object. The common Lisp data type, the list, is a specially-structured
+series of cons cells.
+
+The pointers are accessed from Lisp with `car' and `cdr', and mutated with
+`setcar' and `setcdr' respectively. For historical reasons, the aliases
+`rplaca' and `rplacd' (for `setcar' and `setcdr') are supported.
*/
(car, cdr))
{
Index: src/data.c
===================================================================
RCS file: /pack/xemacscvs/XEmacs/xemacs/src/data.c,v
retrieving revision 1.66
diff -u -u -r1.66 data.c
--- src/data.c 2006/04/16 15:54:21 1.66
+++ src/data.c 2006/04/23 20:07:40
＠＠ -217,10 +217,8 ＠＠
DEFUN ("consp", Fconsp, 1, 1, 0, /*
Return t if OBJECT is a cons cell. `nil' is not a cons cell.
-A cons cell is a Lisp object (an area in memory) comprising two pointers
-called the CAR and the CDR. Each of these pointers can point to any other
-Lisp object. The common Lisp data type, the list, is a specially-structured
-series of cons cells.
+See the documentation for `cons' or the Lisp manual for more details on what
+a cons cell is.
*/
(object))
{
＠＠ -229,6 +227,9 ＠＠
DEFUN ("atom", Fatom, 1, 1, 0, /*
Return t if OBJECT is not a cons cell. `nil' is not a cons cell.
+
+See the documentation for `cons' or the Lisp manual for more details on what
+a cons cell is.
*/
(object))
{
＠＠ -238,9 +239,9 ＠＠
DEFUN ("listp", Flistp, 1, 1, 0, /*
Return t if OBJECT is a list. `nil' is a list.
-A list is implemented as a series of cons cells structured such that the CDR
-of each cell either points to another cons cell or to `nil', the special
-Lisp value for both Boolean false and the empty list.
+A list is either the Lisp object nil (a symbol), interpreted as the empty
+list in this context, or a cons cell whose CDR refers to either nil or a
+cons cell. A "proper list" contains no cycles.
*/
(object))
{
--
In the beginning God created the heavens and the earth. And God was a
bug-eyed, hexagonal smurf with a head of electrified hair; and God said:
“Si, mi chiamano Mimi...”