# books

**Repository Path**: graviton/books

## Basic Information

- **Project Name**: books
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-29
- **Last Updated**: 2026-11-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 教材学习仓库

保存可持续修改的中文教材译写、推导、例题与图解。目前有三本书稿：Sobolev 空间，有限元磁静力学中的树-余树规范（tree-cotree gauge），以及微分几何与广义相对论（曲线、曲面、内蕴几何，广义相对论部分待补）。另有 [Zig 0.17.0 语言参考的中文翻译](src/zig-langref/README.md)，以及 [Janet 语言文档中文版](src/janet-langref/README.md)。Zig 和 Janet 文档都使用各自上游的 HTML 生成流程，不经过 Typst。

## 编译与阅读

已在 Windows / Typst 0.15.1 环境编译。仓库根目录运行：

```powershell
.\src\build.ps1
# 修改源文件后自动编译
.\src\build.ps1 -Watch
# 编译树-余树规范书稿
.\src\build.ps1 -Book tree-cotree
# 编译微分几何与广义相对论书稿
.\src\build.ps1 -Book diff-geo
```

输出为 `output/pdf/sobolev-zh.pdf`、`output/pdf/tree-cotree-zh.pdf` 与 `output/pdf/diff-geo-zh.pdf`。也可直接运行：

```powershell
typst compile --root . src/sobolev/book-sobolev.typ output/pdf/sobolev-zh.pdf
typst compile --root . src/tree-cotree/book-tree-cotree.typ output/pdf/tree-cotree-zh.pdf
typst compile --root . src/diff-geo/book-diff-geo.typ output/pdf/diff-geo-zh.pdf
```

### Linux 编译

Linux 服务器上通常没有书稿使用的思源宋体、STIX Two Math 与 Cascadia Mono，直接编译会出现字体警告，中文显示为方框。用 `--font-path` 指定字体目录即可（本机的 `/data/cmbin` 含思源黑体与 STIX Two Math，宋体会回退到黑体，仅供预览）：

```bash
mkdir -p output/pdf
typst compile --font-path /data/cmbin --root . src/sobolev/book-sobolev.typ output/pdf/sobolev-zh.pdf
typst compile --font-path /data/cmbin --root . src/tree-cotree/book-tree-cotree.typ output/pdf/tree-cotree-zh.pdf
typst compile --font-path /data/cmbin --root . src/diff-geo/book-diff-geo.typ output/pdf/diff-geo-zh.pdf
# 逐页导出 PNG 做视觉检查
typst compile --font-path /data/cmbin --root . src/tree-cotree/book-tree-cotree.typ "tmp/pages/p{0p}.png" --ppi 100
```

其他机器上把 `--font-path` 换成存放上述字体的目录；用 `typst fonts --font-path <目录>` 确认字体已被识别。

### 公式检查

Typst 公式与 LaTeX 有不少差异，部分错误能编译通过却显示错误，见 [Typst 与 LaTeX 公式的常见差异](docs/Typst与LaTeX公式差异.md)。提交前可运行：

```bash
python scripts/check_typst_math.py            # 扫描 src/ 下全部 .typ，发现警告时退出码为 1
python scripts/check_typst_math.py --notes    # 同时列出低优先级提示
```

直接命令要求输出目录已存在。编译不依赖 Python、不加载远程 Typst 包，也不读取参考 PDF，因此没有教材文件的机器仍可构建。

## 文件组织

