Add small clarifications to the documentation

* clarify that multi-line comments are not nestable

* note that pushing respects order and bold the statement on constancy

* note that linear domain operators work as in maths

documentation/dsl.md

@@ -169,7 +169,7 @@ On the other hand fractions like `9/8` are in the *linear* domain. The musically
 
 Relative FJS intervals can be especially confusing because they represent fractions but add like cents do. Our whole-tone stack becomes `M2 + M2` equal to `M3`. This is notationally expected even if obscured by the ordinal nature of traditional Western music notation. Remember that the perfect unison `P1` represents no change and `P1 + P1` is equal to `P1` i.e. 1st + 1st = 1st. Therefore 2nd + 2nd must be a (2+2-1)rd = 3rd.
 
-For the most part you cannot combine intervals across domains so `9/8 + M2` is not a valid operation. Use tildes (`~`) to always operate as if in the linear domain. E.g. `9/8 ~* M2` is a valid expression and evaluates to `81/64` while `9/8 *~ M2` evaluates to `M3`. The direction of the "wing" determines which domain and formatting to prefer.
+For the most part you cannot combine intervals across domains so `9/8 + M2` is not a valid operation. Use tildes (`~`) to always operate as if in the linear domain (meaning that, for example, `+` and `*` will always work as in maths). E.g. `9/8 ~* M2` is a valid expression and evaluates to `81/64` while `9/8 *~ M2` evaluates to `M3`. The direction of the "wing" determines which domain and formatting to prefer.
 
 Conversely the minus operator `-` represent divisions of the underlying values in the logarithmic domain and the usual kind of subraction in the linear domain e.g. `1.2e - 0.1e` equals `1.1e` owing to decimal ratios inhabiting the linear domain.
 
@@ -214,7 +214,7 @@ SonicWeave doesn't have percentages so the CSS color `hsl(120, 60%, 70%)` is spe
 
 ## Code comments
 
-Anything after two slashes (`//`) is ignored until the end of the line. Everything after a slash and an asterisk (`/*`) is ignored until a corresponding pair (`*/`) is encountered.
+Anything after two slashes (`//`) is ignored until the end of the line. Everything after a slash and an asterisk (`/*`) is ignored until a corresponding pair (`*/`) is encountered. (This means you cannot nest multi-line comments, as in C and JavaScript.)
 
 ```c
 1 = 432 Hz  // Good vibes only... Wait what are you doing?!

documentation/intermediate-dsl.md

@@ -15,15 +15,15 @@ Statements can be separated with semicolons `;` or newlines. After these instruc
 3/2
 2/1
 ```
-...the scale consists of `$ = [5/4, 3/2, 2/1]`.
+...the scale consists of `$ = [5/4, 3/2, 2/1]`. Pushing respects order; see the [Function calls section](#function-calls) for an example of how to sort by pitch.
 
 ### Unrolling
 Sub-scales are automatically unrolled onto the current scale.
 ```c
 4\12
 [7\12, 12\12]
 ```
-Results in the scale `$ = [4\12, 7\12, 12\12]`.
+Results in the scale `$ = [4\12, 7\12, 12\12]`. (Unrolling of a sub-scale essentially concatenates the interval list to that of the current scale (`$`). Compare with [record unrolling](#record-unrolling).)
 
 ### Coloring
 If an expression evaluates to a color it is applied to all the intervals in the scale that don't have a color yet.
@@ -146,7 +146,7 @@ let myComma = 81/80
 myComma = 250/243 // Valid: myComma now has the value 250/243
 ```
 
-Constancy is skin-deep. The elements of a `const` array may be re-assigned at will.
+**Constancy is shallow** (skin-deep): the elements of a `const` array may be re-assigned at will.
 
 ```c
 const myCommas = [81/80, 128/125];
@@ -191,7 +191,7 @@ let x, r
 // r has value [2, 3, 4]
 ```
 
-### Operator re-assignment
+### Reassignment operator
 Variables can be reassigned after declaration e.g. with `let i = 2` the statement `i += 3` sets `i` to `5`.
 
 ## Statements / line endings
@@ -228,7 +228,7 @@ Especially scalar multiplication and division can be hard to wrap your head arou
 
 This means that multiplication between linear and logarithmic quantities is the same as raising the underlying value of the logarithmic quantity to the underlying value of the linear quantity. Under the hood `P4 * 3` is actually doing `FJS( (4/3) ^ 3 )`.
 
-Similarly a logarithmic quantity divided by a linear quantity is equivalent to taking an nth root. `P5 / 2` is doing `FJS( (3/2) ^ (1/2) )` or taking advantage of the exotic *recipropower* operator and operator precedence of fractions in SonicWeave `FJS( 3/2 /^ 2)`
+Similarly a logarithmic quantity divided by a linear quantity is equivalent to taking an nth root. `P5 / 2` is doing `FJS( (3/2) ^ (1/2) )` or equivalently `FJS( 3/2 /^ 2)` or `FJS( 3/2 ^/ 2 )`. (The latter two examples take advantage of (two spellings of) the exotic *recipropower* operator.)
 
 Division of logarithmic quantities is a true mind-bender: `m7` is `2 * P4` so correspondingly `m7 / P4` evaluates to `2`, a linear scalar! The underlying operation is that of *logdivision* or log-in-the-base-of in conventional mathematical notation. You may verify for yourself that the logarithm of 16/9 in the base of 4/3 is indeed 2, written as `16/9 /_ 4/3` in SonicWeave. Looking at cents may offer a more natural perspective. It's hopefully less surprising that `1000. / 500.` is `2`.