A medievalist does faith, tech, and popular culture

Menu

Tag Archives: writing

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 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 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:

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!

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:

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:

Open your Zotero app

Right-click on the collection you want to export and select “Export Collection”

In the ensuing dialog box, select “Bibtex” as your format, and click OK

Specify a location for your bibliography file–this should be the same folder in which your draft document resides.

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:

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:

Open a square bracket: [

Type an @ symbol followed by the desired citekey

Add any needed text or page numbers before and after the citekey.

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:

--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:

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!

Like this:

In two more weeks, I end my post-heart-surgery medical leave and go back to doing what I love the most: being with students, teaching Chaucer and Shakespeare, and studying the literature and culture of medieval Britain.

It’s going to be a bit of a transition after three months of focusing on healing, so I’ve been spending my weekend doing a little preliminary “gearing up”, sort of preparing myself psychologically to head back to work, now that my body can actually handle it again.

Since part of my job involves doing some pretty heavy-duty research and writing, part of that prep has involved thinking about ways to work on those projects, especially the writing, with a high degree of focus. The computer is of course both a blessing and a curse in this regard: it’s a necessary tool, to be sure, but it can also be mightily distracting, not only in the sense of offering online diversions (social media, etc.) but visual clutter as well. Our operating systems and browsers seem to be increasingly geared to be platforms for selling us things, which means notifications and message-boxes of various kinds can really proliferate (Windows 10, for example, drives me insane in this regard). With multiple windows and toolbars, computer screens can become a cacophony of clashing colors and notification sounds, none of which are particularly conducive to concentration.

So, being a bit of a nerdy sort, and also someone who cares about recycling older gadgets to reduce e-waste, I decided to resurrect an old desktop computer to use as a dedicated writing machine. The idea was to make the interface as distraction-free as possible, visually elegant, and conducive to long work sessions while minimizing eyestrain.

There are of course many “distraction free” writing apps out there that try to fill this kind of niche (such as WriteMonkey and Writeroom), but I’ve never found them quite right for me: as an academic, I rarely write only what springs spontaneously to mind: I’m constantly looking at previous drafts of what I’ve written, paging through electronic notes, PDF files of articles, etc. I generally also need some consistent information, such as the time (so I’m not missing my next class!), my to-do list, and basic weather information. I also wanted to capacity to play and control music right on the desktop, since that usually helps me tune out other ambient noise. Dedicated distraction-free writing tools accomplish their task my simply filling the entire screen and blocking out everything else; I wanted a solution that would not work by blocking things out, but rather by displaying only what I want. So, my idea was to set up a system that would be as spare and distraction-free as possible without cutting me off from all the information and resources I generally need to manage while I write.

The result is what you see in the screenshot above. I’ll explain the techy bits of this below for anyone interested in duplicating or improving upon my efforts, but here’s what you’re looking at:

To create a very customizable system that runs smoothly on an older computer, I used the Linux operating system, specifically the Xubuntu Linux flavor. Xubuntu is designed to be easy-to-use with a minimum of system resources while still being a fully-featured desktop environment. A similar arrangement should be possible with Windows and MacOS, using a somewhat different set of applications and tools.

To make the whole thing very eye-friendly, I based all the colors on the solarized color scheme developed by Ethan Schoonover. According to Schoonover:

Solarized is a sixteen color palette (eight monotones, eight accent colors) designed for use with terminal and gui applications. It has several unique properties. I designed this colorscheme with both precise CIELAB lightness relationships and a refined set of hues based on fixed color wheel relationships. It has been tested extensively in real world use on color calibrated displays (as well as uncalibrated/intentionally miscalibrated displays) and in a variety of lighting conditions.

I’ve found this scheme to be truly conducive to long periods of staring at a screen. My idea was to integrate all aspects of the desktop within this scheme, so that both the desktop and its various elements (wallpaper, window borders, application backgrounds, music player, system information display), as well as all the applications I need, share this same set of soothing colors.

I set up the system to use two monitors: one directly in front of the keyboard that’s entirely dedicated to the text I’m currently writing (this is the left-hand side of the screenshot above, which combines the images from both monitors). Just to my right, the second monitor is for displaying system and other information (weather, time, music), and also for displaying and managing ancillary documents like notes, images, and PDF’s. This keeps the focus on the main text while also keeping all those other materials ready to hand.

As I’ve mentioned elsewhere on this blog, I love to write using plain-text tools, for a host of reasons that I explain here. My editor of choice for composing is an oldie-but-goody well-known to programmers but less so to writers, known as Vim. Vim is an old-school editor designed to run in a good old-fashioned terminal. There’s a definite learning-curve involved in using Vim, but it’s been worth it for me, as Vim has become about the fastest and most distraction-free tool for bare composition I’ve ever found. Since Vim runs in a terminal window, I simply have the left hand monitor set up to display that single terminal window, made almost transparent, against the solarized background. This keeps the editor in the visual center of the monitor at all times, keeps my hands on the keyboard where they belong, and encourages a focus on what I’m writing.

The most prominent element on the righthand monitor consists of a system monitor tool called conky, set up to display the time, weather information, and basic system information.

To the left of the system information display, there’s a music player called ncmpcpp. This is another tool designed to run in an old-fashioned terminal. The beauty of this is that I can position a transparent terminal on the screen, and the music player becomes a background element of the desktop, always available but never in the way. Console applications also take up much less in the way of system resources than GUI apps, which helps to keep this older machine running smoothly.

The final element is my todo list, which I manage via the elegant application by Gina Trapani called todo.txt. It’s basically a fancy way of keeping your todo list in a plain text file while still being able to manage it nicely, add and delete items, set contexts, etc. This is another console application, so it runs in another small, transparent terminal window right underneath the system information display.

Note management is a little more complex than simple composition, since it involves keeping track of many different small files at once (I keep my reading and thinking notes in small, plain-text files, organized into directories), so I use a more robust text editor for note management so I can easily switch between notes and have several note documents open at once. I accomplish this with the excellent Sublime Text. Note that Sublime Text (the other window in the right-hand part of the screenshot above) displays both my note documents in tabbed or tiled format, with a left-hand panel that shows the directory tree of my note directory, making everything readily accessible.

Those are the basics! Feel free to let me know what you think or suggest improvements. I’m also glad to work with the less-techy to set up similar arrangements of their own.

Addendum: An astute user pointed out that a tool to change the color-temperature of your display according to the time of day or night would also help with eye-strain. I heartily agree. I use the excellent f.lux (which has Windows and Linux versions) for this purpose. Other linux users prefer the (also-excellent) tool redshift.

Like this:

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

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.

Like this:

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:

*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:

Like this

And this

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:

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:

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.

Like this:

[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 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.

Like this:

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.