Writing a Thesis in LaTeX on Mac OS X

This page is ongoing work, thus please be patient until I finished the documentation.

Since I have been using LaTeX under Mac OS X for quite a while now, I’d like to write down my experiences and especially my configurations here, to share it both with you and my future self. My configuration is build on the usage of different building blocks. Most of which should be exchangeable with the modules of your choice, especially regarding the editor.

The configuration is supposed to be easy to use and in particular convenient, i. e., not having to invoke (pdf)latex over and over again. However, all this comfort requires some configuration work first and this might not be completely easy, especially compared to Linux setups, where you just need to call aptitude install blabla.... The LaTeX environment I introduce here is based upon the following tools.

  • Texlive: the TeX system
  • Latexmk: the build system
  • Skim: the pdf viewer
  • R the statistical/plotting tool - optional
  • Scrivener professional writing tool - optional

I hope you find the following pages useful and would be happy if you drop some comments!
iss

Flattr: 

Prerequisites

First of all: get the packages! To compile any LaTeX document you will need to have a TeX distribution installed. On OS X my distribution of choice is MacTeX. You can get the distribution from the web site or from any of its mirrors.

Just for the sake of completeness: For processing, number crunching, or algorithmic prototyping I like to use either Python or Matlab (sometimes also C++), whatever fits best or where I have the right tools at hand.

For my statistics stuff as well as the graphs, i. e., the visual data presentation, I like to use The R Statistical Project. As a Home Brew user, you can install R simply using the following command.

brew install R

As a convenient R GUI I recommend RStudio, which integrates the standard R workflow with console, script editor, plot and workspace tiles nicely. You need to install it separately from the R base distribution and home brew will tell you, how to connect RStudio to R easily.

Then, get Skim. Skim is a PDF viewer like Acrobat Reader or Preview, but observes the opened PDF file for changes and provides further functionality like PDFSync (where you can Cmd-Shift-Click into the document to redirect the editor to the appropriate line in the TeX file).

Now, get your favorite editor, if you don’t have it yet. Some examples for what it might be:

If you are going to write a long thesis you might want to checkout Scrivener additionally. With Scrivener you can elegantly create LaTeX documents using MMD3 (Multi Markdown 3) and compile them into LaTeX and the PDF. However, this requires a least basic understanding of LaTeX, Markdown and Scrivener itself. Hence, I postpone this topic now to cover it in a later section of this document.

Read on to go into further details!

Flattr: 

Useful Packages in the Preemble

Latex provides a wide variety of additional packages to extend it’s functionality or simply to make some things more convenient, automatic, and simpler to maintain.The following table gives an overview of the packages I use in a daily fashion for scientific publications (apart from the standard packages).

microtype

This is a very subtile but nice package that optimizes the typography of the paper on micro-level, e. g. by character protrusion and font-expansion. Just add the package to the preamble and see the difference - best recognized using an updating PDF viewer like Skim.

xfrac

When in text mode (not equations), xfrac enables you to create nice fractions in both text mode and math mode. xfrac defines the command \sfrac, which can be used as in \sfrac{1}{2}.

siunitx

Package for nice formatted (si-)units in a consistent way. To show 48 000 kHz, you can say: \SI{48000}{\kilo\hertz}. It not only formats the units nicely but also inserts thousands separators if desired and is heavily customizable. Anyhow, I am drifting away from using it these days, as it’s a lot to write something like \SI{128}{\kilo\bit\per\second} in contrast to just $128\,$kbps.

todonotes

Package for inserting TODO statements in nice colorful boxes - so that you won’t forget to fix/remove them. To add a todo statement, use something like \todo{Find better wording here}.

subfigure

Every once in a while, you might need subfigures in a paper. This package provides a nice solution for it, including enumeration of subfigures and references support. To add a subfigure, use something like this:

\begin{figure}%
\centering
\subfigure[First.]{...}\qquad
\subfigure[Second figure.]{...}\\
\subfigure[Third.]{\label{3figs-c}...}%
\caption{Three subfigures.}
\label{3figs}
\end{figure}

