Latex with Automatic Versions and Dates

I use Latex a lot on documents that are stored in a CVS or SVN repository. The approach with Latex is that you write your document in the Latex programming language, and then you “compile” or “execute” your latex file to produce a pdf. Frequently when writing, and very frequently when writing with a coauthor, I like to compile early, incomplete versions of the paper and distribute the resulting pdf. After a few of these pdf’s are floating around, however, people using them start wondering, when you talk to them, whether they have the newest version or not....

A good way to approach this is to put some kind of version-specific information on the early copies. For example, it is good to put the date of the file into the pdf. Then people can say things like, “I read the June 23 version of the paper.” For best functioning, note that this date should not be the date the pdf was created, but the date of the last modification to the Latex file. That way, the file can be recompiled later (e.g., by your coauthor, on a different day) without changing the result.

A more specific piece of information is the repository’s version number for the file as of the last compile. This is particularly sensible for SVN repositories, since the version number corresponds to the entire repository instead of to individual files. Then you can put on your title page something like, “compiled from version 1849”, even if your Latex source code includes more than one file.

Now that this problem and solution have been stated, it is straightforward to work out a system for working this way. However, the tools do not support this version-stamping and date-stamping by default, so you have to work a little bit. This page accumulates the scripts and build-file code that I use, so that others might benefit. Maybe one day these things will become popular enough to be supported more directly.

version.tex

My general approach is to have the build system create a version.tex containing the date and version information. An example version.tex file is as follows:

%Automatically generated file.  See ./scripts/getversion.
\newcommand\svnversion{1601}
\newcommand\svndate{Mon, 30 Jan 2006}

The main Latex file can then include this file and make use of the \svnversion and \svndate commands that version.tex provides. It will probably use them in a \date command, like this:

\include{version}
\title{Coolest Stuff Ever}
\date{{\svndate}\hspace{1em}(revision \svnversion)}

Computing version.tex

The next piece of the puzzle is the script to compute the version.tex file. I only have a script for SVN right now, not for CVS.

This is a natural task for Perl. The following script is what I use:

#!/usr/bin/perl
# Retrieve version info for the list of svn-managed files listed
# in the argument vector.  Print out Latex definitions holding
# the retrieved information.

$scriptname = $0 ;

$maxversion = 0 ;
$newestdate = "" ;

for $file (@ARGV) {
    $version = 0;
    $date = "";

    open(RAWINFO, "svn info $file |");
    while(<RAWINFO>) {
    if(/^Revision: ([0-9]+).*/) {
        $version = $1;
    }

    if(/^Last Changed Date: .*\((.*)\)/) {
        $date = $1;
    }
    }

    if($version==0 || $date eq "") {
    print("file $file, version $version, date $date\n");
    exit(2);
    }

    if($version > $maxversion) {
    $maxversion = $version;
    $newestdate = $date;
    }
}

print "%Automatically generated file.  See $scriptname.\n";
print "\\newcommand\\svnversion{$maxversion}\n";
print "\\newcommand\\svndate{$newestdate}\n";

This script expects to have the list of files to consider for version.tex be listed on the command line. (Typically, a single repository may well have a number of other files in it, so you don’t want to version all of them.) It then issues svn commands to find the modification times and revision numbers of the files, chooses the maximum of them, and prints out the contents that should be placed in the version.tex file.

Integration with Jam

The final step is to integrate the computation of version.tex into your build process. I use Jam, but the approach should be the same with make, ant, or whatever else you use. (If it’s hard, then you need a better build tool! Make your life easier!)

The basic approach is that version.tex depends on all of the files you want to version, and tell it to use the above script to build it. Here are the relevant chunks from one Jamfile I use:

rule Version {
  DEPENDS $(1) : $(2) ;
  DEPENDS $(1) : scripts/getversion ;
  Clean clean : $(1) ;
}

actions Version {
  ./scripts/getversion $(2) > $(1).tmp
  mv $(1).tmp $(1) ;
}


Version version.tex :
 phdtr.tex
 gatech-thesis-lexpatch.sty

 macros.tex 
 autoref-tweaks.tex 
 acknowledgements.tex 
 motivation.tex 
 previous.tex 
 algdevel.tex 
 semantics.tex 
 dataflow.tex 
 ddp.tex 
 correctness.tex 
 implementation.tex 
 chuck.tex 
 experiments.tex 
 langchanges.tex
 future.tex 
 sourcetags.tex 
 conclusion.tex 


 screenshots/ss-askflow.png 
 screenshots/ss-asktype.png 
 screenshots/ss-chuckresponders.png 
 screenshots/ss-chucksenders.png 
 screenshots/ss-editpolice.png 
 screenshots/ss-enquirer.png 
 screenshots/ss-flowanswer.png 
 screenshots/ss-implementors.png 
 screenshots/ss-sendersof.png 
 screenshots/ss-typeanswer.png 
 screenshots/ss-typefail.png 
 screenshots/ss-typesucceed.png 
 screenshots/ss-useduration1.png 
 screenshots/ss-useduration2.png 
 screenshots/ss-varrefs1.png 
 screenshots/ss-varrefs2.png 

 screenshots/ex-goal.png
 screenshots/ex-start.png
 screenshots/ex-firstsubgoals.png
 screenshots/ex-updatey.png
 screenshots/ex-updatexfory.png
 screenshots/ex-updatep1.png
 screenshots/ex-prune.png
 screenshots/ex-updatep1forprune.png
 screenshots/ex-updateQ.png
 screenshots/ex-updateP1trivial.png
 screenshots/ex-updateXtrivial.png

 screenshots/speed.png
 screenshots/precision.png

 screenshots/ary1resp.png
 screenshots/basic-response.png
 screenshots/dotResp.png
 screenshots/factResp1.png
 screenshots/factResp2.png  ;

Includes phdtr.tex : version.tex ;

There are better approaches imaginable than having an explicit list of files that need to be versioned. It would be nice if you could say, “have version.tex account for all files needed to build blah.dvi”. This should be doable using include-file scanners: whenever you notice that A includes B, then A’s version file should account for the version of B. However, I have not explored that approach.