6.3 Structures And Processing

► |  | Scribble: The Racket Documentation Tool

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

▼ | 6 | Low-Level Scribble API

6.1 | Scribble Layers
6.2 | @ Reader Internals
6.3 | Structures And Processing
6.4 | Renderers
6.5 | Decoding Text
6.6 | Document Language
6.7 | Document Reader
6.8 | Cross-Reference Utilities
6.9 | Tag Utilities
6.10 | Blue Boxes Utilities
6.11 | Extending and Configuring Scribble Output

► | 6.3 | Structures And Processing

6.3.1 | Parts, Flows, Blocks, and Paragraphs
6.3.2 | Tags
6.3.3 | Styles
6.3.4 | Collected and Resolved Information
6.3.5 | Structure Reference
6.3.6 | HTML Style Properties
6.3.7 | Latex Style Properties

On this page:

6.3.1 Parts, Flows, Blocks, and Paragraphs
6.3.2 Tags
6.3.3 Styles
6.3.4 Collected and Resolved Information
6.3.5 Structure Reference
part
paragraph
table
itemization
nested-flow
compound-paragraph
traverse-block
delayed-block
element
image-element
target-element
toc-target-element
toc-target2-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
delayed-index-desc
collected-info
target-url
document-version
document-date
color-property
background-color-property
table-cells
table-columns
cell-padding-property
box-mode
box-mode*
block?
content?
style
plain
element-style?
tag?
generated-tag
content->string
content-width
block-width
part-number-item?
numberer?
make-numberer
numberer-step
link-render-style
current-link-render-style
collect-info
resolve-info
info-key?
collect-put!
resolve-get
resolve-get/ ext?
resolve-get/ ext-id
resolve-search
resolve-get/ tentative
resolve-get-keys
part-collected-info
current-part-context-accumulation
tag-key
traverse-block-block
traverse-element-content
block-traverse-procedure/ c
element-traverse-procedure/ c
6.3.6 HTML Style Properties
attributes
alt-tag
column-attributes
link-query-addition
url-anchor
hover-property
script-property
xexpr-property
css-addition
css-style-addition
js-addition
js-style-addition
body-id
document-source
html-defaults
head-extra
head-addition
initial-scale
render-convertible-as
part-link-redirect
part-title-and-content-wrapper
link-resource
install-resource
6.3.7 Latex Style Properties
tex-addition
latex-defaults
latex-defaults+ replacements
command-extras
command-optional
short-title
table-row-skip

Racket
top contents ← prev up next →

### 6.3 Structures And Processing🔗ℹ

(require scribble/core) | package: scribble-lib

A document is represented as a part, as described in Parts, Flows, Blocks, and Paragraphs. 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:

- The traverse pass traverses the document content in document order so that information from one part of a document can be communicated to other parts of the same document. The information is transmitted through a symbol-keyed mapping that can be inspected and extended by traverse-elements and traverse-blocks in the document. The traverse pass iterates the traversal until it obtains a fixed point (i.e., the mapping from one iteration is unchanged from the previous iteration).

- The collect pass globally collects information in the document that can span documents that are built at separate times, such as targets for hyperlinking.

- The resolve pass matches hyperlink references with targets and expands delayed elements (where the expansion should not contribute new hyperlink targets).

- The render pass generates the result document.

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.

#### 6.3.1 Parts, Flows, Blocks, and Paragraphs🔗ℹ

This diagram shows the large-scale structure of the type hierarchy for Scribble documents. A box represents a struct or a built-in Racket type; for example part is a struct. The bottom portion of a box shows the fields; for example part has three fields, title, blocks, and subparts. The substruct relationship is shown vertically with navy blue lines connected by a triangle; for example, a compound-paragraph is a block. The types of values on fields are shown via dark red lines in the diagram. Doubled lines represent lists and tripled lines represent lists of lists; for example, the blocks field of compound-paragraph is a list of blocks. Dotted lists represent functions that compute elements of a given field; for example, the block field of a traverse-block struct is a function that computes a block.

The diagram is not completely accurate: a table may have 'cont in place of a block in its cells field, and the types of fields are only shown if they are other structs in the diagram. A prose description with more detail follows the diagram.

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.

- A table is an instance of table; it has a list of list of blocks corresponding to table cells.

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

- A nested flow is an instance of nested-flow; it has a flow that is typeset as sub-flow.

- A paragraph is an instance of paragraph; it has a content:

  - A content can be a string, one of a few symbols, a convertible value in the sense of convertible?, an instance of element (possibly link-element, etc.), a multiarg-element, a traverse element, a part-relative element, a delayed element, or a list of content.

    - A string is included in the result document verbatim, except for space, and unless the content’s enclosing 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 uncollapsible spaces that cannot be broken across lines.

    - A symbol content is either 'mdash, 'ndash, 'ldquo, 'rdquo, 'lsquo, 'rsquo, 'lang, 'rang, 'larr, 'rarr, 'nbsp, 'prime, 'alpha, or 'infin; it is rendered as the corresponding HTML entity (even for Latex output).

    - A convertible value in the sense of convertible? is used in a renderer-specific way, but values convertible to 'text renders the same as the resulting string. If a renderer is not able to convert the value to a known format, the value is converted to a string using write.

    - An instance of element has a content plus a style. The style’s interpretation depends on the renderer, 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 contents to appear in the end-of-document index.

    - An instance of image-element incorporates an image from a file into the rendered document.

    - An instance of multiarg-element combines a style with a list of content, where the style corresponds to a rendered command that takes multiple arguments.

    - 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 traverse element is an instance of traverse-element, which ultimately produces content, but can accumulate and inspect information in the traverse pass.

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

    - An instance of render-element has a procedure that is called in the render pass of document processing.

- A compound paragraph is an instance of compound-paragraph; like blockquote, it has list of blocks, but the blocks are typeset as a single paragraph (e.g., no indentation after the first block) instead of inset.

