Simple setup of a LaTeX project with Subversion

I had a conversation/debate with a colleague recently in which we discussed the creation and editing of large files, e.g., theses, which get shared between multiple people for correction and so forth. I have a certain fondness for LaTeX – I wrote both of my undergraduate degree projects and my PhD thesis in LaTeX, and it is my firm belief that it is well worth learning the program in order to write such large documents. My colleague, on the other hand, defended Microsoft Word at least for its familiarity, pointing out the relative ease of sharing Word documents via email and its own comments system, citing the relative unfamiliarity of LaTeX (at least among people in our profession) as a big disadvantage. Certainly, people called on to correct documents written in LaTeX understandably feel quite put out when confronted with a pdf they can’t directly edit.

But should it be a big disadvantage? I don’t see why well-educated scientists in the 21st century shouldn’t be able to learn how to use LaTeX for collaborative document preparation – if it’s not too difficult to learn and is advantageous to do so, that is. After all, most of us are forced to learn to use much flakier, less well-documented proprietary software for some instrument or other at some point. It occurred to me though, that as one of the minority of LaTeX users in my field, I’d never actually tried to write a LaTeX document with other people contributing. Is it easy to use? Or a pain in the arse? It must work well in principle, at least, since I understand that LaTeX is unsurprisingly the standard in the computer science field.

In the end I decided to try and find out by creating a simple scientific report-style document with Subversion for version control. There are a few tutorials on the subject but being completely new to Subversion it took me a while to get my head around the general concept. Therefore, I figured it might be helpful to have the general principle written down in case it comes in handy for the future or for anyone else with a similar prior knowledge (i.e., some LaTeX experience).

First problem is, you need a Subversion repository running on a fileserver. This is pretty easy to set up, but unfortunately I don’t have a server. Luckily however, there are companies which will host a repository for you – Assembla will give you one for free, so I signed up there and created a repository (or “Space”) for my LaTeX files. I then downloaded SmartSVN as an alternative to managing the repository with the command line. In setting up SmartSVN you can give the program the Checkout URL given by Assembla in order to link the two.

Now the writing can begin. I created a new folder in the trunk/ folder created within the repository and made a new .tex file in there. Subversion can add keyword info into the files themselves so that version info can be incorporated into the built pdfs. This can be achieved through the svn package:

\usepackage{svn}

These keyword tags will need to be added to the .tex file in the preamble:

\SVN $Revision$
\SVN $HeadUrl$
\SVN $Date$
\SVN $Author$
\SVN $Id$

In SmartSVN, the file can be marked to be added to the repository, then by right clicking on the file one can choose Properties > Keyword Substitution and set all the necessary keywords to “Set”. When the file is committed to the repository, the revision number increments and the tags in the file are expanded to include the new information for the revision, for example:

\SVN $Id: main.tex 5 2014-09-23 18:52:10Z mjlacey $

Now, the information can be added into the document by using tags, such as \SVNId, which simply prints out the line of text for the revision ID as shown in the above line of code when the .tex file is built. At the moment I’ve put this information in the footer of my document. There’s more information about what tags one can use in this document, for example.

So, now that I’ve worked it out, pretty straightforward stuff. I like that one can choose to only upload the .tex files, keeping the build files local, and that with SmartSVN it’s very easy to see the changes between a local version of a file and the remote version of the file. I’ve not got any collaborators to work on a document with (…yet) but it’s nice to know that it’s in principle not that complex to set up a collaborative LaTeX project even with no prior knowledge of the versioning system.