I once used Microsoft Word to try to write a 30-page user manual. It had a table of contents, figures, flowcharts, and tables with captions, nothing terribly complicated. Nevertheless it was too complicated for Word, causing it to glitch and slow to a crawl. The problem is Microsoft Word, like all word processors, tries to edit the document while adjusting the layout. It was furiously trying to adjust margins, update the table of contents, and allow me to type words (and spell-check and grammar-check them), all at the same time.1
A better way would use a simple text editor to focus on writing, then typesetting the document after the writing is done. Focus on writing first. After you finish writing then make it pretty.
After giving up on Word I tried LaTeX: a typesetting engine so powerful that publishers use it to typeset books. It is free and open-source. You write a document in plain text and use LaTeX to typeset it into a pdf file.
The winning combination
Writing documents in LaTeX can be a pain. Luckily someone invented Pandoc which allows you to write documents using Markdown instead of LaTex. Pandoc takes the Markdown text file and using the LaTeX typesetting engine, converts it into a beautifully typeset pdf file.
Pandoc benefits
It’s plain text
Pandoc uses plain text files, Microsoft Word uses a binary file format. Plain text is the universal file format. It is future-proof: no matter what computer you buy twenty years from now, you can be reasonably confident it will be able to read plain text files.
It’s scriptable
The command-line nature of Pandoc means that you can automate it with a scripting language like Python. A few years ago I built a report generator for a local water treatment plant using Python and LaTeX. It compiled a morning report complete with graphs and tables of current system status. The script automatically compiled and emailed the report daily to the plant operators and repair team. Things like this can be done easily with Pandoc and LaTeX, but not a word processor.
It’s free
Free is always nice.
It’s open source
Anyone can download and review the source code, and (ideally) submit a bug fix. More people reviewing and fixing the code means fewer bugs.
It’s astonishingly beautiful
Using the LaTeX engine with Pandoc, you can create gorgeous, camera-ready copy for publication.
-
A word processor trying to display a document of medium size and complexity is like a dog trying to mow the lawn: you’re not mad because he’s doing such a poor job. You’re amazed he can do it at all. LaTeX takes several seconds to typeset your document to perfection, while Microsoft Word tries to quickly typeset every time you press a key. Word’s typesetting engine takes shortcuts that lead to imperfections because it’s the only way to keep up with the workload. ↩