Sounds Like Weird
23 November 2013
Once upon a time, I lost all the poetry I ever wrote, including the stuff I’d published. It was published in journals so small I’d be lucky if a single copy survives to this day. It’s possible dozens of people read my work.
Of all of those poems, I’m saddest about the piece I wrote the day I was in Belfast. The day we weren’t supposed to be in Belfast. The day I got a rifle pointed at me. (If you ever happen across Metropolis, a journal of urban poetry, with my poem titled “Belfast Brunch,” I’ll pay you for the copy.)
I thought: I’m a software engineer, why don’t I add all the stuff I’ve written into source control? But then you have two problems, as the old joke goes.
This was back in CVS days, and what CVS really didn’t like much was binary files. And me with a bunch of Word documents. Oh, and AppleWorks documents, because we know how forward-compatible those suckers are. (The current version of Apple’s Pages will not open them, but then it won’t open RTF, either.)
Novels and short stories don’t actually consist of a lot of sophisticated markup, though. There’s the occasional italics, the section breaks, the chapter headings. Because HTML was too much work to generate cleanly, I just wrote in plain text. With underlines around italics. You know, like Markdown. Though Markdown hadn’t been announced back then.
Eventually, I switched over to Subversion for source control. (I recently switched to git due in part to feedback on this post.)
However, getting stuff ready for critique or submission was another story entirely. I was talking about this with Serah Eley, and she mentioned using XSLT and XSL-FO, and had a perl/java toolchain that worked well enough, so I incorporated it into my own work. By this time, I was running my submissions through my own Ruby on Rails app, and it was slick enough that it knew where a project’s files lived, and would generate all the meta information needed by XSL-FO in order to make a PDF to print. (At that point, RTFs weren’t really possible as they were still the realm of proprietary software.)
So why XSL-FO? Part of it was the beauty of the templating system. You could make a stylesheet that specified double-spaced courier and to add an address block for a submission to an editor. You could make it single spaced in Garamond with no address block if it’s something you wanted to hand to someone you didn’t want to have your address. You could have a cover page and exclude your name on subsequent pages for contest submissions.
The downside, though is that XSLT is pretty fiddly and I had a toolchain from hell that required not only Ruby and Perl and Java, but a lot of dependencies that would occasionally drive me mad when they broke or balked.
Apple decided to adopt EPUB for iBooks. Before that, there’d been a far more confusing array of choices for electronic formats, but then people started veering toward EPUB. Plus other tools had come out like calibre, which will convert your books (so long as you don’t mind it getting its grubby paws all over your markup and inserting its calibre-isms).
Then jugyo wrote eeepub, a ruby gem to make EPUB files. And, hey, I already had valid XML files from my earlier process, right?
Not long after that, I was the head of programming (by which I mean scheduling of people and rooms, not software engineering, though I also almost all of that, too) for BayCon and Westercon 64.
One of the things I wrote the code for was the generation of the tabular data for the program grid. From there, especially with jugyo’s excellent gem, it wasn’t that far to getting a program book in EPUB form. (Reusing work I’d done in 2003-2007, I was still using XSLT + XSL-FO + InDesign for things like table tents, back of badge stickers, room signs, and the schedule content for the body of the program book.)
I remember sitting down one night a few days before con, wondering if I could actually make an ebook version of the program schedule. I wrote it on too little sleep when I had a case of shingles, but hey, it works! PDF and EPUB versions of the file are linked on Westercon 64’s site. The PDF used the same intermediate XML that generated the EPUB, but I used InDesign to generate the final product.
Here’s the code to make the EPUB version. The tl;dr version of what it does:
Somewhere around 2008, Ruby had better Markdown support and I’d become aware that I was really writing drafts in Markdown, so I was able to eliminate part of the toolchain I had.
More recently, I discovered textutil, which does the back-end work I’d been using XSL-FO for. So, I can take an HTML file (which I get from Markdown) and get an RTF and a DOC and a PDF out of it? With almost no pain?
To quote Ben Grogan: I call that winning.
As the saying goes: now you have one problem.
I’ve been working on a more general case solution, both in Ruby and Python, for taking Markdown files and making a book out of them without having to do quite so much of the work.
I’ve tried a number of Markdown editors over the last couple of years, and I have standardized on ByWord on both Mac and iOS. For things that I’ve got in source control, I use git on Dropbox with my repository on BitBucket. I use a nightly script to push repository changes in case I forget to do so.
In my current process, I no longer have rails generate XML template files, nor do I need prose DTDs, etc. I just have rails generate a YAML file, and I’ve moved much of the configuration into the rails app. But now I need to push some of that back out into CSS. And maybe I want it to be a Cocoa app, you know?
I’m still thinking about ways to do that when I want to still be able to produce the following variants with no change of my Markdown files:
Most of that’s fairly easy, but some of it’s surprisingly subtle.
And here you thought I just flung words on pages.