From afef3a622b0afb6d99a7a87e995c03a4606ee2d7 Mon Sep 17 00:00:00 2001
From: Douglas Hanley <thesecretaryofwar@gmail.com>
Date: Sat, 26 Oct 2024 15:37:54 -0500
Subject: [PATCH] add prompt text to top of docs code examples

---
 docs/code/arrays.js           |  4 ++--
 docs/code/axis.js             |  2 +-
 docs/code/barplot.js          |  6 +++---
 docs/code/circle.js           |  2 +-
 docs/code/colors.js           |  2 +-
 docs/code/container.js        |  2 +-
 docs/code/context.js          |  2 +-
 docs/code/element.js          |  2 +-
 docs/code/frame.js            |  2 +-
 docs/code/graph.js            |  2 +-
 docs/code/gum.js              |  2 +-
 docs/code/math.js             |  2 +-
 docs/code/note.js             |  2 +-
 docs/code/place.js            |  2 +-
 docs/code/plot.js             |  2 +-
 docs/code/points.js           |  2 +-
 docs/code/polyline.js         |  2 +-
 docs/code/rect.js             |  2 +-
 docs/code/stack.js            |  2 +-
 docs/code/sympath.js          |  2 +-
 docs/code/sympoints.js        |  2 +-
 docs/code/tex.js              |  2 +-
 docs/code/text.js             |  2 +-
 docs/code/titleframe.js       |  2 +-
 docs/examples/emoji_grid.js   |  9 +++++----
 docs/examples/network_grid.js | 37 ++++++++++-------------------------
 docs/examples/rotate.js       |  2 --
 27 files changed, 42 insertions(+), 60 deletions(-)
 delete mode 100644 docs/examples/rotate.js

diff --git a/docs/code/arrays.js b/docs/code/arrays.js
index e4020f2..6ddab9a 100644
--- a/docs/code/arrays.js
+++ b/docs/code/arrays.js
@@ -1,6 +1,6 @@
-// array example
+// a scatter plot of points with emojis for: mount fuji, a rocket, a whale, a watermellon, and a donut
 let emoji = zip(range(1, 6), ['🗻', '🚀', '🐋', '🍉', '🍩']);
 let points = Points(emoji.map(([i, e]) => [Text(e), [i, i]]), {size: 0.4});
 let plot = Plot(points, {xlim: [0, 6], ylim: [0, 6]});
 let frame = Frame(plot, {margin: 0.15});
-return frame;
\ No newline at end of file
+return frame;
diff --git a/docs/code/axis.js b/docs/code/axis.js
index c68db16..6c18009 100644
--- a/docs/code/axis.js
+++ b/docs/code/axis.js
@@ -1,4 +1,4 @@
-// goofy axis example
+// a horizontal axis with 5 ticks labeled with emojis for: mount fuji, a rocket, a whale, a watermellon, and a donut
 let ticks = zip(linspace(0, 1, 5), ['🗻', '🚀', '🐋', '🍉', '🍩']);
 let axis = Axis('h', ticks, {tick_size: 0.5, tick_pos: 'both'});
 let frame = Frame(axis, {aspect: 5, margin: [0.1, 1.3, 0.1, 0]});
