Skip to content

Commit 0cdf52c

Browse files
committed
docs: terms take the spelling this tree already uses, and the README labels take the chapters' own titles
`流水线` was a metaphor invented for the 简体中文 README. It occurs twice in docs/zh and in another sense both times, so the self-hosting line says what it does instead, and the English drops "pipeline" with it. Three terms had a spelling already: `载荷` rather than payload (217 uses against the English word in prose), `运行时适配包` rather than 运行时适配器 (chapter 33's own title), and `SBOM` rather than 物料清单, which is chapter 51's section heading but not the word its prose uses. Five 简体中文 chapter labels had been translated from the English titles rather than taken from the chapters, and named chapters that do not exist under those names: `mcpp.toml 清单` for 工程文件指南, `按场景查命令` for 选命令, `交叉编译` for 交叉构建, `触及设备` for 抵达一台设备, `异构构建` for 异构硬件构建. Both languages now label a chapter with its own title, shortened from the front where a cell is tight. Rule 14 grew the second half of that check. It compares the title only in the two READMEs. Measured across docs/, sixty-odd links label a chapter by its subject on purpose -- `[30 -- build.mcpp]`, `[04 -- §2.6.1]`, `[10 -- Packaging & Release]` -- and requiring a title there would be a new convention wearing a checker's clothes rather than a defect being caught. Both halves were verified by rewording a label in each language and watching the rule name the file, the label and the title.
1 parent 1a4385f commit 0cdf52c

3 files changed

Lines changed: 47 additions & 18 deletions

File tree

.github/tools/check_docs_structure.sh

Lines changed: 30 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@
1717
# 11. every chapter states its reader, its question and its exclusions
1818
# 12. a citation naming a section lands in the chapter that contains it
1919
# 13. every table the manifest reference documents is in the lookup index
20-
# 14. a link labelled with a chapter number points at that chapter
20+
# 14. a link labelled with a chapter number points at that chapter, by its title
2121
# 15. every table row is inside a table
2222
#
2323
# What it deliberately does NOT check: whether a chapter documents what is
@@ -373,6 +373,35 @@ for f in files:
373373
print(f"FAIL: {f}: label `{label}` names chapter "
374374
f"{label_no.group(1)}, the link goes to {base}")
375375
bad += 1
376+
continue
377+
# The number agrees. In the two READMEs the label is also expected to
378+
# carry the chapter's own title, because that is where a renumbering or
379+
# a rename rots unseen and five 简体中文 labels were translated from the
380+
# English titles rather than taken from the chapters.
381+
#
382+
# NOT IN docs/. Measured across the tree: sixty-odd links there label a
383+
# chapter by its SUBJECT on purpose -- `[30 -- build.mcpp]`,
384+
# `[04 -- \u00a72.6.1]`, `[10 -- Packaging & Release]` -- and that is a
385+
# convention, not a defect. A check that would require editing all of
386+
# them is imposing a new rule rather than enforcing an existing one.
387+
if f.name not in ("README.md", "README.zh-CN.md"):
388+
continue
389+
said = label.strip()[label_no.end(1):].strip(" -\u2014\u2013:\uff1a")
390+
if not said:
391+
continue
392+
target = (f.parent / path) if not path.startswith("docs/") else pathlib.Path(path)
393+
if not target.is_file():
394+
continue
395+
head = target.read_text(errors="ignore").split("\n")[0]
396+
title = re.sub(r"^#\s*\d{2}\s*(?:\u2014\u2014|\u2014|--|-)?\s*", "", head).strip()
397+
# A PREFIX rather than equality: shortening a title by dropping its tail
398+
# is honest, and `[30 -- Build Programs]` for `Build Programs:
399+
# \u0060build.mcpp\u0060` is the shape that takes. Words the chapter does not
400+
# use are what this rejects -- a label translated from the other
401+
# language's title rather than taken from the chapter's own.
402+
if title and not title.startswith(said):
403+
print(f"FAIL: {f}: label says `{said}`, chapter {base} is titled `{title}`")
404+
bad += 1
376405
sys.exit(1 if bad else 0)
377406
PYLABEL
378407

README.md

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@
2525
- **Package management and a module-library ecosystem** — SemVer constraints, lockfile, cross-project BMI cache, custom indices; a library from [mcpplibs](https://github.com/mcpplibs) is two lines away from `import`
2626
- **Toolchain management and cross-compilation**`family@version` installed on demand; `--target` moves the same build to Windows, macOS, Cortex-M or RISC-V bare metal, and one source tree reaches several hosted targets over openkal
2727
- **Environment and runtime** — the user-space environment xlings provides: toolchains and dependencies stay in an isolated sandbox, and a runner puts the artifact on a board or an emulator
28-
- **Pure modular self-hosting** — mcpp is written entirely in C++23 module interface units and builds itself with this pipeline
28+
- **Pure modular self-hosting** — mcpp is written entirely in C++23 module interface units and builds itself
2929

3030
## Why mcpp
3131

@@ -455,12 +455,12 @@ a command in front of a reader, to the chapter that owns it.
455455
| Part | Start at |
456456
|---|---|
457457
| `0x` fundamentals | [01 Getting Started](docs/01-getting-started.md) · [04 The mcpp.toml Manifest](docs/04-mcpp-toml.md) · [09 Commands by Scenario](docs/09-commands-by-scenario.md) |
458-
| `1x` publishing | [10 Packaging for Release](docs/10-pack-and-release.md) · [11 Publishing a Library](docs/11-publishing-a-library.md) · [12 Distributing a Prebuilt Library](docs/12-binary-distribution.md) |
458+
| `1x` publishing | [10 Packaging an Application for Release](docs/10-pack-and-release.md) · [11 Publishing a Library to mcpp-index](docs/11-publishing-a-library.md) · [12 Distributing a Prebuilt Library](docs/12-binary-distribution.md) |
459459
| `2x` toolchains and targets | [20 Toolchain Management](docs/20-toolchains.md) · [21 The Target Triple](docs/21-the-target-triple.md) · [24 Cross-Compilation Over openkal](docs/24-openkal-cross.md) |
460-
| `3x` extending mcpp | [30 Build Programs](docs/30-build-mcpp.md) · [31 Authoring a Rule Package](docs/31-authoring-a-rule-package.md) · [34 Authoring a Board-Support Package](docs/34-authoring-a-bsp.md) |
460+
| `3x` extending mcpp | [30 Build Programs: `build.mcpp`](docs/30-build-mcpp.md) · [31 Authoring a Rule Package](docs/31-authoring-a-rule-package.md) · [34 Authoring a Board-Support Package](docs/34-authoring-a-bsp.md) |
461461
| `4x` devices and accelerators | [40 Bare-Metal and Freestanding Targets](docs/40-baremetal.md) · [41 Reaching a Device](docs/41-devices.md) · [42 Heterogeneous Builds](docs/42-heterogeneous-builds.md) |
462-
| `5x` contracts for programs | [50 Machine-Readable Output](docs/50-machine-output.md) · [51 Supported Versions](docs/51-supported-versions.md) · [the specifications](docs/specs/README.md) |
463-
| `9x` mcpp itself | [90 Building from Source](docs/90-build-from-source.md) · [92 Releasing mcpp](docs/92-release.md) |
462+
| `5x` contracts for programs | [50 Machine-Readable Output](docs/50-machine-output.md) · [51 Supported Versions and Compatibility](docs/51-supported-versions.md) · [the specifications](docs/specs/README.md) |
463+
| `9x` mcpp itself | [90 Building from Source and Contributing](docs/90-build-from-source.md) · [92 Releasing mcpp](docs/92-release.md) |
464464

465465
Every directory under [`examples/`](examples/) is a project that builds, and
466466
[03 — Examples](docs/03-examples.md) says which one teaches what. Full options

README.zh-CN.md

Lines changed: 12 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@
2525
- **包管理与模块化库生态** — SemVer 约束、锁文件、跨项目 BMI 缓存、自定义索引;[mcpplibs](https://github.com/mcpplibs) 的库两行引入即可 `import`
2626
- **工具链管理与通用交叉构建**`family@version` 按需安装;`--target` 让同一次构建换到 Windows、macOS、Cortex-M 或 RISC-V 裸机,一份源码经 openkal 触及多个有操作系统的目标
2727
- **环境与运行时** — xlings 提供的用户态环境:工具链与依赖都留在隔离沙盒里,runner 把产物送上板子或模拟器
28-
- **纯模块化自举** — mcpp 完全由 C++23 模块接口单元写成,并用这条流水线构建自己
28+
- **纯模块化自举** — mcpp 完全由 C++23 模块接口单元写成,并用它自己构建自己
2929

3030
## 为什么选择 mcpp
3131

@@ -255,7 +255,7 @@ import mcpplibs.cmdline;
255255
</details>
256256

257257
<details>
258-
<summary><b>交叉编译、裸机与设备</b></summary>
258+
<summary><b>交叉构建、裸机与设备</b></summary>
259259

260260
- `mcpp build --target <triple>` — 一个开关;该目标所需的工具链载荷会自动解析并安装
261261
-`x86_64-linux-gnu` 到 Cortex-M、Cortex-A 与 RISC-V 裸机,完整的表见[平台支持](#平台支持)
@@ -267,7 +267,7 @@ import mcpplibs.cmdline;
267267
</details>
268268

269269
<details>
270-
<summary><b>异构构建与加速器</b></summary>
270+
<summary><b>异构硬件构建与加速器</b></summary>
271271

272272
- `[build] accel = "cuda12.9+{sm_89}, vulkan1.2"` — 一次构建可以点名一个或多个设备后端,该构建里 `cfg(accelerator = "cuda")` 为真
273273
- 目前有规则包的编程模型有五个:CUDA、HIP、SYCL、Vulkan/SPIR-V 与 Ascend C
@@ -317,7 +317,7 @@ import mcpplibs.cmdline;
317317
- `build.mcpp` — 为 mcpp 没有现成规则的那一步写的构建程序,说的是一套带版本号的指令协议,而不是靠猜
318318
- `mcpp::action` 用显式的输入与输出声明一份工作,于是生成物参与增量图,而不是待在图外
319319
- 规则包把那一步带给别的项目:包声明一个 rule 模块,消费者以 feature 的形式选中它
320-
- payload、运行时适配器与板级支持包都是普通的包 —— 一个工具、一个驱动或一块板子,由安装库的那个解析器安装
320+
- 载荷、运行时适配包与板级支持包都是普通的包 —— 一个工具、一个驱动或一块板子,由安装库的那个解析器安装
321321

322322
</details>
323323

@@ -331,7 +331,7 @@ import mcpplibs.cmdline;
331331
- `mcpp add / remove / update` — 依赖管理
332332
- 命令行上的 profile 与 feature:`--release` / `--profile <name>`(`build``run`),`--features <list>`(`build``run``test`)
333333
- `mcpp why [toolchain|runtime|deps|runners]` — 解释已解析的构建决策;`--format json` 供程序读取
334-
- `mcpp emit sbom`为刚刚记录下来的这次解析产出一份 CycloneDX 物料清单
334+
- `mcpp emit sbom`为已记录的那次解析产出一份 CycloneDX 格式的 SBOM
335335
- `mcpp --offline` / `MCPP_OFFLINE=1` — 仅使用已存在的本地状态
336336
- `mcpp explain E0001` — 错误码详细解释
337337
- `mcpp self doctor` — 环境自诊断
@@ -435,13 +435,13 @@ mcpp 的身份模型是两条正交轴:**工具链** = `family@version`(family
435435

436436
| 部分 | 从这里开始 |
437437
|---|---|
438-
| `0x` 基础 | [01 快速开始](docs/zh/01-getting-started.md) · [04 mcpp.toml 清单](docs/zh/04-mcpp-toml.md) · [09 按场景查命令](docs/zh/09-commands-by-scenario.md) |
439-
| `1x` 发布 | [10 发布打包](docs/zh/10-pack-and-release.md) · [11 发布一个库](docs/zh/11-publishing-a-library.md) · [12 分发预编译库](docs/zh/12-binary-distribution.md) |
440-
| `2x` 工具链与目标 | [20 工具链管理](docs/zh/20-toolchains.md) · [21 目标三元组](docs/zh/21-the-target-triple.md) · [24 基于 openkal 的交叉编译](docs/zh/24-openkal-cross.md) |
441-
| `3x` 扩展 mcpp | [30 构建程序](docs/zh/30-build-mcpp.md) · [31 编写规则包](docs/zh/31-authoring-a-rule-package.md) · [34 编写板级支持包](docs/zh/34-authoring-a-bsp.md) |
442-
| `4x` 设备与加速器 | [40 裸机与 freestanding 目标](docs/zh/40-baremetal.md) · [41 触及设备](docs/zh/41-devices.md) · [42 异构构建](docs/zh/42-heterogeneous-builds.md) |
443-
| `5x` 给程序的契约 | [50 机器可读输出](docs/zh/50-machine-output.md) · [51 支持的版本](docs/zh/51-supported-versions.md) · [规范](docs/specs/README.md) |
444-
| `9x` mcpp 自身 | [90 从源码构建](docs/zh/90-build-from-source.md) · [92 发布 mcpp](docs/zh/92-release.md) |
438+
| `0x` 基础 | [01 快速开始](docs/zh/01-getting-started.md) · [04 mcpp.toml 工程文件指南](docs/zh/04-mcpp-toml.md) · [09 按场景选命令](docs/zh/09-commands-by-scenario.md) |
439+
| `1x` 发布 | [10 发布打包](docs/zh/10-pack-and-release.md) · [11 发布一个库到 mcpp-index](docs/zh/11-publishing-a-library.md) · [12 分发预编译库](docs/zh/12-binary-distribution.md) |
440+
| `2x` 工具链与目标 | [20 工具链管理](docs/zh/20-toolchains.md) · [21 目标三元组](docs/zh/21-the-target-triple.md) · [24 基于 openkal 的交叉构建](docs/zh/24-openkal-cross.md) |
441+
| `3x` 扩展 mcpp | [30 构建程序:`build.mcpp`](docs/zh/30-build-mcpp.md) · [31 编写规则包](docs/zh/31-authoring-a-rule-package.md) · [34 编写板级支持包](docs/zh/34-authoring-a-bsp.md) |
442+
| `4x` 设备与加速器 | [40 裸机与 freestanding 目标](docs/zh/40-baremetal.md) · [41 抵达一台设备](docs/zh/41-devices.md) · [42 异构硬件构建](docs/zh/42-heterogeneous-builds.md) |
443+
| `5x` 给程序的契约 | [50 机器可读输出](docs/zh/50-machine-output.md) · [51 受支持的版本与兼容性](docs/zh/51-supported-versions.md) · [规范](docs/specs/README.md) |
444+
| `9x` mcpp 自身 | [90 从源码构建与参与贡献](docs/zh/90-build-from-source.md) · [92 发布 mcpp](docs/zh/92-release.md) |
445445

446446
[`examples/`](examples/) 下的每一个目录都是一个能构建的工程,
447447
[03 — 示例项目](docs/zh/03-examples.md) 说明哪一个教什么。任意命令的完整选项

0 commit comments

Comments
 (0)