Index: code-docs/design.scrbl ================================================================== --- code-docs/design.scrbl +++ code-docs/design.scrbl @@ -6,33 +6,36 @@ @(require "scribble-helpers.rkt" racket/runtime-path) @(require (for-label racket/base)) -@title{Design and Layout} +@title{Design Background} -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. +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 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 + @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{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.}} + @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} } Index: code-docs/main.scrbl ================================================================== --- code-docs/main.scrbl +++ code-docs/main.scrbl @@ -61,11 +61,10 @@ @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/tour.scrbl ================================================================== --- code-docs/tour.scrbl +++ code-docs/tour.scrbl @@ -3,11 +3,134 @@ @; 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)) +@(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. -@title{A Tour: Publishing on @italic{The Local Yarn}} +@subsection{What’s not here yet} -It’s pretty simple. +Eventually there will be facilities for creating PDF files of individual articles, and print-ready +PDFs of books containing collections of articles.