Excursus

One of the much vaunted conceptual advantages of structural markup is the separation of form and content. In LaTeX, the preamble determines the the form of the document, how it is to be typeset, while the main body determines the content of the document and should contain only structural markup, markup that specifies the logical structure of the content.

As I explained in an earlier post, it is useful to independently maintain any LaTeX preambles you may have in version control. Independently, that is, of your present LaTeX project. The rationale is simple. If you discover some heretofore overlooked need requiring a change to the preamble, it would be useful if this change were made available to any other LaTeX document that uses that preamble.

Here is how to do this with Git and Git submodules. (Something similar could be achieved with Subversion and Subversion externals.)

First, let’s create a Git repository for our LaTeX project:

~ $ mkdir myproject
~ $ cd !$
~/myproject $ touch mytex.tex
~/myproject $ git init
Initialized empty Git repository in /Users/markelikalderon/myproject/.git/
~/myproject $ git add .
~/myproject $ git commit -m "Initial commit"

mytex.tex is just an empty file so far. Here is the template LaTeX file that I am currently using:

%!TEX TS-program = xelatex 
%!TEX TS-options = -output-driver="xdvipdfmx -q -E"
%!TEX encoding = UTF-8 Unicode
%
%  my_title
%
%  Created by my_name on date.
%  Copyright (c) year. All rights reserved.
%

\documentclass[12pt]{article} 

% Definitions
\newcommand\mykeywords{} 
\newcommand\myauthor{} 
\newcommand\mytitle{}
\newcommand\mybib{}

\input{preamble/preamble}

%%% BEGIN DOCUMENT
\begin{document}

% Title Page
\maketitle
% \begin{abstract} % optional
% \end{abstract} 
\vskip 2em \hrule height 0.4pt \vskip 2em
% \epigraph{text of epigraph}{\textsc{author of epigraph}} % optional; make sure to uncomment \usepackage{epigraph}

% Layout Settings
\setlength{\parindent}{1em}

% Main Content



% Bibligography
\bibliographystyle{plainnat} 
\bibliography{\mybib} 

\end{document}

A couple of observations about this. First, I am assuming that the included preamble is called preamble.tex and is in a subdirectory called preamble. This is required since we will be keeping our preamble in a Git submodule, and submodules are always subdirectories of the superproject. Second, I have defined some commands, \mytitle, \myauthor, etc. Basically these are all the elements of the preamble that could change from one LaTeX project to another. (So, in the preamble, we have \title{\mytitle}.) This was done to generalize the preamble so it can remain constant from project to project. Also, with a template, it is useful to pull, in this way, all the bits you would need to fill in to the top of the document so that you don’t need to hunt through the code. Once you have added content to mytex.tex, you will, of course, need to commit these changes.

Next we want to push to a remote repository. I will assume that your remote repository is hosted by GitHub (they provide free accounts for publically availbale repositories). So create a repository, “myproject”, on GitHub and then:

~/myproject $ git remote add origin git@github.com:myname/myproject.com
~/myproject $ git push origin master

(where “myname” is your GitHub username).

Now for something mysterious, but it’s required for Git submodules to work. We are going to delete our local Git repository and clone the remote repository:

~/myproject $ cd ..
~ $ rm -rf myproject/
~ $ git clone git@github.com:myname/myproject.com

Now we are going to create a Git submodule. Your preamble, call it preamble.tex, needs to be in a git repository. For the sake of illustration, we will use the preamble I am hosting on GitHub:

% Packages
\usepackage{geometry} \geometry{a4paper} 
\usepackage{url}
\usepackage{pdfsync} 
\usepackage{txfonts}
\usepackage{color}
\definecolor{gray}{rgb}{0.459,0.438,0.471}
% \usepackage{setspace}
% \doublespace % Uncomment for doublespacing if necessary
% \usepackage{epigraph} % optional
 
% XeTeX
\usepackage[cm-default]{fontspec}
\usepackage{xltxtra,xunicode}
\defaultfontfeatures{Scale=MatchLowercase,Mapping=tex-text}
\setmainfont{Hoefler Text}
\setsansfont{Gill Sans}
\setmonofont{Inconsolata}
 
% Section Formatting
\usepackage[]{titlesec}
\titleformat{\section}[hang]{\fontsize{14}{14}\scshape}{\S{\thesection}}{.5em}{}{}
\titleformat{\subsection}[hang]{\fontsize{12}{12}\scshape}{\S{\thesubsection}}{.5em}{}{}
\titleformat{\subsubsection}[hang]{\fontsize{12}{12}\scshape}{\S{\thesubsubsection}}{.5em}{}{}
 
% Headers and Footers
\usepackage{fancyhdr}
\pagestyle{fancy}
\pagenumbering{arabic}
\lhead{\thepage}
\chead{}
\rhead{\itshape{\nouppercase{\leftmark}}}
 
% Bibliography
\usepackage[round]{natbib} 
 
% Title Information
\title{\mytitle} % For thanks comment this line and uncomment the line below
%\title{\mytitle\thanks{}}% 
\author{\myauthor} 
% \date{} % Leave blank for no date, comment out for most recent date
 
% PDF Stuff
\usepackage[plainpages=false, pdfpagelabels, bookmarksnumbered, backref, pdftitle={\mytitle}, pagebackref, pdfauthor={\myauthor}, pdfkeywords={\mykeywords}, xetex, dvipdfmx, colorlinks=true, citecolor=gray, linkcolor=gray, urlcolor=gray]{hyperref} 

Here is what we need to do to create the submodule:

~ $ cd myproject/
~/myproject $ git submodule add git://gist.github.com/835.git preamble
~/myproject $ git submodule init
~/myproject $ git submodule update

Now, if we want to make a change to our preamble and make it available to all our LaTeX projects that use that particular preamble, you need only commit these changes to the Git repository where your preamble lives.

For more information about git submodules, see this tutorial.