◊(Local Yarn Code "Changes On Branch 71aa7cd9450071db")

*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 Background}

The design and implementation of @italic{The Local Yarn} are guided by requirements that have
evolved since I started the site in 1999. I enumerate them here because they explain why the code is
necessarily more complicated than a typical blog.

@itemlist[
  @item{@bold{The writing will publish to two places from the same source: the web server, and the
  bookshelf.} 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{Changes are part of the content.} 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 every published edit to an article to be
  findable and linkable. I want addenda 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{Everything produced here, both in print and on the web, should look good.}
  @item{@bold{All the output should be produced (and reproducible) by automated processes.} No
  clicking on buttons in apps to publish web pages or books.}
]

@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["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 "../pollen.rkt"))

@section{How I Publish: A Quick Tour}

This isn’t a tutorial, since these steps probably won’t all work on your computer. Think of these
narrations like me talking while I drive.

@subsection{Creating an article}

Open a terminal window.

@terminal{@cmd{> cd /path/to/thelocalyarn}}

The @tt{make} command provides a high-level control panel for common tasks. Typing just make from
a terminal window shows a list of options:

@terminal{
@cmd{> make}
article     Start a new article from a template
help        Displays this help screen
publish     Sync all HTML and PDF stuff to the public web server
scribble    Rebuild code documentation and update Fossil repo
web         Rebuild all web content (not PDFs)
zap         Clear Pollen and Scribble cache, and remove all HTML output
}

Following the first option in this list, I type @tt{make article}, and enter a post title when
prompted:

@terminal{
@cmd{> make article}
racket -tm util/newpost.rkt
Enter title: @cmd{My New Post}
}

The script creates a new @filepath{.poly.pm} file using a normalized version of the title for the
filename, and opens it in my editor (this is currently hardcoded to use MacVim). When the file pops
up we see a basic template ready to edit:

@filebox["articles/my-new-post.poly.pm"
@codeblock|{
#lang pollen
 
◊; Copyright 2020 by Joel Dueck. All Rights Reserved.
◊(define-meta draft #t)
◊(define-meta published "2020-01-18")
 
◊title{My New Post}
 
Write here!
}|]

At this point I might delete the @tt{◊title} line, since specifying a formal title is optional
(other than the one needed to generate the filename). I might also add a @racket[define-meta] for
@tt{series} or @tt{topics}. 

As long as the @racket[define-meta] for @tt{draft} is @racket[#t], the new article will not appear
in the RSS feed, or in the blog or any series pages.

When satisfied with the post I’ll remove the @racket[define-meta] for @tt{draft}, save it one last
time, then go back to the terminal:

@terminal{
@cmd{> make web}
[lots of output: rebuilds blog pages, keyword index, RSS feed]
@cmd{> make publish}
[lots of output: uploads all web content to the server]
}

The article also needs to be added to the Fossil repository, so revisions to it will be tracked:

@terminal|{
|@cmd{> fossil add article/my-new-post.poly.pm}
ADDED  article/my-new-post.poly.pm

|@cmd{> fossil commit -m "Publish ‘My New Post’"}
Autosync:  https://joel@thelocalyarn.com/code
Round-trips: 2   Artifacts sent: 0  received: 1
Pull done, sent: 892  received: 8720  ip: 162.243.186.132
New_Version: 15507b62416716a3f0be3c444b0fc09aa4364b989140c5788cf679eb0b2463a6
Autosync:  https://joel@thelocalyarn.com/code
Round-trips: 2   Artifacts sent: 2  received: 1
Sync done, sent: 10153  received: 4680  ip: 162.243.186.132
}|

As you can see, Fossil does an automatic pull before the commit, and another automatic push
afterwards. This commit is now visible on the public timeline, and the source code for the article
can now be seen on the public repo at @tt{thelocalyarn.com/code/}.

@subsection{Adding notes to an article}

A few days (or years) after doing the above, I receive an email from Marjorie with commenting on
@italic{My New Post} and I decide to publish her comments.

I open the article in my editor and add some lines to the end:

@filebox["articles/my-new-post.poly.pm"
@codeblock|{
#lang pollen
 
◊; Copyright 2020 by Joel Dueck. All Rights Reserved.
◊(define-meta published "2020-01-18")
 
◊title{My New Post}
 
It’s a 4⨉4 treated. I got twenty, actually, for the backyard fence.

◊note[#:date "2020-01-23" #:author "Marjorie"]{
 Hope you sank that thing below the frost line.
}
}|]

This looks like a blog-style comment, but the @racket[note] tag function has some special powers
that typical comments don’t have, as we’ll see in a moment.

I save this, go back to the terminal and do @tt{make web} and @tt{make publish} as before.

Now if you open the article’s permlink, you’ll see the note appears in a “Further Notes” section at
the bottom — again, just like a normal blog post comment.

But if you go to the Blog section, you’ll see the note appearing in its own space right alongside
the other articles, as if it were a separate post. It will also appear in a separate entry in the
RSS feed.

@subsection{What’s not here yet}

Eventually there will be facilities for creating PDF files of individual articles, and print-ready
PDFs of books containing collections of articles.