More reasons to love markdown plus critic markup

Deadlines for senior projects mean that in addition to the interesting challenge of how to submit genuinely replicable digital scholarship to the library's institutional repository, it's time to generate pdfs so that the Graphic Arts Department can bind something for the library shelves.  The projects I'm advising are formatted in markdown extended to support citation by scholarly URN (what I'm calling "citedown").  We wanted to create markdown source that could be used with leanpub, beautiful docs, or pandoc, so the automated workflow has to handle some potentially complex issues resolving URNs, downloading local copies of embedded images and rewriting references to them, etc.

I had been using critic markup for editorial questions and copy editing, but with one eye on the calendar, I wanted to test the pdf workflow before we had a complete draft with all critic markup resolved.

To my surprise, when we used pandoc to lay out the text with a LaTex book structure, it recognized the critic markup and formatted it in the resulting pdf!  Comments default, appropriately, to a screaming magenta that could have been taken from a 1990s GIS palette.  (Anyone who forgets to run their automated process to find and resolve critic markup will have a hard time missing these.)

Pandoc has always been a major reason to love markdown's simplicity.  Now it's one more reason to consider the combination of markdown plus critic markup.

Markdown everywhere

Think there's a little momentum behind markdown lately?

This article from Mashable is already half a year old, and lists seventy-eight (78!) tools for "writing and previewing markdown"!  And its topic doesn't even extend to some of the very interesting services that use markdown, like leanpub and draft, or any of the numerous markdown-to-slideshow toolkits out there...

I'm convinced enough that I've just completed an initial version of a tool for working with markdown extended to allow citation using canonical URN values, and converting the source to generic markdown that any of these tools can process.  When I've polished the docs a little more, I'll post here with further notes on markdown and its increasing importance for scholarly work.

markdown + criticmarkup

It's been a year since I last posted about markdown, and in that time, the number of interesting applications and services has continued to grow rapidly.  (If you use markdown and  haven't looked at leanpub yet, you  owe it to yourself to take a peek!)

I've been looking recently at using criticmarkup together with markdown, and it seems really promising.  Editorial on the iPad and both Multimarkdown Composer and Marked2 on OS X support displaying criticmarkup within your editor.

It would be nice to have equally convenient ways to automate accepting or rejecting suggested additions, deletions or changes, but the OS X system services in the  criticmarkup site's toolkit did not work correctly when I installed them, so I'm gisting a couple of perl scripts that accept or reject criticmarkup in standard input.

• gist to accept criticmarkup
• gist to reject criticmarkup

It shouldn't be a big job to turn those into system services. I've never used OS X's Automator, but maybe that would make a good afternoon project...?

Mark[up|down]

People sure hate the pointy brackets.  I've been writing markup since version 2 of  the Text Encoding Initiative Guidelines in SGML in the 1980s, and as easy as modern tools like oXygen make it today, even I'm not crazy about it.  Over the past year or so, I've looked at every "markdown" alternative to markup that I could find:  to name a few, textile, markdown, multimarkdown, reStructuredText, and more wiki languages than I can list.

All of them seem to have a similar history:  somebody wanted to have a quicker and easier way to express HTML, cooked up a tool to convert some simple "markdown" conventions to HTML, and realized, "Hey, this is useful!"  As a result, all of the markdown languages share two main drawbacks.  The first is that they generally express only the semantics of HTML, or a subset of HTML.  That eliminates their application to any writing or editing that requires richer semantics such as an XML language could supply, but more fundamentally, the markdown languages suffer from a long-recognized limitation:  they're not specified.   It should be obvious that "Whatever my converter tool handles" is NOT a specification, but that's the state of most of the markdown schemes.  (See these comments from more than a decade ago about reStructuredText!)

For those cases where I really just want a quick and easy way to bang out HTML-like content, John Grueber's markdown seems to offer the best compromise.  First, if you really need some particular piece of HTML beyond what markdown offers, you can just embed it in your text (although at the price of reintroducing some pointy brackets).  But what really persuades me is the pegdown processor.
Pegdown uses parboiled's "parsing expression grammars" (PEGs) so it comes closer to a separately specified definition of the language than a code library full of regular expressions emitting some kind of converted text.  pegdown will give you an abstract parse tree for your markdown content, which makes me feel much more confident using markdown down from code I write.

Add to that the ever growing number of editors and other tools that support markdown in all kinds of contents, and I'm converted.  So was the text of this post — from markdown to html.