◊(Local Yarn Code "Check-in [885574b7]")

#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
          (for-label "../pollen.rkt"))

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

@title{Basic Notions}

@section[#:tag "design-goals"]{Design Goals}

 @item{@bold{Changes are part of the content.} I like to revisit, resurface and amend things I’ve
 written before. Views change, new ideas come along. In a typical blog the focus is always at
 whatever’s happening at the head of the time stream; an addendum to an older post is, for all
 practical purposes, invisible and nearly useless. I want every published edit to an article to be
 findable and linkable. I want addenda to be extremely visible. These addenda should also be able to
 mark major shifts in the author’s own perspective on what they originally wrote.}

 @item{@bold{Experimentation must be accomodated gracefully.} I should be able to write fiction,
 poetry, opinion pieces, minor observations or collections, or anything else, and have or create
 a good home for it here. Where dissimilar writings appear together, there should be signals that
 @item{@bold{The system will gracefully accomodate experimentation.} I should be able to write
 fiction, poetry, opinion pieces, minor observations or collections, or anything else, and have or
 create a good home for it here.}
 help the reader understand what they are looking at, switch contexts, and find more if they wish.}
 
 @item{@bold{Everything produced here should look good.}}

 @item{@bold{Reward exploration without disorienting the reader.}}
 @item{@bold{Reward exploration without disorienting the reader.} Draw connections between related
 thoughts using typographic conventions and organizational devices that would be familiar to
 a reader of books. Where dissimilar writings appear together, place signals that help the reader
 understand what they are looking at, switch contexts, and find more if they wish.}
 
 @item{@bold{Everything produced here should be the result of an automatable process.} No clicking
 around to publish web pages and books.}
 @item{@bold{Everything is produced, and reproducible, by an automatable process.} No clicking or
 tapping around in GUI apps to publish web pages and books.}
 
 ]

@section{Names for things and how they fit together}

The Local Yarn is mostly comprised of @tech{articles} (individual writings) which may contain
@tech{notes} (addenda by the author or others) and may also be grouped into @tech{series}. These are

started.

@subsection{Notes}

A @deftech{note} is a comment or addendum to an @tech{article} using the @racket[note] tag. It may
be written by the same person who wrote the article, or submitted by a reader.

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

A note appears at the bottom of the article to which it is attached, but it also appears in the blog
and in the RSS feed as a separate piece of content, and is given the same visual weight as actual
articles.
As shown above, a note appears at the bottom of the article to which it is attached, but it also
appears in the blog and in the RSS feed as a separate piece of content, and is given the same visual
weight as actual articles.

A note may optionally have a @deftech{disposition} which reflects a change in attitude towards its
parent article. A disposition consists of a @italic{disposition mark} such as an asterisk or dagger,
and a past-tense verb. For example, an author may revisit an opinion piece written years earlier and
add a note describing how their opinion has changed; the tag for this note might include
@racket[#:disposition "* recanted"] as an attribute. This would cause the @tt{*} to be added to the
article’s title, and the phrase “Now considered recanted” to be added to the margin, with a link to

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
The modules are arranged vertically: those on the upper rows provide bindings which are used by
those on the lower rows. The bottom row are the @tt{.poly.pm} files that make up @tech{articles} and
@tech{series}.
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