Refactor documentation for clarity and consistency across API files

Author: jbunke

README.md

@@ -1,10 +1,11 @@
 # Stipple Effect API specification
 
-This is the API (application programming interface) specification for scripting in *Stipple Effect*. It covers all the extensions made to the [*DeltaScript* base language](https://github.com/jbunke/deltascript) for scripting in *Stipple Effect*.
+This is the API (application programming interface) specification for scripting in *Stipple Effect*. It covers all the extensions made to the [*DeltaScript* base language![](./assets/external.png)](https://github.com/jbunke/deltascript) for scripting in *Stipple Effect*.
 
 For a general overview of scripting, please visit [the documentation](../docs/scripting.md).
 
 ### Content
+
 * Namespaces
   * [Global namespace (`$SE`)](global.md)
   * [`$Graphics`](graphics.md)
@@ -20,13 +21,14 @@ For a general overview of scripting, please visit [the documentation](../docs/sc
   * [`color`](color.md)
 
 ### Changelog
-See changes made to the API across releases [here](changelog.md).
 
-___
+See changes made to the API across *Stipple Effect* releases [here](changelog.md).
+
+---
 
 **SEE ALSO**
 
-* [*Stipple Effect* source code](https://github.com/stipple-effect/stipple-effect)
-* [Script examples](https://github.com/stipple-effect/script-examples)
-* [*DeltaScript for Stipple Effect* - VS Code syntax highlighting extension](https://marketplace.visualstudio.com/items?itemName=jordanbunke.deltascript-for-stipple-effect)
-* [*Stipple Effect* video playlist (w/ tutorials)](https://www.youtube.com/playlist?list=PLy71S74rTLnPEwYYtAXvh2er8QBvWIwRL)
+* [Script examples![](./assets/external.png)](https://github.com/stipple-effect/script-examples)
+* [*DeltaScript for Stipple Effect* - VS Code syntax highlighting extension![](./assets/external.png)](https://marketplace.visualstudio.com/items?itemName=jordanbunke.deltascript-for-stipple-effect)
+* [*Stipple Effect* video playlist (w/ tutorials)![](./assets/external.png)](https://www.youtube.com/playlist?list=PLy71S74rTLnPEwYYtAXvh2er8QBvWIwRL)
+* [*Stipple Effect* source code![](./assets/external.png)](https://github.com/stipple-effect/stipple-effect)

api-sidebar.md

@@ -2,7 +2,7 @@
   * [`$SE`](global.md) (global)
   * [`$Graphics`](graphics.md)
   * [`$Math`](math.md)
-* Types
+* API types
   * [`layer`](layer.md)
   * [`light`](light.md)
   * [`palette`](palette.md)

assets/external.png

@@ -1,7 +1,7 @@
-# API Changelog
-
 [`< Home`](README.md)
 
+# API Changelog
+
 ## 1.2.2
 
 ### Added:

changelog.md

@@ -1,8 +1,8 @@
-# `color` extension
-
 [`< API`](README.md)
 
-This API inherits the `color` type from the *DeltaScript* base language and extends it in the ways described below.
+# `color` extension
+
+This API inherits the `color` type from the [*DeltaScript* base language![](./assets/external.png)](https://github.com/jbunke/deltascript/blob/master/docs/color-sl.md) and extends it in the ways described below.
 
 ## Properties
 
@@ -12,16 +12,20 @@ These definitions use the arbitrary `color` object `C` as the caller.
 ```js
 C.hue -> float
 ```
-Returns the hue of a color `C` as a `float` ranging from 0.0 to 1.0. Since hue is a circular/angular property, a hue of 0.0 and a hue of 1.0 are identical. A hue of 0.0 is conventionally assigned to red ([`#ff0000`](https://en.wikipedia.org/wiki/Red), for example), while green is assigned to 1/3 (120°) and blue is assigned to 2/3 (240°). You can read more about hue [here](https://en.wikipedia.org/wiki/Hue#Defining_hue_in_terms_of_RGB).
+Returns the hue of a color `C` as a `float` ranging from 0.0 to 1.0. Since hue is a circular/angular property, a hue of 0.0 and a hue of 1.0 are identical. A hue of 0.0 is conventionally assigned to red ([`#ff0000`![](./assets/external.png)](https://en.wikipedia.org/wiki/Red), for example), while green is assigned to 1/3 (120°) and blue is assigned to 2/3 (240°).
+
+**Read more:**
+
+* [Defining hue in terms of RGB![](./assets/external.png)](https://en.wikipedia.org/wiki/Hue#Defining_hue_in_terms_of_RGB)
 
 ### Saturation (`sat`)
 ```js
 C.sat -> float
 ```
-Returns the [saturation](https://en.wikipedia.org/wiki/Colorfulness#Saturation) of a color `C` as a `float` ranging from 0.0 to 1.0.
+Returns the [saturation![](./assets/external.png)](https://en.wikipedia.org/wiki/Colorfulness#Saturation) of a color `C` as a `float` ranging from 0.0 to 1.0.
 
 ### Value (`val`)
 ```js
 C.val -> float
 ```
-Returns the [value](https://en.wikipedia.org/wiki/HSL_and_HSV) of a color `C` as a `float` ranging from 0.0 to 1.0.
+Returns the [value![](./assets/external.png)](https://en.wikipedia.org/wiki/HSL_and_HSV) of a color `C` as a `float` ranging from 0.0 to 1.0.

color.md

@@ -1,8 +1,10 @@
+[`< API`](README.md)
+
 # Global namespace (`$SE`)
 
 [`< API`](README.md)
 
-The global namespace for this API is `$SE`. Most Stipple Effect functions that are not called on an object are called on the global namespace.
+The global namespace for this API is `$SE`. Most API functions that are not called on an object are called on the global namespace.
 
 ---
 
@@ -104,7 +106,7 @@ Any of the following will result in runtime errors:
     { '/', '\\', ':', '*', '?', '"', '<', '>', '|', '{', '}' }
     ```
 
-**Reading material:**
+**Read more:**
 * [Save type constants](global.md/#save-type-constants)
 
 ### `read_script`
@@ -122,7 +124,7 @@ Any of the following will result in runtime errors:
 
 Script execution will terminate if the child script fails its semantic error check.
 
-**Reading material:**
+**Read more:**
 * [Child scripts in the documentation](../docs/child-scripts.md)
 
 ### `transform`
@@ -245,7 +247,11 @@ Any of the following will cause the function not to execute:
 ```js
 $SE.outline(int[]{} selection, int[] side_mask) -> int[]{}
 ```
-Returns the outline of the initial selection `selection` when outlined with the side mask `side_mask`. The outlining algorithm can be found [here](https://github.com/stipple-effect/stipple-effect/blob/master/src/com/jordanbunke/stipple_effect/selection/Outliner.java).
+Returns the outline of the initial selection `selection` when outlined with the side mask `side_mask`.
+
+**Read more:**
+
+* [Outlining algorithm in the source code![](./assets/external.png)](https://github.com/stipple-effect/stipple-effect/blob/master/src/com/jordanbunke/stipple_effect/selection/Outliner.java)
 
 **Throws:**
 
@@ -301,8 +307,9 @@ Returns a set of ordered pairs that represent the pixel coordinates of the resul
   * if `true`, adjacency is defined as cardinal adjacency + diagonal adjacency
   * if `false`, pixels must be cardinally adjacent in order to be considered
 
-**Reading material:**
-* [`wand` and `fill` search algorithm implementation](https://github.com/stipple-effect/stipple-effect/blob/master/src/com/jordanbunke/stipple_effect/tools/ToolThatSearches.java)
+**Read more:**
+
+* [`wand` and `fill` search algorithm implementation![](./assets/external.png)](https://github.com/stipple-effect/stipple-effect/blob/master/src/com/jordanbunke/stipple_effect/tools/ToolThatSearches.java)
 
 ### ![](https://raw.githubusercontent.com/stipple-effect/stipple-effect/master/res/icons/fill.png) `fill`
 ```js

global.md

@@ -1,7 +1,7 @@
-# `$Graphics`
-
 [`< API`](README.md)
 
+# `$Graphics`
+
 The `$Graphics` namespace houses graphics utilities for processing images and colors.
 
 ---
@@ -24,7 +24,7 @@ $Graphics.DL_BR = [ 1.0, -1.0, 1.0 ]            // From the bottom-right
 $Graphics.DL_DIRECT = [ 0.0, 0.0, 1.0 ]         // Frontlit
 ```
 
-**Reading material:**
+**Read more:**
 * [`light`](./light.md)
 * [Directional light constructor](#dir_light)
 
@@ -43,7 +43,7 @@ A directional light, as opposed to a point light, shines with a non-dimming lumi
 
 `light` objects are mutable. Arguments `luminosity`, `c`, and `direction` passed to the constructor can be overridden by using the mutator methods of `light`.
 
-**Reading material:**
+**Read more:**
 * [Light direction constants](#light-direction-constants)
 
 ### `gen_lookup`
@@ -53,8 +53,8 @@ $Graphics.gen_lookup(image source, bool dim) -> image
 
 Takes an image `source` and generates a corresponding lookup image where every non-transparent pixel in `source` is assigned a unique opaque RGB color. The flag `dim` determines whether the lookup will have vertical or horizontal striping.
 
-**Reading material:**
-* [Lookup generation algorithm implementation](https://github.com/jbunke/delta-time/blob/master/sprite/src/com/jordanbunke/delta_time/sprite/UVMapping.java#L85)
+**Read more:**
+* [Lookup generation algorithm implementation![](./assets/external.png)](https://github.com/jbunke/delta-time/blob/master/sprite/src/com/jordanbunke/delta_time/sprite/UVMapping.java#L85)
 * [Dimension constants](./global.md#dimension-constants)
 
 ### `lerp_color`
@@ -118,6 +118,6 @@ Otherwise, returns the following image:
     * sets position `(ax, ay)` of the output image to `c`
 
 
-**Reading material:**
-* [UV mapping algorithm implementation](https://github.com/jbunke/delta-time/blob/master/sprite/src/com/jordanbunke/delta_time/sprite/UVMapping.java#L40)
+**Read more:**
+* [UV mapping algorithm implementation![](./assets/external.png)](https://github.com/jbunke/delta-time/blob/master/sprite/src/com/jordanbunke/delta_time/sprite/UVMapping.java#L40)
 * [`gen_lookup()`](#gen_lookup) - generating a naive lookup map for a `texture`

graphics.md

@@ -1,10 +1,12 @@
+[`< API`](README.md)
+
 # `layer`
 
-[`< API`](README.md)
+`layer` objects created in scripts are internally represented by the [`LayerRep`![](./assets/external.png)](https://github.com/stipple-effect/stipple-effect/blob/master/src/com/jordanbunke/stipple_effect/scripting/util/LayerRep.java) class from the *Stipple Effect* source code.
 
-`layer`'s correspondent type in the Stippe Effect source code is [`LayerRep`](https://github.com/stipple-effect/stipple-effect/blob/master/src/com/jordanbunke/stipple_effect/scripting/util/LayerRep.java).
+**Note:**
 
-**Note:** `LayerRep` stores an immutable reference to the project that contains the layer, and to its layer index. This means that a `layer` reference in script can be "spoiled" - i.e. cease to refer to the same layer or no longer refer to a valid layer at all - if the number of layers in the project are changed, or if the order of the layers in the project is changed.
+`LayerRep` stores an immutable reference to the project that contains the layer, and to its layer index. This means that a `layer` reference in script can be "spoiled" - i.e. cease to refer to the same layer or no longer refer to a valid layer at all - if the number of layers in the project are changed, or if the order of the layers in the project is changed.
 
 ---
 

layer.md

@@ -1,8 +1,8 @@
-# `light`
-
 [`< API`](README.md)
 
-`light`'s correspondent type in the Stippe Effect source code is [`Light`](https://github.com/stipple-effect/stipple-effect/blob/master/src/com/jordanbunke/stipple_effect/scripting/util/Light.java).
+# `light`
+
+`light` objects created in scripts are internally represented by the [`Light`![](./assets/external.png)](https://github.com/stipple-effect/stipple-effect/blob/master/src/com/jordanbunke/stipple_effect/scripting/util/Light.java) class from the *Stipple Effect* source code.
 
 ---
 

light.md

@@ -1,17 +1,12 @@
-# `$Math`
-
 [`< API`](README.md)
 
+# `$Math`
+
 The `$Math` namespace houses mathematical constants and functions that may be useful when writing scripts.
 
 **Note:**
 
-There are additional mathematical functions available in DeltaScript that are implemented as native functions. These include:
-* `abs()` - [absolute value](https://en.wikipedia.org/wiki/Absolute_value)
-* `min()`, `max()` - minimum/maximum of two numbers or of a collection
-* `clamp(min, v, max)` - returns `min` if `v < min`, `max` if `v > max`, `v` otherwise
-
-[**\[read more\]**](https://github.com/jbunke/deltascript) <!-- TODO - update link -->
+There are additional mathematical functions available in *DeltaScript* that are included as part of the [standard library![](./assets/external.png)](https://github.com/jbunke/deltascript/blob/master/docs/std-lib.md).
 
 ---
 
@@ -21,13 +16,15 @@ There are additional mathematical functions available in DeltaScript that are im
 ```js
 $Math.PI
 ```
-[Pi](https://en.wikipedia.org/wiki/Pi) represented as a `float`.
+[Pi![](./assets/external.png)](https://en.wikipedia.org/wiki/Pi) represented as a `float`.
 
 **Note:**
 
-The `float` type in DeltaScript is actually implemented as a [double-precision floating point number](https://en.wikipedia.org/wiki/Double-precision_floating-point_format), and is internally mapped to Java's `double` primitive type.
+The `float` type in DeltaScript is actually implemented as a [double-precision floating point number![](./assets/external.png)](https://en.wikipedia.org/wiki/Double-precision_floating-point_format), and is internally mapped to Java's `double` primitive type.
+
+**Read more:**
 
-[**\[`Double` wrapper class Java documentation\]**](https://docs.oracle.com/javase/8/docs/api/java/lang/Double.html)
+* [`Double` wrapper class Java documentation![](./assets/external.png)](https://docs.oracle.com/javase/8/docs/api/java/lang/Double.html)
 
 ---
 
@@ -39,55 +36,55 @@ $Math.cos(float rad) -> float
 ```
 Returns the cosine of an angle (expressed in radians) `rad`.
 
-**Wraps** Java's [`Math.cos(double)`](https://docs.oracle.com/javase/8/docs/api/java/lang/Math.html#cos-double-) function
+**Wraps** Java's [`Math.cos(double)`![](./assets/external.png)](https://docs.oracle.com/javase/8/docs/api/java/lang/Math.html#cos-double-) function
 
 ### `sin`
 ```js
 $Math.sin(float rad) -> float
 ```
 Returns the sine of an angle (expressed in radians) `rad`.
 
-**Wraps** Java's [`Math.sin(double)`](https://docs.oracle.com/javase/8/docs/api/java/lang/Math.html#sin-double-) function
+**Wraps** Java's [`Math.sin(double)`![](./assets/external.png)](https://docs.oracle.com/javase/8/docs/api/java/lang/Math.html#sin-double-) function
 
 ### `tan`
 ```js
 $Math.tan(float rad) -> float
 ```
 Returns the tangent of an angle (expressed in radians) `rad`.
 
-**Wraps** Java's [`Math.tan(double)`](https://docs.oracle.com/javase/8/docs/api/java/lang/Math.html#tan-double-) function
+**Wraps** Java's [`Math.tan(double)`![](./assets/external.png)](https://docs.oracle.com/javase/8/docs/api/java/lang/Math.html#tan-double-) function
 
 ### `acos`
 ```js
 $Math.acos(float ratio) -> float
 ```
 Returns the arc cosine of `ratio`.
 
-**Wraps** Java's [`Math.acos(double)`](https://docs.oracle.com/javase/8/docs/api/java/lang/Math.html#acos-double-) function
+**Wraps** Java's [`Math.acos(double)`![](./assets/external.png)](https://docs.oracle.com/javase/8/docs/api/java/lang/Math.html#acos-double-) function
 
 ### `asin`
 ```js
 $Math.asin(float ratio) -> float
 ```
 Returns the arc sine of `ratio`.
 
-**Wraps** Java's [`Math.asin(double)`](https://docs.oracle.com/javase/8/docs/api/java/lang/Math.html#asin-double-) function
+**Wraps** Java's [`Math.asin(double)`![](./assets/external.png)](https://docs.oracle.com/javase/8/docs/api/java/lang/Math.html#asin-double-) function
 
 ### `atan`
 ```js
 $Math.atan(float ratio) -> float
 ```
 Returns the arc tangent of `ratio`.
 
-**Wraps** Java's [`Math.atan(double)`](https://docs.oracle.com/javase/8/docs/api/java/lang/Math.html#atan-double-) function
+**Wraps** Java's [`Math.atan(double)`![](./assets/external.png)](https://docs.oracle.com/javase/8/docs/api/java/lang/Math.html#atan-double-) function
 
 ### `sqrt`
 ```js
 $Math.sqrt(float n) -> float
 ```
 Returns the square root of a value `n`.
 
-**Wraps** Java's [`Math.sqrt(double)`](https://docs.oracle.com/javase/8/docs/api/java/lang/Math.html#sqrt-double-) function
+**Wraps** Java's [`Math.sqrt(double)`![](./assets/external.png)](https://docs.oracle.com/javase/8/docs/api/java/lang/Math.html#sqrt-double-) function
 
 ### `round`
 ```js
@@ -101,12 +98,12 @@ $Math.floor(float n) -> float
 ```
 Returns the largest integer less than or equal to `n`, expressed as a `float`.
 
-**Wraps** Java's [`Math.floor(double)`](https://docs.oracle.com/javase/8/docs/api/java/lang/Math.html#floor-double-) function
+**Wraps** Java's [`Math.floor(double)`![](./assets/external.png)](https://docs.oracle.com/javase/8/docs/api/java/lang/Math.html#floor-double-) function
 
 ### `ceil`
 ```js
 $Math.ceil(float n) -> float
 ```
 Returns the smallest integer greater than or equal to `n`, expressed as a `float`.
 
-**Wraps** Java's [`Math.ceil(double)`](https://docs.oracle.com/javase/8/docs/api/java/lang/Math.html#ceil-double-) function
+**Wraps** Java's [`Math.ceil(double)`![](./assets/external.png)](https://docs.oracle.com/javase/8/docs/api/java/lang/Math.html#ceil-double-) function

math.md

@@ -1,8 +1,8 @@
-# `palette`
-
 [`< API`](README.md)
 
-`palette`'s correspondent type in the Stippe Effect source code is [`Palette`](https://github.com/stipple-effect/stipple-effect/blob/master/src/com/jordanbunke/stipple_effect/palette/Palette.java).
+# `palette`
+
+`palette` objects created in scripts are internally represented by the [`Palette`![](./assets/external.png)](https://github.com/stipple-effect/stipple-effect/blob/master/src/com/jordanbunke/stipple_effect/palette/Palette.java) class from the *Stipple Effect* source code.
 
 ---