I’ve been digging into Pollen. It’s early days yet, but it seems very promising. So I was surprised and glad to see this happen today:

“New Pollen tutorial: how to generate multiple outputs (e.g., HTML, plain text, LaTeX, and PDF) from one source file.”

I tweeted earlier today that this is probably the best web/writing news of the summer, if not the year. Yes, that’s subjective. But anyhow, let me explain why I think it’s great.

For at least a few years now I’ve been trying to figure out how a good way to generate a web site and a print-ready PDF book from the same source document (because reasons). Before Pollen, the best route seemed to be: write the documents in Markdown, and then use a tool like Pandoc to convert that source to HTML and to PDF (via LaTeX).

The biggest problem is that Markdown is not actually great as a source format. Yes, it’s readable. Markdown documents, being plain text, can have a good shelf life. But in practice it’s just not very smart, and no one agrees on how to educate it. For example, suppose you want to specify a class for an image, so that it floats right. Markdown doesn’t provide a way to do this. Some variants of it have added support for it, but no one agrees on what syntax should be used. Whatever variant you pick, you better hope that your whole toolchain supports it (in the future as well as now). Just about every editor and processor and previewer out there supports their own 92% of what you need from Markdown and they each pick a different 8% to leave out. As an author, you really have no facility for doing things the way you’d like. Brett Terpstra has some good advice for coping with this, but it basically boils down to “keep your source documents as simple as possible to avoid running afoul of incompatibilities.” I say boo to that.

To use a graphics analogy, using Markdown as a source format for web and print is like creating art as a GIF and then trying to upscale to SVG. Pollen offers a completely different way of doing things:

1. You decide what kind of semantics your documents need.
2. You design the markup your documents will use.
3. You decide exactly what output that markup produces.

Here’s an example excerpt of one of my documents in Pollen:

#lang pollen

◊(define-meta title "Two Voices in a Meadow")
◊(define-meta doc-publish-date "25/08/2015")
◊(define-meta author "Richard Wilbur")

◊margin-note{
In ◊hyperlink["http://www.english.illinois.edu/maps/poets/s_z/wilbur/
imageinterview.htm"]{an interview}, he said "the milkweed's speech is
indeed written in one of my voices and was used for the sister's funeral in
a genuine and appropriate way. But the other voice --- the 'slob' voice of
the stone, is also one of my voices."
}

◊verse{◊poem-heading{A Milkweed}
Anonymous as cherubs
Over the crib of God,
White seeds are floating
Out of my burst pod.
What power had I
Before I learned to yield?
Shatter me, great wind:
I shall possess the field.}

The ◊tags above are all functions I write. The ◊verse tag is a good example of an advantage of Pollen over Markdown, because Markdown has no facility for typesetting poetry (at least, none for setting it differently than source code). For now I’ve defined my ◊verse tag to place its contents inside a <pre class="verse"> tag which I can style with CSS. Someday I might find or need a different way to structure poetry in HTML; if so, I can simply edit the function and regenerate the site, without having to change the source documents at all. Another good example is YouTube embeds. I could create a ◊video tag that would take a YouTube ID and use their latest embed code. When YouTube changes I can update my code to match, the tag remains the same.

Pollen was compelling enough when HTML output was all it did. But as of today, you can specify multiple targets for your documents, and code the output behavior for each. This means I could take a bunch of files like the one above and generate a web page, and a book-ready PDF, and a plain-text (dumbed down) Markdown version. If my requirements for any one of those target formats should ever change, I simply edit my Pollen code. The document itself can remain unchanged.

There are other things you could do, too. With some programming and some text-to-speech facilities, you could include .mp3 files as a target, and auto-generate an RSS feed, thus making everything you publish in written form into an automatic podcast as well.

With Pollen I finally have a tool I can use to publish to multiple formats where I have complete control over both the source markup and the finished result in every format. Of course, you have to learn LISP programming to make full use of it, which can be daunting, but I’m having fun doing so.