latex-to-typst

# LaTeX to Typst 迁移指南 本技能指导 AI 将 MathRepo 中的 LaTeX 笔记（使用 elegantbook 文档类）迁移为 Typst 格式。 迁移参考模板：`1.Analyse/Analyse Complexe/initial.typ`（唯一完整迁移的复分析笔记）。 ## 1. 迁移工作流 ``` Step 1: 读取 LaTeX 源文件（initial.tex + chapters/chapNN.tex） ↓ Step 2: 创建 Typst 骨架（initial.typ） ↓ Step 3: 对每个 chapter 文件运行迁移脚本（预处理） ↓ Step 4: AI 手动处理脚本无法覆盖的结构转换 ↓ Step 5: 合并所有章节到 initial.typ（单文件模式） ↓ Step 6: 编译验证（typst compile） ↓ Step 7: 修复编译错误 ``` ### Step 1: 读取源文件 - 读取 `initial.tex` 了解整体结构（`\part`、`\input` 列表、附录、参考文献） - 逐个读取 `chapters/chapNN.tex`，了解每章内容 ### Step 2: 创建 Typst 骨架 ```typst #import "../../TypstTemplate/math-notes.typ": * #set document( title: "笔记标题", author: "Violet", date: datetime.today(), ) #show: apply-style #make-cover( "笔记标题", "Violet", subtitle: "...", institute: "Notiz Mathematiques", date: datetime.today().display(), version: "v0.1.0", extra-info: "...", ) #make-outline(depth: 2, title: "Contents") // 如有自定义多字母运算符，在文件顶部定义： // #let Arg = math.op("Arg") // #let Ln = math.op("Ln") // === 正文 === #part("Part I Title") // ... 各章内容 ... #bibliography("references.bib") ``` ### Step 3: 运行迁移脚本 ```bash # 完整转换（预览模式，不写入文件） bun .agents/skills/latex-to-typst/scripts/migrate.js chapters/chap01.tex /tmp/chap01_draft.typ --dry-run # 完整转换（写入文件） bun .agents/skills/latex-to-typst/scripts/migrate.js chapters/chap01.tex /tmp/chap01_draft.typ # 仅转换结构（标题、环境、列表、图片、标签），跳过符号替换 bun .agents/skills/latex-to-typst/scripts/migrate.js chapters/chap01.tex /tmp/chap01_draft.typ --env-only # 跳过符号替换（当符号需要手动调整时） bun .agents/skills/latex-to-typst/scripts/migrate.js chapters/chap01.tex /tmp/chap01_draft.typ --no-symbols ``` ### Step 4: AI 手动处理 脚本无法完美处理的内容，需要 AI 手动调整： 1. **嵌套环境**：`description` 环境内嵌套 `enumerate` 等复杂嵌套 2. **复杂表格**：`tabular` 环境需要手动转为 `#tex-table(...)` 3. **多行公式对齐**：`align*` 中的 `&` 对齐符号需要删除，改用 Typst 的 `align` 环境 4. **交叉引用语义**：检查 `@label` 引用是否正确 5. **中文注释**：在标题后添加 `// 中文翻译` 注释 6. **自定义运算符**：如 `\mathrm{Arg}` 等需要在文件顶部用 `#let` 定义 7. **分数简化**：脚本生成的 `(\1) / (\2)` 可能需要在简单情况下去掉括号 8. **绝对值**：检查 `|...|` 是否需要改为 `abs(...)` ### Step 5: 合并到单文件 将所有 chapter 内容按顺序合并到 `initial.typ`，删除 `\input{}` 命令。 ### Step 6: 编译验证 ```bash typst compile "Subject/initial.typ" "Subject/initial.pdf" --root . ``` ### Step 7: 修复错误 常见编译错误及修复： - `unknown variable: X` → 检查 Typst 符号名（参考 typst-writing-conventions 技能） - `unexpected token` → 检查数学模式语法 - `missing argument: body` → 检查组件标签位置（标签必须在 `]` 之后） --- ## 2. 组件映射表 ### 2.1 文档结构 | LaTeX | Typst | 说明 | |-------|-------|------| | `\part{X}` | `#part("X")` | 大模块分组 | | `\chapter{X}` | `= X` | 一级标题 | | `\section{X}` | `== X` | 二级标题 | | `\subsection{X}` | `=== X` | 三级标题 | | `\subsubsection{X}` | `==== X` | 四级标题 | | `\paragraph{X}` | `*X*` | 段落标题 | | `\begin{leftbarTitle}{X}...\end{leftbarTitle}` | `=== X` | **小标题，不是组件** | | `\input{chapters/chapNN.tex}` | 直接合并内容 | 单文件模式 | | `\frontmatter / \mainmatter / \appendix` | 不需要 | Typst 自动处理 | ### 2.2 定理类环境 → Typst 组件 | LaTeX 环境 | Typst 组件 | 颜色 | |-----------|-----------|------| | `\begin{theorem}[Name]...\end{theorem}` | `#theorem(name: "Name")[...]` | 红 ♥ | | `\begin{corollary}[Name]...\end{corollary}` | `#corollary(name: "Name")[...]` | 红 ♥ | | `\begin{lemma}[Name]...\end{lemma}` | `#lemma(name: "Name")[...]` | 红 ♥ | | `\begin{definition}{Name}...\end{definition}` | `#definition(name: "Name")[...]` | 绿 ♣ | | `\begin{property}{Name}...\end{property}` | `#property(name: "Name")[...]` | 绿 ♣ | | `\begin{proposition}[Name]...\end{proposition}` | `#proposition(name: "Name")[...]` | 蓝 ♠ | | `\begin{example}[Name]...\end{example}` | `#example(name: "Name")[...]` | 蓝 ♠ | | `\begin{axiom}[Name]...\end{axiom}` | `#axiom(name: "Name")[...]` | 紫 ♦ | | `\begin{postulate}[Name]...\end{postulate}` | `#postulate(name: "Name")[...]` | 紫 ♦ | | `\begin{exercise}[Name]...\end{exercise}` | `#exercise(name: "Name")[...]` | 蓝 ♠ | | `\begin{remark}...\end{remark}` | `#note[...]` | 注释 | | `\begin{note}...\end{note}` | `#note[...]` | 注释 | | `\begin{caution}...\end{caution}` | `#caution[...]` | 警告 | **名称参数格式**： - elegantbook 用 `{Name}` 或 `[Name]` 传参 → Typst 统一用 `name: "Name"` - 无名称时省略 `name:` 参数：`#theorem[...]` ### 2.3 证明/解答环境 | LaTeX | Typst | |-------|-------| | `\begin{proof}...\end{proof}` | `#proof[...]` | | `\begin{solution}...\end{solution}` | `#solution[...]` | - 删除证明末尾的 `\qed` 或 `\qedsymbol`（`#proof` 自动添加 ■） ### 2.4 列表环境 | LaTeX | Typst | |-------|-------| | `\begin{enumerate}\item X\end{enumerate}` | `1. X` | | `\begin{itemize}\item X\end{itemize}` | `- X` | | `\begin{description}\item[Title] Content\end{description}` | `1. *Title.* Content` | - `description` 环境通常出现在 `definition` 内部，转为编号列表 + 粗体标签 ### 2.5 数学环境 | LaTeX | Typst | |-------|-------| | `\[ ... \]` | `$ ... $`（display math） | | `\( ... \)` | `$...$`（inline math） | | `\begin{equation} ... \end{equation}` | `$ ... $` | | `\begin{align*} ... \end{align*}` | `$ ... $`（删除 `\\` 和 `&`） | | `\begin{gather*} ... \end{gather*}` | 多个 `$ ... $`（按 `\\` 拆分） | | `\begin{align} ... \end{align}` | `$ ... $`（删除 `\\` 和 `&`） | **注意**：`align*` 中的 `\\`（换行）和 `&`（对齐）在 Typst 中需要特殊处理： - 简单情况：拆分为多个 display math - 需要对齐：使用 Typst 的 `align` 函数 ### 2.6 图片环境 ```latex % LaTeX \begin{figure}[h] \centering \includegraphics[width=0.25\textwidth]{img/example.png} \caption{Example figure.} \label{fig:example} \end{figure} ``` ```typst // Typst #figure( image("img/example.png", width: 25%), caption: [Example figure.], placement: auto, supplement: [Fig.], ) <fig:example> ``` ### 2.7 标签与引用 | LaTeX | Typst | |-------|-------| | `\label{fig:example}` | `<fig:example>` | | `\label{thm:name}` | `<thm:name>` | | `\label{def:name}` | `<def:name>` | | `\ref{fig:example}` | `@fig:example` | | `\ref{thm:name}` | `@thm:name` | | `\eqref{name}` | `@eq:name` | **重要**：模板组件（`#theorem`、`#definition` 等）内部的标签不能用 `@` 引用， 必须用 `#link(<label>)[显示文本]`。 ### 2.8 字体命令 | LaTeX（文本模式） | Typst | |------------------|-------| | `\textbf{X}` | `*X*` | | `\textit{X}` | `_X_` | | `\emph{X}` | `_X_` | | `\textrm{X}` | `rm("X")` | | `\text{X}`（数学模式中） | `text("X")` | | LaTeX（数学模式） | Typst | |------------------|-------| | `\mathbb{R}` | `bb(R)` | | `\mathcal{F}` | `cal(F)` | | `\mathscr{M}` | `scr(M)` | | `\mathfrak{g}` | `frak(g)` |