2.3 Decoding Parts, Flow Blocks, and Content
Scribble decoding processes a sequence of string literals and other values to produce a part, flow, or content.
The body of a
#lang rhombus/scribble
module, for example, contains a sequence of string literals and calls to
functions like section, tabular, or elem.
As explained in Notation, the module body starts in text
mode, so it is parsed as text literals except as escaped via
@. Any definitions or declarations in the module body—
Decoding a module body starts in part mode, then it decodes portions with a part (and not in subparts) in flow mode, and then text literals within a flow block are decoded in content mode.
2.3.1 Part Decoding Mode
In part mode, each PartDecl in a sequence of values designates a part or subpart, while the result of title is used for the overall enclosing part created by the module body. The result of section designates an immediate subpart, the result of subsection designates a subsubpart within the subpart, and so on.
All values between the start of a part and the start of its first subpart are decoded in flow mode to determine the part’s flow.
2.3.2 Flow Decoding Mode
In flow mode, decoding recognizes a blank line as a paragraph separator, and all non-block values between such separates are collected into a paragraph. An immediate #void or one nested in a list is discarded.
Blocks created by functions like nested and tabular become immediate blocks in the flow, except that flow blocks (and decoded paragraphs) without a blank line in between are collected into a compound paragraph.
A sequence of values to be combined into a paragraph are decoded in content mode.
Functions that accept PreFlow arguments, such as para, use flow mode on sequences of literal-string arguments after flattening nested lists.
2.3.3 Content Decoding Mode
In content mode, decoding perform a handful of special text conversions:
---: converted to a em dash, — (U+2014).
---: converted to a en dash, – (U+2013).
``: converted to curly open double-quotes, “ (U+201C).
'': converted to curly close double-quotes, ” (U+201D).
': converted to curly open single-quote, ‘ (U+2018).
': converted to curly close single-quote or apostrophe, ’ (U+2019).
Functions that accept PreContent arguments, such as italic or elem, use content mode on sequences of literal-string arguments after flattening nested lists. Note that literal does not teat its argument that way. For example, in
@bold{``apple''}
the “apple” argument is decoded to use curly quotes, and then it is bolded.