abzhaw/latex-builder

LaTeX Builder

Handles all aspects of local LaTeX compilation on the Mac Mini. Manages the build pipeline, resolves errors, configures packages, and produces the final PDF. No cloud services -- everything runs locally.

Compilation Pipeline

Primary Method: latexmk

The recommended approach for building the thesis. Handles all intermediate steps automatically.

cd thesis/latex
latexmk -pdf -interaction=nonstopmode main.tex

Flags:

• -pdf: Produce PDF output (via pdflatex)
• -interaction=nonstopmode: Do not stop on errors (log them and continue)
• Add -silent to suppress most console output during clean builds
• Add -f to force compilation even after errors (useful for debugging)

Manual Compilation Sequence

When latexmk is unavailable or for debugging specific steps:

cd thesis/latex
pdflatex -interaction=nonstopmode main.tex    # First pass: generate .aux files
biber main                                      # Process bibliography
pdflatex -interaction=nonstopmode main.tex    # Second pass: resolve citations
pdflatex -interaction=nonstopmode main.tex    # Third pass: resolve cross-references

Important: This project uses biber (not bibtex) because BibLaTeX is the bibliography backend. Running bibtex instead of biber will produce errors about missing .bbl files or garbled citations.

Continuous Compilation (Live Preview)

For active writing sessions where you want the PDF to update on every save:

cd thesis/latex
latexmk -pdf -pvc main.tex

The -pvc flag enables "preview continuously" mode. latexmk watches for file changes and recompiles automatically. Pair with a PDF viewer that supports auto-reload (e.g., Skim on macOS, configured with latexmk -pvc -view=none if using a separate viewer).

Clean Build

Remove all auxiliary files and rebuild from scratch. Useful when the build state is corrupted.

cd thesis/latex
latexmk -C                    # Remove all generated files including PDF
latexmk -pdf main.tex         # Full rebuild

Or manually:

cd thesis/latex
rm -f *.aux *.bbl *.bcf *.blg *.fdb_latexmk *.fls *.log *.out *.run.xml *.toc *.lof *.lot *.synctex.gz
pdflatex main.tex && biber main && pdflatex main.tex && pdflatex main.tex

Prerequisites

Full Installation (Recommended)

brew install --cask mactex

This installs the complete TeX Live distribution (~4 GB). Includes all packages, all fonts, and all tools. No need to install additional packages manually.

After installation, ensure the PATH includes the TeX binaries:

eval "$(/usr/libexec/path_helper)"
# Or add to ~/.zshrc:
export PATH="/Library/TeX/texbin:$PATH"

Minimal Installation (Alternative)

brew install --cask basictex

BasicTeX is much smaller (~100 MB) but requires manual installation of additional packages. After installing BasicTeX:

# Update package manager
sudo tlmgr update --self

# Install required packages for this thesis
sudo tlmgr install \
    babel-german \
    biblatex \
    biber \
    csquotes \
    microtype \
    tikz \
    pgfplots \
    minted \
    listings \
    xcolor \
    hyperref \
    cleveref \
    geometry \
    fancyhdr \
    setspace \
    titlesec \
    tocloft \
    appendix \
    booktabs \
    caption \
    subcaption \
    float \
    enumitem \
    parskip \
    glossaries \
    acronym \
    todonotes \
    latexmk

Verify Installation

# Check all tools are available
pdflatex --version
biber --version
latexmk --version

# Check a specific package is installed
kpsewhich biblatex.sty
kpsewhich tikz.sty

German-Specific Package Setup

The thesis is written in German. The following packages and configurations are essential.

Core German Language Support

% In preamble of main.tex:

% Encoding and fonts
\usepackage[T1]{fontenc}           % Proper output encoding for umlauts
\usepackage[utf8]{inputenc}        % UTF-8 input (default in modern LaTeX but explicit is safer)
\usepackage{lmodern}               % Latin Modern font (clean, scalable)

% German language
\usepackage[ngerman]{babel}        % New German hyphenation and localization
                                   % Changes "Chapter" to "Kapitel",
                                   % "Table of Contents" to "Inhaltsverzeichnis", etc.

% German quotation marks
\usepackage[autostyle=true]{csquotes}
% Usage: \enquote{Text} produces German-style quotation marks
% Nested: \enquote{Aussen \enquote{Innen} Aussen}

% Typography refinement
\usepackage{microtype}             % Better character protrusion and font expansion
                                   % Makes text look significantly more professional

BibLaTeX Configuration

% Bibliography with BibLaTeX (NOT bibtex)
\usepackage[
    backend=biber,          % Use biber as backend processor
    style=alphabetic,       % Citation style: [Doe23] -- common in German CS theses
    sorting=nyt,            % Sort by name, year, title
    maxbibnames=99,         % Show all authors in bibliography
    maxcitenames=2,         % Show max 2 authors in citations, then "et al."
    giveninits=true,        % Abbreviate first names in bibliography
    uniquename=init,        % Disambiguate by initials
    url=true,               % Show URLs in bibliography
    doi=true,               % Show DOIs
    isbn=false,             % Hide ISBNs (usually not needed)
    eprint=false            % Hide eprint info
]{biblatex}

