Explorar o código

Documentation improvements

David Peter %!s(int64=2) %!d(string=hai) anos
pai
achega
b70f4997ba

+ 2 - 2
book/src/SUMMARY.md

@@ -23,9 +23,9 @@
 - [Basics](./basics.md)
   - [Number notation](./number-notation.md)
   - [Unit notation](./unit-notation.md)
-  - [Operators and their precedence](./operators.md)
+  - [Operations and precedence](./operations.md)
+  - [Constants](./constant-definitions.md)
   - [Unit conversions](./unit-conversions.md)
-  - [Constant definitions](./constant-definitions.md)
   - [Function definitions](./function-definitions.md)
   - [Conditionals](./conditionals.md)
   - [Printing, testing, debugging](./procedures.md)

+ 1 - 7
book/src/conditionals.md

@@ -8,14 +8,8 @@ if <cond> then <expr1> else <expr2>
 where `<cond>` is a condition that evaluates to a Boolean value, like
 `3 ft < 3 m`. The types of `<expr1>` and `<expr2>` need to match.
 
-## Example: step function
+For example, you can defined a simple step function using
 
 ```nbt
 fn step(x: Scalar) -> Scalar = if x < 0 then 0 else 1
 ```
-
-## Example: min function
-
-```nbt
-fn min<T>(x: T, y: T) -> T = if x < y then x else y
-```

+ 1 - 1
book/src/constant-definitions.md

@@ -1,4 +1,4 @@
-# Constant definitions
+# Constants
 
 New constants can be introduced with the `let` keyword:
 ```nbt

+ 34 - 0
book/src/operations.md

@@ -0,0 +1,34 @@
+# Operations and precedence
+
+Numbat operators and other language constructs, ordered by precedence form *high* to *low*:
+
+| Operation / operator      | Syntax                               |
+| ------------------------- | ------------------------------------ |
+| square, cube, ...         | `x²`, `x³`, `x⁻¹`, ...               |
+| factorial                 | `x!`                                 |
+| exponentiation            | `x^y`, `x**y`                        |
+| multiplication (implicit) | `x y` (*whitespace*)                 |
+| unary negation            | `-x`                                 |
+| division                  | `x per y`                            |
+| division                  | `x / y`, `x ÷ y`                     |
+| multiplication (explicit) | `x * y`, `x · y`, `x × y`            |
+| subtraction               | `x - y`                              |
+| addition                  | `x + y`                              |
+| comparisons               | `x < y`, `x <= y`, `x ≤ y`, … `x == y`, `x != y` |
+| unit conversion           | `x -> y`, `x → y`, `x ➞ y`, `x to y` |
+| conditionals              | `if x then y else z`                 |
+| reverse function call     | `x // f`                             |
+
+Note that *implicit* multiplication has a higher precedence than division, i.e. `50 cm / 2 m` will be parsed as `50 cm / (2 m)`.
+
+Also, note that `per`-division has a higher precedence than `/`-division. This means `1 / meter  per second` will be parsed as `1 / (meter per second)`.
+
+If in doubt, you can always look at the pretty-printing output (second line in the snippet below)
+to make sure that your input was parsed correctly:
+``` numbat
+>>> 1 / meter per second
+
+  1 / (meter / second)
+
+    = 1 s/m
+```

+ 0 - 31
book/src/operators.md