tikz

THE drawing markup for latex. It’s easier than most other markups I have seen so far and important if you want to use R’s tikz device (as described later). The figures generated with tikz integrate nicely into the document and look like being set with LaTeX. An example Markov Chain:

\begin{tikzpicture}[node distance=20mm,
    state/.style={
    % The shape:
    circle,minimum size=8mm,rounded corners=3mm,
    % The rest
    draw=black}]
% draw the nodes
\path (0,0)  node (A) [state] {A}
      (4,0)  node (B) [state] {B}
      (2,1)  node (D) [state] {D}
      (2,-1) node (M) [state] {M};
% draw the transitions
\draw [->] (A) to [bend left=15] (D);
\draw [->] (D) to [bend left=15] (A);

\draw [->] (D) to [bend left=15] (B);
\draw [->] (B) to [bend left=15] (D);

\draw [->] (B) to [bend left=15] (M);
\draw [->] (M) to [bend left=15] (B);

\draw [->] (M) to [bend left=15] (A);
\draw [->] (A) to [bend left=15] (M);
\end{tikzpicture}

algorithm2e

Not the easiest algorithm package, but maybe the most powerful. Strange syntax, really, but nice for Pseudocode. An example taken from the manual:

\begin{algorithm}[H]
  \SetAlgoLined
  \KwData{this text}
  \KwResult{how to write algorithm with \LaTeX2e }
  initialization\;
  \While{not at end of this document}{
    read current\;
    \eIf{understand}{
      go to next section\;
      current section becomes this one\;
    }{
      go back to the beginning of current section\;
    }
  }
\caption{How to write algorithms}
\end{algorithm}

listings

Package for code listings supporting different programming languages, like C/C++, Ruby, Octave, Python, etc. An example from the manual:

\begin{lstlisting}
if (i<=0) then i := 1;
if (i>=0) then i := 0;
if (i<>0) then i := 0;
\end{lstlisting}

booktabs

Very nice table formatting. Note that you might want to change the arraystretch for tables using \renewcommand{\arraystretch}{1.2} in your preamble. The package also adds new rules (i. e., horizontal lines) for top, bottom, and mid separators. The following listing shows a simple example for a table using the booktabs package:

\begin{tabular}{@{}llr@{}}
\toprule
\multicolumn{2}{c}{Item} \\
\cmidrule(r){1-2}
Animal & Description & Price (\$) \\
\midrule
Gnat      & per gram & 13.65 \\
          & each     &  0.01 \\
Gnu       & stuffed  & 92.50 \\
Emu       & stuffed  & 33.33 \\
Armadillo & frozen   & 8.99 \\
\bottomrule
\end{tabular}

hyphenat

A package I use mostly for suppressing hyphenation in certain words. Can do more, as I’ve heard, but I don’t use it. For example, to suppress hyphenation of the word curiosity use \nohyphens{curiosity}

balance

Balances the columns (in a two column page) on the last page, so that they appear of equal length. Taken from the package manual:

[Balancing two column layouts] is done with the command \balance, which should be issued somewhere in the text of what would be the first column of the last page without balanced columns. If it is issued too late, i. e., in the second column, then a warning message is printed that balancing may not take place.

natbib

Another nice package, useful for advanced bibliography stuff is natbib, which supports different types of references i. e., \citep for a parenthetical citation and \citet for a textual one.

acronym

When writing scientific papers, one often has to deal with tons of acronyms. Apart from simply writing down these acronyms in running text, there are several things to keep track of, i. e., using short or long form of acronym, writing it in full form (long and short) at first occurrence, not introducing typos, changing a custom acronym etc. To ease this pain, the acronym package can be used to define acronyms and refer to those using keys which will be expanded to the actual acronym in short, long (at first occurrence) or whatever desired form. For example, I define some acronyms in the beginning of my document (after \begin{document}) like this:

