2012-10-12

Some time ago I had to give a hand to my girlfriend in writing one of her physics papers using LaTeX. Obviously she provided the content, and asked me for some advice on how to write the LaTeX code. It wasn’t a though task, but the source code was a real mess because of all the (sometimes huge) equations being mixed up with the text.

I started marking all the equations with intrusive comments to help my eyes set them apart from the text, but the code was getting even more unreadable.

Moreover, we wanted to split the workload this way: you write the equations, and I write the text around. We tried using git to merge our edits to the sources, but it was often complaining about merge conflicts, because we were working on the very same files thus making conflictual edits by mistake.

Then I though I had to separate the equations from the code.

How? Since making a single file for each equation is overkill and really unconfortable for the person writing the equations, I searched for a way to put all the equations in a separate file, tag them with an identifier, and have a command like \loadeq{23} to include them in the main source file.

I couldn’t find anything pre-made, but I came across this tex.stackexchange.com post.

The LaTeX package catchfilebetweentags allows you to include parts of other files delimited with a tag (basically a pseudo-XML tag wrapped in a LaTeX comment), by using the command \ExecuteMetaData[file.tex]{tag}.

I created the file equations.tex file as follows (please notice the pseudo-XML tags around equations):

% Equations dictionary

\documentclass[11pt]{article}

\usepackage{amssymb,amsmath}

% Begin document
\begin{document}

%<*eq001>
$$F\left (x_1,\dots,x_n,\frac{\partial u}{\partial x_1},\dots,\frac{\partial u}{\partial x_n},\frac{\partial^2 u}{\partial x_1\partial x_1},\dots,\frac{\partial^2 u}{\partial x_n\partial x_n},\dots \right).$$
%</eq001>

%<*eq002>
$$u_x=\frac{\partial u}{\partial x}, \quad\quad\quad u_{xy}=\frac{\partial^2 u}{\partial y \partial x}=\frac{\partial u}{\partial y}\left( \frac{\partial u}{\partial x} \right).$$
%</eq002>

% A bunch of other equations...

\end{document}


And I defined the custom command \loadeq in my main.tex source file.

\usepackage{catchfilebetweentags}

}


Including an equation in main.tex became easy like this:

\loadeq{001}


The conclusion is that loading the equations from a unique external file proved to be a good idea: the code was more readable, and we efficiently divided the workload.