Writing a journal article in LaTeX with colour coded personalised track changes.

Blog posted on: 23 April 2017

I like writing journal articles in LaTeX. But managing revisions and working out changes between revisions is not easy. So I wrote a shell package to help.

I like writing it LaTex as it is fast, does the formatting for you and the final product is elegant. I won't try to convince you to use LaTeX. It's either something you love or hate. Me? I love it. Obviously, given the title of this blog.

I don't live in an illusionist bubble though. Office has some advantages. As far as I see it there are three. Track changes, merging documents and comments. Now at this point LaTeX users will chime in here and say "wait LaTeX can do all those things", there is latexdiff, merge software (such as Meld) and todo notes. And those users are right, it can. But unfortunately not as good.

Here are the practical problems I have writing in LaTeX. The package latexdiff is awesome. But when you're working on a large multi-authored paper it is hard to work out which author made comments on which sections. In some ways this levels the playing field, almost like blind author writing, everyone has an even say. But for me I find this frustrating. So I really like personalised track changes. This is currently not an option with latexdiff.

The todo notes feature is also a gem. Making clean margin notes is awesome. But I don't like the look of the notes and you can't tell who wrote what or when. So you then have to write the date on the note and the author. This can easily get forgotten.

My last gripe about writing in LaTeX is the need to merge documents after you get an email with an updated revision. You can totally to this in Meld, in fact it is easy. So this is not as much of a problem as the lack of personalisations for track changes and to do notes. Also latexdiff just shows you the changes. It is not used to record track changes, it is purely a comparison between tex documents. There is none of this accept/reject process as in office.

So in order to have personalisations for track changes and todo notes I recruited my husband Steve to help. Together we collaboratively coded a shell package to do this. Not only is he a coder but it helped to have someone to talk through the problems. And to help find solutions. Oh and he helped automate the process too. Win.

The package is publicly available on my github page: WRITE - with git. It has documentation too. There is also a github page: testing environment available so you can play with the scripts and learn how they work.

Write - with git

Here is an example of what the package looks like:

Graffiti

Cool hey?

We stated this project last Christmas while Steve was still living in Berlin. Every visit since we have been tweaking the code and adding new ideas after I started to use it on a paper I am writing. The need for this package came about because I am working on a 10 author paper and I wanted to have a clear idea on what my work flow would look like before the project even started.

If you're still reading then you're either killing time or want to test it out. If you're the former, then you may loose interest soon but stick with me. If you're the latter, then hooray. I am glad someone thinks it is useful.

The package requires two things. One, that you know LaTeX. Tick. Else you would not be interested in the package anyway. Two, deep breath, you need to be very git proficient. Before my current post-doc I was a git user. But I was using git without collaboration. So I rearly had anything complicated to do. Since moving to Exeter I have been collaborating a lot more. As a result my git knowledge has drastically expanded. So at this point I am pretty proficient. I have been using it for about five years or so. I am no saying this to scare you off. Just giving you a heads up. If I was to be critical of the package we wrote it would be that it relies on your ability to resolve git problems. Sorry. Can't be helped. So it means you may find it buggy.

To use this package you must have a branch for each author, one for editing and the master. Here is a picture of how the work flow looks.

Graffiti

The idea is that there is one person that manages the repo. They set it up and act as an admin for it. Each author then just works on their author branch and lets the admin know they have finished a revision. Then the admin merges together all the files from each author. Some ediiting is then required to decide which changes to keep or not. When that is done the admin then updates everyone's branches and the revision moves on.

So in addition to being the admin of the repo you also need to ask your authors to play nicely with you on github (or bitbucket). If they use git that is awesome. But you will likely need to guide them through it. But if they do not use git and don't want to, then that does not matter. Email them the revision tex file and get it back from them via email too. All you need to do is check their revision into their branch, i.e. do the git stuff for them.

It might take little bit to time to get the hang of. I hope people find the package useful. I am using it on a large project and it is working great.