commit f60f217aaed16ab3953fd29b6a5408a9503a2396
parent 19221251c7cc879ebe34789723319fd2967e2517
Author: Matthew Flatt <mflatt@racket-lang.org>
Date: Wed, 6 Jul 2011 09:06:53 -0600
allow lists of pre-content to `decode-content', etc.
and improve docs for `scribble/decode'
original commit: d8352d5890b3817db5bae24c85cc57cf6a25401a
Diffstat:
2 files changed, 62 insertions(+), 50 deletions(-)
diff --git a/collects/scribble/decode.rkt b/collects/scribble/decode.rkt
@@ -8,19 +8,21 @@
(define (pre-content? i)
(or (string? i)
- (and (content? i)
- (not (list? i)))
+ (content? i)
(and (splice? i)
(andmap pre-content? (splice-run i)))
+ (and (list? i)
+ (andmap pre-content? i))
(void? i)))
(define (pre-flow? i)
(or (string? i)
- (and (content? i)
- (not (list? i)))
+ (content? i)
(block? i)
(and (splice? i)
(andmap pre-flow? (splice-run i)))
+ (and (list? i)
+ (andmap pre-flow? i))
(void? i)))
(define (pre-part? v)
@@ -32,7 +34,9 @@
(part-tag-decl? v)
(part? v)
(and (splice? v)
- (andmap pre-part? (splice-run v)))))
+ (andmap pre-part? (splice-run v)))
+ (and (list? v)
+ (andmap pre-part? v))))
(provide-structs
[title-decl ([tag-prefix (or/c false/c string?)]
@@ -224,6 +228,9 @@
[(splice? (car l))
(loop (append (splice-run (car l)) (cdr l))
next? keys colls accum title tag-prefix tags vers style)]
+ [(list? (car l))
+ (loop (append (car l) (cdr l))
+ next? keys colls accum title tag-prefix tags vers style)]
[(null? (cdr l))
(loop null #f keys colls (cons (car l) accum) title tag-prefix tags
vers style)]
@@ -239,8 +246,9 @@
(append tags (list (part-tag-decl-tag (car l))))
vers style)]
[(and (pair? (cdr l))
- (splice? (cadr l)))
- (loop (cons (car l) (append (splice-run (cadr l)) (cddr l)))
+ (or (splice? (cadr l))
+ (list? (cadr l))))
+ (loop (cons (car l) (append ((if (splice? (cadr l)) splice-run values) (cadr l)) (cddr l)))
next? keys colls accum title tag-prefix tags vers style)]
[(line-break? (car l))
(if next?
@@ -278,6 +286,8 @@
[(line-break? (car l)) (skip-whitespace l)]
[(splice? (car l))
(match-newline-whitespace (append (splice-run (car l)) (cdr l)))]
+ [(list? (car l))
+ (match-newline-whitespace (append (car l) (cdr l)))]
[(whitespace? (car l)) (match-newline-whitespace (cdr l))]
[else #f]))
@@ -299,6 +309,7 @@
[(string? s) (decode-string s)]
[(void? s) null]
[(splice? s) (decode-content (splice-run s))]
+ [(list? s) (decode-content s)]
[else (list s)]))
(skip-whitespace l)))
diff --git a/collects/scribblings/scribble/decode.scrbl b/collects/scribblings/scribble/decode.scrbl
@@ -13,8 +13,8 @@ At the @tech{flow} level, decoding recognizes a blank line as a
@tech{paragraph} separator. Blocks and paragraphs without blank lines
in between are collected into a @tech{compound paragraph}.
-At the @tech{content} level, decoding makes just a few
-special text conversions:
+@elemtag['(decode "rules")]{At} the @tech{content} level, decoding
+makes just a few special text conversions:
@itemize[
@@ -45,7 +45,7 @@ then it is bolded.
@defproc[(pre-content? [v any/c]) boolean?]{
Returns @racket[#t] if @racket[v] is a @deftech{pre-content} value: a
-string or other non-list @racket[content], or a @racket[splice]
+string or other non-list @tech{content}, a list of @tech{pre-content} values, or a @racket[splice]
containing a list of @tech{pre-content} values; otherwise returns
@racket[#f].
@@ -56,8 +56,8 @@ Pre-content is decoded into @tech{content} by functions like
@defproc[(pre-flow? [v any/c]) boolean?]{
Returns @racket[#t] if @racket[v] is a @deftech{pre-flow} value: a
-string or other non-list @racket[content], a @racket[block],
-@|void-const|, or a @racket[splice] containing a list of
+string or other non-list @tech{content}, a @racket[block],
+@|void-const|, a list of @tech{pre-flow} values, or a @racket[splice] containing a list of
@tech{pre-flow} values; otherwise returns @racket[#f].
Pre-flow is decoded into a @tech{flow} (i.e., a list of @tech{blocks})
@@ -70,7 +70,7 @@ Returns @racket[#t] if @racket[v] is a @deftech{pre-part} value: a
string or other non-list @tech{content}, a @tech{block}, a
@racket[part], a @racket[title-decl], a @racket[part-start], a
@racket[part-index-decl], a @racket[part-collect-decl], a
-@racket[part-tag-decl], @|void-const|, or a @racket[splice] containing
+@racket[part-tag-decl], @|void-const|, a list of @tech{pre-part} values, or a @racket[splice] containing
a list of @tech{pre-part} values; otherwise returns @racket[#f].
A pre-part sequence is decoded into a @racket[part] by functions like
@@ -79,8 +79,8 @@ A pre-part sequence is decoded into a @racket[part] by functions like
@defproc[(decode [lst (listof pre-part?)]) part?]{
-Decodes a document, producing a part. In @racket[lst], instances of
-@racket[splice] are inlined into the list. An instance of
+Decodes a document, producing a part. In @racket[lst], lists and instances of
+@racket[splice] are inlined into the list, and @|void-const|s are dropped. An instance of
@racket[title-decl] supplies the title for the part, plus tag, style
and version information. Instances of @racket[part-index-decl] (that
precede any sub-part) add index entries that point to the
@@ -90,7 +90,10 @@ of @racket[part-tag-decl] add hyperlink tags to the section
title. Instances of @racket[part-start] at level 0 trigger sub-part
parsing. Instances of @racket[section] trigger are used as-is as
subsections, and instances of @racket[paragraph] and other
-flow-element datatypes are used as-is in the enclosing flow.}
+flow-element datatypes are used as-is in the enclosing flow.
+
+Portions of @racket[lst] are within a part are decoded using
+@racket[decode-flow].}
@defproc[(decode-part [lst (listof pre-part?)]
@@ -108,52 +111,57 @@ parsing.
@defproc[(decode-flow [lst (listof pre-flow?)]) (listof block?)]{
-Decodes a flow. A sequence of two or more newlines separated only by
-whitespace counts is parsed as a paragraph separator. In @racket[lst],
-instances of @racket[splice] are inlined into the list. Instances of
-@racket[paragraph] and other flow-element datatypes are used as-is in
-the enclosing flow.
+Decodes a flow. In @racket[lst], lists and instances of
+@racket[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 @racket[lst] are within a compound paragraph are decoded using
+@racket[decode-compound-paragraph].}
-}
@defproc[(decode-compound-paragraph [lst (listof pre-flow?)]) block?]{
-Decodes a compound paragraph. If the compound paragraph contains a
-single block, the block is returned without a
-@racket[compound-paragraph] wrapper.
+Decodes a compound paragraph. In @racket[lst], lists and instances of
+@racket[splice] are inlined into the list. Instances of
+@racket[paragraph] and other @tech{block} datatypes are used as-is in
+the result. If the compound paragraph contains a single block, the
+block is returned without a @racket[compound-paragraph] wrapper.
+
+Portions of @racket[lst] that are separated by @tech{block}s are
+decoded using @racket[decode-content].}
-}
@defproc[(decode-paragraph [lst (listof pre-content?)]) paragraph?]{
-Decodes a paragraph.
+Decodes a paragraph using @racket[decode-content] to decode
+@racket[lst] as the paragraph's content.}
-}
@defproc[(decode-content [lst (listof pre-content?)]) list?]{
-Decodes @tech{content}.
+Decodes @tech{content}. Lists and splices in @racket[lst] are
+flattened into the list. Plain strings are @elemref['(decode
+"rules")]{decoded}; non-string, non-list @tech{content} is included in
+the result as-is.}
-}
@defproc[(decode-elements [lst (listof pre-content?)]) list?]{
-An alias for @racket[decode-content].
-}
+An alias for @racket[decode-content].}
+
@defproc[(decode-string [s string?]) (listof content?)]{
-Decodes a single string to produce @tech{content}.
-
-}
+@elemref['(decode "rules")]{Decodes} a single string to produce
+@tech{content}.}
@defproc[(whitespace? [s string?]) boolean?]{
Returns @racket[#t] if @racket[s] contains only whitespace, @racket[#f]
-otherwise.
+otherwise.}
-}
@defstruct[title-decl ([tag-prefix (or/c #f string?)]
[tags (listof string?)]
@@ -163,9 +171,8 @@ otherwise.
See @racket[decode] and @racket[decode-part]. The @racket[_tag-prefix]
and @racket[_style] fields are propagated to the resulting
-@racket[part].
+@racket[part].}
-}
@defstruct[part-start ([depth integer?]
[tag-prefix (or/c #f string?)]
@@ -174,37 +181,31 @@ and @racket[_style] fields are propagated to the resulting
[title content?])]{
Like @racket[title-decl], but for a sub-part. See @racket[decode] and
-@racket[decode-part].
+@racket[decode-part].}
-}
@defstruct[part-index-decl ([plain-seq (listof string?)]
[entry-seq list?])]{
-See @racket[decode]. The two fields are as for @racket[index-element].
+See @racket[decode]. The two fields are as for @racket[index-element].}
-}
@defstruct[part-collect-decl ([element element?])]{
-See @racket[decode].
+See @racket[decode].}
-}
@defstruct[part-tag-decl ([tag tag?])]{
-See @racket[decode].
+See @racket[decode].}
-}
@defstruct[splice ([run list?])]{
-See @racket[decode], @racket[decode-part], and @racket[decode-flow].
+See @racket[decode], @racket[decode-part], and @racket[decode-flow].}
-}
@defproc[(clean-up-index-string [str string?]) string?]{
Trims leading and trailing whitespace, and converts non-empty
sequences of whitespace to a single space character.}
-
