[plt-scheme] documentation feature requests

Oh indeed, those are wonderful examples that I hadn't previously seen  
in the image library. That's exactly the sort of thing I'd love to see  
everywhere some day.

Thanks,

  -Lee

On Nov 15, 2009, at 6:40 PM, Robby Findler wrote:

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

--
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/