Re: Documentation for car and cdr

[Alan Mackenzie]

Hi, Thi!

On 25 Jan 2006, Thien-Thi Nguyen wrote:

>Alan Mackenzie <address@hidden> writes:

>> Each of these sentences is completely accurate (by virtue of "loosely
>> speaking"), regardless of whether LIST is a list, a dotted pair, or
>> nil.

>blech.  placing "loosely speaking" in the docstring decreases
>credibility (take it from a practiced word weasler: those are weasel
>words), and does not clarify anything.  that's certainly a bad move.

How would you answer "What's Emacs?".  "Loosely speaking, it's a
programmers' editor" is correct, and a good answer.  "A programmers'
editor" will raise the hackles of Gnus fans and some professional
writers.  "An extensible editing system, programmed in lisp, including
specialized facilities for ..... [ snip next 10 line ]" will bore the
questioner to tears and make him wish he hadn't asked.  "It's Emacs!" is
vacuous.

Describing intuitively what car/cdr mean is useful.  I think that "car
returns the car" and "cdr returns the cdr" have negative value - they
irritate without enlightening.

>(note: CERTAINLY, not just LOOSELY SPEAKING.)

>this whole thread is populated by people who know what CAR and CDR are.
>people who don't, who *might* be confused, who *may* be offended by such
>crass self-documentation; they won't read this or the docstring anyway!

Again, I disagree.  A fledgling Elisp hacker is likely to spend time
reading through existing code.  She's likely to expect C-h f to tell her
what the mysterious functions do.

>now, i suppose someone will lark an ostensibly non-expert friend into
>sending a bug report on this.  what, is it 1-april already?

I submitted precisely this issue as a bug a little over a year ago.  (And
no, I have not communicated with the OP in this thread.)  From that
discussion, and this one, it seems clear that people have widely varying
expectations of what doc-strings should be.  David K. wants rigour at all
costs;  The OP and I want clarity.  Most doc strings are rigorous, clear
and helpful at the same time.  Why can't those for car and cdr also be
so?

>thi

-- 
Alan.