[racket] user's guide feedback/questions as I prepare for my PL course

On Fri, Aug 26, 2011 at 3:57 PM, Matthias Felleisen
<matthias at ccs.neu.edu> wrote:
>> 6. In reading the User's Guide, I was pretty surprised that first
>> (unlike car) raises an error on a non-list.  I eventually looked over
>> at the Reference Guide where I learned that list? is O(1) and I was
>> able to connect the dots -- "aha, now /this/ is a pretty cool reason
>> to make cons cells immutable beyond the basic 'set-cdr! is nasty' ".
>> I recommend the User's Guide include a comment or footnote that first
>> is an O(1) operation -- you can just point to the Reference Guide for
>> any details.
>
> Where do you think it's best to say so? Lists are a bit scattered
> over the Guide, and I didn't find the place where (first '())
> signals an error. [Not that this is necessarily the best place.]

I agree things are a big scattered so it's not clear.  first and rest
are introduced in 2.3.2, but almost by accident and the section title
wouldn't suggest this.  first and rest are not mentioned in 3.8 which
is certainly odd.  So you might consider adding to 3.8 a paragraph on
first and rest, how they're basically defined in terms of list?, car,
and cdr (unless you'd prefer not to explain them that way -- I'm fine
either way), and how list?, first, and rest are O(1) operations (again
this could be in a sidebar).

--Dan