@@ -1,31 +0,0 @@
-# Operators and their precedence
-
-  Operators (ordered by precedence: high to low)
-
-| Operator                  | Syntax               |
-| ------------------------- | -------------------- |
-| square, cube, ...         | `²`, `³`, `⁻¹`, ...  |
-| factorial                 | `!`                  |
-| exponentiation            | `^`, `**`            |
-| multiplication (implicit) | *whitespace*         |
-| division                  | `per`                |
-| division                  | `/`, `÷`             |
-| multiplication (explicit) | `*`, `·`, `×`        |
-| subtraction               | `-`                  |
-| addition                  | `+`                  |
-| unit conversion           | `->`, `→`, `➞`, `to` |
-| reverse function call     | `//`                 |
-
-Note that *implicit* multiplication has a higher precedence than division, i.e. `50 cm / 2 m` will be parsed as `50 cm / (2 m)`.
-
-Also, note that `per`-division has a higher precedence than `/`-division. This means `1 / meter  per second` will be parsed as `1 / (meter per second)`.
-
-If in doubt, you can always look at the pretty-printing output (second line in the snippet below)
-to make sure that your input was parsed correctly:
-``` numbat
->>> 1 / meter per second
-
-  1 / (meter / second)
-
-    = 1 s/m
-```

+ 7 - 6
book/src/tutorial.md

@@ -18,9 +18,10 @@ let occurence = 0.0117%
 let molar_mass = 40 g / mol
 ```
 
-New constants are introduced with the `let` keyword. We define these physical quantities
-with their respective physical units (`years`, `percent`, `g / mol`) in order to profit from
-Numbats unit-safety and unit-conversion features later on.
+New constants are [introduced with the `let` keyword](./constant-definitions.md). We
+define these physical quantities with their respective physical units (`years`,
+`percent`, `g / mol`) in order to profit from Numbats unit-safety and unit-conversion
+features later on.
 
 Our first goal is to compute the radioactivity of natural potassium. Instead of dealing with the
 half-life, we want to know the decay rate. When entering the following computation, you can try
@@ -49,7 +50,7 @@ calculation at the units-level, Numbat would detect that and show an error.
 Unit safety is a powerful concept not just because you can eliminate an entire category
 of errors, but also because it makes your computations more readable.
 
-We are interested in the radioactivity of bananas, so we first introduce a new (base) unit
+We are interested in the radioactivity of bananas, so we first [introduce a new (base) unit](./unit-definitions.md):
 
 ``` numbat
 unit banana
@@ -79,10 +80,10 @@ This also works with custom units since Numbat adds new physical dimensions (typ
 let power_per_banana: Power / Banana = radioactivity_banana * energy_per_decay
 ```
 
-You'll also notice that types can be combined via mathematical operators such as `/` in this example.
+You'll also notice that types can be combined via [mathematical operators](./operations.md) such as `/` in this example.
 
 How many bananas we need to power a household is going to depend on the average power consumption
-of that household. So we are defining a simple function
+of that household. So we are [defining a simple function](./function-definitions.md)
 
 ```numbat
 fn household_power(annual_consumption: Energy) -> Power = annual_consumption / year

+ 2 - 2
book/src/unit-conversions.md

@@ -16,8 +16,8 @@ expression on the right hand side — but only the unit part will be extracted.
   = 0.12 m²·km
 
 # convert x1 to the same unit as x2:
-> x1 = 50 km / h
-> x2 = 3 m/s -> x1
+> let x1 = 50 km / h
+> let x2 = 3 m/s -> x1
 
   x2 = 10.8 km/h
 ```

+ 1 - 1
book/src/unit-notation.md

@@ -9,7 +9,7 @@ All SI-accepted units support [metric prefixes](https://en.wikipedia.org/wiki/Me
 and — where sensible — units allow for [binary prefixes](https://en.wikipedia.org/wiki/Binary_prefix) (`MiB`, `GiB`, ... or `mebibyte`, `gibibyte`, ...). Note
 that the short-form prefixes can only be used with the short version of the unit, and vice versa (that is: `kmeter` and `kilom` are *not* allowed, only `km` and `kilometer`).
 
-Units can be combined using [mathematical operations](./operators.md) such as multiplication, division and exponentiation: `kg * m/s^2`, `km/h`, `m²`, `meter per second`.
+Units can be combined using [mathematical operations](./operations.md) such as multiplication, division and exponentiation: `kg * m/s^2`, `km/h`, `m²`, `meter per second`.
 
 The following snippet shows various styles of entering units:
 ```nbt