mantle-ai-trader/skills/ppt/references/latex.md

Route 3: Academic & Scientific PDF via LaTeX

Produce publication-grade PDFs from .tex source files compiled with Tectonic. Suited for academic papers, theses, mathematical manuscripts, IEEE/ACM-format submissions, and any document where the user explicitly requests LaTeX.

Guiding principle: when someone asks for "a LaTeX PDF," they expect a polished, professional result — not a bare-minimum compilation.

---

Environment Preparation

The binary of Tectonic lands at scripts/tectonic.

Compilation — Always Use the Wrapper Script

All compilations must go through scripts/pdf.py convert.latex. It handles:

• Stripping noisy package-download logs
• Filtering progress chatter
• Surfacing genuine errors and warnings
• Reporting PDF statistics (file size, page count, word estimate, image tally)

Do not invoke Tectonic directly.

# One-pass build
python3 scripts/pdf.py convert.latex main.tex

# Two passes (resolves cross-references)
python3 scripts/pdf.py convert.latex main.tex --runs 2

# Verbose mode (retains full log output)
python3 scripts/pdf.py convert.latex main.tex --keep-logs

---

Pre-Writing Planning

Before touching .tex code, determine the document's category and let that shape your approach.

Recognising the Document Type

Type	Typical outputs	Key concern
Scholarly	Journal articles, conference proceedings, regulatory specs	Rigorous adherence to academic conventions; bibliography accuracy
Utilitarian	Technical reports, reference manuals, product specs	Pack maximum information while preserving scannability
Persuasive	Funding proposals, pitch documents, project roadmaps	Clean professionalism throughout, with one or two visual high-points (title page, KPI dashboards)
Expressive	Design portfolios, brand guidebooks, showcases	Bold typographic and chromatic choices; deliberate rule-breaking that amplifies impact

Fallback Aesthetic (No Style Specified)

When the user gives no visual direction, apply a measured, high-craft system:

1. Contrast — clear figure-ground separation; headings visually distinct from running text
2. Hierarchy — establish reading order through deliberate variation in size, weight, and hue
3. White space — ample margins and leading to let the page breathe
4. Coherence — one typeface family, one accent colour, one spacing rhythm

Enrichment Elements (Add Proactively When Appropriate)

• Decorative: shaded callout boxes, sidebars, comparison panels → tcolorbox
• Scholarly: theorem / definition / proof environments → amsthm + tcolorbox; process diagrams → TikZ
• Page furniture: running headers and footers → fancyhdr; chapter openers → titlesec

Introduce these components on your own initiative whenever the content benefits — don't wait to be told.

---

Mandatory Rules

Rule 1 — Every Build Diagnostic Demands Attention

The wrapper classifies compiler output into three tiers:

Tier	Impact	Required response
Errors	Build aborts	Resolve before anything else
Layout defects	Overfull / underfull boxes, unavailable font shapes, missing glyphs	Repair prior to delivery
Advisories	Remaining warnings	Assess individually; fix whenever feasible

Never acceptable: shrugging off warnings with "they don't affect the final PDF." Every diagnostic merits investigation.

Rule 2 — Modular Files for Larger Works

A single generation turn can comfortably handle roughly 500 lines of TeX.

When to split:

• Anticipated output exceeds 5 pages, or
• Three or more heavyweight elements are present (wide tables, block equations, TikZ graphics)

Stitch modules together with \input{chapter1}, \input{chapter2}, etc.

Rule 3 — Foundation Preamble

\documentclass{article}

% Essentials
\usepackage{graphicx}
\usepackage{xcolor}
\usepackage{geometry}
\usepackage{amsmath}          % Load before hyperref

% hyperref — ALWAYS last among content packages
\usepackage[
    colorlinks=true,
    linkcolor=blue,
    citecolor=darkgray,
    urlcolor=blue,
    bookmarks=true,
    bookmarksnumbered=true,
    unicode=true
]{hyperref}

% Page dimensions
\geometry{a4paper, top=2.5cm, bottom=2.5cm, left=3cm, right=2.5cm}
% CV variant: \geometry{a4paper, margin=1.5cm}

% Superscript citation numbers (scholarly convention)
\usepackage[numbers,super,sort&compress]{natbib}
\bibliographystyle{unsrtnat}

% Commonly needed extras
\usepackage{tcolorbox}
\usepackage{colortbl}
\usepackage{booktabs}
\usepackage{enumitem}

hyperref positioning: it must load after virtually every other package to avoid option clashes.

Rule 4 — TeX Source Hygiene

Prohibited patterns:

• Emoji glyphs (no native LaTeX engine supports them)
• Markdown *asterisk* formatting (generates compile-time errors)

Use instead:

\textbf{bold text}
\emph{emphasised text}

These are frequent model-generation slips — catch them proactively.

Rule 5 — Multi-Language & Font Handling

• babel and polyglossia are incompatible — load only one
• When using polyglossia, ensure amsmath appears earlier in the preamble
• Tectonic downloads standard LaTeX typefaces automatically (Latin Modern, etc.)
• To reference system-installed fonts via \setmainfont{}, first probe with fc-list :lang=ar
• Broadly available choices: DejaVu, Noto typeface families

Rule 6 — Clickable Navigation Is Non-Negotiable