- A traverse block is an instance of traverse-block, which ultimately produces another block, but can accumulate and inspect information during the traverse pass.

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

Changed in version 1.23 of package scribble-lib: Changed the handling of convertible? values to recognize a 'text conversion and otherwise use write.

#### 6.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, 'tech, or 'cite, or whose second item is a list that starts with 'prefixable:

- The prefix is added to a string second item by creating a list containing the prefix and string.

- The prefix is added to a list second item after 'part, 'tech, or 'cite using cons.

- The prefix is added to a second item that starts 'prefixable by adding it to the list after 'prefixable.

- A prefix is not added to a generated-tag item.

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.

The scribble/tag library provides functions for constructing tags.

#### 6.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, or #f. A style property can be anything, including a symbol or 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.

#### 6.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.

During the collect pass and resolve pass, part context information is accumulated from enclosing parts. The context starts as an empty table. When a part-tag-prefix for a part reports a hash table, then for each key in the table, the value in the table is merged with the context from enclosing parts. A value is merged by adding the key and value to the accumulation if the key is not yet present, or by consing the new value to the context’s current value when the key is present. For example, the key 'index-extras is used to merge with an index-desc within a discovered index-element. Use current-part-context-accumulation during the collect pass or resolve pass to retrieve the value that has been accumulated from enclosing parts.

#### 6.3.5 Structure Reference🔗ℹ

