--- a/lisp/ChangeLog	Sun Apr 23 16:11:34 2006 +0000
+++ b/lisp/ChangeLog	Sun Apr 23 20:12:31 2006 +0000
@@ -1,3 +1,10 @@
+2006-04-23  Aidan Kehoe  <kehoea@parhasard.net>
+
+	* cl.el (push):
+	* cl.el (pushnew):
+	Take on board Stephen's criticism of my last changes to the CL
+	docstrings.
+	
 2006-04-24  Stephen J. Turnbull  <stephen@xemacs.org>
 
 	* dumped-lisp.el (fontconfig): Load only with Xft.

--- a/lisp/cl.el	Sun Apr 23 16:11:34 2006 +0000
+++ b/lisp/cl.el	Sun Apr 23 20:12:31 2006 +0000
@@ -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"

--- a/src/ChangeLog	Sun Apr 23 16:11:34 2006 +0000
+++ b/src/ChangeLog	Sun Apr 23 20:12:31 2006 +0000
@@ -1,3 +1,13 @@
+2006-04-23  Aidan Kehoe  <kehoea@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. 
+	
 2006-04-23  Stephen J. Turnbull  <stephen@xemacs.org>
 
 	* Makefile.in.in (x_objs): Change xft-fonts.o to font-mgr.o.

--- a/src/alloc.c	Sun Apr 23 16:11:34 2006 +0000
+++ b/src/alloc.c	Sun Apr 23 20:12:31 2006 +0000
@@ -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))
 {

--- a/src/data.c	Sun Apr 23 16:11:34 2006 +0000
+++ b/src/data.c	Sun Apr 23 20:12:31 2006 +0000
@@ -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))
 {