Series./blog.sh v1.10⁸

./blog.sh 1.10 is out — release on GitHub.

The release that opens a door for programs. Every screen you read before you act, and every action it offers you, can now answer as data too. A program on another machine reaches them over the SSH the server already has, and only through one script that lets it run one engine command and nothing else. It connects with a code ./blog.sh pair draws in the terminal, so nobody types an address or a key anywhere. This is what the native apps for iOS and Android, now in preparation, are built on.

Around it, the archive says more about itself. An "On this day" card shows posts from this day in earlier years, /series/ is an index of every series, a page of a listing says which days it covers, and the 404 page offers a search already filled in with the words of the address it could not find. On a Mac, ./setup.sh offers an icon in Applications, so the blog opens without typing into a terminal. And the second language from 1.9 has grown up: a series has a name in each language, and a translation keeps its old addresses the way a post does.

One thing ahead of time: the /write/ page and the SendPost shortcut go away in 1.11, and the apps take their place. In 1.10 they work as before.

A letter arrived at the end of September. Pavel had used this engine to back up his old blog, and wrote down what he learned doing it: over a thousand posts in nine years, and stretches when he wrote every day. He had not known. The blog had been his the whole time and the posts had been in it the whole time, and still the number came from the archive, the first time anything read it end to end.

This release is about what an archive says when it is asked. How things get into one, how they leave it and how it is checked, this site has written about enough. This is about what the archive knows about you.

What the archive counts

./blog.sh stats reads every post and answers with one screen. On the archive this engine was built around, today it reads:

Every guide to this engine starts with the same sentence: open Terminal, go to your site's folder and type ./blog.sh. For somebody who lives in a terminal, that is one sentence. For somebody who does not, it is three things to get wrong before the first word is written — where Terminal is, what "go to the folder" means, and why the command starts with a dot and a slash.

1.10 turns that sentence into something that can be double-clicked.

What the wizard offers

./setup.sh on a Mac ends with one more question:

Put an icon in Applications that opens this blog with a double-click?

Up to 1.9 the engine had one door for programs, and it was narrow. The phone delivered a post through it: a shortcut sent a file over SSH, receive.sh took it on the other side and answered with one object. Two commands kept that promise — add --json and publish --yes --json. Everything else was a screen for a person: the listing, a post's properties, the queue, the trash. A program that wanted to see what was in the archive had nothing to call.

1.10 opens the door wide, and that is exactly why it is careful about what may come through.

Every screen as data

Every screen a person reads before acting, and every action it offers, now has a --json form: one object on standard output and nothing else, every key always present. A refusal is an object too, {"ok": false, "error": "not_found", …}, with a zero exit — the status says whether an answer arrived at all, the object says what it was. A program that has to test whether a key exists is a program writing its own parser; that is what this prevents.

A listing is the page the engine builds most often and nobody writes. The front page, a tag's page, a year of the archive, the parts of a series, the search results — all of them are cards of posts one after another, and what a card says is the engine's decision, not the author's. 1.10 changes several things on listings at once, and one of them changes without anybody setting anything. That one is worth being ready for.

The card of a picture post carries the picture

A card is cut by height and keeps its first block whatever it weighs. So a photograph under one line of words fell off the card of exactly the post that is that photograph: on one archive the first page of the pictures showed three pictures in thirteen cards. For a post whose kind is image or video the medium now goes first on the card, and the same cut runs over what follows. A picture taller than wide is held to 22rem instead of taking a screen, and the card is charged that height, so the caption under a portrait photograph is on the card too.

A typo fixed in one paragraph. That is the whole change the author made, and that is how the archive should record it: one paragraph different, the rest as they were. On a real archive, by the road a phone sends posts along, the engine could not do that up to 1.9. Measured on October 8: 101 posts changed by being saved unchanged.

What markdown cannot say

A post is stored as blocks, and the editor shows text. Between the two stands a conversion that mostly loses nothing — a paragraph is a paragraph, a heading is a heading. But an archive that came from an import carries things on its blocks that markdown has no word for: a paragraph Tumblr marked as indented, as a list item or as a line of a chat; a video's provider and the address it was first seen at; a player a service handed over as HTML. The text the editor shows carries none of it. And a save used to rebuild every block from that text: fixing one typo rewrote every other block of the post without them. At the desk and from a program alike; only at the desk nobody thought to measure it.

The question the other way round

1.9 brought the second language: one post, a text in each language, an /en/ tree beside the root. The first site to run it for real was the one the engine grew up on, and a month of that showed what no test shows. The 1.10 changelog has over thirty entries about the second language. This is not their list. It is about what a second language needs that the first one does not.

A name that inflects

site.author stands in sentences: "na osobním webu Daniela Šnora". Czech inflects a name, so the configuration holds the genitive, and the pages in English took it over, case and all. 1.10 adds site.author_name: the name as it stands alone — under a hero title, as the person the structured data names, on the pages of a language other than the site's own. Without it author is used everywhere, as before. A language that does not inflect never needed it, which is why nobody wrote it.

A series has a name in every language

Six posts have covered what 1.10 is about: the archive that talks back, an icon instead of a terminal, the door for programs, what a listing says now, saved unchanged and a second language, one release later. This one is the rest, in the order an operator meets it. Most of it came from two sites that have run the pre-release since the end of September, and from readers who read the fixes of the fixes.