diff --git a/WORKFLOW.md b/WORKFLOW.md new file mode 100644 index 0000000..a03341f --- /dev/null +++ b/WORKFLOW.md @@ -0,0 +1,99 @@ +# 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 +``` \ No newline at end of file diff --git a/build.sh b/build.sh index 8c10f66..da55b66 100755 --- a/build.sh +++ b/build.sh @@ -1,104 +1,129 @@ #!/usr/bin/env bash -# 在 WSL 内编译模板，并把生成的 PDF 取回 Windows 侧 +# 在 WSL 内编译模板（WSL 原生版，无需 ssh/scp） # -# 适用场景：开发环境在 WSL 里，编译也在 WSL 里做，只把 PDF 拿回 Windows 看。 -# 不追求跨平台通用，是给「Windows + WSL2 + ssh 连入」这套配置用的。 +# 这套仓库的全部工作都在 WSL 内完成：编辑、编译、查看、提交、提工单。 +# Windows 侧只通过 \\wsl$\<发行版>\... 这个 UNC 路径读取文件（只读浏览）。 # # 用法： -# bash build.sh 特殊事项说明表 # 编译该目录下默认主文件 -# bash build.sh 试卷 试卷题型说明.tex # 显式指定主文件 -# bash build.sh all # 全库所有主文件，逐个编译并取回 +# bash build.sh 特殊事项说明表 # 编译该目录下默认主文件 +# bash build.sh 试卷 试卷题型示例 # 显式指定主文件（不带 .tex 也行） +# bash build.sh all # 全库所有主文件，逐个编译 +# bash build.sh all 2>&1 | tee /tmp/v.log # 想留完整日志 # -# 可用环境变量覆盖（都有默认值）： -# WSL_HOST 默认 yongquan@127.0.0.1 -# WSL_KEY 默认 $HOME/.ssh/wsl_local -# WSL_ROOT WSL 内仓库路径，默认 /home/yongquan/code/ouc_latex_template -# WIN_ROOT Windows 侧仓库路径，默认脚本所在目录 -# TEXBIN WSL 内的 latex 命令，默认 xelatex +# 可用环境变量： +# TEXBIN 默认 xelatex +# SILENT 非空时只打印结论行（给批量脚本用） # -# ⚠️ 两点务必注意 +# ⚠️ 三条务必注意 # -# 1) 不要让本脚本的后台运行。WSL2 会按「空闲」把整个虚拟机回收（poweroff）， -# 一旦回收，正在编译的 xelatex 连同 systemd 的 PID 1 一起消失，日志也随 -# /tmp 清空。本脚本的 ssh 会话在编译期间不断开，正好起到保活作用。 -# 若确实需要长时间无人值守编译，得先在 Windows 侧 .wslconfig 里设 -# vmIdleTimeout=-1 并 wsl --shutdown 一次让它生效，不能只改文件。 +# 1) **PDF 不要提交**。同源码编两次，页面一致但内嵌 CreationDate 不同， +# git 会认为文件变了（全库 13 个 PDF 全变 M）。提交前： +# git checkout -- '*.pdf' +# 或者用 git status 确认只 add 了源码。 # -# 2) 取回的 PDF 不要提交。同源码编译两次，页面内容一致但内嵌 CreationDate -# 不同，git 会认为文件变了（全库 12 个 PDF 全会变成 M）。提交前用 -# git checkout -- '*.pdf' 还原。 +# 2) **每个模板都要在它自己的目录里编**。.sty 里的 Path=../fonts/ 是相对 +# 编译时工作目录解析的，从仓库根调用会找不到字体，报一堆 +# "The font ... cannot be found"。本脚本已自动 cd，不用手动。 +# +# 3) **两遍编译**。目录、页码、LastPage 跨引用要第二遍才稳定。 +# 只编一遍会看到「第 ? 页」或者目录页码错位。 set -u -WSL_HOST="${WSL_HOST:-yongquan@127.0.0.1}" -WSL_KEY="${WSL_KEY:-$HOME/.ssh/wsl_local}" -WSL_ROOT="${WSL_ROOT:-/home/yongquan/code/ouc_latex_template}" -WIN_ROOT="${WIN_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)}" +ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" TEXBIN="${TEXBIN:-xelatex}" -SSH="ssh -i $WSL_KEY -o StrictHostKeyChecking=no $WSL_HOST" +SILENT="${SILENT:-}" die() { echo "$1" >&2; exit 2; } +# 目录 → 主文件。目录名与主文件名不一致的必须在这里登记。 +# 简历/ 下有 fontawesomesymbols-*.tex 等宏包片段，不能拿 ls 第一个 .tex 当主文件。 +mainfile_of() { + case "$1" in + 幻灯片) echo "slides" ;; + 科技报告) echo "report" ;; + 简历) echo "简历" ;; + 试卷) echo "" ;; # 有两个主文件，必须显式指定 + *) echo "$1" ;; + esac +} + +# 编一个：$1=目录 $2=主文件名（不带 .tex） +build_one() { + local dir="$1" name="$2" + local log="/tmp/oucbuild.$$.log" + local log1="/tmp/oucbuild.$$.1.log" + + # 第一遍：产出 .aux/.toc，允许非致命错误（TOC 还没生成时会警告） + ( cd "$ROOT/$dir" && $TEXBIN -interaction=nonstopmode "$name.tex" ) > "$log1" 2>&1 + local rc1=$? + # 第二遍：交叉引用稳定后的最终结果，统计以这一遍为准 + ( cd "$ROOT/$dir" && $TEXBIN -interaction=nonstopmode "$name.tex" ) > "$log" 2>&1 + local rc2=$? + + local err over under pages + err=$(grep -c '^!' "$log" 2>/dev/null || :) + over=$(grep -c 'Overfull' "$log" 2>/dev/null || :) + under=$(grep -c 'Underfull' "$log" 2>/dev/null || :) + pages=$(grep -o 'Output written on .*' "$log" 2>/dev/null | tail -1) + + if [ -z "$SILENT" ]; then + echo "=== $dir / $name ===" + echo " error : $err" + echo " Overfull : $over" + echo " Underfull : $under" + echo " ${pages:-（无输出，见 $log）}" + else + printf '%-24s err=%-2s over=%-2s under=%-2s %s\n' \ + "$dir" "$err" "$over" "$under" "$(echo "$pages" | sed 's/Output written on .*(\([0-9]*\) page.*/\1页/')" + fi + + if [ "$rc2" -ne 0 ]; then + echo "--- 错误片段（$log）---" >&2 + grep -A6 '^!' "$log" 2>/dev/null | head -20 | sed 's/^/ /' >&2 + # 保留失败日志，方便排查；成功时删掉 + return "$rc2" + fi + rm -f "$log" "$log1" + return 0 +} + [ $# -eq 0 ] && die "用法: bash build.sh <目录名|all> [主文件名]" + DIR="$1"; TEX="${2:-}" -# 全库：先跑批量验证，再逐个取回 +#---------------------------------------------------------------------- +# 全库模式：直接转给 verify_all.sh（那边有完整的 TARGETS 清单） +#---------------------------------------------------------------------- if [ "$DIR" = "all" ]; then - $SSH "bash '$WSL_ROOT/../verify_all.sh'" - rc=$? - echo - echo "--- 取回全部 PDF ---" - while IFS= read -r rel; do - [ -z "$rel" ] && continue - if scp -i "$WSL_KEY" -q "$WSL_HOST:$WSL_ROOT/$rel" "$WIN_ROOT/$rel" 2>/dev/null; then - echo " $rel" - else - echo " $rel (取回失败)" >&2 - fi - done < <($SSH "cd '$WSL_ROOT' && find . -name '*.pdf' -not -path './.git/*' | sed 's|^\./||'") - exit $rc + exec bash "$ROOT/verify_all.sh" +fi + +#---------------------------------------------------------------------- +# 单目录模式 +#---------------------------------------------------------------------- +if [ ! -d "$ROOT/$DIR" ]; then + echo "没有这个目录：$DIR" >&2 + echo "可选：" >&2 + ( cd "$ROOT" && ls -d */ 2>/dev/null | sed 's|/$||' | sed 's/^/ /' ) >&2 + exit 2 fi -# 单目录：目录名与主文件名不一致的，在这里登记 if [ -z "$TEX" ]; then - case "$DIR" in - 幻灯片) TEX="slides.tex" ;; - 科技报告) TEX="report.tex" ;; - 试卷) die "试卷/ 有两个主文件，请显式指定：试卷题型示例.tex 或 参考答案与评分标准示例.tex" ;; - *) TEX="$DIR.tex" ;; - esac + TEX="$(mainfile_of "$DIR")" + if [ -z "$TEX" ]; then + echo "$DIR/ 有多个主文件，请显式指定：" >&2 + ( cd "$ROOT/$DIR" && ls *.tex 2>/dev/null | grep -v fontawesome | sed 's/\.tex$//' | sed 's/^/ /' ) >&2 + echo "例: bash build.sh $DIR $(cd "$ROOT/$DIR" && ls *.tex 2>/dev/null | grep -v fontawesome | head -1 | sed 's/\.tex$//')" >&2 + exit 2 + fi fi -echo "=== WSL 编译: $DIR/$TEX ===" -# 编译输出先落到临时文件，失败时才好把 ! 开头的行捞出来给人看。 -# 用当前目录下的隐藏文件名，不用 mktemp —— mktemp 在 Windows 的 Git Bash -# 里返回 /tmp/... 形式，与其后的 rm 组合会触发安全检查（safe-delete）， -# 属于无害噪音但会干扰输出。 -TMPLOG="./.build_out.$$" -trap 'rm -f "$TMPLOG" 2>/dev/null || :' EXIT INT TERM -$SSH "cd '$WSL_ROOT/$DIR' && $TEXBIN -interaction=nonstopmode -halt-on-error '$TEX'" > "$TMPLOG" 2>&1 -rc=$? +# 允许用户写带 .tex 的 +TEX="${TEX%.tex}" -LOG="${TEX%.tex}.log" -echo "=== 结论 ===" -# 页码那一行原样输出（含 "pages." 结尾），不要用正则截断 —— -# 截了会把括号吃掉，看起来像 "1 page" 少个字符。 -$SSH "cd '$WSL_ROOT/$DIR' && \ - printf 'error: %s\n' \"\$(grep -c '^!' '$LOG' 2>/dev/null || :)\"; \ - printf 'Overfull: %s\n' \"\$(grep -c 'Overfull' '$LOG' 2>/dev/null || :)\"; \ - printf 'Underfull: %s\n' \"\$(grep -c 'Underfull' '$LOG' 2>/dev/null || :)\"; \ - grep 'Output written on' '$LOG' 2>/dev/null | tail -1" - -if [ "$rc" -ne 0 ]; then - echo "编译失败，日志片段：" >&2 - grep -A6 "^!" "$TMPLOG" 2>/dev/null | head -20 | sed 's/^/ /' >&2 - exit $rc +if [ ! -f "$ROOT/$DIR/$TEX.tex" ]; then + echo "找不到 $DIR/$TEX.tex" >&2 + exit 2 fi -PDF="${TEX%.tex}.pdf" -# 打印用户熟悉的 Windows 路径形式，而不是 Git Bash 的 /d/... 挂载路径 -WINPDF="$WIN_ROOT/$DIR/$PDF" -if scp -i "$WSL_KEY" -q "$WSL_HOST:$WSL_ROOT/$DIR/$PDF" "$WINPDF"; then - echo "PDF 已取回: $(echo "$WINPDF" | sed 's|^/\([a-zA-Z]\)/|\U\1:/|')" -else - echo "PDF 取回失败" >&2; exit 1 -fi \ No newline at end of file +build_one "$DIR" "$TEX" \ No newline at end of file