Apply example suggestions from code review

Co-authored-by: David Peter <[email protected]>

book/src/list-functions-lists.md

@@ -309,18 +309,14 @@ fn filter<A>(p: Fn[(A) -> Bool], xs: List<A>) -> List<A>
 <details>
 <summary>Examples</summary>
 
-* Filter all elements greater than \\( 1 \\).
+* <a href="https://numbat.dev/?q=filter%28is%5Ffinite%2C%20%5B0%2C%201e10%2C%20NaN%2C%20%2Dinf%5D%29"><i class="fa fa-play"></i> Run this example</a>
 
-  <a href="https://numbat.dev/?q=fn%20filter%5Ffn%28x%29%20%3D%20x%20%3E%201%0Afilter%28filter%5Ffn%2C%20%5B3%2C%202%2C%201%2C%200%5D%29"><i class="fa fa-play"></i> Run this example</a>
   ```nbt
-    >>> fn filter_fn(x) = x > 1
-    filter(filter_fn, [3, 2, 1, 0])
+    >>> filter(is_finite, [0, 1e10, NaN, -inf])
     
-      fn filter_fn(x: Scalar) -> Bool = x > 1
+      filter(is_finite, [0, 10_000_000_000, NaN, -inf])
     
-      filter(filter_fn, [3, 2, 1, 0])
-    
-        = [3, 2]    [List<Scalar>]
+        = [0, 10_000_000_000]    [List<Scalar>]
     
   ```
 </details>
@@ -360,14 +356,14 @@ fn sort_by_key<A, D: Dim>(key: Fn[(A) -> D], xs: List<A>) -> List<A>
 
 * Sort by last digit.
 
-  <a href="https://numbat.dev/?q=fn%20map%5Ffn%28x%29%20%3D%20mod%28x%2C%2010%29%0Asort%5Fby%5Fkey%28map%5Ffn%2C%20%5B701%2C%20313%2C%209999%2C%204%5D%29"><i class="fa fa-play"></i> Run this example</a>
+  <a href="https://numbat.dev/?q=fn%20last%5Fdigit%28x%29%20%3D%20mod%28x%2C%2010%29%0Asort%5Fby%5Fkey%28last%5Fdigit%2C%20%5B701%2C%20313%2C%209999%2C%204%5D%29"><i class="fa fa-play"></i> Run this example</a>
   ```nbt
-    >>> fn map_fn(x) = mod(x, 10)
-    sort_by_key(map_fn, [701, 313, 9999, 4])
+    >>> fn last_digit(x) = mod(x, 10)
+    sort_by_key(last_digit, [701, 313, 9999, 4])
     
-      fn map_fn(x: Scalar) -> Scalar = mod(x, 10)
+      fn last_digit(x: Scalar) -> Scalar = mod(x, 10)
     
-      sort_by_key(map_fn, [701, 313, 9999, 4])
+      sort_by_key(last_digit, [701, 313, 9999, 4])
     
         = [701, 313, 4, 9999]    [List<Scalar>]
     
@@ -428,14 +424,14 @@ fn sum<D: Dim>(xs: List<D>) -> D
 <details>
 <summary>Examples</summary>
 
-* <a href="https://numbat.dev/?q=sum%28%5B3%2C%202%2C%201%5D%29"><i class="fa fa-play"></i> Run this example</a>
+* <a href="https://numbat.dev/?q=sum%28%5B3%20m%2C%20200%20cm%2C%201000%20mm%5D%29"><i class="fa fa-play"></i> Run this example</a>
 
   ```nbt
-    >>> sum([3, 2, 1])
+    >>> sum([3 m, 200 cm, 1000 mm])
     
-      sum([3, 2, 1])
+      sum([3 metre, 200 centimetre, 1000 millimetre])
     
-        = 6
+        = 6 m    [Length]
     
   ```
 </details>

book/src/list-functions-math.md

@@ -267,7 +267,7 @@ fn ceil(x: Scalar) -> Scalar
 </details>
 
 ### `ceil_in` (Ceil function)
-Returns the smallest integer multuple of `base` greater than or equal to `value`.
+Returns the smallest integer multiple of `base` greater than or equal to `value`.
 
 ```nbt
 fn ceil_in<D: Dim>(base: D, value: D) -> D
@@ -859,10 +859,10 @@ fn gcd(a: Scalar, b: Scalar) -> Scalar
 <details>
 <summary>Examples</summary>
 
