#lang scribble/doc
@(require "common.ss"
          (for-label (only-in slideshow circle pict?)
                     scribblings/quick/mreval)
          scribble/eval
          scribblings/quick/mreval)

@title[#:tag "code"]{Scribbling Code}

@declare-exporting["common.ss"]

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:

@nested{@interaction[5 "art gallery"]}

The @tt{>} represents the Scheme prompt. The first @scheme[5] is a
constant value in an expression, so it is colored green, while the second
@schemeresult[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

@scr:code-block|{
 @interaction[5 "art gallery"]
}|

@no-indent where @scheme[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:

@nested{@mr-interaction[(circle 10)]}

@no-indent Here, again, the expression is colored in the normal way
for PLT Scheme code. More importantly, the @scheme[circle] identifier
is hyperlinked to the definition of the @scheme[circle] function in
the @schememodname[slideshow] library, so an interested reader can
follow the link to learn more about @scheme[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:

@scr:code-block|{
 @mr-interaction[(circle 10)]
}|

@no-indent The author of the tutorial had to implement the
@scheme[mr-interaction] syntactic form, because @scheme[interaction]
does not currently support picture results. The syntax coloring,
hyperlinking, and evaluation of @scheme[(circle 10)], however, is
implemented by expanding to @scheme[interaction]. In particular,
@scheme[circle] is correctly hyperlinked because the module containing
the above source also includes

@scr:code-block|{
 @(require (for-label slideshow))
}|

@no-indent which causes the @scheme[circle] binding to be imported
from the @schememodname[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 @scheme[for-label] is @emph{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
@scheme[circle] is documented, but instead merely import
@scheme[for-label] a module that supplies @scheme[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 @scheme[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 @scheme[circle] hyperlink leads to its documentation in a
standard format:

@nested{
 @defproc[(circle [diameter real?]) pict?]{
  Creates an unfilled ellipse.
 }
}

@no-indent In this definition, @scheme[real?] and @scheme[pict?] are
contracts for the function argument and result. Naturally, they are in
turn hyperlinked to their definitions, because suitable libraries are
imported @scheme[for-label] in the documentation source. 

The above documentation of @scheme[circle] is implemented using
@scheme[defproc]:

@scr:code-block|{
 @defproc[(circle [diameter real?]) pict?]{
  Creates an unfilled ellipse.
 }
}|

@no-indent Alternately, instead of writing the documentation for @scheme[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 @scheme[circle]. In that case, the documentation
would look slightly different, since it would be part of the module's
export declarations:

@scr:code-block|{
(provide/doc 
 [circle ([diameter real?] . -> . pict?)
         @{Creates an unfilled ellipse.}])
}|

Although @scheme[defproc] and @scheme[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 @secref["extensions"].