# WSL 工作流

本仓库的所有工作都在 **WSL** 内完成。Windows 侧不保留工作副本。

## 为什么

- 隔离：LaTeX 编译会产生大量中间文件（`.aux` / `.log` / `.toc`），
  不用清理 Windows 目录。
- 可重置：环境坏了删掉重建即可，不影响 Windows 系统。
- 一套工具链：TeX Live 2025 + Python venv + git + 工单工具，全在一个地方。

## 目录位置

| 用途 | 路径 |
|---|---|
| 仓库 | `~/code/ouc_latex_template`（WSL 内） |
| 从 Windows 浏览 | `\\wsl$\Ubuntu-26.04\home\yongquan\code\ouc_latex_template` |
| Python venv | `~/.venv-latex`（装了 pymupdf / fonttools） |
| 工单工具 | `~/.local/bin/gi.py` |
| Gitea 配置 | `~/.config/ouc-latex/gitea.json` |
| 环境变量 | `~/.config/ouc-latex/env.sh`（已在 `.bashrc` 里 source） |

⚠️ 发行版名是 **Ubuntu-26.04**。若将来重装 WSL 改名了，
UNC 路径里的这一段要跟着换。用 `wsl -l -v` 查当前名字。

## 日常命令

```bash
ouccd                          # 进仓库（别名）
bash build.sh 试卷 试卷题型示例   # 编译单个（自动两遍，打印 error/Overfull/页数）
bash build.sh all              # 全库编译（13 个模板）
git status && git add -A && git commit -m "... #N"
git push origin main
gi context                     # 查在途工单
```

`texbuild 试卷 试卷题型示例` 是 `build.sh` 的等价别名（定义在 env.sh 里）。

## 编辑文件

两种方式都行：

1. **在 WSL 里用 vim/nano**（推荐，路径最直接）
2. **从 Windows 用任意编辑器打开 UNC 路径** —— VS Code、Typora、
   PDF 阅读器都能直接读写，因为 `\\wsl$\...` 是双向的。
   但**不要在 Windows 里跑 LaTeX 编译**，那样中间文件会落在
   Windows 的 9p 文件系统缓存里，慢且容易出权限问题。

## Windows 侧注意事项

- **不要**在 Windows 目录保留第二份仓库副本。两份会分叉，
  同步靠 scp 很容易漏。这是之前"很乱"的根源。
- 想快速看 PDF：直接双击 UNC 路径下的 PDF，或
  `explorer \\wsl$\Ubuntu-26.04\home\yongquan\code\ouc_latex_template`
- Windows 上装的 TeX Live 2022 **可以留着当兼容性抽检**，
  但不是主编译环境。真要抽检时，把源码拷到临时目录编，别在仓库里编。

## PDF 不进版本库

`*.pdf` 都在 git 里，但**编译产生的 PDF 不要提交**——
同源码编两次，页面一致但内嵌 `CreationDate` 不同，git 会认为文件变了。
提交前统一还原：

```bash
git checkout -- '*.pdf'
```

## 已知的少量排版告警（不是回归）

| 模板 | 告警 | 原因 |
|---|---|---|
| 幻灯片 | Underfull 1 | 既有问题 |
| 科技报告 | Underfull 4 | 1 既有 + 3 内容块长串（见 boxes.cls 注释） |
| 课程执行大纲 | Overfull 1 | 既有问题 |

## 环境重建

万一 WSL 环境坏了：

```bash
# 1. 装 TeX（功能全集，跳过 11 个 -doc 包，省 800MB+）
sudo apt-get install --no-install-recommends \
  texlive-xetex texlive-lang-chinese texlive-latex-extra \
  texlive-fonts-extra texlive-science texlive-pictures

# 2. Python 依赖
python3 -m venv ~/.venv-latex
~/.venv-latex/bin/pip install pymupdf fonttools

# 3. FontAwesome（Debian 的 texlive-fonts-extra 不带，需走 fontconfig）
cp ~/code/ouc_latex_template/fonts/fontawesome/FontAwesome.otf \
   ~/.local/share/fonts/ && fc-cache -f

# 4. 仓库
git clone https://code.yangyq.net/laoyang/ouc_latex_template.git ~/code/ouc_latex_template

# 5. 验证
cd ~/code/ouc_latex_template && bash build.sh all
```