1 How to Scribble Documentation
2 Scribble Layers
3 @-Reader
4 Structures And Processing
5 Renderer
6 Decoding Text
7 Document Language
8 Document Reader
9 Basic Document Forms
10 Scheme
11 Manual Forms
12 Evaluation and Examples
13 BNF Grammars
14 Cross-Reference Utilities
15 Text Preprocessor
Index
On this page:
4.1 Parts
4.2 Tags
4.3 Collected and Resolved Information
4.4 Structure Reference
part
unnumbered-part
versioned-part
flow
paragraph
styled-paragraph
table
itemization
blockquote
delayed-block
element
target-element
toc-target-element
toc-element
link-element
index-element
aux-element
hover-element
script-element
delayed-element
part-relative-element
collect-element
with-attributes
collected-info
target-url
image-file
block?
tag?
generated-tag
content->string
element->string
element-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
Version: 4.0.2

 

4 Structures And Processing

 (require scribble/struct)

A document is represented as a part, as described in Parts. This representation is intended to 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 three passes. The first pass is the collect pass, which globally collects information in the document, such as targets for hyperlinking. The second pass is the resolve pass, which matches hyperlink references with targets and expands delayed elements (where the expansion should not contribute new hyperlink targets). The final pass is the render pass, which generates the resulting document. None of the passes mutate the document, but instead collect information in side collect-info and resolve-info tables.

4.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. An unnumbered-part is the same as a part, but it isn’t numbered. A versioned-part is add a version field to part. There’s 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 an instance of flow; it has a list of blocks.

A block is either a table, an itemization, blockquote, paragraph, or a delayed block.

4.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 Scheme 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, 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.

4.3 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.

4.4 Structure Reference

(struct

 

part

 (

tag-prefix

 

 

 

 

tags

 

 

 

 

title-content

 

 

 

 

style

 

 

 

 

to-collect

 

 

 

 

flow

 

 

 

 

parts))

  tag-prefix : (or/c false/c string?)

  tags : (listof tag?)

  title-content : (or/c false/c list?)

  style : any/c

  to-collect : list?

  flow : flow?

  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.

The style field is normally either a symbol or a list of symbols. The currently recognized style symbols (alone or in a list) 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 flow field contains the part’s initial flow (before sub-parts).

The parts field contains sub-parts.

(struct

 

(unnumbered-part part)

 

())

Although a section number is computed for an “unnumbered” section during the collect pass, the number is not rendered.

(struct

 

(versioned-part part)

 

(version))

  version : (or/c string? false/c)

Supplies a version number for this part and its sub-parts (except as overridden). A #f version is the same as not supplying a version.

The version number may be used when rendering a document. At a minimum, a version is rendered when it is attached to a part representing the whole document. The default version for a document is (version).

(struct

 

flow

 

(paragraphs))

  paragraphs : (listof flow-element?)

A flow has a list of blocks.

(struct

 

paragraph

 

(content))

  content : list?

A paragraph has a list of elements.

(struct

 

(styled-paragraph paragraph)

 

(style))

  style : any/c

The style is normally a string that corresponds to a CSS class for HTML output.

(struct

 

table

 

(style flowss))

  style : any/c

  flowss : (listof (listof (or/c flow? (one-of/c 'cont))))

A table has, roughly, a list of list of flows. A cell in the table can span multiple columns by using 'cont instead of a flow in the following columns (i.e., for all but the first in a set of cells that contain a single flow).

(struct

 

itemization

 

(flows))

  flows : (listof flow?)

A itemization has a list of flows.

(struct

 

blockquote

 

(style paragraphs))

  style : any/c

  paragraphs : (listof flow-element?)

A blockquote has a style and a list of blocks. The style field is normally a string that corresponds to a CSS class for HTML output.

(struct

 

delayed-block

 

(resolve))

  resolve : (any/c part? resolve-info? . -> . flow-element?)

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))

  style : any/c

  content : list?

The style field is normally either

The content field is a list of elements.

(struct

 

(target-element element)

 

(tag))

  tag : tag?

Declares the content as a hyperlink target for tag.

(struct

 

(toc-target-element target-element)

 

())

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

(struct

 

(toc-element element)

 

(toc-content))

  toc-content : list?

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))

  tag : tag?

Hyperlinks the content to tag.

(struct

 

(index-element element)

 

(tag plain-seq entry-seq desc))

  tag : tag?

  plain-seq : (and/c pair? (listof string?))

  entry-seq : list?

  desc : any/c

The plain-seq specifies the keys for sorting, where the first element 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-element 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

 

(aux-element element)

 

())

Instances of this structure type are intended for use in titles, where the auxiliary part of the title can be omitted in hyperlinks. See, for example, secref.

(struct

 

(hover-element element)

 

(text))

  text : string?

The text is displayed in HTML output when the mouse hovers over the element’s content.

(struct

 

(script-element element)

 

(type script))

  type : string?

  

script

 

:

 

(or/c path-string?

      (listof string?))

For HTML rendering, when scripting is enabled in the browser, script is used for the element instead of its normal content – it can be either path naming a script file to refer to, or the contents of the script. The type string is normally "text/javascript".

(struct

 

delayed-element

 

(resolve sizer plain))

  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 (i.e., a list of elements). 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 element 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 element when needed before the collect pass, such as when element->string is used before the collect pass.

(struct

 

part-relative-element

 

(resolve sizer plain))

  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))

  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

 

with-attributes

 

(style assoc))

  style : any/c

  assoc : (listof (cons/c symbol? string?))

Used for an element’s style to combine a base style with arbitrary HTML attributes.

(struct

 

collected-info

 

(number parent 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 style))

  addr : path-string?

  style : any/c

Used as a style for an element. The style at this layer is a style for the hyperlink.

(struct

 

image-file

 

(path scale))

  

path

 

:

 

(or/c path-string?

      (cons/c 'collects (listof bytes?)))

  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.

(block? v)  boolean?

  v : any/c

Returns #t if v is a paragraph, table, itemization, blockquote, or delayed-block, #f otherwise.

(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

 

())

A placeholder for a tag to be generated during the "collect" "\n" "pass". Use tag-key to convert a tag containing a generated-tag instance to one containing a string.

(content->string content)  string?

  content : list?

(content->string content renderer p info)  string?

  content : list?

  renderer : any/c

  p : part?

  info : resolve-info?

Converts a list of elements 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).

(element->string element)  string?

  element : any/c

(element->string element renderer p info)  string?

  element : any/c

  renderer : any/c

  p : part?

  info : resolve-info?

Like content->string, but for a single element.

(element-width element)  nonnegative-exact-integer?

  element : any/c

Returns the width in characters of the given element.

(block-width e)  nonnegative-exact-integer?

  e : block?

Returns the width in characters of the given block.

(struct

 

collect-info

 (

ht

 

 

 

 

ext-ht

 

 

 

 

parts

 

 

 

 

tags

 

 

 

 

gen-prefix

 

 

 

 

relatives

 

 

 

 

parents))

  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))

  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 setup-plt 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 setup-plt 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 setup-plt 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.