latex-thesis

name

latex-thesis

description

LaTeX thesis compilation & troubleshooting. Turkish + English preamble setup (memoir/report class, babel/polyglossia, fontspec); biblatex + biber config; TikZ/pgfplots example plots; float/caption discipline; cleveref cross-refs; 20 common LaTeX errors + fixes (Undefined control sequence, biber not run, Missing $, Overfull hbox, File not found for figures, babel Turkish shorthand clashes, Unicode char not set up, etc.). Execute: bash scripts/latex_build.sh for digested error log. Use when setting up LaTeX thesis, fixing compile errors, or troubleshooting figures/bibliography/Turkish characters.

Gate: latex_build.sh writes into build//exports/, which .claude/hooks/phase_gate.py enforces at the tool-call layer per CLAUDE.md Invariant 3 — verify-status.json must be PASS and the latest reviews/round-N.md must show Major issues: 0, or the hook denies the call regardless of what this skill says. Run /verify-citations and /critique (looping through /revise until Major=0) before building.

1. Preamble Setup (TR + EN Bilingual)

Minimal working example (Turkish thesis):

\documentclass[12pt,oneside,a4paper]{memoir}

% Language + encoding
\usepackage[utf8]{inputenc}
\usepackage[turkish,english]{babel}  % OR: \usepackage{polyglossia} if XeLaTeX
\usepackage[margin=2.5cm]{geometry}

% Fonts (pdfLaTeX: use babel+inputenc; XeLaTeX/LuaLaTeX: use fontspec)
% For pdfLaTeX with Turkish:
\usepackage{lmodern}  % Latin Modern (better support than default)

% Bibliography (biblatex + biber MANDATORY for Turkish hyphenation/sorting)
\usepackage[
  backend=biber,
  style=apa,           % or ieee, chicago, etc.
  language=auto,       % Auto-switch language per entry
  sorting=nyt,         % Name-year-title
  maxbibnames=999
]{biblatex}
\addbibresource{bib/references.bib}

% Cross-references (cleveref; load AFTER babel/polyglossia)
\usepackage{cleveref}
\crefname{figure}{Figure}{Figures}
\crefname{table}{Table}{Tables}
\Crefname{figure}{Figure}{Figures}
\Crefname{table}{Table}{Tables}

% Graphics + plots
\usepackage{graphicx}
\usepackage{tikz}
\usepackage{pgfplots}
\pgfplotsset{compat=1.18}

% Captions (control figure/table numbering and spacing)
\usepackage[hang,small]{caption}
\captionsetup{
  labelsep=period,      % "Figure 1. Caption text"
  skip=6pt              % Space between figure and caption
}

% Other common
\usepackage{amsmath,amssymb}
\usepackage{booktabs}        % Professional tables
\usepackage{hyperref}        % Clickable TOC, cross-refs

\hypersetup{
  colorlinks=false,          % Black links (not colored)
  pdfborder={0 0 0}
}

\title{Your Thesis Title}
\author{Student Name}
\date{\today}

\begin{document}

\maketitle

% Preliminaries (Özet, Abstract, TOC, etc.)
\frontmatter
\selectlanguage{turkish}
\include{chapters/0_ozet}
\selectlanguage{english}
\include{chapters/0_abstract}
\tableofcontents
\listoffigures
\listoftables

% Main content
\mainmatter
\include{chapters/1_introduction}
\include{chapters/2_literature}
\include{chapters/3_methodology}
\include{chapters/4_results}
\include{chapters/5_discussion}

% Bibliography
\backmatter
\printbibliography

\end{document}

Key settings:

• backend=biber (NOT bibtex) for Turkish support and modern BibTeX features.
• language=auto in biblatex: auto-switches entry language (Turkish entries render with Turkish hyphenation).
• babel + lmodern for pdfLaTeX; fontspec + polyglossia for XeLaTeX/LuaLaTeX.

---

2. Bibliography Setup (biblatex + biber)

Project structure:

thesis/
  bib/
    references.bib         # Master BibTeX file (NEVER edit manually)
  build/
    main.pdf              # Compiled output
  main.tex              # Preamble + structure
  scripts/
    latex_build.sh        # Execute: bash scripts/latex_build.sh main.tex build

references.bib example (machine-generated by doi2bib.py):

@article{Smith2020learning,
  author = {Smith, Jane and Jones, Bob},
  title = {Learning Representations from Raw Data},
  journal = {Journal of Machine Learning},
  year = {2020},
  volume = {45},
  pages = {123--145},
  doi = {10.1234/example},
  language = {english}
}

@article{Kaya2023türkçe,
  author = {Kaya, Ahmet and Yıldız, Elif},
  title = {Türkçe Doğal Dil İşlemesi},
  journal = {Bilgisayar Mühendisliği Dergisi},
  year = {2023},
  volume = {12},
  pages = {45--67},
  language = {turkish}
}

In-text citations:

\cite{Smith2020learning}        % Parenthetical citation: (Smith 2020)
\parencite{Kaya2023türkçe}      % Same as \cite
\textcite{Smith2020learning}    % Narrative: Smith (2020)
\fullcite{Smith2020learning}    % Full entry inline (rare)

---

3. Figures, Tables & Captions

Figure best practices:

\begin{figure}[htbp]  % h=here, t=top, b=bottom, p=float page
  \centering
  \includegraphics[width=0.8\textwidth]{figures/my_plot.pdf}
  \caption{Short title describing the figure. Details can follow in legend.}
  \label{fig:my_plot}
