Tags

This contribution comes from Thomas Hodgson, a philosopher with an interest in the nature of language and communication. Thomas believes that ‘Word is good for some things but it’s not the right tool for every job … not least, because it’s expensive.’ Thomas wrote his thesis with LaTeX but uses Pandoc for journal papers and teaching materials.

Warning: There is a bit of ‘tech talk’ here but we’ve been assured if you need to know; you will get it! Enjoy, Claire.

What is Pandoc?

Pandoc is a free, open source, GPL licensed program, written by John MacFarlane, that converts documents between formats, for example LaTeX to the DOCX format used by Microsoft Word. This simple conversion is done by typing pandoc –output document.docx document.tex on the command line. It is the best tool I know of for converting documents, and it is getting better all the time.

Suppose that you write a paper in LaTeX for submission to a journal that unfortunately rejects the paper. Your next choice requires submissions to be DOCX because they use Word. Pandoc will make the conversion between formats painless when you prepare your revised submission. The advantage of Pandoc is that you can move easily between different formats. You can write in whatever format you prefer, and Pandoc can convert it to whatever other format you need for the finished product.

Pandoc understands an extension of the Markdown structured text format sometimes called Pandoc flavoured Markdown which includes several functionalities useful to academics such as bibliographic references and footnotes. Pandoc will cope with mathematical formalism, and you can also make slides with it. There are other conventions for structuring plain text, but Markdown is the most widely used; using Pandoc’s version means that Pandoc will correctly interpret your source. Pandoc flavoured Markdown allows Pandoc to be more than a conversion tool: it’s also a tool for writing. In my own work, all my papers start out as plain text files written in Pandoc flavoured Markdown. Journals and conferences receive an appropriately styled PDF after the content has been written.

You can read about Markdown in John Gruber’s original description. You might also find the specification of CommonMark useful; it is co-authored by John MacFarlane and Pandoc follows it. There’s a useful tutorial for Markdown written by Esteban Herrera.

References with Pandoc are handled with a system that reads a range of bibliography formats, including Biblatex, and formats references using the Citation Style Language. To use it just type pandoc –bibliography=bibliography.bib –output document.docx document.md on the command line.

Doing academic writing in plain text has several advantages. Plain text can be read and edited on any platform, and you can use any text editor you like. There is no cost to changing your mind about which editor to use. The chance of plain text becoming obsolete is practically nil. The same points apply to keeping references in a format like Biblatex; you can also use your favourite bibliographic program as long as it will export to one of the formats Pandoc understands.

Who should use Pandoc?

If you like the idea of writing in plain text then Pandoc is the best way to go. LaTeX has the same advantages but there is a steeper learning curve, and once a document is written in LaTeX it is harder to turn it into something else (although it is certainly not impossible). Pandoc means you can keep your options open about format until the last minute.

On the down side, using Pandoc’s command line can feel a bit awkward at first but it is no harder than learning to use any piece of software properly. Writing in plain text also takes some getting used to if you are immersed in the ‘what you see is what you get’ paradigm of Word, Pages, or LibreOffice.

If you never need to convert between formats, and the format you use works for you and/or has features essential to your work that Pandoc doesn’t support then Pandoc might not be for you.

Where can you get Pandoc?

There are instructions for installing Pandoc on for Windows, Mac OS X, and Linux. There is a helpful mailing list for Pandoc called pandoc-discuss.

I also recommend Kieran Healy’s description of his workflow which discusses some issues relevant to writing in the social sciences.

Mark Sprevak has written a useful tool for adding styles to Pandoc called Panzer which you might find useful. Finally, I have written a script called Convert bibliography that converts bibliography files found on the web to a tidy format that works with Pandoc.