ADDED code-docs/design.scrbl Index: code-docs/design.scrbl ================================================================== --- code-docs/design.scrbl +++ code-docs/design.scrbl @@ -0,0 +1,38 @@ +#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 and Layout} + +The design and implementation of @italic{The Local Yarn} are guided by a few basic requirements that +have evolved since I started the site in 1999. + +@itemlist[ + @item{@bold{The writing will live in two places: on a web server, and on bookshelves.} 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{Addenda to older writings should be highly visible.} 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 them 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{Finally: everything produced here, both in print and on the web, should look good.}} +] + +@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} +} Index: code-docs/main.scrbl ================================================================== --- code-docs/main.scrbl +++ code-docs/main.scrbl @@ -11,25 +11,61 @@ 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. + +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"] - ADDED code-docs/tour.scrbl Index: code-docs/tour.scrbl ================================================================== --- code-docs/tour.scrbl +++ code-docs/tour.scrbl @@ -0,0 +1,13 @@ +#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 (for-label racket/base)) + +@title{A Tour: Publishing on @italic{The Local Yarn}} + +It’s pretty simple. +