6 Decoding Text

(require scribble/decode)

The scribble/decode library helps you write document content in a natural way – more like plain text, except for @ escapes. Roughly, it processes a stream of strings to produces instances of the scribble/struct datatypes (see Structures And Processing).

At the flow level, decoding recognizes a blank line as a paragraph separator. At the paragraph-content level, decoding makes just a few special text conversions:

• ---: converted to 'mdash, which the HTML render outputs as an en-dash surrounded by space (so don’t put spaces around --- in a document)

• --: converted to 'ndash

• ``: converted to 'ldquo, which is fancy open quotes: “

• '': converted to 'rdquo, which is fancy closing quotes: ”

• ': converted to 'rsquo, which is a fancy apostrophe: ’

Some functions decode a sequence of pre-flow or pre-content arguments using decode-flow or decode-content, respectively. For example, the bold function accepts any number of pre-content arguments, so that in

@bold{``apple''}

the ``apple'' argument is decoded to use fancy quotes, and then it is bolded.

(decode lst) → part?

lst : list?

Decodes a document, producing a part. In lst, instances of splice are inlined into the list. An instance of title-decl supplies the title for the part, plus tag, style and version information. Instances of part-index-decl (that precede any sub-part) add index entries that point to the section. Instances of part-collect-decl add elements to the part that are used only during the collect pass. Instances of part-tag-decl add hyperlink tags to the section title. Instances of part-start at level 0 trigger sub-part parsing. Instances of section trigger are used as-is as subsections, and instances of paragraph and other flow-element datatypes are used as-is in the enclosing flow.

(decode-part lst tags title depth) → part?

lst : list?

tags : (listof string?)

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

depth : excat-nonnegative-integer?

Like decode, but given a list of tag string for the part, a title (if #f, then a title-decl instance is used if found), and a depth for part-starts to trigger sub-part parsing.

(decode-flow lst) → flow?

lst : list?

Decodes a flow. A sequence of two or more newlines separated only by whitespace counts is parsed as a paragraph separator. In lst, instances of splice are inlined into the list. Instances of paragraph and other flow-element datatypes are used as-is in the enclosing flow.

(decode-paragraph lst) → paragraph?

lst : list?

Decodes a paragraph.

(decode-content lst) → list?

lst : list?

Decodes a sequence of elements.

(decode-elements lst) → list?

lst : list?

An alias for decode-content.

(decode-string s) → list?

s : string?

Decodes a single string to produce a list of elements.

(whitespace? s) → boolean?

s : string?

Returns #t if s contains only whitespace, #f otherwise.

(struct title-decl (tag-prefix tags version style content))

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

tags : (listof string?)

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

style : any/c

content : list?

See decode and decode-part. The tag-prefix and style fields are propagated to the resulting part.

(struct part-start (depth tag-prefix tags style title))

depth : integer?

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

tags : (listof string?)

style : any/c

title : list?

Like title-decl, but for a sub-part. See decode and decode-part.

(struct part-index-decl (plain-seq entry-seq))

plain-seq : (listof string?)

entry-seq : list?

See decode. The two fields are as for index-element.

(struct part-collect-decl (element))

element : element?

See decode.

(struct part-tag-decl (tag))

tag : tag?

See decode.

(struct splice (run))

run : list?

See decode, decode-part, and decode-flow.

(clean-up-index-string str) → string?

str : string?

Trims leading and trailing whitespace, and converts non-empty sequences of whitespace to a single space character.