Decide on a Markdown processor

[Klortho]

For the structured annotations, we want to allow people to write in Markdown format. Here are some possibilities for a markdown processor:

• pandoc - This might be the successor of peg-markdown (see below). It's by the same "absurdly prolific" John MacFarlane. Gives delimited code blocks and syntax highlighting -- see this comparison of MultiMarkdown and pandoc.
• Multimarkdown - written in C. According to this post, this is one of the "big three". It has some nice extensions. It is a fork of peg-markdown.
• peg-markdown - written in C. Also by John MacFarlane; I think pandoc might be the successor of this.
• Original markdown Perl processor from Daring Fireball: http://daringfireball.net/projects/markdown/. Very easy to use. This is somewhat limited; doesn't have a lot of very fashionable extensions. Doesn't always put out valid XHTML (but the output could be run through tidy). Try "<a>", for example. Output is "<p><a></p>". Use Dingus to try things out: http://daringfireball.net/projects/markdown/dingus
• Redcarpet - what Github uses, "smells like butterflies and popcorn": https://github.com/vmg/redcarpet - this looks good, but requires ruby. Is that an onerous dependency? How easy is this to install and use?
• pegdown is a Java library: https://github.com/sirthias/pegdown. I tried to get this working for about two hours, and failed. It has a lot of dependencies. Probably installing it with Maven would be easy. A big advantage would be that it could be accessed straight from Java.

See Wikipedia's List of Markdown implementations to have mind blown.

[Klortho]

pandoc is the clear winner here. It is a beautiful piece of software. It installed effortlessly on my Windows and Ubuntu boxes, but might be a hassle for our Centos boxes at work -- I don't see a package for them.

As for interfacing to Java -- I think just using the Runtime to execute as a shell process will have to do.

I don't see an easy way to overload/extend the linking mechanism, to allow us to have pandoc do the work of turning "<split>" into a link to the split page, so I think we'll have to come up with a syntax for that that's layered on top of Markdown. I'm thinking of using backticks: <split>. I don't think it would be an issue for @attributes, %param-ents, or &gen-ents.