docs: say what these things are, not where they used to be
mara on #3923: "past tense is itself a smell for docs, we dont need any 'used to be somewhere else'" and "any gate we add should not have false positives". Those are one instruction: the entire false-positive set of a repo-path checker was prose naming files that are deliberately gone, so removing the prose is what lets the gate be strict instead of carrying a skip-list nobody maintains. Three sites, and only two of them are past tense: `agent-hierarchy.md` named two removed modules to explain that a code path is gone. A reader cannot act on where it used to live; they can act on where cancellation happens now, which is the half the sentence buried. `term_msg.rs` carried a "Design history" paragraph whose live content was three rules -- classification is server-side, `level` carries styling, four named fields are deliberately absent -- wrapped in narration about a redesign and a pointer to a deleted frontend file. Restated as the rules. `gotchas.md` is NOT past tense: it correctly names a file in the website repo. Qualifying it as `hyperhive/website:nix/options.nix` did not work -- the extractor still matches `nix/options.nix` as a substring, so the fix has to be prose that contains no repo-relative path at all. Naming the file alone does that and reads better. Verified against this tree rather than the default checkout: the audit script takes a directory argument and defaults elsewhere, so its first (unchanged) DEAD:3 was a true statement about a different branch. On this one: DEAD 3 -> 0, 141 distinct paths enumerated, and an injected dead path is still caught. Refs #3923
This commit is contained in:
parent
b7c5067f79
commit
efbfeb3954
3 changed files with 10 additions and 14 deletions
|
|
@ -472,7 +472,7 @@ Pipeline:
|
|||
- CommonMark from `nixosOptionsDoc.optionsCommonMark` is the only
|
||||
output — the source of truth, emitted as `.md`.
|
||||
- **HTML + CSS is rendered downstream by the website repo**
|
||||
(`nix/options.nix` there), which consumes this bundle's `host.md` /
|
||||
(its own `options.nix`), which consumes this bundle's `host.md` /
|
||||
`agent.md`, renders them with `cmark-gfm`, and shares one
|
||||
stylesheet (`docs.css`) across `/options/` and the prose `/docs/`
|
||||
tree. Keeping rendering in the website means the theme has a single
|
||||
|
|
|
|||
Loading…
Reference in a new issue