Markdown and PlainDoc: Almost the Same, Except...

Sampo Kellomäki (sampo@iki.fi)

I notice with gratitude that there are like thinking souls. Parallel innovation has happened: what I call "PlainDoc" (http://zxid.org/plaindoc/pd.html) is nearly the same as "Markdown" by John Gruber - http://daringfireball.net/projects/markdown/syntax and they are both written in perl :-). My inspiration was email and usenet news as seems to have been Gruber's. Perhaps our projects should collaborate or merge.

Both PlainDoc and Markdown need to contend against other formatting languages such as

1 Markdown and PlainDoc

1.1 PlainDoc is Markdown Compatible

  1. Email and usenet logic applies: easy for anyone from these cultures

  2. Distinguish a paragraph by empty line in between

  3. Indication of headings using underlining with "===" (H1) and "---" (H2), but Plaindoc does not support multiple hashmarks syntax (yet as of 2012). Instead it supports tilde underline "~~~" (H3) and caret underline "^^^" (H4), as well as '< <subsubsec: ...>>' syntax.

  4. Blockquotes are the same, i.e. prefix the line with "> ". Nesting works the same, just add the prefix more times.

  5. Code (monospaced) blocks are produced by mere indentation (without ">"). PlainDoc provides also several semantically tagged code blocks using special markup, but the bulk of the usage continues to be the indentation without ">" method.

  6. Bulleted lists work the same: star ("*"), plus ("+"), and minus ("-") can introduce a bulleted list. PlainDoc also recognizes hollow bullet, i.e. lowercase oh ("o") as bullet. Bulleted lists nest naturally.

  7. Ordered lists with arabic numerals work the same. PlainDoc also supports A,B,C; a,b,c; I,II,III; and i,ii,iii lists. In HTML they translate to the same as in Markdown, but in PDF-LaTeX the numbering style is preserved. The ordered lists nest naturally (among themselves and with bulleted lists).

  8. Automatic formatting of URLs

  9. Automatic formatting of function() and man(1) page references (with parens in the end)

  10. Strong emphasis using star "*" works the same, i.e bold.

1.2 PlainDoc Differs from Markdown

  1. Broader rendering target options: monolith HTML, section per page HTML, PDF, RTF, DBX

  2. Different native tagging: in Plaindoc double angle brackets ("< < > >") are used to indicate most special or output driver specific formatting, where as Markdown passes anything that looks like HTML tag verbatim to its HTML output driver.

  3. Emphasis element is indicated in PlainDoc using plus ("+") rather than underscore ("_") used by Markdown. In PlainDoc the underscore signifies subscript, as it does in LaTeX. Double asterisk and double underscore are not supported by PlainDoc. Regarding difference between emphasis and strong: in PlainDoc asterisk produces strong or bold and plus produces emphasis or italic.

  4. PlainDoc is more fuzzy about indentation of lists. While Markdown allows you to be sloppy on additional lines of a list item paragraph, PlainDoc insists you indent them properly (as would be logical for anyone viewing the file as plain text).

  5. Markdown states list items are to be indented by fixed 4 spaces, whereas PlainDoc states that they should be indented as much as the previous list item. Also subsequent paragraphs of the same list item should be similarly indented. Generally this indentation style makes sense for a reader of a plain text version of the document.

  6. File inclusion mechanisms for supporting large projects (bibles made out of many books)

  7. PlainDoc does not explicitly support horizontal rules, though some command line options cause page breaks to be rendered as such. It is also possible to add explicit HTML markup to introduce a horizontal rule (HR).

  8. While URLs are understood by both, the Link syntax differs slightly: PlainDoc always considers the URL to be a link, while Markdown allows specification of link string explicitly.

  9. Literal asterisk (or other special character) production in PlainDoc is determined by context. Markdown offers an explicit escape mechanism.

  10. Image introduction mechnism is quite different. PlainDoc uses the double angle brackets and handles many conversions automatically, including eps, pdf, png, dot, and gnuplot.