-* <a href="https://numbat.dev/?q=gcd%2860%2C42%29"><i class="fa fa-play"></i> Run this example</a>
+* <a href="https://numbat.dev/?q=gcd%2860%2C%2042%29"><i class="fa fa-play"></i> Run this example</a>
 
   ```nbt
-    >>> gcd(60,42)
+    >>> gcd(60, 42)
     
       gcd(60, 42)
     
@@ -909,11 +909,11 @@ fn diff<X: Dim, Y: Dim>(f: Fn[(X) -> Y], x: X) -> Y / X
 <details>
 <summary>Examples</summary>
 
-* Compute the drivative of \\( f(x) = x² -x -1 \\) at \\( x=1 \\).
+* Compute the derivative of \\( f(x) = x² -x -1 \\) at \\( x=1 \\).
 
-  <a href="https://numbat.dev/?q=use%20numerics%3A%3Adiff%0Afn%20polynomial%28x%29%20%3D%20x%C2%B2%20%2Dx%20%2D1%0Adiff%28polynomial%2C%201%29"><i class="fa fa-play"></i> Run this example</a>
+  <a href="https://numbat.dev/?q=use%20numerics%3A%3Adiff%0Afn%20polynomial%28x%29%20%3D%20x%C2%B2%20%2D%20x%20%2D%201%0Adiff%28polynomial%2C%201%29"><i class="fa fa-play"></i> Run this example</a>
   ```nbt
-    >>> fn polynomial(x) = x² -x -1
+    >>> fn polynomial(x) = x² - x - 1
     diff(polynomial, 1)
     
       fn polynomial(x: Scalar) -> Scalar = (x² - x) - 1
@@ -922,6 +922,23 @@ fn diff<X: Dim, Y: Dim>(f: Fn[(X) -> Y], x: X) -> Y / X
     
         = 1.0
     
+  ```
+* Compute the free fall velocity after \\( t=2 s \\).
+
+  <a href="https://numbat.dev/?q=use%20numerics%3A%3Adiff%0Afn%20distance%28t%29%20%3D%200%2E5%20g0%20t%C2%B2%0Afn%20velocity%28t%29%20%3D%20diff%28distance%2C%20t%29%0Avelocity%282%20s%29"><i class="fa fa-play"></i> Run this example</a>
+  ```nbt
+    >>> fn distance(t) = 0.5 g0 t²
+    fn velocity(t) = diff(distance, t)
+    velocity(2 s)
+    
+      fn distance<A: Dim>(t: A) -> A² × Length / Time² = 0.5 g0 × t²
+    
+      fn velocity<A: Dim>(t: A) -> A × Length / Time² = diff(distance, t)
+    
+      velocity(2 second)
+    
+        = 19.6133 m/s    [Velocity]
+    
   ```
 </details>
 
@@ -1023,14 +1040,14 @@ fn hypot2<T: Dim>(x: T, y: T) -> T
 <details>
 <summary>Examples</summary>
 
-* <a href="https://numbat.dev/?q=hypot2%283%2C%204%29"><i class="fa fa-play"></i> Run this example</a>
+* <a href="https://numbat.dev/?q=hypot2%283%20m%2C%204%20m%29"><i class="fa fa-play"></i> Run this example</a>
 
   ```nbt
-    >>> hypot2(3, 4)
+    >>> hypot2(3 m, 4 m)
     
-      hypot2(3, 4)
+      hypot2(3 metre, 4 metre)
     
-        = 5
+        = 5 m    [Length]
     
   ```
 </details>
@@ -1045,14 +1062,14 @@ fn hypot3<T: Dim>(x: T, y: T, z: T) -> T
 <details>
 <summary>Examples</summary>
 
-* <a href="https://numbat.dev/?q=hypot3%284%2C%201%2C%204%29"><i class="fa fa-play"></i> Run this example</a>
+* <a href="https://numbat.dev/?q=hypot3%288%2C%209%2C%2012%29"><i class="fa fa-play"></i> Run this example</a>
 
   ```nbt
-    >>> hypot3(4, 1, 4)
+    >>> hypot3(8, 9, 12)
     
-      hypot3(4, 1, 4)
+      hypot3(8, 9, 12)
     
-        = 5.74456
+        = 17
     
   ```
 </details>

book/src/list-functions-other.md

@@ -216,10 +216,10 @@ fn DMS(alpha: Angle) -> String
 <details>
 <summary>Examples</summary>
 
-* <a href="https://numbat.dev/?q=DMS%2846%2E5858%C2%B0%29"><i class="fa fa-play"></i> Run this example</a>
+* <a href="https://numbat.dev/?q=46%2E5858%C2%B0%20%2D%3E%20DMS"><i class="fa fa-play"></i> Run this example</a>
 
   ```nbt
