# User Guide
## Installation
```bash
git clone https://github.com/yingkitw/latex-rs
cd rtex
cargo build --release
```
Binary: `target/release/rtex`
## Quick Start
```bash
# Default: PDF in output/input.pdf
rtex examples/minimal.tex
# Custom output path
rtex examples/math.tex -o my_math.pdf
# Other formats
rtex examples/minimal.tex --format html
rtex examples/sample.tex --format docx -o report.docx
rtex examples/sample.tex --format epub
```
## CLI Reference
| `-o, --output PATH` | Output file path |
| `-f, --format FORMAT` | `pdf` (default), `html`, `docx`, `epub` |
| `--fetch-packages` | Download missing `.sty`/`.cls` from CTAN |
| `--package-cache DIR` | Package cache directory (default: `.rtex/cache`) |
| `--keep-intermediate` | Write `.expanded.tex`, `.ast.json`, `.meta.json` |
| `--watch` | Recompile on file changes (all formats) |
| `--force` | Force rebuild despite incremental cache |
| `--no-incremental` | Disable incremental compilation |
### Examples
```bash
# Watch mode
rtex thesis.tex --watch
# Fetch packages then convert
rtex paper.tex --fetch-packages
# Debug parse tree
rtex doc.tex --keep-intermediate
# → output/doc.pdf, output/doc.ast.json, output/doc.expanded.tex
```
## Library API
```rust
use rtex::{convert_tex_file, convert_tex_string, ConversionOptions, OutputFormat};
// File conversion
let options = ConversionOptions::default()
.with_format(OutputFormat::Html)
.with_keep_intermediate(true);
convert_tex_file("doc.tex".as_ref(), "doc.html".as_ref(), &options)?;
// In-memory (WASM-friendly)
let pdf = rtex::convert_tex_string_to_pdf_bytes(r"\documentclass{article}...")?;
let html = rtex::convert_tex_string(tex, OutputFormat::Html)?;
```
## Supported LaTeX
### Document structure
```latex
\documentclass{article}
\title{My Document}
\author{Jane Doe}
\date{\today}
\begin{document}
\maketitle
\tableofcontents
\section{Introduction}
Content here.
\appendix
\section{Extra}
\end{document}
```
### Text formatting
`\textbf`, `\textit`, `\texttt`, `\underline`, `\emph`, `\textsc`, `\textcolor{color}{text}`, `\colorbox`, `\fcolorbox`
### Math (618+ symbols)
Inline: `$E = mc^2$` — Display: `\begin{equation}...\end{equation}`
Supported: fractions, roots, matrices, Greek letters, operators, `\mathbb`, `\mathcal`, `\mathfrak`, accents (`\vec`, `\hat`, `\bar`, …).
### Lists, tables, figures
- `itemize`, `enumerate` (with optional `\item[label]`)
- `tabular` with `l/c/r` columns and booktabs rules
- `\includegraphics` for PNG, JPEG, and SVG
### References and bibliography
```latex
\label{sec:intro}
See Section~\ref{sec:intro} on page~\pageref{sec:intro}.
\cite{smith2020}
\begin{thebibliography}{9}
\bibitem{smith2020} Smith, J. (2020). Example.
\end{thebibliography}
```
BibTeX `.bib` file parsing is available via the library (`BibliographyManager`).
### Macros
```latex
\newcommand{\kw}[1]{\textbf{#1}}
\def\laplace#1{\mathcal{L}\{#1\}}
```
### Environments
`center`, `quote`, `quotation`, `abstract`, `equation`, `lstlisting`, `table`+`tabular`
## WebAssembly
```bash
rustup target add wasm32-unknown-unknown
cargo build --target wasm32-unknown-unknown --features wasm --release
wasm-bindgen target/wasm32-unknown-unknown/release/rtex.wasm --out-dir pkg --target web
```
JavaScript export: `convertTexToPdf(texSource)` → `Uint8Array` PDF bytes.
## Examples
| `examples/minimal.tex` | Smallest valid document |
| `examples/math.tex` | Equations and symbols |
| `examples/table.tex` | Tabular + booktabs |
| `examples/lists.tex` | Itemize/enumerate |
| `examples/code.tex` | lstlisting |
| `examples/sample.tex` | Combined features |
```bash
cargo test --lib example_tests -- --nocapture # generate example PDFs
./generate_examples.sh # batch script
```
## Troubleshooting
| `Invalid file path` | Check input `.tex` exists and is readable |
| Empty PDF | Ensure `\begin{document}` / `\end{document}` present |
| Missing image | Use paths relative to `.tex` file; check PNG/JPEG/SVG |
| Unknown command | Command may be unsupported; try `--keep-intermediate` to inspect AST |
| Package not found | Run with `--fetch-packages` or install manually into cache |
## Limitations
See [KNOWN_LIMITATIONS.md](KNOWN_LIMITATIONS.md) for the full list. Summary:
- Not a full LaTeX engine — no TikZ, beamer, or arbitrary package execution
- DOCX/EPUB/HTML are functional first versions, not pixel-perfect LaTeX replicas
- PDF file size ~750 bytes for ASCII-only docs; ~385 KB when Unicode/math requires embedded font
- Package fetching uses CTAN mirror heuristics; exotic layouts may fail
For production documents requiring 100% LaTeX compatibility, use Tectonic or TeX Live.