Re: Documentation for car and cdr

[Alan Mackenzie]

On Wed, 25 Jan 2006, Luc Teirlinck wrote:

>Describing basic concepts like car, cdr, cons cell, list and so on is
>the task of manuals, not of docstrings.

That has not been established.  And even if it had, a one-liner
description in a doc-string is likely to be convenient and helpful.

>If somebody is not familiar with the basic concepts, they have to read a
>manual, where those concepts can be put into the proper context, _not_
>individual docstrings.

Suppose somebody has read the manuals, a bit.  She knows what car and cdr
mean, roughly, but isn't quite sure which is which.  C-h f is a
convenient way of checking.  Or it could be.

>There are two different Elisp manuals included with the Emacs
>distribution.  Why on earth would a beginning Elisp programmer try to
>learn Elisp exclusively through the docstrings rather than through the
>one of these two manuals?

Your begging the question here.  I don't think anybody (least of all me)
is suggesting that doc-strings should supplant the manuals.  But I am
saying that somebody needing a short snappy one-liner description of a
function shouldn't be forced to go through the drudgery of opening the
Elisp manual, finding the page "cdr" is on, then ploughing through all
the "broadening your horizons" documentation to reach that one critical
sentence.

Different people use manuals and doc-strings in different ways.

>Sincerely,

>Luc.

-- 
Alan.