docs(language): a walk through a relation is stated once, in the three verbs the loader uses

[FBumann]

Prompt: "Lets bring this focused definition into mathspec docs. I think they are too confusing and bloated atm" — "Scan the rest of this docs page. I think there are many places where things arent as clear as they should be"

Note

The following content was generated by AI.

What this changes

The relations reference states a walk once, in the three verbs the loader uses, the operators page links to it rather than restating it, and the rest of the page says each rule in things before abstractions.

A walk consumes one or more columns of a relation, produces one or more, and joins on every other key column. The operand carries each joined dimension. The result keeps it, and keeps every dimension the relation does not name.

sum consumes key columns and produces value columns. at consumes value columns and produces the key.

over= names the column consumed and into= the column produced. Name a column only where the relation offers two.

What moved where

• Walks is a new section under relations, opening with the definition above. The example spells over=zone on at, and each constraint's comment names the three roles and the frame it moves between. The typeset form of the at line is shown, with the joined period as the second subscript. The refusals quoted are the three that teach the rule: at on a bare relation, a sum that consumes no key column, and an operand missing a joined dimension.
• Three copies became one. The walk-needs table under "The key is the claim", the nine-bullet rules list under "A walk names its ends", and the partition paragraph said the same things in different words. Partitions have a short section of their own. The where bullet is a link to the where-strings table on the expressions page, which already owns those forms.
• The field table is corrected. It still listed over: as the required key and had a row saying into: is not a field. It now lists columns:.
• The rest of the page is rewritten sentence by sentence where a sentence packed several claims, described the engine's side rather than the reader's, or argued for a settled decision: the bind-check paragraph, the cardinality lead-in that called the key "the side that is one", the list and masked-sum bullets, the self-map paragraph, the data-supply section, and the closing table's row on selected-on label sets. Two pieces of rationale leave the page, the comparison to a 0/1 membership parameter and the history of the nodal balance through two relations, and one sentence that repeated rule 1 of "Where the members come from" is cut.
• On operators.md the sum(by=) and at paragraphs that restated the walk rules are cut to one sentence each plus a link. The null-value and variable facts for at stay.

Sentence measure on dimensions.md, from the docs-writing script:

	sentences	median words	over 25
before	85	22	30
after	104	16	13

Verified

Pixi is blocked by the proxy in this session, so every gate ran from a uv environment on Python 3.12.

• prettier --check and typos clean on both pages.
• mkdocs build --strict clean, with the Python object inventory dropped from a temporary config copy, since docs.python.org is blocked here too.
• pytest tests/test_docs.py tests/test_reading_page.py: 34 passed.
• The example YAML under Walks loads through to_spec, and its typeset line is pasted from to_markdown.
• The rewritten self-map claim is checked against the loader: comparing rep_of.rep to rep_of.snapshot, in either order, and rep_of == snapshot are all refused.

Not run: reuse lint, the full suite, and compile-tex, which no examples/ change needs.

Why

The thread on #437 showed a reader could not tell from at(price, by=zone_of, into=generator) why the result carries period. The page held the answer in three places, none of them where the example was. Now it is one sentence above the example, and the example's comments say it again for each row.

Deliberately not done: the page describes today's rule, where at names the key column it produces when the key has two. Inferring that column from the operand is a resolution change, and a PR of its own.

🤖 Generated with Claude Code

https://claude.ai/code/session_019vg9UDLgdaFiu9gtbqAj7P

[read-the-docs-community]

Documentation build overview

📚 math-spec | 🛠️ Build #34587102 | 📁 Comparing f652f36 against latest (33a22fa)

  🔍 Preview build  

2 files changed

± reference/language/dimensions/index.html
± reference/language/operators/index.html