RE: Documentation for car and cdr

[Drew Adams]

Repeating, since people are still discussing "list" in this context.

    Use the following doc strings (or similar):  

    ----
    (car ARG):
    
    Return the car (first part) of a cons cell.
    ARG must be a cons cell or nil, or else an error is raised.
    (car (cons a b)) returns a.
    (car nil) returns nil.
    See also `car-safe'.

    ----
    (cdr ARG):
    
    Return the cdr (second part) of a cons cell.
    ARG must be a cons cell or nil, or else an error is raised.
    (cdr (cons a b)) returns b.
    (cdr nil) returns nil.
    See also `cdr-safe'.
    

    These descriptions are precise but also clear enough wrt what the
    "car" and the "cdr" of a cons cell mean (first/second part of a 
    cons cell).  The first line provides the raison d'etre and core
    meaning; the other lines mention the nil and error cases.
    
    There is no need to cross-reference the manual's explanation of
    "cons cell", and the manual section on lists should definitely not
    be cross-referenced.  Users not understanding these doc strings
    will naturally look at the doc for `cons', which is what we want
    them to do.
 
    The doc strings should not mention "list" at all, especially as the
    argument name.  There is no reason to do so, and that can be
    misleading, due to the use of "list" in the doc for both:
    
     1) consp or null, and
     2) "true list" (nil as last cdr).