Initial commit

2026-06-06 05:21:10 +00:00
commit 6664758a6d
493 changed files with 135653 additions and 0 deletions
--- a/skills/ppt/references/latex.md
+++ b/skills/ppt/references/latex.md
@@ -0,0 +1,342 @@
+# 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.**
+
+```bash
+# 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
+
+```latex
+\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**:
+```latex
+\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
+```latex
+\tableofcontents   % Entries are auto-linked courtesy of hyperref
+\listoffigures
+\listoftables
+```
+
+#### 6.2 Internal Cross-References
+
+**Attach labels** right after each numbered element:
+```latex
+\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):
+```latex
+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)**:
+```latex
+\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**:
+```latex
+\usepackage[numbers]{natbib}
+\bibliographystyle{plainnat}
+
+\cite{smith2023}   % [1]
+\citep{smith2023}  % (Smith, 2023)
+\citet{smith2023}  % Smith (2023)
+```
+
+**biblatex pathway**:
+```latex
+\usepackage[backend=biber,style=numeric-comp]{biblatex}
+\addbibresource{refs.bib}
+
+Per~\cite{smith2023}...
+\printbibliography
+```
+
+#### 6.4 External Links
+```latex
+\url{https://example.com}
+\href{https://example.com}{Visible label}
+\href{mailto:a@b.com}{a@b.com}
+```
+
+#### 6.5 PDF Metadata & Outline
+```latex
+\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:
+```bash
+# 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:
+
+```latex
+\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 |