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