#lang scribble/doc @(require "common.ss") @title{Scribbling Prose} The beginning of the PLT Scheme overview documentation demonstrates several common typesetting forms: @snested{ @fake-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 Scribble syntax for generating this document fragment is reminiscent of @|latex|, using @lit["@"] (like texinfo) instead of @lit["\\"]: @; @code-block|{ #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 @code-elem{#lang scribble/doc} line declares that the module uses Scribble's documentation syntax, as opposed to using @code-elem{#lang scheme} for S-expression syntax. At the same time, the @hash-lang[] line also imports all of the usual PLT Scheme functions and syntax. The @scr:code-elem|{@(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 @scheme[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 @lit["@"] 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 @tt{---} to an em-dash and @tt{``...''} to curly quotes. Although @|latex| and Scribble use a similar syntax, the semantics are completely different. For example, @scheme[itemize] is a function that accepts document fragments created by the @scheme[item] function, instead of a text-parsing macro like @|latex|'s @tt{itemize} environment. The square brackets after @scheme[itemize] in the document source reflect that it accepts @scheme[item] values, whereas @scheme[item] and many other functions are followed by curly braces that indicate text arguments. The @lit["@"]-notation is simply another way of writing S-expressions, as we describe in detail in @Secref["at-sign"].