My Declaration of Arbroath Revitalised

A few months ago, I published a brief post on the 1320 document known as the 800px-Declaration_of_arbroath“Declaration of Arbroath” in the midst of what was, at the time, the ramp-up to the recent referendum on Scottish independence. It contained a brief reflection on the phenomenon of using that document in political debates that post-date the document’s creation, and included my own introduction to and edition and translation of the document.

Since then, that post has been one of the more often-visited pieces on my blog, so I’ve returned to it this week to update its content in light of more recent events in Scotland, and also to make it more readable and user-friendly. Specifically, one may now find:

  • A somewhat updated reflection on later uses of the Declaration
  • A much-improved and more easily readable text of my introduction to the document.
  • A downloadable version of my introduction, edition, and translation of the document formatted for easier printing (offered under a Creative Commons license)

That edition/translation was a labor of love for me a number of years ago, part of a program of research related to other issues concerning the Declaration. I’m glad to offer it, here, as a free resource.

You can find the updated post here:

 

RUSH LIMBAUGH’S REVISIONIST THANKSGIVING

Worth your attention: an important corrective from a fantastic historian.

Faith and History

In my previous post I noted that Rush Limbaugh’s “Rush Revere” series has just come out as #1 in the “Children’s Series” category of the New York Times Best Sellers’ list. My fear is that some Christian readers will assume that the series offers a reliable window into the American past solely because they agree with the author’s political reading of the American present. If you happen to fall into that category, may I appeal to you to reconsider?

I began this blog more two years ago out of a sense of calling to be in conversation with other Christians about what it means to think wisely–historically and Christianly–about the American past. If that is your desire as well, then I hope you will agree with me that loving God with our minds is worlds away from the mindless name-calling that so often masquerades as thoughtful reflection in today’s public square. Nor…

View original post 1,662 more words

Plain Text Writing Lesson Four: Pandoc Magic

Pandoc: The Magic Wand of Sustainable Document magic-wandConversion

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
pandoc-screen-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”
pandoc-conversion

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.

pandoc-wordoutput

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


  1. Here’s our actual footnote.