Skip to content

Bring the documentation and the website up to the unreleased changes - #50

Merged
zoosky merged 2 commits into
mainfrom
chore/docs-up-to-par
Sep 12, 2026
Merged

zoosky merged 2 commits into
mainfrom
chore/docs-up-to-par

Conversation

@zoosky

@zoosky zoosky commented Sep 12, 2026

Copy link
Copy Markdown
Owner

Documentation only: no code, no manifests, no behaviour. Five things the pages did not say since 0.10.0, found by auditing every page against the Unreleased changelog.

What changed

  • A Command line page on the site (/docs/cli), third in the navigation after Rust and JavaScript. The three pages after it are renumbered (04.language, 05.architecture, 06.divergences) so the order reads that way; slugs come from the name, so no link changes. The docs index gains a "Start here" row and no longer routes "a CLI" to the Rust page.
  • A Command line section in the root README, with install, the three commands a CI pipeline uses, and a pointer to the crate README. The MSRV line now says 1.96, which is what the CI job runs; it said 1.82.
  • The landing page's "The same engine in a browser" feature is "…in a browser, and in a shell".
  • The JavaScript page and the npm README record what Share the schema vocabulary between the hosts #48 changed: the vocabulary is shared with the command line (one schema file serves both hosts, linked); a schema object is read key by key, so a class instance or proxy works; an undefined variable is null; a type list may not nest; a property whose getter throws is refused as unreadable rather than read as absent. The npm README ships with the next release.
  • The architecture page's lead and description said "one trait seam, two responsibilities left outside" above a body that said three traits; both now match. Its workspace table lists all three members, and the paragraph after it says why a binary is a host and the vocabulary crate is not.

Verified

scripts/build-site.sh builds with the new page; /docs/rust, /docs/javascript, /docs/cli, /docs/language, /docs/architecture and /docs/divergences all come out at their slugs; every /docs/* link across the built site resolves; cargo run --example readme still runs; fmt and the library tests pass.

Review fixes

Eight findings from /code-review and three it cut for room, all taken:

  • The overstated claim, in five places: the browser reads an object, not a file. Every page now says the vocabulary is shared, a schema declared for one host is accepted by the other, and a JSON file is the one spelling both read as it stands (JSON.parse in the browser).
  • The Command line page: exit 2 for a document fmt cannot settle, and the four-pass bound stated; parse's two additions over upstream (bindings-shape positions, a file label) restored; the --var x= → null row; the vocabulary crate named and linked.
  • Navigation and metadata: the theme's hand-written footer gains the page; site/config.yaml's llms description and the landing page's description name the command line.
  • CHANGELOG: the command-line host "will" read through the vocabulary crate → it does.
  • tests/readme.rs pins the README's MSRV sentence to CARGO_PKG_RUST_VERSION, so the drift that put 1.82 on the front page cannot recur silently.
  • The crate README leads with cargo install --path, as the outer pages do.

Rebuilt the site: the footer on every page links /docs/cli, llms.txt names the command line, all six doc slugs present.

Five things the pages did not say since 0.10.0.

The command-line host was invisible: no page and no README section named
`accent-proust fmt` or `validate`, and the docs index routed "a CLI" to the
Rust page. The site has a Command line page now, third in the navigation
after Rust and JavaScript; the three pages after it are renumbered so the
order reads that way, and their slugs are unchanged. The root README has a
section, and the landing page's browser feature is a browser-and-shell one.

The npm README and the JavaScript page did not record what the vocabulary
extraction changed: that one schema file now serves both hosts, that a
schema object is read key by key so a class instance works, that an
`undefined` variable is `null`, that a `type` list may not nest, and that a
property whose getter throws is refused rather than read as absent. The npm
README ships with the next release, so this was on the release path.

The architecture page's lead and description still said "one trait seam, two
responsibilities left outside" above a body that said three traits; its
workspace table listed one member of three. The root README's minimum Rust
version said 1.82 where the CI job runs 1.96.

The site builds with the new page, every /docs/* link on it resolves, and
the README example still runs.
Eight findings from the review of #50, and three it cut for room. The one
that matters most was a claim made in five places that the code
contradicts: "a schema file written for one host is read by the other
unchanged". The browser host reads an object, not a file. What is shared is
the vocabulary; a schema declared for one host is accepted by the other, and
a JSON file is the one spelling both read as it stands, the shell from disk
and the browser through `JSON.parse`. Every page says that now.

The Command line page omitted what the crate README knew: that `fmt` refuses
a document still changing after four passes, with exit 2; that `parse` adds
positions in the bindings' shape and a `file` label upstream does not
write; that `--var x=` is `null`; and it never named or linked the
vocabulary crate. The theme's hand-written footer had no entry for the page,
and the site's `llms` description and the landing page's `description` did
not name the command line. The changelog still said the command-line host
"will" read through the vocabulary crate; it does.

The README's minimum Rust version drifted once because nothing read it;
`tests/readme.rs` pins the sentence to the manifest's `rust-version` now.
The crate README leads with `cargo install --path`, which is what the outer
pages say.
@zoosky
zoosky merged commit edc6e02 into main Sep 12, 2026
13 checks passed
@zoosky
zoosky deleted the chore/docs-up-to-par branch September 12, 2026 17:03
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant