On this page:
7.3.1 Parts
7.3.2 Tags
7.3.3 Styles
7.3.4 Collected and Resolved Information
7.3.5 Structure Reference
part
paragraph
table
itemization
nested-flow
compound-paragraph
traverse-block
delayed-block
element
image-element
target-element
toc-target-element
page-target-element
redirect-target-element
toc-element
link-element
index-element
multiarg-element
traverse-element
delayed-element
part-relative-element
collect-element
render-element
collected-info
target-url
document-version
color-property
background-color-property
table-cells
table-columns
block?
content?
style
plain
element-style?
tag?
generated-tag
content->string
content-width
block-width
collect-info
resolve-info
info-key?
collect-put!
resolve-get
resolve-get/ ext?
resolve-search
resolve-get/ tentative
resolve-get-keys
part-collected-info
tag-key
traverse-block-block
traverse-element-content
block-traverse-procedure/ c
element-traverse-procedure/ c
7.3.6 HTML Style Properties
attributes
url-anchor
hover-property
script-property
css-addition
body-id
html-defaults
7.3.7 Latex Style Properties
tex-addition
latex-defaults
latex-auto-extra-files

7.3 Structures And Processing

 (require scribble/core)

A document is represented as a part, as described in Parts. This representation is intended to be independent of its eventual rendering, and it is intended to be immutable; rendering extensions and specific data in a document can collude arbitrarily, however.

A document is processed in four passes:

None of the passes mutate the document representation. Instead, the traverse pass, collect pass, and resolve pass accumulate information in a side hash table, collect-info table, and resolve-info table. The collect pass and resolve pass are effectively specialized version of traverse pass that work across separately built documents.

7.3.1 Parts

A part is an instance of part; among other things, it has a title content, an initial flow, and a list of subsection parts. There is no difference between a part and a full document; a particular source module just as easily defines a subsection (incorporated via include-section) as a document.

A flow is a list of blocks.

A block is either a table, an itemization, a nested flow, a paragraph, a compound paragraph, a traverse block, or a delayed block.

7.3.2 Tags

A tag is a list containing a symbol and either a string, a generated-tag instance, or an arbitrary list. The symbol effectively identifies the type of the tag, such as 'part for a tag that links to a part, or 'def for a Racket function definition. The symbol also effectively determines the interpretation of the second half of the tag.

A part can have a tag prefix, which is effectively added onto the second item within each tag whose first item is 'part or 'tech. The prefix is added to a string value by creating a list containing the prefix and string, and it is added to a list value using cons; a prefix is not added to a generated-tag instance. The prefix is used for reference outside the part, including the use of tags in the part’s tags field. Typically, a document’s main part has a tag prefix that applies to the whole document; references to sections and defined terms within the document from other documents must include the prefix, while references within the same document omit the prefix. Part prefixes can be used within a document as well, to help disambiguate references within the document.

Some procedures accept a “tag” that is just the string part of the full tag, where the symbol part is supplied automatically. For example, section and secref both accept a string “tag”, where 'part is implicit.

7.3.3 Styles

A style combines a style name with a list of style properties in a style structure. A style name is either a string, symbol, of #f. A style property can be anything, including a symbol a structure such as color-property.

A style has a single style name, because the name typically corresponds to a configurable instruction to a renderer. For example, with Latex output, a string style name corresponds to a Latex command or environment. For more information on how string style names interact with configuration of a renderer, see Extending and Configuring Scribble Output. Symbolic style names, meanwhile, provide a simple layer of abstraction between the renderer and documents for widely supported style; for example, the 'italic style name is supported by all renderers.

Style properties within a style compose with style names and other properties. Again, symbols are often used for properties that are directly supported by renderers. For example, 'unnumbered style property for a part renders the part without a section number. Many properties are renderer-specific, such as a hover-property structure that associates text with an element to be shown in an HTML display when the mouse hovers over the text.

7.3.4 Collected and Resolved Information

The collect pass, resolve pass, and render pass processing steps all produce information that is specific to a rendering mode. Concretely, the operations are all represented as methods on a render% object.

The result of the collect method is a collect-info instance. This result is provided back as an argument to the resolve method, which produces a resolve-info value that encapsulates the results from both iterations. The resolve-info value is provided back to the resolve method for final rendering.

