From d8352d5890b3817db5bae24c85cc57cf6a25401a Mon Sep 17 00:00:00 2001 From: Matthew Flatt Date: Wed, 6 Jul 2011 09:06:53 -0600 Subject: [PATCH] allow lists of pre-content to `decode-content', etc. and improve docs for `scribble/decode' --- collects/scribble/decode.rkt | 25 +++++-- collects/scribblings/scribble/decode.scrbl | 87 +++++++++++----------- 2 files changed, 62 insertions(+), 50 deletions(-) diff --git a/collects/scribble/decode.rkt b/collects/scribble/decode.rkt index 2c47e30734..2f5f51de2d 100644 --- 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 index 0baa513674..85242d18eb 100644 --- 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.} -