► |  | Scribble: The Racket Documentation Tool

1 | Getting Started
2 | @ Syntax
3 | High-Level Scribble API
4 | Scribbling Documentation
5 | Literate Programming
6 | Text Generation
7 | Low-Level Scribble API
8 | Running scribble
| Index

▼ | 3 | High-Level Scribble API

3.1 | Base Document Format
3.2 | Racket Manual Format
3.3 | Book Format
3.4 | Report Format
3.5 | SIGPLAN Paper Format
3.6 | JFP Paper Format
3.7 | LNCS Paper Format

► | 3.1 | Base Document Format

3.1.1 | Document Structure
3.1.2 | Blocks
3.1.3 | Text Styles and Content
3.1.4 | Spacing
3.1.5 | Links
3.1.6 | Indexing
3.1.7 | Tables of Contents
3.1.8 | Tags

On this page:

3.1.1`` Document Structure
title
section
subsection
subsubsection
subsubsub*section
include-section
author
author+ email
3.1.2`` Blocks
para
nested
centered
margin-note
margin-note*
itemlist
items/ c
item
item?
tabular
verbatim
3.1.3`` Text Styles and Content
elem
italic
bold
tt
subscript
superscript
smaller
larger
emph
literal
image
3.1.4`` Spacing
linebreak
nonbreaking
hspace
~
-~-
?-
._
._ _
3.1.5`` Links
hyperlink
url
secref
Secref
seclink
other-doc
elemtag
elemref
3.1.6`` Indexing
index
index*
as-index
section-index
index-section
3.1.7`` Tables of Contents
table-of-contents
local-table-of-contents
3.1.8`` Tags

top ← prev up next →

#### 3.1`` Base Document Format

#lang scribble/base | package: scribble-lib

The scribble/base language provides functions and forms that can be used from code written either in Racket or with @ expressions. It essentially extends racket/base, except that top-level forms within a module using the scribble/base language are treated as document content (like scribble/doclang).
The scribble/base name can also be used as a library with require, in which case it provides only the bindings defined in this section, and it also does not set the reader or set the default rendering format to the Racket manual format.

Functions provided by this library, such as title and italic, might be called from Racket as

> (title #:tag "how-to"
> "How to Design " (italic "Great") " Programs")

They can also be called with @ notation as

