To begin, a couple of definitions:
Revision: One particular state of the files in a project, positioned along one or more lines of history
Edition: One particular variation which has a purpose in being different from other variations
(Notice that I have avided using the word "version"; it's too ambiguous, and will only occur here, if at all, in talking about "version control systems".)
I believe, strongly, that using different Revisions (probably on different branches of a VCS) is not a good way to manage Editions. Personal, embarrassing experience suggests that when branches are created that are not meant ever to merge back together, changes on one branch can get forgotten, or included by mistake, when a change needs to be incorporated in multiple editions.
A far better method is to create a configurable master file, and to include it from a series of top-level files, one for each Edition that is required.
Here is an example with three Editions. It is a very simple exam paper which includes questions, answers, and notes, and uses Viktor Eijkhout's comment
package and Hendrik Mittby's todonotes
package. You may find other packages more useful for your particular case.
To keep it simple, I haven't used any exam- or Q&A-related packages, just Enrico Gregorio's kantlipsum
to pad it out a bit. Please bear in mind that this isn't meant to be an example of "Great Typography", just an illustration of general principles for making polymorphic editions.
The three editions are:
- The student edition: questions only
- The examiner edition: questions and guidelines for answers
- The supervisor edition: questions, guidelines for answers, and my
notes to discuss the development of the exam with my supervisor.
The example consists of five TeX files:
Student.tex:
\documentclass[disable]{memoir} % [disable] is passed to todonotes
\input{preamble}
\excludecomment{answers}
\input{master}
Examiner.tex:
\documentclass[disable]{memoir}
\input{preamble}
\includecomment{answers}
\input{master}
Supervisor.tex:
\documentclass{memoir}
\input{preamble}
\includecomment{answers}
\input{master}
preamble.tex:
\usepackage{kantlipsum}
\usepackage{comment}
\usepackage{todonotes}
\newcommand{\mynote}[1]{\todo[inline]{#1}}
master.tex:
\begin{document}
\section{Philosophy}
Compare and contrast Aristotle's view with that of Kant, expressed in the following quotation:
\begin{quote}
\kant[2]
\end{quote}
\mynote{Should that be Aristotle, or would Plato be more demanding?}
\begin{answers}
\textbf{Answer Notes:}
bear this in mind: \kant[2]
\end{answers}
\listoftodos
\end{document}
I hesitate to say this, but I think you're doing it wrong; but you're close to what is, I think, needed.
The purpose of a branch is to separate an activity, not a structural component.
Thus, I would not have a branch for the "Introduction" file, but for the process "Develop the Introduction". This branch might include, for example, changes not only to Introduction.tex
but also to Preamble.tex
(\usepackage{todonotes}
, maybe) and to Master.tex
(\input{Introduction}
, maybe).
That said, I suspect this is only useful if you're working as part of a team -- one doing the intro, one doing chapters 1-3, one doing chapters 4-8, for example.
As a solitary author, the way I work is this (I use git
):
- To a first approximation, one repo per document
- A master branch which represents the life of the "public" document (also known as a "release" branch)
- If you really need it, a development branch where you accumulate other branches before release
- Ad-hoc branches for specific major items of work (eg "I'm moving from Komascript to Memoir")
- But normal day-to-day evolution (eg just plodding along adding paragraphs) I do on the master branch or, if I need one, the development branch.
- Frequent commits of bite-sized changes (eg It may be useful to separate the commits for the preamble separately
- Try to obey the maxim "Don't commit a broken version" (I try but I don't always succeed)
- Use tagging extensively to keep notes on what a given point in the graph means
Where I am building documents that go out to clients, I also do something strange:
- Commit everything when the document is ready (but not the direct PDF)
- After the commit, format the document anew and check it (this brings in my git commit reference for my dogfooded
gitinfo
)
- Rename the PDF output to, say, client.2013-03-19.pdf, and move it to a folder called "archive", also somewhere in the repo
- Stage and commit the date-specific PDF, and tag that commit appropriately.
This answer, I hope, may also be helpful: Automatic branching for versions and git
Best Answer
You should not use version control for generated files, period.
git
can store binary (non text) files, but it is quite bad at it. And asking for e.g. differences between binary files will just give gibberish, unless you go the extra mile to write a specialized "show differences in humanly understandable format". And without such, the whole point of having files under version control is moot. Or almost.I.e., my lecture notes in LaTeX are under
git
's control. If I want to see differences between versions, they are apparent in the sources, not in the PDFs.