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,41 @@ +#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} +} Index: code-docs/main.scrbl ================================================================== --- code-docs/main.scrbl +++ code-docs/main.scrbl @@ -11,25 +11,27 @@ 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.}} @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"] - 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,136 @@ +#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/core "../pollen.rkt")) + +@title{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. + +@section{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/}. + +@section{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. + +@section{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. +