Re: Documentation for car and cdr

[Alan Mackenzie]

Hi, Luc!

On Sun, 29 Jan 2006, Luc Teirlinck wrote:

>Ken Manheimer wrote:

>   language lawyers know what `car' does - you need to ask what clues
>   will help someone who is lost enough to ask.

>If that person did `C-h f car' because he did not know what a car was,
>that is, because he does not know the very basics of Lisp, the clue that
>will help him is that he should learn Lisp by studying a manual, not by
>reading docstrings.

This seems maximally unhelpful to me.  Many people do not pass from total
ignorance to total familiarity in a single pass of an introductory
manual.  I certainly don't.  Whilst passing between these two states,
some people are going to want continual concise reminders of what car and
cdr mean.  "RTFM!" isn't very helpful - opening an FM and navigating to
the right place, time after time after time, is mind-numbing.  Possibly
the best way for a newbie to compensate for the current doc-strings of
car and cdr is to make her own notes on a piece of paper and stick it to
the side of her monitor.  Is this a Good Thing?  Should we put such a
suggestion into emacs-lisp-intro.texi?

The argument in your last paragraph is an argument for doing away with
doc-strings altogether.  Surely if a Lisp hacker wants to check the
meaning or parameters of a function, he should study the manual rather
than reading a doc-string?  Why should car's and cdr's doc-strings be so
different from other functions'?

>If the person doing `C-h f car' _does_ know Lisp, then the only likely
>reason why he consulted the docstring of car is because it is unclear
>to him what happens if the arg is not a cons cell.

Untrue, unless "does know Lisp" means "is already a competentent Lisp
hacker".  There are several reasons for doing `C-h f car': for example:

(i) Somebody's got the names "car" and "cdr" confused.
(ii) It's the morning after the night before, and "car" evokes the
  response "whaaaattt???".
(ii) Somebody's been using car quite happily on lists, and comes across
  (car dotted-pair) for the very first time.

>So the docstring should make three things clear:

>1.  If the arg is nil, `car' returns nil.

>2.  If the arg is neither nil nor a cons cell, an error is thrown.

>3.  If you do not want an error in the above case, use car-safe.

but not what "car" does?  How about:

0>.  `car' returns the first element of a list or dotted pair.

Why do you object so strongly to such a sentence in the doc-string?

>Here is the docstring of car:

>    Return the car of list.  If arg is nil, return nil.
>    Error if arg is not nil and not a cons cell.  See also `car-safe'.

>    See Info node `(elisp)Cons Cells' for a discussion of related basic
>    Lisp concepts such as car, cdr, cons cell and list.

>That last sentence was added by me (on Richard's request) yesterday in
>a desperate, but apparently futile, attempt to make this time wasting
>thread stop.

The lack of a description of `c[ad]r' in their doc-strings wastes the
time of Emacs newbies.  I think we differ in our judgements of the
relative worth of our time and their time.

>If the docstring of car does not make the three points above clear
>enough, it needs fixing.  Otherwise it does not.

I think it needs fixing, and I've already suggested a fix.  One enormous
benefit of putting "first element of a list/dotted-pair" into the
doc-string would have would be to prevent this time wasting discussion on
emacs-devel happening ever again.  :-)

>Sincerely,

>Luc.

-- 
Alan.