[racket-dev] scribble/doclang example?

From: Danny Yoo (dyoo at hashcollision.org)
Date: Wed Dec 12 19:29:19 EST 2012

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?

Posted on the dev mailing list.