Scribble is the language the Racket documentation is written in, and a general tool for documents and for text generation. A Scribble file (.scrbl) is mostly ordinary text with Racket code inside it, marked by @. The text is read into strings and function calls, and the program that results builds the document, which can be rendered as HTML, LaTeX, PDF, Markdown, plain text, or Typst. This page describes the file syntax and the languages; it is the reader's @ notation of scribble/reader.
The #lang line
A Scribble document starts #lang scribble/manual (documentation of Racket libraries), #lang scribble/base (general documents), #lang scribble/text (text generation and preprocessing), #lang scribble/doc (the older form that the Racket documentation itself uses) or one of the others in the table. In these languages the body is read in text mode: everything is text except @ forms. A Scribble document module exports one value, doc, the document, and the tools render it.
| Language | For |
|---|---|
scribble/base | the basic document language: title, section, subsection, itemlist, item, bold, italic, tt, verbatim, image, hyperlink, table-of-contents, index, author, and so on |
scribble/manual | everything in scribble/base plus the forms for Racket documentation: typesetting code, defining functions and syntax, cross references; it also selects the Racket manual style |
scribble/text | a text-generation or preprocessor language: all text is read as strings and written out, with Racket functions and expressions available through @ |
scribble/doc, scribble/lp2 | the older documentation language; literate programming, where a document holds code chunks that are assembled into a program |
scribble/sigplan and other style languages | styles for conference and journal papers; scribble/sigplan is one that the manual names |
at-exp language | not a document language: #lang at-exp racket turns on the @ notation in an ordinary S-expression language |
The @ notation
An @-form has this shape, where all three parts after the @ are optional (but at least one must be present) and no space is allowed between them:
@ cmd [ datum … ] { text-body … }
It is read as the S-expression (cmd datum … parsed-body …). The command is usually an identifier; the datum part holds arguments, including keyword arguments; the text body is turned into strings (one for each line, with the newlines as separate strings) and the forms nested in it.
| Written | Read as |
|---|---|
@foo{blah blah} | (foo "blah blah") |
@foo[1 2]{3 4} | (foo 1 2 "3 4") |
@foo[1 2 3 4] | (foo 1 2 3 4) – the datum part alone is an ordinary call |
@foo[#:width 2]{blah} | (foo #:width 2 "blah") |
@foo{a @bar{b} c} | (foo "a " (bar "b") " c") – forms nest inside text |
@foo | foo – a lone command is the expression itself, an escape in text |
@{blah blah} | ("blah blah") – no command: a list of the body |
@(+ 1 2), @"string", @(lambda (x) x){blah} | the command may be any Racket expression (one that does not start with [, { or |); an escaped string is merged with the surrounding text |
@|id|, @|1 (+ 2 3) 4| | a Racket expression between bars, used where an identifier would touch the following text: foo@|bar|.; bars may hold several expressions, and the result is never merged with the text around it |
@'foo{x}, @`,@foo{x}, @#'foo{x} | quote marks between the @ and the command wrap the whole form |
@; to the end of the line | a comment: the text to the end of the line and the spaces or tabs that follow it, as the % of TeX |
@;{ … } | a block comment; the braces must balance, and the comment may hold @ forms |
@"@" | a literal @ |
The body
In a body, only two things are special: @ (a nested form) and } (the end). A { is allowed and makes the matching } part of the text, so balanced braces need no escape. Spaces at the start and end of lines are dropped, indentation is removed relative to the first line, and a body of one line keeps its inner spaces. A space is not allowed before a [ or {, or it starts the text.
Alternative bodies
To write text that holds many @ or }, begin the body with |{ and end it with }|; a nested form then begins |@. Punctuation may be added between the | and the { (|--{ … }--|, |<<{ … }>>|); the closing marker has the characters in reverse order, with (, [ and < turned to their mates, and nested forms begin with | followed by the same characters and @. This works like a here string.
#lang scribble/manual
@(require (for-label racket/base racket/list))
@title{Guide to Lists}
@author{Ada Lovelace}
@section[#:tag "basics"]{The basics}
A list is made with @racket[list]. For example,
@racketblock[(map add1 (list 1 2 3))]
gives @racket['(2 3 4)]; see @secref["basics"] and @racketmodname[racket/list].
@itemlist[
@item{@bold{Build} with @racket[cons].}
@item{@italic{Take apart} with @racket[first] and @racket[rest].}
]
@defproc[(count-up [n exact-nonnegative-integer?]) (listof exact-nonnegative-integer?)]{
Returns the numbers from 0 up to @racket[n], not including it.
}
@; this line is not in the output
@verbatim|{email@example.org |@racket[(f)] }|Forms used in documents
| Group | Forms |
|---|---|
| Structure | title (with #:tag, #:style, #:version), section, subsection, subsubsection, subsubsub*section, author, table-of-contents, local-table-of-contents, include-section, bibliography, index-section |
| Text | bold, italic, emph, tt, elem, subscript, superscript, smaller, larger, nonbreaking, hspace, linebreak, verbatim, centered, nested, margin-note, item, itemlist, tabular, image, hyperlink, url, index, cite, footnote |
| Code | racket (inline), racketblock and racketblock0 (a block, quoted so that identifiers link to their documentation), racketmod (a block that starts with a module language), codeblock and code (verbatim, coloured as Racket is), racketresult, racketinput, racketoutput, racketid, litchar, filepath, exec, commandline, envvar; the older scheme… names are aliases; examples (scribble/example) runs code in an evaluator and shows the results |
| Definitions | defproc, defproc*, defform, defform*, defform/subs, defform/none, defidform, defthing, defstruct, defparam, defboolparam, defclass, definterface, defmixin, defmethod, defsignature, deftogether, defmodule, defmodulelang, defmodulereader, declare-exporting, defsubform, specsubform, racketgrammar |
| References | secref, seclink, tech (links to a deftech definition), techlink, racketmodname, racketlink, other-manual, history, deprecated |
Identifiers in @racket[…] become links to their documentation if the module that provides them is imported for-label: (require (for-label racket/list)). A Scribble document therefore requires the libraries it documents, but only for their names.
Rendering and tools
scribble (also raco scribble) renders a document. The format flags are --html (one page), --htmls (several pages in a folder), --html-tree n, --latex, --pdf (through pdflatex), --xelatex, --lualatex, --dvipdf, --text, --markdown, and --typst and --typst-pdf, the last two added in the Scribble version 1.66. raco setup builds the documents that a package lists in its info.rkt field scribblings. A document's style can be adjusted by #:style properties for HTML, LaTeX and Typst, and a file given with --style. The command takes a source file by name, or a module path with --lib.
How the viewer reads Scribble
In a .scrbl file, or any file whose first line names a scribble/… language, the viewer reads the text as plain (uncoloured) text. Each @ and its command are coloured (the @ and the brackets as directives, the command as a function or keyword), the datum part in [ ] as Racket code, and nested bodies are read the same way. @; comments are comments. In #lang at-exp files, @ forms in the code are read the same way. Text in a body is not coloured, whatever it says.
Not described
Known, not yet covered
- Reference: the syntax of
@is described from the reader chapter of the Scribble manual (read up to the body and expression-escape sections); its sections on newlines and indentation, on how the reader can be configured (make-at-readtable,use-at-readtable) and on the internals of the reader were not read. The forms table lists names from the manual's list of definitions (most of the structure and text forms, and the languagesscribble/base,scribble/docandscribble/lp2, are named from memory: onlyscribble/manual,scribble/textandscribble/basicwere downloaded), and their arguments are not given. The Scribble document model (scribble/corestructures such aspart,paragraph,elementand their style properties), the HTML, LaTeX and Typst renderers, bibliographies and theexamplesevaluators are not described. - Viewer: the text of a Scribble document is not coloured, so headings and emphasis are not shown;
@|…|escapes with several expressions are coloured as a single variable name; an@in the middle of an e-mail address is read as a form, as Scribble reads it.
See also
- The #lang family –
at-expand the other reader languages - Packages and raco –
raco scribbleandscribblings - Lexical structure – the reader that Scribble extends