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 to represent this document fragment is reminiscent of LaTeX, but using @ instead of \:
@(require scribble/manual) |
|
@section{Welcome to PLT Scheme} |
|
Depending on how you look at it, @bold{PLT Scheme} |
is |
|
@itemize[ |
descendant of Scheme, which is a dialect |
of Lisp;} |
|
– variants of Scheme, and more; or} |
|
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 read 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!.