1 How to Scribble Documentation
2 Scribble Layers
3 @-Reader
4 Structures And Processing
5 Renderer
6 Decoding Text
7 Document Language
8 Document Reader
9 Basic Document Forms
10 Scheme
11 Manual Forms
12 Evaluation and Examples
13 BNF Grammars
14 Cross-Reference Utilities
15 Text Preprocessor
Index
On this page:
decode
decode-part
decode-flow
decode-paragraph
decode-content
decode-elements
decode-string
whitespace?
title-decl
part-start
part-index-decl
part-collect-decl
part-tag-decl
splice
clean-up-index-string
Version: 4.0.2

 

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:

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)  (listof flow-element?)

  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.