\acrodef{voip}[VoIP]{Voice over IP}
\acrodef{mos}[MOS]{Mean Opinion Score}

Which can then be used in the text, e. g.:

...was not reflected in the \ac{MOS}, leading to...

You can explicitly use the short form and long form like this:

was not reflected in the \acs{MOS}, leading to

Example LaTeX file

The following listing just concatenates all packages above and adds some configuration candy to it into the well-known preamble. You could use it as a template for new latex papers, etc.

% specify your documentclass here [report|article|...]
\documentclass[a4paper,final]{article}
% \documentclass[a4paper,draft]{article}

% for nicer tables
\usepackage{booktabs}
% use package
\usepackage{graphicx}
\usepackage{microtype}
\usepackage{balance}

% version 1 of siunitx package
%\usepackage{siunitx}
%\sisetup{per=fraction,fraction=nice,alsoload=binary,obeyall}
% version 2 of siunitx package
\usepackage{siunitx}
\usepackage{xfrac}
\sisetup{per-mode=fraction,fraction-function=\sfrac,alsoload=binary,detect-all}

\usepackage{hyphenat}
\usepackage{todonotes}
\usepackage{subfigure}
\usepackage{listings}
\usepackage[ruled,vlined,linesnumbered]{algorithm2e}
\usepackage[sort&compress]{natbib}
\usepackage{acronym}

\usepackage{tikz}
\usetikzlibrary{
    calc,trees,positioning,arrows,chains,shapes.geometric,%
     decorations.pathreplacing,decorations.pathmorphing,shapes,%
    matrix,shapes.symbols}
% objectstyle1, objectstyle2, and important line are defined by personal preference
\tikzset{%
    objectstyle1/.style={rectangle,minimum size=6mm,%
    rounded corners=1mm, draw=black, very thick, text centered},%
    objectsyle2/.style={rectangle,minimum size=4mm,%
    rounded corners=1mm, draw=black, thick, text centered},%
    important line/.style={thick}%
}

% some settings for nicer tables
\renewcommand{\arraystretch}{1.2}

The main matter of the document could then continue like that:

\title{And Now for Something Completely Different}
\author{Eric Idle}

\begin{document}
\maketitle

Is your wife a...``goer''... eh? Know what I mean? Know what I mean? Nudge nudge.
Nudge nudge! Know what I mean? Say no more...Know what I mean?

\end{document}

Very small, very non-sense. To get an idea of how LaTeX works, simply copy above two sections into a text file and save it with the extension .tex into a new folder, we will also refer to as the project folder.
Read on for further detail!

Flattr: 

LatexMk

After installing the TeX distribution and having created a project folder with a .tex file in it, you can simply enter your project directory and invoke it using the following command:

latexmk [file]

If you want to use pdflatex instead, use

latexmk -pdf [file]

If you have only one tex file in the current directory, you can omit ‘[file]’ in both cases. But that’s not the end of the feature list! Use the following command to open the resulting PDF file in your system’s PDF viewer.

latexmk -pdf -pvc [file]

If you appear to be not an utterly ultimate LaTeX guru or you are using the tikzDevice with R, or similar, you might want to get rid of pdflatex’s interactive mode, which prompts on every error. Use the following command line to keep pdflatex quiet.

latexmk -pdf -pvc -silent [file]

If you appear to have Skim on Mac OS X, you might want to add the following lines to your ${HOME}/.latexmkrc (which you might need to create):

$pdf_previewer = 'osascript -e "set theFile to POSIX file \"%S\" as alias" -e "set thePath to POSIX path of theFile" -e "tell application \"Skim\"" -e "open theFile" -e "end tell"';
$pdf_update_method = 4;
$pdf_update_command = '/usr/bin/osascript -e "set theFile to POSIX file \"%S\" as alias" -e "set thePath to POSIX path of theFile" -e "tell application \"Skim\"" -e  "  set theDocs to get documents whose path is thePath" -e "  try" -e "    if (count of theDocs) > 0 then revert theDocs" -e "  end try" -e "  open theFile" -e "end tell"';
$latex = 'latex --shell-escape';
$pdflatex = 'pdflatex --shell-escape';