@title[#:tag "how-to"]{How to Design @italic{Great} Programs}

Although the procedures are mostly designed to be used from @ mode, they are easier to document in Racket mode (partly because we have scribble/manual).

##### 3.1.1`` Document Structure

> > procedure
> > (title | [ | #:tag tag |  |  |  |
> > |  | #:tag-prefix tag-prefix |  |  |  |
> > |  | #:style style |  |  |  |
> > |  | #:version vers |  |  |  |
> > |  | #:date date] |  |  |  |
> > |  | pre-content ...+) |  | → |  | title-decl?
> tag : (or/c #f string? (listof string?)) = #f
> tag-prefix : (or/c #f string? module-path?) = #f
> style : (or/c style? #f string? symbol? (listof symbol?)) = #f
> vers : (or/c string? #f) = #f
> date : (or/c string? #f) = #f
> pre-content : pre-content?

Generates a title-decl to be picked up by decode or decode-part. The decoded pre-content (i.e., parsed with decode-content) supplies the title content. If tag is #f, a tag string is generated automatically from the content. The tag string is combined with the symbol 'part to form the full tag.

The style argument can be a style structure, or it can be one of the following: a #f that corresponds to a “plain” style, a string that is used as a style name, a symbol that is used as a style property, or a list of symbols to be used as style properties. For information on styles, see part. For example, a style of 'toc causes sub-sections to be generated as separate pages in multi-page HTML output.

The tag-prefix argument is propagated to the generated structure (see Tags). If tag-prefix is a module path, it is converted to a string using module-path-prefix->string.

The vers argument is propagated to the title-decl structure. Use "" as vers to suppress version rendering in the output.

The date argument is propagated to the title-decl structure via a document-date style property. Use "" as date to suppress date rendering in Latex output.

The section title is automatically indexed by decode-part. For the index key, leading whitespace and a leading “A”, “An”, or “The” (followed by more whitespace) is removed.

> > procedure
> > (section | [ | #:tag tag |  |  |  |
> > |  | #:tag-prefix tag-prefix |  |  |  |
> > |  | #:style style] |  |  |  |
> > |  | pre-content ...+) |  | → |  | part-start?
> tag : (or/c #f string? (listof string?)) = #f
> tag-prefix : (or/c #f string? module-path?) = #f
> style : (or/c style? #f string? symbol? (listof symbol?)) = #f
> pre-content : pre-content?

Like title, but generates a part-start of depth 0 to be by decode or decode-part.

> > procedure
> > (subsection | [ | #:tag tag |  |  |  |
> > |  | #:tag-prefix tag-prefix |  |  |  |
> > |  | #:style style] |  |  |  |
> > |  | pre-content ...+) |  | → |  | part-start?
> tag : (or/c #f string? (listof string?)) = #f
> tag-prefix : (or/c #f string? module-path?) = #f
> style : (or/c style? #f string? symbol? (listof symbol?)) = #f
> pre-content : pre-content?

Like section, but generates a part-start of depth 1.

> > procedure
> > (subsubsection | [ | #:tag tag |  |  |  |
> > |  | #:tag-prefix tag-prefix |  |  |  |
> > |  | #:style style] |  |  |  |
> > |  | pre-content ...+) |  | → |  | part-start?
> tag : (or/c #f string? (listof string?)) = #f
> tag-prefix : (or/c #f string? module-path?) = #f
> style : (or/c style? #f string? symbol? (listof symbol?)) = #f
> pre-content : pre-content?

Like section, but generates a part-start of depth 2.

> > procedure
> > (subsubsub*section | [ | #:tag tag |  |  |  |
> > |  | #:tag-prefix tag-prefix |  |  |  |
> > |  | #:style style] |  |  |  |
> > |  | pre-content ...+) |  | → |  | paragraph?
> tag : (or/c #f string? (listof string?)) = #f
> tag-prefix : (or/c #f string? module-path?) = #f
> style : (or/c style? #f string? symbol? (listof symbol?)) = #f
> pre-content : pre-content?

Similar to section, but merely generates a paragraph that looks like an unnumbered section heading (for when the nesting gets too deep to include in a table of contents).

> syntax (include-section module-path)

Requires module-path and returns its doc export (without making any imports visible to the enclosing context). Since this form expands to require, it must be used in a module or top-level context.

> procedure (author auth ...) → block?
> auth : content?

Generates a paragraph with style name 'author to show the author(s) of a document, where each author is represented by content. Normally, this function is used after title for the beginning of a document. See also author+email.

> > procedure
> > (author+email |  | author-name |  |  |  |
> > |  | email |  |  |  |
> > | [ | #:obfuscate? obfuscate?]) |  | → |  | element?
> author-name : content?
> email : string?
> obfuscate? : any/c = #f

Combines an author name with an e-mail address. If obfuscate? is true, then the result obscures the e-mail address slightly to avoid address-harvesting robots.

Note that author+email is not a replacement for author. The author+email function is often used in combination with author.

##### 3.1.2`` Blocks

> procedure (para [#:style style] pre-content ...) → paragraph?
> style : (or/c style? string? symbol? #f) = #f
> pre-content : pre-content?

Creates a paragraph containing the decoded pre-content (i.e., parsed with decode-paragraph).

The style argument can be a style, #f to indicate a “plain” style, a string that is used as a style name, or a symbol that is used as a style name. (Note that section and para treat symbols differently as style arguments.)

> procedure (nested [#:style style] pre-flow ...) → nested-flow?
> style : (or/c style? string? symbol? #f) = #f
> pre-flow : pre-flow?

Creates a nested flow containing the decoded pre-flow (i.e., parsed with decode-flow).

The style argument is handled the same as para. The 'inset and 'code-inset styles cause the nested flow to be inset compared to surrounding text, with the latter particularly intended for insetting code.

> procedure (centered pre-flow ...) → nested-flow?
> pre-flow : pre-flow?

Produces a nested flow whose content is centered.

> procedure (margin-note pre-flow ... [#:left? left?]) → block?
> pre-flow : pre-flow?
> left? : any/c = #f

Produces a nested flow that is typeset in the margin, instead of inlined.

If left? is true, then the note is shown on the opposite as it would normally be shown (which is the left-hand side for HTML output). Beware of colliding with output for a table of contents.

> procedure (margin-note* pre-content ... [#:left? left?]) → element?
> pre-content : pre-content?
> left? : any/c = #f

Produces an element that is typeset in the margin, instead of inlined. Unlike margin-note, margin-note* can be used in the middle of a paragraph; at the same time, its content is constrained to form a single paragraph in the margin.

> procedure (itemlist itm ... [#:style style]) → itemization?
> itm : items/c
> style : (or/c style? string? symbol? #f) = #f

Constructs an itemization given a sequence of items. Typical each itm is constructed by item, but an itm can be a block that is coerced to an item. Finally, itm can be a list or splice whose elements are spliced (recursively, if necessary) into the itemlist sequence.

The style argument is handled the same as para. The 'ordered style numbers items, instead of just using a bullet.

> value items/c : flat-contract?

A contract that is equivalent to the following recursive specification:

> (or/c item? block? (listof items/c) (spliceof items/c))

> procedure (item pre-flow ...) → item?
> pre-flow : pre-flow?

Creates an item for use with itemlist. The decoded pre-flow (i.e., parsed with decode-flow) is the item content.

> procedure (item? v) → boolean?
> v : any/c

Returns #t if v is an item produced by item, #f otherwise.

> procedure (tabular cells [#:style style #:sep sep]) → table?
> cells : (listof (listof (or/c block? content? 'cont)))
> style : (or/c style? string? symbol? #f) = #f
> sep : (or/c block? content? #f) = #f

Creates a table with the given content, which is supplies as a list of rows, where each row has a list of cells. The length of all rows must match.

If sep is not #f, it is inserted between every column in the table. Otherwise, the default style places no space between table columns.

Use 'cont as a cell to continue the content of the preceding cell in a row in the space that would otherwise be used for a new cell. A 'cont must not appear as the first cell in a row.

The style argument is handled the same as para.

Examples:

> @tabular[#:sep @hspace[1]
> (list (list "soup" "gazpacho")
> (list "soup" "tonjiru"))]
> @tabular[#:style 'boxed
> (list (list @bold{recipe} @bold{vegetable})
> (list "caldo verde" "kale")
> (list "kinpira gobō" "burdock")
> (list "makizushi" 'cont))]

> Renders like:

> > > soup |  | gazpacho
> > > soup |  | tonjiru

> > > recipe | vegetable
> > > caldo verde | kale
> > > kinpira gobō | burdock
> > > makizushi

> procedure (verbatim [#:indent indent] elem ...+) → block?
> indent : exact-nonnegative-integer? = 0
> elem : content?

Typesets string elems in typewriter font with linebreaks specified by newline characters in string elems. Consecutive spaces in the string elems are converted to hspace to ensure that they are all preserved in the output. Additional space (via hspace) as specified by indent is added to the beginning of each line. A non-string elem is treated as content within a single line.

The string elems are not decoded with decode-content, so (verbatim "---") renders with three hyphens instead of an em dash. Beware, however, that reading @verbatim converts @ syntax within the argument, and such reading occurs well before arguments to verbatim are delivered at run-time. To disable simple @ notation within the verbatim argument, verbatim is typically used with |{...}| or similar brackets, like this:

@verbatim|{
Use @bold{---} like this...
}|

which renders as

Use @bold{---} like this...

while

@verbatim|{
Use |@bold{---} like this...
}|

renders as

Use — like this...

Even with brackets like |{...}|, beware that consistent leading whitespace is removed by the parser; see Alternative Body Syntax for more information.

See also literal.

##### 3.1.3`` Text Styles and Content

> procedure (elem pre-content ... [#:style style]) → element?
> pre-content : pre-content?
> style : (or/c style? string? symbol? #f) = #f

Wraps the decoded pre-content as an element with style style.

> procedure (italic pre-content ...) → element?
> pre-content : pre-content?

Like elem, but with style 'italic.

> procedure (bold pre-content ...) → element?
> pre-content : pre-content?

Like elem, but with style 'bold.

> procedure (tt pre-content ...) → element?
> pre-content : pre-content?

Like elem, but with style 'tt.

> procedure (subscript pre-content ...) → element?
> pre-content : pre-content?

Like elem, but with style 'subscript.

> procedure (superscript pre-content ...) → element?
> pre-content : pre-content?

Like elem, but with style 'superscript.

> procedure (smaller pre-content ...) → element?
> pre-content : pre-content?

Like elem, but with style 'smaller. When uses of smaller are nested, text gets progressively smaller.

> procedure (larger pre-content ...) → element?
> pre-content : pre-content?

Like elem, but with style 'larger. When uses of larger are nested, text gets progressively larger.

> procedure (emph pre-content ...) → element?
> pre-content : pre-content?

The same as italic.

> procedure (literal str ...+) → element?
> str : string?

Produces an element containing literally strs with no decoding via decode-content.

Beware that @ for a literal call performs some processing before delivering arguments to literal. The literal form can be used with |{...}| or similar brackets to disable @ notation within the literal argument, like this:

@literal|{@bold{---}}|

which renders as

@literal|{@bold{---}}|

See also verbatim.

> > procedure
> > (image |  | path |  |  |  |
> > | [ | #:scale scale |  |  |  |
> > |  | #:suffixes suffixes] |  |  |  |
> > |  | pre-content ...) |  | → |  | element?
> path : (or/c path-string? (cons/c 'collects (listof bytes?)))
> scale : real? = 1.0
> suffixes : (listof #rx"^[.]") = null
> pre-content : pre-content?

Creates an image element from the given path. The decoded pre-content serves as the alternate text for contexts where the image cannot be displayed.

If path is a relative path, it is relative to the current directory, which is set by raco setup and scribble to the directory of the main document file. Instead of a path or string, the path argument can be a result of path->main-collects-relative.

The strings in suffixes are filtered to those supported by given renderer, and then the acceptable suffixes are tried in order. The HTML renderer supports ".png", ".gif", and ".svg", while the Latex renderer supports ".png", ".pdf", and ".ps" (but ".ps" works only when converting Latex output to DVI, and ".png" and ".pdf" work only for converting Latex output to PDF).

Note that when the suffixes library is non-empty, then the path argument should not have a suffix.

##### 3.1.4`` Spacing

> procedure (linebreak) → element?

Produces an element that forces a line break.

> procedure (nonbreaking pre-content ...) → element?
> pre-content : pre-content?

Like elem, but line breaks are suppressed while rendering the content.

> procedure (hspace n) → element?
> n : exact-nonnegative-integer?

Produces an element containing n spaces and style 'hspace.

> value ~ : string?

A string containing the non-breaking space character, which is equivalent to 'nbsp as an element.

> value -~- : string?

A string containing the non-breaking hyphen character.

> value ?- : string?

A string containing the soft-hyphen character (i.e., a suggestion of where to hyphenate a word to break it across lines when rendering).

> value ._ : element?

Generates a period that ends an abbreviation in the middle of a sentence, as opposed to a period that ends a sentence (since the latter may be typeset with extra space). Use @._ in a document instead of just . for an abbreviation-ending period that is preceded by a lowercase letter and followed by a space.

See .__ for an example.

> value .__ : element?

Generates a period that ends a sentence (which may be typeset with extra space), as opposed to a period that ends an abbreviation in the middle of a sentence. Use @.__ in a document instead of just . for a sentence-ending period that is preceded by an uppercase letter.

The following example illustrates both ._ and .__:

> #lang scribble/base
> My name is Mr@._ T@.__ I pity the fool who can't typeset punctuation.

##### 3.1.5`` Links

> > procedure
> > (hyperlink |  | url |  |  |  |
> > |  | pre-content ... |  |  |  |
> > | [ | #:underline? underline? |  |  |  |
> > |  | #:style style]) |  | → |  | element?
> url : string?
> pre-content : pre-content?
> underline? : any/c = #t
> | style |  | : |  | (or/c style? string? symbol? #f)
> |  |  | = |  | (if underline? #f "plainlink")

The decoded pre-content is hyperlinked to url. If style is not supplied, then underline? determines how the link is rendered.

> procedure (url dest) → element?
> dest : string?

Generates a literal hyperlinked URL.

> > procedure
> > (secref |  | tag |  |  |  |
> > | [ | #:doc module-path |  |  |  |
> > |  | #:tag-prefixes prefixes |  |  |  |
> > |  | #:underline? underline?]) |  | → |  | element?
> tag : string?
> module-path : (or/c module-path? #f) = #f
> prefixes : (or/c (listof string?) #f) = #f
> underline? : any/c = #t

Inserts a reference to the section tagged tag.

If #:doc module-path is provided, the tag refers to a tag with a prefix determined by module-path. When setup-plt renders documentation, it automatically adds a tag prefix to the document based on the source module. Thus, for example, to refer to a section of the Racket reference, module-path would be '(lib "scribblings/reference/reference.scrbl").

The #:tag-prefixes prefixes argument similarly supports selecting a particular section as determined by a path of tag prefixes. When a #:doc argument is provided, then prefixes should trace a path of tag-prefixed subsections to reach the tag section. When #:doc is not provided, the prefixes path is relative to any enclosing section (i.e., the youngest ancestor that produces a match).

For HTML output, the generated reference is the hyperlinked title of the elements in the section’s title content, except that elements with the 'aux style property are omitted in the hyperlink label. If underline? is #f, then the hyperlink is rendered in HTML without an underline.

For Latex output, the generated reference’s format depends on the document style. By default, only the section number is shown in the reference, but the scribble/manual style shows the title after the section number. Customize the output (see Extending and Configuring Scribble Output) by redefining the \BookRef, etc., macros (see Predefined Latex Macros).

> > procedure
> > (Secref |  | tag |  |  |  |
> > | [ | #:doc module-path |  |  |  |
> > |  | #:tag-prefixes prefixes |  |  |  |
> > |  | #:underline? underline?]) |  | → |  | element?
> tag : string?
> module-path : (or/c module-path? #f) = #f
> prefixes : (or/c (listof string?) #f) = #f
> underline? : any/c = #t

Like secref, but if the rendered form of the reference starts with a word (e.g., “section”), then the word is capitalized.

> > procedure
> > (seclink |  | tag |  |  |  |
> > | [ | #:doc module-path |  |  |  |
> > |  | #:tag-prefixes prefixes |  |  |  |
> > |  | #:underline? underline? |  |  |  |
> > |  | #:indirect? indirect?] |  |  |  |
> > |  | pre-content ...) |  | → |  | element?
> tag : string?
> module-path : (or/c module-path? #f) = #f
> prefixes : (or/c (listof string?) #f) = #f
> underline? : any/c = #t
> indirect? : any/c = #f
> pre-content : pre-content?

Like secref, but the link label is the decoded pre-content instead of the target section’s name.

In addition to secref’s arguments, seclink supports a indirect? argument. When indirect? is true, then the section hyperlink’s resolution in HTML is potentially delayed; see 'indirect-link for link-element.

> > procedure
> > (other-doc |  | module-path |  |  |  |
> > | [ | #:underline? underline? |  |  |  |
> > |  | #:indirect indirect]) |  | → |  | element?
> module-path : module-path?
> underline? : any/c = #t
> indirect : (or/c #f content?) = #f

Like secref for the document’s implicit "top" tag. Use this function to refer to a whole manual instead of secref, in case a special style in the future is used for manual titles.

If indirect is not #f, then the link’s resolution in HTML can be delayed, like seclink with #:indirect? #t. The indirect content is prefixed with “the” and suffixed with “documentation” to generate the rendered text of the link.

> procedure (elemtag t pre-content ...) → element?
> t : (or/c tag? string?)
> pre-content : pre-content?

The tag t refers to the content form of pre-content.

> > procedure
> > (elemref |  | t |  |  |  |
> > |  | pre-content ... |  |  |  |
> > | [ | #:underline? underline?]) |  | → |  | element?
> t : (or/c tag? string?)
> pre-content : pre-content?
> underline? : any/c = #t

The decoded pre-content is hyperlinked to t, which is normally defined using elemtag.

##### 3.1.6`` Indexing

> procedure (index words pre-content ...) → index-element?
> words : (or/c string? (listof string?))
> pre-content : pre-content?

Creates an index element given a plain-text string—or list of strings for a hierarchy, such as '("strings" "plain") for a “plain” entry below a more general “strings” entry. As index keys, the strings are “cleaned” using clean-up-index-strings. The strings (without clean-up) also serve as the text to render in the index. The decoded pre-content is the text to appear inline as the index target.

Use index when an index entry should point to a specific word or phrase within the typeset document (i.e., the pre-content). Use section-index, instead, to create an index entry that leads to a section, instead of a specific word or phrase within the section.

> procedure (index* words word-contents pre-content ...) → index-element?
> words : (listof string?)
> word-contents : (listof list?)
> pre-content : pre-content?

Like index, except that words must be a list, and the list of contents render in the index (in parallel to words) is supplied as word-contents.

> procedure (as-index pre-content ...) → index-element?
> pre-content : pre-content?

Like index, but the word to index is determined by applying content->string on the decoded pre-content.

> procedure (section-index word ...) → part-index-decl?
> word : string?

Creates a part-index-decl to be associated with the enclosing section by decode. The words serve as both the keys and as the rendered forms of the keys within the index.

> procedure (index-section [#:tag tag]) → part?
> tag : (or/c #f string?) = "doc-index"

Produces a part that shows the index the enclosing document. The optional tag argument is used as the index section’s tag.

##### 3.1.7`` Tables of Contents

> procedure (table-of-contents) → delayed-block?

Returns a delayed flow element that expands to a table of contents for the enclosing section. For Latex output, however, the table of contents currently spans the entire enclosing document.

> procedure (local-table-of-contents [#:style style]) → delayed-block?
> style : (or/c symbol? #f) = #f

Returns a delayed flow element that may expand to a table of contents for the enclosing section, depending on the output type. For multi-page HTML output, the flow element is a table of contents; for Latex output, the flow element is empty.

The meaning of the style argument depends on the output type, but 'immediate-only normally creates a table of contents that contains only immediate sub-sections of the enclosing section. See also the 'quiet style of part (i.e., in a part structure, not supplied as the style argument to local-table-of-contents), which normally suppresses sub-part entries in a table of contents.

##### 3.1.8`` Tags

The exports of scribble/tag are all re-exported by scribble/base.

top ← prev up next →