[racket] Learning Scribble

Laurent wrote at 11/23/2013 10:45 AM:
>
> 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."

It's not perfect, but McFly has some of this documentation, and some 
kinds of templates (as well as programmatically generating and updating 
"info.rkt").  McFly does a lot of the worst of Scribble for you (hidden; 
you never see the boilerplate-ish Scribble parts), but it doesn't 
document something like a Scribble cheat-sheet, which would be very useful.

(McFly does what it does because I was working on a Racket 
practitioner's book that had an emphasis on being a full participant in 
open source component ecology, easily and sustainably, as part of normal 
development process.  However, releasing packages was such a pain in the 
butt that it defeated a key part of my thesis of how this ecology would 
work.  McFly got the story on some of the pragmatics of packaging 
plausible enough that I could return to bigger-picture issues of the 
ecology.)

Neil V.