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 in the
tutorial, 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 useful hints
to readers – but only if they have the consistency of an automatic
annotation.
The source code for the first example is simply
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 shows a more interesting
evaluation:
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. 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:
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, much like automatic hyperlinking in wikis.
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:
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.
Alternatively, 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:
With
provide/doc, the single contract
specification for
circle is used in two ways: at run time to
check arguments and results for
circle, and when building the
documentation to show the expected arguments and results of
circle.
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.
![[image]](img0.png)