Here are a few suggestions for a PLT-specific cookbook, in which our primary goal is to provide information to users of PLT Scheme. However, we also want the reader to be aware of what is PLT-specific, so that they can converse in the broader Scheme community and avoid unnecessary nonportability in their code; and I think we have a secondary goal of helping the reader to use other Schemes, since one of the benefits of Scheme is that you can retarget to any of a wealth of good implementations if you need to.
Avoid totally gratuitous PLT-isms. For example, I wouldn't use match simply to get the first element of the list in an example (unless the example were intended to illustrate match, or there were symmetry with other uses of match in the example). However, use PLTisms with impunity wherever they help.
When introducing a non-R5RS-ism in a discussion, a subtle reference to PLT-ismness (e.g., "The PLT match syntax can be used...") would be helpful. Likewise, we could say "The Scheme do syntax..." or "The R5RS do syntax..." when introducing a Scheme concept that isn't PLT-specific.
Some convention similar in intent to a sidebar or a box could be used to say whether and how you can do the same thing in particular other popular Scheme implementations. For example, "This works in R5RS implementations with SRFI-6," "R5RS syntax-rules is similar but does not use PLT syntax objects, so...," "Other Scheme implementations have different module systems. Bigloo's module system is documented in...," and "An equivalent but more verbose R5RS procedure that doesn't use match is..." [ SiteToDo: we currently don't have any way of doing sidebars or boxes ]
I suppose this is only a small step from a multiple-implementation cookbook. But, as a reader interested mainly in PLT, I'd hate to wade through piles of examples employing non-PLT object systems and such. (At least that would be a problem in print, though fancy hypertext could ellide irrelevant implementations in a convenient way, if someone wanted
to volunteer Anton to invent that. :)
-- NeilVanDyke - 11 May 2004
The above all sounds fine to me, except for the part where I have to invent stuff. :) We probably could do something fancy with hypertext, but I'll be happy just to get a decent automatic table of contents capability!
-- AntonVanStraaten - 19 May 2004
RSS