[racket-dev] scribble/srcdoc

From: Matthew Flatt (mflatt at cs.utah.edu)
Date: Sat May 12 03:47:11 EDT 2012

If you use `scribble/srcdoc', please check that the latest version
still works on your code.

I've changed the implementation to use submodules. In the old
implementation, `require/doc' and `provide/doc' expanded to
syntax-quoted constants that the compiler would drop when creating
bytecode (so that there would be no documentation overhead for a
module), and so `include-extracted' would use `expand' on the module
source to find the information. Submodules solve the problem of having
extra information in a module that is not loaded with the module's
code, so the `expand' approach is not longer necessary.

Instead of `require/doc', you can use the new `for-doc' sub-form within
`require'. Instead of `provide/doc', just use `provide'; `proc-doc',
etc., are all `provide' sub-forms.

The new forms are different in many subtle ways. Mostly, the new
implementation should work in corners where the old implementation
wouldn't.

There is at least one pattern, however, that no longer works by
default. Suppose that modules `a' and `b' refer to each other in
documentation. That is, `a' contains `(require (for-doc (for-label
a)))' and `b' contains `(require (for-doc (for-label b)))'. With the
old implementation, `for-doc' requires (via `require/doc') were
effectively copied to the module that uses `include-extracted'; with
the new implementation, `for-doc' requires turn into `require's within
a submodule, so that cycle would not be allowed. To get delayed
`require's more like the old implementation, use the
`generate-delayed-documents' declaration (which is still not
implemented with expand', but instead with relatively simple macro
juggling).


Posted on the dev mailing list.