Writing an Economics Essay with Pandoc, JSON and Python

It wasn’t necessarily the wisest choice to begin my economics essay at 10 P.M. the night before it was due. The project, assigned weeks earlier, was to research three potential careers, including starting salary, job duties, and employment availability. Since the requirements for each job were the same, I figured it would be alright if my paragraphs were fairly formulaic.

Autogeneration from JSON

Taking this “formulaic paragraphs” idea and combining it with the fact that I really didn’t want to write my essay, I came up with a brilliant workcrastination plan: I could structure my essay as JSON and whip up a Python script to autogenerate paragraphs from that! My structure would be an array of objects with attributes that make up the parts of the essay. Once I had this plan, I finally began doing proper research, finding job prospects, salary ranges, training, and other information about each of my three chosen careers. When I was finished, I had a nice little bit of JSON:

I felt like I had definitely done too much work, so I took a break from that to write up a really simple Python script. It used Python’s str.format to plug in all the right words in all the right places, writing the output to a text file. Here it is in all its glory:

import json

TEMPLATE = ('The {ordinal} career I am interested in is one as {name}. {description} '
            '{training} The first job I would get on my path to be {name} is that of '
            '{first_job_name}, which would pay {first_job_salary}. {availability}')

with open('jobs.json') as j:
    jobs = json.load(j)

paragraphs = []
for ordinal, attrs in jobs.items():
    paragraphs.append(TEMPLATE.format(ordinal=ordinal, **attrs))

sources = []
for attrs in jobs.values():
    sources += attrs['sources']

with open('generated.txt', 'w') as g:
    g.write('\n'.join(paragraphs + sources))

Finally, I had something real to show for my work. But the work wasn’t over yet. First, I had to proofread and edit the generated text. I had left more than a few typos in the source JSON that needed correcting. I also took the chance to edit for style a little bit. After that, the raw text of my essay was finished, but I still had to make my paper presentable.

Citing my Sources

I had the end goal of generating a PDF using LaTeX through pandoc. LaTeX is a tool often used to create mathematics and science papers¹ because of its powerful math rendering capabilities. pandoc is a universal translator between text formats, including from Markdown to PDF. Of course, my paper would have no math or other fancy formatting that necessitates either of these tools. But I still felt an intense need to play around with new tools and do the essay as atypically as possible.

I did some research and found that pandoc supports citations in a number of formats. I stumbled across Zotero (source), an open-source citation management-program that can generate .bib files pandoc supports. I also downloaded a file called mla.csl, which apparently tells either pandoc or LaTeX how to format the citations. At this point, I went back to doing actual work, making citations for each of the sources I had so nicely catalogued in the JSON.

I played around with it and discovered that pandoc would only put sources in the document if they were cited in the body of the text². I decided that the only course of action would be to go through my essay, adding inline citations for every source I had, using up ten to twenty minutes in the process. I enjoyed the process of learning how to use pandoc’s inline citation formatting.

Once I finished adding the citations to my essay, I read through it once again to fix any errors. At last, it was 2 A.M., and I was finished! I ran a quick pandoc -o essay.pdf essay.md to generate the PDF, printed that, and woke up five hours later to turn it in.

Lessons learned

Interoperability is fun! Reading documentation is fun! Open source software is fun! I certainly had fun doing the project because of all the shiny new tools I got to use.

But fun is distracting. Doing things the “normal” way, writing in Pages or Word or Google Docs, would have taken 60% of the time that my adventure did. Perhaps 10 P.M. on the night before a due date is not the best time to take the slow but fun route.