Rebooting Chroma

30 Aug '22

I’ve just arrived in Te Whanganui-a-Tara/Wellington for the Australasian Computer Music Conference, the first in-person edition since 2019, and it’s a good time to reflect on a bit project I’ve undertaken with this community—rebooting our journal: Chroma: Journal of the Australasian Computer Music Association.

Skipping to the end first, we now have a first issue “Rebooting Chroma” with progressively released, open access articles from computer musicians, music technologists, and composers. The journal costs less than 100AUD per year to run and has no costs for authors.

We use:

• a markdown-to-pdf workflow for all articles, the Chroma Template
• Open Journal Systems for creating the journal website and reviewing system
• old-school shared hosting with cPanel to host everything as well as the wordpress site for our community

In this post I want to document a bit of what I have put together to get this journal working. My strong belief is that folks shouldn’t have to pay thousands of dollars to publish journal articles with big publishers: we academics should be running community journals by and for each other where (as peer-reviewers and editors) we can keep an eye on quality as well as support emerging researchers. Community-run journals can run at (almost) zero cost to the researchers and readers they serve by leaning into web-first publishing using free tools.

Markdown to PDF

One draw of publishing in a commercial journal is that your output paper looks really nice. This is because the journal pays people to do the production to a certain layout. Well our journal has no money, and I don’t have much time, so we have to rely on computers to help.

Luckily it is possible to go from a word-document manuscript to a quite nice looking PDF without too much effort using pandoc and latex.

There are lots of blog posts out there about using markdown and pandoc for academic writing. Mostly these are about using markdown as the starting point to publishing in a traditional journal or conference using that publisher’s template. The idea here is to let authors use whatever they want to create a manuscript (usually Microsoft Word) and then I use pandoc to “magically” turn it into a beautiful PDF.

To do this, I have a template repository on Github which I use to create new repos—one for each article. There’s a carefully crafted latex template file, a demo article, and some scripts to tie everything together. The workflow works like this:

1. I run a little script that uses pandoc to extract the text and images from the author’s manuscript: pandoc -i $1 -o article.md --extract-media .
2. I paste the output into the template’s article.md file, and fix up the metadata
3. I run make in the repository to generate the PDF and a bonus HTML version!

The good news is that it mostly works.

Normal text is laid out beautifully in the template. Images pretty much work well although authors get confused about latex’s automatic placement sometimes. Figure captions don’t seem to work in HTML. Tables tend to need a lot of reworking to fit into the width of the page generated by latex. References and citations are a still a bit of an issue. As it turns out, most authors just have their references in verbatim text in their manuscript. Pandoc supports more advanced citation practices with bibtex files and citation style language files, but in practice my job is to take what authors give me and create a PDF.

From my perspective, the production part of editing the journal takes place in a normal code editor like this:

Mostly the markdown output from pandoc makes, sense, but I have found that I need to wrap the reference section in a latex hangparas environment to get them to work correctly:

```{=latex}
\begin{hangparas}{1.5em}{1}
```

(references go here)

```{=latex}
\end{hangparas}
```

So far, this is the only latex code I need to paste into the markdown manuscripts, which seems like a pretty big win!

Aspiration: an end-to-end online editing process

I’m still experimenting with a few features of the GitHub template.

For now, I’m happy using the template just in the production stage, but ideally, authors would fork their own template and edit in there directly. I have set up github actions that automagically build and host the compiiled outputs from the template on GitHub pages (e.g., here (HTML) and here (PDF)).

I’d also like to provide a way to edit an article online. Overleaf works so well for this for LaTeX but it’s not as easy to work out a way to edit markdown and connect to an existing template.

An overall goal would be to have (like in Overleaf) an online workflow for importing a Word document manuscript, editing in markdown and then submitting the automatically generated PDF or HTML file for review. It sort of works with a collection of different tools, but I haven’t had much interest from authors in engaging within the Chroma community in particular.

Journal Website

Open Journal Systems is a venerable and effective way to host a journal as well as manage the reviewing workflow. It’s not very hard to set up in a standard “shared hosting” environment with cPanel. In fact, there’s often a way to install it automatically in cPanel app installer widget.

OJS is fairly detailed and designed for use in journals that are more complicated than our use case (e.g., with different people in charge of review, copy editing, production, etc). I actually only now feel like I understand how the whole publication process is supposed to work, having gone all the way from submission to publication with a couple of papers.

I’m probably most familiar now with the review part of the website as the second hardest part of journal editing is getting folks to write reviews (the hardest part is getting authors to revise manuscripts). Email deliverability can be a tricky issue here. OJS normally likes to send email from PHP using the server it is running from which, these days, is probably a bad idea. The IP address of the shared hosting server tends to get spam filtered which makes getting in touch with reviewers difficult. I switched OJS to use SMTP and the email server provided by the our web host. I had to make sure the SPF and DKIM records were set up correctly, and now I think that the OJS emails are not getting labelled as “unverified” or being filtered by IP address.

One cool thing about OJS is that it supports multiple output formats for one article, so one the page for one article (e.g., Sze Tsang’s “Exploring aspects of place through sound mapping”) you can have links to a PDF and HTML version.

Once published, the metadata for articles seems to get picked up by Google Scholar, which, depending on who you ask, might be the only thing that actually matters :-/

It works!

There’s complications and difficulties above, but the takeaway should be: it works! It is possible to do a very low budget community-run journal and produce pretty good looking PDF output articles. Having tuned the latex template a bit, the production part is now very quick for a normal article. The main hassles with running the journal at this point are the normal human ones of interacting with reviewers and authors!