[plt-scheme] documentation feature requests

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
it.

Robby

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
>