-    >>> DMS(46.5858°)
+    >>> 46.5858° -> DMS
     
       DMS(46.5858 degree)
     
@@ -239,10 +239,10 @@ fn DM(alpha: Angle) -> String
 <details>
 <summary>Examples</summary>
 
-* <a href="https://numbat.dev/?q=DM%2846%2E5858%C2%B0%29"><i class="fa fa-play"></i> Run this example</a>
+* <a href="https://numbat.dev/?q=46%2E5858%C2%B0%20%2D%3E%20DM"><i class="fa fa-play"></i> Run this example</a>
 
   ```nbt
-    >>> DM(46.5858°)
+    >>> 46.5858° -> DM
     
       DM(46.5858 degree)
     
@@ -262,10 +262,10 @@ fn feet_and_inches(length: Length) -> String
 <details>
 <summary>Examples</summary>
 
-* <a href="https://numbat.dev/?q=feet%5Fand%5Finches%28180cm%29"><i class="fa fa-play"></i> Run this example</a>
+* <a href="https://numbat.dev/?q=180%20cm%20%2D%3E%20feet%5Fand%5Finches"><i class="fa fa-play"></i> Run this example</a>
 
   ```nbt
-    >>> feet_and_inches(180cm)
+    >>> 180 cm -> feet_and_inches
     
       feet_and_inches(180 centimetre)
     
@@ -285,10 +285,10 @@ fn pounds_and_ounces(mass: Mass) -> String
 <details>
 <summary>Examples</summary>
 
-* <a href="https://numbat.dev/?q=pounds%5Fand%5Founces%281kg%29"><i class="fa fa-play"></i> Run this example</a>
+* <a href="https://numbat.dev/?q=1%20kg%20%2D%3E%20pounds%5Fand%5Founces"><i class="fa fa-play"></i> Run this example</a>
 
   ```nbt
-    >>> pounds_and_ounces(1kg)
+    >>> 1 kg -> pounds_and_ounces
     
       pounds_and_ounces(1 kilogram)
     
@@ -312,7 +312,7 @@ fn from_celsius(t_celsius: Scalar) -> Temperature
 <details>
 <summary>Examples</summary>
 
-* \\( 300 °C \\) in Kelvin.
+* 300 °C in Kelvin.
 
   <a href="https://numbat.dev/?q=from%5Fcelsius%28300%29"><i class="fa fa-play"></i> Run this example</a>
   ```nbt
@@ -336,7 +336,7 @@ fn celsius(t_kelvin: Temperature) -> Scalar
 <details>
 <summary>Examples</summary>
 
-* \\( 300K \\) in degree Celsius.
+* 300 K in degree Celsius.
 
   <a href="https://numbat.dev/?q=300K%20%2D%3E%20celsius"><i class="fa fa-play"></i> Run this example</a>
   ```nbt
@@ -360,7 +360,7 @@ fn from_fahrenheit(t_fahrenheit: Scalar) -> Temperature
 <details>
 <summary>Examples</summary>
 
-* \\( 300 °F \\) in Kelvin.
+* 300 °F in Kelvin.
 
   <a href="https://numbat.dev/?q=from%5Ffahrenheit%28300%29"><i class="fa fa-play"></i> Run this example</a>
   ```nbt
@@ -384,7 +384,7 @@ fn fahrenheit(t_kelvin: Temperature) -> Scalar
 <details>
 <summary>Examples</summary>
 
-* \\( 300K \\) in degree Fahrenheit.
+* 300 K in degree Fahrenheit.
 
   <a href="https://numbat.dev/?q=300K%20%2D%3E%20fahrenheit"><i class="fa fa-play"></i> Run this example</a>
   ```nbt

book/src/list-functions-strings.md

@@ -34,14 +34,14 @@ fn str_slice(s: String, start: Scalar, end: Scalar) -> String
 <details>
 <summary>Examples</summary>
 
-* <a href="https://numbat.dev/?q=str%5Fslice%28%22Numbat%22%2C%200%2C%202%29"><i class="fa fa-play"></i> Run this example</a>
+* <a href="https://numbat.dev/?q=str%5Fslice%28%22Numbat%22%2C%203%2C%206%29"><i class="fa fa-play"></i> Run this example</a>
 
   ```nbt
-    >>> str_slice("Numbat", 0, 2)
+    >>> str_slice("Numbat", 3, 6)
     
-      str_slice("Numbat", 0, 2)
+      str_slice("Numbat", 3, 6)
     
