[plt-scheme] documentation feature requests

From: Robby Findler (robby at eecs.northwestern.edu)
Date: Sun Nov 15 18:40:47 EST 2009

I've seen that Jon Rafkind has been adding such things to lots of
places in the docs and I've put them in the new image documentation
library (http://pre.plt-scheme.org/docs/html/teachpack/2htdpimage.html),
so I think it is safe to say we recognize the need and are working on


On Sun, Nov 15, 2009 at 5:24 PM, Lee Spector <lspector at hampshire.edu> wrote:
> Crutches are often quite useful! :-)
> Minimal examples shouldn't add much clutter, and a minimal example can
> establish a base line of understanding even when more reading would be
> necessary to do anything fancier.
> I mentioned the use of examples in the Processing documentation -- here's a
> link: http://processing.org/reference/ . You'll see that almost every
> procedure is introduced with a simple example, sometimes just a single line
> (although in some cases it has to be quite a bit longer). One can often just
> glance at the example and know how to use the procedure in the simplest
> cases, without reading anything else.
> There are already a few examples of the sort that I'm talking about in the
> PLT documentation -- for example I like the examples for build-list and for
> several of the other procedures in section 3.9. What I was hoping to
> encourage was the inclusion of such example more uniformly throughout the
> documentation.
>  -Lee
> On Nov 15, 2009, at 5:58 PM, Neil Van Dyke wrote:
>> 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/
> --
> Lee Spector, Professor of Computer Science
> School of Cognitive Science, Hampshire College
> 893 West Street, Amherst, MA 01002-3359
> lspector at hampshire.edu, http://hampshire.edu/lspector/
> Phone: 413-559-5352, Fax: 413-559-5438
> Check out Genetic Programming and Evolvable Machines:
> http://www.springer.com/10710 - http://gpemjournal.blogspot.com/
> _________________________________________________
>  For list-related administrative tasks:
>  http://list.cs.brown.edu/mailman/listinfo/plt-scheme

Posted on the users mailing list.