Plain Text Writing Lesson Seven: Markdown Resources and Editors

The first six lessons in my series on plain-text writing should be enough to get anyone–even the least techy–started with a complete plain-text writing workflow, using Gedit, markdown syntax, and Pandoc.

Editing Markdown in Typora, an elegant editor for Linux, Windows, and MacOS

But I’m not done with the series look for more to come on editors, operating systems (and why you should seriously consider Linux), more advanced editing and markup with the amazing text editor emacs and orgmode, keeping a plain-text note system, and even ways to ditch the computer altogether but still take advantage of digital technologies in your writing. Also look for posts on other, more fun things you can do, like creating a whole-house music server with an old laptop, creating a writing computer you can take into direct sunlight using an old netbook and e-ink Kindle, the joys of the command line and terminal, and lots of other geeky fun tailored to the non-computer-geek user and writer. My goal is to make this incredibly useful technology accessible to everyone, especially those who don’t always feel comfortable with the kind of documentation that’s usually found online.

In the meantime, here are a few sets of additional resources: a breakdown of my own series so far, some important general resources for Markdown, and some recommendations for exploring the wide range of editors out there to find the one that’s perfect for how you work.

My Articles:

Here’s a complete index to my complete series so far on plain-text writing:

• Lesson One: Writing in Plain Text: A Tutorial for the Non-Techy Writer: A general introduction to plain-text and explanation of its potential benefits for writers, especially over and above the traditional word processor.
• Lesson Two: The Editor: How to download, install, and use a good all-around text editor called “Gedit”
• Lesson Three: Markdown Elegance: An introduction to using Markdown syntax, geared toward the total beginner.
• Lesson Four: Pandoc Magic: An introduction to Pandoc, a tool that allows you to convert your plain-text, markdown-enhanced documents to any other file format you want (Word, LibreOffice, PDF, html, etc.)
• Lesson Five: Detangling Your Footnotes: How to create footnotes within a Markdown document, and why doing so makes them easier to manage than with a traditional word processor.
• Lesson Six: Citation Wizardry: For the harder-core academics, this lesson covers how to do more complex citation and documentation management, pairing your markdown text with a citation manager such as Zotero, RefWorks, or Endnote. Most importantly, the lesson explains why and how managing citations this way can get rid of a lot of common citation headaches.

Markdown Resources:

• The definitive resource on Markdown syntax, from its creator. A little more techy than my explanation, but important as the font from which springeth all things Markdown.
• A very handy Markdown cheatsheet on github. Especially useful for beginners, for reference until you get used to the syntax you use most often (which won’t take long at all), and too keep handy for those times when you need to look up something that you don’t use as often. Put it in a text file you can pull up in your editor, or have a printout on your desk for reference. You’ll find that you don’t really need it after only a few writing sessions.
• A nice little interactive markdown tutorial: Another very beginner-friendly tutorial that lets you try things out right in the browser as you go. If you’re still nervous about learning Markdown, start here.

Some Good Text Editors

Taste in text editors varies between writers and coders like taste in flavors of ice cream. There are a lot of choices out there, making it worth your while to explore and find one you really like. Some are more general purpose, some more specifically targeted. The general rule of thumb is that the editors that are the most graphical and simplest to use are often one-trick ponies–good for one thing but not much else. Editors that are more versatile and customizable tend to have a steeper learning curve, but the reward for the learning curve is a lot more ability to customize your editor to your particular needs and style of working. I suggest starting with an easy-to-use, simple editor first, but then experimenting with some of the more advanced editors to see what they can offer. I learned both vim and emacs very slowly, just experimenting with each a few minutes at a time, looking around at online documentation, and not worrying about doing anything with them right away. As a result, I’ve discovered ways to enhance my writing process that I’d never imagined.

Here’s a set of links to the editors I’ve found the most useful:

Gedit: I think Gedit offers about the best balance of features, simplicity, and ease of use. Definitely my recommended editor for beginners, and adequate for more advanced markdown users as well. – Also on the “easy but less versatile” spectrum, but also very useful for beginners, are specialized markdown editors that provide features like a dual-pane view that gives you an immediate preview of your markdown.

Typora is one of my favorites, offering live preview, and the ability to convert your markdown to various other document types right onboard. Especially good for those who want to use Markdown but who find the command-line interface of raw Pandoc intimidating.

For Windows users, Markdown Pad is one of more mature go-to-options. It also features a dual-pane view, where you write your markdown on the left side and see a live

Using the live preview feature in MarkdownPad for Windows.

preview of the result on the right. There are both free and paid versions. The free one is very nice as an editor, and the paid version offers automatic conversion features, among other enhancements.

For those who desire a very distraction-free experience, WriteMonkey is a lean and elegant cross-platform writing app, with versions for Windows, Mac, and Linux alike. WM is designed to give you clean, minimal, full-screen interface, and supports Markdown. While it doesn’t give you a live preview like the previous two, it does feature syntax highlighting, which helps you keep track of your formatting.

Another great condender in this category is FocusWriter, a ‘zenware’ editor that really concentrates on a clean composition experience.

If you need or want to be able to work from anywhere within your browser (working on a borrowed computer, a public computer, or a Chromebook, for instance), I can’t recommend StackEdit highly enough. It gives you a real-time preview, seamless integration with cloud storage services like Dropbox, and–most useful for bloggers–the ability to publish directly from the app to your WordPress account. Stackedit is a chome app that runs in your browser, so you can work from any internet-connected device.

Other editors offer a more technical approach and are oriented toward writers of both code and prose.

My favorite of these is SublimeText. It’s probably the most elegant code and text editor out there, looks fantastic, and is extensible in ways few can imagine. It can provide tons of functionality, there’s a little bit of a learning curve, but it’s not that hard. One

