fix(language): a composition refusal calls a library file a fragment rather than a template

[FBumann]

Prompt: "Templates is not correct I think / It's a showcase / Or a library" — and, on the leftover in the refusal, "Do it"

Note

The following content was generated by AI.

What this changes

template: is the key a macro's body is written under, so the word meant two things. The composition messages and docstrings now say fragment, and the pages that described a library the same way follow. One word, swept.

fragments 'gas' and 'coal' both declare the parameter 'Generator_p_nom'. Two of the same
kind of thing are two rows of a dimension rather than two fragments: merge the fragment
once, and let the data carry both. Different math under one spelling is a rename — call
one of them something else.

Where it went

File	What changed
src/math_spec/composition.py	the collision refusal, the module docstring, merge's docstring and two others
src/math_spec/advice.py	the given note, and the docstring above it
docs/about/limits.md	the composition section, and the given_variables: line under the third kind
docs/howto/compose.md	the opening, the section heading, the given-disagreement section, the quoted refusal
docs/reference/language/declarations.md	the given_variables opening
docs/examples/index.md	the library's catalogue entry
tests/test_given.py	the module docstring and one fixture comment
tests/test_library_example.py	test_a_component_file_reads_the_surface_and_introduces_no_flow, test_the_balance_is_written_once_however_many_fragments_are_merged

macros:' own template: is untouched, in model.py, expansion.py, resolution.py, expressions.md and errors.md. That is the word's one remaining meaning.

Verified

Same environment as the rest of the stack: python 3.13, dependencies by pip, not the pinned solve.

• pytest -q — 1368 passed, 6 skipped, the count unchanged: two tests were renamed, none added or removed.
• No test pinned the changed wording. test_a_name_two_fragments_declare_is_refused pins both fragment names and two rows of a dimension, which is the claim rather than the prose, and test_advice.py pins binds it to the model. Both still pass.
• ruff format --check ., ruff check, typos, prettier clean. mkdocs build --strict builds, after the usual local drop of the CPython inventory this proxy 403s.
• tools.gallery --check 13 pages current, tools.home_math --check 2 current — no generated page carried the word.
• pyrefly reports the same 11 errors with and without this diff, all from missing type stubs in this environment.

Not run: reuse, zizmor, taplo, and compile-tex — no model file changed.

Deliberately not done

• No test on the message text. The refusal tests pin what the message claims, not how it is worded, and a test that restates the sentence would fail on every improvement to it.
• No check that the refusals quoted in howto/compose.md are what the code prints. Six messages are fenced on that page and read by nothing; each one was produced by running its case, this one included, but nothing holds them there. That is a gap worth its own issue rather than this diff.

Stack: on #510 → #508 → #507 → #505.

🤖 Generated with Claude Code

https://claude.ai/code/session_01CA5v9XJvgYViUHP7hSiKPU

---

Generated by Claude Code

[read-the-docs-community]

Documentation build overview

📚 math-spec | 🛠️ Build #34608059 | 📁 Comparing 296119d against latest (479b11b)

  🔍 Preview build  

21 files changed · + 7 added · ± 14 modified

+ Added

• examples/library/index.html
• howto/compose/index.html
• examples/library/composed/index.html
• examples/library/generator/index.html
• examples/library/load/index.html
• examples/library/surface/index.html
• reference/math_spec/composition/index.html

± Modified

• examples/index.html
• about/limits/index.html
• reference/language/index.html
• reference/language/declarations/index.html
• reference/language/file/index.html
• reference/language/reading/index.html
• reference/math_spec/advice/index.html
• reference/math_spec/errors/index.html
• reference/math_spec/lowering/index.html
• reference/math_spec/model/index.html
• and 4 more...

[FBumann]

Decided with @FabianHofmann:
Move all about given into a top level key.

given:
   variables:
      var1:...