#lang scribble/doc @(require "common.ss" scribble/core scheme/list scheme/string scribble/bnf) @(begin (define (blit s) (schemeparenfont s)) (define (scr-code . stuff) (scr:code-elem (string-append* (map (lambda (x) (if (equal? x "\n") " " x)) stuff)))) (define at @lit["@"]) (define op @nonterm{op}) (define text (make-splice @list{@blit["{"]...@blit["}"]})) (define braces @elem{@blit["{"]@nonterm{text}@blit["}"]}) (define brackets @elem{@blit["["]@kleenestar[@nonterm{S-expr}]@blit["]"]}) (define (underline e) (make-element "underline" (list e))) (define (xoptional e) (make-element #f (list (underline e) (subscript "?")))) ) @title[#:tag "at-sign"]{@|at|s and @lit{[]}s and @lit{{}}s, Oh My!} Users of a text-markup language experience first and foremost the language's concrete syntax. The same is true of any language, but in the case of text, authors with different backgrounds have arrived at a remarkably consistent view of the appropriate syntax: it should use blank lines to indicate paragraph breaks, double-quote characters should not be special, and so on. At the same time, a programmable mark-up language needs a natural escape to the programming layer and back. From the perspective of a programming language, conventional notations for string literals are terrible for writing text. The quoting rules tend to be complex, and they usually omit an escape for arbitrarily nested expressions. ``Here strings'' and string interpolation can alleviate some of the quoting and escape problems, but they are insufficient for writing large amounts of text with frequent nested escapes to the programming language. More importantly, building text in terms of string escapes and operations like @scheme[string-append] distracts from the business of writing prose, which is about @emph{text and markup} rather than @emph{strings and function calls}. Indeed, many documentation systems, like JavaDoc, avoid the limitations of string literals in the language by defining a completely new syntax that is embedded within comments. Of course, this approach sacrifices any connection between the text and the programming language. For Scribble, our solution is the @|at|-notation, which is a text-friendly alternative to traditional S-expression syntax. More precisely, the @|at|-notation is another way to write down arbitrary S-expressions, but it is tuned for writing blocks of free-form text. The @|at|-expression notation is a strict extension of PLT Scheme's S-expression syntax; the @|at| character has no special meaning in Scheme strings, in comments, or in the middle of Scheme identifiers. Furthermore, since it builds on the existing S-expression parser, it inherits all of the existing source-location support (e.g., for error messages). @section{@|at|-expressions as S-expressions} The grammar of an @|at|-expression is roughly as follows (where @lit["@"], @blit["["], @blit["]"], @blit["{"], and @blit["}"] are literal, and @xoptional[@italic{x}] means that @italic{x} is optional): @; @(make-nested-flow (make-style "BNF" null) (list @BNF[ (list @nonterm{at-expr} @elem{@lit["@"]@xoptional[@nonterm{op}]@xoptional[@|brackets|]@xoptional[@|braces|]}) (list @nonterm{op} @elem{@nonterm{S-expr} that does not start with @blit["["] or @blit["{"]}) (list @nonterm{S-expr} @elem{any PLT Scheme S-expression}) (list @nonterm{text} @elem{text with balanced @blit["{"]...@blit["}"] and with @lit["@"]-exprs}) ])) @; An @|at|-expression maps to an S-expression as follows: @itemize[ @item{An @lit["@"]@nonterm{op}@blit["{"]...@blit["}"] sequence combines @nonterm{op} with text-mode arguments. For example, @; @scr:code-block|{@emph{Yes!}}| @; is equivalent to the S-expression @; @code-block|{(emph "Yes!")}| @; Also, since @|at| keeps its meaning inside text-mode arguments, @; @scr:code-block["@section{Country @emph{and} Western}"] @; is equivalent to the S-expression @; @code-block|{(section "Country " (emph "and") " Western")}|} @item{An @lit["@"]@nonterm{op}@blit["["]...@blit["]"] sequence combines @nonterm{op} with S-expression arguments. For example, @; @scr:code-block|{@itemize[(item "a") (item "b")]}| @; is equivalent to the S-expression @; @code-block{(itemize (item "a") (item "b"))}} @item{An @lit["@"]@nonterm{op}@blit["["]...@blit["]"]@blit["{"]...@blit["}"] sequence combines S-expression arguments and text-mode arguments. For example, @; @scr:code-block|{@title[#:style 'toc]{Contracts}}| @; is equivalent to the S-expression @; @code-block|{(title #:style 'toc "Contracts")}| @; where @scheme[#:style] uses PLT Scheme notation for a keyword.} @item{An @lit["@"]@nonterm{op} sequence without an immediately following @blit["{"] or @blit["["] is equivalent to just @nonterm{op} in Scheme mode. For example, @; @scr:code-block|{@username}| @; is equivalent to the S-expression @; @code-block{username} @; so that @; @scr:code-block|{@emph{committed by @username}}| @; is equivalent to @; @code-block{(emph "committed by " username)}} @item{An @nonterm{op} can be omitted in any of the above forms. For example, @; @scr:code-block|{@{Country @emph{and} Western}}| @; is equivalent to the S-expression @; @code-block{("Country " (emph "and") " Western")} @; which is useful in some quoted or macro contexts.} ] Another way to describe the @|at|-expression syntax is simply @lit["@"]@nonterm{op}@blit["["]...@blit["]"]@blit["{"]...@blit["}"] where each of the three parts is optional. When @nonterm{op} is included but both kinds of arguments are missing, then @nonterm{op} can produce a value to use directly instead of a function to call. The @nonterm{op} in an @|at|-expression is not constrained to be an identifier; it can be any S-expression that does not start with @blit["{"] or @blit["["]. For example, an argumentless @scr:code-elem|{@(require scribble/manual)}| is equivalent to the S-expression @code-elem|{(require scribble/manual)}|. The spectrum of @|at|-expression forms enables a document author to use whichever variant is most convenient. For a given operation, however, one particular variant is typically used. In general, @lit["@"]@nonterm{op}@blit["{"]...@blit["}"] or @lit["@"]@nonterm{op}@blit["["]...@blit["]"] is used to imply a typesetting operation, whereas @lit["@"]@nonterm{op} more directly implies an escape to Scheme. Hence, the form @scr:code-elem|{@emph{Yes!}}| is preferred to the equivalent @scr:code-elem|{@(emph "Yes!")}|, while @scr:code-elem|{@(require scribble/manual)}| is preferred to the equivalent @scr:code-elem|{@require[scribble/manual]}|. A combination of S-expression and text-mode arguments is often useful to ``customize'' an operation that consumes text. The @scr-code|{@title[#:style 'toc]{Contracts}}| example illustrates this combination, where the optional @scheme['toc] style customizes the typeset result of the @scheme[title] function. In other cases, an operation that specifically leverages S-expression notation may also have a text component. For example, @; @scr:code-block|{ @defproc[(circle [diameter real?]) pict?]{ Creates an unfilled ellipse. } }| @; is equivalent to @; @code-block|{ (defproc (circle [diameter real?]) pict? "Creates an unfilled ellipse.") }| @; but as the description of the procedure becomes more involved, using text mode for the description becomes much more convenient. An @|at| works both as an escape from text mode and as a form constructor in S-expression contexts. As a result, @|at|-forms keep their meaning whether they are used in a Scheme expression or in a Scribble text part. This equivalence significantly reduces the need for explicit quoting and unquoting operations, and it helps avoid bugs due to incorrect quoting levels. For example, instead of @scr:code-elem|{@itemize[(item "a") (item "b")]}|, an itemization is normally written @scr:code-elem|{@itemize[@item{a} @item{b}]}|, since items for an itemization are better written in text mode than as conventional strings; in this case, @scr-code|{@item{a}}| can be used directly without first switching back to text mode. Overall, @|at|-expressions are crucial to Scribble's flexibility in the same way that S-expressions are crucial to Scheme's flexibility---and, in the same way, the benefit is difficult to quantify. Furthermore, just as S-expressions can be used for more than writing Scheme programs, the @|at| notation can be used for purposes other than documentation, and the @|at|-notation parser is available for use in PLT Scheme separate from the rest of the Scribble infrastructure. We use it as an alternative to HTML for building the @show-link{plt-scheme.org} web pages, more generally in a template system supported by the PLT Scheme web server, and also as a text preprocessor language similar in spirit to @exec{m4} for generating plain-text files. @section{Documentation-Specific Decoding} The @lit["@"] notation supports local text transformations and mark-up, but it does not directly address some other problems specific to organizing a document's source: @; @itemize[ @item{Section content should be grouped implicitly via @scheme[section], @scheme[subsection], etc. declarations, instead of explicitly nesting section constructions.} @item{Paragraph breaks should be determined by empty lines in the source text, instead of explicitly constructing paragraph values.} @item{A handful of ASCII character sequences should be converted automatically to more sophisticated typesetting elements, such as converting @lit["``"] and @lit["''"] to curly quotes or @lit["---"] to an em-dash.} ] These transformations are specific to typesetting, and they are not appropriate for other contexts where the @lit["@"] notation is useful. Therefore, the @lit["@"] parser in Scribble faithfully preserves the original text in Scheme strings, and a separate @defterm{decode} layer in Scribble provides additional transformations. Functions like @scheme[bold] and @scheme[emph] apply @scheme[decode-content] to their arguments to perform ASCII transformations, and @scheme[item] calls @scheme[decode-flow] to transform ASCII sequences and form paragraphs between empty lines. In contrast, @scheme[tt] and @scheme[verbatim] do not call the decode layer, and they instead typeset text exactly as it is given. For example, the source document @; @code-block|{ #lang scribble/doc @(require scribble/manual) @title{Tubers} @section{Problem} You say ``potato.'' I say ``potato.'' @section{Solution} Call the whole thing off. }| @; invokes the decode layer, producing a module that is roughly equivalent to the following (where a @scheme[part] is a generic section): @; @code-block|{ #lang scheme/base (require scribble/core) (provide doc) (define doc (make-part (list "Tubers") (list (make-part (list "Problem") (list (make-paragraph (list "You say \u201Cpotato.\u201D")) (make-paragraph (list "I say \u201Cpotato.\u201D")))) (make-part (list "Solution") (list (make-paragraph (list "Call the whole thing off."))))))) }|