Optionally, before the resolve method is called, serialized information from other documents can be folded into the collect-info instance via the deserialize-info method. Other methods provide serialized information out of the collected and resolved records.

During the collect pass, the procedure associated with a collect-element instance can register information with collect-put!.

During the resolve pass, collected information for a part can be extracted with part-collected-info, which includes a part’s number and its parent part (or #f). More generally, the resolve-get method looks up information previously collected. This resolve-time information is normally obtained by the procedure associated with a delayed block or delayed element.

The resolve-get information accepts both a part and a resolve-info argument. The part argument enables searching for information in each enclosing part before sibling parts.

7.3.5 Structure Reference

(struct part (tag-prefix
    tags
    title-content
    style
    to-collect
    blocks
    parts)
  #:extra-constructor-name make-part)
  tag-prefix : (or/c false/c string?)
  tags : (listof tag?)
  title-content : (or/c false/c list?)
  style : style?
  to-collect : list?
  blocks : (listof block?)
  parts : (listof part?)
The tag-prefix field determines the optional tag prefix for the part.

The tags indicates a list of tags that each link to the section.

The title-content field holds the part’s title, if any.

For the style field, the currently recognized symbolic style names are as follows:

The recognized style properties are as follows:

The to-collect field contains content that is inspected during the collect pass, but ignored in later passes (i.e., it doesn’t directly contribute to the output).

The blocks field contains the part’s initial flow (before sub-parts).

The parts field contains sub-parts.

(struct paragraph (style content)
  #:extra-constructor-name make-paragraph)
  style : style?
  content : content?
A paragraph has a style and a content.

For the style field, a string style name corresponds to a CSS class for HTML output or a macro for Latex output (see Implementing Styles). The following symbolic style names are recognized:

The currently recognized style properties are as follows:

(struct table (style blockss)
  #:extra-constructor-name make-table)
  style : style?
  blockss : (listof (listof (or/c block? (one-of/c 'cont))))
A table has, roughly, a list of list of blocks. A cell in the table can span multiple columns by using 'cont instead of a block in the following columns (i.e., for all but the first in a set of cells that contain a single block).

Within style, a string style name corresponds to a CSS class for HTML output or an environment for Latex output (see Implementing Styles). The following symbolic style names are also recognized:

The following style properties are currently recognized:

For Latex output, a paragraph as a cell value is not automatically line-wrapped, unless a vertical alignment is specified for the cell through a table-cells or table-columns style property. To get a line-wrapped paragraph, use a compound-paragraph or use an element with a string style and define a corresponding Latex macro in terms of parbox. For Latex output of blocks in the flow that are nested-flows, itemizations, compound-paragraphs, or delayed-blocks, the block is wrapped with minipage using linewidth divided by the column count as the width.

(struct itemization (style blockss)
  #:extra-constructor-name make-itemization)
  style : style?
  blockss : (listof (listof block?))
A itemization has a style and a list of flows.

In style, a string style name corresponds to a CSS class for HTML output or a macro for Latex output (see Implementing Styles). In addition, the following symbolic style names are recognized:

The following style properties are currently recognized:

(struct nested-flow (style blocks)
  #:extra-constructor-name make-nested-flow)
  style : any/c
  blocks : (listof block?)
A nested flow has a style and a flow.

In style, the style name is normally a string that corresponds to a CSS class for HTML <blockquote> output or a Latex environment (see Implementing Styles). The following symbolic style names are recognized:

The following style properties are currently recognized:

(struct compound-paragraph (style blocks)
  #:extra-constructor-name make-compound-paragraph)
  style : style?
  blocks : (listof block?)
A compound paragraph has a style and a list of blocks.

For HTML, a paragraph block in blocks is rendered without a <p> tag, unless the paragraph has a style with a non-#f style name. For Latex, each block in blocks is rendered with a preceding \noindent, unless the block has the 'never-indents property (checking recursively in a nested-flow or compound-paragraph if the nested-flow or compound-paragraph itself has no 'never-indents property).

The style field of a compound paragraph is normally a string that corresponds to a CSS class for HTML output or Latex environment for Latex output (see Implementing Styles). The following style properties are currently recognized:

(struct traverse-block (traverse)
  #:extra-constructor-name make-traverse-block)
  traverse : block-traverse-procedure/c
Produces another block during the traverse pass, eventually. The traverse procedure is called with procedures to get and set symbol-keyed information, and it should return either a block (which effectively takes the traverse-block’s place) or a procedure like traverse to be called in the next iteration of the traverse pass.

All traverse-element and traverse-blocks that have not been replaced are forced in document order relative to each other during an iteration of the traverse pass.

(struct delayed-block (resolve)
  #:extra-constructor-name make-delayed-block)
  resolve : (any/c part? resolve-info? . -> . block?)
The resolve procedure is called during the resolve pass to obtain a normal block. The first argument to resolve is the renderer.

(struct element (style content)
  #:extra-constructor-name make-element)
  style : element-style?
  content : content?
Styled content within an enclosing paragraph or other content.

The style field can be a style structure, but it can also be just a style name.

In style, a string style name corresponds to a CSS class for HTML output and a macro name for Latex output (see Implementing Styles). The following symbolic style names are recognized:

The following style properties are currently recognized:

(struct image-element element (path suffixes scale)
  #:extra-constructor-name make-image-element)
  path : 
(or/c path-string?
      (cons/c 'collects (listof bytes?)))
  suffixes : (listof #rx"^[.]")
  scale : real?
Used as a style for an element to inline an image. The path field can be a result of path->main-collects-relative.

For each string in suffixes, if the rendered works with the corresponding suffix, the suffix is added to path and used if the resulting path refers to a file that exists. The order in suffixes determines the order in which suffixes are tried. The HTML renderer supports ".png", ".gif", and ".svg", while the Latex renderer supports ".png", ".pdf", and ".ps" (but rendering Latex output to PDF will not work with ".ps" files, while rendering to Latex DVI output works only with ".ps" files). If suffixes is empty or if none of the suffixes lead to files that exist, path is used as-is.

The scale field scales the image in its rendered form.

(struct target-element element (tag)
  #:extra-constructor-name make-target-element)
  tag : tag?
Declares the content as a hyperlink target for tag.

Like target-element, the content is also a kind of section label to be shown in the “on this page” table for HTML output.

Like target-element, but a link to the element goes to the top of the containing page.

(struct redirect-target-element target-element (alt-path
    alt-anchor)
  #:extra-constructor-name make-redirect-target-element)
  alt-path : path-string?
  alt-anchor : string?
Like target-element, but a link to the element is redirected to the given URL.

(struct toc-element element (toc-content)
  #:extra-constructor-name make-toc-element)
  toc-content : content?
Similar to toc-target-element, but with specific content for the “on this page” table specified in the toc-content field.

(struct link-element element (tag)
  #:extra-constructor-name make-link-element)
  tag : tag?
Hyperlinks the content to tag.

When tag is a part tag and the content of the element is null, then the hyperlink uses the target part’s number and/or title as the content. In that case, if the section number is preceded by a word, the word starts in uppercase if the element’s style includes a 'uppercase property.

(struct index-element element (tag plain-seq entry-seq desc)
  #:extra-constructor-name make-index-element)
  tag : tag?
  plain-seq : (and/c pair? (listof string?))
  entry-seq : (listof content?)
  desc : any/c
The plain-seq specifies the keys for sorting, where the first string is the main key, the second is a sub-key, etc. For example, an “night” portion of an index might have sub-entries for “night, things that go bump in” and “night, defender of the”. The former would be represented by plain-seq '("night" "things that go bump in"), and the latter by '("night" "defender of the"). Naturally, single-string plain-seq lists are the common case, and at least one word is required, but there is no limit to the word-list length. The strings in plain-seq must not contain a newline character.

The entry-seq list must have the same length as plain-seq. It provides the form of each key to render in the final document.

The desc field provides additional information about the index entry as supplied by the entry creator. For example, a reference to a procedure binding can be recognized when desc is an instance of procedure-index-desc. See scribble/manual-struct for other typical types of desc values.

See also index.

(struct multiarg-element (style content)
  #:extra-constructor-name make-multiarg-element)
  style : element-style?
  content : (listof content?)
Like element with a list for content, except that for Latex output, if the style name in style is a string, then it corresponds to a Latex command that accepts as many arguments (each in curly braces) as elements of content.

(struct traverse-element (traverse)
  #:extra-constructor-name make-traverse-element)
  traverse : element-traverse-procedure/c
Like traverse-block, but the traverse procedure must eventually produce content, rather than a block.

(struct delayed-element (resolve sizer plain)
  #:extra-constructor-name make-delayed-element)
  resolve : (any/c part? resolve-info? . -> . list?)
  sizer : (-> any/c)
  plain : (-> any/c)
The render procedure’s arguments are the same as for delayed-block, but the result is content. Unlike delayed-block, the result of the render procedure’s argument is remembered on the first call for re-use for a particular resolve pass.

The sizer field is a procedure that produces a substitute content for the delayed element for the purposes of determining the delayed element’s width (see element-width).

The plain field is a procedure that produces a substitute content when needed before the collect pass, such as when element->string is used before the collect pass.

(struct part-relative-element (resolve sizer plain)
  #:extra-constructor-name make-part-relative-element)
  resolve : (collect-info? . -> . list?)
  sizer : (-> any/c)
  plain : (-> any/c)
Similar to delayed-block, but the replacement content is obtained in the collect pass by calling the function in the resolve field.

The resolve function can call collect-info-parents to obtain a list of parts that enclose the element, starting with the nearest enclosing section. Functions like part-collected-info and collected-info-number can extract information like the part number.

(struct collect-element element (collect)
  #:extra-constructor-name make-collect-element)
  collect : (collect-info . -> . any)
Like element, but the collect procedure is called during the collect pass. The collect procedure normally calls collect-put!.

Unlike delayed-element or part-relative-element, the element remains intact (i.e., it is not replaced) by either the collect pass or resolve pass.

(struct render-element element (render)
  #:extra-constructor-name make-render-element)
  render : (any/c part? resolve-info? . -> . any)
Like delayed-element, but the render procedure is called during the render pass.

If a render-element instance is serialized (such as when saving collected info), it is reduced to a element instance.

(struct collected-info (number parent info)
  #:extra-constructor-name make-collected-info)
  number : (listof (or/c false/c integer?))
  parent : (or/c false/c part?)
  info : any/c
Computed for each part by the collect pass.

(struct target-url (addr)
  #:extra-constructor-name make-target-url)
  addr : path-string?
Used as a style property for an element. A path is allowed for addr, but a string is interpreted as a URL rather than a file path.

(struct document-version (text)
  #:extra-constructor-name make-document-version)
  text : (or/c string? false/c)
Used as a style property for a path to indicate a version number.

(struct color-property (color)
  #:extra-constructor-name make-color-property)
  color : (or/c string? (list/c byte? byte? byte?))
Used as a style property for an element to set its color. Recognized string names for color depend on the renderer, but at the recognized set includes at least "white", "black", "red", "green", "blue", "cyan", "magenta", and "yellow". When color is a list of bytes, the values are used as RGB levels.

(struct background-color-property (color)
  #:extra-constructor-name make-background-color-property)
  color : (or/c string? (list/c byte? byte? byte?))
Like color-property, but sets the background color.

(struct table-cells (styless)
  #:extra-constructor-name make-table-cells)
  styless : (listof (listof style?))
Used as a style property for a table to set its cells’ styles.

If a cell style has a string name, it is used as an HTML class for the <td> tag or as a Latex command name.

The following symbols are recognized as cell-style properties:

In addition, for HTML output, attributes structures as style properties can add arbitrary attributes to a cell’s <td> tag.

(struct table-columns (styles)
  #:extra-constructor-name make-table-columns)
  styles : (listof style?)
Like table-cells, but the styles list is duplicated for each row in the table. This style property is used only when a table-cells is not present in a style’s list of properties.

(block? v)  boolean?
  v : any/c
Returns #t if v is a paragraph, table, itemization, nested-flow, traverse-block, or delayed-block, #f otherwise.

(content? v)  boolean?
  v : any/c
Returns #t if v is a string, symbol, element, multiarg-element, traverse-element, delayed-element, part-relative-element, a convertible value in the sense of convertible?, or list of content. Otherwise, it returns #f.

(struct style (name properties)
  #:extra-constructor-name make-style)
  name : (or/c string? symbol? #f)
  properties : list?
Represents a style.

A style (make-style #f null).

(element-style? v)  boolean?
  v : any/c
Returns #t if v is a string, symbol, #f, or style structure.

(tag? v)  boolean?
  v : any/c
Returns #t if v is acceptable as a link tag, which is a list containing a symbol and either a string, a generated-tag instance, or a list (of arbitrary values).

(struct generated-tag ()
  #:extra-constructor-name make-generated-tag)
A placeholder for a tag to be generated during the collect pass. Use tag-key to convert a tag containing a generated-tag instance to one containing a string.

(content->string content)  string?
  content : content?
(content->string content renderer p info)  string?
  content : content?
  renderer : any/c
  p : part?
  info : resolve-info?
Converts content to a single string (essentially rendering the content as “plain text”).

If p and info arguments are not supplied, then a pre-“collect” substitute is obtained for delayed elements. Otherwise, the two arguments are used to force the delayed element (if it has not been forced already).

Returns the width in characters of the given content.

Returns the width in characters of the given block.

(struct collect-info (ht
    ext-ht
    parts
    tags
    gen-prefix
    relatives
    parents)
  #:extra-constructor-name make-collect-info)
  ht : any/c
  ext-ht : any/c
  parts : any/c
  tags : any/c
  gen-prefix : any/c
  relatives : any/c
  parents : (listof part?)
Encapsulates information accumulated (or being accumulated) from the collect pass. The fields are exposed, but not currently intended for external use, except that collect-info-parents is intended for external use.

(struct resolve-info (ci delays undef)
  #:extra-constructor-name make-resolve-info)
  ci : any/c
  delays : any/c
  undef : any/c
Encapsulates information accumulated (or being accumulated) from the resolve pass. The fields are exposed, but not currently intended for external use.

(info-key? v)  boolean?
  v : any/c
Returns #t if v is an info key: a list of at least two elements whose first element is a symbol. The result is #f otherwise.

For a list that is an info tag, the interpretation of the second element of the list is effectively determined by the leading symbol, which classifies the key. However, a #f value as the second element has an extra meaning: collected information mapped by such info keys is not propagated out of the part where it is collected; that is, the information is available within the part and its sub-parts, but not in ancestor or sibling parts.

Note that every tag is an info key.

(collect-put! ci key val)  void?
  ci : collect-info?
  key : info-key?
  val : any/c
Registers information in ci. This procedure should be called only during the collect pass.

(resolve-get p ri key)  any/c
  p : (or/c part? false/c)
  ri : resolve-info?
  key : info-key?
Extract information during the resolve pass or render pass for p from ri, where the information was previously registered during the collect pass. See also Collected and Resolved Information.

The result is #f if the no value for the given key is found. Furthermore, the search failure is recorded for potential consistency reporting, such as when racket setup is used to build documentation.

(resolve-get/ext? p ri key)  
any/c boolean?
  p : (or/c part? false/c)
  ri : resolve-info?
  key : info-key?
Like render-get, but returns a second value to indicate whether the resulting information originated from an external source (i.e., a different document).

(resolve-search dep-key p ri key)  void?
  dep-key : any/c
  p : (or/c part? false/c)
  ri : resolve-info?
  key : info-key?
Like resolve-get, but a shared dep-key groups multiple searches as a single request for the purposes of consistency reporting and dependency tracking. That is, a single success for the same dep-key means that all of the failed attempts for the same dep-key have been satisfied. However, for dependency checking, such as when using racket setup to re-build documentation, all attempts are recorded (in case external changes mean that an earlier attempt would succeed next time).

(resolve-get/tentative p ri key)  any/c
  p : (or/c part? false/c)
  ri : resolve-info?
  key : info-key?
Like resolve-search, but without dependency tracking. For multi-document settings where dependencies are normally tracked, such as when using racket setup to build documentation, this function is suitable for use only for information within a single document.

(resolve-get-keys p ri pred)  list?
  p : (or/c part? false/c)
  ri : resolve-info?
  pred : (info-key? . -> . any/c)
Applies pred to each key mapped for p in ri, returning a list of all keys for which pred returns a true value.

(part-collected-info p ri)  collected-info?
  p : part?
  ri : resolve-info?
Returns the information collected for p as recorded within ri.

(tag-key t ri)  tag?
  t : tag?
  ri : resolve-info?
Converts a generated-tag value with t to a string.

Produces the block that replaces b.

Produces the content that replaces e.

Defined as

  (recursive-contract
   ((symbol? any/c . -> . any/c)
    (symbol? any/c . -> . any)
    . -> . (or/c block-traverse-procedure/c
                 block?)))

Defined as

  (recursive-contract
   ((symbol? any/c . -> . any/c)
    (symbol? any/c . -> . any)
    . -> . (or/c element-traverse-procedure/c
                 content?)))

7.3.6 HTML Style Properties

The scribble/html-properties library provides datatypes used as style properties for HTML rendering.

(struct attributes (assoc)
  #:extra-constructor-name make-attributes)
  assoc : (listof (cons/c symbol? string?))
Used as a style property to add arbitrary attributes to an HTML tag.

(struct url-anchor (name)
  #:extra-constructor-name make-url-anchor)
  name : string?
Used as a style property with element to insert an anchor before the element.

(struct hover-property (text)
  #:extra-constructor-name make-hover-property)
  text : string?
Used as a style property with element to add text that is shown when the mouse hovers over the element.

(struct script-property (type script)
  #:extra-constructor-name make-script-property)
  type : string?
  script : (or/c path-string? (listof string?))
Used as a style property with element to supply a script alternative to the element content.

(struct css-addition (path)
  #:extra-constructor-name make-css-addition)
  path : 
(or/c path-string?
      (cons/c 'collects (listof bytes?)))
Used as a style property to supply a CSS file to be referenced in the generated HTML. This property can be attached to any style, and all additions are collected to the top of the generated HTML page.

The path field can be a result of path->main-collects-relative.

(struct body-id (value)
  #:extra-constructor-name make-body-id)
  value : string?
Used as a style property to associate an id attribute with an HTML tag.

(struct html-defaults (prefix style extra-files)
  #:extra-constructor-name make-html-defaults)
  prefix : 
(or/c bytes? path-string?
      (cons/c 'collects (listof bytes?)))
  style : 
(or/c bytes? path-string?
      (cons/c 'collects (listof bytes?)))
  extra-files : 
(listof (or/c path-string?
              (cons/c 'collects (listof bytes?))))
Like latex-defaults, but use for the scribble command-line tool’s --html and --htmls modes.

7.3.7 Latex Style Properties

The scribble/latex-properties library provides datatypes used as style properties for Latex rendering.

(struct tex-addition (path)
  #:extra-constructor-name make-tex-addition)
  path : 
(or/c path-string?
      (cons/c 'collects (listof bytes?)))
Used as a style property to supply a ".tex" file to be included in the generated Latex. This property can be attached to any style, and all additions are collected to the top of the generated Latex file.

The path field can be a result of path->main-collects-relative.

(struct latex-defaults (prefix style extra-files)
  #:extra-constructor-name make-latex-defaults)
  prefix : 
(or/c bytes? path-string?
      (cons/c 'collects (listof bytes?)))
  style : 
(or/c bytes? path-string?
      (cons/c 'collects (listof bytes?)))
  extra-files : 
(listof (or/c path-string?
              (cons/c 'collects (listof bytes?))))
Used as a style property on the main part of a document to set a default prefix file, style file, and extra files (see Configuring Output). The defaults are used by the scribble command-line tool for and --latex or --pdf mode if none are supplied via --prefix and --style (where extra-files are used only when prefix is used). A byte-string value is used directly like file content, and a path can be a result of path->main-collects-relative.

Languages (used with #lang) like scribble/manual and scribble/sigplan add this property to a document to specify appropriate files for Latex rendering.

(struct latex-auto-extra-files (paths)
  #:extra-constructor-name make-latex-auto-extra-files)
  paths : 
(listof (or/c path-string?
              (cons/c 'collects (listof bytes?))))
Used as a style property for the main part of a document to supply extra files needed to build the document via the scribble command-line tool (for --latex and --pdf mode).

Languages (used with #lang) like scribble/sigplan add this property to a document to specify appropriate extra files.