-        = "Nu"    [String]
+        = "bat"    [String]
     
   ```
 </details>

numbat/modules/core/functions.nbt

@@ -60,7 +60,7 @@ fn floor_in<D: Dim>(base: D, value: D) -> D = floor(value / base) × base
 fn ceil(x: Scalar) -> Scalar
 
 @name("Ceil function")
-@description("Returns the smallest integer multuple of `base` greater than or equal to `value`.")
+@description("Returns the smallest integer multiple of `base` greater than or equal to `value`.")
 @example("ceil_in(m, 5.3 m)", "Ceil in meters.")
 @example("ceil_in(cm, 5.3 m)", "Ceil in centimeters.")
 

numbat/modules/core/lists.nbt

@@ -78,7 +78,7 @@ fn map<A, B>(f: Fn[(A) -> B], xs: List<A>) -> List<B> =
     else cons(f(head(xs)), map(f, tail(xs)))
 
 @description("Filter a list by a predicate")
-@example("fn filter_fn(x) = x > 1\nfilter(filter_fn, [3, 2, 1, 0])", "Filter all elements greater than $1$.")
+@example("filter(is_finite, [0, 1e10, NaN, -inf])")
 fn filter<A>(p: Fn[(A) -> Bool], xs: List<A>) -> List<A> =
   if is_empty(xs)
     then []
@@ -104,7 +104,7 @@ fn _merge(xs, ys, cmp) =
 
 
 @description("Sort a list of elements, using the given key function that maps the element to a quantity")
-@example("fn map_fn(x) = mod(x, 10)\nsort_by_key(map_fn, [701, 313, 9999, 4])","Sort by last digit.")
+@example("fn last_digit(x) = mod(x, 10)\nsort_by_key(last_digit, [701, 313, 9999, 4])","Sort by last digit.")
 fn sort_by_key<A, D: Dim>(key: Fn[(A) -> D], xs: List<A>) -> List<A> =
   if is_empty(xs)
     then []
@@ -129,7 +129,7 @@ fn intersperse<A>(sep: A, xs: List<A>) -> List<A> =
 
 fn _add(x, y) = x + y # TODO: replace this with a local function once we support them
 @description("Sum all elements of a list")
-@example("sum([3, 2, 1])")
+@example("sum([3 m, 200 cm, 1000 mm])")
 fn sum<D: Dim>(xs: List<D>) -> D = foldl(_add, 0, xs)
 
 # TODO: implement linspace using `map` or similar once we have closures. This is ugly.

numbat/modules/core/strings.nbt

@@ -7,7 +7,7 @@ use core::error
 fn str_length(s: String) -> Scalar
 
 @description("Subslice of a string")
-@example("str_slice(\"Numbat\", 0, 2)")
+@example("str_slice(\"Numbat\", 3, 6)")
 fn str_slice(s: String, start: Scalar, end: Scalar) -> String
 
 @description("Get a single-character string from a Unicode code point.")

numbat/modules/math/geometry.nbt

@@ -2,11 +2,11 @@ use core::functions
 use math::constants
 
 @description("The length of the hypotenuse of a right-angled triangle $\\sqrt\{x^2+y^2\}$.")
-@example("hypot2(3, 4)")
+@example("hypot2(3 m, 4 m)")
 fn hypot2<T: Dim>(x: T, y: T) -> T = sqrt(x^2 + y^2)
 
 @description("The Euclidean norm of a 3D vector $\\sqrt\{x^2+y^2+z^2\}$.")
-@example("hypot3(4, 1, 4)")
+@example("hypot3(8, 9, 12)")
 fn hypot3<T: Dim>(x: T, y: T, z: T) -> T = sqrt(x^2 + y^2 + z^2)
 
 # The following functions use a generic dimension instead of

numbat/modules/math/number_theory.nbt

@@ -4,7 +4,7 @@ use core::functions
 @name("Greatest common divisor")
 @description("The largest positive integer that divides each of the integers $a$ and $b$.")
 @url("https://en.wikipedia.org/wiki/Greatest_common_divisor")
-@example("gcd(60,42)")
+@example("gcd(60, 42)")
 fn gcd(a: Scalar, b: Scalar) -> Scalar =
   if b == 0
     then abs(a)

numbat/modules/numerics/diff.nbt

@@ -3,7 +3,8 @@ use core::quantities
 @name("Numerical differentiation")
 @url("https://en.wikipedia.org/wiki/Numerical_differentiation")
 @description("Compute the numerical derivative of the function $f$ at point $x$ using the central difference method.")
-@example("fn polynomial(x) = x² -x -1\ndiff(polynomial, 1)", "Compute the drivative of $f(x) = x² -x -1$ at $x=1$.")
+@example("fn polynomial(x) = x² - x - 1\ndiff(polynomial, 1)", "Compute the derivative of $f(x) = x² -x -1$ at $x=1$.")
+@example("fn distance(t) = 0.5 g0 t²\nfn velocity(t) = diff(distance, t)\nvelocity(2 s)", "Compute the free fall velocity after $t=2 s$.")
 fn diff<X: Dim, Y: Dim>(f: Fn[(X) -> Y], x: X) -> Y / X =
   (f(x + Δx) - f(x - Δx)) / 2 Δx
   where

numbat/modules/physics/temperature_conversion.nbt

@@ -5,12 +5,12 @@ use units::si
 let _offset_celsius = 273.15
 
 @description("Converts from degree Celsius (°C) to Kelvin.")
-@example("from_celsius(300)", "$300 °C$ in Kelvin.")
+@example("from_celsius(300)", "300 °C in Kelvin.")
 @url("https://en.wikipedia.org/wiki/Conversion_of_scales_of_temperature")
 fn from_celsius(t_celsius: Scalar) -> Temperature = (t_celsius + _offset_celsius) kelvin
 
 @description("Converts from Kelvin to degree Celcius (°C). This can be used on the right hand side of a conversion operator: `200 K -> celsius`.")
-@example("300K -> celsius", "$300K$ in degree Celsius.")
+@example("300K -> celsius", "300 K in degree Celsius.")
 @url("https://en.wikipedia.org/wiki/Conversion_of_scales_of_temperature")
 fn celsius(t_kelvin: Temperature) -> Scalar = t_kelvin / kelvin - _offset_celsius
 
@@ -18,11 +18,11 @@ let _offset_fahrenheit = 459.67
 let _scale_fahrenheit = 5 / 9
 
 @description("Converts from degree Fahrenheit (°F) to Kelvin.")
-@example("from_fahrenheit(300)", "$300 °F$ in Kelvin.")
+@example("from_fahrenheit(300)", "300 °F in Kelvin.")
 @url("https://en.wikipedia.org/wiki/Conversion_of_scales_of_temperature")
 fn from_fahrenheit(t_fahrenheit: Scalar) -> Temperature = ((t_fahrenheit + _offset_fahrenheit) × _scale_fahrenheit) kelvin
 
 @description("Converts from Kelvin to degree Fahrenheit (°F). This can be used on the right hand side of a conversion operator: `200 K -> fahrenheit`.")
-@example("300K -> fahrenheit", "$300K$ in degree Fahrenheit.")
+@example("300K -> fahrenheit", "300 K in degree Fahrenheit.")
 @url("https://en.wikipedia.org/wiki/Conversion_of_scales_of_temperature")
 fn fahrenheit(t_kelvin: Temperature) -> Scalar = (t_kelvin / kelvin) / _scale_fahrenheit - _offset_fahrenheit

numbat/modules/units/mixed.nbt

@@ -5,13 +5,13 @@ use units::imperial
 @name("Degrees, minutes, seconds")
 @description("Convert an angle to a mixed degrees, (arc)minutes, and (arc)seconds representation. Also called sexagesimal degree notation.")
 @url("https://en.wikipedia.org/wiki/Sexagesimal_degree")
-@example("DMS(46.5858°)")
+@example("46.5858° -> DMS")
 fn DMS(alpha: Angle) -> String =
   _mixed_units(alpha, [deg, arcmin, arcsec], ["° ", "′ ", "″"], true)
 
 @name("Degrees, decimal minutes")
 @description("Convert an angle to a mixed degrees and decimal minutes representation.")
-@example("DM(46.5858°)")
+@example("46.5858° -> DM")
 @url("https://en.wikipedia.org/wiki/Decimal_degrees")
 fn DM(alpha: Angle) -> String =
   _mixed_units(alpha, [deg, arcmin], ["° ", "′"], false)
@@ -19,13 +19,13 @@ fn DM(alpha: Angle) -> String =
 @name("Feet and inches")
 @description("Convert a length to a mixed feet and inches representation.")
 @url("https://en.wikipedia.org/wiki/Foot_(unit)")
-@example("feet_and_inches(180cm)")
+@example("180 cm -> feet_and_inches")
 fn feet_and_inches(length: Length) -> String =
   _mixed_units(length, [foot, inch], [" ft ", " in"], false)
 
 @name("Pounds and ounces")
 @description("Convert a mass to a mixed pounds and ounces representation.")
 @url("https://en.wikipedia.org/wiki/Pound_(mass)")
-@example("pounds_and_ounces(1kg)")
+@example("1 kg -> pounds_and_ounces")
 fn pounds_and_ounces(mass: Mass) -> String =
   _mixed_units(mass, [pound, ounce], [" lb ", " oz"], false)