Scribble: Closing the Book on Ad Hoc Documentation Tools Matthew Flatt Eli Barzilay Robert Bruce Findler University of Utah and PLT Northeastern University and PLT Northwestern University and PLT mfl
[email protected] [email protected] [email protected] Abstract Scribble is a system for writing library documentation, user guides, and tutorials. It builds on PLT Scheme’s technology for language extension, and at its heart is a new approach to connecting prose references with library bindings. Besides the base system, we have built Scribble libraries for JavaDoc-style API documentation, liter- ate programming, and conference papers. We have used Scribble to produce thousands of pages of documentation for PLT Scheme; the new documentation is more complete, more accessible, and bet- ter organized, thanks in large part to Scribble’s flexibility and the ease with which we cross-reference information across levels. This paper reports on the use of Scribble and on its design as both an extension and an extensible part of PLT Scheme. Categories and Subject Descriptors I.7.2 [Document and Text Processing]: Document Preparation—Languages and systems General Terms Design, Documentation, Languages 1. Documentation as Code Most existing documentation tools fall into one of three categories: LATEX-like tools that know nothing about source code; JavaDoc- like tools that extract documentation from annotations in source code; and WEB-like literate-programming tools where source code is organized around a prose presentation. Scribble is a new documentation infrastructure for PLT Scheme Figure 1: DrScheme with binding arrows and documentation links that can support and integrate all three kinds of tools.