Take the 2-minute tour ×
TeX - LaTeX Stack Exchange is a question and answer site for users of TeX, LaTeX, ConTeXt, and related typesetting systems. It's 100% free, no registration required.

Building on What are good working practices for VCS with LaTeX documents?, are there best practices for formatting (La)TeX source files to take advantage of version-control systems?

I keep my résumé in LaTeX form in a git repository, for example, saving various job-offer–specific tweaks in branches. When I update the formatting or basic information on the main branch, I try to rebase the tweaked branches to fit, but the operation tends not to apply cleanly. I don’t have this problem with my C code, so I’m wondering how I might do better with LaTeX source.

share|improve this question
1  
See my answer here tex.stackexchange.com/a/1488/86 and the links therein. –  Loop Space Jul 6 '12 at 22:12

2 Answers 2

This isn't an optimistic answer, nor, probably, a very good one. It is based on my experience using git, and the accidents I had while trying to use git to manage different configurations within a number of projects.

Why I think rebase isn't the answer

I believe that the philosophy of version control systems is directed at linear development with asynchronous side-events. What I mean by this is that the flow is always forwards, never sideways. When branches are created, their use, by design, is to provide a semi-independent development stream with one of three destinies:

  1. It is merged back into a single mainline development stream

  2. It stops. A good example of this might be the 'archive' branch from Andrew Stacey's excellent description, or a product release.

  3. In some cases, it stops, but fixes are added in from time to time. This is more likely, I think, with post-release bug fixes than it is with archived documents, which have a very different life cycle and are used, if at all, in a very different way.

Rebase is a form of merge; both are designed to, in some sense, bring the development streams 'back together' by including all the history, and this is not what you want when the development streams are, in fact, diverging configurations. Models 1 and 2 don't work for handling configurations, and, on the three or four times I've tried to do this, I've always ended up having to restore my complete project and repo from backup. I accept that this could be seen as careless -- I'm still learning git the hard way!

Why I think cherry-picking is better than rebase, but still not the answer

Another option I've tried, and am still trying, is to use cherry-picking. Here you can select individual commits (as patches, conceptually) and apply them to the head of some other branch. This works a bit better, but it is essential that you separate your commits which change a given configuration from those which apply to many or all configurations. (That's probably obvious, but it took me a few failures to learn.)

I'm currently using this method to manage a rather complex proposal where I am (one day to be) a subcontractor. The proposal has two configurations: one for the prime contractor, and one for the end client, with some bits just omitted and some with minor changes of wording. Managing changes this way is taking much more work than I had hoped.

What I plan to do for all my new projects that need this

In the end, I've come to the conclusion that this isn't the best approach, either. I now firmly believe that the different configurations should be handled in a single branch by having relatively small and simple top-level files, one for each configuration, inputting one or more master files which are configured through the use of the verbatim 'comments' environment, the comments package, or my own, rather more limited, tagging package (though even vulture chicks are pretty in the eyes of their mum). My answer to Multilingual document is a very simple example.

Under this regime, you can archive or provide other fallback reference points through the use of tags or branches (whichever you prefer). But all of your configurations are carried along together, not separately, and I think this makes the whole thing (both version and configuration control) a lot easier.

Closing ideas

One positive thing I can recommend here for git users: Syntevo's Smartgit. It's index editor allows you to break changes up into smaller bits for multiple commits to allow clean cherry-picking, and it's stashing interface is clean and easy to use.

As I said at the start, this probably isn't the best answer; I'm working at the limits of my mental capacity here. So I'd welcome comments, criticism, and improvements from my technical superiors.

share|improve this answer
    
tl;dr: How is that answer concerned with formatting the source code? –  Martin Schröder Jul 7 '12 at 16:39
    
@MartinSchröder: It isn't. I'm just trying to explain to OP that I think he may be solving a lesser problem before a greater one. And to point out that formatting the source code isn't going to solve his rebase problem. –  Brent.Longborough Jul 7 '12 at 16:57
up vote 5 down vote accepted

Per Andrew Stacey’s comment above, his tips at http://www.math.ntnu.no/~stacey/HowDidIDoThat/LaTeX/versioning.html are handy. Of particular use is dividing the layout code from the content (a good idea anyway) and managing line-wraps.

I tend toward long sentences with many dependent clauses, and my rewrites often combine or split these, so his advice about breaking lines at sentence boundaries is not quite enough for me; I’ve therefore gone beyond those tips, all the way to writing my prose as if it were blank verse: breaking lines at most punctuation points and at other phrase boundaries.

I would write the above paragraph/sentence thus:

I tend toward long sentences with many dependent clauses,
and my rewrites often combine or split these,
so his advice about breaking lines at sentence boundaries is not quite enough for me;
I’ve therefore gone beyond those tips,
all the way to writing my prose as if it were blank verse:
breaking lines at most punctuation points
and at other phrase boundaries.

(It’s somewhat exaggerated from my actual writing style, for illustration.)

ETA: I’ve just discovered a name for this technique: semantic linefeeds. Brandon Rhodes, in a blog post on the subject, quotes Brian Kernighan’s 1974 version of “UNIX for Beginners” [PDF]:

Hints for Preparing Documents

Most documents go through several versions (always more than you expected) before they are finally finished. Accordingly, you should do whatever possible to make the job of changing them easy.

First, when you do the purely mechanical operations of typing, type so subsequent editing will be easy. Start each sentence on a new line. Make lines short, and break lines at natural places, such as after commas and semicolons, rather than randomly. Since most people change documents by rewriting phrases and adding, deleting and rearranging sentences, these precautions simplify any editing you have to do later.

share|improve this answer

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.