Re: The doc-strings for car and cdr are insulting.

[Luc Teirlinck]

Alan Mackenzie wrote:

   I was thinking that, although my proposed doc-strings are not the whole
   truth, they might be the clearest explanation for a raw beginner at lisp.

I do not exactly believe that reading docstrings is the best way for a
raw beginner at Lisp to start to learn Elisp.  Depending on the
person's inclination, he might either use the "Introduction to
Programming in Emacs Lisp" manual or the Elisp reference manual.  Both
are now included with the Emacs distribution.  I do not believe that
it makes a lot of sense to try to make docstrings play a role that
they quite simply can not play.

Docstrings for commands should contain notes about interactive usage
that are understandable by non-Elisp programmers, because they can be
consulted by Emacs users, but that is a different question.

I believe that it is perfectly all right for docstrings to assume a
certain minimum familiarity with Elisp, except for the description of
interactive usage of commands.

   However, the current (vacuous) definitions

They are not vacuous.  The _functions_ c[ad]r return the _objects_
c[ad]r, which is not the same thing.  It may be easy to guess the
purpose of the functions from the name, but it is not bad to make it
unambiguously clear anyway.  The reason somebody would do `C-h f
c[ad]r' is for the (non-trivial) details in the remainder of the
docstring, not to get a first introduction to Elisp.

   How about something like the following, changing "LIST" to "CONS",

That might indeed avoid some confusion (namely that the argument would
have to be a proper list).  Of course, the actual argument in the code
would need to be changed too, for consistency.

   Return the \"left hand side\" of CONS.

Your raw beginner would probably not know what a CONS is to begin
with.   I believe that the current version:  "Return the car of list."
is shorter and clearer.

Sincerely,

Luc.