- `inputs/`：原始参考资料，沿用现有 Git 忽略规则。
- `AGENTS.md`：协作说明（uv 环境、编译与检查流程）。
- `docs/`：项目文档与重写进度。
- `src/lib/book.typ`：通用中文书稿样式与定义、命题、注释框。
- `src/sobolev/book-sobolev.typ`：书稿入口、封面、目录和章节顺序。
- `src/sobolev/chapters/`：按主题拆分的中文源稿。
- `src/sobolev/figures/`：可直接修改的 Typst 原生矢量图。
- `src/tree-cotree/`：树-余树规范书稿，结构同上；`figures/` 中的 SVG 由 `tools/tree_cotree_demo.py` 生成，第 12 章的三维数值由 `tools/tree_cotree_3d.py`、高阶数值由 `tools/whitney_high_order.py` 给出。
- `src/diff-geo/`：微分几何与广义相对论书稿，结构同上；`figures/` 中曲线部分的 SVG 由 `tools/diff_geo_curves.py` 生成。
- `src/zig-langref/`：Zig 语言参考中文版。在该目录下运行 `zig build` 生成 HTML；构建方法、翻译约定和许可证（MIT）见其中的 README 与 AGENTS.md。
- `src/janet-langref/`：Janet 语言文档中文版（官网固定提交，1.42.0-dev 系列）。沿用上游 `.mdz` 源格式和 Mendoza 生成 HTML；在该目录下运行 `build.ps1` 或 `JANET_PATH=tools janet tools/mdz build`。构建方法、翻译进度和许可证见其中的 README 与 UPSTREAM.md。
- `tools/`：可复现的网格与推导辅助脚本；含 `reproduce_nipg_counterexample.py`、`plot_nipg_nonuniform_l2.py` 和 `scan_nipg_three_subdivision.py`，用于复算 NIPG 非均匀网格例、绘制收敛曲线及扫描三段细分比例的观测阶；`plot_dg_optimal_mesh.py` 绘制一维 P0 上风 DG 渐近最优网格密度的示例。比例扫描默认取层级 9–11；复算脚本的 `--penalty-scaling local|global` 可切换面局部罚与陈书式全局 `h = max_K h_K` 罚尺度；`--problem quadratic|cubic` 可比较不同精确解对观测阶的影响。
- `scripts/`：仓库维护脚本，如公式检查 `check_typst_math.py`。
- `output/pdf/`：编译结果；`tmp/pdfs/`：视觉检查临时文件，均不进入 Git。

## 参考教材与进度

当前为起步学习稿，完整状态与后续任务见[重写进度](docs/重写进度.md)、[树-余树规范进度](docs/树-余树规范进度.md)与[微分几何与广义相对论进度](docs/微分几何与广义相对论进度.md)。

Sobolev 书稿的主要参考：

1. `inputs/sobolev-space-索伯列夫空间/An Introduction to Sobolev Spaces and Interpolation 2--Luc Tartar 2007.pdf`
2. `inputs/sobolev-space-索伯列夫空间/Finite Element Methods and Their Applications--陈掌星.pdf`

树-余树规范书稿的参考资料在 `inputs/tree-cotree-gauge-树-余树规范/`：Manges–Cendes 1995、Rapetti–Dubois–Bossavit 2003、Creusé–Dular–Nicaise 2019、Rapetti–Alonso Rodríguez–De Los Santos 2021、Kapidani–Merkel–Schöps–Vázquez 2021 与 White 1997 学位论文；缩写与页码换算见书稿导读。

微分几何与广义相对论书稿的参考资料在 `inputs/math-gr-diff-geo/`：以 do Carmo《Differential Geometry of Curves and Surfaces》（2016）为主干，辅以 Needham《Visual Differential Geometry and Forms》与梁灿彬、周彬《微分几何入门与广义相对论》；缩写、页码换算与挠率的符号约定见书稿导读。

## 字体与编辑约定

参考已有 Typst 项目的模板与分章方式，重新建立独立样式。正文为 `Libertinus Serif` + `Source Han Serif SC`，标题为 `Source Han Sans SC`，数学为 `STIX Two Math`，代码为 `Cascadia Mono`。这些字体均已在当前机器确认存在；迁移时用 `typst fonts` 检查并在 `src/lib/book.typ` 统一替换。数学字体也可改成 Typst 自带的 `New Computer Modern Math`，中文字体需要系统提供。

中文段落按源码可读性正常换行即可；接受 Typst 当前可能在汉字间产生的空格，暂不做额外处理。增加章节时在书稿入口（`src/sobolev/book-sobolev.typ`、`src/tree-cotree/book-tree-cotree.typ`、`src/diff-geo/book-diff-geo.typ`）中添加 `include`。新内容需注明原书节号、印刷页码和 PDF 页码；统一记号时说明映射，发现原书疑点时保留校注。不要把补充解释写成作者原文。每轮执行编译，并检查 PDF 中的公式、图表及分页。