Scribble: closing the book on ad hoc documentation tools

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, literate 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 better 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.

REFERENCES

• 1: R. Kent Dybvig, Robert Hieb, and Carl Bruggeman. Syntactic Abstraction in Scheme. Lisp and Symbolic Computation 5(4), pp. 295--326, 1993.
• 2: Matthew Flatt. Compilable and Composable Macros, You Want it When? In Proc. ACM Intl. Conf. Functional Programming, pp. 72--83, 2002.
• 3: Matthew Flatt, Robert Bruce Findler, Shriram Krishnamurthi, and Matthias Felleisen. Programming Languages as Operating Systems (or Revenge of the Son of the Lisp Machine). In Proc. ACM Intl. Conf. Functional Programming, pp. 138--147, 1999.
• 4: Matthew Flatt, and PLT Scheme. Reference: PLT Scheme. PLT Scheme Inc., PLT-TR2009-reference-v4.2, 2009.
• 5: Erick Gallesio, and Manuel Serrano. Skribe: a Functional Authoring Language. J. Functional Programming 15(5), pp. 751--770, 2005.
• 6: Alan C. Kay. The early history of Smalltalk. ACM SIGPLAN Notices 28(3), 1993.
• 7: Donald E. Knuth. Literate Programming. Computer Journal 27(2), pp. 97--111, 1984.
• 8: Xavier Leroy. The Objective Caml System, release 3.10. 2007.
• 9: Simon Marlow. Haddock, a Haskell Documentation Tool. In Proc. ACM Wksp. Haskell, pp. 78--89, 2002.
• 10: Jacob Matthews. Component Deployment with PLaneT: You Want it Where? In Proc. Wksp. Scheme and Functional Programming, 2006.
• 11: Norman Ramsey. Literate Programming Simplified. IEEE Software 11(5), pp. 97--105, 1994.
• 12: Volker Simonis, and Roland Weiss. ProgDOC -- A New Program Documentation System. In Proc. Perspectives of System Informatics, Lecture Notes in Computer Science volume 2890, pp. 438--449, 2003.
• 13: Dorai Sitaram. TeX2page. 2007. http://www.ccs.neu.edu/home/dorai/tex2page/tex2page-doc.html
• 14: Dorai Sitaram. How to Use SLaTeX. 2007. http://www.ccs.neu.edu/home/dorai/slatex/.
• 15: Michael Sperber (Ed.). The Revised 6 Report on the Algorithmic Language Scheme. 2007.
• 16: Norman Walsh, and Leonard Muellner. DocBook: The Definitive Guide. O'Reilly & Associates, Inc., 2008.
• 17: Dimitri van Heesch. Doxygen Source Code Documentation Generator Tool. 2007. http://www.stack.nl/~dimitri/doxygen/

INDEX TERMS

Primary Classification:
  I. Computing Methodologies
  I.7 DOCUMENT AND TEXT PROCESSING
      I.7.2 Document Preparation
          Subjects: Languages and systems

General Terms:
Design, Documentation, Languages

Keywords:
domain-specific languages, macros, metaprogramming