[OS X TeX] Version controls for LaTeX book production

[Jon Reades]

Mark Eli Kalderon wrote:
<snip>
> A backup system and a version control system are not the same---I use
> both. Subversion, for example gives you an annotated timeline of changes
> to a directory with diff, merge, and tagging facilities. Neither
> Retrospect nor Time Machine does this.

I'd just like to add to this a bit since version control systems are a 
little tricky to get your head around the first time you encounter them...

1. The two most common version control systems are Subversion and CVS. 
CVS is older and less user-friendly, and most companies that I'm aware 
of have migrated to Subversion in the past year or so.

2. Version control works best with text files, so LaTex is a natural fit 
when compared with, say, Word. The simple reason for this is that with 
binary files you need to understand what the content is in order to 
understand what's changed, whereas for text it's just a case of 
comparing lines. The origins of CVS are in programming, where it was 
used to manage large, distributed projects.

3. The whole idea is that you are always working the same file, and 
don't have some crazy proliferation of My_Document_20071112.doc, 
My_Document_20071112_v2.doc, etc. The server timestamps every operation 
and knows exactly what has changed so you never need to say: "Hmmm, I 
could have sworn there was a v3.doc" or "I wonder if this is the most 
recent version of this document". The server KNOWS about everything that 
has been done (within limits).

So, what are diffs, merges, and tags?

1. Diffs are a command (which can often be run through a web interface) 
allowing you to compare two different versions of the *same* document 
and see what has been added/deleted/modified on a line-by-line basis. 
This gets used a lot in big coding projects where a bug has appeared and 
you need to figure out what has changed since the last good version.

2. Merges are a command that allows you to take two different versions 
of the same document and merge them in to a newer version. If there are 
conflicts (i.e. the same line has been changed in both versions) then 
you'll be asked to make a choice between the two. This often gets used 
when a project has multiple programmers all working on portions of the 
same code base. I work on one bit on my computer and you work on another 
bit, and then we send our changes to the server where they can be merged 
into a new version that combines both sets of changes.

3. Tags are a way of grouping together a set of files with a 
user-defined label so that you can easily retrieve them. A classic case 
of this is tagging all of the files in a project 'v1', 'v2', etc. when 
you have a stable release that has no bugs. Now you can always find the 
set of files that were released as version 1.0 or 1.2 or whatever, even 
if it's five years later.

4. You can also do some interesting things like concurrent branching, 
but that's probably a little too complex to go into right now and not 
really relevant to this type of project.

5. You also need to understand all of these commands in the context of a 
server and checking out/in files. Typically, you have a server somewhere 
that acts as the 'canonical' repository and which everyone on the 
project can access. You then 'check out' the files that you want to work 
with and a copy is downloaded to your computer.
- With a versioning system, someone else can also check out and work 
with the same files, but the changes that you both make are invisible 
until you check your changes back in or commit them to the respository.
- If you commit your changes and the other person checks out or updates 
their local copy then they *automatically* get your changes. No emailing 
around attachments saying "No, *this* is the latest copy" shortly 
followed by "Forget that, use *this* version instead".

So when you're looking a LaTex book, I'd imagine that there are several 
places that Subversion could come in handy:

1. Templating and design -- when setting up the layout and design it may 
be enough initially for the graphic designer to work with a draft copy 
of the text so that they can work with appropriate content but not worry 
about updating it all later manually.

2. Copy editing -- the copy editor can work with each chapter as it's 
checked in by the author. They can make changes and the author and 
editor can review the edits together on a line-by-line basis online.

3. Revisions -- say you get to a pre-publication version but the 
designer now needs to make changes to the text in order to get the 
layout that looks best, then now is your time to tag something so that 
you can always extract the original text if you need it again.

Hope this helps a little bit,

jon
-- 
Jon Reades
MPhil/PhD Candidate
Bartlett School of Planning

e: j.reades at ucl.ac.uk
m: 0797.698.7392