\addbibresource{bibliography/references.bib}

% At end of document (before \end{document}):
\printbibliography[heading=bibintoc, title={Literaturverzeichnis}]

Alternative citation styles common in German theses:

• style=alphabetic -- [Doe23] -- most common in German CS
• style=numeric -- [1] -- compact but less informative
• style=authoryear -- (Doe, 2023) -- common in social sciences

Thesis Template Setup

Page Layout

\usepackage[
    a4paper,
    left=3cm,               % Extra space on left for binding
    right=2.5cm,
    top=2.5cm,
    bottom=2.5cm,
    bindingoffset=0.5cm     % Additional binding offset
]{geometry}

Line Spacing

\usepackage{setspace}
\onehalfspacing             % 1.5 line spacing (standard for German theses)
% Use \singlespacing in code listings and captions if needed

Headers and Footers

\usepackage{fancyhdr}
\pagestyle{fancy}
\fancyhf{}                          % Clear all headers/footers
\fancyhead[L]{\leftmark}            % Chapter name on the left
\fancyhead[R]{\thepage}             % Page number on the right
\renewcommand{\headrulewidth}{0.4pt}
\renewcommand{\footrulewidth}{0pt}

% Plain style for chapter opening pages
\fancypagestyle{plain}{
    \fancyhf{}
    \fancyfoot[C]{\thepage}
    \renewcommand{\headrulewidth}{0pt}
}

Code Listings

