laoyang/ouc_latex_template
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity
50 Commits 1 Branch 0 Tags
main
Commit Graph
5 Commits
Author SHA1 Message Date
laoyang 3906bb49a4 清理代码库中的开发过程内容 
- 删除 WORKFLOW.md（开发流程文档，已移入记忆库）
- build.sh 去掉 WSL 相关说明
- 33 个源文件的注释：去掉踩坑记录、实测推导、原文件对比、工单号引用
- 保留技术参数、约束说明、命令含义

净删 399 行。全库 16/16 编译通过。
 2026-11-01 09:29:00 +08:00
laoyang a4bfcac82a 新增《教材》LaTeX 模板，从 sre 教材抽取版式骨架 #25 
源：D:\Yongquan\code\sre =《软件需求工程导论》完整教材
（13 章 + 5 附录，78 万字节，265 页 PDF，elegantbook 文档类）

## 新增文件

   教材/ouctextbook.sty    版式配置
   教材/elegantbook.cls    本地化过的文档类（改过字体）
   教材/教材.tex           示例正文（1 章 + 附录 + 参考文献）
   教材/reference.bib      参考文献库（虚构条目）
   教材/README.md          用法 + 踩坑记录

## 核心约束：字体的共用性

用户明确要求「注意字体的共用性」。原教材用 elegantbook 的
chinesefont=founder 档，加载方正四大字体：

   FZShuSong-Z01 / FZHei-B01 / FZKai-Z03 / FZFangSong-Z02

这些是**商业字体，不能随仓库分发**（#17 定下的规矩）。

### elegantbook 三档字体全都不通用

| 选项 | 实际字体 | 问题 |
|---|---|---|
| founder（默认） | 方正四大字体 | 商业字体，换机器就废 |
| ctexfont | 系统字体（Win=SimSun，macOS=PingFang） | 三平台三种样子 |
| nofont | 不设 | 不配置就报错 |

### 只写 nofont 还不够 —— cls 自身还硬编码字体

elegantbook.cls 第 176/184 行：

   \setmainfont{TeXGyreTermesX}[...]
   \setsansfont{texgyreheros}[...]

这两款在精简 TeX Live 上都没有，报 9 个错误连发：

   ! Package fontspec Error: The font "texgyreheros-regular" cannot be found

**实测：在 \documentclass 之后用 \setsansfont 覆盖无效** ——
类加载时字体族已注册失败，后面重新指定救不回来。

⇒ 所以本模板必须带一份**本地化的 cls**，改三处（都留了"本地化"注释）：

| 位置 | 改动 |
|---|---|
| ~176 行 | TeXGyreTermesX → texgyretermes + Path=../fonts/tex-gyre-termes/ |
| ~184 行 | texgyreheros → OUCSans + Path=../fonts/ouc-sans/ |
| \maketitle | example-image → \ouc@coverblank |

这是本模板与仓库其他模板的**唯一结构性差异**：别的模板只要
\input{../fonts.tex}，本模板还要那份改过字体的 cls。

## 踩到的三个坑

### 1. 封面不写 \cover{} 会插一张 "Image" 占位图

cls 第 1288~1300 行：
   \ifcsname @cover\endcsname ... \else
     \includegraphics[width=\linewidth]{example-image}   ← mwe 的灰底占位图

首页顶着 "Image" 两个大字。已把 else 分支换成空盒子。

### 2. 占位盒宽度不能是 0（这个坑耗了最久）

第一版 \rule{0pt}{0pt}（0 宽），立刻冒出：

   Overfull \hbox (5.00002pt too wide) in paragraph at lines 44--44

试过全部无效，溢出量死钉在 5.00002pt 不动：
  改 \hspace{2em} / \hspace{2.5em}     无效
  改 minipage 的 0.67/0.27\linewidth   无效
  改 tabular 列间距 @{}l@{}            无效
  改 \colorbox 的 \makebox[\hsize]     无效

根因：0 宽空盒让 \linewidth 在 titlepage 里与 \textwidth 差 5pt，
后续并排的 \parbox{0.8\textwidth} + 两个 minipage 整体超宽。

✅ 正解：给占位盒满宽
   \newcommand{\ouc@coverblank}{%
     \rule{0pt}{0pt}\hspace{\linewidth}\rule{0pt}{0pt}}
实测 0 Overfull。

### 3. 封面色带改不动（一行 \colorlet 的位置问题）

