3Scribbling 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.

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.

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 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 (circle10), 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:

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.

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:

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.