latex-toolkit

LaTeX problems fall into two kinds: a build that fails (read the log, fix the first error, rebuild) and a document that builds wrong (question marks, misplaced floats, broken references). Both are diagnosed from the .log, never by guessing at the source.

Project layout

thesis/
  main.tex            \documentclass, packages, \input of chapters
  preamble.tex        packages and macros, nothing else
  chapters/01-introduction.tex ...
  figures/            vector PDFs or high-dpi PNGs, one per figure
  tables/             generated .tex tables (from scripts, never hand-typed numbers)
  references.bib      the bibliography (bibtex-manager owns it)
  latexmkrc           build settings
  .gitignore          *.aux *.bbl *.blg *.log *.out *.toc *.lof *.lot *.fls *.fdb_latexmk *.synctex.gz

One file per chapter, \input{chapters/01-introduction} from main.tex. \includeonly{chapters/04-results} speeds up iteration on one chapter.

Build

Use latexmk; it runs pdflatex/biber/pdflatex the right number of times:

latexmk -pdf -interaction=nonstopmode -file-line-error main.tex
latexmk -pdf -pvc main.tex      # rebuild on save
latexmk -C                       # clean everything

latexmkrc:

$pdf_mode = 1;
$bibtex_use = 2;            # run biber/bibtex when needed
$pdflatex = 'pdflatex -interaction=nonstopmode -file-line-error -synctex=1 %O %S';

Prefer pdflatex unless the template needs xelatex/lualatex (system fonts, Arabic or CJK text); then $pdf_mode = 5 (xelatex) or 4 (lualatex).

Bibliography

biblatex with biber is the modern default and handles Unicode, DOIs, and URLs cleanly:

\usepackage[backend=biber,style=ieee,sorting=none]{biblatex}   % or style=apa, authoryear
\addbibresource{references.bib}
...
\printbibliography

natbib (\citep, \citet, \bibliographystyle{plainnat}, \bibliography{references}) when the template requires it. Never mix the two. Question marks for citations mean biber/bibtex has not run or the key is missing: run the full latexmk build, then check main.blg for "I didn't find a database entry for".

Reading the log

Always fix the first error; later ones are usually consequences. Search the .log for ! at line start, or use -file-line-error so errors read ./chapters/03-method.tex:42: Undefined control sequence.

When the log is huge, filter: grep -n -A3 '^!' main.log | head -40.

Packages worth loading

geometry (margins per template), graphicx, booktabs (tables that look printed), siunitx (numbers and units, aligned decimals), subcaption, cleveref (\cref{} writes "Figure 3" for you; load last), hyperref (load before cleveref, after everything else), microtype, csquotes (with biblatex), listings or minted (code; minted needs -shell-escape and Pygments), algorithm2e or algpseudocode, todonotes (drafting only), glossaries or acronym (acronyms defined once).

Templates

Department templates come as a .cls or a .sty plus an example. Keep the template unmodified in the repo, put customisations in preamble.tex, and check what the class already loads (grep RequirePackage thesis.cls) before loading packages again. If the template hard-codes bibtex, use natbib; do not fight it a week before submission.

Figures and tables

• Figures as PDF (vector) from matplotlib (savefig('x.pdf')) or SVG converted with inkscape --export-type=pdf; PNG at 300 dpi only for raster content.
• Width in text units: \includegraphics[width=0.8\linewidth]{figures/x.pdf}.
• Tables generated by scripts into tables/*.tex and \input; booktabs rules (\toprule, \midrule, \bottomrule), no vertical lines, units in headers, siunitx S columns for numbers.
• Captions below tables and figures alike unless the template differs; \label after \caption.

Word count and progress

texcount -inc -total main.tex counts words excluding markup; thesis-progress uses it.

Overleaf

Overleaf projects sync with git (git clone https://git.overleaf.com/<id>). Keep the same layout; Overleaf runs latexmk with the main file set in the menu. Keep references.bib as the source of truth in git and let Overleaf read it; do not let two people edit the .bib in the browser.

Attribution

The error table draws on awesome-latex-skills (MIT); the layout and build conventions are this repository's.