docs: the README states three tiers, both languages state the same targets, and a check enforces it - #593
Merged
Conversation
…rgets, and a check enforces it The two top-level READMEs were outside every documentation check but the emoji rule, and had drifted from the implementation in three ways. The target table now carries the three tiers the engine actually stores -- `verified`, `preview`, `planned` -- and every canonical spelling in `modules/toolchain-model/src/triple.cppm`. The distinction is load-bearing: a build for a `planned` row is refused, while a `preview` row builds and links, and three rows the README called `planned` were `preview`. Three rows were absent altogether. The 简体中文 table was seven rows behind -- every bare-metal row, plus the footnote that says a freestanding target takes its C library, startup code and emulator from a board-support package -- so that README described a tool with no freestanding support at all. The Feature Overview gains the surfaces shipped since 2026.8 and previously unmentioned in either language: cross-compilation, bare metal and devices; heterogeneous builds and accelerators; and the extension model of `build.mcpp` and rule packages. `--release`, `--profile`, `--features`, `mcpp emit sbom` and the machine-readable output join the command list, and `mcpp why` regains its fourth topic. The Documentation section names the parts of the manual and points at the index that owns the reverse lookup, rather than naming seven chapters out of thirty-one. The benchmark keeps its table, its provenance and its control row, and loses half its lines. Two counts that rot with the tree -- "43+ C++23 modules" against 119 interface units -- are replaced by prose; the one count that is a measurement stays where it is measured. Rules 9 and 10 of `check_docs_structure.sh` now cover the README pair: the row counts are 61 and 61, and a row dropped from either side fails the check. Rule 14 is new -- a link labelled with a chapter number must point at that chapter. It was written for `[docs/13 -- ...](docs/40-baremetal.md)` in README.md and found six more of the same, left in `docs/` and `docs/specs/` by the renumbering in #590; all seven are corrected here. `triple.cppm`'s own tier legend named two of the three tiers it stores. The README now cites that file, so it is corrected in the same change.
…ow my own criterion could not see Review found a table row sitting on line 1 of README.zh-CN.md, above the document's title. It was put there by the probe that verified rule 10: the restore step replaced the empty string, which inserts at position 0 rather than where the row came from. Rule 10 stayed green throughout at 61 rows against 61, because a count cannot see WHERE a row is. The row is back in the target table. Rule 15 is the criterion that would have caught it: a maximal run of lines beginning with `|` is a table only if its second line is a delimiter row, so a row moved anywhere else lands in a run of its own and is reported. Verified by reproducing the defect exactly as the probe produced it, and watching the rule name the file and the line. The opening now answers "what is this" before the feature list does. C++ spreads five jobs across five tools; the table gives mcpp's answer for each, and a second row names what each column is usually recognised as, so a reader arriving with CMake, vcpkg or rustup in mind can place the whole tool in one glance. The highlights had not moved since the tool was a module build system. Two of the five bullets stated the same thing twice and none of them mentioned a target other than the host. They now cover the surface the sections below document: dependencies and workspaces are one bullet, and the two that replace the freed one state that a target is one flag away and that accelerators and `build.mcpp` exist. The bundled toolchain versions leave the highlight, since the host default and the freestanding pin are different versions and this line is not where that is explained.
…and the analogy moves to Why mcpp The highlights had been a flat list in which "native C++23 module support" (a capability) sat beside "works out of the box" and "one flag changes the target" (two things a capability is used for), so a reader could not tell which claims were parts of the tool and which were consequences of them. They are now two columns, and the five rows are the same five parts the analogy names, in the same order, so the two tables read as one statement. The analogy is two rows rather than three. The middle row restated mcpp's implementation for each column, which the left column of the highlights already carries; what the analogy is for is placing the tool against something the reader already uses, and that needs the header and one row. It now sits in Why mcpp, where the question it answers is asked. The four bullets it replaces there each said something the highlights table now says. The P1689 detail they carried is in the build-system group of the feature overview, and the mcpplibs link appears twice further down.
…the capability from its use The two-column table made the distinction structural at the cost of the shape the section has always had, and the shape was the better of the two. Each line is a bullet again, in the original form: the bold name is the capability, the first sentence says what it is, and the second says what it is used for. The five names are still the five the analogy in Why mcpp uses, in the same order, and self-hosting returns as the sixth bullet rather than a trailing sentence.
…, in one line The lead sentence is gone: with each bullet named for both halves, saying that a bullet has two halves is a line that explains the next six rather than adding to them. The names now pair a capability with the work it is for -- build plugins with heterogeneous hardware, package management with the module-library ecosystem, toolchain management with cross-compilation -- so the reader sees what each part is for without reading to the end of the line. Every bullet is one line. The mcpplibs link moves up into the ecosystem bullet, where a reader looking for libraries meets it first; it can be given a bullet of its own once the library set is the thing being announced.
…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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
The two top-level READMEs sat outside every documentation check but the emoji
rule, and had drifted from the implementation in three ways. This corrects all
three and closes the hole that let them drift silently.
The target table now carries the three tiers the engine stores.
verified,previewandplannedcome frommodules/toolchain-model/src/triple.cppm, andthe distinction is load-bearing:
prepare.cppmrefuses a build for aplannedrow, while a
previewrow builds and links. Three rows the README calledplannedarepreview; three rows (x86_64-windows-musl,aarch64-none-elf,x86_64-none-elf) were absent. All 23 canonical spellings now appear, in 14rows rather than 21.
The 简体中文 table was seven rows behind — every bare-metal row, plus
footnote 2, which says a freestanding target takes its C library, startup code
and emulator from a board-support package.
bare metalandfreestandingoccurred zero times in that file, so it described a tool with no freestanding
support. Heading count, code-block count and
<details>count were equal onboth sides, which is why no check reported it.
The Feature Overview gains three groups for surfaces shipped since 2026.8
and unmentioned in either language until now: cross-compilation, bare metal and
devices; heterogeneous builds and accelerators; and the extension model of
build.mcppand rule packages.--release,--profile,--features,mcpp emit sbomand the machine-readable output join the command list, andmcpp whyregains its fourth topic,runners.The Documentation section names the parts and points at the index that owns
the reverse lookup, instead of naming seven chapters out of thirty-one. The
benchmark keeps its table, its provenance and its control row, and loses half
its lines. Two counts that rot with the tree — "43+ C++23 modules" against 119
interface units — become prose; the one count that is a measurement stays in
the benchmark paragraph where it is measured, now labelled as belonging to the
pinned workload.
Smaller corrections: the footnote linking to
docs/40-baremetal.mdunder thelabel
docs/13, left by the renumbering in #590; one spelling for the xlingsrepository (
d2learn/xlings301-redirects toopenxlings/xlings); and the--configure-onlyclause the English build-system bullet has and the 简体中文one never received.
The check, and what it caught
Rules 9 and 10 of
check_docs_structure.shnow cover the README pair. Rule 14is new: a link labelled with a chapter number must point at that chapter.
Each was verified by putting the defect back and watching it fail, not by
reading the code:
README.zh-CN.mddocs/13label restoredRule 14 was written for the one label in README.md and found six more of the
same on its first run, left in
docs/anddocs/specs/by the samerenumbering. All seven are corrected here.
triple.cppm's own tier legend namedtwo of the three tiers it stores; the README now cites that file, so it is
corrected too — a two-line comment change, no code.
Test plan
bash .github/tools/check_docs_structure.sh—OK: docs structure checks passbash .github/tools/check_docs_style.sh—OK: docs style checks passmodules/toolchain-model/src/triple.cppm; the tier definitions againstdocs/40-baremetal.mdanddocs/20-toolchains.md; every command and flag againstsrc/cli.cppmbench/results/standard-20260814-linux-x86_64/gcc-mcpp-2026.8.11.3.json,+optcolumn included, so the section still quotes only what that run measuredtriple.cppmand the checker itselfLeft for a follow-up, deliberately
docs/21is missing the twoarmv7arows. Its build-host matrix lists 21targets; the code and
docs/40carry 23. Filling them in means asserting fourhost columns I have not measured, so it is not guessed here.
module into a README edit; a floor would have to be parsed out of prose in two
languages, which is the kind of criterion that goes quietly empty. Removing
the claim was the cheaper correct answer.