Index: code-docs/cache.scrbl ================================================================== --- code-docs/cache.scrbl +++ code-docs/cache.scrbl @@ -35,18 +35,22 @@ @defthing[cache-conn connection?]{ The database connection. } @defproc[(init-cache-db!) void?]{ + 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. This function is called automatically in @seclink["pollen-rkt"]{@filepath{pollen.rkt}} whenever HTML -is the target output. } +is the target output. + +} @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, a default title is supplied. If the article contained a @racket[note] that used the @code{#:disposition} attribute, the disposition-mark may be included in the title. @@ -53,10 +57,11 @@ This is a weird parameter, and at some point I will probably get rid of it and have @racket[parse-and-cache-article!] supply it as an extra return value instead. @margin-note{Note that this needs to be called @emph{after} @racket[parse-and-cache-article!] in order to get an up-to-date value.} + } @section{Retrieving cached data} Some of this looks a little wacky, but it’s a case of putting a little extra complextity into the @@ -88,10 +93,11 @@ @defproc[( [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]. @@ -117,15 +123,18 @@ 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{"] 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[] tag function or its siblings. } +@racket[] tag function or its siblings. + +} @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} @deftogether[(@defproc[(delete-article! [page stringish?]) void?] @defproc[(delete-notes! [page stringish?]) void?])]{ + Delete a particular article, or all notes for a particular article, respectively. + } @section{Schema} The cache database has four tables: @tt{articles}, @tt{notes}, @tt{index_entries} and @tt{series}. Each of these has a corresponding schema, shown below. In addition, there is a “virtual” schema, @tt{listing}, for use with queries which may or may not combine articles and notes intermingled. @@ -188,11 +206,13 @@ [disp-html-anchor string/f] [listing-full-html string/f] [listing-excerpt-html string/f] [listing-short-html string/f]) #:constructor-name make-cache:article]{ + Table holding cached article information. + } @defstruct*[cache:note ([id id/f] [page symbol/f] [html-anchor string/f] @@ -207,26 +227,42 @@ [conceal string/f] [listing-full-html string/f] [listing-excerpt-html string/f] [listing-short-html string/f]) #:constructor-name make-cache:note]{ + Table holding cached information on notes. + } @defstruct*[cache:series ([id id/f] [page symbol/f] [title string/f] [published string/f] [noun-plural string/f] [noun-singular string/f]) #:constructor-name make-cache:series]{ + Table holding cached information on series. + } @defstruct*[cache:index-entry ([id id/f] [entry string/f] [subentry string/f] [page symbol/f] [html-anchor string/f]) #:constructor-name make-cache:index-entry]{ + Table holding cached information about index entries found in articles. + +} + +@defstruct*[listing ([html string/f] + [published date/f] + [series-page symbol/f]) + #:constructor-name make-listing]{ + +This is not a table that persists in the cache database; rather it is the schema targeted by +@racket[articles] and @racket[articles+notes] using deta’s @racket[project-onto]. + } Index: code-docs/main.scrbl ================================================================== --- code-docs/main.scrbl +++ code-docs/main.scrbl @@ -6,20 +6,19 @@ @(require "scribble-helpers.rkt" racket/runtime-path (for-label racket/base "../crystalize.rkt")) -@title{Local Yarn: source code notes} +@title{Local Yarn: Source Code Notes} @author{Joel Dueck} These are my notes about the internals of the Local Yarn source code. In other words, a personal -reference, rather than a tutorial. These pages concern only the source code itself. Refer to the -wiki for info about deployment, etc. +reference, rather than a tutorial. You’ll get the most out of these notes if you have read @other-doc['(lib -"pollen/scribblings/pollen.scrbl")], and worked through the tutorials by hand. +"pollen/scribblings/pollen.scrbl")], and worked through the tutorials there by hand. @margin-note{Note that these pages are heavily interlinked with the central Racket documentation at @tt{docs.racket-lang.org}, which are written and maintained by others. Some links from those pages will not work unless you @ext-link["#"]{open this page in its own tab}. @@ -56,6 +55,5 @@ @include-section["pollen.scrbl"] @; pollen.rkt @include-section["dust.scrbl"] @; dust.rkt @include-section["snippets-html.scrbl"] @; you get the idea @include-section["cache.scrbl"] @include-section["crystalize.scrbl"] -