Elegant editing in Sublime Text (here in Ubuntu Linux)

drawback is that ST is not technically free software. You can download a fully-functional evaluation copy to use for as long as you like (it’ll remind you occasionally about buying a license), but if you decide it’s the right editor for you and use it a lot, do the honest thing and pony up the (expensive but well-worth-it) $70 license.

For windows users, another contender in this category is the venerable Notepad ++, which has been a mainstay of coders and writers alike for many years.

A newer player in this category of editors is Atom, and is probably the best-looking editor in this list. It has similar functionality and complexity to Sublime Text, but is free and open-source, which makes it a preferable options for many. Like Sublime Text, it’s primarily geared toward coders, but has extensions that make it quite nice for writing if you’re willing to deal with a bit of a learning curve.

The Hardcore Options: Vim and Emacs

One thing I’ve learned about software since learning to program my first-ever computer (a Commodore 64!) in junior high: it’s always a trade-off. The easier an app is to use, the less versatile and powerful it will be. The higher the learning curve, the more powerful the app, and the more customizable to your own experience. The question to ask yourself is this: Do I want to work the way someone else thinks I should work, or do I want to work the way I want to work? If the answer is the latter, you owe it to yourself to look into one of the editors that takes a little while longer to learn, but gives you undreamed-of control, flexibility, customizability (is that a word?), and speed. There are really two major editors that fall into this category. While I started out with several of the editors listed above, I have to admit that these two have become my favorites, and my go-to editors for almost everything. They take a little more time and effort to learn–but once you learn them, wow–gangbusters! Each will get a post of its own here, but for the being short descriptions will have to suffice:

Vim is actually one of the oldest pieces of software still in continuous development, initially developed as an editor for the Commodore Amiga in the late 1980’s. It’s come a long way since then, but it’s a powerhouse that many coders and writers alike still swear by. It’s an app that runs without a GUI (that is, a “graphical user interface,”although there are GUI versions available), which means that it runs, regardless of platform, in a

Minimalist and lighting fast, but still powerful: Vim running on my desktop.

terminal window. One advantage of this is that it makes Vim the most blazingly fast editor on this list. Up and running in a keystroke. Its interface is keyboard-oriented, which means you never reach for the mouse, keeping your mind and hands on your writing. It doesn’t look like much, but the advantage is that it gets the heck out of your way and lets you compose and navigate easily through even long, complex documents. There’s a great beginner’s tutorial here if you’re interested in getting started. Look for a post from me on customizing it for writing.

Emacs is the other biggie in this category. Like vim, there’s a steeper learning curve associated with emacs, but I can tell you this: when I finally committed myself to learning emacs and discovering what it could really do, my reaction was “where have you been all my life?” I’m a little angry with computer scientists and programmers, truth be told, because they’ve been keeping all the best writing tools for themselves without letting

This blog post in Spacemacs, a variant of Emacs.

we writers know about them! Emacs definitely has a learning curve, but, in conjunction with a plugin called orgmode, it is hands down the most powerful tool for both note-taking and composition I’ve ever found. In fact, I wrote this post in a variant of Emacs called Spacemacs. I’m going to dedicate a whole series to Emacs later on, but, for now, there’s a good introduction for beginners here.

That’s it for now–have fun playing with the various editors and discovering more. And, as always, happy writing!

Advertisements

Plain-Text Writing Lesson Six: Citation Wizardry

Note: if you’re new to this series or to plain-text writing in general, please refer to Lesson One of this series to get started.

As I mentioned in the previous lesson, one of the biggest pains for me in academic writing is dealing with what happens to footnotes and citations in Word documents over the course of my writing process. Every piece I write goes through many stages of life: it starts as random jottings, becomes a general “idea draft,” then becomes a conference paper or a blog post, then an article or chapter, then a presentation, etc. Each of these versions goes through several revisions and I don’t know how much editing and refining. This means that citations get dropped, added and moved around; whole sections of one version get cut and pasted into another, sections get moved around, etc. And, of course, as I adapt a certain course of research to various publications and audiences, the style and formatting of the citations changes: one venue wants Chicago style footnotes, one wants endnotes, one wants MLA, ad nauseam.

One of the main issues that drew me to a plain-text workflow was what kept happening to my footnotes in word processors (Word and LibreOffice, for the most part), as my writing went through all these convolutions: it seemed that every time I moved things around or changed formatting, something would get messed up. When I converted from footnotes to endnotes or back again, the process never seemed to work as advertised, and I’d spend hours cleaning up formatting and manually fixing citations, even when using a citation manager like EndNote or Zotero (and sometimes because of the ways in which auto-inserted citations can get screwy when edited manually). If I needed to change style from MLA or Chicago or back, I’d wind up needing to go through an entire document and redo all the notes from scratch. All of this is not to mention the “cascade” effect, which I suspect you’ve experienced, of changing something in one note only to somehow throw off the formatting of the rest of them, or having note formatting fail to behave as expected, or even having notes change position or show up in the wrong place. There’s nothing more frustrating than pushing a deadline for an article only to find one’s self wrangling unruly citations.

There’s a better way.

Enter Pandoc once again, with some special extensions.

As with other elements of markdown writing, the idea here is that you insert citations as plain text right in line with the rest of your plain-text document. This means, for one thing, that citations always stay where they’re supposed to, even when you’re moving blocks of text around. The actual formatting of citations into different documentation and note styles (in-text citations, footnotes, endnotes, MLA, Chicago, APA, etc.) is something that only happens after your document is finished and ready to be prepared for publication. Just as you can transform any markdown document, via pandoc, into any digital format (Word, PDF, html, etc.), you can convert the plain-text, inline citations in any markdown document into any desired documentation style, without changing the original text. If you output to Word format at one point and then, say, make major edits and move sections around in your original plain-text document, you simply convert the plain-text document again and everything stays where it should and looks like it should with very little, if any, fuss.

