I was raised during a generation where writing on a computer was virtually synonymous with using Microsoft Word (little has changed since). However, as I grew versed in the landscape of software development utilities, I knew there had to be a better way to write. For me, the perfect writing toolchain needed the following qualities:
- Content should be portable.
- Content should play nice with version control and diff tools.
- Content should be grep-able.
- Structure emphasized over presentation.
- Automation should be straightforward.
Some common themes can be picked out from these qualities:
- Plain text is preferable to binary formats.
- Battling WYSIWYG nuances should not impede writing.
Luckily, many software developers share a similar philosophy for writing and a wealth of high-quality utilities are now available. Having tried several solutions, I have found the following use case/software pairings to work well for my needs:
- Simply formatted notes/articles/posts - Markdown/Pandoc (or similar).
- More detailed notes/documents - AsciiDoc/AsciiDoctor.
- Formal, page-oriented documents - LaTeX.
- Heavily formatted single-page documents - LibreOffice/InkScape.
In the following sections, let's take a closer look at the four solutions and answer the follow questions for each:
- What is it?
- How is it used?
- What software is used?
First, some terminology should be cleared up. For me there are two common types of documents:
- page-oriented - These documents are intended to be physically printed onto paper. The page size greatly influences the presentation and structure of the document. Typical file format is PDF.
- screen-oriented - These documents are intended to be viewed on a screen (via web browser or similar). Typical file format is HTML.
Markdown
What is it?
Markdown is a text-based markup that has become wildly popular. It has a simple, easy to understand and remember syntax that provides the bare formatting essentials.
How is it used?
Primarily for blog posts. Occasionally for quick notes. Sometimes for documentation that accompanies software projects (e.g. readme and changelog files).
What software is used?
For blogging, practically all static website generates support Markdown. I use Pelican for this blog but there are numerous other options available.
Outside of blogging, Pandoc is the go-to utility for all things Markdown.
Like all plain-text markups, your text editor of choice can be used to actually write the documents. I prefer Vim and there is great support for Markdown syntax highlighting and folding.
AsciiDoc
What is it?
AsciiDoc is essentially a supercharged version of Markdown. It provides a wide variety of formatting options which allows for expressive, well designed documents.
How is it used?
I use AsciiDoc whenever possible, especially for screen-oriented documents. Most things I write on a regular basis are done with AsciiDoc. To be completely honest, the other utilities in this writing toolchain are only employed because they are slightly better suited for their use case than AsciiDoc.
What software is used?
While no longer actively developed, the original Python implementation of AsciiDoc is still my utility of choice. It is simple to use and provides all the functionality I need for now.
AsciiDoctor is a newer implementation that will likely succeed the original. There are some synatical changes that are not backwards compatible which may be an issue for existing documents.
Additionally, Pandoc can be used to output a file to AsciiDoc but it cannot directly read AsciiDoc. The workaround is to first convert an AsciiDoc file to DocBook which can be read directly by Pandoc.
LaTeX
What is it?
LaTeX is a highly configurable markup and typesetting system. It excels at generating formal page-oriented documents.
How is it used?
When the need arises for formal documents with a sharp professional look, LaTeX is the way to go. While there is a bit of a time investment getting the initial packages and styling configured, reusing the settings for other documents is simple.
What software is used?
On Windows, MiKTeX is the best LaTeX implementation around. If the document will need to be displayed on the web, I highly recommend running the LaTeX generated PDF file through the exceptionally awesome pdf2htmlEX utility.
LibreOffice/InkScape
What is it?
LibreOffice is an open-source alternative to Microsoft Office. InkScape is an open-source vector graphics suite.
How is it used?
Sometimes the need for a heavily formatted single page document is necessary (e.g. a resume or flyer). For this use case, WYSIWYG comes in handy as there can be no question about how the final product will look.
What software is used?
Well LibreOffice and InkScape of course!
