[OS X TeX] Version controls for LaTeX book production

[Alain Schremmer]

I have a "repository of stuff that might turn out handy when I get to  
that point" and a copy of your post just went right in there.

Grateful regards
--schremmer


On Nov 12, 2007, at 10:41 AM, Jon Reades wrote:

> 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
> -------------------------- Helpful Info --------------------------
> TeX FAQ: http://www.tex.ac.uk/faq
> List Reminders and Etiquette: http://www.esm.psu.edu/mac-tex/list/
> List Info: http://email.esm.psu.edu/mailman/listinfo/macosx-tex
> List Archive: http://tug.org/pipermail/macostex-archives/
> Mac-TeX Website: http://www.esm.psu.edu/mac-tex/
>