Option A: minted (requires Python's Pygments, better syntax highlighting)

\usepackage{minted}
\setminted{
    fontsize=\footnotesize,
    linenos=true,
    frame=single,
    framesep=2mm,
    breaklines=true,
    tabsize=2
}

% Usage:
% \begin{minted}{typescript}
% const julia = new Orchestrator();
% \end{minted}

% Note: Requires compilation with -shell-escape flag:
% pdflatex -shell-escape main.tex
% latexmk -pdf -shell-escape main.tex

Option B: listings (no external dependencies, simpler)

\usepackage{listings}
\lstset{
    basicstyle=\ttfamily\footnotesize,
    numbers=left,
    numberstyle=\tiny,
    frame=single,
    breaklines=true,
    tabsize=2,
    captionpos=b,
    showstringspaces=false,
    keywordstyle=\color{blue},
    commentstyle=\color{green!60!black},
    stringstyle=\color{red!70!black}
}

% Usage:
% \begin{lstlisting}[language=Java, caption={Orchestrator-Initialisierung}]
% const julia = new Orchestrator();
% \end{lstlisting}

Chapter and Section Formatting

\usepackage{titlesec}

% Optional: customize chapter heading appearance
\titleformat{\chapter}[display]
    {\normalfont\huge\bfseries}    % Format
    {\chaptertitlename\ \thechapter}  % Label
    {20pt}                          % Separation between label and title
    {\Huge}                         % Before-code for title text

Error Handling

Reading the Log File

After a failed compilation, parse main.log for errors:

# Find all errors in the log
grep -n "^!" thesis/latex/main.log

# Find undefined references
grep "undefined" thesis/latex/main.log

# Find missing files
grep "File .* not found" thesis/latex/main.log

# Find missing packages
grep "LaTeX Error: File .* not found" thesis/latex/main.log

Common Errors and Fixes

Missing package:

! LaTeX Error: File `csquotes.sty' not found.

Fix: sudo tlmgr install csquotes

Undefined control sequence (typo in command):

! Undefined control sequence.
l.42 \beginn{document}

Fix: Check for typos. \beginn should be \begin.

Undefined reference:

LaTeX Warning: Reference `sec:architektur' on page 12 undefined.

Fix: Check that \label{sec:architektur} exists somewhere. May need another compilation pass.

Missing bibliography entry:

Package biblatex Warning: Citation 'doe2023' undefined.

Fix: Ensure the key exists in bibliography/references.bib and run biber main.

Encoding issues with umlauts:

! Package inputenc Error: Unicode character ae (U+00E4) not set up for use with LaTeX.

Fix: Ensure \usepackage[utf8]{inputenc} and \usepackage[T1]{fontenc} are in the preamble.

Overfull hbox (text exceeding margins):

Overfull \hbox (15.2pt too wide) in paragraph at lines 120--125

Fix: Rephrase the text, add \allowbreak, or use \sloppy locally. For URLs, use \url{} with the url package. For code, ensure breaklines=true in listings.

Biber cannot find .bcf file:

INFO - This is Biber ...
ERROR - Cannot find control file 'main.bcf'!

Fix: Run pdflatex main.tex first to generate the .bcf file, then run biber main.

Validation Checks

Run these checks before considering a build "successful":

1. All Graphics Files Exist

# Extract all \includegraphics references and check they exist
grep -oP '\\includegraphics(\[.*?\])?\{(.*?)\}' thesis/latex/main.tex thesis/latex/chapters/*.tex | \
    grep -oP '\{(.*?)\}' | tr -d '{}' | while read f; do
    if [ ! -f "thesis/latex/$f" ] && [ ! -f "thesis/latex/$f.pdf" ] && [ ! -f "thesis/latex/$f.png" ]; then
        echo "MISSING: $f"
    fi
done

2. All Citation Keys Exist

# Extract all \cite{} keys and check against references.bib
grep -oP '\\cite\{(.*?)\}' thesis/latex/chapters/*.tex | grep -oP '\{(.*?)\}' | tr -d '{}' | \
    tr ',' '\n' | sort -u | while read key; do
    if ! grep -q "@.*{${key}," thesis/latex/bibliography/references.bib; then
        echo "MISSING CITATION: $key"
    fi
done

3. No Orphan References

# Check for undefined references in the log
grep -c "undefined" thesis/latex/main.log
# Should be 0 after a clean build

4. No Critical Warnings

# Check for overfull boxes exceeding tolerance
grep "Overfull.*hbox" thesis/latex/main.log | grep -v "badness"

# Check for missing characters
grep "Missing character" thesis/latex/main.log

5. TODO Markers

# Find remaining TODO markers in tex files
grep -rn "TODO" thesis/latex/chapters/ thesis/latex/main.tex
# These should be resolved before final submission

Word Count

Use texcount to get word counts per chapter:

# Overall word count
texcount thesis/latex/main.tex -inc -total

# Per-file breakdown
texcount thesis/latex/chapters/*.tex -inc

# Detailed count (headers, captions, etc. separated)
texcount thesis/latex/main.tex -inc -v

If texcount is not installed:

sudo tlmgr install texcount
# or
brew install texcount

Project File Structure

Expected directory layout for the thesis:

thesis/latex/
    main.tex                          # Root document
    bibliography/
        references.bib                # BibLaTeX bibliography database
    chapters/
        01-einleitung.tex             # Einleitung
        02-verwandte-arbeiten.tex     # Verwandte Arbeiten
        03-grundlagen.tex             # Grundlagen
        04-konzept.tex                # Konzept und Entwurf
        05-implementierung.tex        # Implementierung
        06-evaluation.tex             # Evaluation
        07-fazit.tex                  # Fazit und Ausblick
    figures/
        fig-04-systemarchitektur.tex  # TikZ figures
        fig-05-nachrichtenfluss.tex
        ...
    frontmatter/
        titlepage.tex                 # Titelseite
        abstract.tex                  # Zusammenfassung / Abstract
        declaration.tex               # Eidesstattliche Erklaerung
        acknowledgments.tex           # Danksagung (optional)
    appendix/
        appendix-a.tex                # Anhang

main.tex Structure

\documentclass[12pt, a4paper, twoside, openright]{report}

% Packages (as detailed above)
...

\begin{document}

% Front matter (Roman page numbers)
\frontmatter
\input{frontmatter/titlepage}
\input{frontmatter/declaration}
\input{frontmatter/abstract}
\tableofcontents
\listoffigures
\listoftables

% Main content (Arabic page numbers)
\mainmatter
\input{chapters/01-einleitung}
\input{chapters/02-verwandte-arbeiten}
\input{chapters/03-grundlagen}
\input{chapters/04-konzept}
\input{chapters/05-implementierung}
\input{chapters/06-evaluation}
\input{chapters/07-fazit}

% Bibliography
\printbibliography[heading=bibintoc, title={Literaturverzeichnis}]

% Appendix
\appendix
\input{appendix/appendix-a}

\end{document}

Build Automation

latexmkrc Configuration

Create a .latexmkrc file in the thesis/latex directory for project-specific build settings:

# thesis/latex/.latexmkrc
$pdf_mode = 1;                    # Generate PDF via pdflatex
$bibtex_use = 2;                  # Use biber (detected automatically by latexmk)
$pdflatex = 'pdflatex -interaction=nonstopmode -shell-escape %O %S';
$clean_ext = 'bbl bcf run.xml synctex.gz';  # Additional files to clean

With this file in place, simply running latexmk in the thesis/latex directory will do the right thing.

Troubleshooting Checklist

When the build fails:

1. Read the first error in main.log (later errors are often cascading)
2. Check if it is a missing package (install via tlmgr)
3. Check if it is a syntax error (typo in a command)
4. Check if it is a missing file (figure, bibliography, input)
5. Try a clean build (latexmk -C && latexmk -pdf)
6. Check that biber (not bibtex) is being used
7. Verify the compilation flag -shell-escape if using minted
8. Check that all \input{} paths are correct relative to main.tex