◊(Local Yarn Code "Changes On Branch c7350de07b52c097")

*compiled/*
*.poly.pm
*.woff*
x-*/*
*.*~
web-extra/martin.css
scribbled/*
code-docs/*.css
code-docs/*.js
*/images/*
*.db
*.sqlite
*.pdf
*.ltx
*.html
*.out
*.ltx
*.aux
*.log
*.xml
*.toc
*.mark

.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;
}

#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}
}

@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"]

#lang racket/base

; SPDX-License-Identifier: BlueOak-1.0.0
; This file is licensed under the Blue Oak Model License 1.0.0.

;; 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.
(define (ticket id-str)
  (hyperlink (string-append repo-url/ "tktview?name=" id-str)

             #:style (style #f (list (attributes '((target . "_parent")))))))

(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)))))

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