Files

T

laoyang 6819d78f29 工作流全部迁到 WSL：新增 WORKFLOW.md，build.sh 改为 WSL 原生 #21

用户要求「全部在 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（重写）

2026-10-29 21:50:34 +08:00

3.5 KiB

Raw Blame History

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 查当前名字。

日常命令

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 里）。

编辑文件

两种方式都行：

在 WSL 里用 vim/nano（推荐，路径最直接）
从 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 会认为文件变了。提交前统一还原：

git checkout -- '*.pdf'

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

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

环境重建

万一 WSL 环境坏了：

# 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

3.5 KiB Raw Blame History Unescape Escape