◊(Local Yarn Code "design.scrbl at [e2a5ab96]")

File code-docs/design.scrbl artifact 7f7e48a9 part of check-in e2a5ab96


#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{Design Background}

The design and implementation of @italic{The Local Yarn} are guided by requirements that have
evolved since I started the site in 1999. I enumerate them here because they explain why the code is
necessarily more complicated than a typical blog.

@itemlist[
  @item{@bold{The writing will publish to two places from the same source: the web server, and the
  bookshelf.} The web server, because it’s a fun, fast way to publish writing and code to the whole
  world (you knew that already); but also on bookshelves, because
  @ext-link["https://thelocalyarn.com/excursus/secretary/posts/web-books.html"]{a web server is like
  a projector}, and I want to be able to turn it off someday and still have something to show for
  all my work. Plus, I just like printed books.}

  @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{Everything produced here, both in print and on the web, should look good.}
  @item{@bold{All the output should be produced (and reproducible) by automated processes.} No
  clicking on buttons in apps to publish web pages or books.}
]

@nested[#:style 'inset]{
  “Yet modest ornament with use combined @(linebreak)
  Attracts the eye to exercise the mind.” @(linebreak)
  —@ext-link["https://en.wikipedia.org/wiki/Samuel_Rogers"]{Samuel Rogers}
}