{"id":467,"date":"2015-11-18T18:46:53","date_gmt":"2015-11-18T18:46:53","guid":{"rendered":"https:\/\/tech.me.holycross.edu\/?p=467"},"modified":"2015-11-18T18:46:53","modified_gmt":"2015-11-18T18:46:53","slug":"theplaintextworkflow","status":"publish","type":"post","link":"https:\/\/blogs.holycross.edu\/tech\/2015\/11\/18\/theplaintextworkflow\/","title":{"rendered":"The Plain Text Workflow"},"content":{"rendered":"

(Microsoft Word must die.)<\/em><\/h3>\n

The Plain Text Workflow<\/a> is an alternative to writing with a word processor. Mind you, I said writing<\/em>, not typesetting or formatting, which is a major part of what word processors do. The idea of the plain text workflow is that you separate the act of writing from that of producing a formatted, typeset final document. You initially capture your words using a plain text editor<\/a>, perhaps using a lightweight formatting language like Markdown<\/a>. Then, using freely-available software such as pandoc<\/a>, you translate your plain text document into whatever file format you need to provide (to a colleague, reviewer, literary agent, journal editor, blog post, email, website, etc.), be it Microsoft Word, LibreOffice, PDF, HTML, or whatever. You might also bring this translated file into your word processor to continue tweaking the formatting. However, your original words<\/em> are captured in one or more plain text files, which remain the source from which various other document formats flow. With the plain text workflow, you work<\/em> in plain text, and all of those other document formats are outputs<\/em> from your plain text source document.<\/p>\n

<\/p>\n

This concept was described in 1999 by Allin Cottrell<\/a>:<\/p>\n

I am suggesting, therefore, that [there] should be two distinct \u201cmoments\u201d in the production of a printed text using a computer. First one types one\u2019s text and gets its logical structure right, indicating this structure in the text via simple annotations. This is accomplished using a text editor, a piece of software not to be confused with a word processor \u2026 Then one \u201chands over\u201d one\u2019s text to a typesetting program, which in a very short time returns beautifully typeset copy.<\/p><\/blockquote>\n

Although Cottrell was talking about printed copy here, he goes on to say that his remarks apply to digital documents as well.<\/p>\n

Writing in plain text\u00a0is not new, and dates back at least to 1978 when the TeX<\/a> computer typesetting system was created by Donald Knuth<\/a>. What is new is that writers are increasingly turning (or re-turning) to plain text because they are sick of having to deal with complicated, bloated, expensive word processing software<\/a>, proprietary file formats that constantly change, incompatibilities across word processor versions and computer platforms (including, now, smartphones, tablets, and other mobile devices), collaborators and co-authors who each use a different word processor, et sic porro<\/em>. Plain text files have been around since the birth of modern computing. HTML<\/a>, the foundation of the Internet and World Wide Web, is a plain-text markup language<\/a>. All computer programming source code<\/a> is written in plain text. And now, as W. Caleb McDaniel has written in Why (and How) I Wrote My Academic Book in Plain Text<\/a><\/em>, it \u201cseems like the ancient past of personal computing is becoming the wave of the future.\u201d<\/p>\n

A plain text file differs from a word processor file because plain text contains only the letters, numbers, and symbols that appear on a standard keyboard, known as the ASCII<\/a> character set. Word processor files, however, contain additional, invisible formatting commands that the software uses to produce fonts, text styles such as boldface and italics, bulleted lists, placeholders for endnotes, footnotes, and bibliographic citations, and so on. Each word processor vendor uses different formatting commands, such that a document file from one vendor\u2019s word processor cannot be used directly in another vendor\u2019s word processor. At the very least, the proprietary file format of word processor A needs to be converted into the proprietary format of word processor B. Often, the files cannot be read at all, or if they can, some of the formatting may be lost in translation.<\/p>\n

Plain ASCII text files, on the other hand, are universal and will be readable on any conceivable type of computing device that humanity will produce in the forseeable future. Although we are not sure at this time how much of the future is forseeable, the plain text format does alleviate all future and backward compatiblity issues. Plain text files are multi-platform: You can edit them on a Mac, iPad, iPhone, Windows PC, Android, Unix\/Linux, all without any compatibility worries.<\/p>\n

Without plain text files, if you are collaborating on a book with several co-authors and each uses a different word processor (Microsoft Word and Apple Pages and LibreOffice, say), then each author needs to use a different proprietary document format. This can complicate the process of collaboration, because in order for all authors to contribute to the book, each of their word processor file formats would have to be translated, then changes integrated back into the original document, raising the possibility of different versions of the same file getting mixed up, etc., etc. But if all authors are writing in plain text, the file compatibility problem is eliminated because every computer, and all editing software, can read and write plain text. One copy of the plain text document could be kept on a cloud storage medium, such as Dropbox<\/a>, and every co-author could then edit that same text file directly, using whatever plain text editing software they desired.<\/p>\n

And because it is \u201cubiquitously compatible and futureproof<\/a>,\u201d plain text is an excellent archival format. In Forget fancy formatting: Why plain text is best<\/a>, David Sparks writes:<\/p>\n

Although modern word processing programs can do some amazing things\u2014adding charts, tables, and images, applying sophisticated formatting\u2014there\u2019s one thing they can\u2019t do: Guarantee that the words I write today will be readable ten years from now.<\/p><\/blockquote>\n

If you\u2019ve ever dusted off a 3.5-inch floppy disk (or, God forbid, a 5.25-incher), and then dusted off your old external floppy disk drive, fired it up and retrieved that brilliant essay that you wrote in Wordstar<\/a> back in 1984, you know the problem. That old word processor format is no longer readable, because good old Wordstar has gone extinct. You could try opening the Wordstar file in a plain text editor, but all those proprietary formatting commands have turned your words into gibberish. If Wordstar had used the plain text file format, this problem would not exist.<\/p>\n

Another advantage of plain text is that it works well with version control systems<\/a> (VCS), software that writers can use<\/a> to archive and retrieve drafts of their writing projects. Long used by software developers to store and track changes in their programming source code<\/a>, VCSs such as Draft<\/a> are now available specifically for writers. Benefits of a VCS include tracking every change in a document; tracking writing experiments, while keeping the main file intact; tracking co-authoring and collaboration; and tracking individual contributions. The proprietary, often binary<\/a> file formats used for word processor files generally do not fare well in a VCS, but plain text files are what VCSs were designed for.<\/p>\n

There are distinct advantages to setting down your words in plain text instead of in a word processor. Because plain text editing software<\/a> is by design fairly minimal and uncomplicated, a writer can concentrate on writing and not be distracted by the myriad of formatting and typesetting options, icons, menus, widgets, gadgets, buttons, and other digitalia that a typical word processor presents. For example, here is a screenshot of Microsoft Word<\/a> running on a Mac:<\/p>\n

\"\"<\/p>\n

And the corresponding screenshot of MacDown<\/a>, a free plain-text Markdown editor for the Mac:<\/p>\n

\"\"<\/p>\n

Any questions?<\/p>\n

Another plus is that most computers come with a free editor for plain text, for example Notepad<\/a> for Windows and TextEdit<\/a> for the Mac. There are also many third-party free and paid text editors with added features, for Windows<\/a>, Mac<\/a>, iOS<\/a>, and Android<\/a>.<\/p>\n

Furthermore, plain text files can be used with reference management software<\/a>, such as RefWorks<\/a> and Zotero<\/a>, to insert literature citations into the text and to produce formatted bibliographies. While both RefWorks and Zotero have toolbar plugins for Microsoft Word, LibreOffice, and OpenOffice, which enable writers to access their references while writing with those word processors, they can also insert plain-text citation markers into plain-text documents. With a couple of additional steps those markers can be converted into formatted literature citations and bibliographies for both footnotes and endnotes. (Of course, users of LaTeX<\/a> and BibTeX<\/a> have been doing this for decades, but that’s another blog post<\/a>.)<\/p>\n

In addition to containing links to bibliographic databases, plain text files can include embedded computer code for producing data analyses, simulations, graphics, and other data-based content. For example, using programming statements from R, the open-source statistical and graphics platform<\/a>, along with a variant of the Markdown<\/a> language, one can write a single, plain-text document that will produce elegant formatting, an automatically generated table of contents, well-formatted mathematical expressions, tables, crisp figures, and an automatically generated bibliography (see this example<\/a>). With this approach (known as reproducible research<\/a>), your plain-text file becomes not only the source of your finished, typeset document, but also maintains a record of the data management and analysis steps taken to arrive at your final result.<\/p>\n

By now I hope that I have convinced you that there are numerous advantages to writing in plain text. We now turn to some examples of the plain text workflow.<\/p>\n

Examples of the Plain Text Workflow<\/h3>\n

The following examples use Markdown<\/a> as the starting point. The name Markdown<\/em> is a play on the word markup<\/a>. Probably the most well-known markup language is HTML<\/a>, or hypertext markup language, which is used to \u201cmark up\u201d a plain text file to create Web pages. HTML creates its markup with \u201ctags.\u201d If you look at a list of HTML tags<\/a>, you will see that there are a lot of them. Markdown, in contrast, is what is known as a lightweight<\/a> markup language, having a simple syntax that is easy to create using any text editor. Because it has a lightweight syntax, Markdown is easy to read in its raw form, unlike markup languages such as HTML and XML<\/a>.<\/p>\n

Here is an example of a Markdown file. Click here<\/a> to view this file rendered as HTML. You could also copy-paste the Markdown text into a Markdown-friendly editor, like MacDown<\/a>, and be able to view the\u00a0original Markdown and its HTML rendering side-by-side. Sadly, WordPress.org does not let me install my own custom CSS<\/a> and so you will have to live with the fact that this text box does not word-wrap.<\/p>\n

\n# A Markdown Example<\/code> ## Markdown ### Markdown #### Markdown Paragraph breaks are simply blank lines. Four score and seven years ago our fathers brought forth on this continent a new nation, conceived in liberty, and dedicated to the proposition that all men are created equal. A blockquote is the greater-than symbol: > Now we are engaged in a great civil war, testing whether that nation, or any nation so conceived and so dedicated, can long endure. We are met on a great battlefield of that war. We have come to dedicate a portion of that field, as a final resting place for those who here gave their lives that that nation might live. It is altogether fitting and proper that we should do this. But, in a larger sense, we can not dedicate, we can not consecrate, we can not hallow this ground. The brave men, living and dead, who struggled here, have consecrated it, far above our poor power to add or detract. The world will little note, nor long remember what we say here, but it can never forget what they did here. It is for us the living, rather, to be dedicated here to the unfinished work which they who fought here have thus far so nobly advanced. It is rather for us to be here dedicated to the great task remaining before us\u2014that from these honored dead we take increased devotion to that cause for which they gave the last full measure of devotion\u2014that we here highly resolve that these dead shall not have died in vain\u2014that this nation, under God, shall have a new birth of freedom\u2014and that government of the people, by the people, for the people, shall not perish from the earth.[^1] [^1]: Abraham Lincoln wrote this. Subsequent lines of the footnote need to be indented. A jump from the footnote back to the text is conveniently generated. Or else they are not considered to be part of the footnote. Thus is we keep typing, and if we insert another footnote, like right here[^2], we get another footnote. [^2]: And here is the material for the second footnote. You can insert plain-text bibliographic citations into a footnote, as we are doing right here[^3]. In this case the footnote contains a citation marker pasted in from RefWorks, which we will later format. [^3]: {{816 Wang,Jiawu 2014;}} Indentation is produced by multiples of `<space><space>*<space>`. (And notice the use of the backtick character to delimit use of a monospaced font.) * So here is some indentation. * More indentation. * And more. * Useful for outlines. Numbered lists? Just type them: 1. First line. 2. Second line. 3. Third line. The numbers are produced automatically by the MacDown editor. For \"code blocks,\" which are blocks of monospaced text, indent every line of the block at least 4 spaces or 1 tab: Like this. These are handy for inserting examples of computer code statements or for simply setting off blocks of text for extra emphasis. And now we are back to normal text, because we are no longer indenting 1 tab space. A hyperlink looks like this: [College of the Holy Cross](http:\/\/www.holycross.edu) An image link looks like this: ![trout](http:\/\/live-hcblog.pantheonsite.io\/tech\/wp-content\/uploads\/sites\/2\/2015\/11\/wpid-fish.jpg) More information on Markdown and its syntax can be found [here](https:\/\/daringfireball.net\/projects\/markdown\/).<\/pre>\n
We will not dwell on all of the details of Markdown syntax<\/a> here. Suffice it to say that Markdown provides a lightweight markup language that allows you to create a plain text source document on any text editor, on any computing device. The aim of the plain text workflow is to provide a simple means of setting down words efficiently. As mentioned earlier, keeping this Markdown file on a cloud storage account such as Dropbox would make it accessible, and editable, from any computing device that was synced to the Dropbox account, including mobile devices.<\/p>\n
Using the MacDown<\/a> editor, we can export this Markdown file to either HTML or PDF. However, the pandoc<\/a> file conversion utility lets us convert Markdown files to any of the major word processor document formats (as well as a number of other formats). These include HTML, docx, ODT, EPUB, LaTeX, and PDF.<\/p>\n
Pandoc is free and runs on all major computer platforms. Installation instructions are here<\/a>, and the essential instructions can be found here<\/a>. Greatly more detailed instructions are here<\/a>, meant for people who are \u201ccommand-line experts.\u201d<\/p>\n
Yes, pandoc is a command-line<\/a> tool. There is no graphical user interface, no menu system, no point-and-click to pandoc. It\u2019s a blinking cursor, waiting for you to type a command. But do not be afraid. We will work through a simple example, which most of the time will be all that you need.<\/p>\n
Once pandoc is installed, you need to open up a terminal window, also called a command prompt or command shell. The exact way you would open up a command-line interface will vary according to your computer platform, but all of them basically look something like this:<\/p>\n
\"shell\"<\/p>\n
To verify that pandoc is installed correctly, type:<\/p>\n
pandoc --help<\/code><\/p>\n
and you should see something that looks like:<\/p>\n
10-100-41-44-vlan40:~ rlent$ pandoc --help\npandoc [OPTIONS] [FILES]\nInput formats:  native, json, markdown, markdown_strict, markdown_phpextra,\n                markdown_github, markdown_mmd, rst, mediawiki, docbook, textile,\n                html, latex\nOutput formats: native, json, docx, odt, epub, epub3, fb2, html, html5, s5,\n                slidy, slideous, dzslides, docbook, opendocument, latex, beamer,\n                context, texinfo, man, markdown, markdown_strict,\n                markdown_phpextra, markdown_github, markdown_mmd, plain, rst,\n                mediawiki, textile, rtf, org, asciidoc\n<\/code><\/pre>\n
followed by a list of command-line options. You can see in the above help listing all of the input file formats that pandoc can convert to the various output formats.<\/p>\n
Let\u2019s try converting our markdown file, which is named Markdown.md, to a Microsoft Word docx file. The conversion command is as follows:<\/p>\n
pandoc -s -f markdown -t docx Markdown.md -o Markdown.docx<\/code><\/p>\n
The first item typed on the command line is the name of the application, pandoc. The other items are command-line options, and are simply a sequence of options telling pandoc what we want it to do. Thus the -s<\/code> means we want a \u201cstandalone\u201d file, that is, a complete file and not just a piece of a file. The -f<\/code> means \u201cfrom,\u201d meaning we want to convert from Markdown (the next item) to (the -t<\/code>) a docx file (Starting to get it?). Next is the name of the input file (Markdown.md), followed by -o<\/code> for \u201coutput,\u201d then the name we want to give to the converted file (Markdown.docx).<\/p>\n
For all of this to work, you need to be in the folder (directory) of your computer\u2019s filesystem where the input file is located. In the command window you would have to use the cd command<\/a> to navigate to the proper location. See Getting started with pandoc<\/a> for more details.<\/p>\n
Assuming that everything worked, you should now have a file called Markdown.docx, which if opened in Microsoft Word should look like a bona fide Word file, with proper formatting as created in the original, plain-text Markdown file.<\/p>\n
What if a colleague didn\u2019t have Word and instead wanted a PDF file? Just type:<\/p>\n
pandoc -s -f markdown Markdown.md -o Markdown.pdf<\/code><\/p>\n
Pandoc can figure out that you want PDF output by the filename extension specified on the output file.<\/p>\n
Referring back to our original Markdown file, what about that third footnote, with the citation marker? The footnote looks like this:<\/p>\n
[^3]: {{816 Wang,Jiawu 2014;}}<\/code><\/p>\n
This was inserted using RefWorks, and we need to format that bibliographic reference properly. For this, we need to convert the Markdown file to Microsoft Word format, which is one of the word processor formats that RefWorks supports. We have already done this, and the file is called Markdown.docx. After logging in to our RefWorks account, from the Bibliography menu we choose Format Document, and get a dialog that looks like this:<\/p>\n
\"ref\"<\/p>\n
We select our Markdown.docx Word file, upload it, and in return we get another Word file with the footnoted citation properly formatted in our chosen bibliographic style, which in this case is Chicago Manual of Style 14th edition:<\/p>\n
\"cit\"<\/p>\n
Parting Thoughts<\/h3>\n
Other workflows, of course, are possible. You could capture your words in longhand with pen and paper and then type your manuscript into a computer file. You could dictate into a computer or smartphone, and software will automagically convert your spoken words into text. If you write exclusively on one computer, are happy with your word processing software, and you\u2019re getting published, then that system is working and you may not want to mess with it. If a group of co-authors all agree to use the same word processing software, then the collaborative writing project is made easier. (Unless the word processor vendor goes out of business, changes its file format, or releases a new version of the software that no longer works with your favorite reference manager.) You should use whatever writing workflow enables you to initially capture your words, edit them, and then produce a finished product, be it printed on paper or stored in a digital file.<\/p>\n
Like many things in computing, the plain text workflow is just one of numerous options. (Remember that Yahoo<\/a> stands for Y<\/strong>ou A<\/strong>lways H<\/strong>ave O<\/strong>ther O<\/strong>ptions.) But unlike many of the alternatives, plain text has been around a long time, will continue to be around, and is resistant to change. Using the tools described here, the plain text workflow can give you \u201cthe reckless freedom to write anywhere<\/a>.\u201d<\/p>\n
This blog post was written in Markdown<\/a> using the MacDown<\/a> editor on an iMac and the Byword<\/a> editor on an iPhone 6 Plus. The Markdown file\u00a0was stored on Dropbox<\/a> and was uploaded directly to WordPress.org<\/a> via the Byword iOS app.<\/p><\/blockquote>\n","protected":false},"excerpt":{"rendered":"
(Microsoft Word must die.) The Plain Text Workflow is an alternative to writing with a word processor. Mind you, I said writing, not typesetting or formatting, which is a major part of what word processors do. The idea of the plain text workflow is that you separate the act of writing from that of producing … <\/p>\n
Continue reading “The Plain Text Workflow”<\/span><\/a><\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[6,7],"tags":[],"class_list":["post-467","post","type-post","status-publish","format-standard","hentry","category-software","category-writing-tools"],"_links":{"self":[{"href":"https:\/\/blogs.holycross.edu\/tech\/wp-json\/wp\/v2\/posts\/467","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/blogs.holycross.edu\/tech\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/blogs.holycross.edu\/tech\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/blogs.holycross.edu\/tech\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/blogs.holycross.edu\/tech\/wp-json\/wp\/v2\/comments?post=467"}],"version-history":[{"count":0,"href":"https:\/\/blogs.holycross.edu\/tech\/wp-json\/wp\/v2\/posts\/467\/revisions"}],"wp:attachment":[{"href":"https:\/\/blogs.holycross.edu\/tech\/wp-json\/wp\/v2\/media?parent=467"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/blogs.holycross.edu\/tech\/wp-json\/wp\/v2\/categories?post=467"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/blogs.holycross.edu\/tech\/wp-json\/wp\/v2\/tags?post=467"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}