#lang scribble/doc @(require "common.ss" (for-label scheme/help)) @title{Additional Related Work} In the introduction, we relate Scribble to existing documentation tools as represented by @|latex|, Skribe@~cite["Skribe"], JavaDoc, WEB@~cite["litprog"], and @tt{noweb}@~cite["noweb"], and as implemented in tools too numerous to list here. @citet["progdoc"] provide a more complete overview of existing systems and adds @tt{Prog}@italic{Doc}, which is similar to @tt{noweb} in the way that it uses a pipeline of tools. Scribble builds on many ideas from these predecessors, but fits them into an extensible framework backed by an expressive programming language. Scribble also builds on a long line of work in Lisp-style language extensibility, including traditional Lisp macros, lexically scoped macros in Scheme@~cite["syntax-case"], and readtable-based syntactic extension as in Common Lisp@~cite["CLTL2"]. Many systems follow the Lisp tradition of @defterm{docstrings}, in which documentation is associated to run-time values and used for online help. Python supports docstrings, and its @tt{doctest} module even extracts and executes examples as tests, analogous to Scribble's @scheme[examples] form. Scribble supports a docstring-like connection between run-time bindings and documentation, but using lexical-binding information instead of the value associated with a binding. For example, @scheme[(help cons)] in MzScheme's read-eval-print loop opens documentation for @scheme[cons] based on its binding as imported from @scheme[scheme/base], and not based on the procedure obtained by evaluating @scheme[cons]. Smalltalk programming environments have always encouraged programmers to use the source (with its comments) as documentation, and environments like Eclispe and Visual Studio now make code navigation similarly convenient for other languages. Such tools do not supplant the need for external documentation, however, such as guides and tutorials. In terms of surface syntax, many documentation systems build on either S-expressions or its (garish, nouveau riche) cousin XML as a way to encode both document structure and program structure. Such representations are especially appropriate for an intermediate representation of documentation, as in DocBook@~cite["docbook"]. S-expression encodings of documentation are especially common in Lisp projects, where data an code is mingled easily. Aside from Scribble's @lit["@"] notation, little attention has been devoted to designing a surface syntax with the economy of S-expressions for both code and text. Skribe is a notable exception; it uses square brackets to quote strings, and within square brackets, a comma followed by an open parenthesis escapes back into Scheme. Scribble's @lit["@"] notation is more complex than Scribe's notation, which implies a steeper learning curve. The learning overhead is compensated by the succinctness of the notation and its consistently across text and expression modes.