\end{figure}

Reference: \cref{fig:my_plot} shows that...

Rules:

• Always use \label{} AFTER \caption{}.
• Always use \cref{} for references (auto-inserts "Figure" / "Table").
• Captions should be self-contained (reader understands without reading text).
• For multi-part figures: \subcaption{(a) First part} using subcaption package.

Table best practices:

\begin{table}[htbp]
  \centering
  \caption{Method × Metric comparison.}
  \label{tab:results}
  \begin{tabular}{lcc}
    \toprule
    Method & Accuracy & F1 \\
    \midrule
    Baseline & 0.85 & 0.82 \\
    Ours & \textbf{0.92} & \textbf{0.91} \\
    \bottomrule
  \end{tabular}
\end{table}

Rules:

• Use booktabs rules (\toprule, \midrule, \bottomrule) — never vertical lines.
• Caption goes ABOVE table (unlike figures, which go BELOW).
• Use \textbf{} to highlight best results.

---

4. TikZ & pgfplots Starter Examples

Simple bar chart:

\begin{tikzpicture}
\begin{axis}[
  xlabel=Method,
  ylabel=Accuracy (\%),
  xtick={1,2,3},
  xticklabels={Baseline, SOTA, Ours},
  ymax=100,
  bar width=0.6cm,
  width=8cm,
  height=5cm
]
\addplot[fill=gray] coordinates {(1,80) (2,90) (3,95)};
\end{axis}
\end{tikzpicture}

Line plot with error bars:

\begin{tikzpicture}
\begin{axis}[
  xlabel=Epoch,
  ylabel=Loss,
  legend pos=upper right,
  width=10cm,
  height=6cm
]
\addplot[
  color=blue,
  error bars/.cd,
  y dir=both,
  y explicit
] coordinates {
  (1, 2.5) +- (0.2, 0.2)
  (5, 1.2) +- (0.1, 0.1)
  (10, 0.8) +- (0.05, 0.05)
};
\addlegend{Training}
\end{axis}
\end{tikzpicture}

Tip: Use pgfplots for publication-grade plots (consistent fonts, tight spacing). For quick sketches, tikz alone suffices.

---

5. 20 Common LaTeX Errors + Fixes

Error	Symptom	Cause	Fix
Undefined control sequence	! Undefined control sequence. l.XX \mycommand	Typo in macro name or package not loaded	Check spelling; add \usepackage{pkg}
Missing $ inserted	! Missing $ inserted. l.XX x^2 is	Math mode not entered (forgot $ or $...$)	Wrap in $...$ or \[...\]
Biber not run	Empty bibliography; warning: empty bibliography	.bbl file missing or out of date	Run: biber main (or use script)
Overfull hbox	Black box in margin	Line too long for margin width	Adjust \textwidth or reword; use \sloppy sparingly
File not found	! LaTeX Error: File 'figures/x.pdf' not found	Wrong path or file doesn't exist	Use correct relative path; verify file exists
Babel Turkish shorthand clash	Hyphenation broken; text runs together	Turkish shorthands (e.g., "e) interfere	Use \shorthandoff{"} in preamble or switch to \selectlanguage{english}
Unicode char not set up	Package inputenc Error: Unicode char ... not set up	fontspec missing or wrong encoding	Use \usepackage[utf8]{inputenc} (pdfLaTeX) or fontspec (XeLaTeX)
Citation key undefined	Citation 'mykey2020' undefined	Key in .tex not in .bib	Add entry to references.bib or correct key spelling
Double spacing	Text has extra line breaks	\usepackage{doublespace} loaded

---

6. Building & Debugging

Execute (don't read):

bash scripts/latex_build.sh main.tex build

This runs: pdflatex → biber → pdflatex → pdflatex (standard pipeline) and returns only the last 10 meaningful error/warning lines (full compile log ignored in context to save tokens).

Manual build (if script unavailable):

pdflatex -interaction=nonstopmode main.tex
biber main
pdflatex -interaction=nonstopmode main.tex
pdflatex -interaction=nonstopmode main.tex

Troubleshooting workflow:

1. Check .log file for full error context: tail -50 main.log | grep -i "error\|undefined\|missing"
2. Search error code (e.g., "Undefined control sequence l.234") in this guide's Table (Section 5).
3. Apply fix, re-run bash scripts/latex_build.sh main.tex build.

---

7. Best Practices Checklist

• Use utf8 encoding + lmodern font (pdfLaTeX) or fontspec (XeLaTeX).
• babel/polyglossia BEFORE cleveref.
• biber backend (NOT bibtex).
• EVERY figure/table has \label{} and is referenced via \cref{}.
• Captions are self-contained (sentence fragments acceptable).
• No [h!] or [t] in production; let floats flow naturally.
• Turkish shorthands ("e, etc.) disabled or used consciously.
• No hardcoded colors; use \textbf{} or \textit{}.
• File names: ASCII only (no Turkish chars, spaces, or special symbols).
• Margins match institution guideline (check templates/institution/GUIDELINE-NOTES.md).

---

References

• Compile & troubleshoot: Execute bash scripts/latex_build.sh main.tex build (digested errors only).
• Turkish thesis setup: thesis-structure skill, reference/yok-tr.md.
• Biblatex doc: CTAN biblatex/doc/biblatex.pdf.
• TikZ manual: CTAN pgf/doc/pgfmanual.pdf (comprehensive, searchable).