Contemporary Quill

When writing for the web, there’s nothing but disappointment. I almost wish I didn’t understand HTML — then I could use high-level word processors, export to HTML and turn a blind eye to the atrocious markup.

I was holding HTML-editing-enabled WebKit (part of 10.4 and installable under 10.3, check out /Developer/Examples/WebKit/Blot/ for a developer-level taste of the tech) as my future savior. It promised a WYSIWYG HTML editing environment. While it largely succeeds, its HTML output is… “inspired”. It’s not altogether bad, but it’s not what I would write by hand. Again, if I could just let go of the underlying representation obsession, I wouldn’t have an issue. But it’s my nature.

Previously I used two different tools for authoring words destined for HTML: my own micro-markup app and BBEdit.

I used my micro-markup app for penning blog entries. It’s pretty lame: its engine consists of a series of regex-based transformations. (This is why I sympathize with Gus’s unit testing posting. My engine is also covered with unit tests. I know it works up and down, but I also know how fragile it is. Every time I added any little feature I broke two other things.) Single line breaks become <br> tags. Double into <p> tags. Basic bolding, linkage and lists. Not much else. I originally wrote it to simplify rich text entry into a web form for a client. It’s written in Java, so when I wanted something similar for myself, I just copied the code into a Cocoa/Java project and hooked up the UI. It’s a poster child for STTCPW — it doesn’t even save. The only notable thing is its widescreen three-pane UI which displays the source, generated HTML and HTML preview simultaneously.

My engine didn’t do everything I wanted it to do, but I knew that if I were going to add another feature, I would break down, throw away the skanky series-of-regexes and code a recursive descent parser. So I did nothing, spiting Feyligsungur. “I see a little man too scared to write a state machine.”

Due to micro-markup app’s weaknesses, I pen articles directly in BBEdit. Hence my bitter complaining at its old web preview bug. Unfortunately this is nonoptimal. Not only to I have to think about HTML tags while I write, they clutter the text itself and BBEdit lacks Check-Spelling-as-You-Type.

I pondered my situation. What I need to find is a lackey like me: a prefectionist purist writer/programmer who demands cleanliness in textual input, markup output, and the transformation code itself. Of course, such phrasing made the answer obvious: Gruber.

I took another look at Markdown. I initially dismissed Markdown because John and I have differing opinions on how to minimally represent links (I favor the [some text http://example.com] pattern, while Markdown uses [some text](http://example.com) and really favors out-of-line addresses.) Still, I couldn’t deny Markdown was a lot further along than my engine, and John’s code didn’t reveal “perlitis” — a common form of brain damage clinically tied to extensive Perl coding. (It’s currently undetermined whether Perl’s relation to the illness is causal or merely correlated.)

The act that sealed the deal was when I took a deeply-nested article outline I previously wrote in an outgoing email, dropped it into Markdown, and out popped a correct HTML unordered list. Cool, apparently I already think in Markdown and didn’t even know it. (Either that or I think like Gruber, a scenario that sends shivers down my spine.)

Now that I decided on Markdown for my engine, I needed an environment to plop it into. I thought about adding it to BBEdit but remembered somebody mentioning to me that Markdown is already integrated into TextMate.

I tried TextMate when it first came out, and pretty quickly dumped it. I hated the robot-on-the-keyboard icon, its lack of a preferences window, and its tag line (“The Missing Editor” — struck me as arrogant.)

Then Dave Dribin used it when demoing Ruby on Rails at PSIG 86. First thing I noticed was icon was replaced with a nice ruby-colored gear. It looked like a Mac OS X app icon. I downloaded it, and sure enough using Markdown inside TextMate was just a matter of enabling a “Pipe text through” checkbox, which was already even pre-populated with Markdown.pl. Voilà a Markdown-based authoring environment.

While I would still prefer authoring in a WYSIWYG environment, word-wrapped monospace isn’t half bad. Unlike BBEdit, TextMate offers Check-Spelling-as-You-Type (I love you, squiggly red lines). TextMate also ships with Markdown syntax highlighting out-of-the-box (language selection could be nicer, I don’t get why I can’t click on the “Language: whatever” status line at the bottom of the window to select the current language.)

Yet, all was not perfect in TextMate+Markdown land. Specifically, Markdown does not transform plain ASCII punctuation into the its typographically-rich HTML-entity brethren. I can understand not doing this by default, but it’s not offered even as an option. Gruber does offer SmartyPants, but it’s intended more as a Moveable Type plugin. Fortunately, you can pretty easily pipe Markdown’s output directly through SmartyPants.

It’s easy to get Markdown+SmartyPants web preview working in TextMate. Two steps:

1. Copy Gruber’s SmartyPants.pl and my Markdown+SmartyPants.pl into TextMate.app/Contents/SharedSupport/Support/bin/.

2. In the Web Preview window’s options drawer (check the “Show Options” checkbox at the bottom of the preview window) switch the “Pipe text through” checkbox+field from Markdown.pl to Markdown+SmartyPants.pl

That buys you preview. When you want to “compile” to HTML, you can use this TextMate command bundle plugin. When you copy it into ~/Library/Application Support/TextMate/Bundles/, it will yield a Automation->Run Command->Markdown+SmartyPants->Convert Document to HTML menu command.

That plugin Works For Me, and it should work for you, but it’s pretty loosey-goosey. I just copied an existing plugin, and guessed at everything that needed to be changed without reading any docs (are there docs? I couldn’t be bothered to even look.). It seems to work, let me know if you run into any trouble with either Markdown+SmartyPants.pl preview script or markdown-smartypants-0.tmbundle plugin.

So far I’ve written a couple of articles and blog posts using this system, and it appears to be holding up. I seem to be willing to write longer screeds in this environment. Man, I hope that isn’t more of Gruber rubbing off on me. I’m cautiously monitoring my levels of adoration regarding gray and white…

Thursday, November 10, 2005
12:00 AM