Home

Scribble: Closing the Book on Ad Hoc Documentation Tools

Scribble: Closing the Book on Ad Hoc Documentation Tools. Matthew Flatt, Eli Barzilay, and Robert Bruce Findler. ICFP '09.

Scribble is a new system for writing library documentation, user guides, and tutorials. Scribble builds on PLT Scheme’s technology for language extension, and at its heart is a new approach to connecting prose references with library bindings. We have built Scribble libraries that support standalone documentation and papers, JavaDoc-style API documentation, and literate programming. Thanks in large part to Scribble’s flexibility and the ease with which we can cross-reference information across different levels, the documentation that is distributed with PLT Scheme now runs into the thousands of pages. This paper reports on the use of Scribble and on its design as both an extension and extensible part of PLT Scheme.

This introduces a cute and well thought out syntax for writing technical prose and for escaping back into the PL for typesetting operations and cross-references to PL values. It looks reminiscent of TeX, but has a direct transformation to S-expressions. Scribble also makes great use of PLT Scheme's modular and polyglot programming facilities.

A nice twist on the classic Scheme ploy:

A documentation language should be designed not by piling escape conventions on top of a comment syntax, but by removing the weaknesses and restrictions of the programming language that make a separate documentation language appear necessary. Scribble demonstrates that a small number of rules for forming documentation, with no restrictions on how they are composed, suffice to form a practical and efficient documentation language that is flexible enough to support the major documentation paradigms in use today.

(P.S. To which I'd like to add, somewhat OT, that compared to PLT Scheme, Common Lisp is starting to look teeny.)

By Manuel J. Simoni at 2010-07-21 01:18 | DSL | other blogs | 16157 reads

Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.

Presentation Video

Coincedentally I just happened to see this presentation on Scribble on Vimeo
Scribble: Closing the Book on Ad Hoc Documentation Tools on Vimeo

I though, based on the title, that the goal was to replace documentation tools in general but it's somewhat scheme specific.
If you want to document something not written in Scheme then you need to to write some scheme for the outline in addition to the document.

By Phil Miess at Wed, 2010-07-21 10:39 | login or register to post comments

Odd, I'm not getting any

Odd, I'm not getting any sound?

By scottmcl at Wed, 2010-07-21 19:57 | login or register to post comments

Sound

The sound is working for me; maybe Flash player is having problems connecting to your audio driver. This happens somewhat regularly on my Linux system; killing and reopening my browser usually fixes it. (And then there are the usual questions like "is the volume turned on?" and "do you have headphones plugged in?")

By Matt Brubeck at Wed, 2010-07-21 20:32 | login or register to post comments

Firefox

That's a Firefox bug. Switch to Chromium.

By dmbarbour at Wed, 2010-07-21 21:09 | login or register to post comments

bugs and browsers

Well, I am a Firefox developer as my day job, so I can't stop using it completely. :) But I do use Chromium too, and have seen this in both browsers; if anything it is a linux Flash Player bug.

By Matt Brubeck at Fri, 2010-07-23 23:10 | login or register to post comments

Browser Developer, eh?

I've never seen it in Chromium. With Firefox, it happened every day, several times a day, whenever I was favoring sites such as hulu and youtube on Ubuntu.

I agree that there may be some interactions Adobe-side, but there's something more than that going on. It may be some sort of feature-interaction with multi-threading or with the sleep-mode.

This is THE reason I dropped Firefox (after trying several versions).

By dmbarbour at Fri, 2010-07-23 23:54 | login or register to post comments

Nice!

Combining code and text markup into a readable unified language is a promising direction. I've been toying with the underlying idea for about a year now, so I have some thoughts to share:

1. You really want tags like @item {text goes here} to be parameterizable by programming language expressions, e.g. so you could write something like @item(2,3) {text goes here}. But to avoid ambiguity, this means there needs to be a unique bracketing syntax distinguishing markup from e.g. a parenthesized expression.

2. Pursuing this in LISP/Scheme is almost cheating, because the trivial S-expression syntax leaves plenty of symbols available for markup use. Intermixing markup and code is more challenging in languages that leave fewer symbols available. Try it in Haskell or C#, for example.

3. I'd love to see this concept explored more thoroughly in a mainstream-style programming and markup scenario. For example, redesign the syntax of HTML + Javascript, nesting code and markup.

By Tim Sweeney at Thu, 2010-07-22 00:20 | login or register to post comments

Read On!

Scribbles syntax handles this parameterization as well. In the full generality, the {text} is optional, and also preceded by an optional [args]. @item[args]{text} is syntax for the s-expression (item args text), but args is parsed as a series of s-expressions, and text is parsed in text mode (a list of markup-free string, separated by the s-expressions translated from embedded markup).

Some ambiguity is avoided in Scribble by using a restructuring pass on the parse to move some text into it's logical parent,
so sections can be introduced by @section{title}, instead of wrapping the entire contents in @section["title"]{...}. If textual arguments are kept short like this, then it is even less objectionable to require some kind of escape or markup for unmatched close braces.

The escape syntax would probably be the easiest part to adapt for a mainstream language. The lexical hook just depends on having a character that cannot begin a valid expression. For Haskell and C++ I think @ would actually work

By Brandon Moore at Thu, 2010-07-22 08:03 | login or register to post comments

TeX Replacement

When I saw their presentation last year, I was hoping to use Scribble as a replacement for LaTeX. The main obstacle is the fuzzy division between compile-time and run-time. Here, compile time is when Scribble translate things into LaTeX, while run time is when the resulting code is being LaTeXed.

For example, you want Scribble to be able to manipulate page numbers , so they should be available at compile time, but you also want TeX to break the pages (because it's pretty good at that), so you only have them at compile time. I don't remember what Scribble's solution was, but I remember I wasn't too happy with it. Other references can be handled by Scribble at compile time.

Perhaps the solution is to have multiple runs of LaTeX, with possible divergence. Your programs are not guaranteed to stop anyway, and there are only a handful of run-time data that might not stabilise after 3-4 runs, I think.

Another, more important, is reuse of existing package, most importantly math package. You really want to typeset the math in LaTeX, but still have the power of the Scribble language. This leads to some ugly quoting and unquoting, and meticulous thinking about which part goes into compile time and which into run time in your formulae. This issue can be fixed by porting all the libraries from LaTeX to Scribble. But that's tons of work...

Hmm... This post has grown rather technical. Perhaps I should move it to the racket mailing list?

By Ohad Kammar at Thu, 2010-07-22 09:44 | login or register to post comments