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

1.1 Creating an article

Open a terminal window.

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

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

The script creates a new ".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:

"articles/my-new-post.poly.pm"

#lang pollen

◊; Copyright 2020 by Joel Dueck. All Rights Reserved.

◊(define-meta conceal "blog,rss")

◊(define-meta published "2020-01-18")

◊title{My New Post}

Write here!

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

As long as the define-meta for conceal contains "rss", the new article will not appear in the RSS feed; as long as it contains "blog" it will not appear in the blog. This is useful for when an article is in a draft state, or simply when you want to keep it semi-hidden.

When satisfied with the post I’ll remove the define-meta for conceal, save it one last time, then go back to the terminal:

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

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 thelocalyarn.com/code/.

1.2 Adding notes to an article

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

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

"articles/my-new-post.poly.pm"

#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 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 make web and 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.

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