99 lines
3.5 KiB
Markdown
99 lines
3.5 KiB
Markdown
|
# 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
|
|||
|
|
```
|