Index: code-docs/crystalize.scrbl
==================================================================
--- code-docs/crystalize.scrbl
+++ code-docs/crystalize.scrbl
@@ -74,18 +74,22 @@
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.
-@deftogether[(@defproc[(list-short/articles [#:series series (or/c string? boolean?) #t]
+@deftogether[(@defproc[(listing<>-short/articles [#:series series (or/c string? boolean?) #t]
[#:limit limit stringish? -1]
[order string? "DESC"]) txexpr?]
- @defproc[(list-full/articles [#:series series (or/c string? boolean?) #t]
+ @defproc[(listing<>-full/articles [#:series series (or/c string? boolean?) #t]
[#:limit limit stringish? -1]
[order string? "DESC"]) txexpr?])]
-Fetches the HTML for all articles from the SQLite cache and returns the HTML strings inside
+@margin-note{Notice how the functions that start with @tt{list/} return lists and the functions that
+start with @tt{listing<>} return fenced HTML strings. Maybe this is ugly, but it helps me keep these
+otherwise too-similar sets of functions straight in my head.}
+
+Fetches the HTML for all articles from the SQLite cache and returns the HTML strings fenced inside
a @racket['style] tagged X-expression. The articles will be ordered by publish date according to
@racket[_order] and optionally limited to the series specified in @racket[_series].
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
@@ -102,23 +106,24 @@
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
@racket[unfence].
-@defproc[(list-full/articles+notes [#:series series (or/c string? #f) #f]
+@defproc[(listing<>-full/articles+notes [#:series series (or/c string? #f) #f]
[#:limit limit exact-integer? -1]
[order string? "DESC"]) txexpr?]
-Like @racket[list-full/articles] except that notes and articles are combined side by side in the results.
+Like @racket[listing<>-full/articles] except that notes and articles are combined side by side in
+the results.
@defproc[(unfence [html string?]) string?]
Returns @racket[_html] with all occurrences of @racket["<style>"] and @racket["</style>"] removed.
The contents of the style tags are left intact.
Use this with strings returned from @racket[->html] when called on docs containing
-@racket[list-full/articles] or its siblings.
+@racket[listing<>-full/articles] or its siblings.
@defproc[(article-plain-title [pagenode pagenode?]) non-empty-string?]
Fetches the “plain” title (i.e., with no HTML markup) for the given article from the SQLite cache.
If the article did not specify a title, a default title is supplied. If the article contained
Index: code-docs/pollen.scrbl
==================================================================
--- code-docs/pollen.scrbl
+++ code-docs/pollen.scrbl
@@ -118,12 +118,12 @@
@defproc[(block [element xexpr?] ...) txexpr?]
A container for content that should appear grouped together on larger displays. Intended for use in
Series pages, where the template is very minimal. You would want output from
-@racket[list-short/articles] to appear inside a @racket[block], but you would want output from
-@racket[list-full/articles] to appear outside it (since each article effectively supplies its own
+@racket[listing<>-short/articles] to appear inside a @racket[block], but you would want output from
+@racket[listing<>-full/articles] to appear outside it (since each article effectively supplies its own
block). Only relevant to HTML output.
@deftogether[(@defproc[(link [link-id stringish?] [link-text xexpr?]) txexpr?]
@defproc[(url [link-id stringish?] [url string?]) void?])]
Index: crystalize.rkt
==================================================================
--- crystalize.rkt
+++ crystalize.rkt
@@ -47,13 +47,13 @@
(provide spell-of-summoning!
crystalize-article!
article-plain-title
list/articles
list/articles+notes
- list-short/articles
- list-full/articles
- list-full/articles+notes
+ listing<>-short/articles
+ listing<>-full/articles
+ listing<>-full/articles+notes
unfence
preheat-series!)
;; ~~~ Private use ~~~
@@ -197,20 +197,20 @@
;; ~~~~
;; Return cached HTML of articles and/or notes, fenced within a style txexpr to prevent it being
;; escaped by ->html. See also: definition of `unfence`
-(define (list-short/articles #:series [s #t] #:limit [limit -1] [order "DESC"])
+(define (listing<>-short/articles #:series [s #t] #:limit [limit -1] [order "DESC"])
`(style "<ul class=\"article-list\">"
,@(list/articles "listing_short_html" #:series s #:limit limit order)
"</ul>"))
-(define (list-full/articles #:series [s #t] #:limit [limit -1] [order "DESC"])
+(define (listing<>-full/articles #:series [s #t] #:limit [limit -1] [order "DESC"])
`(style ,@(list/articles "listing_full_html" #:series s #:limit limit order)))
;; Return a combined list of articles and notes (“full content” version) sorted by date
-(define (list-full/articles+notes #:series [s #t] #:limit [limit -1] [order "DESC"])
+(define (listing<>-full/articles+notes #:series [s #t] #:limit [limit -1] [order "DESC"])
`(style ,@(list/articles+notes "listing_full_html" #:series s #:limit limit order)))
;; Remove "<style>" and "</style>" introduced by using ->html on docs containing output from
;; listing functions
(define (unfence html-str)