▼Scribble: Closing the Book on Ad Hoc Documentation Tools
  ← prev  up  next → 

2 Scribbling Prose

The beginning of the PLT Scheme overview documentation demonstrates several common typesetting forms:

1  Welcome to PLT Scheme

Depending on how you look at it, PLT Scheme is

  • a programming language – a descendant of Scheme, which is a dialect of Lisp;

  • a family of programming languages – variants of Scheme, and more; or

  • a set of tools for using a family of programming languages.

Where there is no room for confusion, we use simply “Scheme” to refer to any of these facets of PLT Scheme.

The Scribble syntax for generating this document fragment is reminiscent of LaTeX, using @ (like texinfo) instead of \:

 #lang scribble/doc

 @(require scribble/manual)

 

 @section{Welcome to PLT Scheme}

 

 Depending on how you look at it, @bold{PLT Scheme}

 is

 

 @itemize[

   @item{a @emph{programming language} – a

         descendant of Scheme, which is a dialect

         of Lisp;}

 

   @item{a @emph{family} of programming languages

          – variants of Scheme, and more; or}

 

   @item{a set of @emph{tools} for using a family

         of programming languages.}

 ]

 

 Where there is no room for confusion, we use

 simply “Scheme” to refer to any of these facets

 of PLT Scheme.

The initial #lang scribble/doc line declares that the module uses Scribble’s documentation syntax, as opposed to using #lang scheme for S-expression syntax. At the same time, the #lang line also imports all of the usual PLT Scheme functions and syntax. The @(require scribble/manual) form imports additional functions and syntactic forms specific to typesetting a user manual. The remainder of the module represents the document content. The semantics of the document body is essentially that of Scheme, where most of the text is represented as Scheme strings.

Although we build Scribble on Scheme, a LaTeX-style syntax works better than nested S-expressions, because it more closely resembles the resulting textual layout. First, although all of the text belongs in a section, it is implicitly grouped by the section title, instead of explicitly grouped into something like a section function call. Second, the default parsing mode is “text” instead of “expression,” so that commas, periods, quotes, paragraphs, and sections behave in the usual way for prose, while the @ notation provides a uniform way to escape to a Scheme function call with text-mode arguments. Third, various automatic rules convert ASCII to more sophisticated typeset forms, such as the conversion of – to an em-dash and “...” to curly quotes.

Although LaTeX and Scribble use a similar syntax, the semantics are completely different. For example, itemize is a function that accepts document fragments created by the item function, instead of a text-parsing macro like LaTeX’s itemize environment. The square brackets after itemize in the document source reflect that it accepts item values, whereas item and many other functions are followed by curly braces that indicate text arguments. The @-notation is simply another way of writing S-expressions, as we describe in detail in @s and []s and {}s, Oh My!.

  ← prev  up  next →