docs: declarative register across docs/, plus a style skill and a checker - #452
Merged
Conversation
…t is decidable
The documentation had drifted into a conversational voice: headings phrased as
questions or as asides ("一段话讲完", "打什么由谁决定", "Consuming one", "The
whole idea in one paragraph"), figurative coinages ("姊妹篇", a package's "legs",
sources that "travel"), and the reader addressed as "you"/"你" in reference
material that a person reads to look something up rather than to follow along.
Every heading is now a noun phrase or a declarative statement, and the second
person is gone from the reference documents. Tutorials keep it — 00, 01 and 04
are read while doing, and the list is written down rather than inferred. Quoted
mcpp output keeps its own wording: `did you mean 'x86_64-linux-musl'?` and `your
toolchain : …` are what the program prints, so reproducing them verbatim is a
requirement, not a lapse.
The sweep surfaced four content gaps that no reading would have found:
* docs/zh/05 was missing §2.6, §2.7, §2.7.1, §2.8 and §2.8.3 — five sections of
a reference manual, including the whole of `[target.*]`;
* docs/zh/05 also had `#### 表形式` filed under the namespace-resolution section
instead of under `[features]`, which is where its English original sits. Same
heading COUNT, different structure, which is why the check compares the level
sequence and not the count;
* docs/zh/10 was missing "manifest keys that need a version floor" and
docs/zh/README the specifications index;
* docs/12 still said `kind = "shared"` was "Linux/ELF today" in its opening
example, two days after Mach-O and PE/MinGW landed.
`.agents/skills/mcpp-docs-style` states the rules; `.github/tools/check_docs_style.sh`
enforces the three that are decidable from the text (heading register, second
person, bilingual structure) and runs in ci-linux beside the version-pin check —
same placement, same reason: pure text, no toolchain, and it catches drift that
is invisible to every other job. The skill says plainly which rule the script
cannot check, and it is the most important one: whether a claim's strength
matches its evidence.
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.
Documentation had drifted into a conversational voice. This restores a
declarative register across
docs/**, and adds the rules — plus a checker forthe part of them a script can decide.
What changed in the prose
一段话讲完,打什么由谁决定,怎么消费,The whole idea in one paragraph,Consuming one概述,打包内容的决定依据,消费方式,Overview,Consuming a package姊妹篇, a package's腿/ "legs", sources that "travel"相关文档:,每个 target 的产物, "interface units included in the package"你的工程, "your toolchain", "hands you the path"Tutorials keep the second person —
00-getting-started,01-examplesand04-build-from-sourceare read while doing. That list is written down, notinferred. Quoted mcpp output keeps its own wording:
did you mean 'x86_64-linux-musl'?andyour toolchain : …are what the program prints, soreproducing them verbatim is a requirement rather than a style lapse, and the
checker blanks inline code spans before matching.
Four content gaps the sweep surfaced
Register work is not usually how you find missing sections, but comparing the
two language versions structurally is:
docs/zh/05was missing five sections — §2.6[dev-dependencies], §2.7[toolchain], §2.7.1[target.*], §2.8[features], §2.8.3[scan_overrides].[target.*]is the entire platform-conditionalmechanism; a 简体中文 reader had no page for it.
docs/zh/05also had#### 表形式filed under namespace resolutioninstead of under
[features], where its English original sits. Same headingcount, different structure — which is why the check compares the level
sequence and not the count.
docs/zh/10was missing "manifest keys that need a version floor";docs/zh/READMEwas missing the specifications index.docs/12still describedkind = "shared"as "Linux/ELF today" in itsopening example, two days after Mach-O and PE/MinGW landed.
The rules, and what a script can and cannot check
.agents/skills/mcpp-docs-stylestates them..github/tools/check_docs_style.shenforces the three that are decidable from the text — heading register, second
person in reference docs, bilingual heading structure — and runs in
ci-linuxbeside the version-pin check: pure text, no toolchain, and it catches drift
(a 简体中文 page falling behind its original) that is invisible to every other
job.
The skill says plainly which rule the script cannot check, and it is the
one that matters most: whether a claim's strength matches its evidence. Its
worked example is a mistake from this repository — an inference about a guard
being inert on native builds, written up as if measured, when reading
resolution.jsonwould have shown it was not.