Making this work might seem a little bit complicated at first, but I’ll try to detangle the process for you here. It’s really quite quick and efficient once you get the concept.

One thing I’ll assume in this post is that you’re already familiar with or using a citation manager such as Endnote, Zotero, or Refworks (I prefer Zotero). If you’re not, you’re really missing out on a handy tool, so I’d certainly recommend doing a little research and installing a citation manager that works for you. Zotero is clean, effective, versatile, as well as free and open-source, which is why it’s my manager of choice. In what follows, I’ll demonstrate the process with instructions for Zotero where needed, but everything I do with Zotero should be easily adaptable to the citation manager of your choice.

Step One: Enhance the Magic Wand:

To make citations work with pandoc, you need one additional tool, an extension to pandoc called pandoc-citeproc.

In any Debian-based version of linux, you can install this simply be opening a terminal and typing:

sudo apt-get install pandoc-citeproc

If you already installed pandoc in Windows, you should already have the pandoc-citeproc package, since it’s included in the Windows MSI installer, which you can find here.

Step Two: Gather the Elements:

In order to fully process citations in markdown, you need three elements:

1. A bibliography file in bibtex format that will live in the same directory as your main markdown document. This is the file from which pandoc will draw the actual bibliographic data.
2. Your markdown document itself, with correctly formatted citation placeholders (concerning which more below).
3. A .csl file containing the formatting information for whatever documentation style you need or prefer.

Let’s set up these elements one by one:

A Bibliography File in Bibtex Format

This is quite easy to do. Assuming you’ve been keeping your bibliographic data in your citation manager, all citation managers have the ability to export a collection of citations into Bibtex format. In the case of Zotero, the procedure is:

1. Open your Zotero app
2. Right-click on the collection you want to export and select “Export Collection”
3. In the ensuing dialog box, select “Bibtex” as your format, and click OK
4. Specify a location for your bibliography file–this should be the same folder in which your draft document resides.
5. Name the file whatever you like, and make sure it has a “.bib” extension.

This file will simply live alongside your text file in the same folder, so the citation information it needs is always handy. If, in the source of revising, you wind up adding sources to the original collection in your citation manager, simply delete the old .bib file and re-export the updated collection.

Format Your Citations As You Write and Revise

Dropping in-line citations into your document as you go could not be easier. Start by opening up your exported Bibtex file. As with the other components of this process, it’s also essentially a plain-text file, with no hidden formatting. You’ll see that each of your bibliography items is recorded as a record with several fields, like this:

 @book{gransden_historical_1974,
    location = {Ithaca, N.Y.},
    title = {Historical writing in England},
    isbn = {0-8014-0770-2 978-0-8014-0770-3 0-8014-1264-1 978-0-8014-1264-6},
    number = {Book, Whole},
    publisher = {Cornell University Press},
    author = {Gransden, Antonia},
    date = {1974},
    keywords = {chronicle, laercost}
}

You see that the record starts with an indication of the type of source (book, article, etc.). The next piece of information in each record is the most important for our purposes, the one that reads grandsen_historical_1974. This is called the citekey for this record–the unique ID that allows pandoc to differentiate it from every other record in the file. Dropping a citation into your document is very straightforward:

