@@ -41,10 +41,16 @@
 Creates and initializes the SQLite database cache file (named @filepath{vitreous.sqlite} and located
 in the project root folder) by running queries to create tables in the database if they do not
 exist.
 
 }
+
+@defproc[(preheat-series!) void?]{
+
+Save info about each series in @racket[series-folder] to the cache.
+
+}
 
 @defparam[current-plain-title title-plain non-empty-string? #:value "void"]{
 
 Contains (or sets) the “plain” title (i.e., with no HTML markup) for the current article based on
 analysis done by @racket[parse-and-cache-article!]. If the article did not specify a title,
@@ -71,53 +77,20 @@
 
 ◊title{My New Series}
 
 ...some other content
 
-◊(<listing-excerpt> articles+notes #:order 'asc)
+◊fenced-listing[(articles+notes 'excerpt #:order 'asc)]
 }|
 ]
 
-@deftogether[(@defproc[(<listing-full> 
-                                 [query-func (-> any/c query?)]
-                                 [#:series series (or/c string? (listof string?) boolean?) #t]
-                                 [#:limit limit integer? -1]
-                                 [order stringish? 'desc]) txexpr?]
-              @defproc[(<listing-excerpt>
-                                 [query-func (-> any/c query?)]
-                                 [#:series series (or/c string? (listof string?) boolean?) #t]
-                                 [#:limit limit integer? -1]
-                                 [order stringish? 'desc]) txexpr?]
-              @defproc[(<listing-short>
-                                 [query-func (-> any/c query?)]
-                                 [#:series series (or/c string? (listof string?) boolean?) #t]
-                                 [#:limit limit integer? -1]
-                                 [order stringish? 'desc]) txexpr?])]{
-
-Fetches the HTML for items from the SQLite cache, concatenates their HTML strings and returns
-a @racket['style] tagged X-expression with this string as its element. The items will be ordered by
-publish date according to @racket[_order] and optionally limited to the series specified in
-@racket[_series].
-
-The @racket[_query-func] should be either @racket[articles], which will create a listing of articles
-only, or @racket[articles+notes], which will include notes intermingled with articles.
-
-@margin-note{Note that the signature shown for the @racket[_query-func] argument above is
-incomplete. If you choose to pass a function other than @racket[articles] or
-@racket[articles+notes], you must use a function with exactly the same signature as those
-functions.}
-
-If @racket[_series] expression evaluates to @racket[#f], articles will not be filtered by series. If
-it evaluates to @racket[#t] (the default), articles will be filtered by those that specify the
-current output of @racket[here-output-path] in their @tt{series_pagenode} column in the SQLite
-cache. If a string is supplied, articles will be filtered by those containing that exact value in
-their @tt{series_pagenode} column in the SQLite cache.
-
-The @racket[_order] expression must evaluate to either @racket["ASC"] or @racket["DESC"] and the
-@racket[_limit] expressions must evaluate to a value suitable for use in the @tt{LIMIT} clause of
-@ext-link["https://sqlite.org/lang_select.html"]{a SQLite @tt{SELECT} statement}. An expression that
-evaluates to a negative integer (the default) is the same as having no limit.
+@defproc[(fenced-listing [query query?]) txexpr?]{
+
+Fetches a the HTML strings from the SQLite cache and returns a @racket['style] tagged X-expression
+with these strings as its elements. The @racket[_query] will usually be the result of a call to
+@racket[articles] or @racket[articles+notes], but can be any custom query that projects onto the
+@racket[listing] schema (see @racket[project-onto]).
 
 The reason for enclosing the results in a @racket['style] txexpr is to prevent the HTML from being
 escaped by @racket[->html] in the template. This tag was picked for the job because there will
 generally never be a need to include any actual CSS information inside a @tt{<style>} tag in any
 page, so it can be safely filtered out later. To remove the enclosing @tt{<style>} tag, see
@@ -126,11 +99,13 @@
 }
 
 @defproc[(listing-htmls [listing-query query?]) (listof string?)]{
 
 Returns the HTML bodies for the articles and/or notes returned by @racket[_listing-query] as a list
-of strings.
+of strings. The @racket[_query] will usually be the result of a call to @racket[articles] or
+@racket[articles+notes], but can be any custom query that projects onto the @racket[listing] schema
+(see @racket[project-onto]).
 
 }
 
 @deftogether[(@defproc[(articles [type (or/c 'full 'excerpt 'short)]
                                  [#:series series (or/c string? (listof string?) boolean?) #t]
@@ -139,15 +114,31 @@
               @defproc[(articles+notes [type (or/c 'full 'excerpt 'short)]
                                        [#:series series (or/c string? (listof string?) boolean?) #t]
                                        [#:limit limit integer? -1]
                                        [order stringish? 'desc]) query?])]{
 
-Create a query that fetches either articles only (@racket[articles]) or articles and notes
-intermingled (@racket[articles+notes]), sorted by publish date and optionally limited to
-a particular series.
+Create a query that fetches either articles only, or articles and notes intermingled, respectively.
+The results will be sorted by publish date according to @racket[_order] and optionally limited to
+a particular series. Use the resulting query with the @racket[listing-htmls] or
+@racket[fenced-listing] functions provided by this module, or with deta’s @racket[in-entities] if
+you want to work with the @racket[listing] schema structs.
+
+If @racket[_series] expression evaluates to @racket[#f], articles will not be filtered by series. If
+it evaluates to @racket[#t] (the default), articles will be filtered by those that specify the
+current output of @racket[here-output-path] in their @tt{series_pagenode} column in the SQLite
+cache. If a string or a symbol is supplied, articles will be filtered by those containing the result
+of @racket[(format "series/~a.html" _series)] in their @tt{series_pagenode} column in the SQLite
+cache. If a list of strings or symbols is provided, this @racket[format] operation will be applied
+to each of its members and articles whose @tt{series_pagenode} column matches any of the resulting
+values will be included.
+
+The @racket[_order] expression must evaluate to either @racket["ASC"] or @racket["DESC"] and the
+@racket[_limit] expressions must evaluate to a value suitable for use in the @tt{LIMIT} clause of
+@ext-link["https://sqlite.org/lang_select.html"]{a SQLite @tt{SELECT} statement}. An expression that
+evaluates to a negative integer (the default) is the same as having no limit.
 
-Typically you will pass these functions by name to listing functions like @racket[<listing-full>]
+Typically you will pass these functions by name to listing functions like @racket[fenced-listing]
 rather than calling them directly.
 
 @examples[#:eval example-eval
 (articles 'full)]
 }
@@ -156,18 +147,18 @@
 
 Returns @racket[_html] with all occurrences of @racket["<style>"] and @racket["</style>"] removed.
 The contents of the style tags are left intact.
 
 Use this in templates with strings returned from @racket[->html] when called on docs that use the
-@racket[<listing-full>] tag function or its siblings.
+@racket[fenced-listing] tag function.
 
 }
 
 @defproc[(series-grouped-list) (listof (listof cache:series?))]{
 
 Return a list of lists of all @racket[cache:series] in the cache database. The series are grouped so
-that series using the same value in the @tt{noun-plural} column appear together.
+that series using the same value in the @tt{noun_plural} column appear together.
 
 }
 
 @section{Deleting records}