Pandoc -- write once, display documentaiton anywhere.

Pandoc is a fantastic tool that converts common markup languages like: LaTeX, markdown, html, groff, mediawiki, in to one another. It also helps you export them to PDF, HTML, docx, rtf, with a single command.

The command for it couldn't be simpler:

pandoc <inputfile> -o <outputfilename>.<output_ext>

My Trial

I am writing a short piece of documentation about an API I built with the requirement that readers be able to:

• access the information on a web page
• save the API as a download or print it for easy reference
• open it on an e-reader (Why kill trees if you don't have to? Unless you're a sadist...)

As an additional requirement, I wanted to be able to quickly and easily edit the original. (This throws LaTeX out: \command{ICan'tremember} \command_toEnd{THATcommand})

Here are the images of what I ended up with, all coming from one source file, and that single command being repeated with different extensions:

Epub Output

The epub output looks great, and reflows nicely. Additionally, handy little links are put in for easy navigation, and a table of contents is created. My only dislike comes with the fact that a blank title page is added (probably because I didn't use the syntax for adding a title). One would assume if the document didn't have that appended, no title page would be added.

HTML

HTML with 20 lines of custom CSS

 The HTML output looked very nice on the surface, and I was very pleasantly surprised that when I opened up the source, all of the tags had attached classes, so building a style-sheet was a breeze!

PDF

PDF -- looks eerily like Pandoc converted it to LaTeX first

The PDF command performed well, links are click-able, and the document had a very nice table of contents. However, it looks like the text was first converted to LaTeX before being exported, due to the general styling (or perhaps this is what PDFs look like by default). Good thing I like it, the text doesn't stretch so far to be unreadable, and the spacing is nice.

Summary

Pandoc is a great little tool for document converstion and export, and makes a wonderful addition to any toolkit.

One of the better features, I imagine, if you have lots of old documentation is being able to convert that to newer representations through it's conversion command:

pandoc -f html -t markdown http://www.fsf.org

It also does tables, math rendering, and automatic citations.