I have finally found time to play around with John Gruber’s Markdown and SmartyPants plugin — very nice, easy-to-use ways to write readable plain text that gets translated into valid (X)HTML. The best way to see what it does, and how it works, is compare the HTML version of the Markdown syntax with the plain text version.
Markdown is exceptionally great when it comes e.g. to mixing text with code samples: public String echo(String test) { return “echo ” + test; }
This works without any problems, even if what you need to explain is some piece of XML:
Essentially, you write your text similarly to the way you would in an email message - most thing just work intuitively, like * hightlighting bold text and * writing lists.
Markdown can be run from the command line or integrated into MovableType, Blosxom, and BBEdit. I have also integrated it into our internal, Java/Notes-based wiki by simply calling Markdown (which is written in Perl) via Runtime.exec() (which is kind of embarassing, but works surprisingly well).
Setting it up on our servers makes for a nice war story of its own; suffice it to say that if running Markdown with Perl 5.6.0 causes a segmentation fault, it’s a good idea to really think about the consequences before updating your operating system’s default Perl installation. (Hint: Make sure you’ll be able to recompile those modules before you do this.)
Somewhere along the way I must have introduced something that makes my Perl installation choke on the variable $backtick_count in line 854; preceding the regexp block there with my $backtick_count; fixed that.