@@ -4,35 +4,46 @@
 @; This file is licensed under the Blue Oak Model License 1.0.0.
 
 @(require "scribble-helpers.rkt")
 
 @(require (for-label "../pollen.rkt"
-                     "../dust.rkt"
                      "../crystalize.rkt"
+                     "../cache.rkt"
                      racket/base
                      racket/contract
                      racket/string
                      txexpr
                      pollen/pagetree))
 
-@title{@filepath{crystalize.rkt}}
+@title[#:tag "crystalize-rkt"]{Crystalize}
 
 @defmodule["crystalize.rkt" #:packages ()]
 
-“Crystalizing” is an extra layer in between docs and templates that destructures the doc and stores
-it in various pieces in a SQLite cache. Individual articles save chunks of rendered HTML to the
-cache when their individual pages are rendered. When pulling together listings of articles in
+“Crystalizing” is an extra layer in between docs and templates that destructures the @tt{doc} and
+stores it in various pieces in a SQLite cache. Individual articles save chunks of rendered HTML to
+the cache when their individual pages are rendered. When pulling together listings of articles in
 different contexts that need to be filtered and sorted, a SQL query is much faster than trolling
 through the Pollen cache for matching docs and regenerating the HTML.
 
-@defproc[(parse-and-cache-article! [pagenode pagenode?] [doc txexpr?]) non-empty-string?]
-
-Returns a string containing the HTML of @racket[_doc]. @margin-note{This is one function that breaks
-my convention of using a prefix of @tt{html$-} for functions that return a single string of HTML.}
-
-Privately, it does a lot of other work. The article is analyzed, additional metadata is constructed,
-and it is saved to the SQLite cache. If the article specifies a @racket['series] meta, information
-about that series is fetched and used in the rendering of the article. If there are @racket[note]s
-in the doc, they are parsed and saved individually to the SQLite cache. If any of the notes use the
-@code{#:disposition} attribute, information about the disposition is parsed out and used in the
-rendering of the article.
-
+@margin-note{These functions are designed to be used within the template for articles and series,
+respectively, so that the cache is updated precisely when the web page is rendered.}
+
+@defproc[(parse-and-cache-article! [pagenode pagenode?] [doc txexpr?]) non-empty-string?]{
+
+Returns a string containing the HTML of @racket[_doc]. 
+
+Privately, it does a lot of other work. The article is analyzed, additional metadata is constructed
+and saved to the SQLite cache and saved using @racket[make-cache:article]. If the article specifies
+a @racket['series] meta, information about that series is fetched and used in the rendering of the
+article. If there are @racket[note]s or @racket[index] tags in the doc, they are parsed and saved
+individually to the SQLite cache (using @racket[make-cache:note] and @racket[make-cache:index-entry]
+respectively). If any of the notes use the @code{#:disposition} attribute, information about the
+disposition is parsed out and used in the rendering of the article.
+}
+
+@defproc[(cache-series!) void?]{
+
+Attempts to look up certain values in @racket[current-metas] which we expect to be defined on
+a typical series page, and saves them to the cache using @racket[make-cache:series]. If @tt{title}
+is not defined in the current metas, you’ll get an error. If any of the others are missing, an empty
+string is used.
+}