[racket-dev] scribble/doclang example?

At Wed, 12 Dec 2012 18:45:10 -0700, Matthew Flatt wrote:
> It's backward-incompatible, but looking for existing uses of
> `scribble/doclang' [...]

Well, After sending my message, I remembered another place, and now I
think there may be more uses. So, I don't think a backward-incompatible
change is a good idea, after all.

I suggest that you pick a new name for the language that you'd like to
have, and fix the docs to talk about that one. Then, we can leave
`scribble/doclang' alone, documenting it as only for backward
compatibility.

> 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
> _________________________
>   Racket Developers list:
>   http://lists.racket-lang.org/dev