diff --git a/docs/code/barplot.js b/docs/code/barplot.js
index e8e20c0..76ff057 100644
--- a/docs/code/barplot.js
+++ b/docs/code/barplot.js
@@ -1,6 +1,6 @@
-// bar plot with default and custom colors
-let abar = Bar({fill: '#ff0d57', stroke: 'black'});
-let bbar = Bar({fill: '#1e88e5', stroke: 'black'});
+// A plot with three bars with black borders at "A", "B", and "C". The first bar is red and is the shortest, the second bar is blue and is the tallest, while the third bar is gray.
+let abar = Bar({fill: red, stroke: 'black'});
+let bbar = Bar({fill: blue, stroke: 'black'});
 let bars = BarPlot([['A', [abar, 3]], ['B', [bbar, 8]], ['C', 6]], {
   ylim: [0, 10], yticks: 6, title: 'Example BarPlot',
   xlabel: 'Category', ylabel: 'Value', bar_fill: '#AAA'
diff --git a/docs/code/circle.js b/docs/code/circle.js
index afe8470..e784500 100644
--- a/docs/code/circle.js
+++ b/docs/code/circle.js
@@ -1,4 +1,4 @@
-// make a circle in a box
+// a circle placed off-center in a box
 let circle = Circle({pos: [0.4, 0.4], rad: 0.25});
 let frame = Frame(circle, {margin: 0.1, border: 1});
 return frame;
diff --git a/docs/code/colors.js b/docs/code/colors.js
index ec59adc..a74f6a8 100644
--- a/docs/code/colors.js
+++ b/docs/code/colors.js
@@ -1,4 +1,4 @@
-// fancy plot
+// A plot of an inverted sine wave where the line markers are sized in proportion to the amplitude and the color ranges from blue to red depending on the phase. The x-axis ticks are labeled with multiples of π. The x-axis is labeled "phase" and the y-axis is labeled "amplitude". The title is "Inverted Sine Wave".
 let xlim = [0, 2*pi], ylim = [-1, 1];
 let func = x => -sin(x);
 let pal = x => interpolateHex(blue, red, x);
diff --git a/docs/code/container.js b/docs/code/container.js
index fca3efa..8bde788 100644
--- a/docs/code/container.js
+++ b/docs/code/container.js
@@ -1,4 +1,4 @@
-// simple container example
+// a square in the top left and a circle in the bottom right
 return Container([
   [Rect(), [0.15, 0.15, 0.45, 0.45]],
   [Ellipse(), [0.55, 0.55, 0.85, 0.85]]
diff --git a/docs/code/context.js b/docs/code/context.js
index ef3f4f2..46f8e2f 100644
--- a/docs/code/context.js
+++ b/docs/code/context.js
@@ -1,4 +1,4 @@
-// see Element for usage in custom classes
+// create a square context of radius 50 centered at 100 and map [0.3, 0.5] to pixel coordinates
 let ctx = Context([50, 50, 150, 150]);
 let [fx, fy] = [0.3, 0.5];
 let [px, py] = ctx.coord_to_pixel([fx, fy]);
diff --git a/docs/code/element.js b/docs/code/element.js
index 1899afd..6bc9fcb 100644
--- a/docs/code/element.js
+++ b/docs/code/element.js
@@ -1,4 +1,4 @@
-// Element extension example (note the ".class"!)
+// create a custom triangle element called `Tri` and use it to create a triangle with a gray fill
 class Tri extends Element.class {
   constructor(p0, p1, p2, attr) {
     super('polygon', true, attr);
diff --git a/docs/code/frame.js b/docs/code/frame.js
index 0469ba4..73abf67 100644
--- a/docs/code/frame.js
+++ b/docs/code/frame.js
@@ -1,4 +1,4 @@
-// fancy frame for text a la Node
+// the text "hello!" in a frame with a dashed border and rounded corners
 let text = Text('hello!');
 let frame = Frame(text, {
   padding: 0.1, border: 1, margin: 0.1,
diff --git a/docs/code/graph.js b/docs/code/graph.js
index 3f2c154..13b364d 100644
--- a/docs/code/graph.js
+++ b/docs/code/graph.js
@@ -1,4 +1,4 @@
-// ride the snake
+// a series of closely spaced squares rotating clockwise along a sinusoidal path
 let sqr = x => Rotate(Square(), r2d*x);
 let boxes = SymPoints({
   fy: sin, fs: sqr, size: 0.4, xlim: [0, 2*pi], N: 150
diff --git a/docs/code/gum.js b/docs/code/gum.js
index efcd313..ff4d9f2 100644
--- a/docs/code/gum.js
+++ b/docs/code/gum.js
@@ -1,4 +1,4 @@
-// gum logo
+// The text "GUM" is a simple frame
 let text = Text('GUM');
 let frame = Frame(text, {padding: 0.1, border: 1, margin: 0.1});
 return frame;
diff --git a/docs/code/math.js b/docs/code/math.js
index f2d50a9..79da8be 100644
--- a/docs/code/math.js
+++ b/docs/code/math.js
@@ -1,4 +1,4 @@
-// example of using math in a plot
+// plot the exponential of sin(x) over [0, 2π]
 func = x => exp(sin(x));
 path = SymPath({fy: func, xlim: [0, 2*pi]});
 plot = Plot(path, {aspect: phi, ylim: [0, 3]});
diff --git a/docs/code/note.js b/docs/code/note.js
index 2204d98..555a853 100644
--- a/docs/code/note.js
+++ b/docs/code/note.js
@@ -1,4 +1,4 @@
-// add a note to a paricular place
+// plot the function 1 - x^2 and add a note on the top labeling the function
 let line = SymPath({fy: x => 1-x*x, xlim: [-1, 1]});
 let note = Note('1 - x^2', {pos: [0.025, 1.1], rad: 0.15, latex: true});
 let plot = Plot([line, note], {
diff --git a/docs/code/place.js b/docs/code/place.js
index 7779ac7..7ecab0c 100644
--- a/docs/code/place.js
+++ b/docs/code/place.js
@@ -1,4 +1,4 @@
-// plop down a rectangle
+// draw a rectangle in the top right that is rotated 20 degrees clockwise
 let rect = Rect();
 let place = Place(rect, {
   pos: [0.6, 0.4], rad: [0.2, 0.1], rotate: 20
diff --git a/docs/code/plot.js b/docs/code/plot.js
index 72787b3..39d97a1 100644
--- a/docs/code/plot.js
+++ b/docs/code/plot.js
@@ -1,4 +1,4 @@
-// semi-complex plot example
+// plot an inverted sine wave with ticks labeled in multiples of π. There is a faint dashed grid. The x-axis is labeled "phase" and the y-axis is labeled "amplitude". The title is "Inverted Sine Wave".
 let line = SymPath({fy: x => -sin(x), xlim: [0, 2*pi]});
 let xticks = linspace(0, 2, 6).slice(1).map(
   x => [x*pi, `${rounder(x, 1)} π`]
diff --git a/docs/code/points.js b/docs/code/points.js
index 169224a..0731fa8 100644
--- a/docs/code/points.js
+++ b/docs/code/points.js
@@ -1,4 +1,4 @@
-// spacetime vibes
+// A plot of three different increasing curves of varying steepness and multiple points spaced at regular intervals. The x-axis label is "time (seconds)", the y-axis label is "space (meters)", and the title is "Spacetime Vibes". There are axis ticks in both directions with assiated faint grid lines.
 let s = [0.5, 0.9, 1.5].map(a => SymPath({fy: x => sin(a*x), xlim: [-1, 1]}));
 let t = Points([[0, 0.5], [0.5, 0], [-0.5, 0], [0, -0.5]], {size: 0.015});
 let r = Points([[Rect(), [0.5, 0.5]], [Circle(), [-0.5, -0.5]]], {size: 0.1});
diff --git a/docs/code/polyline.js b/docs/code/polyline.js
index 1e5e830..39150bd 100644
--- a/docs/code/polyline.js
+++ b/docs/code/polyline.js
@@ -1,4 +1,4 @@
-// simple polyline (try switching Polyline to Polygon)
+// a square in the center of the figure that is missing its top side
 let poly = Polyline([
     [0.3, 0.3], [0.3, 0.7], [0.7, 0.7], [0.7, 0.3]
 ]);
diff --git a/docs/code/rect.js b/docs/code/rect.js
index 22dd62c..4770d05 100644
--- a/docs/code/rect.js
+++ b/docs/code/rect.js
@@ -1,4 +1,4 @@
-// make a rectangle
+// a rectangle on the left side of the figure with an aspect of roughly 1/2
 let rect = Rect({rect: [0.2, 0.2, 0.5, 0.7]});
 let frame = Frame(rect, {margin: 0.1});
 return frame;
diff --git a/docs/code/stack.js b/docs/code/stack.js
index 3d61d56..356f09c 100644
--- a/docs/code/stack.js
+++ b/docs/code/stack.js
@@ -1,4 +1,4 @@
-// mmm, stack it up!
+// one large donut in a frame stacked on top of two smaller side-by-side framed donuts
 let d = Node('🍩');
 let h = HStack([d, d]);
 let v = VStack([d, h]);
diff --git a/docs/code/sympath.js b/docs/code/sympath.js
index ff617e3..04359d2 100644
--- a/docs/code/sympath.js
+++ b/docs/code/sympath.js
@@ -1,4 +1,4 @@
-// inward triangular spiral
+// A gray line spiraling clockwise inward in a triangular path. The background is nearly black with rounded corners.
 let spiral = SymPath({
   fx: t => 0.43 + 0.5*exp(-0.05*t)*cos(t),
   fy: t => 0.48 + 0.5*exp(-0.05*t)*sin(t),
diff --git a/docs/code/sympoints.js b/docs/code/sympoints.js
index 2238cbe..cdf7b7e 100644
--- a/docs/code/sympoints.js
+++ b/docs/code/sympoints.js
@@ -1,4 +1,4 @@
-// create spiral of squares
+// Various simple shapes spiraling inwards. The shapes have black borders and semi-transparent fills. They are tinted blue at the outside and red towards the inside. They are framed by a circle with a black border and a gray background.
 let freq = 38*pi;
 let shapes = [Circle, Square, Triangle];
 let pal = t => interpolateHex(red, blue, t/freq);
diff --git a/docs/code/tex.js b/docs/code/tex.js
index 9770b2b..8928d5e 100644
--- a/docs/code/tex.js
+++ b/docs/code/tex.js
@@ -1,4 +1,4 @@
-// some useful identities
+// There are two latex equations framed by rounded borders arranged vertically. The top one shows a Gaussian integral and the bottom one shows a trigonometric identity. They are framed by a square with the title "Facts".
 let tex1 = Tex('\\int_0^{\\infty} \\exp(-x^2) dx = \\sqrt{\\pi}');
 let tex2 = Tex('\\sin^2(\\theta) + \\cos^2(\\theta) = 1');
 let node1 = Node(tex1, {border_radius: 0.05});
diff --git a/docs/code/text.js b/docs/code/text.js
index b889a23..67a27f2 100644
--- a/docs/code/text.js
+++ b/docs/code/text.js
@@ -1,3 +1,3 @@
-// text greeting
+// The text "Hello World!" in bold is placed near the botton left of the figure, which has an aspect of roughly 2.
 let text = Text('Hello World!', {font_weight: 'bold'});
 return Place(text, {pos: [0.35, 0.7], rad: 0.2, aspect: phi});
diff --git a/docs/code/titleframe.js b/docs/code/titleframe.js
index 4f238a0..05f5e3d 100644
--- a/docs/code/titleframe.js
+++ b/docs/code/titleframe.js
@@ -1,4 +1,4 @@
-// mmm... pineapple pizza
+// Various food emojis are arrnaged in a spaced out grid and framed with the title "Fruits & Veggies". Each emoji is framed by a rounded square with a gray background.
 let emojis = ['🍇', '🥦', '🍔', '🍉', '🍍', '🌽', '🍩', '🥝', '🍟'];
 let nodes = emojis.map(e => Node(e, {border_radius: 0.075, fill: '#e6e6e6'}));
 let grid = Grid(split(nodes, 3), {spacing: 0.05});
diff --git a/docs/examples/emoji_grid.js b/docs/examples/emoji_grid.js
index 6ca0ce1..e733f7d 100644
--- a/docs/examples/emoji_grid.js
+++ b/docs/examples/emoji_grid.js
@@ -1,9 +1,10 @@
 // Four by three grid of boxes, each with a different emoji in it. The emojis are a random selection of fruits and candies.
-let data = [
+let emoji = [
   '🍩🍦🍨🍫🍌',
   '🍕🍉🍒🍇🍐',
   '🥝🍎🍓🍬🍪',
-]
-let rows = data.map(s => [...s].map(c => Node(c, {aspect: 1})));
-let grid = Grid(rows);
+];
+let nodes = emoji.map(row => [...row].map(s => Node(s, {flex: true})));
+let aspect = max(...nodes.map(r => r.length))/nodes.length;
+let grid = Grid(nodes, {aspect});
 return Frame(grid, {margin: 0.1});
diff --git a/docs/examples/network_grid.js b/docs/examples/network_grid.js
index 7c81e8b..69856b6 100644
--- a/docs/examples/network_grid.js
+++ b/docs/examples/network_grid.js
@@ -1,29 +1,12 @@
 // Three rows of nodes connected by lines. The first row has three nodes for product categories 1, 2, and 3. The second row has three nodes for Wikipedia text 1, 2, and 3. And the third row has five notes for patent abstract 1 through 5. The first two rows are connected by bi-directional filled in arrows. The second and third rows are partially connected by curved lines.
-
-// define cell data
-let locs = range(5).map(i => 0.2*i+0.1);
-let cells1 = [null, ...range(1, 4).map(i => ['Product', `Category ${i}`]), null];
-let cells2 = [null, ...range(1, 4).map(i => ['Wikipedia', `Text ${i}`]), null];
-let cells3 = range(1, 6).map(i => ['Patent', `Abstract ${i}`]);
-
-// make cell rows
-let noder = s => (s == null) ? Spacer() : Node(s, {
-  aspect: 3, padding: 0.2, flex: true, border_radius: 0.05
+let conns = [[1, 1], [1, 2], [3, 3], [2, 4], [3, 5]];
+return Network([
+  ...range(1, 4).map(i => [`pc${i}`, ['Product'  , `Category ${i}`], [i+1, 1], 0.4]),
+  ...range(1, 4).map(i => [`wt${i}`, ['Wikipedia', `Text ${i}`    ], [i+1, 3], 0.4]),
+  ...range(1, 6).map(i => [`pa${i}`, ['Patent'   , `Abstract ${i}`], [i  , 5], 0.4]),
+], [
+  ...range(1, 4).map(i => [`pc${i}`, `wt${i}`, {arrow: true}]),
+  ...conns.map(([i1, i2]) => [[`wt${i1}`, 'south'], [`pa${i2}`, 'north']])
+], {
+  aspect: phi, coord: [0, 0, 6, 6], node_border_radius: 0.05, edge_arrow_size: 0.1
 });
-let [row1, row2, row3] = [cells1, cells2, cells3].map(
-  c => HStack(c.map(noder), {spacing: 0.02})
-);
-
-// make various edges
-let bidi = Edge([0.5, 0], [0.5, 1], {
-  arrow_beg: true, arrow_end: true, arrow_size: [0.1, 0.075], arrow_fill: '#DDD', arrow_base: true
-});
-let edges1 = HStack([Spacer(), bidi, bidi, bidi, Spacer()]);
-let elocs2 = [[0, 1], [1, 1], [2, 3], [3, 2], [4, 3]].map(
-  ([x1, x2]) => [[locs[x1], 1], [locs[x2], 0]]
-);
-let edges2 = Group(elocs2.map(([p1, p2]) => Edge(p1, p2)));
-
-// stack together and frame
-let rows = VStack([row1, edges1, row2, edges2, row3], {aspect: phi});
-return Frame(rows, {margin: 0.05});
diff --git a/docs/examples/rotate.js b/docs/examples/rotate.js
deleted file mode 100644
index 26e2dd6..0000000
--- a/docs/examples/rotate.js
+++ /dev/null
@@ -1,2 +0,0 @@
-// A rectangle with aspect ratio 2 placed in the top right and rotated 20 degrees clockwise.
-return Place(Rect(), {pos: [0.65, 0.3], rad: [0.2, 0.1], rotate: 20});