◊(Local Yarn Code "Diff")

#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")
@(require "scribble-helpers.rkt"
          racket/runtime-path
          (for-label racket/base
                     "../crystalize.rkt"))

@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.


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.

If you’re viewing these notes on the Fossil repository, 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. Links on those pages that lead outside of that domain will not work within
this repo’s “Code Docs” frame, due to the repository’s
@ext-link["https://content-security-policy.com"]{content security policy}. To follow such links,
right-click and open the link in a new tab or window.
@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}.
}

Here’s a rough diagram showing how the @tt{.rkt} modules in this project relate to each other, and
to the Pollen source documents. This is the least complex system I could devise that would @tt{A)}
implement everything I want in my @secref["design-goals"], @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. 

@(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,
@seclink["pollen-rkt"]{@filepath{pollen.rkt}} to source documents and templates. The orange lines
highlight the provision and use of the functions in
@seclink["crystalize-rkt"]{@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 @racket[parse-and-cache-article!] from within
their template. Likewise, series pages cache themselves with a call to @racket[cache-series!] from
within their 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.

@local-table-of-contents[]

@include-section["overview.scrbl"]
@include-section["tour.scrbl"]
@include-section["design.scrbl"]
@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"]