@@ -11,19 +11,20 @@
           scribble/example)
 
 @(require (for-label "../pollen.rkt"
                      "../dust.rkt"
                      racket/base
+                     racket/contract
                      txexpr
                      sugar/coerce
                      pollen/tag
                      pollen/setup
                      pollen/pagetree
                      pollen/core))
 
 @(define dust-eval (make-base-eval))
-@(dust-eval '(require "dust.rkt"))
+@(dust-eval '(require "dust.rkt" txexpr))
 
 @title{@filepath{dust.rkt}}
 
 @defmodule["dust.rkt" #:packages ()]
 
@@ -73,34 +74,75 @@
 Look up a value in @code{(current-metas)} that may or may not be present, returning the value of
 @racket[_missing-expr] if it’s not there.
 
 @defproc[(tx-strs [tx txexpr?]) string?]
 
-Finds all the strings from the @emph{elements} of @racket[_tx] (ignoring attributes) and concatenates them together.
+Finds all the strings from the @emph{elements} of @racket[_tx] (ignoring attributes) and
+concatenates them together.
 
 @examples[#:eval dust-eval
 (tx-strs '(p [[class "intro"]] 
              (em "I’m not opening the safe") ", Wilson remembers thinking."))]
 
-@defproc[(first-words [str string?] [n exact-nonnegative-integer?]) string?]
+@defproc[(make-tag-predicate [sym symbol?]) (-> any/c boolean?)]
+
+Returns a function (or @italic{predicate}) that returns @racket[#t] if its argument is
+a @racket[_txexpr] whose tag is @racket[_sym]. This predicate is useful for passing as the
+@racket[_pred] expression in functions @racket[splitf-txexpr] and @racket[findf-txexpr].
+
+@examples[#:eval dust-eval
+(define is-aside? (make-tag-predicate 'aside))
+
+(is-aside? '(q "I am not mad, Sir Topas. I say to you this house is dark."))
+(is-aside? '(aside "How smart a lash that speech doth give my Conscience?"))]
+
+@defproc[(first-words [txprs (listof txexpr?)] [n exact-nonnegative-integer?]) string?]
+
+Given a list of tagged X-expressions, returns a string containing the first @racket[_n] words found
+in the string elements of @racket[_txprs], or all of the words if there are less than @racket[_n]
+words available. Used by @racket[default_title].
 
-Returns a string containing the first @racket[_n] words of @racket[_str], removing any trailing
-punctuation. It will trip on opening punctuation or punctuation surrounded by spaces.
+This function aims to be smart about punctuation, and equally fast no matter how large the list of
+elements that you send it.
 
 @examples[#:eval dust-eval
-(first-words "Another time, perhaps." 2)
-(first-words "‘One problem’ – it don’t always do punctuation right." 3)]
+(define txs-decimals
+  '((p "Four score and 7.8 years ago — our fathers etc etc")))
+(define txs-punc-and-split-elems
+  '((p "“Stop!” she called.") (p "(She was never one to be silent.)")))
+(define txs-dashes
+  '((p [[class "newthought"]] (span [[class "smallcaps"]] "One - and") " only one.")
+    (p "That was all she would allow.")))
+(define txs-parens-commas
+    '((p "She counted (" (em "one, two") "— silently, eyes unblinking")))
+(define txs-short
+  '((span "Not much here!")))
+
+(first-words txs-decimals 5)
+(first-words txs-punc-and-split-elems 5)
+(first-words txs-dashes 5)
+(first-words txs-parens-commas 5)
+(first-words txs-short 5)
+]
 
 @section{Article parsers and helpers}
 
-@defproc[(default-title [date string?]) string?]
+@defproc[(default-title [body-txprs (listof txexpr?)]) string?]
+
+Given a list of tagged X-expressions (the elements of an article’s doc, e.g.), returns a string
+containing a suitable title for the document. (Uses @racket[first-words].)
 
 Titles are not required for articles, but there are contexts where you need something that
 serves as a title if one is not present, and that’s what this function supplies.
 
 @examples[#:eval dust-eval
-(default-title "2018-02-19")]
+(define doc 
+  '(root (p "If I had been astonished at first catching a glimpse of so outlandish an "
+            "individual as Queequeg circulating among the polite society of a civilized "
+            "town, that astonishment soon departed upon taking my first daylight "
+            "stroll through the streets of New Bedford…")))
+(default-title (get-elements doc))]
 
 @defproc[(series-pagenode) pagenode?]
 
 If @code{(current-metas)} has the key @racket['series], converts its value to the pagenode pointing to
 that series, otherwise returns @racket['||].