allow lists of pre-content to `decode-content', etc.

and improve docs for `scribble/decode'

collects/scribble/decode.rkt

@@ -8,19 +8,21 @@
 
 (define (pre-content? i)
   (or (string? i)
-      (and (content? i)
+      (content? i)
-           (not (list? 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)
+      (content? i)
-           (not (list? 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)))
+	     (or (splice? (cadr l))
-	(loop (cons (car l) (append (splice-run (cadr l)) (cddr 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)))
 

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
+@elemtag['(decode "rules")]{At} the @tech{content} level, decoding
-special text conversions:
+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],
+string or other non-list @tech{content}, a @racket[block],
-@|void-const|, or a @racket[splice] containing a list of
+@|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
+Decodes a document, producing a part. In @racket[lst], lists and instances of
-@racket[splice] are inlined into the list. An instance 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
+Decodes a flow. In @racket[lst], lists and instances of
-whitespace counts is parsed as a paragraph separator. In @racket[lst],
+@racket[splice] are inlined into the list. A sequence of two or more
-instances of @racket[splice] are inlined into the list. Instances of
+newlines separated only by whitespace is parsed as a
-@racket[paragraph] and other flow-element datatypes are used as-is in
+compound-paragraph separator.
-the enclosing flow.
+
+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
+Decodes a compound paragraph. In @racket[lst], lists and instances of
-single block, the block is returned without a
+@racket[splice] are inlined into the list. Instances of
-@racket[compound-paragraph] wrapper.
+@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.}
-