Archive for April, 2010

Introduction

Creating graphics for latex can be a real pain. There are a number of different options for doing this, though none of them is completely ideal. If you’re comfortable using regular latex and generating DVI’s, then the pstricks package is a very powerful tool. If you prefer generating PDF (now an open standard) files (as I do) then the PGF/TikZ latex packages are a very powerful and can do just about everything… except that you have to code your graphics… which is a very slow iterative process. The GNU Diagramming tool Dia can create block diagrams and flow charts and can export either `pstricks` or `tikz` code. Inkscape is a much nicer user-oriented graphical vector drawing tool, but doesn’t have native support for for LaTex, and creating graphics including LaTeX math-mode is a real pain. In any case, I’ve found a number of situations where a figure like the following was pretty easy to do create in Inkscape.

Inkscape Figure for LaTeX

Getting the Fonts

In order to get the math font’s to look like they do in LaTeX, though, you need to have the font’s installed where Inkscape can find them. Unfortunately, LaTex uses `type1` postscript fonts, while Inkscape can only find font’s that windows has installed in the system, which includes true-type or open-type fonts. Fortunately you can get the fonts for “Computer Modern” (Knuth’s Font uses as the default in LaTeX) from the TeX archives in these formats. Simply download these fonts, and install them in windows (drag them to C:/Windows/Fonts). The next time you run Inkscape, it will have these font’s available and you can use them in your pretty graphics.

Other Fonts

There are some other font’s that you’ll find used by latex that aren’t in OTF or TTF format though. The only (open-source) way I’ve found to convert type-1 font’s to OTF is through an ancient tool called Font-Forge. It’s an X-Windows program so you’ll have to install the Cygwin x-server, or, luckily, someone has ported it to MinGW (native Win32).

Tex Text plugin

Lately, I’ve been using the Tex Text plugin instead of using latex fonts with regular inkscape text. The interface is a little tedious, but it works quite well (and it’s a lot less tedious then laying out the text by hand).

HTML Documentation with Equation Numbers (Referencing an External PDF Document with Doxygen’s HTML Documentation)

So, anyone who uses Doxygen to document their code knows that it’s pretty much the most amazing thing ever. Seriously, it’s awesome. One cool thing about it is the ability to reference external documentation. For instance, if you use a library in your code and you want to include the library’s documentation with your own. However, let’s say that (hypothetically of course) you’re an academic… and the code you write implements some theoretical design or model. In that case, you may actually want your documentation to reference a paper, or a report that you’ve written. Perhaps, even many such papers or reports.

The Problem

In particular, let’s say that you’re a grad student, in the process of writing a paper (and of course, you used LaTex… because, well, why wouldn’t you?) and you go and write some code to simulate or demonstrate some elements of that paper. In that case, some of your functions may implement certain equations. Some of your classes (if it’s object oriented) may implement certain models. For an example, lets say this is your paper:

Let’s also assume that you’ve been good, and have been documenting your code with Doxygen. Let’s say you had some c++ class that implemented your model and it’s definition looks something like this:

```1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 /** * file CTheoreticalModel.h * author Joe Author (jauthor@institute.edu) * date Apr 17, 2010 * brief Definition file for CTheoreticalModel class */   #ifndef CTHEORETICALMODEL_H_ #define CTHEORETICALMODEL_H_     /** * brief Theoretical Model derived in section 2, on page 1 * * This is a detailed description of the model */ class CTheoreticalModel { private: double m_alpha; ///< [parameter] defined in equation 2.1 double m_beta; ///< [parameter] defined in equation 2.2   public: /** * brief Construct a new model using the given parameters * param[in] alpha [parameter] defined in equation 2.1 * param[in] beta [parameter] defined in equation 2.2 */ CTheoreticalModel( double alpha, double beta );     /** * brief calculates [some property] by implementing algorithm 2.1 * on page 1 * return [some property] */ double algorithmA();     /** * brief updates the model by [some parameter] according to the * dynamics of equation 2.4 * param[in] gamma [parameter] defined in equation 2.3 */ void equationB( double gamma );     /** * brief tests [some parameter] against the model; implements * equation 2.6 * param[in] theta [some parameter] defined by equation 2.5 */ bool testC( double theta ); };   #endif /* CTHEORETICALMODEL_H_ */```

Then the html documentation that doxygen will generate will look like this:

Now let’s say that you talk to your advisor and he suggests that maybe section 2 should come after section 3. Moreover, you add a bunch of content to section 1 so now all of the code for this model is on page five. So then you end up with this:

