Loading
Jun 10, 2016

How to write an ACM-styled conference paper using Markdown/Pandoc

markdown-acm-conference-paper

I do not have much time for writing this post. Please insert here the obligatory rant against LaTeX syntax despite of its powerful functionality. Also insert here how Markdown syntax is fresh and readable.

Let’s go straight to the point. I don’t know about my peers, but if LaTeX lacked support from editors and plugins for achieving desirable features such as quick autocompletion (especially when citing material), I would likely switch to Word. That is why plugins like LaTeXing and platforms like Overleaf, ShareLaTeX, and Authorea were born, where automation drives innovation. Well, I want that for Markdown, too. I should mention that Authorea does support Markdown. However, I want to achieve the same, if not better, in offline mode.

A couple of days ago, I was whining about how Markdown (and its powerful cousin Pandoc) is lacking support from tools in the context of academic writing.

So I tried a little experiment. My goal was to be able to write an academic article using Markdown (from now on called Pandoc, as this is the variant of Markdown I am using). However, the produced PDF had to be ready for submission and follow any academic publishing style and guidelines. I chose to experiment with ACM. Here is the result:

markdown-acm-conference-paper

Let’s see how I managed to achieve this. My approach should also work fine with other publishers such as IEEE, Springer, and friends. At the end of this post you will find an example project, too.

Credits

My experiment heavily borrows from Christopher Grainger’s excellent flow.

Prerequisites

This is what you need installed on your machine.
Pandoc and what is needed to convert to PDF, in our case a LaTeX environment
Pandoc-citeproc
Pandocfilters
table-filter.py for handling tables
– The LaTeX template that we aim to use, in our case ACM SIG Proceedings template
– The Citation Style Language (CSL) file related to your publisher format. You can look for these files at the Zotero Style Repository or at the Mendeley Style Repository. I chose ACM SIG Proceedings (“et al.” for 15+ authors).

Installing the required software is a matter of apt-get, brew install, pip, or whatever. Easy peasy.

The paper project structure

Create a folder that will host your paper project. Put inside the folder any LaTex-related file that the publisher provides. For the ACM specific case, you need:
– The LaTeX class (sig-alternate-05-2015.cls)
– The CSL file
– Any extra LaTeX support file (e.g., acmcopyright.sty)
– The sample .tex file (sig-alternate-sample.tex). This is not required for the typesetting, but it comes at handy for copy-pasting some commands
– A BibTeX file (sigproc.bib)

The metadata

Papers have title, subtitle, authors, and abstract. Here are some good news and bad news. Good news: pandoc supports the metadata using YAML. Bad news: publishers hardcode some metadata into some custom LaTeX preamble commands. For example, ACM needs a series of commands such as \numberofauthors, \author, \setcopyright, \doi, etc.

All the supported metadata can be provided using YAML language. The non-supported metadata has to be provided as LaTeX command.

Create a file called metadata.yml with the following content:

Anything under header-includes is included into the intermediary LaTeX file when typesetting to a PDF, in its preamble. Pity that header-includes is required as Pandoc does provide support for authors and affiliations.

The \usepackage{booktabs} line is required for handling tables with a two-column layout using a pandoc filter.

The actual paper

Here is the easy and relaxing part. Just write the paper using Markdown/Pandoc. You are free to use a single file or split it into multiple files. Here is my example:

This should be familiar. Citations are handled using the @ symbol followed by the BibTeX label. My example includes a picture, too. Please keep that in mind if you are copy-pasting my code from here.

Typesetting

This is easy, too. I typeset the project using the following command, which is for OS X but it can be easily adapted to GNU/Linux.

Let’s break it down:
– I am using markdown as input -f markdown
– I want to use LaTeX for typeset to PDF  –latex-engine=/Library/TeX/texbin/pdflatex
– I want smart punctuation (e.g., converting three dashes to em-dashes —) —smart
– I want to adopt ACM LaTeX class  –variable documentclass=sig-alternate-05-2015
– I need to use a filter in order to hand tables  –filter table-filter.py
– I want to use pandoc-citeproc to handle citations  –filter=/usr/local/bin/pandoc-citeproc
– My bibliography file is..  –bibliography=sigproc.bib
– I want the References list formatted using ACM style  –csl=acm-sig-proceedings-long-author-list.csl 
– My metadata is..  metadata.yml
– My text is..  sig-alternate-sample.md
– My output file will be.. -o sig-alternate-sample.pdf

That is all. You will obtain a nice-looking PDF, which conforms to your publisher’s guidelines.

Tip: Markdown/Pandoc is not as powerful as LaTeX. Sometimes you need to revert to LaTeX. Again, that is easy. Just type the LaTeX commands in text. They are supported.

Clone my example project

You can git clone my example project or download it as a zip file to start writing.

Autocompletion of references and commands

See Christopher Grainger post for more. There you will learn about the AcademicMarkdown and Citer plugins for Sublime Text. They support the syntax and autocompletion. Citer in particular is cool as you link it to a bib file, then it will autocomplete citations starting with the @ symbol.

written by dgraziotin

Dr. Daniel Graziotin received his PhD in computer science, software engineering at the Free University of Bozen-Bolzano, Italy. His research interests include human aspects in empirical software engineering with psychological measurements, Web engineering, and open science. He researches, publishes, and reviews for venues in software engineering, human-computer interaction, and psychology. Daniel is the founder of the psychoempirical software engineering discipline and guidelines. He is associate editor at the Journal of Open Research Software, academic editor at the Research Ideas and Outcomes (RIO) journal, and academic editor at the Open Communications in Computer Science journal. He is the local coordinator of the Italian Open science local group for the Open Knowledge Foundation. He is a member of ACM, SIGSOFT, and IEEE.