> > struct
> > (struct |  | part | ( | tag-prefix
> > |  |  |  | tags
> > |  |  |  | title-content
> > |  |  |  | style
> > |  |  |  | to-collect
> > |  |  |  | blocks
> > |  |  |  | parts)
> #:extra-constructor-name make-part)
> tag-prefix : (or/c #f string? hash?)
> tags : (listof tag?)
> title-content : (or/c #f list?)
> style : style?
> to-collect : list?
> blocks : (listof block?)
> parts : (listof part?)

The tag-prefix field determines the optional tag prefix for the part and/or part context accumulation. When tag-prefix is a hash table, the value associated with the 'tag-prefix key is used as the tag prefix when the value is a string. When tag-prefix as a hash table is used for the main part in a document rendered by raco setup, raco setup uses recognizes some keys to configure the document’s rendering; see scribblings in Controlling raco setup with "info.rkt" Files for more information.

The tags indicates a list of tags that each link to the section. Normally, tags should be a non-empty list, so that hyperlinks can target 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:

- 'index — The part represents an index.

The recognized style properties are as follows:

- 'unnumbered — A section number is not computed or rendered for the section.

- 'hidden-number — A section number is computed for the section, but it is not rendered as part of the section name.

- 'toc-hidden — The part title is not shown in tables of contents, including in “on this page” boxes. For Latex rendering, the part title is omitted only if it is unnumbered or has a hidden number.

- 'hidden — The part title is not shown; for Latex output, the part title is not shown only if its is empty, and in that case, it is also excluded from tables of contents. The 'toc-hidden style property usually should be included with 'hidden (for consistency in non-Latex output).

- 'grouper — The part is numbered with a Roman numeral, by default, and its subsections continue numbering as if they appeared in the preceeding part. In other words, the part acts like a “part” in a book where chapter numbering is continuous across parts.

- numberer instance — A numberer created with make-numberer determines a representation of the part’s section number as an extension of it’s parent’s number. A numberer overrides the default representation, which is a natural number or (in the case of an accompanying 'grouper property) a Roman numeral. If a 'unnumbered property is also present, a numberer property is ignored.

- 'toc — Sub-parts of the part are rendered on separate pages for multi-page HTML mode.

- 'non-toc — Initial sub-parts of the part are not rendered on separate pages for multi-page HTML mode; this style property applies only to the main part.

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

- 'quiet — In HTML output and most other output modes, hides entries for sub-parts of this part in a table-of-contents or local-table-of-contents listing except when those sub-parts are top-level entries in the listing.

- 'no-toc+aux — As a style property for the main part of a rendered page, causes the HTML output to not include a margin box for the main table of contents, “on this page”, or tables with the 'aux style property. The 'no-toc+aux property effectively implies 'no-toc and 'no-sidebar, but also suppresses 'aux tables.

- 'no-toc — As a style property for the main part of a rendered page, 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.

- 'no-sidebar — As a style property for the main part of a document, causes the HTML output to not include an “on this page” margin box.

- 'no-navigation — As a style property for the main part of a rendered page, causes the HTML output to not include “top,” “up,”, “prev,” and “next” controls if they would otherwise apply.

- 'family-navigation — As a style property for the main part of a rendered page, causes the HTML output to include “top,” “up,”, “prev,” and “next” controls only when the viewing context indicates a language family not in the page’s language families.

- 'show-language-family — As a style property for the main part of a rendered page or any enclosing part, causes the HTML output to include an indication of the document’s primary language family, as well as the language family being used to navigate documentation.

- 'no-header-controls — Suppresses link and link-information icons (if any) as part of a section header in HTML output.

- 'no-index — Has no effect as a style property on a part, but as a style property on a title or part-start that provides a part’s style via decode, the 'no-index style property cause decode to skip the generation of an entry for the part’s title in the document index.

- document-version structure — A version number for this part and its sub-parts (except as overridden). When it is not "" may be used when rendering a document; at a minimum, a non-"" version is rendered when it is attached to a part representing the whole document. The default version for a document is (version). In rendered form, the version is normally prefixed with the word “Version,” but this formatting can be controlled by overriding .version:before and/or .versionNoNav:before in CSS for HTML rendering or by redefining the \SVersionBefore macro for Latex rendering (see Extending and Configuring Scribble Output).

- document-date structure — A date for the part, normally used on a document’s main part for for Latex output. The default date for a document is #f, which avoids explicitly specifying a date at the Latex level, so that the current date is used as the document date. Set the date to "" to suppress a date in an output document.

- body-id structure — Generated HTML uses the given string id attribute of the <body> tag; this style property can be set separately for parts that start different HTML pages, otherwise it is effectively inherited by sub-parts; the default is "scribble-racket-lang.org", but raco setup installs "doc-racket-lang.org" as the id for any document that it builds.

- attributes structure — Provides additional HTML attributes for the <html> tag when the part corresponds to its own HTML page.

- head-extra structure — Provides additional HTML content for the <head> tag when the part corresponds to its own HTML page.

- head-addition structure — Like head-extra, but also propagated to enclosing and nested HTML pages.

- color-property structure — For HTML, applies a color to the part title.

- background-color-property structure — For HTML, applies a color to the background of the part title.

- hover-property structure — For HTML, adds a text label to the title to be shown when the mouse hovers over it.

- render-convertible-as structure — For HTML, controls how objects that subscribe to the file/convertible protocol are rendered.

- document-source structure — For HTML, provides a module path for the part’s source. Clicking on an HTML section title generated for the part or its sub-parts may show the module path plus a section-tag string, so that the user can create a reference to the section.

- link-render-style structure — Determines the default rendering of links to sections or other destinations within the section. See also link-element and current-link-render-style.

- part-title-and-content-wrapper structure — For HTML, adds a tag with attributes around the part title and its content, including any content before the title from a paragraph with the 'pretitle style. The wrapper is not used around a subpart that is rendered on a different HTML page.

- part-link-redirect structure — For HTML, redirects hyperlinks that would otherwise go to the part so that they refer to a different URL.

- 'enable-index-merge — On an index parts or one of its enclosing parts for Latex output, causes index entries to be merged when they have the same content, with multiple references for the same entry combined with \Smanypageref. The \Smanypageref Latex macro must be redefined to accept multiple ,-separated labels and generate a suitable set of references. See also scriblib/book-index.

- initial-scale structure — For HTML, adjusts the initial scale for responsive views, such as on mobile devices.

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.

Changed in version 1.25 of package scribble-lib: Added 'no-index support.
Changed in version 1.26: Added link-render-style support.
Changed in version 1.27: Added 'no-toc+aux support.
Changed in version 1.54: Changed tag-prefix field to allow a part context hash table.
Changed in version 1.57: Added 'no-header-controls support.
Changed in version 1.59: Added 'no-navigation, 'family-navigation, and 'show-language-family support.

> > struct
> > (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:

- 'author — Typeset as the author of a document. Such paragraphs normally should appear only in the initial flow of a part for a document, where they are treated specially by the Latex renderer by moving the author information to the title.

- 'pretitle — Typeset before the title of the enclosing part.

- 'wraps — Like a #f style name, but not boxable in the sense of box-mode for Latex output.

When a paragraph’s style is #f, then it is boxable in the sense of box-mode for Latex output.

The currently recognized style properties are as follows:

- 'omitable — When a table cell contains a single paragraph with the 'omitable style property, then when rendering to HTML, no <p> tag wraps the cell content.

- 'div — Generates <div> HTML output instead of <p> (unless a alt-tag property is provided).

- alt-tag structure — Generates the indicated HTML tag instead of <p> or <div>.

- attributes structure — Provides additional HTML attributes for the <p>, <div>, or alternate tag.

- 'never-indents — For Latex and compound paragraphs; see compound-paragraph.

- box-mode structure — For Latex output, uses an alternate rendering form for boxing contexts (such as a table cell); see box-mode.

> > struct
> > (struct |  | table (style blockss)
> #:extra-constructor-name make-table)
> style : style?
> blockss : (listof (listof (or/c block? 'cont)))

See also the tabular function.

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:

- 'boxed — Renders as a definition. This style name is not intended for use on a table that is nested within a 'boxed table; nested uses may look right for some renders of the style but not others.

- 'centered — Centers HTML output horizontally.

- 'block — Prevents pages breaks in Latex output.

The following style properties are currently recognized:

- table-columns structure — Provides column-specific styles, but only column-attributes properties (if any) are used if a table-cells structure is included as a style property. See table-cells for information about how a column style is used for each cell.

- table-cells structure — Provides cell-specific styles. See table-cells for information about how the styles are used.

- attributes structure — Provides additional HTML attributes for the <table> tag.

- 'aux — For HTML, include the table in the table-of-contents display for the enclosing part.

- 'never-indents — For Latex and compound paragraphs; see compound-paragraph.

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
> > (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:

- 'compact — Reduces space between items.

- 'ordered — Generates <ol> HTML output instead of <ul> or an Latex enumeration instead of an itemization.

The following style properties are currently recognized:

- attributes structure — Provides additional HTML attributes for the <ul> or <ol> tag.

- 'never-indents — For Latex and compound paragraphs; see compound-paragraph.

> > struct
> > (struct |  | nested-flow (style blocks)
> #:extra-constructor-name make-nested-flow)
> style : style?
> 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:

- 'inset — Insets the nested flow relative to surrounding text.

- 'code-inset — Insets the nested flow relative to surrounding text in a way suitable for code. If the nested flow has a single block, then it is boxable in the sense of box-mode for Latex output.

- 'vertical-inset — Insets the nested flow vertically relative to surrounding text, but not horizontally. If the nested flow has a single block, then it is boxable in the sense of box-mode for Latex output.

The following style properties are currently recognized:

- 'command — For Latex output, a string style name is used as a command name instead of an environment name.

- 'multicommand — For Latex output, a string style name is used as a command name with a separate argument for each block in blocks.

- attributes structure — Provides additional HTML attributes for the <blockquote> tag.

- 'never-indents — For Latex and compound paragraphs; see compound-paragraph.

- box-mode structure — For Latex output, uses an alternate rendering form for boxing contexts (such as a table cell); see box-mode.

- 'decorative — The content of the nested flow is intended for decoration. Text output skips a decorative nested flow.

- alt-tag structure — Generates the indicated HTML tag instead of <blockquote>.

- 'pretitle — For Latex, raises the contents of the flow to above the title.

> > struct
> > (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:

- 'command — For Latex output, a string style name is used as a command name instead of an environment name.

- alt-tag structure — Generates the given HTML tag instead of <p>.

- attributes structure — Provides additional HTML attributes for the <p> or alternate tag.

- 'never-indents — For Latex within another compound paragraph; see above.

> > struct
> > (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 get and set procedures to get and set symbol-keyed information; the traverse procedure 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.

The get procedure passed to traverse takes a symbol and any value to act as a default; it returns information registered for the symbol or the given default if no value has been registered. The set procedure passed to traverse takes a symbol and a value to be registered for the symbol.

See also cond-block in scriblib/render-cond. The symbol 'scribble:current-render-mode is automatically registered to a list of symbols that describe the target of document rendering. The list contains 'html when rendering to HTML, 'latex when rendering via Latex, and 'text when rendering to text. The registration of 'scribble:current-render-mode cannot be changed via set.

> > struct
> > (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
> > (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:

- 'tt, 'italic, 'bold, 'roman, 'sf, 'url, 'subscript, 'superscript, 'smaller, 'larger — Basic styles recognized by all renders.

- 'hspace — Renders its content as monospace blanks.

- 'newline — Renders a line break independent of the content.

- 'no-break — Prevents line breaks when rendering content.

The following style properties are currently recognized:

- target-url structure — Generates a hyperlink.

- url-anchor structure — For HTML, inserts a hyperlink target before content.

- color-property structure — Applies a color to the text of content.

- background-color-property structure — Applies a color to the background of content.

- alt-tag structure — Generates the given HTML tag instead of the default one (<span>, <b>, etc.).

- attributes structure — Provides additional HTML attributes for a tag.

- hover-property structure — For HTML, adds a text label to the content to be shown when the mouse hovers over it.

- script-property structure — For HTML, supplies a script alternative to content.

- xexpr-property structure — For HTML, supplies literal HTML to render before and after content.

- 'aux — Intended for use in titles, where the auxiliary part of the title can be omitted in hyperlinks. See, for example, secref.

- 'tt-chars — For Latex output, when the style name is a string, render the element’s content with escapes suitable for Latex tt mode.

- 'exact-chars — For Latex output, when the style name is a string or #f, render the elements content exactly (without escapes).

- command-extras structure — For Latex output, adds strings as arguments to the Latex command.

Changed in version 1.6 of package scribble-lib: Changed 'exact-chars handling to take effect when the style name is #f.
Changed in version 1.27: Changed to support xexpr-property.

> > struct
> > (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
> > (struct |  | target-element element (tag)
> #:extra-constructor-name make-target-element)
> tag : tag?

Declares the content as a hyperlink target for tag.

> > struct
> > (struct |  | toc-target-element target-element ()
> #:extra-constructor-name make-toc-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
> > (struct |  | toc-target2-element toc-target-element (toc-content)
> #:extra-constructor-name make-toc-target2-element)
> toc-content : content?

Extends target-element with a separate field for the content to be shown in the “on this page” table for HTML output.

> > struct
> > (struct |  | page-target-element target-element ()
> #:extra-constructor-name make-page-target-element)

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

> > struct
> > (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
> > (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
> > (struct |  | link-element element (tag)
> #:extra-constructor-name make-link-element)
> tag : tag?

Represents a hyperlink to tag.

Normally, the content of the element is rendered as the hyperlink. When tag is a part tag and the content of the element is null, however, rendering is treated specially based on the mode value of a link-render-style style property:

- For HTML output, in the 'default mode, the generated reference is the hyperlinked title of the elements in the section’s title content, except that elements with the 'aux style property are omitted in the hyperlink label.

  In 'number mode, the section title is not shown. Instead, the word “section” is shown followed by a hyperlinked section number. The word “section” starts in uppercase if the element’s style includes a 'uppercase property.

- For Latex/PDF output, the generated reference’s format can depend on the document style in addition the mode. For the 'default mode and a default document style, a section number is shown by the word “section” followed by the section number, and the word “section” and the section number are together hyperlinked. The word “section” starts in uppercase if the element’s style includes a 'uppercase property. The scribble/manual style uses the symbol “§” in place of the word “section”.

  In 'number mode, rendering is the same, except that only the number is hyperlinked, not the word “section” or the “§” symbol.

  A new document style can customize Latex/PDF output (see Extending and Configuring Scribble Output) by redefining the \SecRefLocal, etc., macros (see Base Latex Macros). The \SecRef, etc., variants are used in 'number mode.

If a link-render-style style property is not attached to a link-element that refers to a part, a link-render-style style property that is attached to an enclosing part is used, since attaching a link-render-style style property to a part causes current-link-render-style to be set while rendering the part. Otherwise, the render-time value of current-link-render-style determine’s a link-element’s rendering.

The following style properties are recognized in addition to the style properties for all elements:

- link-render-style structure — As described above.

- 'indirect-link — For HTML output, treats the link as “external”. When rendering to HTML and the set-external-tag-path method is called to provide an external-link URL, then the resolution of the hyperlink can be deferred until the link is clicked (or, in some cases, patched by JavaScript when the documentation is viewed in a browser).

  Note that deferred resolution relies on cooperation with the page pointed to by the external-link URL, and arbitrary tags are not supported. Functions and forms like seclink, other-doc, racketmodname, tech, and techlink provide higher-level interfaces for creating supported kinds of indirect links.

- link-query-addition structure — Adds query parameters to the link.

Changed in version 1.26 of package scribble-lib: Added link-render-style support.
Changed in version 1.65: Added link-query-addition support.

> > struct
> > (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 exported-index-desc* with the '("procedure") kind. See scribble/manual-struct for other types of desc values, but generally index-desc or exported-index-desc* should be used. A delayed-index-desc is also recognized, and its resolve function is called during the to provide the index entry’s description (which should normally produce a index-desc or exported-index-desc*).

When desc is index-desc, exported-index-desc, or exported-index-desc*, and when part context is accumulated for 'index-extras, the accumulated context is merged with the extras field of desc (after promoting exported-index-desc to exported-index-desc* with an empty extras hash table). An accumulated 'index-extras contribution should be a cons tree of hash tables, which are processed in order so that a subpart takes precedence over its enclosing part. For each accumulated table, if a key in the table is not present in extras table, it is added with its value to the table. These additions are performed as an index entry is recorded during the collect pass or resolve pass (the latter for a delayed-index-desc).

See also index.

> > struct
> > (struct |  | multiarg-element (style contents)
> #:extra-constructor-name make-multiarg-element)
> style : element-style?
> contents : (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 contents.

> > struct
> > (struct |  | traverse-element (traverse)
> #:extra-constructor-name make-traverse-element)
> traverse : element-traverse-procedure/c

See also cond-element in scriblib/render-cond. Like traverse-block, but the traverse procedure must eventually produce content, rather than a block.

> > struct
> > (struct |  | delayed-element (resolve sizer plain)
> #:extra-constructor-name make-delayed-element)
> resolve : (any/c part? resolve-info? . -> . content?)
> sizer : (-> any/c)
> plain : (-> any/c)

The resolve procedure’s arguments are the same as for delayed-block, but the result is content. Unlike delayed-block, the result of the resolve 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
> > (struct |  | part-relative-element (collect sizer plain)
> #:extra-constructor-name make-part-relative-element)
> collect : (collect-info? . -> . content?)
> 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 part. Functions like part-collected-info and collected-info-number can extract information like the part number.

> > struct
> > (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
> > (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
> > (struct |  | delayed-index-desc (resolve)
> #:extra-constructor-name make-delayed-index-desc)
> resolve : (any/c part? resolve-info? . -> . any/c)

Like index-desc, but the resolve procedure is called during the resolve pass. See also index-element.

> > struct
> > (struct |  | collected-info (number parent info)
> #:extra-constructor-name make-collected-info)
> number : (listof part-number-item?)
> parent : (or/c #f part?)
> info : any/c

Computed for each part by the collect pass.

The length of the number list indicates the section’s nesting depth. Elements of number correspond to the section’s number, it’s parent’s number, and so on (that is, the section numbers are in reverse order):

- A number value corresponds to a normally numbered section.

- A non-empty string corresponds to a 'grouper section, which is shown as part of the combined section number only when it’s the first element.

- A list corresponds to a numberer-generated section string plus its separator string, where the separator is used in a combined section number after the section string and before a subsection’s number (or, for some output modes, before the title of the section).

- For an unnumbered section, a #f is used in place of any number or lists element, while "" is used in place of all non-empty strings.

Changed in version 1.1 of package scribble-lib: Added (list/c string? string?) number items for numberer-generated section numbers.

> > struct
> > (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
> > (struct |  | document-version (text)
> #:extra-constructor-name make-document-version)
> text : (or/c string? #f)

Used as a style property for a part to indicate a version number.

> > struct
> > (struct |  | document-date (text)
> #:extra-constructor-name make-document-date)
> text : (or/c string? #f)

Used as a style property for a part to indicate a date (which is typically used for Latex output).

> > struct
> > (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.

When rendering to HTML, a color-property is also recognized for a block, part (and used for the title in the latter case)or cell in a table.

> > struct
> > (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
> > (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 are recognized as cell-style properties:

- 'left — Left-align the cell content.

- 'right — Right-align the cell content top baselines.

- 'center — Center the cell content horizontally.

- 'top — Top-align the cell content.

- 'baseline — Align the cell content top baselines.

- 'bottom — bottom-align the cell content.

- 'vcenter — Center the cell content vertically.

- 'border — Draw a line around all sides of the cell. Borders along a shared edge of adjacent cells are collapsed into a single line.

- 'left-border, 'right-border, 'top-border, or 'bottom-border — Draw a line along the corresponding side of the cell (with the same border collapsing as for 'border).

- color-property structure — For HTML, applies a color to the cell content.

- background-color-property structure — For HTML, applies a color to the background of the cell.

- cell-padding-property structure — Specifies padding to add around a cell’s content.

- attributes — Provides additional HTML attributes for the cell’s <td> tag.

Changed in version 1.1 of package scribble-lib: Added color-property and background-color-property support.
Changed in version 1.4: Added 'border, 'left-border, 'right-border, 'top-border, and 'bottom-border support.

> > struct
> > (struct |  | table-columns (styles)
> #:extra-constructor-name make-table-columns)
> styles : (listof style?)

Like table-cells, but with support for a column-attributes property in each style, and the styles list is otherwise duplicated for each row in the table. The non-column-attributes parts of a table-columns are used only when a table-cells property is not present along with the table-columns property.

For HTML table rendering, for each column that has a column-attributes property in the corresponding element of styles, the attributes are put into an HTML col tag within the table.

> > struct
> > (struct |  | cell-padding-property (left top right bottom)
> #:extra-constructor-name make-cell-padding-property)
> left : real?
> top : real?
> right : real?
> bottom : real?

When used as a cell property for a table, specifies padding to add around the cell content. Padding is expressed in “ex” units, which corresponds roughly to the width of a character.

Added in version 1.58 of package scribble-lib.

> > struct
> > (struct |  | box-mode (top-name center-name bottom-name)
> #:extra-constructor-name make-box-mode)
> top-name : string?
> center-name : string?
> bottom-name : string?
> procedure (box-mode* name) → box-mode?
> name : string?

As a style property, indicates that a nested flow or paragraph is boxable when it is used in a boxing context for Latex output, but a nested flow is boxable only if its content is also boxable.

A boxing context starts with a table cell in a multi-column table, and the content of a block in a boxing context is also in a boxing context. If the cell’s content is boxable, then the content determines the width of the cell, otherwise a width is imposed. A paragraph with a #f style name is boxable as a single line; the 'wraps style name makes the paragraph non-boxable so that its width is imposed and its content can use multiple lines. A table is boxable when that all of its cell content is boxable.

To generate output in box mode, the box-mode property supplies Latex macro names to apply to the nested flow or paragraph content. The top-name macro is used if the box’s top line is to be aligned with other boxes, center-name if the box’s center is to be aligned, and bottom-name if the box’s bottom line is to be aligned. The box-mode* function creates a box-mode structure with the same name for all three fields.

A box-mode style property overrides any automatic boxed rendering (e.g., for a paragraph with style name #f). If a block has both a box-mode style property and a 'multicommand style property, then the Latex macro top-name, center-name, or bottom-name is applied with a separate argument for each of its content.

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

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

> procedure (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
> > (struct |  | style (name properties)
> #:extra-constructor-name make-style)
> name : (or/c string? symbol? #f)
> properties : list?

Represents a style.

> value plain : style?

A style (make-style #f null).

> procedure (element-style? v) → boolean?
> v : any/c

Returns #t if v is a string, symbol, #f, or style structure.

> procedure (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 non-empty list of serializable? values.

> > struct
> > (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.

> procedure (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).

> procedure (content-width c) → exact-nonnegative-integer?
> c : content?

Returns the width in characters of the given content.

> procedure (block-width e) → exact-nonnegative-integer?
> e : block?

Returns the width in characters of the given block.

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

Return #t if v is #f, an exact non-negative integer, a string, or a list containing two strings. See collected-info for information on how different representations are used for numbering.

Added in version 1.1 of package scribble-lib.

> procedure (numberer? v) → boolean?
> v : any/c
> procedure (make-numberer step initial-value) → numberer?
> | step |  | : |  |
> (any/c (listof part-number-item?)
> . -> .
> (values part-number-item? any/c))
> initial-value : any/c
> > procedure
> > (numberer-step |  | n |  |  |  |
> > |  | parent-number |  |  |  |
> > |  | ci |  |  |  |
> > |  | numberer-values) |  | → |  |
> > part-number-item? |  | hash?
> n : numberer?
> parent-number : (listof part-number-item?)
> ci : collect-info?
> numberer-values : hash?

A numberer implements a representation of a section number that increment separately from the default numbering style and that can be rendered differently than as Arabic numerals.

The numberer? function returns #t if v is a numberer, or #f otherwise.

The make-numberer function creates a numberer. The step function computes both the current number’s representation and increments the number, where the “number” can be an arbitrary value; the initial-value argument determines the initial value of the “number”, and the step function receives the current value as its first argument and returns an incremented value as its second result. A numberer’s “number” value starts fresh at each new nesting level. In addition to the numberer’s current value, the step function receives the parent section’s numbering (so that its result can depend on the part’s nesting depth).

The numberer-step function is normally used by a renderer. It applies a numberer, given the parent section’s number, a collect-info value, and a hash table that accumulates numberer values at a given nesting layer. The collect-info argument is needed because a numberer’s identity is based on a generated-tag. The result of numberer-step is the rendered form of the current section number plus an updated hash table with an incremented value for the numberer.

Typically, the rendered form of a section number (produced by numberer-step) is a list containing two strings. The first string is the part’s immediate number, which can be combined with a prefix for enclosing parts’ numbers. The second string is a separator that is placed after the part’s number and before a subsection’s number for each subsection. If numberer-step produces a plain string for the rendered number, then it is not added as a prefix to subsection numbers. See also collected-info.

Added in version 1.1 of package scribble-lib.

> > struct
> > (struct |  | link-render-style (mode)
> #:extra-constructor-name make-link-render-style)
> mode : (or/c 'default 'number)

Used as a style property for a part or a specific link-element to control the way that a hyperlink is rendered for a part via secref or for a figure via figure-ref from scriblib/figure.

The 'default and 'number modes represent generic hyperlink-style configurations that could make sense for various kinds of references. The 'number style is intended to mean that a specific number is shown for the reference and that only the number is hyperlinked. The 'default style is more flexible, allowing a more appropriate choice for the rendering context, such as using the target section’s name for a hyperlink in HTML.

Added in version 1.26 of package scribble-lib.

> parameter (current-link-render-style) → link-render-style?
> (current-link-render-style style) → void?
> style : link-render-style?

A parameter that determines the default rendering style for a section link.

When a part has a link-render-style as one of its style properties, then the current-link-render-style parameter is set during the resolve pass and render pass for the part’s content.

Added in version 1.26 of package scribble-lib.

> > struct
> > (struct |  | collect-info | ( | fp
> > |  |  |  | ht
> > |  |  |  | ext-ht
> > |  |  |  | ext-demand
> > |  |  |  | parts
> > |  |  |  | tags
> > |  |  |  | gen-prefix
> > |  |  |  | relatives
> > |  |  |  | parents)
> #:extra-constructor-name make-collect-info)
> fp : any/c
> ht : any/c
> ext-ht : any/c
> ext-demand : (tag? collect-info? . -> . 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
> > (struct |  | resolve-info (ci delays undef searches)
> #:extra-constructor-name make-resolve-info)
> ci : any/c
> delays : any/c
> undef : any/c
> searches : any/c

Encapsulates information accumulated (or being accumulated) from the resolve pass. The fields are exposed, but not currently intended for external use.

> procedure (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.

> procedure (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.

> procedure (resolve-get p ri key) → any/c
> p : (or/c part? #f)
> 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.

> > procedure
> > (resolve-get/ext? p ri key) |  | → |  |
> > any/c |  | boolean?
> p : (or/c part? #f)
> ri : resolve-info?
> key : info-key?

Like resolve-get, but returns a second value to indicate whether the resulting information originated from an external source (i.e., a different document).

> > procedure
> > (resolve-get/ext-id p ri key) |  | → |  |
> > any/c |  | (or/c boolean? string?)
> p : (or/c part? #f)
> ri : resolve-info?
> key : info-key?

Like resolve-get/ext?, but the second result can be a string to indicate the source document’s identification as established via load-xref and a #:doc-id argument.

Added in version 1.1 of package scribble-lib.

> procedure (resolve-search dep-key p ri key) → void?
> dep-key : any/c
> p : (or/c part? #f)
> 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).

The dep-key can be any value, but when it is a pair with #f as its car, then a failed search (possibly after re-builds) is not reported for the key.

Changed in version 1.43 of package scribble-lib: Added the convention to suppress reporting for a dep-key starts with #f.

> procedure (resolve-get/tentative p ri key) → any/c
> p : (or/c part? #f)
> 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.

> procedure (resolve-get-keys p ri pred) → list?
> p : (or/c part? #f)
> 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.

> procedure (part-collected-info p ri) → collected-info?
> p : part?
> ri : resolve-info?

Returns the information collected for p as recorded within ri.

> procedure (current-part-context-accumulation key) → any/c
> key : any/c

Retrieves the accumulated value for a key in the part context for enclosing parts, returning #f if no value has been accumulated for the key.

Added in version 1.54 of package scribble-lib.

> procedure (tag-key t ri) → tag?
> t : tag?
> ri : resolve-info?

Converts a generated-tag value with t to a string.

> procedure (traverse-block-block b i) → block?
> b : traverse-block?
> i : (or/c resolve-info? collect-info?)

Produces the block that replaces b.

> procedure (traverse-element-content e i) → content?
> e : traverse-element?
> i : (or/c resolve-info? collect-info?)

Produces the content that replaces e.

> value block-traverse-procedure/c : contract?

Defined as

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

> value element-traverse-procedure/c : contract?

Defined as

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

#### 6.3.6 HTML Style Properties🔗ℹ

(require scribble/html-properties) | package: scribble-lib

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

> > struct
> > (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
> > (struct |  | alt-tag (name)
> #:extra-constructor-name make-alt-tag)
> name : (and/c string? #rx"^[a-zA-Z0-9]+$")

Used as a style property for an element, paragraph, or compound-paragraph to substitute an alternate HTML tag (instead of <span>, <p>, <div>, etc.).

> > struct
> > (struct |  | column-attributes (assoc)
> #:extra-constructor-name make-column-attributes)
> assoc : (listof (cons/c symbol? string?))

Used as a style property on a style with table-columns to add arbitrary attributes to an HTML col tag within the table.

> > struct
> > (struct |  | link-query-addition (params)
> #:extra-constructor-name make-link-query-addition)
> params : (listof (cons/c symbol? string?))

Used as a style property for an link-element to add query parameters to the link. The params field provides a list of symbol keys and string values, which are added in order to the hyperlink.

Added in version 1.65 of package scribble-lib.

> > struct
> > (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
> > (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
> > (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
> > (struct |  | xexpr-property (before after)
> #:extra-constructor-name make-xexpr-property)
> before : xexpr/c
> after : xexpr/c

Used as a style property with element to supply literal HTML that is rendered before and after element content.

Example:

> #lang scribble/base
> @(require scribble/core
> scribble/html-properties
> (only-in xml cdata))
> @(define comments (xexpr-property
> (cdata #f #f "<!-- before -->")
> (cdata #f #f "<!-- after -->")))
> Here is some
> @elem[#:style (style #f (list comments))]{content with comments around}.

Added in version 1.27 of package scribble-lib.

> > struct
> > (struct |  | css-addition (path)
> #:extra-constructor-name make-css-addition)
> | path |  | : |  |
> (or/c path-string?
> (cons/c 'collects (listof bytes?))
> url?
> bytes?)

Used as a style property to supply a CSS file (if path is a path, string, or list), URL (if path is a url) or content (if path is a byte string) to be referenced or included in the generated HTML. This property can be attached to any style, and all additions are collected and lifted to the enclosing generated HTML. When the style property is attached to a part, then it is also propagated to any generated HTML for a subpart of the part.

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

> > struct
> > (struct |  | css-style-addition (path)
> #:extra-constructor-name make-css-style-addition)
> | path |  | : |  |
> (or/c path-string?
> (cons/c 'collects (listof bytes?))
> url?
> bytes?)

Like css-addition, but added after any style files that are specified by a document and before any style files that are provided externally.

> > struct
> > (struct |  | js-addition (path)
> #:extra-constructor-name make-js-addition)
> | path |  | : |  |
> (or/c path-string?
> (cons/c 'collects (listof bytes?))
> url?
> bytes?)

Like css-addition, but for a JavaScript file instead of a CSS file.

> > struct
> > (struct |  | js-style-addition (path)
> #:extra-constructor-name make-js-style-addition)
> | path |  | : |  |
> (or/c path-string?
> (cons/c 'collects (listof bytes?))
> url?
> bytes?)

Like css-style-addition, but for a JavaScript file instead of a CSS file.

> > struct
> > (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 within a main part.

> > struct
> > (struct |  | document-source (module-path)
> #:extra-constructor-name make-document-source)
> module-path : module-path?

Used as a style property to associate a module path with a part. Clicking on a section title within the part may show module-path with the part’s tag string, so that authors of other documents can link to the section.

More specifically, the section title is given the HTML attributes x-source-module and x-part-tag, plus x-part-prefixes if the section or enclosing sections declare tag prefixes, and x-source-pkg if the source is found within a package at document-build time. The scribble/manual style recognizes those tags to make clicking a title show cross-reference information.

Added in version 1.2 of package scribble-lib.
Changed in version 1.7: Added x-part-prefixes.
Changed in version 1.9: Added x-source-pkg.

> > struct
> > (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.

> > struct
> > (struct |  | head-extra (xexpr)
> #:extra-constructor-name make-head-extra)
> xexpr : xexpr/c

For a part that corresponds to an HTML page, adds content to the <head> tag.

> > struct
> > (struct |  | head-addition (xexpr)
> #:extra-constructor-name make-head-addition)
> xexpr : xexpr/c

Like head-extra in content, but propagated to enclosing and nested HTML pages like css-addition. Additions to <head> via head-addition appear before additions via head-extra.

Added in version 1.38 of package scribble-lib.

> > struct
> > (struct |  | initial-scale (value)
> #:extra-constructor-name make-initial-scale)
> value : (real-in 0.0 10.0)

Adjusts initial-scale in a meta tag with name viewport. The default is 1.0.

Added in version 1.61 of package scribble-lib.

> > struct
> > (struct |  | render-convertible-as (types)
> #:extra-constructor-name make-render-convertible-as)
> types : (listof (or/c 'png-bytes 'svg-bytes 'gif-bytes))

For a part that corresponds to an HTML page, controls how objects that subscribe to the file/convertible protocol are rendered.

The alternatives in the types field are tried in order and the first one that succeeds is used in the html output.

Changed in version 1.34 of package scribble-lib: Added support for 'gif-bytes.

> > struct
> > (struct |  | part-link-redirect (url)
> #:extra-constructor-name make-part-link-redirect)
> url : url?

As a style property on a part, causes hyperiinks to the part to be redirected to url instead of the rendered part.

> > struct
> > (struct |  | part-title-and-content-wrapper (tag attribs)
> #:extra-constructor-name make-part-title-and-content-wrapper)
> tag : string?
> attribs : (listof (list/c symbol? string?))

Used as a style property on a part to add a tag with attributes around a part title and its content that is rendered on the same HTML page.

Added in version 1.49 of package scribble-lib.

> > struct
> > (struct |  | link-resource (path)
> #:extra-constructor-name make-link-resource)
> path : path-string?

As a style property on an element, causes the elements to be rendered as a hyperlink to (a copy of) path.

The file indicated by path is referenced in place when render<%> is instantiated with refer-to-existing-files as true. Otherwise, it is copied to the destination directory and potentially renamed to avoid conflicts.

> > struct
> > (struct |  | install-resource (path)
> #:extra-constructor-name make-install-resource)
> path : path-string?

Like link-resource, but makes path accessible in the destination without rendering a hyperlink.

This style property is useful only when render<%> is instantiated with refer-to-existing-files as #f, and only when path does not match then name of any other file that is copied by the renderer to the destination.

#### 6.3.7 Latex Style Properties🔗ℹ

(require scribble/latex-properties) | package: scribble-lib

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

> > struct
> > (struct |  | tex-addition (path)
> #:extra-constructor-name make-tex-addition)
> | path |  | : |  |
> (or/c path-string?
> (cons/c 'collects (listof bytes?))
> bytes?)

Used as a style property to supply a ".tex" file (if path is a path, string, or list) or content (if path is a byte string) 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
> > (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 --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. With scribble/base, not specifying a latex-defaults struct is equivalent to using this one:

> (latex-defaults
> (list 'collects #"scribble" #"scribble-prefix.tex")
> (list 'collects #"scribble" #"scribble-style.tex")
> '())

See also scribble/latex-prefix.

> > struct
> > (struct |  | latex-defaults+replacements latex-defaults (replacements)
> #:extra-constructor-name make-latex-defaults+replacements)
> | replacements |  | : |  |
> (hash/c string? (or/c bytes? path-string?
> (cons/c 'collects (listof bytes?))))

Like latex-defaults but it allows for more configuration.

For example if the replacements maps "scribble-load-replace.tex" to "my-scribble.tex", then the "my-scribble.tex" file in the current directory will be used in place of the standard scribble package inclusion header. Using "scribble-load-replace.tex" can disable the use of possibly-conflicting packages in the LaTeX output. The file (collection-file-path "scribble" "scribble.tex") contains a number of macros of the form \packageMathabx that will, by default, load the corresponding packages. Use a "scribble-load-replace.tex" replacement with content like #"\\renewcommand{\\packageMathabx}{\\relax}\n" to disable the loading of those packages.

> > struct
> > (struct |  | command-extras (arguments)
> #:extra-constructor-name make-command-extras)
> arguments : (listof string?)

Used as a style property on an element to add extra arguments to the element’s command in Latex output.

> > struct
> > (struct |  | command-optional (arguments)
> #:extra-constructor-name make-command-optional)
> arguments : (listof string?)

Used as a style property on a element to add optional arguments to the element’s command in Latex output.

Added in version 1.20 of package scribble-lib.

> > struct
> > (struct |  | short-title (text)
> #:extra-constructor-name make-short-title)
> text : (or/c string? #f)

Used as a style property on a title-decl. Attaches a short title to the title for a part if the Latex class file uses a short title.

Added in version 1.20 of package scribble-lib.

> > struct
> > (struct |  | table-row-skip (amount)
> #:extra-constructor-name make-table-row-skip)
> amount : string?

Used as a style property in table-cells to specify a spacing adjustment between the cell’s row and the row afterward, such as "1ex" to increase the space or "-1ex" to decrease it. If multiple cells on a row provide this property, the first one in the row is used.

Added in version 1.33 of package scribble-lib.

top contents ← prev up next →