#lang pollen
◊; Copyright 2015 by Joel Dueck. All Rights Reserved.
◊(define-meta published "2015-09-01")
◊title{Pollen Targets}
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:
◊blockquote{◊link[1]{“New Pollen tutorial:} how to generate multiple outputs (e.g., HTML, plain text,
LaTeX, and PDF) from one source file.”
◊footer{Matthew Butterick (◊mono{@mbutterick}) in a now-deleted tweet}
◊url[1]{https://docs.racket-lang.org/pollen/fourth-tutorial.html}
}
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 (◊xref["future-proofing"]{because
reasons}). Before Pollen, the best route seemed to be: write the documents in ◊link[2]{Markdown},
and then use a tool like ◊link[3]{Pandoc} to convert that source to HTML and to PDF (via LaTeX).
◊url[2]{https://daringfireball.net/projects/markdown/basics}
◊url[3]{http://pandoc.org/}
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 ◊link[4]{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.
◊url[4]{http://brettterpstra.com/2015/08/24/write-better-markdown/}
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:
◊ol{
◊item{You decide what kind of semantics your documents need.}
◊item{You design the markup your documents will use.}
◊item{You decide exactly what output that markup produces.}
}
Here’s an example excerpt of one of my documents in Pollen:
◊blockcode|{#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 ◊code{◊"◊"tags} above are all functions I write. The ◊code{◊"◊"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 ◊code{◊"◊"verse}
tag to place its contents inside a ◊code{<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 ◊code{◊"◊"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 ◊code{.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.
