#lang scribble/doc
@(require "common.ss"
          (for-label scheme/help))

@title{Related Work}

As noted in the introduction, most existing documentation tools fall
into one of three categories: @|latex|-like tools, JavaDoc-like tools,
and WEB-like tools.

The @|latex| category includes general word-processing tools like
Microsoft Word, but @|latex| offers the crucial advantage of
programmability, where macros enable automatic formatting of API
details. Systems like Skribe@~cite[Skribe] improve @|latex| by
offering a sane programming language. Even in a programmable
documentation language, however, a lack of connection to source code
means that information is duplicated in documentation and source, and
binding and evaluation rules inherent to the source language are not
automatically reflected in documentation and in examples related to
those bindings.

The JavaDoc category includes perldoc for Perl, RDoc for Ruby,
Haddock@~cite[Haddock] for Haskell, OCamlDoc@~cite[OCAML],
Doxygen@~cite[Doxygen] for various languages (including Java, C++, C#,
and Fortran), and many others. Such tools improve on the @|latex| category, in that
they provide a closer connection to the programs that they
document. In particular, they are specifically designed for library
API documentation, where they shine in automatic extraction of API
details from the source code. These tools are not
suitable for other kinds of stand-alone documents, such as overview
documents, tutorials, and papers (like this one), where prose and
document structuring are more central than API details.

Literate programming tools such as WEB@~cite[litprog] and
@tt{noweb}@~cite[noweb] are designed for documenting the
implementation of a library as much as the API that a library
exports. In a sense, these tools are an extreme version of the JavaDoc
category, where the information communicated to a reader is drawn from
both the prose and the executable source. In doing so, unfortunately,
the tools typically revert to a textual slice-and-dice of the program
and prose sources, instead of a programmable layer that spans the two
halves.

@citet[progdoc] provide a more complete overview of existing systems
and add @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.

Skribe (categorized above in the @|latex| group) is by far the system
most closely related to Scribble.  Like Scribble, Skribe builds on
Scheme to construct representations of documents using Scheme
functions and macros, and it uses an extension of Scheme syntax to make
it more suitable for working with literal text. (Skribe uses square
brackets to quote strings, and within square brackets, a comma
followed by an open parenthesis escapes back into Scheme.) Skribe's
format-independent document structure and its use of passes to render
a document influenced the design of Scribble. Skribe, however,
lacks an integration with lexical binding and the module system that
is the heart of Scribble. For example, a @scheme[scheme] form that
typesets and links and identifier in a lexically sensitive way is not
possible to implement in Skribe without building a PLT Scheme-style
module and macro layer on top of Skribe.

Scribble 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. Phase-sensitive binding
through @scheme[for-label] is specific to PLT Scheme, as is the
disciplined approach to reader extension embodied by
@hash-lang[].

The @|slatex|@~cite[Sitaram-slatex] system provides automatic
formatting of Scheme code within a @|latex| document. To identify
syntactic forms and constants, @|slatex| relies on @tt{defkeyword} and
@tt{defconstant} declarations. In this mode, the author of a work in
progress must constantly add another ``standard'' binding to
@|slatex|'s list; @|slatex|'s built-in table of syntactic forms is
small compared to the number of syntactic forms available in PLT
Scheme. More generally, the problem is the usual one for
``standards'': there are many to choose from. Scribble solves this
problem with @scheme[for-label] imports and by directly using the
namespace-management functionality of PLT Scheme modules.

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 PLT Scheme'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@~cite[smalltalk-history] have always encouraged programmers
to use the source (with its comments) as documentation, and
environments like Eclipse 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-expression notation (or its 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 and code are mingled
easily.