[racket-dev] scribble/doclang example?

Yes, I think this is a good idea.

It's backward-incompatible, but looking for existing uses of
`scribble/doclang', I find only two uses not in the distribution: your
Planet package and the ICFP paper. The current `scribble/doclang' has
already drifted from the ICFP paper, and I imagine that you're willing
to adapt your Planet package. Given the small number of uses, plus the
fact that the documentation is some combination of non-existent and
incorrect (the docs say `#lang' instead of `require' for
`scribble/doclang'), I think it's probably ok.

At Wed, 12 Dec 2012 17:29:19 -0700, Danny Yoo wrote:
> I'm reading the documentation on how scribble/doclang works,
> 
>      http://docs.racket-lang.org/scribble/doclang.html
> 
> but it doesn't say really what it needs to work.
> 
> That is, a program written in scribble/doclang must provide a few
> elements besides the chunks of document: it needs to also provide the
> name of the id it's going to bind the document to, some function to
> post-process after decoding, and some leading expressions.  I see that
> other readers such as scribble/jfp take advantage of this to do extra
> stuff.
> 
> 
> Here's a small example I've ben able to figure out:
> 
> ;;;;;;;;;;;;;;;;;;;;;;;;;;;;
> #lang racket
> (module* example scribble/doclang
>   doc
>   values
>   ()
>   (require scribble/base)
>   (provide (all-defined-out))
>   (define foo (para "hello again"))
>   "hello world, this is an example document"
>   (para "note the " (bold "structure")))
> 
> (module+ main
>   (require (submod ".." example))
>   (printf "I see doc is: ~s\n\n" doc)
>   (printf "I see foo is: ~s" foo))
> ;;;;;;;;;;;;;;;;;;;;;;;;;;;;
> 
> and I was about to add this example to the doclang documentation, but
> paused; the current interface seems awfully error-prone: it took me
> several minutes to figure out why (module example scribble/doclang
> "hello world") didn't work.
> 
> 
> Would it acceptable if I hack up the language so that it takes those
> three values as keyword arguments, and provide reasonable defaults?
> 
> 
> That is, I'd like to be able to write:
> 
> ;;;;;;;;;;;;;;;;;;;;;;;;;;;;
> (module example scribble/doclang
>   "hello world, this is an example document")
> ;;;;;;;;;;;;;;;;;;;;;;;;;;;;
> 
> and have it Just Work.
> 
> 
> If we need to override the defaults, we should be able to provide them
> as keywords at the beginning of the module:
> 
> ;;;;;;;;;;;;;;;;;;;;;;;;;;;;
> (module example scribble/doclang
>   #:id doc
>   #:post-process values
>   #:exprs ()
> 
>   "hello world, this is an example document")
> ;;;;;;;;;;;;;;;;;;;;;;;;;;;;
> 
> 
> Does that seem reasonable?
> _________________________
>   Racket Developers list:
>   http://lists.racket-lang.org/dev