[racket] Learning Scribble

On Friday, Sam Tobin-Hochstadt wrote:
> On Fri, Nov 22, 2013 at 8:46 AM, Eli Barzilay <eli at barzilay.org> wrote:
> >
> > It's probably good to make this an important goal when learning
> > the system, even though it's a small corner of the whole thing
> > now...
> 
> I think Eli means "the documentation system" by "the whole thing",

Yes.


> but the equivalence between at-exps and s-exps is at the heart of
> why at-exps are great, and why Eli's design succeeded where many
> many other people have failed in this space.  If you're learning
> about at-exps, keeping this equivalence in mind is very useful.

Yes, that was supposed to be my point...


Two days ago, Laurent wrote:
> 
> My 2 cents: I think what is missing is a complete example as a
> tutorial, like "You've written a module? Here is what to do, step by
> step, to document it and make it a package. Here is the example
> module file, here is the corresponding scribble file (with defproc,
> defform, defstruct(*), itemlist, tabular, racket, racketblock,
> image, sections, title, emph and bold, and all most used forms), and
> here is the result on-screen."  Then people don't need initially to
> fully grok the at-exp syntax or other difficult parts, they can just
> copy/paste from the example when it's not yet clear to them.

+1; especially in a context of a programmable language where such
things often tempt you to write macros for doing things, which makes
template examples a little more rare...

-- 
          ((lambda (x) (x x)) (lambda (x) (x x)))          Eli Barzilay:
                    http://barzilay.org/                   Maze is Life!