Index: .fossil-settings/ignore-glob
==================================================================
--- .fossil-settings/ignore-glob
+++ .fossil-settings/ignore-glob
@@ -3,10 +3,12 @@
*.woff*
x-*/*
*.*~
web-extra/martin.css
scribbled/*
+code-docs/*.css
+code-docs/*.js
*/images/*
*.db
*.sqlite
*.pdf
*.ltx
ADDED code-docs/custom.css
Index: code-docs/custom.css
==================================================================
--- code-docs/custom.css
+++ code-docs/custom.css
@@ -0,0 +1,28 @@
+.fileblock .SCodeFlow {
+ padding-top: 0.7em;
+ margin-top: 0;
+}
+
+.fileblock {
+ width: 90%;
+}
+
+.fileblock_filetitle{
+ background: #eee;
+ text-align:right;
+ padding: 0.15em;
+ border: 1px dotted black;
+ border-bottom: none;
+}
+
+.terminal, .browser {
+ margin-bottom: 1em;
+ padding: 0.5em;
+ width: 88%;
+ background: #fcfcfc;
+ color: rgb(150, 35, 105);
+}
+
+.terminal .SIntrapara, .browser .SIntrapara, .fileblock .SIntrapara {
+ margin: 0 0 0 0;
+}
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"]
-
Index: code-docs/scribble-helpers.rkt
==================================================================
--- code-docs/scribble-helpers.rkt
+++ code-docs/scribble-helpers.rkt
@@ -6,12 +6,17 @@
;; Convenience/helper functions for this project’s Scribble documentation
(require scribble/core
scribble/manual/lang
scribble/html-properties
+ scribble/private/manual-sprop
+ scribble/decode
+ racket/runtime-path
(only-in net/uri-codec uri-encode))
(provide (all-defined-out))
+
+(define-runtime-path custom-css "custom.css")
(define repo-url/ "https://thelocalyarn.com/cgi-bin/yarncode/")
;; Link to a ticket on the Fossil repository by specifying the ticket ID.
;; The "_parent" target breaks out of the iframe used by the Fossil repo web UI.
@@ -43,5 +48,32 @@
(define (responsive-retina-image img-path)
(image img-path
#:scale 0.5
#:style (style #f (list (attributes '((style . "max-width:100%;height:auto;")))))))
+;;
+;; From https://github.com/mbutterick/pollen/blob/master/pollen/scribblings/mb-tools.rkt
+;;
+
+(define (terminal . args)
+ (compound-paragraph (style "terminal" (list (css-style-addition custom-css) (alt-tag "div")))
+ (list (apply verbatim args))))
+
+(define (cmd . args)
+ (elem #:style (style #f (list (color-property "black"))) (tt args)))
+
+(define (fileblock filename . inside)
+ (compound-paragraph
+ (style "fileblock" (list* (alt-tag "div") 'multicommand
+ (box-mode "RfileboxBoxT" "RfileboxBoxC" "RfileboxBoxB")
+ scheme-properties))
+ (list
+ (paragraph (style "fileblock_filetitle" (list* (alt-tag "div") (box-mode* "RfiletitleBox") scheme-properties))
+ (list (make-element
+ (style "fileblock_filename" (list (css-style-addition custom-css)))
+ (if (string? filename)
+ (filepath filename)
+ filename))))
+ (compound-paragraph
+ (style "fileblock_filecontent" (list* (alt-tag "div") (box-mode* "RfilecontentBox") scheme-properties))
+ (decode-flow inside)))))
+
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.
+