►Scribble:   The Racket Documentation Tool
▼6 Low-Level Scribble API
On this page:
pre-content?
pre-flow?
pre-part?
decode
decode-part
decode-flow
decode-compound-paragraph
decode-paragraph
decode-content
decode-elements
decode-string
whitespace?
title-decl
part-start
part-index-decl
title-decl*
part-start*
part-index-decl*
part-collect-decl
part-tag-decl
splice
spliceof
clean-up-index-string
decode-current-language-family
  top  contents    up   

6.5 Decoding Text🔗ℹ

 (require scribble/decode) package: scribble-lib
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 Compatibility Structures And Processing).

At the flow level, decoding recognizes a blank line as a paragraph separator. Blocks and paragraphs without blank lines in between are collected into a compound paragraph.

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

procedure

(pre-content? v) → boolean?

  v : any/c
Returns #t if v is a pre-content value: a string or other non-list content, a list of pre-content values, or a splice containing a list of pre-content values; otherwise returns #f.

Pre-content is decoded into content by functions like decode-content and decode-paragraph.

procedure

(pre-flow? v) → boolean?

  v : any/c
Returns #t if v is a pre-flow value: a string or other non-list content, a block, #<void>, a list of pre-flow values, or a splice containing a list of pre-flow values; otherwise returns #f.

Pre-flow is decoded into a flow (i.e., a list of blocks) by functions like decode-flow.

procedure

(pre-part? v) → boolean?

  v : any/c
Returns #t if v is a pre-part value: a string or other non-list content, a block, a part, a title-decl, a part-start, a part-index-decl, a part-collect-decl, a part-tag-decl, #<void>, a list of pre-part values, or a splice containing a list of pre-part values; otherwise returns #f.

A pre-part sequence is decoded into a part by functions like decode and decode-part.

procedure

(decode lst) → part?

  lst : (listof pre-part?)
Decodes a document, producing a part. In lst, lists and instances of splice are inlined into the list, and #<void>s are dropped. 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.

As a part is decoded, as long as the style for the part does not include the style property 'hidden or 'no-index, an entry is added to the document index for the part’s title. See also decode-current-language-family.

Portions of lst are within a part are decoded using decode-flow.

Changed in version 1.25 of package scribble-lib: Added 'no-index support.

procedure

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

  lst : (listof pre-part?)
  tags : (listof string?)
  title : (or/c #f list?)
  depth : exact-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.

procedure

(decode-flow lst) → (listof block?)

  lst : (listof pre-flow?)
Decodes a flow. In lst, lists and instances of splice are inlined into the list. A sequence of two or more newlines separated only by whitespace is parsed as a compound-paragraph separator.

Portions of lst are within a compound paragraph are decoded using decode-compound-paragraph.

procedure

(decode-compound-paragraph lst) → block?

  lst : (listof pre-flow?)
Decodes a compound paragraph. In lst, lists and instances of splice are inlined into the list. Instances of paragraph and other block datatypes are used as-is in the result. If the compound paragraph contains a single block, the block is returned without a compound-paragraph wrapper.

Portions of lst that are separated by blocks are decoded using decode-content.

procedure

(decode-paragraph lst) → paragraph?

  lst : (listof pre-content?)
Decodes a paragraph using decode-content to decode lst as the paragraph’s content.

procedure

(decode-content lst) → list?

  lst : (listof pre-content?)
Decodes content. Elements at the start of the list that are whitespace (according to whitespace?) are dropped. Dropping whitespace in nested lists and splices was a poor implementation choice that is left in place for compatibility. To protect against it, you can exploit the similarly unfortunate fact that an empty list does not count as whitespace. Lists and splices in lst are flattened into the list, similarly dropping leading whitespace. Plain strings are decoded; non-string, non-list content is included in the result as-is.

procedure

(decode-elements lst) → list?

  lst : (listof pre-content?)
An alias for decode-content.

procedure

(decode-string s) → (listof content?)

  s : string?
Decodes a single string to produce content.

procedure

(whitespace? v) → boolean?

  v : any/c
Returns #t if v is a string that contains only whitespace, #f otherwise.

struct

(struct title-decl (tag-prefix tags version style content)
    #:extra-constructor-name make-title-decl)
  tag-prefix : (or/c #f string? hash?)
  tags : (listof tag?)
  version : (or/c string? #f)
  style : style?
  content : content?
See decode and decode-part. The tag-prefix and style fields are propagated to the resulting part. If the version field is not #f, it is propagated as a document-version style property on the part.

struct

(struct part-start (depth tag-prefix tags style title)
    #:extra-constructor-name make-part-start)
  depth : integer?
  tag-prefix : (or/c #f string? hash?)
  tags : (listof tag?)
  style : style?
  title : content?
Like title-decl, but for a sub-part. See decode and decode-part.

struct

(struct part-index-decl (plain-seq entry-seq)
    #:extra-constructor-name make-part-index-decl)
  plain-seq : (listof string?)
  entry-seq : list?
See decode. The two fields are as for index-element.

struct

(struct title-decl* title-decl (desc)
    #:extra-constructor-name make-title-decl*)
  desc : index-desc?

struct

(struct part-start* part-start (desc)
    #:extra-constructor-name make-part-start*)
  desc : index-desc?

struct

(struct part-index-decl* part-index-decl (desc)
    #:extra-constructor-name make-part-index-decl*)
  desc : index-desc?
Like title-decl, part-start, and part-index-decl, but adds an index-entry description to be propagated to the created index-element.

Added in version 1.54 of package scribble-lib.

struct

(struct part-collect-decl (element)
    #:extra-constructor-name make-part-collect-decl)
  element : (or/c element? part-relative-element?)
See decode.

struct

(struct part-tag-decl (tag)
    #:extra-constructor-name make-part-tag-decl)
  tag : tag?
See decode.

struct

(struct splice (run)
    #:extra-constructor-name make-splice)
  run : list?
See decode, decode-part, and decode-flow.

procedure

(spliceof ctc) → flat-contract?

  ctc : flat-contract?
Produces a contract for a splice instance whose run elements satisfy ctc.

procedure

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

parameter

(decode-current-language-family)

 → (parameter/c (or/c #f (listof string?)))
(decode-current-language-family family) → void?
  family : (parameter/c (or/c #f (listof string?)))
 = #f
A parameter that determines how decode creates index entries for document parts. If the parameter value is #f, no language family is associated, otherwise the parameter’s value is used for the 'language-family entry description. See also index-desc.

Added in version 1.54 of package scribble-lib.

  top  contents    up