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.

• A table is an instance of table; it has a list of list of flows with a particular style. In Latex output, each table cell is typeset as a single line.

• A itemization is an instance of itemization; it has a list of flows.

• A blockquote is an instance of blockquote; it has list of blocks that are indented according to a specified style.

• A paragraph is an instance of paragraph; it has a content, which is a list of elements:

  • An element can be a string, one of a few symbols, an instance of element (possibly link-element, etc.), a part-relative element, a delayed element, or anything else allowed by the current renderer.

    • A string element is included in the result document verbatim, except for space, and unless the element’s style is 'hspace. In a style other than 'hspace, consecutive spaces in the output may be collapsed togther or replaced with a line break. In the style 'hspace, all text is converted to uncollapsable spaces that cannot be broken across lines.

    • A symbol element is either 'mdash, 'ndash, 'ldquo, 'lsquo, 'rsquo, 'rarr, or 'prime; it is rendered as the corresponding HTML entity (even for Latex output).

    • An instance of element has a list of elements plus a style. The style’s interpretation depends on the rendrer, but it can be one of a few special symbols (such as 'bold) that are recognized by all renderers.

    • An instance of link-element has a tag for the target of the link.

    • An instance of target-element has a tag to be referenced by link-elements. An instance of the subtype toc-target-element is treated like a kind of section label, to be shown in the “on this page” table for HTML output.

    • An instance of index-element has a tag (as a target), a list of strings for the keywords (for sorting and search), and a list of elements to appear in the end-of-document index.

    • An instance of collect-element has a procedure that is called in the collect pass of document processing to record information used by later passes.

    • A part-relative element is an instance of part-relative-element, which has a procedure that is called in the collect pass of document processing to obtain content (i.e., a list of elements). When the part-relative element’s procedure is called, collected information is not yet available, but information about the enclosing parts is available.

    • A delayed element is an instance of delayed-element, which has a procedure that is called in the resolve pass of document processing to obtain content (i.e., a list of elements).

    • An instance of aux-element is excluded in the text of a link when it appears in a referenced section name.

    • An instance of hover-element adds text to show in render HTML when the mouse hovers over the elements.

    • An instance of script-element provides script code (usually Javascript) to run in the browser to generate the element; the element’s normal content is used when scripting is disabled in the browser, or for rendering to other formats.

• A delayed block is an instance of delayed-block, which has a procedure that is called in the resolve pass of document processing to obtain a 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:

• 'toc – sub-parts of the part are rendered on separate pages for multi-page HTML mode.

• 'index – the part represents an index.

• 'reveal – shows sub-parts when this part is displayed in a table-of-contents panel in HTML output (which normally shows only the top-level sections).

• 'hidden – the part title is not shown in rendered output.

• 'no-toc – as a style for the main part of a document, causes the HTML output to not include a margin box for the main table of contents; the “on this page” box that contains toc-element and toc-target-element links (and that only includes an “on this page” label for multi-page documents) takes on the location and color of the main table of contents, instead.

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

• a string, which corresponds to a CSS class for HTML output and a macro name for Latex output;

• one of the symbols that all renderers recognize: 'tt, 'italic, 'bold, 'sf, 'subscript, 'superscript, 'hspace, or 'newline (which renders a line break independent of the content);

• a list of the form (list 'color name) or (list 'color byte byte byte) to set the text color, where name is one of "white", "black", "red", "green", "blue", "cyan", "magenta", or "yellow", or three bytes specify RGB values;

• a list of the form (list 'bg-color name) or (list 'bg-color byte byte byte) to set the text background color (with the same constraints and meanings as for 'color);

• an instance of target-url to generate a hyperlink;

• an instance of image-file to support an inline image; or

• an instance of with-attributes, which combines a base style with a set of additional HTML attributes.

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.