laoyang
6819d78f29
用户要求「全部在 wsl 完成」，原因是 Windows 上工作太多太乱， WSL 像虚拟环境、坏了能重置、不影响系统。 ## 之前为什么乱 分工是「Windows 改代码 + 两端都编」：Windows 侧一份仓库副本装满了 .aux/.log/.toc/.pdf，WSL 侧另一份，靠 scp/git pull 同步维持。 同一项目两份工作副本，漏同步就分叉。 ## 实测确认的技术前提 1. **UNC 路径双向读写** —— `\\wsl$\Ubuntu-26.04\home\yongquan\...` Read/Write/Edit 三个工具都能直接作用于该路径，读写均落到 WSL 磁盘。 延迟 6~63ms。⇒ 不需要「本地编辑 → scp」这套中间环节。 ⚠️ 发行版名是 Ubuntu-26.04，不是常见的 Ubuntu 或 Ubuntu-22.04。 2. **WSL 内 TeX 可完整编译全库** —— `bash build.sh all` 13/13 通过。 3. **WSL 内 git 可推送** —— credential.helper=store 已指向含 token 的 ~/.git-credentials，fetch 实测通过。 4. **gi.py 可迁** —— 纯标准库，无第三方依赖，复制即用。 5. **Python 依赖** —— 建 ~/.venv-latex，装 pymupdf 2.0 + fonttools 4.68.0， 不污染系统 Python。 ## 本 commit 的改动 ### 新增 WORKFLOW.md 写清：为什么在 WSL、目录位置（含 UNC 路径）、日常命令、编辑方式、 PDF 不进版本库的原因、已知排版告警清单、环境重建步骤。 ### build.sh 重写为 WSL 原生 原版是「Windows 通过 ssh 远程调 WSL 编译再 scp 取回」，在 WSL 内跑没意义。 新版改动： - 去掉全部 ssh/scp，直接本地编译 - 两遍编译（目录/页码/LastPage 跨引用第二遍才稳定） - 自动 cd 到模板目录（.sty 的 ../fonts/ 相对编译目录解析） - 目录→主文件映射保留：幻灯片/slides、科技报告/report、 试卷有两个主文件必须显式指定、简历不能拿 ls 第一个 .tex - `all` 转给 verify_all.sh（那边有完整 TARGETS 清单） - 新增 SILENT=1 输出紧凑表格，便于脚本消费 - 单目录模式找不到时列出可选目录/主文件，不用去翻源码 ### WSL 侧环境（不入库，属个人配置） - ~/.config/ouc-latex/env.sh 固定 OUC_PY / GI / WB_GITEA_CONFIG / OUC_REPO， 提供 gi / ouccd / texbuild 别名 - ~/.bashrc 末尾 source - ~/.local/bin/gi.py + ~/.config/ouc-latex/gitea.json（chmod 600） ## 验证 WSL 内全库编译： 总数 13 | 通过 13 | 失败 0 逐项：劳务发放说明表 1 / 年度考核登记表 2 / 幻灯片 30(UF1) / 成绩构成说明 1 / 特殊事项说明表 1 / 科技报告 10(UF4) / 简历 3 / 试卷题型示例 6 / 参考答案 3 / 试卷归档封面 1 / 试卷归档目录 1 / 课程执行大纲 5(OF1) / 课程教学日历 2 页数与 Windows 侧历史记录逐个一致。3 处告警均为既有问题，非回归。 WSL 内工单工具：`gi whoami` → token 有效、仓库识别为 ouc_latex_template。 本工单 #21 即由 WSL 内的 gi 创建，工具链已实证可用。 ## Windows 侧 备份 D:\Yongquan\backup\ouc_latex_template-win-backup-20261029.tar.gz （49MB / 244 项 / 不含 .git）。删除前确认两端 HEAD 同为 fb7c76b、 无未推送提交、无 stash。备份保留，不删。 涉及文件：WORKFLOW.md（新增）、build.sh（重写）
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
|
||
``` |