feat!: a spec written back out and its typeset document follow one section order

CHANGELOG.md

@@ -12,6 +12,7 @@ it releases that version ([RELEASING.md](https://github.com/energy-models/mathsp
 
 ## Upcoming version
 
+- feat!: a spec written back out and its typeset document follow one section order ([#848](https://github.com/energy-models/mathspec/pull/848))
 - docs(pypsa): a delayed port under uneven snapshot weights is refused, where PyPSA counts weighted time ([#852](https://github.com/energy-models/mathspec/pull/852))
 - docs: limits.md names that a count compares only against a whole-number literal ([#851](https://github.com/energy-models/mathspec/pull/851))
 - docs: every spec in the docs and examples opens with its given block ([#813](https://github.com/energy-models/mathspec/pull/813))

docs/examples/commitment.md

@@ -167,14 +167,6 @@ $`\mathrm{pos}(t)`$ denotes where index $`t`$ sits along its dimension's own ord
 \mathit{dispatch}_{t,g} - \mathit{dispatch}_{t \boxminus_{0} 1,g} \le \mathrm{ramp\_limit}_{g} \cdot \mathit{previous\_status}_{t,g} + \mathrm{start\_up\_limit}_{g} \cdot \left( 1 - \mathit{previous\_status}_{t,g} \right) \qquad \forall\, t \in \mathcal{T},\ g \in \mathcal{G}
 ```
 
-#### Definitions
-
-**`previous_status`**
-
-```math
-\mathit{previous\_status}_{t,g} = \begin{cases} 1 & \text{if } \neg \mathrm{committable}_{g} \\ \mathrm{status}^{\mathrm{initial}}_{g} & \text{if } \mathrm{committable}_{g} \wedge \mathrm{pos}(t) = 0 \\ \mathit{status}_{t - 1,g} & \text{otherwise} \end{cases} \qquad \forall\, t \in \mathcal{T},\ g \in \mathcal{G}
-```
-
 #### Variable domains
 
 **`dispatch`**
@@ -189,6 +181,14 @@ $`\mathrm{pos}(t)`$ denotes where index $`t`$ sits along its dimension's own ord
 \mathit{status}_{t,g} \in \{0, 1\} \qquad \forall\, t \in \mathcal{T},\ g \in \mathcal{G}
 ```
 
+#### Definitions
+
+**`previous_status`**
+
+```math
+\mathit{previous\_status}_{t,g} = \begin{cases} 1 & \text{if } \neg \mathrm{committable}_{g} \\ \mathrm{status}^{\mathrm{initial}}_{g} & \text{if } \mathrm{committable}_{g} \wedge \mathrm{pos}(t) = 0 \\ \mathit{status}_{t - 1,g} & \text{otherwise} \end{cases} \qquad \forall\, t \in \mathcal{T},\ g \in \mathcal{G}
+```
+
 #### Assumptions
 
 **`output_floor_fits_under_the_cap`**

docs/examples/library/composed.md

@@ -75,6 +75,7 @@ variables:
     domain: continuous
     missing: absent
     description: '`Generator-p` — what a generator produces in a snapshot'
+objective: {sense: minimize, expression: total_cost}
 constraints:
   Bus_nodal_balance:
     dims: [snapshot, bus]
@@ -90,7 +91,6 @@ constraints:
     expression: at(Port_p, by=Load_port[port]) == -Load_p_set
     description: 'what a load takes is what its port withdraws. No PyPSA row stands for this: PyPSA writes
       the load into the balance instead'
-objective: {sense: minimize, expression: total_cost}
 expressions:
   Generator_cost: sum(Generator_p * Generator_marginal_cost)
   total_cost:
@@ -159,32 +159,32 @@ expressions:
     f_{t,\mathrm{Load\_port}(d)} = -\mathrm{load}_{t,d} \qquad \forall\, t \in \mathcal{T},\ d \in \mathcal{D}
     ```
 
-    #### Definitions
+    #### Variable domains
 
-    **`Generator_cost`**
+    **`Port_p`**
 
     ```math
-    \mathit{Generator\_cost} = \sum_{t \in \mathcal{T},\ g \in \mathcal{G}} p_{t,g} \cdot \mathrm{c}_{g}
+    f_{t,j} \in \mathbb{R} \qquad \forall\, t \in \mathcal{T},\ j \in \mathcal{J}
     ```
 
-    **`total_cost`**
+    **`Generator_p`**
 
     ```math
-    \mathit{total\_cost} = \mathit{Generator\_cost}
+    0 \le p_{t,g} \le \mathrm{p}^{\mathrm{nom}}_{g} \qquad \forall\, t \in \mathcal{T},\ g \in \mathcal{G}
     ```
 
-    #### Variable domains
+    #### Definitions
 
-    **`Port_p`**
+    **`Generator_cost`**
 
     ```math
-    f_{t,j} \in \mathbb{R} \qquad \forall\, t \in \mathcal{T},\ j \in \mathcal{J}
+    \mathit{Generator\_cost} = \sum_{t \in \mathcal{T},\ g \in \mathcal{G}} p_{t,g} \cdot \mathrm{c}_{g}
     ```
 
-    **`Generator_p`**
+    **`total_cost`**
 
     ```math
-    0 \le p_{t,g} \le \mathrm{p}^{\mathrm{nom}}_{g} \qquad \forall\, t \in \mathcal{T},\ g \in \mathcal{G}
+    \mathit{total\_cost} = \mathit{Generator\_cost}
     ```
 
 === "With commitment"
@@ -281,37 +281,37 @@ expressions:
     p_{t,g} \ge \underline{\mathrm{p}}_{g} \cdot \mathrm{p}^{\mathrm{nom}}_{g} \cdot u_{t,g} \qquad \forall\, t \in \mathcal{T},\ g \in \mathcal{G}
     ```
 
-    #### Definitions
+    #### Variable domains
 
-    **`Generator_cost`**
+    **`Port_p`**
 
     ```math
-    \mathit{Generator\_cost} = \sum_{t \in \mathcal{T},\ g \in \mathcal{G}} p_{t,g} \cdot \mathrm{c}_{g}
+    f_{t,j} \in \mathbb{R} \qquad \forall\, t \in \mathcal{T},\ j \in \mathcal{J}
     ```
 
-    **`total_cost`**
+    **`Generator_p`**
 
     ```math
-    \mathit{total\_cost} = \mathit{Generator\_cost}
+    p_{t,g} \ge 0 \qquad \forall\, t \in \mathcal{T},\ g \in \mathcal{G}
     ```
 
-    #### Variable domains
-
-    **`Port_p`**
+    **`Generator_status`**
 
     ```math
-    f_{t,j} \in \mathbb{R} \qquad \forall\, t \in \mathcal{T},\ j \in \mathcal{J}
+    u_{t,g} \in \{0, 1\} \qquad \forall\, t \in \mathcal{T},\ g \in \mathcal{G}
     ```
 
-    **`Generator_p`**
+    #### Definitions
+
+    **`Generator_cost`**
 
     ```math
-    p_{t,g} \ge 0 \qquad \forall\, t \in \mathcal{T},\ g \in \mathcal{G}
+    \mathit{Generator\_cost} = \sum_{t \in \mathcal{T},\ g \in \mathcal{G}} p_{t,g} \cdot \mathrm{c}_{g}
     ```
 
-    **`Generator_status`**
+    **`total_cost`**
 
     ```math
-    u_{t,g} \in \{0, 1\} \qquad \forall\, t \in \mathcal{T},\ g \in \mathcal{G}
+    \mathit{total\_cost} = \mathit{Generator\_cost}
     ```
 <!-- gallery:end -->

docs/examples/library/generator.md

@@ -68,6 +68,13 @@ expressions:
 
 PyPSA's `Generator`, wired to a port rather than straight to a bus, and cut to what a dispatch spec needs: a fixed build, no availability profile, no ramp limits.
 
+#### Given
+
+| Symbol | Meaning |
+|---|---|
+| $`f`$ | `Port_p` over $`\mathcal{T} \times \mathcal{J}`$ — the surface introduces this flow, and this file pins it at its own ports |
+| $`\mathit{total\_cost}`$ | `total_cost` (scalar), an expression this file adds `Generator_cost` to |
+
 #### Sets
 
 | Symbol | Meaning |
@@ -89,13 +96,6 @@ PyPSA's `Generator`, wired to a port rather than straight to a bus, and cut to w
 |---|---|
 | $`p`$ | `Generator_p` over $`\mathcal{T} \times \mathcal{G}`$ — `Generator-p` — what a generator produces in a snapshot |
 
-#### Given
-
-| Symbol | Meaning |
-|---|---|
-| $`f`$ | `Port_p` over $`\mathcal{T} \times \mathcal{J}`$ — the surface introduces this flow, and this file pins it at its own ports |
-| $`\mathit{total\_cost}`$ | `total_cost` (scalar), an expression this file adds `Generator_cost` to |
-
 #### Definitions
 
 | Symbol | Meaning |
@@ -110,19 +110,19 @@ PyPSA's `Generator`, wired to a port rather than straight to a bus, and cut to w
 f_{t,\mathrm{Generator\_port}(g)} = p_{t,g} \qquad \forall\, t \in \mathcal{T},\ g \in \mathcal{G}
 ```
 
-#### Definitions
+#### Variable domains
 
-**`Generator_cost`**
+**`Generator_p`**
 
 ```math
-\mathit{Generator\_cost} = \sum_{t \in \mathcal{T},\ g \in \mathcal{G}} p_{t,g} \cdot \mathrm{c}_{g}
+0 \le p_{t,g} \le \mathrm{p}^{\mathrm{nom}}_{g} \qquad \forall\, t \in \mathcal{T},\ g \in \mathcal{G}
 ```
 
-#### Variable domains
+#### Definitions
 
-**`Generator_p`**
+**`Generator_cost`**
 
 ```math
-0 \le p_{t,g} \le \mathrm{p}^{\mathrm{nom}}_{g} \qquad \forall\, t \in \mathcal{T},\ g \in \mathcal{G}
+\mathit{Generator\_cost} = \sum_{t \in \mathcal{T},\ g \in \mathcal{G}} p_{t,g} \cdot \mathrm{c}_{g}
 ```
 <!-- gallery:end -->

docs/examples/library/load.md

@@ -39,6 +39,12 @@ constraints:
 
 PyPSA's `Load`, wired to a port rather than straight to a bus. What it takes is data, so it decides nothing.
 
+#### Given
+
+| Symbol | Meaning |
+|---|---|
+| $`f`$ | `Port_p` over $`\mathcal{T} \times \mathcal{J}`$ — the surface introduces this flow, and this file pins it at its own ports |
+
 #### Sets
 
 | Symbol | Meaning |
@@ -53,12 +59,6 @@ PyPSA's `Load`, wired to a port rather than straight to a bus. What it takes is
 |---|---|
 | $`\mathrm{load}`$ | `Load_p_set` over $`\mathcal{T} \times \mathcal{D}`$ — `Load-p_set` — what a load takes in a snapshot |
 
-#### Given
-
-| Symbol | Meaning |
-|---|---|
-| $`f`$ | `Port_p` over $`\mathcal{T} \times \mathcal{J}`$ — the surface introduces this flow, and this file pins it at its own ports |
-
 #### Subject to
 
 **`Load_withdrawal`**

docs/examples/library/surface.md

@@ -55,6 +55,12 @@ objective:
 
 The coupling surface every component in this library is written against: one flow per port, one balance per bus, and one cost to minimise. A component is wired to a port, the port to a bus, and the balance names no component class. A flow is positive where the port injects into its bus. A component that costs something adds its cost to `total_cost`.
 
+#### Given
+
+| Symbol | Meaning |
+|---|---|
+| $`\mathit{total\_cost}`$ | `total_cost` (scalar), an expression another file defines — what running the system costs |
+
 #### Sets
 
 | Symbol | Meaning |
@@ -69,12 +75,6 @@ The coupling surface every component in this library is written against: one flo
 |---|---|
 | $`f`$ | `Port_p` over $`\mathcal{T} \times \mathcal{J}`$ — what a port puts into its bus in a snapshot, negative for a withdrawal |
 
-#### Given
-
-| Symbol | Meaning |
-|---|---|
-| $`\mathit{total\_cost}`$ | `total_cost` (scalar), an expression another file defines — what running the system costs |
-
 #### Objective
 
 ```math