bug#9082: Add hints to documentation of car and cdr for (e)lispnewcomers

["Drew Adams" <drew.adams@oracle.com>]

> It's really hard to explain these two functions, because they are so
> simple and have little intrinsic meaning.  Which is why they 
> were called why they're called, and not `first' and `rest' (which also has
> proponents).

No, that is not the reason why they were called `car' and `cdr'.
http://en.wikipedia.org/wiki/CAR_and_CDR

And no, it's not difficult to describe these two functions.

It's nearly enough to say:

1. `cons' creates a pair (called a "cons cell" or a "cons") from its two
arguments.

2. (car (cons a b)) = a
   (cdr (cons a b)) = b

That's in fact the definition, and it's a pretty good explanation too.

I say "nearly" enough because it also helps to explain more about conses and
list structure (what's shared, what is not, etc.).

Lisp is not a purely functional language, so while #2 above defines these two
functions functionally, it does not describe them in terms of behavior.  Mainly
because it begs the question of `cons', which is not a pure function and which
is where list structure comes into the picture.

If `cons' were simply a constructor in the functional language (or rewrite or
algebra) sense of that word (essentially an undefined function), then #2 above
would suffice.

> If a user sees
> (setq a '(foo . bar))
> (zot (cdr a))
> I don't see how looking up `cdr' and seeing "(rest)" really
> unconfuses all that much.  Pointing to the manual is the only 
> thing that will help here, in my opinion.

Here, I agree with you, Lars.

`rest' does not describe `cdr', especially when `rest' is thought of in terms of
purely functional languages.  Again, the nub is `cons' and the behavior.

It is also true as has been pointed out that the word `rest' is a better fit for
true lists than for conses.