Excursus

LaTeX is great for complex documents. (Of course, other forms of markup are good as well. DocBook comes to mind.) When working on a complex LaTeX document, it is important, nay, imperative to keep it in some form of version control. (The necessity may not be apparent until you actually use version control—if you don’t, well, just trust me, at least for now.)

I have been posting about a popular, open source form of version control, subversion. If you are keeping your complex LaTeX document in a subversion repository, it would be useful to include information about the current revision, the “Who?”, “What?”, “When?”, and “Where?” of the last committed change, within your document. You could enter this information by hand, but this would be tedious and unreliable. Fortunately, there are LaTeX packages that can help. There are three:

1. svn

2. svninfo

3. svn-multi aka svnkw

The svn package doesn’t work if your LaTeX document comprises multiple files. So that’s out. The svninfo and svnkw packages happily do not share this limitation. The svninfo package, however, has a terrible limitation IMHO. It only registers revision information when you check out the document. This means if you create a LaTeX document, add it to your working copy, and commit the addition, the revision information, the “Who?”, “What?”, “When?”, and “Where?”, will never be registered. So that’s out. That leaves svnkw—which worked well for me. Let me detail how I use it.

In the preamble, I have the following:

\usepackage{svnkw}

\svnidlong

{$HeadURL$}

{$LastChangedDate$}

{$LastChangedRevision$}

{$LastChangedBy$}

\svnRegisterAuthor{kalderon}{Mark Eli Kalderon}

The first line:

\usepackage{svnkw}

should be familiar to LaTeX users—it loads the svnkw package. The command:

\svnidlong

{$HeadURL$}

{$LastChangedDate$}

{$LastChangedRevision$}

{$LastChangedBy$}

gets the url of the file in the repository, the date of the last revision, the last revision number in which the file was changed, and who made the change, from subversion.

---

Update Sorry, missed a crucial step here. To get this to interact with subversion, you need to enter the following in the Terminal:

svn propset svn:keywords 'HeadURL LastChangedDate LastChangedRevision LastChangedBy' foo.tex

where foo.tex is the name of your LaTeX source. Once this is set, when you commit a change to your repository or receive a change by updating your working copy, this information will be registered. Apologies for the oversight.

---

Who made the change is the username of the commiter. You might want to include the real name of the commiter. The command:

\svnRegisterAuthor{username}{real name}

registers this information.

The commands:

\svnidlong

and

\svnRegisterAuthor

registers the information described above. Now we want to use this information. There are different ways to do this. See the package documentation for sknkw for more details. I find it useful to include this information in a footer. Here’s how I do it. In the preamble, I include the following:

\usepackage{fancyhdr}

\pagestyle{fancy}

\lfoot{\tiny{URL: \url{\svnkw{HeadURL}} ; \space Last changed on: \svndate ; \space Revision: \svnrev ; \space Author: \svnFullAuthor*{\svnauthor}}}

\cfoot{}

\rfoot{}

The first line:

\usepackage{fancyhdr}

loads the fancyhdr package. This package allows you to format headers and footers. The second line:

\pagestyle{fancy}

loads the default pagestyle of the fanchdr package. fancyhdr divides footers into three fields:

1. the left field

2. the center field

3. the right field

To place content in these field you use the commands:

\lfoot{}

\cfoot{}

\rfoot{}

respectively. Whatever is between the brackets is inserted in the relevant field. If nothing is between the brackets, then the field is blank. Since there is a lot of information to be placed in the footer, it makes sense to have it flush left, and so I left the center and right fields blank. Let’s take a closer look at the line that is doing all the work:

\lfoot{\tiny{URL: \url{\svnkw{HeadURL}} ; \space Last changed on: \svndate ; \space Revision: \svnrev ; \space Author: \svnFullAuthor*{\svnauthor}}}

That’s a little daunting, so let’s build up to it, step by step. I want the information in the left field so, of course, I use the command:

\lfoot{}

In the left field I want to include the url of the file, the date of the last change, the revision number of the last change, and the author of the revision. Let’s begin with the url. The command:

\svnkw{HeadURL}

yields the value encoded by:

{$HeadURL$}

in the preamble. LaTeX provides the means of nicely formatting urls. To do this we use the url package loaded in the preamble with:

\usepackage{url}

and we use the command:

\url{}

This gives us:

\url{\svnkw{HeadURL}}

Next the date of the last revision. This is easier. The command:

\svndate

yields the value encoded by:

{$LastChangedDate$}

in the preamble. The revision number is easy as well. The command:

\svnrev

yields the value encoded by:

{$LastChangedRevision$}

in the preamble. The command:

\svnauthor

gives the value encoded by:

{$LastChangedBy$}

in the preamble. Remember, this is the username of the commiter. But, I wanted the full name of the commiter. The command:

\svnFullAuthor*{\svnauthor}

gives the full name of the author registered with:

\svnRegisterAuthor

and the asterisk is a switch that gives both the username and the full name of the commiter. So far, we now have:

\lfoot{\url{\svnkw{HeadURL}} \svndate \svnrev \svnFullAuthor*{\svnauthor}}

Three further refinements are called for.

First, it is useful to label this information. Thus, for example, the value of:

\svnrev

is just a number. A label would provide some useful context for understanding what the number represents. Similarly for the rest of this information. Moreover, it would be useful to clearly distinguish this information, so lets separate them with semicolons. This gives us:

\lfoot{URL: \url{\svnkw{HeadURL}} ; Last changed on: \svndate ; Revision: \svnrev ; Author: \svnFullAuthor*{\svnauthor}}

Second, if you typeset your document at this point, a small problem will become evident. For some reason, the svnkw does not insert spaces between the values of its commands even if you have spaces between them in your document. To correct this we use the command:

\space

and get the following:

\lfoot{URL: \url{\svnkw{HeadURL}} ; \space Last changed on: \svndate ; \space Revision: \svnrev ; \space Author: \svnFullAuthor*{\svnauthor}}

Third, this information is really of editorial interest only. I want it to be there, but not in the way. So let’s make it really small. To do this we wrap the content with the command:

\tiny{}

to get the final product:

\lfoot{\tiny{URL: \url{\svnkw{HeadURL}} ; \space Last changed on: \svndate ; \space Revision: \svnrev ; \space Author: \svnFullAuthor*{\svnauthor}}}

One last thing. Suppose you are using pdflatex as your typesetting engine to directly generate a PDF of your LaTeX document. pdflatex is usefully used in conjunction with the hyperref package that does a lot of nifty things not least of which is turning urls into functional hyperlinks. If you do, then clicking on the url of the file will open that file in your browser. Of course, your browser will ask you for your username and password if it hasn’t already saved that information for you.

Here is a screen shot of the final result: