all messages for Emacs-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
From: Glenn Morris <rgm@gnu.org>
To: asjo@koldfront.dk (Adam Sjøgren)
Cc: Lars Magne Ingebrigtsen <larsi@gnus.org>, 9082@debbugs.gnu.org
Subject: bug#9082: Add hints to documentation of car and cdr for (e)lisp newcomers
Date: Thu, 14 Jul 2011 15:47:43 -0400	[thread overview]
Message-ID: <imxggk5k0.fsf@fencepost.gnu.org> (raw)
In-Reply-To: <87k4bkd61a.fsf@topper.koldfront.dk> ("Adam Sjøgren"'s message of "Thu, 14 Jul 2011 21:19:13 +0200")


>>> DEFUN ("cdr", Fcdr, Scdr, 1, 1, 0,
>>> !        doc: /* Return the cdr (rest) of LIST.  If arg is nil, return nil.
[...]
> ¹ "When cons cells are used to implement singly linked lists (rather
>    than trees and other more complicated structures), the car operation
>    returns the first element of the list, while cdr returns the rest of
>    the list." - http://en.wikipedia.org/wiki/CAR_and_CDR

To me, "rest" means nothing with no context.
It's fine to say: "A returns the first element, and B the rest."
But just saying on its own "B returns the rest" with no reference to A
means nothing.
I might say "B returns everything but the first element".

But really, one should read the Lisp intro or something if one does not
know what car and cdr mean. The doc string of such fundamental functions
shouldn't be expected to bootstrap from zero knowledge IMO.

Oh, I see there is already a reference to the lisp manual in these doc
strings. So personally I don't think any change was needed...

Also to complete my bitching, this should be marked "tiny change" since
we don't have an Emacs assignment (only a Gnus one).





  reply	other threads:[~2011-07-14 19:47 UTC|newest]

Thread overview: 8+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2011-07-14 15:03 bug#9082: Add hints to documentation of car and cdr for (e)lisp newcomers Adam Sjøgren
2011-07-14 18:31 ` Lars Magne Ingebrigtsen
2011-07-14 19:19   ` Adam Sjøgren
2011-07-14 19:47     ` Glenn Morris [this message]
2011-07-14 20:09       ` Lars Magne Ingebrigtsen
2011-07-14 20:28         ` Adam Sjøgren
2011-07-14 20:37           ` Lars Magne Ingebrigtsen
2011-07-14 21:20             ` bug#9082: Add hints to documentation of car and cdr for (e)lispnewcomers Drew Adams

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=imxggk5k0.fsf@fencepost.gnu.org \
    --to=rgm@gnu.org \
    --cc=9082@debbugs.gnu.org \
    --cc=asjo@koldfront.dk \
    --cc=larsi@gnus.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this external index

	https://git.savannah.gnu.org/cgit/emacs.git
	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.