So now you have to go back and change all of the equation numbers and page references in your code. But wait, when we wrote our document we “`label{}`“ed all of our equations, algorithms, and sections. Wouldn’t it be cool if we could just reference those in the comments? Doxygen exposes latex’s math mode for us to document inline equations. It uses latex to render the equations, and then uses dvipng to turn those into png images. Moreover, latex has the `xr` package, which allows us to reference labels from other documents. Lastly, the “`ref{}`” command is valid inside math-mode. So we have all the tools we need, but there is one slight problem. In order to use the `xr` latex package, we need to include the “`externaldocument`” command in the header of the document.

The solution

Now here’s the fun part. When Doxygen renders all of the equations, it does so by generating a single latex source file called “`_formulas.tex`“. We don’t have explicit access to modify the preamble of that source file, but we are allowed to add optional packages to the list of what is included. We do that by modifying the “`EXTRA_PACKAGES`” line of the doxyfile. For instance, if we edit the doxyfile like this:

```1 2 3 4 5 6 ... # The EXTRA_PACKAGES tag can be to specify one or more names of LaTeX # packages that should be included in the LaTeX output.   EXTRA_PACKAGES = amsmath xr amsfonts ...```

then when doxygen generates `_formulas.tex` it will include in the preamble a list of includes like this

```1 2 3 usepackage{amsmath} usepackage{xr} usepackage{amsfonts}```

Note that Doxygen tokenizes the list of packages (parses it) at whitespace, and then takes each token and wraps it with “usepackage{}”, inserting it into the header. We can hijack this method of input by making `EXTRA_PACKAGES` variable like this

```1 2 3 ... EXTRA_PACKAGES = amsmath xr}externaldocument[paper-]{dummy}% amsfonts ...```

Then the preamble of `_formulas.tex` will look like this

```1 2 3 4 usepackage{amsmath} usepackage{amsfonts} usepackage{xr}externaldocument[paper-]{dummy}%} usepackage{hyperref}```

Note how we use a comment character (percent) to comment out the closing bracket that doxygen put’s around our ‘package’. Now we have an extra command in our preamble. If you haven’t looked up the `xr` documentation yet, this command means to look for a file called “`dummy.aux`” generated by latex. The package extracts all the labels from that file and appends “`paper-`” to the front of the label names. Now we can change our code documentation to look like this:

```1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 /** * file CTheoreticalModel.h * author Joe Author (jauthor@institute.edu) * date Apr 17, 2010 * brief Definition file for CTheoreticalModel class */   #ifndef CTHEORETICALMODEL_H_ #define CTHEORETICALMODEL_H_     /** * brief Theoretical Model derived in section f\$ref{paper-sec:Model}f\$, * page f\$pageref{paper-sec:Model}f\$ * * This is a detailed description of the model */ class CTheoreticalModel { private: double m_alpha; ///< [parameter] defined in equation f\$ref{paper-eqn:alphaDef}f\$ double m_beta; ///< [parameter] defined in equation f\$ref{paper-eqn:betaDef}f\$   public: /** * brief Construct a new model using the given parameters * param[in] alpha [parameter] defined in equation * f\$ref{paper-eqn:alphaDef}f\$ * param[in] beta [parameter] defined in equation * f\$ref{paper-eqn:betaDef}f\$ */ CTheoreticalModel( double alpha, double beta );     /** * brief calculates [some property] by implementing algorithm * f\$ref{paper-alg:SomeAlgorithm}f\$ on page * f\$pageref{paper-alg:SomeAlgorithm}f\$ * return [some property] */ double algorithmA();     /** * brief updates the model by [some parameter] according to the * dynamics of equation f\$ref{paper-eqn:SomeEquation}f\$ * on page f\$pageref{paper-eqn:SomeEquation}f\$ * param[in] gamma [parameter] defined in equation * f\$ref{paper-eqn:gammaDef}f\$ */ void equationB( double gamma );     /** * brief tests [some parameter] against the model; implements * condition f\$ref{paper-eqn:SomeCondition}f\$ * param[in] theta [some parameter] defined by equation * f\$ref{paper-eqn:thetaDef}f\$ */ bool testC( double theta ); };   #endif /* CTHEORETICALMODEL_H_ */```

Now all we have to do is dump `dummy.aux` (generated when we build the paper using latex) into the `html` directory where doxygen is going to build `_formulas.tex` and then when we make the documentation it looks like this:

Sure, all the references are images… which isn’t particularly great, but it’s a lot better than having to go in and change the labels every time we make a change to the referenced document. Whenever writing a code and a referenced document are done in parallel, this could be quite a handy trick. If you want the html document to look a little more professional, add a package that will set the font to the same as the font set by your doxygen `CSS` stylesheet.

If you want to play around with the files used in this post, pick them up here: dummy.7z. Create the latex document with the following command.

```1 latex dummy.tex```

Then copy `dummy.aux` into the `html` directory.

```1 cp dummy.aux html/```

Then run doxygen

```1 doxygen doxyfile```