Academic writing extensions to Markdown

Get Version

0.0.10

→ ‘mandown’

What

Mandown provides simple extensions to the Markdown syntax that are useful for academic writing.

Writing a paper using Mandown is simple: write your paper using standard Markdown syntax and the Mandown extensions where necessary, then process your file using the Mandown tools. These will generate a standard Markdown file containing your citations, bibliography etc. Then process the resulting file using a suitable Markdown processor (I recommend using Pandoc, which will generate RTF files that can be opened using Microsoft Word).

‘Mandown’ is a portmanteau of ‘Markdown’ and ‘manuscript’ which I found appropriately amusing (“Man down!!”).

Mandown is at an early stage of development and is not quite ready for use on real work. However, it still might be useful to you and I’d appreciate early feedback. It is easy to install, upgrade and uninstall Mandown, so if you’re interested, please give it a try.

Why?

Academics typically write papers using either LaTeX or Microsoft Word. Word is often favoured by the less technically inclined (or those who are simply ignorant of the existence of alternatives). LaTeX is used for some combination of the following reasons: it’s free software; it can produce typographically excellent output; LaTeX documents are plain text files which can be edited using powerful text editors (vi, Emacs, TextMate etc.). Those who would otherwise choose LaTeX are often forced to use Word by their co-authors or the publishers of their work, and would like a way to maintain the benefits of their LaTeX environment while being able to produce Word documents. Mandown provides tools to allow this.

Mandown is not attempting to be a document preparation system like LaTeX; if you can use LaTeX you probably should—it’s far more powerful than Mandown. For example, Mandown will have no support for controlling page layout or inserting and controlling graphics (though it will support the concept of figures).

Mandown is implemented as a set of command line tools that can be chained together into a pipeline. In future, further extensions to Markdown will be developed and implemented (e.g. figdown will support figures, another tool will support sectioning, labels and referring, etc.). Mandown is distributed as a gem for ease of installation (see the next section).

Installing

Mandown is distributed as a Ruby gem (so you’ll need Ruby and RubyGems installed already). To install, type something like:

sudo gem install mandown

(If you are confused already, read the Really Quick Start guide from the RubyGems user guide and note that you may or may not need the sudo command: it’s necessary on Mac OS X, but on other systems you might need to become the super user first by running the su command and entering the super user’s password, and then running gem install mandown.)

This will add the Mandown programs (executable Ruby scripts).

You will also need to install a suitable Markdown processor. I recommend Pandoc which can convert Markdown to multiple output formats, including RTF which can be opened using Microsoft Word.

The tools

The following Mandown tools are provided in the latest release:

Usage

First you need to write a manuscript using a combination of the Markdown and Mandown syntaxes, but to get you started Mandown includes a sample Mandown document (see the example, below). Markdown and Mandown are very simple and all you need is a plain text editor (don’t save your Mandown files as Word documents, they must be plain text files).

To learn Markdown, see the Markdown documentation (note that Pandoc is the recommended Markdown processor for academic applications).

Each Mandown tool adds one or two simple extensions to Markdown; for example bibdown adds the cite: syntax to cite references and allows you to specify your bibliography in YAML format.

Each tool provides its own documentation via a --help option, for example type

bibdown --help

to learn how to use the bibdown tool and see its syntax.

Because each Mandown tool does one thing and adds only one or two syntax extensions, you can easily learn just the ones you need and ignore the rest (or perhaps contribute your own).

Example

Let’s read an example Mandown manuscript using the less pager:

mandown-sample | less

The mandown-sample program simply outputs the sample manuscript.

(Note how papers are cited using the cite: command. Also scroll to the bottom and have a quick look at the YAML-format bibliography.)

We want to process this document using Mandown (and then Pandoc), so first save the sample to a file:

mandown-sample > sample-manuscript.txt

Now let’s process this sample manuscript using bibdown:

cat sample-manuscript.txt | bibdown > sample-markdown.txt

This uses the cat program to send the sample-manuscript.txt file to bibdown using a pipe (via the | character), and then saves the result to a file called sample-markdown.txt (via the > character):

bibdown interprets the bibliographic aspects of the Mandown syntax and renders them using Markdown. The result can then be processed using a Markdown processor such as Pandoc:
pandoc --smart -s sample-markdown.txt -o manuscript.rtf

You could now open the manuscript.rtf file using an application like Microsoft Word or OpenOffice.org.

The Mandown tools are designed to be chained together into a pipeline, so for example you might do:

cat my-manu.txt | bibdown | secdown > my-manu-out.txt
pandoc ...

Upgrading

Mandown is undergoing steady development and currently has a 0.0.x release number. I’m hoping to get first versions of the most important tools finished soon. At this point Mandown will be given the 0.1.0 version number, to indicate that it is suitable for people to start using it (even if just in an experimental context).

If you use the early versions of Mandown and want to keep up-to-date, simply run

sudo gem update mandown

You may also optionally remove previous versions using:

sudo gem uninstall mandown --version x.y.z

or

sudo gem uninstall mandown

and then install Mandown as usual.

Help, gotchas and FAQ

Q1: How do I …

Email me; there isn’t much implemented yet, but the bare bones are there. No guarantees, but I’ll try and take your feature requests into consideration. Or better yet, send me code!

Q2: I have a problem running bibdown.

Check that you are not using hard tabs; AFAIK, Ruby’s YAML parser requires that soft tabs (i.e. emulated using spaces) be used. Also check the alignment of the various fields.

Q3: bibdown chokes on titles etc. that contain colons.

Surround the title in quotes; these will be ignored, but fix the problem. I think this is a bug in Ruby’s YAML parser (as of Ruby 1.8.6).

Q4: The tools don’t run.

Mandown requires Ruby version 1.8.6 or higher, and the ruby interpreter program should probably be on your $PATH. If you installed Mandown from the gem, then the tools should be on your system’s $PATH and you should be able to run them. To verify that the tools are on your system’s $PATH, type

which bibdown

If a path is reported to the bibdown program, then it is on your $PATH and should be executable; try running

bibdown --help

Otherwise please get in touch with me.

Please help

If you would like to contribute to Mandown, please email Chris Rose

The trunk repository is svn://rubyforge.org/var/svn/mandown/trunk for anonymous access.

Acknowledgements

Mandown would not be possible without the excellent tools provided by the Ruby community. In particular, the Ruby standard library YAML parser, Nic Williams’ newgem and the Ruby Forge project have made Mandown much easier to develop and distribute. Thanks!

License

This code is distributed according to the terms of the GNU General Public License; see the file COPYING for full details.

Chris Rose, 18th January 2008
Theme extended from Paul Battley