1. Open a square bracket: [
2. Type an @ symbol followed by the desired citekey
3. Add any needed text or page numbers before and after the citekey.
4. Close the bracket.

So, a normal citation would look like this:

Here is a brilliant sentence that requires a citation.[@grandsen_historical_1974]

That’s it. That citekey will follow that sentence wherever it goes.

If you want to add other information, such as discursive text, page numbers, etc., just add that text where you need it. Separate the page numbers from the citekey with a comma:

Here is a brilliant sentence that requires a citation.[If you need some discursive text, just add it inside the brackets before the citekey. See @grandsen_historical_1974, pp. 147-52]

If you need to include more than one citation, separate the citekeys with semicolons:

Here is a brilliant sentence that requires a citation.[Some discursive text. See @grandsen_historical_1974, pp. 7-9; also @anzaldua_borderlands:_2007, pp. 153-8]

Easy, yes? Once again, these citation placeholders will follow your text no matter what you do with it, just like any other kind of markdown formatting.

Grab The .csl File For Your Documentation Style

This might seem a little tricky at first, but it isn’t. The .csl file is simply a file that contains all the instructions for how final citations should be formatted according to a particular style (Chicago, APA, etc.). You can get a pre-made .csl file for most documentation styles from the Zotero Style Repository here. Simply find the style you want, click the link, and download the file into the same directory as your main text file and your bibtex file.

And Now, the Magic: Creating Fully-Cited Documents With One Swish:

Okay, now that we’ve got all the materials together, it’s time to tell Pandoc to do its thing. Let’s start with a sample markdown document with some citation placeholders included:

 

Now we just need to tell Pandoc to put all the pieces together. At this point we should have three files in our document directory: Our text file, the .csl file for our chosen documentation style (I normally need the Chicago Full-Note and Bibliography style, so I’ve downloaded that one for this example), and the bibtex file containing our references, like so:

MyDocument.md
MyBibtexFile.bib
chicago-fullnote-bibliography.csl

Here comes Pandoc. Fire up a terminal and type:

pandoc MyDocument.md -s -S --bibliography MyBibtexFile.bib --filter pandoc-citeproc --csl chicago-fullnote-bibliography.csl -o MyFormattedDocument.odt

Let’s break down what each part of the command is doing:

• pandoc simply invokes the pandoc app.
• MyDocument.md tells pandoc which markdown document to process
• -s -S These two tags tell pandoc to create a standalone document file, and to use smart quotes, respectively
• --bibliography MyBibtexFile.bib Points pandoc to your bibliography file.
• --filter pandoc-citeproc tells pandoc to use the pansdoc-citeproc tool to process your citation placeholders
• --csl chicago-fullnote-bibliography.csl tells pandoc to format your citations according to the information in the chicago fullnote bibliography csl file, and points it to that file.
• -o MyFormattedDocument.odt tells pandoc to output to an .odt (LibreOffice, OpenOffice) file named “MyFormattedDocument.odt” If you want a different file type, just change the extension (.docx for Word, .pdf for Portable Document Format, etc.)

And here’s the reveal, your fully formatted document:

But let’s say (alas!) one publisher turns down that manuscript. You want to submit it elsewhere, but the new journal to which you’re submitting requires MLA rather than Chicago style. No problem–and no need to do anything with my original text document. I simply download the MLA 8th edition .csl file from the Zotero Style Repository, and change the pandoc command to use that stye:

pandoc MyDocument.md -s -S --bibliography MyBibtexFile.bib --filter pandoc-citeproc --csl modern-language-association-8th-edition.csl -o MyFormattedDocument_MLA.odt

And my output looks like:

There it is! While this tutorial takes a little longer to explain the process than some of the others, I hope it’s apparent how easy and muss-free this can be if you set it up as your workflow from the beginning. As always, I’m glad to field questions about the process. Happy writing!

Plain Text Writing Lesson Five: Detangling Your Footnotes

Note: This is the fifth instalment in a series of brief lessons on writing with plain text tools, such as basic text editors, Markdown syntax, and Pandoc. The lessons are designed with the non-techy in mind, and are meant to
take about 5-10 minutes apiece to digest. If you’re unfamiliar with plain-text tools, I strongly recommend that you begin with the first lesson. This lesson deals with notes for which you’re hand-keying all the text. If you’d like to use footnotes or other documentation styles with a citation manager like Zotero, please refer to Lesson Six: Citation Wizardry.

Footnote Foofaraw

Now that we’ve got the basics of plain-text writing, using markdown syntax, and invoking pandoc for formatting, let’s tackle one of the more complex bugbears of writing, especially for academic writers: footnotes.

If you’re accustomed to using a traditional word processor such as Word or LibreOffice Writer, you’re aware that the initial steps for including footnotes are pretty easy: select “footnote” from an “insert” menu or hit a keyboard shortcut, an auto-numbered note shows up at the bottom of the page, and you type happily away (or insert a note or placeholder code from a citation manager like Zotero or Endnote). Easy peasy.

As you’ve likely experienced if you’ve done a lot of heavily-footnoted writing, however, the problem isn’t about adding the notes initially; it’s about maintaining their continuity and formatting down the line. This isn’t such a big deal for shorter-form writing (like blog posts), but it can be a very big deal indeed for longer, more in-depth work, such as articles and book chapters. The problem is that those longer pieces tend to travel a great deal before reaching their final (published) destinations: they go back and forth between writers, peers, peer-reviewers, editors, publishers, etc. As with all of the complex coding that underlies a word processor document, irregularities have a way of creeping in as the document is continually emailed, opened under different platforms or tools, edited and modified, etc. This process can turn those easily-added footnotes into a nightmare: if you’ve ever had the problem of suddenly finding that your notes are out of sequence, or that the formatting has suddenly changed and no change in settings seems to bring them back into order, you know what I’m talking about.

Markdown and Pandoc to the Rescue, Again

What’s handy about Markdown here is basically the same principle outlined in lesson three: You keep your original document in a kind of “raw” format in which everything is consistent, and then use Pandoc to turn that universal format into any other format an editor, publisher, or friend might require. In this way, your preferred formatting, and the position and style of your footnotes, is essentially always preserved in a consistent state in your original markdown document. Changes can be made easily in that Markdown document without any possibility of unintentionally adding code that will affect your formatting down the line. In other words, using Markdown and Pandoc together can mean that you’ll never again need to tear your hair out when your notes go haywire.

The How-To Bit

There are two different ways to create footnotes using Markdown. The first is entirely native to Markdown, and is ideal for shorter-form writing for the web (i.e. blog posts). The second requires Pandoc, but is ideal for longer-form writing where maintaining the consistency of many footnotes is important.

The Markdown Way

To create a basic Markdown footnote, place your cursor where you want the footnote to appear in your text and start with an open bracket, followed by a caret, a footnote name or number, and a close bracket, like this:

[^1]

Then, at the bottom of your main text, place the same sequence of characters again, followed by a colon, a space, and then the text of your note:

[^1]: Here is the text of the footnote.

In the final document, markdown will create a footnote at the bottom of your text that includes a link back to the in-text footnote marker, like this.¹

This sort of footnote is excellent for web-oriented writing, since it assumes a contiguous text (i.e. no page breaks) and provides an easy way for readers to click back and forth between the superscript note indicators in the text and the notes themselves at the bottom.

However, it’s not difficult to see how these footnotes can become unwieldy with longer, more print-oriented documents with many footnotes. For one thing, creating them would mean constantly scrolling up and down your ever-expanding main text. For another, adding footnotes would mean manually re-numbering every note that comes after the newly added one. Talk about a pain!

Inline Footnotes in Pandoc

Luckily, we’re not stuck with native Markdown footnotes if we have Pandoc, which was introduced in Lesson Four.

Pandoc allows us to create inline footnotes, which are much more convenient for print-oriented writing that utilizes numerous notes and citations. To create an inline footnote, one simply places a caret at the point one wishes the superscript footnote indicator to appear, follow by the content of the note in brackets, thus:

##Using In-Line Footnotes with Pandoc

Here is my main text, rolling along and expressing its usual brilliance, followed by an inline footnote.^[Footnotes are cool.] As I continue to write, I can place additional footnotes using the same format.^[Cool like bow ties and fezzes]

When I run this through Pandoc, using the procedure outlined in Lesson Four, and open the resulting formatted text in a word processor (LibreOffice in this case), I get this result:

Output from Pandoc viewed in LibreOffice Writer.

Note that Pandoc has automatically formatted and numbered the inline notes. It gets better. Let’s say I need to add a sentence to the above text that requires an additional note between the two initial ones, like this:

##Using In-line Footnotes with Pandoc

Here is my main text, rolling along and expressing its usual brilliance, followed by an inline footnote.^[Footnotes are cool.] I might even need to add a sentence that needs its own note later on.^[No, I'm not a *Doctor Who* fan. Why do you ask?] As I continue to write, I can place additional footnotes using the same format.^[Cool like bow ties and fezzes.]

Here’s the new output from Pandoc:

Pandoc output from edited original document.

Notice that Pandoc has inserted the new note and automatically renumbered the other notes to accommodate my addition.

The value of creating notes this way for longer, more heavily-annotated documents should be apparent: instead of dealing with an “insert note” function at all, one simply creates all one’s footnotes right in line with the text, keeping the flow of thought contiguous and avoiding unnecessary keyboard commands. No matter how much the plain-text document is edited, and no matter how many notes are added or deleted in that process, running the plain-text document through Pandoc again will always renumber footnotes automatically, meaning that the output from Pandoc will always be a “fresh” word processor document, with all the formatting and numbering of notes perfectly consistent. No more fiddling around with footnotes that seem to have a mind of their own.

There can be even more flexibility when inline notes are used with a citation manager, which we’ll tackle in a future lesson.

For now, your five-minute assignment is to create a sample document with both native markdown and Pandoc inline footnotes (if you don’t remember how to use Pandoc, refer back to Lesson Four, linked above). Or, better yet, try out the note functionality in some of your normal writing.

---

1. Click on the arrow at the end of this note to return to the note’s position in the main text.  ↩

Plain Text Writing Lesson Four: Pandoc Magic

Pandoc: The Magic Wand of Sustainable Document Conversion

Now that you’ve had some fun playing with a great text editor like Gedit, and have played around with Markdown syntax, it’s time to work a little magic on your plain-text writing.

Think of Pandoc like a magic wand: it’s a tool that takes your markdown text files and, with a few words, transmutes them into fully-formatted documents in the format of your choice (or the format required by a publisher). You can output to many different file types, including .docx (the native Word format), .odt (the native format for Openoffice and LibreOffice), .rtf (Rich Text Format, readable by many different applications), ,html (the format for web pages and blogs), and even (with a few software additions) PDF.

The one drawback of Pandoc, for the non-techy person, is that it’s a command line tool. In other words, there’s no snazzy graphical interface with pretty buttons to click. It works entirely with text commands inside a terminal window.

A terminal is simply an application on your computer that allows you to interact with it via text commands rather than graphical buttons. If you’re old enough to have worked with programs in MS-DOS, you’re already familiar with a command-line interface. There are two great things about command-line tools:

• They’re incredibly fast. They tend to start instantly and work very quickly, just like your compact text editor.
• They can be even more powerful and offer more options and functions than graphical tools. Think about it this way: a graphical tool is limited, in many ways, by the amount of space it takes up on your screen: there’s only room for so many buttons. A command-line tool can have as many available functions as its creator can imagine.

The drawback is the flip side of the advantages: you have to learn the text commands.

Luckily, you can do basic conversion with Pandoc with only a few commands, so it’s pretty darned easy.

Getting Pandoc

Let’s start by downloading and installing Pandoc.

• Go to this page.
• Scroll down until you see two large green buttons.
• If you have a Windows computer, click the one that says “pandoc-1.13.1-windows.msi.”
• If you have a mac, click the one that says “pandoc-1.13.1-osx.pkg.”

Go ahead and install the downloaded file (the one assumption I’m making is that you know how to install software on your OS of choice. If you need help with this, please leave a comment to that effect!).

Create a sample document

Let’s create a sample markdown document to work with. You can either type this in yourself or just copy it from here and paste it into Gedit (make sure each line is flush all the way to the left):

###Sample Markdown Document

*****

**Here's a lovely bulleted list:**

- With this lovely line
- And this even lovelier line
- Iambic lines are very nice as well.

And just to show off an important function for academics, let's include a sentence that ends with an inline footnote.^[And here's the text of the note.]

Go ahead and paste this into a document in Gedit (be sure each line is flush to the left). When you save your file, make sure you save it with the “.md” extension (i.e. “Sample.md”). That’s how Pandoc will know it’s a markdown document. For the sake of this lesson, let’s save this document as “PandocTest.md”.

Save the file in a convenient folder on your hard drive (usually the “My Documents” or “Documents” folder).

Fire up A Terminal

This is where things get a little bit techy. But don’t worry–it’s not really all that techy, and ultimately pretty easy!

Start by opening a terminal window on your computer so you can issue text commands.

• For MacOS: Open a Finder window and go to Applications and then Utilities; then double-click on Terminal. You can also click the spotlight icon in the upper right-hand corner of your screen and type “Terminal.”
• For Windows 7: Click click the “Start” button, and navigate to “Accessories” and then “Command Prompt”
• For Windows 8: Swipe up or click on the down arrow icon at the bottom of the screen. When you’re on the Apps screen, swipe or scroll right and located the Windows System section heading. Then click on Command Prompt.

Work Some Magic

Now that you’ve got a terminal open, we can type the commands we need to get Pandoc to work its magic.

Start by making sure you’ve got Pandoc installed. To do that, just type:

pandoc --version

The pandoc –version command and what its output should look like.

You should see a message telling you what version of Pandoc is installed along with a lot of other information.

Assuming that’s the case, let’s actually convert our document.

First, change to the directory in which you saved your test document. To do this, you use the text command “cd” (for “change directory,” naturally!). So, if you saved your test file in the “My Documents” directory in Windows, type:

cd My Documents

If you like, type “ls” (mac) or “dir” in Windows and you should see a list of files in the current directory. Make sure your “PandocTest.md” file is there.

Then it’s just a matter of using some text commands to tell Pandoc which file you want to convert and what you want to convert it to. The general syntax works like this:

• Start with the command that invokes the Pandoc program. Conveniently, this is just “pandoc”
• Then tell Pandoc which file you want to convert. In this case, our file is called “PandocTest.md”.
• Then tell Pandoc what format you’re converting from. Do this with the flag “-f” followed by the file type (“markdown” in this case)
• Next, we tell what kind of file we want our final output to be. Do this with the flag “-t” followed by the file type (in our case, “docx”)
• Then we’ll tell Pandoc to create a standalone file, put its output in that file, and name the output file, like so :”-s -o PandocTest_Output.docx”

Converting our file with Pandoc in a Windows terminal.

Do do all this, just type all the preceding commands into one line in your terminal, like so:

pandoc PandocTest.md -f markdown -t docx -s -o PandocTest_Output.docx

Then just press Enter. Your computer may think for a few seconds, but when a new command prompt appears, you’ll be done.

Our converted output in Word.

Finally, either use your file manager (that’s “explorer” in Windows) or Word to open the new file you just created. You should see your new, fully-formatted document, which should look something like the image on the left.

That’s your first conversion with Pandoc! We’ll cover more aspects of Pandoc in subsequent lessons, but, for now, just try creating and converting some documents according to your needs and play around.

In the meantime, if you’d like to look at some more complete documentation for Pandoc, you can do so here.

Happy writing! Feel free to leave questions or suggestions in the comments, especially if you run into problems with these instructions.

 

Plain-Text Writing Lesson Three: Markdown Elegance

Introducing Markdown, the Plain-Text Writer’s Power Tool

Everybody’s familiar with the usual way of formatting text in a traditional word processor, but have you stopped to think about how laborious the process normally is?

If you want to make a word italic, your hands come off the keyboard and one hand moves to the mouse. Using the mouse, you click and drag the cursor over a word (or double-click on the word) to highlight it, then move the mouse cursor up to the top of the screen to click on the “italicize” button along the toolbar. To create a footnote, your hands again leave the keyboard, you move your mouse cursor up to an “insert” pull-down menu, select “footnote,” which brings you down to the bottom of your page. You type the footnote, then scroll back up to where you were originally working in your document. Not a big deal once or twice, but such operations, when repeated over and over, actually consume a lot of time and break the flow of your thinking.

What if there were a way to perform all those operations as you go, simply by typing normal keyboard characters? Your hands would never leave the keyboard, and the mechanics of your software wouldn’t interrupt your train of thought.

This is where Markdown Syntax is a godsend.

Markdown syntax is simply a set of textual conventions, using standard keyboard characters, that indicate various kinds of formatting you want in your final output. Here are some of the basic conventions:

---

# Markdown Syntax:

## Hashtags indicate headings

### One for a level-one heading, two for level two, etc.

A string of three or more asterisks, like this:

***

Indicates a horizontal rule.

*An asterisk on either side of a word or phrase indicates italics*

**Two asterisks on either side of a word or phrase indicates boldface**

***Three asterisks indicate both boldface and italics***

You can use hyphens to indicate a bullet list:

- Like this

- And this

- And this

    - To create another level to your list,

    - simply indent the hyphen four spaces.

Indicate numbered lists as you’d expect, with numbers:

1. Like this

2. And this

3. And this

If you’d like to create a hyperlink, simply enclose the link text in square brackets, followed by the url in parenthesis, like this:

[This is the link text.](https://surfingedges.wordpress.com/2014/10/28/writing-in-plain-text-a-tutorial-for-the-non-techy-writer/)

You can indent a quotation by using a “greater than” symbol, like this

>Putting a "greater than sign at the front of a paragraph of text will indent the whole thing as a nice block quote.

There are a couple of ways of doing footnotes. We’ll explore two eventually, but

the first way is to enclose a caret and a "name" or number for the note inside square brackets, like this.[^1]

Then, at the bottom of the document, you create the note itself like this:

[^1]: Here's our actual footnote.

Here’s the magic. When you type a plain-text document using markdown syntax, it looks like this above. Once you’re done composing, however, you run your file through another piece of software that interprets your markdown and uses it to format a final document in the form of your choice, be it a word file (.docx), a PDF file (.pdf), a Libre/OpenOffice file (.odt) or a web page (.html).

For example, I can convert the mardown example above into html to incorporate it into this web page, and it looks like this:

---

Markdown Syntax:

Hashtags indicate headings

One for a level-one heading, two for level two, etc.

A string of three or more asterisks, like this:

---

Indicates a horizontal rule.

An asterisk on either side of a word or phrase indicates italics

Two asterisks on either side of a word or phrase indicates boldface

Three asterisks indicate both boldface and italics

You can use hyphens to indicate a bullet list:

• Like this
• And this
• And this
  • To create another level to your list,
  • simply indent the hyphen four spaces.

Indicate numbered lists as you’d expect, with numbers:

1. Like this
2. And this
3. And this

If you’d like to create a hyperlink, simply enclose the link text in square brackets, followed by the url in parenthesis, like this:

This is the link text.

You can indent a quotation by using a “greater than” symbol, like this:

Putting a “greater than sign at the front of a paragraph of text will indent the whole thing as a nice block quote.

There are a couple of ways of doing footnotes. We’ll explore two eventually, but the first way is to enclose a caret and a “name” or number for the note inside square brackets, like this.¹

Then, at the bottom of the document, you create the note itself like this:

BTW, another way to indicate a footnote, which I think much more useful for academic writing, is called an “inline” footnote. Inline footnotes are indicated by a caret (^) where you want the note to appear followed by the note itself in brackets.^[Like this.]

---

Pretty sweet, huh? The beauty of this system is that all of your formatting happens in-line with your prose, which means that including it doesn’t interrupt your thinking. And, as I’ve mentioned in previous installments, when you edit and move things around, your formatting code moves in a natural, visible way (as opposed to all that messy underlying code in Word that seems so bent on destroying both your formatting and your sanity).

So, here’s your five-minute assignment for this lesson:

• Fire up the new text editor you downloaded in the previous lesson.
• Using the above formatting as a guide, do a little of your daily writing (some notes, a journal entry, some freewriting, an email, or whatever) using markdown syntax for formatting.
• If you’d like a more comprehensive guide to the syntax or want to find out how to format something I didn’t mention above, there’s a great markdown “cheatsheet” here

That’s it for this lesson! Have fun experimenting with the syntax, and notice how much word-processor fussing it removes from your writing process. In the next lesson, I’ll show you how to convert your markdown to beautiful, fully-formatted Word, OpenOffice, or PDF documents.

---

1. Here’s our actual footnote. ↩

Plain-Text Writing Lesson Two: The Editor

[Note: This is part two of a multi-part series on the joys of writing with plain-text tools. If you haven’t already, you might want to take a look at the first lesson, which covers why one might want to use plain-text tools in the first place. This lesson, and all the forthcoming lessons, are geared toward writers who aren’t techy and don’t have a great deal of time to devote to learning new gadgets and gizmos. They’re designed to take just a few minutes each to complete, with a view toward having a complete plain-text workflow in place by the time you’re through all the lessons]

Lesson Two: Let’s Get a Text Editor

If the first segment of this series convinced you–as I hope it did–that working with plain-text tools might be worth exploring, the next step is to get yourself a brand new text editor.

One of the great things about text editors, as I mentioned in the previous lesson, is that they’re extremely lightweight when compared to traditional office suites. This gives them two major advantages:

• They’re lightning fast, even on older hardware. No whirring hard drives or laggy performance gets in the way of your thought process.
• They get out of your way: The interfaces for most text editors are very minimal, giving you space to write and a few commands, many of which are accessible from the keyboard rather than mouse clicks. Working with the keyboard as much as possible also speeds you up: if you think about how many times your hand leaves the keyboard in order to grab the mouse when you’re working with a traditional word processor and add that up, it can work out to be a significant chunk.The less your hands leave the keyboard, the less there is to break the flow of your thoughts.

There are many flavors of text editor out there, and your ultimate choice of editor (or editors) will depend on how you decide you work best. I’m writing this in an editor called VIM, which is one of the more old-school and traditional options out there, and a long-standing mainstay for programmers. I like it primarily because of the gets-out-of-the-way factor: it presents you with only text in a terminal window, and works only with keyboard commands, keeping all my focus on what I’m doing.

The VIM editor running in a terminal. Nothing but the words.

The initial drawback of VIM, however, is that there’s a bit of a learning curve involved, since one needs to learn a lot of keyboard commands that make writing faster in the longer term, but not the shorter. So, for our purposes we’re going to start with something that’s geared more toward writers and more intuitive to use, an editor called Gedit. It’s available for all three major platforms (MacOS, Linux, and Windows), it’s free, and it’s intentionally designed to be as simple as possible.

So, your first lesson is to download, install, and spend a little time playing with Gedit. There are many different text editors out there, all geared toward different kinds of users and tasks, some more fancy than others. Gedit gives us a good starting point with its balance of simplicity and functionality.

Start by doing to the Gedit download page for your OS:

• For Windows, go here, and click on the file with the .exe estension. Double-click on the file and follow the prompts.
• For Mac, go here, and click on the file with the .dmg extension.
• For Linux, if you’re using Ubuntu, Gedit is already installed, just access it from the menu or open a terminal and type “gedit.” For other distributions, just use your distribution’s package manager.

When you first open your installed version of Gedit, you’ll get a very simple interface that looks like this:

What you’ll see the first time you open Gedit. Clean lines and no fuss.

That’s it! There’s nothing else to do, at this point, but play around with writing in that nice, clean interface. You can save your documents just as you would with any word processor. When you first save a file, it’s good practice to give your filename a .txt extension. Note that you can have multiple documents open simultaneously and switch between them by clicking on the tabs at the top of the writing area.

You can also click “view” and then select “side panel” to open a side panel that will show your list of open files. Click the tab with what looks like a file cabinet at the bottom of that panel, and you’ll get a directory tree (very handy for working with multiple files at once).

If you want to make the interface a little easier on the eyes for longer writing sessions, you can change the color scheme and font it uses (note that this will have nothing to do with determining the font in your final output document; this is just about using the font that’s most attractive to your eyes while composing). Just click on the “edit” menu, select “preferences,” and then the tab for “fonts & colors.” You’ll get a list of several preset color schemes (I like the “oblivion” scheme, which gives you gray text on a black background). If you want to change the font, uncheck the checkbox that says “use the system fixed width font.” The otherwise grayed-out pull-down menu for selecting the font and size of your text will become active, and you can choose any font you like.

That’s all for now! Have fun playing with Gedit! Next time, we’ll look at the elegant MarkDown syntax, the most important “power tool” for plain-text writing.

If you run into any problems of have questions, feel free to contact me in the comment section.

Writing in Plain Text: A Tutorial for the Non-Techy Writer

Inspired by a conversation with some of my advanced literature students, I offer, here, a short set of tutorials for writing productively (especially as an academic) using plain-text tools. Unlike most of the online resources on this subject, this series of tutorials is designed for the non-techy writer who doesn’t have a lot of time. The lessons are desgned to to be extremely simple, even if you’re a technophobe, and take only five to ten minutes to complete. By the end of the series, you’ll be up and running with a digital writing process that gets the technology out of your way and puts your creative process first.

Lesson One: Why Plain Text?

I’ll admit it, I’m a tech nerd. Or, at least, as much of a tech nerd as one is likely to find in an English department.

As I mentioned in my previous post, I think medievalists bring a kind of historical awareness to tech that allows us to see it more as a collection of useful functions–where novelty isn’t necessarily the only value–than a progressive march toward perfection. This approach allows us to ask not “what’s the newest thing?” but rather “what’s the best technology for the job?” in an awareness that the best tool for the job might potentially be a very old one.

One thing scholars in the humanities do all the time is write, and taking my “medievalist mind” to the available technologies for doing that has helped me light on some tools for supporting my writing that are in some ways older and less “high tech” than other options. For the same reason, however, they are also more stable, more sustainable, and (with a little practice) faster and easier to manage than traditional electronic writing with a word processing suite such as Microsoft Office.

The Elegance of Plain Text

To understand how working in plain text is helpful, think about the tools you normally use to write on a computer. If you’re like most, you default to a traditional “word processor” such as Microsoft Word. But consider this: have you ever had a problem with Word where some strange formatting seems to have sneaked into your document and you can’t get rid of it, no matter what you do or what settings you change? Have you ever had a Word document behave in infuriatingly odd ways for no apparent reason? Well, there is a reason, which is that Word documents are actually extremely complicated beasts. For example, a very simple sentence in Word, such as:

This is a simple sentence typed in the Word .docx file format

only appears to be very simple. Underneath what you can see in Word, there’s a huge amount of code that you don’t see. Here’s that same sentence with all the underlying word code revealed:

The image you’re seeing is only one out of nine pages of code Word generates to display that single sentence.

Hence the reason Word tends to misbehave, and misbehave more the more you work with a document. As you add edits, elements such as notes and images, copy text from other sources, rearrange blocks of text–in other words, most of the things an academic does with documents all the time–the more of that code is inserted, the more random and redundant strings of code interact and conflict with one another, and the more complex and unwieldy the document becomes. No wonder your document starts behaving as though it’s possessed by something unholy.

On the other hand, a plain-text file contains only the ascii characters that you type. A plain text file in which you type:

This is a simple sentence in plain text.

contains only the characters you typed, nothing else. If you make edits, rearrange things, paste in text from elsewhere, make lots of revisions over time, add sources, etc., you’re only rearranging and adding your text. Where a graphical Word processor might boast that “what you see is what you get,” a text editor can boast “what you see is what is there.” Nothing is hidden.

For this reason, plain text documents are much more stable and sustainable through the process of composition and revision than word processor documents. That doesn’t mean there’s something inherently wrong with word processors. What it does mean is that word processors are the right tools for the job when the job is formatting and processing complex documents, and not necessarily the right tools for the job when the job is writing.

A few other advantages of plain text:

• It’s compatible with everything. You can edit plain text files on any device, with any simple text editor. You can work on your writing on any computer, your tablet, or even your phone without screwing up any formatting in the process.
• It’s sustainable over time. As mentioned above, plain text doesn’t add tons of behind-the-scenes code the more you work with a document, so you can say goodbye to Word’s shenanigans. It’s also true that popular file formats change over time: if you wrote documents in something like, say, WordStar years ago, those documents take a lot of doing to access these days. Plain text documents have always been, and will aways be, universally accessible.
• You can focus on your words. Word tends to be so complex, and presents you with such a dizzying arrange of options (most of which you don’t need unless you’re a massive insurance corporation) that the tool itself can distract from your writing. A simple text editor removes all that nonsense–it’s just you and your words.
• You have more control over formatting. The basic idea behind a plain-text workflow is that you do your composing with a text editor in a sustainable, unversal format, and then, only when your text is ready to send somewhere–say, to a journal for publication–do you worry about formatting. We’ll cover how to make this work in later posts, but for now, imagine this: you’ve written an article as a text file. That file contains only universal formatting for everything–subheadings, footnotes, citations, etc. To format the file for different venues, you use another piece of software to convert that document into any format you like. One journal wants the document submitted as a Word document with citations in MLA style? You simply tell your conversion software that’s what you want, and, with a few keystrokes, ZAP! You’ve got a properly-formatted Word document ready to go. Another journal wants the same article submitted as a PDF with footnotes using the Chicago notes-bibliography style? A few more keystrokes and voila! Need to make some substantial edits after a peer review? Make those edits in the original text file and avoid all the formatting shenanigans your word processor always gives you.
• It’s blazingly fast. Text editors are tiny pieces of software compared to word processors, so they start instantaneously, load documents almost instantly, and run like lightning even on old hardware. Nothing gets between you and your words.

In the end, the best thing about working with plain text is that it’s a technology that gets out of your way, allowing you to think and compose without distraction.

Convinced? If so, stay tuned for the next lesson, in which we will download and get started with some elegant text editing software.