Re: [racket-dev] define-struct exports something to BSL

2010-09-22 Thread Michael Sperber

Nadeem Abdul Hamid nad...@acm.org writes:

 Consider a beginner file with:
(define-struct boa (name length))

 Student writes a template/function with parameter named a-boa, but
 misspells one occurrence, writing boa instead of a-boa.

 (define (feed a-boa)
   (make-boa (boa-name a-boa)
 (boa-length boa)))

 Their tests then fail at runtime with:
boa-length: expects argument of type struct:boa; given (make-signature 
 ...)

 Why is boa as a type visible at all in the student languages? The
 make-signature thing is really confusing, because they recognize it as
 something like a constructor but they don't know what structure it
 corresponds to.

This is my fault: We're working on something called signatures, which
can take the place of a contract comment, but is instead checked by the
system.  For example, one could write for the functions above:

(: make-boa (string number - boa))
(: boa-name (boa - string))
(: boa-length (boa - number))
(: feed (boa - boa))
 ^^^

This is why `boa' is available, and why you get output identifying boa
as a signature.  (Before the introduction of signatures, it would say
illegal use of syntax - I'm not sure that's much better.)

The work on signatures is not quite done yet (and undocumented ...), but
we're working hard on completing it in the near future.

-- 
Cheers =8-} Mike
Friede, Völkerverständigung und überhaupt blabla
_
  For list-related administrative tasks:
  http://lists.racket-lang.org/listinfo/dev


Re: [racket-dev] Racket documentation

2010-09-22 Thread Neil Van Dyke

Eli Barzilay wrote at 09/22/2010 01:18 AM:

The punchline is that your desire to use a local copy is in direct 
contradiction with the desire to get community involvement in improving the 
docs. No matter what facility is available for the community to discuss and 
supplement the docs -- if you have to go out of your way to see it, then you 
(the collective) just won't do it (statistically speaking).
  


I think that you can make online docs sufficiently immediate value-added 
that people are drawn to use those.


This can be done without compromising local-copy docs.  If you did the 
online right, everyone knows that they get immediate benefit from the 
value-add of the online docs, so they must have a good reason when they 
use local copy.


For a simple example of docs similar to Racket's can be online and 
participatory to some degree, see PostgreSQL's.  They have their 
well-structured and well-edited manuals, and online you can browse a 
version with old-school community annotations at the bottom of each 
page.  I've found some of the annotations very helpful, and I'd hope 
that they feed future versions of the well-edited manuals.


You could also go more of a Wikipedia route.  But you don't have a 
million contributors, and you will be spending lots of effort on quality 
control, and with a relatively small contributor pool you have to be 
more cautious about alienating people when a contribution really needs 
to be excised.


Whatever you do, I hope that the goodness of well-edited local-copy docs 
is not compromised.


Also keep in mind that some of us think that, when working on library 
code or documentation, the interface should present both code and doc 
easily.  Usually, with dumb tools, that means JavaDoc-like embedded 
documentation.  I have a goal to make Racket support this better in the 
future, and I hope that any new online docs thing won't get in the way, 
and that I can be compatible with that.


The best that you'd get is yet another scheme cookbook 


I think that some of the problems that the Scheme Cookbook encountered 
are relevant to Racket.


One is that a few characters of Perl operators from some Perl Cookbook 
item, in the Scheme Cookbook could become a huge page full of different 
verbose, cryptic, and so-so quality attempts to do a comparable thing in 
Scheme.  (Which, in hindsight, should not have been surprising, when 
Schemers are involved.)  I finally decided that most of the cookbook 
entries would ideally mostly be pointers to reusable code libraries 
(*not* copypastemunge), which led to me to silly extremes like: 
http://www.neilvandyke.org/tabexpand-scheme/


There were also various quality control problems for various reasons.  I 
got disenchanted after realizing that messes were being created faster 
than good content, and that it would've been much easier for me to do 
something correctly from scratch than find a politic way to fix an 
existing entry or wrestle with the wiki software to reverse some bizarre 
structure change some user had done.  (This is actually much like 
software development in general.)


A problem that the Racket online docs *won't* necessarily have is that 
of scope: as I recall, the Scheme Cookbook was originally mostly 
PLT-specific, and some dork (me) advocated strongly that the Cookbook 
cover other Scheme implementations (e.g., R5RS whenever possible, then 
separate out the various implementation-specifics within an entry).  
This turned out to be additional mess and bulk.  Racket will still have 
to decide what to do about version differences, but any mess will be a 
lot smaller and simpler to organize.


--
http://www.neilvandyke.org/
_
 For list-related administrative tasks:
 http://lists.racket-lang.org/listinfo/dev


Re: [racket-dev] Racket documentation

2010-09-22 Thread Neil Van Dyke

And also, the wiki software kinda blew in many ways.

One of the biggest ways was a small thing with, I think, big 
implications: the software would by default add an attribution line for 
each edit, encouraging people to view the page as a dumbed-down Web 
commenting forum to append a comment to, rather than as a coherent 
document to refine holistically.


Also, depersonalization can be good: when there are no authorship names 
at all on a page, some people will have less resistance to making 
improvements.  This also removes some of the incentive to contribute for 
some people, which can cost the document some good contributions but 
also scare off some low-quality contributions (see, as cautionary tale: 
Java sites).  I think that removing incentive alone is not a net loss, 
and that depersonalization overall is a big net win.


Neil Van Dyke wrote at 09/22/2010 03:53 AM:

Eli Barzilay wrote at 09/22/2010 01:18 AM:
The punchline is that your desire to use a local copy is in direct 
contradiction with the desire to get community involvement in 
improving the docs. No matter what facility is available for the 
community to discuss and supplement the docs -- if you have to go out 
of your way to see it, then you (the collective) just won't do it 
(statistically speaking).
  


I think that you can make online docs sufficiently immediate 
value-added that people are drawn to use those.


This can be done without compromising local-copy docs.  If you did the 
online right, everyone knows that they get immediate benefit from the 
value-add of the online docs, so they must have a good reason when 
they use local copy.


For a simple example of docs similar to Racket's can be online and 
participatory to some degree, see PostgreSQL's.  They have their 
well-structured and well-edited manuals, and online you can browse a 
version with old-school community annotations at the bottom of each 
page.  I've found some of the annotations very helpful, and I'd hope 
that they feed future versions of the well-edited manuals.


You could also go more of a Wikipedia route.  But you don't have a 
million contributors, and you will be spending lots of effort on 
quality control, and with a relatively small contributor pool you have 
to be more cautious about alienating people when a contribution really 
needs to be excised.


Whatever you do, I hope that the goodness of well-edited local-copy 
docs is not compromised.


Also keep in mind that some of us think that, when working on library 
code or documentation, the interface should present both code and doc 
easily.  Usually, with dumb tools, that means JavaDoc-like embedded 
documentation.  I have a goal to make Racket support this better in 
the future, and I hope that any new online docs thing won't get in the 
way, and that I can be compatible with that.


The best that you'd get is yet another scheme cookbook 


I think that some of the problems that the Scheme Cookbook encountered 
are relevant to Racket.


One is that a few characters of Perl operators from some Perl Cookbook 
item, in the Scheme Cookbook could become a huge page full of 
different verbose, cryptic, and so-so quality attempts to do a 
comparable thing in Scheme.  (Which, in hindsight, should not have 
been surprising, when Schemers are involved.)  I finally decided that 
most of the cookbook entries would ideally mostly be pointers to 
reusable code libraries (*not* copypastemunge), which led to me to 
silly extremes like: http://www.neilvandyke.org/tabexpand-scheme/


There were also various quality control problems for various reasons.  
I got disenchanted after realizing that messes were being created 
faster than good content, and that it would've been much easier for me 
to do something correctly from scratch than find a politic way to fix 
an existing entry or wrestle with the wiki software to reverse some 
bizarre structure change some user had done.  (This is actually much 
like software development in general.)


A problem that the Racket online docs *won't* necessarily have is that 
of scope: as I recall, the Scheme Cookbook was originally mostly 
PLT-specific, and some dork (me) advocated strongly that the Cookbook 
cover other Scheme implementations (e.g., R5RS whenever possible, then 
separate out the various implementation-specifics within an entry).  
This turned out to be additional mess and bulk.  Racket will still 
have to decide what to do about version differences, but any mess will 
be a lot smaller and simpler to organize.



--
http://www.neilvandyke.org/
_
 For list-related administrative tasks:
 http://lists.racket-lang.org/listinfo/dev


Re: [racket-dev] Racket documentation

2010-09-22 Thread Eli Barzilay
On Sep 22, Neil Van Dyke wrote:
 Eli Barzilay wrote at 09/22/2010 01:18 AM:
  The punchline is that your desire to use a local copy is in direct
  contradiction with the desire to get community involvement in
  improving the docs. No matter what facility is available for the
  community to discuss and supplement the docs -- if you have to go
  out of your way to see it, then you (the collective) just won't do
  it (statistically speaking).
 
 I think that you can make online docs sufficiently immediate
 value-added that people are drawn to use those.

I don't believe that this will ever be effective enough.  We have a
large number of newcomers (because it's being used in courses there's
a constant stream of new students who later move on), and these people
will never see it.  Also, IMO if you need to choose to use some
alternative, then many people will never bother doing so, and many
people will not do it because they'll want to stick with a blessed
version.


 This can be done without compromising local-copy docs.  If you did
 the online right, everyone knows that they get immediate benefit
 from the value-add of the online docs, so they must have a good
 reason when they use local copy.

Specifically, you don't have to have any reason if it's the default.


 Whatever you do, I hope that the goodness of well-edited local-copy
 docs is not compromised.

I'm imagining having the docs with an easy way to see the user
contributions/discussions/suggestions -- and the improvements to the
actual docs would be done continuously based on this feedback.


 Also keep in mind that some of us think that, when working on
 library code or documentation, the interface should present both
 code and doc easily.  Usually, with dumb tools, that means
 JavaDoc-like embedded documentation.  I have a goal to make Racket
 support this better in the future, and I hope that any new online
 docs thing won't get in the way, and that I can be compatible with
 that.

Yeah -- that would be an issue of the doc sources are in a separate
place.  Doc sources that are in code (like a javadoc-like thing or a
literate programming thing) will have to stay there.

But given the overall excitement around this, I doubt that anything
will happen.


 I think that some of the problems that the Scheme Cookbook encountered 
 are relevant to Racket.  [...lots of issues with that wiki...]

These are all true, but they'd been much better still if there were
more people involved.  If you think about everybody that uses racket
having a (prominent) one-click access to the content, you get orders
of magnitude more eyes, and this can lead much better to a
self-organizing wikipedia-like effect.

-- 
  ((lambda (x) (x x)) (lambda (x) (x x)))  Eli Barzilay:
http://barzilay.org/   Maze is Life!
_
  For list-related administrative tasks:
  http://lists.racket-lang.org/listinfo/dev


Re: [racket-dev] Racket documentation

2010-09-22 Thread Matthias Felleisen

Don't talk it to death with long emails. Help people to get this started. -- 
Matthias



On Sep 22, 2010, at 4:30 PM, Eli Barzilay wrote:

 On Sep 22, Neil Van Dyke wrote:
 Eli Barzilay wrote at 09/22/2010 01:18 AM:
 The punchline is that your desire to use a local copy is in direct
 contradiction with the desire to get community involvement in
 improving the docs. No matter what facility is available for the
 community to discuss and supplement the docs -- if you have to go
 out of your way to see it, then you (the collective) just won't do
 it (statistically speaking).
 
 I think that you can make online docs sufficiently immediate
 value-added that people are drawn to use those.
 
 I don't believe that this will ever be effective enough.  We have a
 large number of newcomers (because it's being used in courses there's
 a constant stream of new students who later move on), and these people
 will never see it.  Also, IMO if you need to choose to use some
 alternative, then many people will never bother doing so, and many
 people will not do it because they'll want to stick with a blessed
 version.
 
 
 This can be done without compromising local-copy docs.  If you did
 the online right, everyone knows that they get immediate benefit
 from the value-add of the online docs, so they must have a good
 reason when they use local copy.
 
 Specifically, you don't have to have any reason if it's the default.
 
 
 Whatever you do, I hope that the goodness of well-edited local-copy
 docs is not compromised.
 
 I'm imagining having the docs with an easy way to see the user
 contributions/discussions/suggestions -- and the improvements to the
 actual docs would be done continuously based on this feedback.
 
 
 Also keep in mind that some of us think that, when working on
 library code or documentation, the interface should present both
 code and doc easily.  Usually, with dumb tools, that means
 JavaDoc-like embedded documentation.  I have a goal to make Racket
 support this better in the future, and I hope that any new online
 docs thing won't get in the way, and that I can be compatible with
 that.
 
 Yeah -- that would be an issue of the doc sources are in a separate
 place.  Doc sources that are in code (like a javadoc-like thing or a
 literate programming thing) will have to stay there.
 
 But given the overall excitement around this, I doubt that anything
 will happen.
 
 
 I think that some of the problems that the Scheme Cookbook encountered 
 are relevant to Racket.  [...lots of issues with that wiki...]
 
 These are all true, but they'd been much better still if there were
 more people involved.  If you think about everybody that uses racket
 having a (prominent) one-click access to the content, you get orders
 of magnitude more eyes, and this can lead much better to a
 self-organizing wikipedia-like effect.
 
 -- 
  ((lambda (x) (x x)) (lambda (x) (x x)))  Eli Barzilay:
http://barzilay.org/   Maze is Life!
 _
  For list-related administrative tasks:
  http://lists.racket-lang.org/listinfo/dev

_
  For list-related administrative tasks:
  http://lists.racket-lang.org/listinfo/dev