◊(Local Yarn Code "overview.scrbl at [bd48c56a]")

File code-docs/overview.scrbl artifact 1a4508f5 part of check-in bd48c56a


#lang scribble/manual

@; SPDX-License-Identifier: BlueOak-1.0.0
@; This file is licensed under the Blue Oak Model License 1.0.0.

@(require "scribble-helpers.rkt"
          racket/runtime-path)

@(require (for-label racket/base))

@title{Overview}

@section{Source Code}

Here’s a rough diagram showing how the @tt{.rkt} modules in this project relate to each other, and
to the Pollen source documents.

@(define-runtime-path source-diagram "source-diagram.png")
@centered{@responsive-retina-image[source-diagram]}

The solid-line connections indicate explicit @racket[require] relationships. Dotted arrows generally
indicate implicit exports in the Pollen environment: docs and metas to templates,
@filepath{pollen.rkt} to source documents and templates. The orange lines highlight the provision
and use of the functions in @filepath{crystalize.rkt}.

Individual articles, while they are being rendered to HTML pages, save copies of their metadata and
HTML to the SQLite cache. This is done by calling functions in @filepath{crystalize.rkt} from within
the template.

Any pages that gather content from multiple articles, such as Series pages and the RSS feed, pull
this content directly from the SQLite cache. This is much faster than trawling through Pollen’s
cached metas of every article looking for matching articles.

This is the least complex system I could devise that can @tt{A)} implement everything I want in my
@wiki{Design and Layout}, @tt{B)} cleanly separate dependencies for print and web output, and
@tt{C)} organize an ever-growing collection of hundreds of individual notes and articles without
noticable loss of speed.