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