3 Scribbling Code
The PLT Scheme tutorial “Quick: An Introduction to PLT Scheme with Pictures” starts with a few paragraphs of prose and then shows the following example interaction:
> 5 5
> "art gallery" "art gallery"
The > represents the Scheme prompt. The first 5 is a constant value in an expression, so it is colored green, while the second 5 is a result, so it is colored blue. In Scheme, the syntax for output does not always match the syntax for expressions, so the different colors are a useful hint to readers – but only if they have the consistency of an automatic annotation.
The source code for the first example is simply
@interaction[5 "art gallery"] |
where interaction is provided by a Scribble library to both evaluate examples and typeset the expressions and results with syntax coloring. Since example expressions are evaluated when the document is built, examples never contain bugs where evaluation does not match the predicted output.
The second example in the “Quick” tutorial is as follows:
> (circle 10)
Here, again, the expression is colored in the normal way for PLT Scheme code. More importantly, the circle identifier is hyperlinked to the definition of the circle function in the slideshow library, so an interested reader can follow the link to learn more about circle at any time. Meanwhile, the result is shown as a circle image, just as it would be shown when evaluating the expression in DrScheme.
The source code for the second example is equally simple:
@mr-interaction[(circle 10)] |
The author of the tutorial had to implement the mr-interaction syntactic form, because interaction does not currently support picture results. The syntax coloring, hyperlinking, and evaluation of (circle 10), however, is implemented by expanding to interaction. In particular, circle is correctly hyperlinked because the module containing the above source also includes
which causes the circle binding to be imported from the slideshow module for the purposes of hyperlinking. Based on this import and a database mapping bindings to definition sites, Scribble can automatically insert the hyperlink.
A module that is imported only with for-label is not run when the documentation is built, because the time at which a document is built may not be a suitable time to actually run a module. As an extreme example, an author might want to document a module whose job is to erase all files on the disk. More practically, executing a GUI library might require a graphics terminal, while the documentation for the graphics library can be built using only a text terminal.
Pervasive and precise hyperlinking of identifiers greatly improves the quality of documentation, and it relieves a document author from much tedious cross-referencing work. The author need not specify where circle is documented, but instead merely import for-label a module that supplies circle, and the documentation system is responsible for correlating the use and the definition. Furthermore, since hyperlinks are used in examples everywhere, an author can expect readers to follow them, instead of explicitly writing “for more information on the circle procedure used above, see ...” These benefits are crucial when a system’s documentation runs to thousands of pages. Indeed, PLT Scheme’s documentation has 57,997 links between manuals, which is roughly 15 links per printed page (and which does not count the additional 105,344 intra-manual links).
Clicking the circle hyperlink leads to its documentation in a standard format:
(circle diameter) → pict? diameter : real? Creates an unfilled ellipse.
In this definition, real? and pict? are contracts for the function argument and result. Naturally, they are in turn hyperlinked to their definitions, because suitable libraries are imported for-label in the documentation source.
The above documentation of circle is implemented using defproc:
Creates an unfilled ellipse. |
} |
Alternately, instead of writing the documentation for circle in a stand-alone document – where there is a possibility that the documented contract does not match the contract in the implementation – the documentation could be written with the implementation of circle. In that case, the documentation would look slightly different, since it would be part of the module’s export declarations:
@{Creates an unfilled ellipse.}]) |
Although defproc and provide/doc are provided with Scribble, they are not built into the core typesetting engine. They are written in separate libraries, and Scribble users could have implemented these forms. We describe this approach to extending Scribble further in Scribble’s Extensibility.