Interactive navigation is a baseline professional expectation.

6.1 Table of Contents

\tableofcontents   % Entries are auto-linked courtesy of hyperref
\listoffigures
\listoftables

6.2 Internal Cross-References

Attach labels right after each numbered element:

\section{Background}\label{sec:bg}

\begin{figure}[htbp]
    \includegraphics{...}
    \caption{Overview diagram}\label{fig:overview}
\end{figure}

\begin{table}[htbp]
    \caption{Benchmark results}\label{tab:bench}
    ...
\end{table}

\begin{equation}\label{eq:energy}
    E = mc^2
\end{equation}

Cite these labels (each produces a live hyperlink):

As noted in Section~\ref{sec:bg}...
Figure~\ref{fig:overview} illustrates...
Table~\ref{tab:bench} summarises...
Equation~\eqref{eq:energy} yields...   % \eqref auto-wraps in parentheses
See page~\pageref{sec:bg}...

Good habits:

• Place a non-breaking space ~ before \ref to avoid orphaned line breaks
• Prefer \eqref{} for equations (auto-wraps the number in parentheses)
• Adopt a consistent label-prefix convention: sec:, fig:, tab:, eq:, lst:

6.3 Bibliography

Superscript numerals (preferred academic style):

\usepackage[numbers,super,sort&compress]{natbib}
\bibliographystyle{unsrtnat}

Prior work\cite{smith2023} shows...     % → shows^[1]
Several studies\cite{a,b,c} agree...    % → agree^[1–3]

\bibliography{refs}

Numeric bracket alternative:

\usepackage[numbers]{natbib}
\bibliographystyle{plainnat}

\cite{smith2023}   % [1]
\citep{smith2023}  % (Smith, 2023)
\citet{smith2023}  % Smith (2023)

biblatex pathway:

\usepackage[backend=biber,style=numeric-comp]{biblatex}
\addbibresource{refs.bib}

Per~\cite{smith2023}...
\printbibliography

6.4 External Links

\url{https://example.com}
\href{https://example.com}{Visible label}
\href{mailto:a@b.com}{a@b.com}

6.5 PDF Metadata & Outline

\hypersetup{
    pdftitle={Document Title},
    pdfauthor={Author Name},
    pdfsubject={Topic},
    pdfkeywords={keyword1, keyword2}
}

Bookmark trees are auto-generated from \section / \chapter hierarchy.

6.6 Why Multiple Passes Matter

Label resolution requires at least two compilation passes:

# Resolve section / figure / table labels
python3 scripts/pdf.py convert.latex main.tex --runs 2

# Also resolves bibliography back-references
python3 scripts/pdf.py convert.latex main.tex --runs 3

If ?? placeholders persist after two passes, verify that every \label string has an exact \ref match.

6.7 Navigation Troubleshooting

Observation	Root cause	Resolution
?? in place of numbers	Only a single pass was run	Recompile with --runs 2
All links render in black	hyperref colour options omitted	Enable colorlinks=true
TOC items are not clickable	hyperref package missing	Load the package
[?] beside citations	.bib path incorrect or biber step skipped	Confirm path; rebuild
Bookmark pane empty	bookmarks option set to false	Switch to bookmarks=true

---

Package Catalogue

Foundational

• hyperref (Rule 3)
• geometry (Rule 3)
• listings — \lstset{basicstyle=\ttfamily\small, numbers=left, backgroundcolor=\color{gray!5}}
• enumitem — \setlist[itemize]{itemsep=0.3em, leftmargin=1.5em}

Tabular

booktabs · longtable · multirow · array · colortbl

Visual & Charting

tikz · pgfplots · float · wrapfig · subfig / subcaption

International & Typography

fontspec (XeLaTeX / LuaLaTeX) · ctex

Mathematical

amsmath · amssymb · amsthm · natbib · biblatex · siunitx

Algorithmic & Domain-Specific

algorithm + algpseudocode · chemfig

Page Design

tcolorbox · fancyhdr · titlesec · tocloft · multicol · setspace · microtype · parskip · adjustbox · marginnote

Code Listings

listings · minted (depends on Pygments)

---

Scripts & Backends

Script	Purpose
pdf.py convert.latex	Tectonic wrapper — log sanitisation, error highlighting, PDF metrics

Engine	Notes
Tectonic	Stand-alone LaTeX engine; packages are fetched transparently on demand

---

Operational Notes

CJK Without Manual Font Setup

Tectonic resolves CJK font bundles on the fly — zero manual installation:

\usepackage{ctex}   % Tectonic pulls the font files automatically

Cold-Start Latency

The very first compilation of a new document triggers package downloads:

• Initial build: 1–5 min (depends on network speed)
• Repeat builds with warm cache: 10–30 s

Working Without Internet

Previously fetched packages are stored under ~/.cache/Tectonic/. When offline, only cached packages are available; attempting to use a new one will fail.

Tectonic vs a Full TeX Live Installation

Dimension	Tectonic	Traditional pdflatex
Package acquisition	On-demand, transparent	Manual via tlmgr
Multi-pass compilation	Handled by the engine	Explicit re-invocations required
Reference resolution	Automatic	Requires bibtex/biber cycles
Disk footprint	Single binary	Full TeX Live ≈ 4 GB