#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")

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

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

If you’re browsing these docs from within @italic{The Local Yarn}’s main website, and if you follow
links to other Racket documentation, you’ll find that to @emph{other} sites on those pages will not
work (due to the  @ext-link["https://content-security-policy.com"]{content security policy} in
effect when inside a frame). To follow such links, right-click and open the link in a new tab or
window.

You may also wish to @ext-link["#"]{open this page in its own tab.}}

@section{Yarnian @italic{telos}}

The Local Yarn is my garden: a garden of thinking and code. It’s tailored to my needs as a guy who
likes thinking, writing and publishing, isn’t an expert on anything, misses enchantment, and who
likes things to look nice. It’s a place to experiment and solve problems and be creative on several
levels at once. (You’re looking at one of the lower levels right now.)

Whatever gets done here, the idea is to:

@itemlist[
  @item{Invite and reward exploration; entice the visitor to go @italic{further up and further in}}
  
  @item{Make lush, prolific and expert use of language and typography, even obscure or gratuitous
  variants, purely for their own sake}

  @item{Grow and connect new ideas, and maintain older growth}
  ]

Like a garden, @italic{The Local Yarn} has a particular layout, which is described at all levels of
detail in Design and Layout.

@section{Yarnian @italic{cræft}}

New areas are always being designed and added. I try to do some cyclical planning, but most of it
comes from iterative, deeply lazy, center-building iteration. 

Let’s build on the garden metaphor: this place is groomed like a garden. All the lofty notions above
— creative processes, design principles — are, in the end, underpinned by a stable of imperfect old
tools and machines. Anyone who works on the garden must learn and practice their use, understand how
to maintain them, and (eventually) when to replace them. Details of this maintenance are discussed
in Tools and Methods.


@local-table-of-contents[]

@include-section["tour.scrbl"]
@include-section["design.scrbl"]
@include-section["overview.scrbl"]
@include-section["pollen.scrbl"]  @; pollen.rkt
@include-section["dust.scrbl"]    @; dust.rkt
@include-section["snippets-html.scrbl"] @; you get the idea
@include-section["crystalize.scrbl"]
