[plt-scheme] documentation feature requests

I actually find writing examples for procedures to be relatively fun, as 
API documentation goes.  (Though not as much fun as it used to be, now 
that I'm targeting so-so HTML, rather than nicely typeset PDF with my 
pretty TeXinfo "@result{}" arrow and everything.)

I can also see validity of arguments, e.g., that lots of little examples 
often clutter the documentation unnecessarily, and that such examples 
are often used as crutches in lieu of understanding the language, 
library, or problem domain.

Also note that examples won't necessarily avert you having to look 
around at bits of documentation.  Below is an example from one of my 
libraries.  You could use it as a model for how to turn a CSV file into 
SXML, but that doesn't tell you how to transform the SXML, nor pick 
values out of it, nor write it out as XML, etc.  Such things are not 
within the scope of the documentation of this procedure nor this library.

> For example, given a CSV-format file friends.csv that has the contents:
>
> Binoche,Ste. Brune,33-1-2-3
> Posey,Main St.,555-5309
> Ryder,Cellblock 9,
>
> with elements not given, the result is:
>
>   (csv->sxml (open-input-file "friends.csv"))
>   ==>
>   (*TOP*
>    (row (col-0 "Binoche") (col-1 "Ste. Brune")  (col-2 "33-1-2-3"))
>    (row (col-0 "Posey")   (col-1 "Main St.")    (col-2 "555-5309"))
>    (row (col-0 "Ryder")   (col-1 "Cellblock 9") (col-2 "")))
>
> With elements given, the result is like:
>
>   (csv->sxml (open-input-file "friends.csv")
>              'friend
>              '(name address phone))
>   ==>
>   (*TOP* (friend (name    "Binoche")
>                  (address "Ste. Brune")
>                  (phone   "33-1-2-3"))
>          (friend (name    "Posey")
>                  (address "Main St.")
>                  (phone   "555-5309"))
>          (friend (name    "Ryder")
>                  (address "Cellblock 9")
>                  (phone   "")))

-- 
http://www.neilvandyke.org/