# Writing a Thesis in LaTeX on Mac OS X

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 conﬁgurations here, to share it both with you and my future self. My conﬁguration is build on the usage of diﬀerent building blocks. Most of which should be exchangeable with the modules of your choice, especially regarding the editor.

The conﬁguration 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 conﬁguration work ﬁrst 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 ﬁnd the following pages useful and would be happy if you drop some comments!
iss

# 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 ﬁts best or where I have the right tools at hand.

For my statistics stuﬀ 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 workﬂow 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 ﬁle 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 ﬁle).

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!

# 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 scientiﬁc 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 diﬀerence - 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 deﬁnes 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 ﬁx/remove them. To add a todo statement, use something like \todo{Find better wording here}.

## subﬁgure

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

\begin{figure}%
\centering
\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 ﬁgures 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}{
\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 diﬀerent 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 ﬁrst 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 stuﬀ is natbib, which supports diﬀerent types of references i. e., \citep for a parenthetical citation and \citet for a textual one. ## acronym When writing scientiﬁc 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 ﬁrst occurrence, not introducing typos, changing a custom acronym etc. To ease this pain, the acronym package can be used to deﬁne acronyms and refer to those using keys which will be expanded to the actual acronym in short, long (at ﬁrst occurrence) or whatever desired form. For example, I deﬁne 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 ﬁle The following listing just concatenates all packages above and adds some conﬁguration 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 ﬁle 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! # LatexMk After installing the TeX distribution and having created a project folder with a .tex ﬁle in it, you can simply enter your project directory and invoke it using the following command: latexmk [file]  If you want to use pdﬂatex instead, use latexmk -pdf [file]  If you have only one tex ﬁle in the current directory, you can omit ‘[ﬁle]’ in both cases. But that’s not the end of the feature list! Use the following command to open the resulting PDF ﬁle 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 pdﬂatex’s interactive mode, which prompts on every error. Use the following command line to keep pdﬂatex 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 ﬁle in Skim (ignoring your system default settings) and tells Skim to reload the ﬁle every time the PDF is updated. Note that the update command may not be necessary depending on your Skim version. Besides that, the conﬁguration adds some magic in case you are using the tikzDevice, R and glossaries.

Cheers, iss

# 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 ﬁgure from an PDF of EPS ﬁle, the tikzDevice renders the ﬁgure as an actual TeX ﬁle 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 ﬁgure 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 ﬁle.

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}",
"\\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:

Neat, isn’t it?
Best,
iss

# 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 ﬁxing 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 ﬁne. 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 ﬁle to PDF “by hand” (pstopdf). R and gnuplot do have tikz devices which you deﬁnitely should consider to use for your plots. They are not only ﬁxing the issue of the embedded fonts, but also make the graphs look much nicer as they are plotted as native LaTeX ﬁgures.

Cheers, iss