Make API documentation into YAML files and autogenerate markdown files

and manpages from those.

1 files changed, 2 insertions, 1142 deletions

diff --git a/docs/nums.md b/docs/nums.md
index c209d74d..1bd9b52d 100644
--- a/docs/nums.md
+++ b/docs/nums.md
@@ -94,1146 +94,6 @@ eliminating conditional branching inside of compound math expressions. Users
 should also be able to write code that can safely assume that all values
 provided are not NaN.
 
-## Constants
+# API
 
-- **`1_PI`**: \( \frac{1}{\pi} \)
-- **`2_PI`**: \( 2 \times \pi \)
-- **`2_SQRTPI`**: \( 2 \times \sqrt{\pi} \)
-- **`E`**: Base of natural logarithms (\( e \))
-- **`INF`**: Positive infinity
-- **`LN10`**: Natural logarithm of 10
-- **`LN2`**: Natural logarithm of 2
-- **`LOG2E`**: Logarithm base 2 of \( e \)
-- **`PI`**: Pi (\( \pi \))
-- **`PI_2`**: \( \frac{\pi}{2} \)
-- **`PI_4`**: \( \frac{\pi}{4} \)
-- **`SQRT1_2`**: \( \sqrt{\frac{1}{2}} \)
-- **`SQRT2`**: \( \sqrt{2} \)
-- **`TAU`**: Tau (\( 2 \times \pi \))
-
-## Functions
-
-Each Num type has its own version of the following functions. Functions can be
-called either on the type itself: `Num.sqrt(x)` or as a method call:
-`x.sqrt()`. Method call syntax is preferred.
-
----
-
-- [`func abs(n: Num -> Num)`](#abs)
-- [`func acos(x: Num -> Num)`](#acos)
-- [`func acosh(x: Num -> Num)`](#acosh)
-- [`func asin(x: Num -> Num)`](#asin)
-- [`func asinh(x: Num -> Num)`](#asinh)
-- [`func atan(x: Num -> Num)`](#atan)
-- [`func atan2(x: Num, y: Num -> Num)`](#atan2)
-- [`func atanh(x: Num -> Num)`](#atanh)
-- [`func cbrt(x: Num -> Num)`](#cbrt)
-- [`func ceil(x: Num -> Num)`](#ceil)
-- [`func clamped(x, low, high: Num -> Num)`](#clamped)
-- [`func copysign(x: Num, y: Num -> Num)`](#copysign)
-- [`func cos(x: Num -> Num)`](#cos)
-- [`func cosh(x: Num -> Num)`](#cosh)
-- [`func erf(x: Num -> Num)`](#erf)
-- [`func erfc(x: Num -> Num)`](#erfc)
-- [`func exp(x: Num -> Num)`](#exp)
-- [`func exp2(x: Num -> Num)`](#exp2)
-- [`func expm1(x: Num -> Num)`](#expm1)
-- [`func fdim(x: Num, y: Num -> Num)`](#fdim)
-- [`func floor(x: Num -> Num)`](#floor)
-- [`func format(n: Num, precision: Int = 0 -> Text)`](#format)
-- [`func hypot(x: Num, y: Num -> Num)`](#hypot)
-- [`func isfinite(n: Num -> Bool)`](#isfinite)
-- [`func is_between(n: Num, low: Num, high: Num -> Bool)`](#is_between)
-- [`func isinf(n: Num -> Bool)`](#isinf)
-- [`func j0(x: Num -> Num)`](#j0)
-- [`func j1(x: Num -> Num)`](#j1)
-- [`func log(x: Num -> Num)`](#log)
-- [`func log10(x: Num -> Num)`](#log10)
-- [`func log1p(x: Num -> Num)`](#log1p)
-- [`func log2(x: Num -> Num)`](#log2)
-- [`func logb(x: Num -> Num)`](#logb)
-- [`func mix(amount: Num, x: Num, y: Num -> Num)`](#mix)
-- [`func near(x: Num, y: Num, ratio: Num = 1e-9, min_epsilon: Num = 1e-9 -> Bool)`](#near)
-- [`func nextafter(x: Num, y: Num -> Num)`](#nextafter)
-- [`func parse(text: Text -> Num?)`](#parse)
-- [`func percent(n: Num -> Text)`](#percent)
-- [`func rint(x: Num -> Num)`](#rint)
-- [`func round(x: Num -> Num)`](#round)
-- [`func scientific(n: Num, precision: Int = 0 -> Text)`](#scientific)
-- [`func significand(x: Num -> Num)`](#significand)
-- [`func sin(x: Num -> Num)`](#sin)
-- [`func sinh(x: Num -> Num)`](#sinh)
-- [`func sqrt(x: Num -> Num)`](#sqrt)
-- [`func tan(x: Num -> Num)`](#tan)
-- [`func tanh(x: Num -> Num)`](#tanh)
-- [`func tgamma(x: Num -> Num)`](#tgamma)
-- [`func trunc(x: Num -> Num)`](#trunc)
-- [`func y0(x: Num -> Num)`](#y0)
-- [`func y1(x: Num -> Num)`](#y1)
-
-### `abs`
-Calculates the absolute value of a number.
-
-```tomo
-func abs(n: Num -> Num)
-```
-
-- `n`: The number whose absolute value is to be computed.
-
-**Returns:**
-The absolute value of `n`.
-
-**Example:**
-```tomo
->> (-3.5).abs()
-= 3.5
-```
-
----
-
-### `acos`
-Computes the arc cosine of a number.
-
-```tomo
-func acos(x: Num -> Num)
-```
-
-- `x`: The number for which the arc cosine is to be calculated.
-
-**Returns:**
-The arc cosine of `x` in radians.
-
-**Example:**
-```tomo
->> (0.0).acos() // -> (π/2)
-= 1.5708
-```
-
----
-
-### `acosh`
-Computes the inverse hyperbolic cosine of a number.
-
-```tomo
-func acosh(x: Num -> Num)
-```
-
-- `x`: The number for which the inverse hyperbolic cosine is to be calculated.
-
-**Returns:**
-The inverse hyperbolic cosine of `x`.
-
-**Example:**
-```tomo
->> (1.0).acosh()
-= 0
-```
-
----
-
-### `asin`
-Computes the arc sine of a number.
-
-```tomo
-func asin(x: Num -> Num)
-```
-
-- `x`: The number for which the arc sine is to be calculated.
-
-**Returns:**
-The arc sine of `x` in radians.
-
-**Example:**
-```tomo
->> (0.5).asin()  // -> (π/6)
-= 0.5236
-```
-
----
-
-### `asinh`
-Computes the inverse hyperbolic sine of a number.
-
-```tomo
-func asinh(x: Num -> Num)
-```
-
-- `x`: The number for which the inverse hyperbolic sine is to be calculated.
-
-**Returns:**
-The inverse hyperbolic sine of `x`.
-
-**Example:**
-```tomo
->> (0.0).asinh()
-= 0
-```
-
----
-
-### `atan`
-Computes the arc tangent of a number.
-
-```tomo
-func atan(x: Num -> Num)
-```
-
-- `x`: The number for which the arc tangent is to be calculated.
-
-**Returns:**
-The arc tangent of `x` in radians.
-
-**Example:**
-```tomo
->> (1.0).atan() // -> (π/4)
-= 0.7854
-```
-
----
-
-### `atan2`
-Computes the arc tangent of the quotient of two numbers.
-
-```tomo
-func atan2(x: Num, y: Num -> Num)
-```
-
-- `x`: The numerator.
-- `y`: The denominator.
-
-**Returns:**
-The arc tangent of `x/y` in radians.
-
-**Example:**
-```tomo
->> Num.atan2(1, 1) // -> (π/4)
-= 0.7854
-```
-
----
-
-### `atanh`
-Computes the inverse hyperbolic tangent of a number.
-
-```tomo
-func atanh(x: Num -> Num)
-```
-
-- `x`: The number for which the inverse hyperbolic tangent is to be calculated.
-
-**Returns:**
-The inverse hyperbolic tangent of `x`.
-
-**Example:**
-```tomo
->> (0.5).atanh()
-= 0.5493
-```
-
----
-
-### `cbrt`
-Computes the cube root of a number.
-
-```tomo
-func cbrt(x: Num -> Num)
-```
-
-- `x`: The number for which the cube root is to be calculated.
-
-**Returns:**
-The cube root of `x`.
-
-**Example:**
-```tomo
->> (27.0).cbrt()
-= 3
-```
-
----
-
-### `ceil`
-Rounds a number up to the nearest integer.
-
-```tomo
-func ceil(x: Num -> Num)
-```
-
-- `x`: The number to be rounded up.
-
-**Returns:**
-The smallest integer greater than or equal to `x`.
-
-**Example:**
-```tomo
->> (3.2).ceil()
-= 4
-```
-
----
-
-### `clamped`
-Returns the given number clamped between two values so that it is within
-that range.
-
-```tomo
-func clamped(x, low, high: Num -> Num)
-```
-
-- `x`: The number to clamp.
-- `low`: The lowest value the result can take.
-- `high`: The highest value the result can take.
-
-**Returns:**  
-The first argument clamped between the other two arguments.
-
-**Example:**  
-```tomo
->> (2.5).clamped(5.5, 10.5)
-= 5.5
-```
-
----
-
-### `copysign`
-Copies the sign of one number to another.
-
-```tomo
-func copysign(x: Num, y: Num -> Num)
-```
-
-- `x`: The number whose magnitude will be copied.
-- `y`: The number whose sign will be copied.
-
-**Returns:**
-A number with the magnitude of `x` and the sign of `y`.
-
-**Example:**
-```tomo
->> (3.0).copysign(-1)
-= -3
-```
-
----
-
-### `cos`
-Computes the cosine of a number (angle in radians).
-
-```tomo
-func cos(x: Num -> Num)
-```
-
-- `x`: The angle in radians.
-
-**Returns:**
-The cosine of `x`.
-
-**Example:**
-```tomo
->> (0.0).cos()
-= 1
-```
-
----
-
-### `cosh`
-Computes the hyperbolic cosine of a number.
-
-```tomo
-func cosh(x: Num -> Num)
-```
-
-- `x`: The number for which the hyperbolic cosine is to be calculated.
-
-**Returns:**
-The hyperbolic cosine of `x`.
-
-**Example:**
-```tomo
->> (0.0).cosh()
-= 1
-```
-
----
-
-### `erf`
-Computes the error function of a number.
-
-```tomo
-func erf(x: Num -> Num)
-```
-
-- `x`: The number for which the error function is to be calculated.
-
-**Returns:**
-The error function of `x`.
-
-**Example:**
-```tomo
->> (0.0).erf()
-= 0
-```
-
----
-
-### `erfc`
-Computes the complementary error function of a number.
-
-```tomo
-func erfc(x: Num -> Num)
-```
-
-- `x`: The number for which the complementary error function is to be calculated.
-
-**Returns:**
-The complementary error function of `x`.
-
-**Example:**
-```tomo
->> (0.0).erfc()
-= 1
-```
-
----
-
-### `exp`
-Computes the exponential function \( e^x \) for a number.
-
-```tomo
-func exp(x: Num -> Num)
-```
-
-- `x`: The exponent.
-
-**Returns:**
-The value of \( e^x \).
-
-**Example:**
-```tomo
->> (1.0).exp()
-= 2.7183
-```
-
----
-
-### `exp2`
-Computes \( 2^x \) for a number.
-
-```tomo
-func exp2(x: Num -> Num)
-```
-
-- `x`: The exponent.
-
-**Returns:**
-The value of \( 2^x \).
-
-**Example:**
-```tomo
->> (3.0).exp2()
-= 8
-```
-
----
-
-### `expm1`
-Computes \( e^x - 1 \) for a number.
-
-```tomo
-func expm1(x: Num -> Num)
-```
-
-- `x`: The exponent.
-
-**Returns:**
-The value of \( e^x - 1 \).
-
-**Example:**
-```tomo
->> (1.0).expm1()
-= 1.7183
-```
-
----
-
-### `fdim`
-Computes the positive difference between two numbers.
-
-```tomo
-func fdim(x: Num, y: Num -> Num)
-```
-
-- `x`: The first number.
-- `y`: The second number.
-
-**Returns:**
-The positive difference \( \max(0, x - y) \).
-
-**Example:**
-```tomo
-fd
-
->> (5.0).fdim(3)
-= 2
-```
-
----
-
-### `floor`
-Rounds a number down to the nearest integer.
-
-```tomo
-func floor(x: Num -> Num)
-```
-
-- `x`: The number to be rounded down.
-
-**Returns:**
-The largest integer less than or equal to `x`.
-
-**Example:**
-```tomo
->> (3.7).floor()
-= 3
-```
-
----
-
-### `format`
-Formats a number as a text with a specified precision.
-
-```tomo
-func format(n: Num, precision: Int = 0 -> Text)
-```
-
-- `n`: The number to be formatted.
-- `precision`: The number of decimal places. Default is `0`.
-
-**Returns:**
-A text representation of the number with the specified precision.
-
-**Example:**
-```tomo
->> (3.14159).format(precision=2)
-= "3.14"
-```
-
----
-
-### `hypot`
-Computes the Euclidean norm, \( \sqrt{x^2 + y^2} \), of two numbers.
-
-```tomo
-func hypot(x: Num, y: Num -> Num)
-```
-
-- `x`: The first number.
-- `y`: The second number.
-
-**Returns:**
-The Euclidean norm of `x` and `y`.
-
-**Example:**
-```tomo
->> Num.hypot(3, 4)
-= 5
-```
-
----
-
-### `isfinite`
-Checks if a number is finite.
-
-```tomo
-func isfinite(n: Num -> Bool)
-```
-
-- `n`: The number to be checked.
-
-**Returns:**
-`yes` if `n` is finite, `no` otherwise.
-
-**Example:**
-```tomo
->> (1.0).isfinite()
-= yes
->> Num.INF.isfinite()
-= no
-```
-
----
-
-### `is_between`
-Determines if a number is between two numbers (inclusive).
-
-```tomo
-func is_between(x: Num, low: Num, high: Num -> Bool)
-```
-
-- `x`: The integer to be checked.
-- `low`: The lower bound to check (inclusive).
-- `high`: The upper bound to check (inclusive).
-
-**Returns:**  
-`yes` if `low <= x and x <= high`, otherwise `no`
-
-**Example:**  
-```tomo
->> (7.5).is_between(1, 10)
-= yes
->> (7.5).is_between(100, 200)
-= no
->> (7.5).is_between(1, 7.5)
-= yes
-```
-
----
-
-### `isinf`
-Checks if a number is infinite.
-
-```tomo
-func isinf(n: Num -> Bool)
-```
-
-- `n`: The number to be checked.
-
-**Returns:**
-`yes` if `n` is infinite, `no` otherwise.
-
-**Example:**
-```tomo
->> Num.INF.isinf()
-= yes
->> (1.0).isinf()
-= no
-```
-
----
-
-### `j0`
-Computes the Bessel function of the first kind of order 0.
-
-```tomo
-func j0(x: Num -> Num)
-```
-
-- `x`: The number for which the Bessel function is to be calculated.
-
-**Returns:**
-The Bessel function of the first kind of order 0 of `x`.
-
-**Example:**
-```tomo
->> (0.0).j0()
-= 1
-```
-
----
-
-### `j1`
-Computes the Bessel function of the first kind of order 1.
-
-```tomo
-func j1(x: Num -> Num)
-```
-
-- `x`: The number for which the Bessel function is to be calculated.
-
-**Returns:**
-The Bessel function of the first kind of order 1 of `x`.
-
-**Example:**
-```tomo
->> (0.0).j1()
-= 0
-```
-
----
-
-### `log`
-Computes the natural logarithm (base \( e \)) of a number.
-
-```tomo
-func log(x: Num -> Num)
-```
-
-- `x`: The number for which the natural logarithm is to be calculated.
-
-**Returns:**
-The natural logarithm of `x`.
-
-**Example:**
-```tomo
->> Num.E.log()
-= 1
-```
-
----
-
-### `log10`
-Computes the base-10 logarithm of a number.
-
-```tomo
-func log10(x: Num -> Num)
-```
-
-- `x`: The number for which the base-10 logarithm is to be calculated.
-
-**Returns:**
-The base-10 logarithm of `x`.
-
-**Example:**
-```tomo
->> (100.0).log10()
-= 2
-```
-
----
-
-### `log1p`
-Computes \( \log(1 + x) \) for a number.
-
-```tomo
-func log1p(x: Num -> Num)
-```
-
-- `x`: The number for which \( \log(1 + x) \) is to be calculated.
-
-**Returns:**
-The value of \( \log(1 + x) \).
-
-**Example:**
-```tomo
->> (1.0).log1p()
-= 0.6931
-```
-
----
-
-### `log2`
-Computes the base-2 logarithm of a number.
-
-```tomo
-func log2(x: Num -> Num)
-```
-
-- `x`: The number for which the base-2 logarithm is to be calculated.
-
-**Returns:**
-The base-2 logarithm of `x`.
-
-**Example:**
-```tomo
->> (8.0).log2()
-= 3
-```
-
----
-
-### `logb`
-Computes the binary exponent (base-2 logarithm) of a number.
-
-```tomo
-func logb(x: Num -> Num)
-```
-
-- `x`: The number for which the binary exponent is to be calculated.
-
-**Returns:**
-The binary exponent of `x`.
-
-**Example:**
-```tomo
->> (8.0).logb()
-= 3
-```
-
----
-
-### `mix`
-Interpolates between two numbers based on a given amount.
-
-```tomo
-func mix(amount: Num, x: Num, y: Num -> Num)
-```
-
-- `amount`: The interpolation factor (between `0` and `1`).
-- `x`: The starting number.
-- `y`: The ending number.
-
-**Returns:**
-The interpolated number between `x` and `y` based on `amount`.
-
-**Example:**
-```tomo
->> (0.5).mix(10, 20)
-= 15
->> (0.25).mix(10, 20)
-= 12.5
-```
-
----
-
-### `near`
-Checks if two numbers are approximately equal within specified tolerances. If
-two numbers are within an absolute difference or the ratio between the two is
-small enough, they are considered near each other.
-
-```tomo
-func near(x: Num, y: Num, ratio: Num = 1e-9, min_epsilon: Num = 1e-9 -> Bool)
-```
-
-- `x`: The first number.
-- `y`: The second number.
-- `ratio`: The relative tolerance. Default is `1e-9`.
-- `min_epsilon`: The absolute tolerance. Default is `1e-9`.
-
-**Returns:**
-`yes` if `x` and `y` are approximately equal within the specified tolerances, `no` otherwise.
-
-**Example:**
-```tomo
->> (1.0).near(1.000000001)
-= yes
-
->> (100.0).near(110, ratio=0.1)
-= yes
-
->> (5.0).near(5.1, min_epsilon=0.1)
-= yes
-```
-
----
-
-### `nextafter`
-Computes the next representable value after a given number towards a specified direction.
-
-```tomo
-func nextafter(x: Num, y: Num -> Num)
-```
-
-- `x`: The starting number.
-- `y`: The direction towards which to find the next representable value.
-
-**Returns:**
-The next representable value after `x` in the direction of `y`.
-
-**Example:**
-```tomo
->> (1.0).nextafter(1.1)
-= 1.0000000000000002
-```
-
----
-
-### `parse`
-Converts a text representation of a number into a floating-point number.
-
-```tomo
-func parse(text: Text -> Num?)
-```
-
-- `text`: The text containing the number.
-
-**Returns:**
-The number represented by the text or `none` if the entire text can't be parsed
-as a number.
-
-**Example:**
-```tomo
->> Num.parse("3.14")
-= 3.14
->> Num.parse("1e3")
-= 1000
-```
-
----
-
-### `percent`
-Convert a number into a percentage text with a percent sign.
-
-```tomo
-func percent(n: Num, precision: Int = 0 -> Text)
-```
-
-- `n`: The number to be converted to a percent.
-- `precision`: The number of decimal places. Default is `0`.
-
-**Returns:**
-A text representation of the number as a percentage with a percent sign.
-
-**Example:**
-```tomo
->> (0.5).percent()
-= "50%"
->> (1./3.).percent(2)
-= "33.33%"
-```
-
----
-
-### `rint`
-Rounds a number to the nearest integer, with ties rounded to the nearest even integer.
-
-```tomo
-func rint(x: Num -> Num)
-```
-
-- `x`: The number to be rounded.
-
-**Returns:**
-The nearest integer value of `x`.
-
-**Example:**
-```tomo
->> (3.5).rint()
-= 4
->> (2.5).rint()
-= 2
-```
-
----
-
-### `round`
-Rounds a number to the nearest whole number integer.
-
-```tomo
-func round(x: Num -> Num)
-```
-
-- `x`: The number to be rounded.
-
-**Returns:**
-The nearest integer value of `x`.
-
-**Example:**
-```tomo
->> (2.3).round()
-= 2
->> (2.7).round()
-= 3
-```
-
----
-
-### `scientific`
-Formats a number in scientific notation with a specified precision.
-
-```tomo
-func scientific(n: Num, precision: Int = 0 -> Text)
-```
-
-- `n`: The number to be formatted.
-- `precision`: The number of decimal places. Default is `0`.
-
-**Returns:**
-A text representation of the number in scientific notation with the specified precision.
-
-**Example:**
-```tomo
->> (12345.6789).scientific(precision=2)
-= "1.23e+04"
-```
-
----
-
-### `significand`
-Extracts the significand (or mantissa) of a number.
-
-```tomo
-func significand(x: Num -> Num)
-```
-
-- `x`: The number from which to extract the significand.
-
-**Returns:**
-The significand of `x`.
-
-**Example:**
-```tomo
->> (1234.567).significand()
-= 0.1234567
-```
-
----
-
-### `sin`
-Computes the sine of a number (angle in radians).
-
-```tomo
-func sin(x: Num -> Num)
-```
-
-- `x`: The angle in radians.
-
-**Returns:**
-The sine of `x`.
-
-**Example:**
-```tomo
->> (0.0).sin()
-= 0
-```
-
----
-
-### `sinh`
-Computes the hyperbolic sine of a number.
-
-```tomo
-func sinh(x: Num -> Num)
-```
-
-- `x`: The number for which the hyperbolic sine is to be calculated.
-
-**Returns:**
-The hyperbolic sine of `x`.
-
-**Example:**
-```tomo
->> (0.0).sinh()
-= 0
-```
-
----
-
-### `sqrt`
-Computes the square root of a number.
-
-```tomo
-func sqrt(x: Num -> Num)
-```
-
-- `x`: The number for which the square root is to be calculated.
-
-**Returns:**
-The square root of `x`.
-
-**Example:**
-```tomo
->> (16.0).sqrt()
-= 4
-```
-
----
-
-### `tan`
-Computes the tangent of a number (angle in radians).
-
-```tomo
-func tan(x: Num -> Num)
-```
-
-- `x`: The angle in radians.
-
-**Returns:**
-The tangent of `x`.
-
-**Example:**
-```tomo
->> (0.0).tan()
-= 0
-```
-
----
-
-### `tanh`
-Computes the hyperbolic tangent of a number.
-
-```tomo
-func tanh(x: Num -> Num)
-```
-
-- `x`: The number for which the hyperbolic tangent is to be calculated.
-
-**Returns:**
-The hyperbolic tangent of `x`.
-
-**Example:**
-```tomo
->> (0.0).tanh()
-= 0
-```
-
----
-
-### `tgamma`
-Computes the gamma function of a number.
-
-```tomo
-func tgamma(x: Num -> Num)
-```
-
-- `x`: The number for which the gamma function is to be calculated.
-
-**Returns:**
-The gamma function of `x`.
-
-**Example:**
-```tomo
->> (1.0).tgamma()
-= 1
-```
-
----
-
-### `trunc`
-Truncates a number to the nearest integer towards zero.
-
-```tomo
-func trunc(x: Num -> Num)
-```
-
-- `x`: The number to be truncated.
-
-**Returns:**
-The integer part of `x` towards zero.
-
-**Example:**
-```tomo
->> (3.7).trunc()
-= 3
->> (-3.7).trunc()
-= -3
-```
-
----
-
-### `y0`
-Computes the Bessel function of the second kind of order 0.
-
-```tomo
-func y0(x: Num -> Num)
-```
-
-- `x`: The number for which the Bessel function is to be calculated.
-
-**Returns:**
-The Bessel function of the second kind of order 0 of `x`.
-
-**Example:**
-```tomo
->> (1.0).y0()
-= -0.7652
-```
-
----
-
-### `y1`
-Computes the Bessel function of the second kind of order 1.
-
-```tomo
-func y1(x: Num -> Num)
-```
-
-- `x`: The number for which the Bessel function is to be calculated.
-
-**Returns:**
-The Bessel function of the second kind of order 1 of `x`.
-
-**Example:**
-```tomo
->> (1.0).y1()
-= 0.4401
-```
+[API documentation](../api/nums.md)