# added for using glossaries
add_cus_dep('glo', 'gls', 0, 'makeglo2gls');
sub makeglo2gls {
  system("makeindex -s '$_[0]'.ist -t '$_[0]'.glg -o '$_[0]'.gls '$_[0]'.glo");
}

# automatically convert R to .tex
# (needs to use tikzDevice and R file needs to have the same file base as tex file)
add_cus_dep( 'R', 'tex', 0, 'CallRscript');
sub CallRscript {
    system("cd `dirname $_[0].R` && Rscript `basename $_[0].R` `basename $_[0].tex`");
}

These lines make sure, that latexmk opens the PDF file in Skim (ignoring your system default settings) and tells Skim to reload the file every time the PDF is updated. Note that the update command may not be necessary depending on your Skim version. Besides that, the configuration adds some magic in case you are using the tikzDevice, R and glossaries.

Cheers, iss

Flattr: 

Pretty Figures with tikzDevice

The standard way to integrate graphics into LaTeX is still by using the graphicx package. If you happen to create most of your graphs with GNU/R like me, you can instead use the tikzDevice package. Note that by the time of this blog post the tikzDevice package is not available in the archive due to failing tests. Anyhow, the package is fully functional (at least as far as I can tell). Read my other blog post on how to install it anyway.

The advantage of the tikzDevice is the integration into the LaTeX document. Rather than including the figure from an PDF of EPS file, the tikzDevice renders the figure as an actual TeX file using the tikz macro package.

Therefore, all fonts will be type set by LaTeX during it’s compilation phase and thus can include formulas, special characters, or any other LaTeX package commands you are using in your document (e. g. abbreviations, siunitx, etc.). Besides that, the fonts in the figure will match the LaTeX font you use in your document (unless you specify otherwise) and thus won’t break the layout.

Furthermore, all images, lines, symbols show up amazingly pretty as they are actually plotted by LaTeX itself rather than created and pre-rendered by an external application into an PDF/EPS file.

To use the tikzDevice, you need to add a preemble to your R script. I have mine in my snippets list, so I don’t need to copy it all the time.

# load tikzDevice package
require(tikzDevice)

# configure tikz params - width and height in inches
tikzheight <- 3.2
tikzwidth <- 3.2
fntsize <- 0.8
options( tikzDocumentDeclaration = c(
  "\\documentclass[a4paper]{article}",
  "\\usepackage{amssymb,amsmath,graphicx}",
  "\\usepackage{tikz}",
  "\\usepackage{cite}",
  "\\usepackage{algorithm}",
  "\\usepackage{algorithmic}",
  "\\usepackage{siunitx}",
  "\\sisetup{per=fraction,fraction=nice,alsoload=binary}",
  "\\usepackage{fixme}",
  "\\fxsetup{draft}",
  "\\fxuselayouts{index}") )
# prepare output medium
tikz( file="figures/outfile.tex",
  width=tikzwidth,
  height=tikzheight )
par( cex=fntsize ) 

Put these lines before your actual R script and the output will be written into figures/outfile.tex - which you can change in the call to tikz(...) above.

Examples:
png version tikz version

Neat, isn’t it?
Best,
iss

Flattr: 

Finalize the Document

If you want to submit your document to a conference or workshop, you might need to make sure, that all fonts are embedded. The check for this is much easier than fixing the issue by invoking the following command which lists all used fonts:

pdffonts [yourdocument.pdf]

If all fonts have a yes in the emb column, everything is fine. Otherwise, you might need to check your graph plotting tools like Matlab, R or gnuplot. Matlab should be used with EPS export and then convert the eps file to PDF “by hand” (pstopdf). R and gnuplot do have tikz devices which you definitely should consider to use for your plots. They are not only fixing the issue of the embedded fonts, but also make the graphs look much nicer as they are plotted as native LaTeX figures.

Cheers, iss

Flattr: