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
3.1.4 Images
image
3.1.5 Spacing
linebreak
nonbreaking
hspace
~
-~-
?-
._
._  _
3.1.6 Links
hyperlink
url
secref
Secref
seclink
other-doc
elemtag
elemref
3.1.7 Indexing
index
index*
as-index
section-index
index-section
3.1.8 Tables of Contents
table-of-contents
local-table-of-contents
3.1.9 Tags

3.1 Base Document Format

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 picked up 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.

Examples:

@author{Alice P. Racketeer}

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.

Examples:

@author[(author+email "Bob T. Scribbler" "bob@racket-lang.org")]
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. The default style is specified by the output destination (and tends to inset text for HTML output and not inset for Latex output).

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.

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    
  #:column-properties column-properties    
  #:row-properties row-properties    
  #:cell-properties cell-properties    
  #:sep-properties sep-properties])  table?
  cells : (listof (listof (or/c block? content? 'cont)))
  style : (or/c style? string? symbol? #f) = #f
  sep : (or/c block? content? #f) = #f
  column-properties : (listof any/c) = '()
  row-properties : (listof any/c) = '()
  cell-properties : (listof (listof any/c)) = '()
  sep-properties : (or/c list? #f) = #f
Creates a table with the given cells content, which is supplied as a list of rows, where each row has a list of cells. The length of all rows must match.

Use 'cont in cells 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. See table for a list of recognized style names and style properties.

The default style places no space between table columns. If sep is not #f, it is inserted as a new column between every column in the table; the new column’s properties are the same as the preceding column’s, unless sep-properties provides a list of style properties to use. When sep would be placed before a 'cont, a 'cont is inserted, instead.

The column-properties, row-properties, and cell-properties arguments specify style properties for the columns and cells of a table; see table-columns and table-cells for a description of recognized properties. The lists do not contain entries for columns potentially introduced for sep, and when non-empty, they are extended as needed to match the table size determined by cells:

Each element of column-properties or row-properties is either a list of style property values or a non-list element that is wrapped as a list. Similarly, for each list that is an element of cell-properties, the list’s non-list elements are wrapped as nested lists.

If column-properties is non-empty, then its list of property lists is converted into a table-columns style property that is added to the style specified by styleor merged with an existing table-columns style property that matches the column shape of cells. In addition, if either row-properties or cell-properties is non-empty, the property lists of column-properties are merged with the property lists of row-properties and cell-properties. If row-properties or cell-properties is non-empty, the merged lists are converted into a table-cells style property that is added to the style specified by styleor merged with an existing table-cells style property that matches the shape of cells.

If the style lists for column-properties are both merged with cell-properties and converted to table-columns, then style will contain some redundant information. In that case, column-attributes properties will be used from table-columns, while other properties will be used from the merger into table-cells.

Changed in version 1.1 of package scribble-lib: Added the #:column-properties, #:row-properties, and #:cell-properties arguments.
Changed in version 1.12: Changed sep insertion before a 'cont.
Changed in version 1.28: Added sep-properties and made the preceding column’s properties used consistently if not specified.

Examples:
@tabular[#:sep @hspace[1]
         (list (list "soup" "gazpacho")
               (list "soup" "tonjiru"))]
 
@tabular[#:style 'boxed
         #:column-properties '(left right)
         #:row-properties '(bottom-border ())
         (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?
Similar to elem, but the 'tt style is used for immediate strings and symbols among the pre-content arguments.

To apply the 'tt style uniformly to all pre-content arguments, use (elem #:style 'tt pre-content ...), instead.

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?
Like elem, but emphasised. Typically, italics are used for emphasis. Uses of emph can be nested; typically this causes the text to alternate between italic and upright.

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

  @bold{---}

See also verbatim.

3.1.4 Images

procedure

(image path    
  [#:scale scale    
  #:suffixes suffixes    
  #:style style]    
  pre-content ...)  image-element?
  path : (or/c path-string? (cons/c 'collects (listof bytes?)))
  scale : real? = 1.0
  suffixes : (listof #rx"^[.]") = null
  style : (or/c style? string? symbol? #f) = #f
  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 to the directory of the main document file. (In general, however, it’s more reliable to express relative paths using define-runtime-path.) Instead of a path or string, the path argument can be a result of path->main-collects-relative.

The scale argument sets the images scale relative to its default size as determined by the content of path. For HTML output, the resulting image-element is rendered with an img or object (for SVG) tag, and scale adjusts the width and height attributes; a class name or other attributes in style can effectively override that size.

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 list is non-empty, then the path argument should not have a suffix.

Changed in version 1.3 of package scribble-lib: Added the #:style argument.

3.1.5 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.6 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?]    
  #:link-render-style ref-style)  element?
  tag : string?
  module-path : (or/c module-path? #f) = #f
  prefixes : (or/c (listof string?) #f) = #f
  underline? : any/c = #t
  ref-style : (or/c link-render-style? #f)
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 raco setup 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 the result link-element, if ref-style is not #f, then it is attached as a style property and affects the rendering of the link. Alternatively, an enclosing part can have a link-render style that adjusts the rendering style for all links within the part. See link-element for more information about the rendering of section references.

If underline? is #f, then a style is attached to the result link-element so that the hyperlink is rendered in HTML without an underline

In Racket documentation that is rendered to HTML, clicking on a section title normally shows the secref call that is needed to link to the section.

Changed in version 1.25 of package scribble-lib: Added the #:link-render-style argument.

procedure

(Secref tag    
  [#:doc module-path    
  #:tag-prefixes prefixes    
  #:underline? underline?]    
  #:link-render-style ref-style)  element?
  tag : string?
  module-path : (or/c module-path? #f) = #f
  prefixes : (or/c (listof string?) #f) = #f
  underline? : any/c = #t
  ref-style : (or/c link-render-style? #f)
Like secref, but if the rendered form of the reference starts with a word (e.g., “section”), then the word is capitalized.

Changed in version 1.25 of package scribble-lib: Added the #:link-render-style argument.

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. For example:

  @other-doc['(lib "parsack/parsack/parsack.scrbl")

             #:indirect "Parsec implementation in Racket"]

renders as a hyperlink with the text:

  the Parsec implementation in Racket documentation

procedure

(elemtag t pre-content ...)  element?

  t : (or/c taglet? generated-tag?)
  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 taglet? generated-tag?)
  pre-content : pre-content?
  underline? : any/c = #t
The decoded pre-content is hyperlinked to t, which is normally defined using elemtag.

3.1.7 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-string. 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.8 Tables of Contents

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.9 Tags

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