In his famous essay on “History as a Literary Art,” Samuel Eliot Morrison advises, “When you once are writing, go on writing as long as you can; there will be plenty of time later to shove in the footnotes or return to the library for extra information,” and, “Don’t stop to consult your notes for every clause or sentence: it is better to get what you have to say clearly in your mind and dash it off; then, after you have it down, return to your notes and compose your next few pages or paragraphs.”

I try to follow this advice when I’m writing by leaving notes or markers in the text when I’m missing a fact or a reference. Following up on my post about Vim yesterday, here is how I manage these markers in Vim.

First, I insert the markers in a standard form: {TODO} is my generic marker; {PAGE} marks a missing reference; {FACT} marks a missing date or the like. I insert these markers using vim-snipmate but any method will do.

Second, I use the line below to highlight these markers in the text. I have the line in ~/.vim/after/syntax/pandoc.vim, but you could also put it in your .vimrc.

match Error '{\w\+}'

The result looks like this:

These markers then come in handy when it’s time to clean up the draft. I could search for the markers, but this keymapping makes things easier:

nnoremap <leader>{ :vimgrep /{\w\+}/ %<CR>:copen<CR>

That keymapping puts all of the markers into Vim’s quickfix buffer, which gives me a list of all the needed corrections and lets me jump from item to item. It looks like this:


Jason Heppler, Caleb McDaniel, and Chad Black often post Vim hacks, so here is one of mine.

One of the downsides to writing prose in Markdown is that the formatting of the text can become quite messy, with lines of varying lengths, footnotes scattered throughout the document with incorrect numbering, links in the text, and so on. For files like HTML or Javascript, Vim can automatically indent text using the = command over a range or motion, or the == command on a single line. By setting the equalprg variable, you can clean up your Markdown text using an external program.

First, add this line to a ~/.vim/ftplugin/pandoc.vim file. This code tells Vim to use = to call Pandoc as a filter to format the text.

setlocal equalprg=pandoc\ -t\ markdown\ --reference-links\ --atx-headers

Now you can select a range of text and press =, or go to the start of the document and press =G to filter the whole document.

I’ve also added a keymapping to filter the whole document automatically. You can put this line in the same file as above, or in your .vimrc.

nnoremap <silent> <leader>= mpgg/\v^(\w\|\#)<CR>=G`p :let @/ = ""<CR>

That line drops a mark at your current cursor location, goes to the beginning of the document, finds the first line that begins with a word or a header (to avoid the Pandoc title block), filters the text through Pandoc to the end of the document, return the cursor to the mark, and clears the search highlighting.

I tend to clean up the text after every paragraph I write. One caution: if Pandoc thinks your markup is invalid, you can lose text, so be careful. Also, keep your documents under version control.


At the Anxious Bench, Thomas Kidd lists “Five Compelling Religious Biographies.” Among them is Catherine Brekus’s new book, Sarah Osborn’s World: The Rise of Evangelical Christianity in Early America, which Kidd calls “the best biography we have on a female evangelical in colonial America” and also “simply one of the best books I have read on the life of an American evangelical, female or male.”


Today the JSR editors (Mike Pasquier, Luke Harlow, Art Remillard, and Emily Clark) published volume 14 of the Journal of Southern Religion. This issue has a great line up of articles, especially the forum on “Religion in the Early South” guest edited by Rebecca Goetz.

My technical innovation for this issue was generating EPUB and Kindle e-books of the issue. To do so, I used a Ruby program that I coded. The source code is on GitHub, and I released the utility as a RubyGem. I was surprised by how many people downloaded the Gem. Sure, the downloads were not in the tens of thousands, but at least sixty people have downloaded the latest version.


[This post originally appeared at ProfHacker.]

In the past few months there has been a lot of attention paid to a Zotero plugin called Paper Machines. Created by Brown grad student Chris Johnson-Roberson as a Google Summer of Code project, Paper machines was coded by Brown grad student Chris Johnson-Roberson, and Jo Guldi and Matthew Battles directed the project. Paper Machines uses the data in a Zotero collection to generate analyses and visualizations. If you have a sizeable collection of documents with good metadata and full text (for example, PDFs with text layers) then Paper Machines can run its analysis. The most basic output is a word cloud. More advanced analyses provide phrases matching a pattern, maps of place names, annotations of people, places, and organizations. Paper Machines can also perform topic modeling using MALLET.

I ran Paper Machines on the digitized primary sources for a chapter of my dissertation. I didn’t do any work to clean up the data, and this is obviously just a first pass without any analysis. But I was impressed by this map of place names, which generated the kind of American-British-German connection that I thought I saw in the sources. But the plot also contains places that I didn’t expect, which I hope will be a fruitful area to research further.

For a much fuller description of Paper Machines, you can see the documentation, Johnson-Roberson’s [write up][Paper Machines Map] at Harvard’s metaLAB, or a two blog posts by Sarita Alami from the Emory libraries.

Have you tried Paper Machines with your Zotero library?

Update (11/8): In the original post I neglected to give credit to Jo Guldi and Matthew Battles who started and directed the project. You can read a post about Paper Machines by Guldi here.

Update (11/9): Chris Johnson-Roberson sends this update about the contributions of the various collaborators:¬†“Paper Machines was coded by Brown grad student Chris Johnson-Roberson in collaboration with historian Jo Guldi, under the guidance of Matthew Battles at Harvard’s¬†metaLAB.”


This Saturday, October 20, I’ll be giving a workshop at THATCamp New England 2012. Here is the description of the workshop:

An operating system is the most basic software on a computer, which allows the computer run higher order applications. Scholars also need an ‘operating system’—a set of basic tools that work together reliably to handle the low level tasks of scholarship so scholars can concentrate on higher order thinking. We will begin this workshop by drawing some ideas from the philosophy of the Unix operating system, especially the idea that (almost) all scholarly work can be done in plain text. We will then experiment with Unix-style tools that can be used on any computer operating system. We will spend most of the workshop trying out the components of a plain-text scholarly operating system, including text editors (take your pick), plain-text markup (Markdown), document converters (Pandoc with a nod to LaTeX), and version control (Git). Along the way we will also learn the basics of interacting with a computer through a command line.

Participants will get more out of the workshop if they install Pandoc and a good text editor (TextWrangler on Mac, Notepad++ on Windows) before the session. The links above to ProfHacker posts may also be helpful.

Here are some links to resources to help you get started with plain-text scholarship. N.B. I’ll be adding more links soon.

ProfHacker posts

Online Markdown converters

Git


The JSR editors been making a lot of changes at the Journal of Southern Religion in the past year. We’ve rebuilt the site from the ground up, we’ve released our content under an open-access license (written up here), we’ve added a successful podcast with seven episodes already, and we’re getting close to adding DOIs and releasing a new issue. Sometime soon I want to write a full ‘making of’ post about the decisions we made and the tools we used. Today, though, I want to introduce a Ruby script I’ve written for the JSR to make e-books in EPUB format of each issue.

The JSR’s website runs on Jekyll, a ‘simple, blog aware, static site generator’ that converts Markdown files into a website. In other words, JSR articles are stored in plain text files like these from issue 13. Stephen Ramsay explains why this is a good thing. Because the JSR content is portable and parsable, it’s easy to use the content for purposes other than the website itself.

One of the new things I want to do with the JSR is make an e-book of each issue, so that scholars can read the journal on tablets and mobiles more immersively than is possible on a website. Whether there interest among JSR readers in this new format remains to be seen, but other people are writing about EPUB for scholars and other open-access journals, like the Journal of Digital Humanities are releasing their content as EPUB.

I’ve written a Ruby script, epub-jekyll, which parses posts and pages in a Jekyll website and passes them through Pandoc to create an EPUB. Because the script uses a YAML file as a table of contents, it should be useable on other Jekyll (or Octopress) websites. You can get the code from GitHub and learn how to use the script in the README.

This my first project in Ruby, so I’ll be glad for any improvements you’d like to suggest.

Update 2012-11-01: I learned that there is another project called jekyll-epub so I had to change the name of this project to jekyll-ebook. The links above have been corrected. And I’ve also published the project as a gem.


I write all my documents in Markdown and pipe them through Pandoc to make PDFs. Typing pandoc myfile.md -o myfile.md.pdf over and over at the command line gets tedious, especially if the Pandoc command requires options for BibTeX and CSL files.

My solution is to use GNU Make (helpful introduction here). Make lets you define a series of rules to compile files. You define ’targets’ (the files to be made), ‘dependencies’ (the source files), and the commands that express the relation between the two. A typical rule using Pandoc might look like this:

lesson.01.md.pdf : lesson.01.md
    pandoc lesson.01.md -o lesson 01.md.pdf

Read the entire post 


[This post originally appeared at ProfHacker.]

Of the perennial ProfHacker favorites, WordPress is probably neck and neck with Zotero as our most written about topic. From course blogs to department websites to ProfHacker itself, we like WordPress for just about any kind of website that you might run. In fact, other than the barest mention, I don’t think we’ve even acknowledged the existence of WordPress competitors like Blogger, Typepad, and MoveableType. WordPress really is that much better than the competition. (Jason does like About.me for profile pages, and if you’re comfortable on the command line Jekyll or Octopress are great choices.)

But if for academic purposes there isn’t much choice between WordPress and its competitors, you do have a choice between WordPress.org and WordPress.com. With WordPress.org, you host your own installation of WordPress and can install plugins and themes however you wish. With WordPress.com, you use a WordPress as a hosted service, which gives you no control over plugins, but the service comes with some nice features already set up for you, such as stats.

Recently the choice has been made easier with the release of the plugin JetPack. Automattic, the company behind WordPress, has bundled a lot of the extra functionality of WordPress.com into a single plugin for WordPress.org. You install the plugin like any other, then connect your site with your WordPress.com account.

The plugin adds over a dozen features, not all of which are equally useful. Here are the highlights that are relevant for course websites, as mentioned by Brian, Mark, and Jason.

  • Stats. The WordPress stats are clean, simple, and easy to understand. They also don’t require any additional configuration. For almost any purpose these stats should be sufficient. Professional-grade services like Google Analytics are overkill.
  • Shortened URLs. For each page and post Jetpack provides a shortened URL, which can be useful for e-mails and documents. (E.g., from http://lincolnmullen.com/courses/uws/schedule to http://wp.me/P2GPwb-f.)
  • Embed codes. If you need to embed video in posts, Jetpack adds some shortcuts.
  • Math plugin. If you’re in a STEM field, the math plugin will let you create equations with LaTeX.

In short, Jetpack is hardly essential, but if you’ll use some of these features, it’s a nice addition.

What experience do you have with JetPack for course websites? Are there other plugins you find essential?


I’ve been asked to give a workshop at THATCamp New England 2012 on Saturday, October 20. Here is the description of the workshop:

The Humanist’s Operating System; or, Scholarship in Plain Text

An operating system is the most basic software on a computer, which allows the computer run higher order applications. Scholars also need an ‘operating system’—a set of basic tools that work together reliably to handle the low level tasks of scholarship so scholars can concentrate on higher order thinking. We will begin this workshop by drawing some ideas from the philosophy of the Unix operating system, especially the idea that (almost) all scholarly work can be done in plain text. We will then experiment with Unix-style tools that can be used on any computer operating system. We will spend most of the workshop trying out the components of a plain-text scholarly operating system, including text editors (take your pick), plain-text markup (Markdown), document converters (Pandoc with a nod to LaTeX), and version control (Git). Along the way we will also learn the basics of interacting with a computer through a command line.

Participants will get more out of the workshop if they install Pandoc and a good text editor (TextWrangler on Mac, Notepad++ on Windows) before the session. The links above to ProfHacker posts may also be helpful.

As a bonus, here is a video from AT&T about Unix posted by Caleb McDaniel.

[http://www.youtube.com/embed/tc4ROCJYbm0]