{"id":2151,"date":"2014-08-29T14:10:28","date_gmt":"2014-08-29T18:10:28","guid":{"rendered":"http:\/\/blogs.law.harvard.edu\/pamphlet\/?p=2151"},"modified":"2014-09-22T17:40:20","modified_gmt":"2014-09-22T21:40:20","slug":"switching-to-markdown-for-scholarly-article-production","status":"publish","type":"post","link":"https:\/\/archive.blogs.harvard.edu\/pamphlet\/2014\/08\/29\/switching-to-markdown-for-scholarly-article-production\/","title":{"rendered":"Switching to Markdown for scholarly article production"},"content":{"rendered":"\n

With few exceptions, scholars would be better off writing their papers in a lightweight markup format called Markdown<\/a>, rather than using a word-processing program like Microsoft Word. This post explains why, and reveals a hidden agenda as well.1<\/a><\/sup><\/p>\n

Microsoft Word is not appropriate for scholarly article production<\/h3>\n\n\n\n\n
\"Old<\/a><\/td>\n<\/tr>\n
\u2026lightweight\u2026<\/span>
\n\u201cOld two pan balance<\/a>\u201d image from Nikodem Nijaki<\/a> at Wikimedia Commons<\/a>. Used by permission<\/a>.<\/span><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

Before turning to lightweight markup, I review the problems with Microsoft Word as the lingua franca for producing scholarly articles. This ground has been heavily covered. (Here\u2019s<\/a> a recent example.) The problems include:<\/p>\n

\n
Substantial learning curve<\/dt>\n
Microsoft Word is a complicated program that is difficult to use well.<\/dd>\n
Appearance versus structure<\/dt>\n
Word-processing programs like Word conflate composition with typesetting<\/a>. They work by having you specify how a document should look, not how it is structured. A classic example is section headings. In a typical markup language, you specify that something is a heading by marking it as a heading. In a word-processing program you might specify that something is a heading by increasing the font size and making it bold. Yes, Word has \u201cparagraph styles\u201d, and some people sometimes use them more or less properly, if you can figure out how. But most people don\u2019t, or don\u2019t do so consistently, and the resultant chaos has been well documented. It has led to a whole industry of people who specialize in massaging Word files into some semblance of consistency.<\/dd>\n
Backwards compatibility<\/dt>\n
Word-processing program file formats have a tendency to change. Word itself has gone through multiple incompatible file formats in the last decades, one every couple of years. Over time, you have to keep up with the latest version of the software to do anything at all with a new document, but updating your software may well mean that old documents are no longer identically rendered. With Markdown, no software is necessary to read documents. They are just plain text files with relatively intuitive markings, and the underlying file format (UTF-8 n\u00e9e ASCII) is backward compatible to 1963. Further, typesetting documents in Markdown to get the \u201cnice\u201d version is based on free and open-source software<\/a> (markdown<\/a>, pandoc<\/a>) and built on other longstanding open source standards (LaTeX<\/a>, BibTeX).<\/dd>\n
Poor typesetting<\/dt>\n
Microsoft Word does a generally poor job of typesetting, as exemplified by hyphenation, kerning, mathematical typesetting. This shouldn\u2019t be surprising, since the whole premise of a word-processing program means that the same interface must handle both the specification and typesetting in real-time, a recipe for having to make compromises.<\/dd>\n
Lock-in<\/dt>\n
Because Microsoft Word\u2019s file format is effectively proprietary, users are locked in to a single software provider for any and all functionality. The file formats are so complicated<\/a> that alternative implementations are effectively impossible.<\/dd>\n<\/dl>\n

Lightweight markup is the solution<\/h3>\n

The solution is to use a markup format that allows specification<\/em> of the document (providing its logical structure) separate from the typesetting<\/em> of that document. Your document is specified \u2013 that is, generated and stored \u2013 as straight text. Any formatting issues are handled not by changing the formatting directly via a graphical user interface but by specifying the formatting textually using a specific textual notation. For instance, in the HTML markup language, a word or phrase that should be emphasized<\/em> is textually indicated by surrounding it with <em>\u2026<\/em>. HTML and other powerful markup formats like LaTeX and various XML formats carry relatively large overheads. They are complex to learn and difficult to read. (Typing raw XML is nobody\u2019s idea of fun.) Ideally, we would want a markup format to be lightweight<\/em>, that is, simple, portable, and human-readable even in its raw state.<\/p>\n

Markdown is just such a lightweight markup language. In Markdown, emphasis is textually indicated by surrounding the phrase with asterisks, as is familiar from email conventions<\/a>, for example, *lightweight*. See, that wasn\u2019t so hard. Here\u2019s another example: A bulleted list is indicated by prepending each item on a separate line with an asterisk, like this:<\/p>\n

 * First item\r\n * Second item<\/code><\/pre>\n
which specifies the list<\/p>\n