[plt-scheme] Vision behind Scribble

From: Matthew Flatt (mflatt at cs.utah.edu)
Date: Tue Mar 18 14:20:15 EDT 2008

I've put together a prototype to see how in-source documentation might
work. It's not ready for real work, but if you're curious, see


in SVN.

The "gifwrite.ss" file imports `scribble/srcdoc' to get `provide/doc'
and `require/doc':

 * The `provide/doc' form is similar to `provide/contract', except that
   only `->' contracts are supported so far, and an argument name is
   associated with each argument contract. Also, after the contract is
   content to describe the exported function.

 * The `require/doc' form is a quasi-import into a "documentation"
   phase. For example, to be able to use the `scheme' form when
   documenting a function, use `(require/doc scribble/manual)'. For
   every `require' (after expansion) of the file, there's an implicit
   `(require (for-label ...))', so many cross-references (e.g., in
   contract expressions) are automatic.

The "gifwrite.scrbl" file imports `scribble/extract', which provides
just `include-extracted' to pull documentation out of a module that
uses `scribble/srcdoc'. So "gifwrite.scrbl" contains some overview
information, but extracts the API details from "gifwrite.ss".

Unfortunately, the bytecode compiler is not quite smart enough to throw
away the documentation in the compiled form of "gifwrite.ss". (It's an
expression of the form `(void (quote-syntax ...))', which
`include-extracted' detects in the macro-expanded module.) I'll fix


Posted on the users mailing list.