#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"]} @no-indent The @tt{>} represents the Scheme prompt. The first @scheme[5] is a constant value in an expression, so it is colored green in the tutorial, 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 useful hints 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 shows a more interesting evaluation: @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]. 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, much like automatic hyperlinking in wikis. 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 Alternatively, 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.}]) }| @no-indent With @scheme[provide/doc], the single contract specification for @scheme[circle] is used in two ways: at run time to check arguments and results for @scheme[circle], and when building the documentation to show the expected arguments and results of @scheme[circle]. 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"].