[racket] Learning Scribble

On Nov 23, 2013, at 10:45 AM, Laurent wrote:

> On Sat, Nov 23, 2013 at 4:04 PM, Greg Hendershott <greghendershott at gmail.com> wrote: 
> 
> Let me see if I can find time to review the current docs for Planet
> and the new package system, and see where more examples/tips -- or at
> least links to examples -- could go, and submit a PR.
> 
> 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.


That is correct. 

I used scribble this past semester for Labs, which grad and undergrad students drafted. When people are given templates, getting them to work is possible. But, one step off the beaten path takes people by surprise. 

If anyone has time to draft such a document, I'd be happy to play editor. 

-- Matthias


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.racket-lang.org/users/archive/attachments/20131123/6aee53c4/attachment.html>