Geekygrad’s Blog

Subverting LaTeX Part One April 30, 2009

Anyone new to LaTeX quickly learns how a missing brace or bracket can suddenly break your document – and always at the wrong time. Even worse is when users of more conventional word processors sneer that you “can’t even track changes” – well, with a little help, you can! There’s quite a few ways to do this, but I’ll just fill you in on what’s worked for me. Best of all, it’ll very quickly fix those sudden compilation errors. LaTeX-using collaborators can even join in on the fun because it’s easy to incorporate network access to your document too.

Since LaTeX separates content from presentation to a large degree, the approach we’re going to take will do this too. I’m assuming that you’re Linux or  Mac – some of the instructions will need some tweaking to work on Microsoft Windows. (On Mac, use /Users/geekygrad/Documents instead of /home/geekygrad.) We’re going to start in this installment by getting our document into revision control and looking at some layout issues.

Let’s get started – the first thing we need is a means to recall different versions of the source files. The computer programming community luckily have a lot of experience in this area to keep source code under control, and have invented what are called Revision Control Systems. The one I’m going to recommend using first is Subversion. It’s a powerful but simple revision control system and there are plenty of front-ends for it; there’s also a number brilliant tutorials for it online. It’s network-aware too, so you can start collaborating with others in no time.

Let’s assume we’ve got mydoc.tex, and a bibliography file called mydoc.bib. The first thing we need to do is create arepository for it, which will act as a datastore:

mkdir /home/geekygrad/svn-repository
svnadmin create /home/geekygrad/svn-repository/mydoc

Then we need to check out a “working copy”, so from in our home directory we type:

svn co file:///home/geekygrad/svn-repository/mydoc mydoc

Copy the TeX file and the bibliography into it:

cp /home/geekygrad/mydoc.tex /home/geekygrad/mydoc/mydoc.tex
cp /home/geekygrad/mydoc.bib /home/geekygrad/mydoc/mydoc.bib 

Then we add them to the subversion revision control

cd mydoc
svn add mydoc.tex mydoc.bib

And type

svn ci

If all goes well, you’ll get the command-line editor (nano) at the prompt. Type a brief message and press enter. Now you can make changes, safe in the knowledge that if you do something that breaks the document, you can safely revert it by typing:

svn revert mydoc.tex

When you’ve made a few changes and are happy with how it compiles and looks, commit your changes as before

svn ci 

and press enter. Then enter a brief description. You can view all your change messages by typing

svn log

That should be enough to get you started – don’t forget not to delete or try playing with the subversion repository folder we created at the start. That’s where all your revision history lives. In Part Two we’ll look at how to get back to a specific revision and I’ll show you how you can track changes. Then we’ll move on and look at some more advanced repository layouts that open some new possibilities.

As always, I’d love to see questions or comments!