cls 第 345 行 `\colorlet{coverlinecolor}{second}` 在**类加载末尾**执行，
把 coverlinecolor 绑到 second 色（black 模式下就是黑）。

⇒ 导言区写 \colorlet 会被覆盖，实测色带仍是纯黑。
必须用 \AtBeginDocument 排到它后面。

## build.sh 补了 bibtex 支持

原来只跑两遍 xelatex，教材的参考文献出不来。
新增：目录下有 .bib（排除 *-blx.bib 这种中间产物）就插一次 bibtex，
再补一遍 xelatex，最后跑统计那一遍。

## 验证

   8 页  error 0  Overfull 0  Underfull 0
   封面色带 RGB(32,178,170) 青绿，实测 fill=(0.125,0.698,0.667)
   封面无 example-image 占位

字体（PDF 内嵌实测，全部来自仓库）：
   OUCSerif-Regular / -Bold        中文正文
   OUCKai-Regular                  中文斜体（楷体代）
   TeXGyreTermes-Regular/-Bold/-Italic   西文
   LMMono10-Regular                \texttt 等宽（TeX Live 自带）

→ **无方正、无 SimSun/SimHei、无 Times New Roman**

全库 16/16 通过（新增第 16 项，已加入 verify_all.sh）。

⚠️ Windows 端本机未能编译：TeX Live 写字体缓存
（C:\texlive\2022\texmf-var）被安全策略拦截，属环境限制非模板问题。
模板只依赖 TeX Live 标准宏包与发行版自带字体；原教材本身就是在
Windows + TeX Live 2022 上编出来的。

## .gitignore 补充

新增 *-blx.bib、*.run.xml（biblatex 中间产物）、*/.preview/（预览图）。

## 与原教材的差异

| 项 | 原教材 | 本模板 | 原因 |
|---|---|---|---|
| 封面图 | cover.jpg | 无（纯色带） | 模板不附图片 |
| 字体 | 方正四大字体 | 仓库开源字体 | 商业字体不能分发 |
| 西文无衬线 | texgyreheros | OUC Sans | 仓库没有 Hero |
| 正文 | 13 章 265 页 | 1 章示例 | 只抽骨架 |
 2026-11-01 08:06:22 +08:00
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
laoyang 8660860495 build.sh 两处输出打磨 #18 
1) 页码那行改为原样输出。原先用正则截断到 "page"，把结尾的括号吃掉了，
   打出来是 "1 page" 而不是 "(1 page)."，看着像少字符。

2) 临时文件改用 ./.build_out.$$ + trap 清理，不再用 mktemp。mktemp 在
   Windows 的 Git Bash 里返回 /tmp/... 形式，随后的 rm 会触发安全检查
   （SAFE_DELETE_INVALID_PATH: embedded drive prefix is not allowed），
   无害但会往输出里插一行噪音。

3) 取回成功后打印的路径转成 Windows 形式（D:/...），不再显示 Git Bash
   的挂载路径（/d/...）。
 2026-10-29 12:03:02 +08:00
laoyang ef1bc72603 加入 WSL 编译取回脚本与换行符策略 #18 
build.sh      在 WSL 内编译（默认 xelatex），成功后用 scp 把 PDF 取回
              Windows 侧同路径。支持单模板与 all 全库。路径全部走环境
              变量覆盖，默认值可用，不硬编码某个人的目录。

verify_all.sh 批量编译验证全库主文件，打印 error / Overfull / Underfull
              与页数。每个模板都在自己目录下编译 —— 模板的 .sty 与
              ../fonts/ 是相对编译工作目录解析的，从仓库根调用找不到字体。

.gitattributes 把所有 .sh 钉成 eol=lf。Windows 侧 core.autocrlf=true 会把
              脚本存成 CRLF，到 Linux 上执行就报
                  /bin/bash^M: bad interpreter: No such file or directory
              这个错误容易误判成"没装 bash"，所以在仓库层面固定规则，
              不依赖各人本机的 autocrlf 设置。.tex/.sty/.cls 同样钉 lf，
              避免中文注释行尾残留 CR 被 XeTeX 当字符排出来。

关于脚本为什么要写成「编译-取回」而不是纯编译：
WSL2 会按空闲把整个虚拟机 poweroff，届时 xelatex 连同 PID 1 一起消失，
/tmp 也一并清空（后台日志丢失）。脚本的 ssh 会话在编译期间保持不断，
顺带起了保活作用，所以不要把它改成后台运行。
 2026-10-29 12:01:06 +08:00