SimpleMarkup is dead. Long live MarkDown (and Textile)

If you use RDoc, than you're probably familiar with it's markup, known as SimpleMarkup. If you've been using RDoc for a while, you are also probably aware that SimpleMarkup is horribly broken, when it comes to handling odd formatting.

Besides the usual formatting mistakes that can easily crash SimpleMarkup, I and other users began noticing odd error messages when installing YARD documentation with SimpleMarkup:

Unhandled special: Special: type=65, name=CROSSREF,_SPECIAL_, text="Spidr"

Even after ditching RDoc for YARD, SimpleMarkup (the default markup used by YARD) was able to reach forth from it's icy RubyGem and introduce bugs into my code. This was the last straw, SimpleMarkup is dead, time to move on.

Luckily, YARD supports using alternate markup engines, such as MarkDown or Textile. Having used MarkDown regularly in the past, and that it matched SimpleMarkup's syntax in some ways, I decided to convert all of my Ruby project's to MarkDown formatted YARD documentation.

First, I had to specify the --markup markdown option in the yard_options setting (provided by the hoe-yard plugin) in the Rakefile.

Second, I renamed the README.*, History.* files to README.md, History.md, respectively.

Finally, I began the tedious process of converting SimpleMarkup formatted text to MarkDown:

1. Replace the =, ==, === headings with #, ##, ###.
2. Indent all source-code examples not following a YARD @example tag by 4 spaces.
3. Convert any raw URLs to MarkDown links.
4. Replace any +code+ or <tt>code</tt> formatting with `code` or <code>code</code>. (Note: `code` can handle spaces, numbers and symbols within the ` ` characters, where as +code+ cannot.)

In conclusion, that is how I ridded myself of the last buggy vestiges of RDoc, and increased the reliability of my documentation using YARD.