Thesis
My master's thesis "Building a 25 MHz NMR spectrometer" about the hardware and software developed to acquire basic signals.
## π Table of Contents
- [π Table of Contents](#-table-of-contents)
- [π§ About ](#-about-)
- [π Getting Started ](#-getting-started-)
- [β
Prerequisites ](#-prerequisites-)
- [π οΈ Setup ](#οΈ-setup-)
- [π§ͺ Usage ](#-usage-)
- [π Note on LaTeX ](#-note-on-latex-)
- [π Acknowledgements ](#-acknowledgements-)
## π§ About
These subfolders contain my master's thesis "Building a 25 MHz NMR spectrometer" written at ETH ZΓΌrich.
The final `.pdf` version can be found next to this `README.md`: [Final Thesis](./thesis.pdf).
Everything to compile the project is located within this repository including measurement results
and pictures also found in other parts of this repository.
## π Getting Started
These instructions will get you up and running to compile a copy of the thesis on your local machine. I'll assume you're using a RedHat based ("`dnf`") GNU/Linux distribution, other distributions or operating systems might need to adapt a little.
### β
Prerequisites
To compile the project a full `texlive` installation including `xindy` is necessary for the index and `pygments` for code highlighting. In Fedora this can be simply installed by executing
```bash
$> sudo dnf install texlive-scheme-full texlive-xindy python-pygments
```
In Ubuntu you need
```bash
$> sudo apt install texlive-full xindy python-pygments
```
### π οΈ Setup
After installing the `LaTeX` environment above you'll need to checkout this repository. Either do a [partial clone](https://github.blog/2020-12-21-get-up-to-speed-with-partial-clone-and-shallow-clone/) (supported in newer git versions) or a full clone of the repository. For simplicity we will do a full clone here
```bash
$> git clone https://gitlab.ethz.ch/mstabel/nmr-spectrometer
```
Next go into this folder and execute `latexmk`. This is a program written in Perl that automatically figures out how often it needs to run `LaTeX`, `makeindex`, `biber`, `makeglossaries`, ... until the final document is stable.
```bash
$> cd docs/report
$> latexmk
```
That's it! `latexmk` should take care of everything now. If you didn't install all packages (by not installing a "full" TeX distribution above), you might encounter some errors. Try to figure out which packages are missing by searching for "error" in the `out/thesis.log`.
The final `thesis.pdf` will be in the `out` folder, maybe a little bit hidden between all the other files.
You can get rid of the intermediate files that are generated by telling `latexmk` to do a "cleanup":
```bash
$> latexmk -c
```
## π§ͺ Usage
If you want to edit the document I recommend [`Visual Studio Code`](https://code.visualstudio.com/) with the excellent [`LaTeX Workshop extension`](https://marketplace.visualstudio.com/items?itemName=James-Yu.latex-workshop). Simply open this folder directly with it and it should detect and build the project with `latexmk`.
By default the extension compiles the project on changed files. This can lead to problems when the intermediate files are generated. To only recompile when you hit "save" in the editor, add the line below to your `settings.json`:
```json
{
"latex-workshop.latex.autoBuild.run": "onSave",
}
```
To manually compile your program hit `Ctrl+Shift+P` and look for `LaTeX Workshop: Build with recipe` and then choose `latexmk`.
If you decide not to use the LaTeX Workshop plugin, make sure to occasionally run `latexindent.pl` from this folder (so it can find the `.latexindent.yaml` configuration). And if you add other (external) "custom dependencies" reading on [how to edit the `.latexmkrc` file](https://mirror.init7.net/ctan/support/latexmk/latexmk.pdf) might be worth it. The little known [official `.latexmkrc` examples](https://www.ctan.org/tex-archive/support/latexmk/example_rcfiles) are *very* helpful as well (or even more so).
## π Note on LaTeX
If you're unfamiliar with LaTeX I warmly recommend reading up on the basics a little before delving into the code. LaTeX is quite old and a lot of results from Google can be confusing, way more complicated than they need be or plain wrong (i.e. they cause problems elsewhere). Nowadays a lot of the stuff is simpler to achieve than it used to be. A *very* good place to delve into LaTeX is [Tobias Oetiker's "The Not So Short Introduction to LaTeX"](https://tobi.oetiker.ch/lshort/lshort.pdf) which can be read front to back or just used as a reference (as I still do).
This is document is written with [`kaobook`](https://github.com/fmarotta/kaobook) which itself is based on the excellent [KOMA-Script](https://komascript.de/~mkohm/scrguien.pdf) ([or in German](https://komascript.de/~mkohm/scrguide.pdf)). KOMA-Script is the base class for almost all templates I have worked with (the rare exception is the [`memoir` class](https://mirror.init7.net/ctan/macros/latex/contrib/memoir/memman.pdf)). Knowing just a few base concepts of that class (e.g. titlepage, backmatter, frontmatter, colophon, abstract, ...) help immensely with customizing almost any LaTeX template.
Because of its age, a lot of stuff you find on LaTeX on e.g. stackoverflow (or from ChatGPT) is way outdated and needs to be used with caution. My usual approach now is - as antique as it sounds - figuring out which package a command comes from or I need (usually with ChatGPT) and then reading the "Userguide" `pdf` on [CTAN](https://ctan.org/) (which is the place *all* packages and classes are located).
## π Acknowledgements
The thesis is based on the beautiful [`kaobook`](https://github.com/fmarotta/kaobook) template augmented with parts from the excellent
and modern [`latex-cookbook`](https://github.com/alexpovel/latex-cookbook). It has been written in a way that it should compile on [`Overleaf`](https://www.overleaf.com/) without issues as well. External programs called are
- `latexmk`
- `makeglossaries`
- `makeindex`
- `biber`
- `xindy`
- `pygments`
which are (with the exception of the last two) part of a standard full `texlive` installation.