document more libs

docs/lib/arquero.md

@@ -1,6 +1,6 @@
 # Arquero
 
-[Arquero](https://uwdata.github.io/arquero/) is a JavaScript library for “query processing and transformation of array-backed data tables.” Arquero (currently version ${aq.version}) is available by default as `aq` in Markdown, but you can import it explicitly like so:
+[Arquero](https://uwdata.github.io/arquero/) is a JavaScript library for “query processing and transformation of array-backed data tables.” Arquero is available by default as `aq` in Markdown, but you can import it explicitly like so:
 
 ```js echo
 import * as aq from "npm:arquero";

docs/lib/arrow.md

@@ -1,5 +1,28 @@
 # Apache Arrow
 
+[Apache Arrow](https://arrow.apache.org/) defines a language-independent columnar memory format for flat and hierarchical data, organized for efficient analytic operations. You will probably not consume it directly, but it is used by [Arquero](arquero), [DuckDB](duckdb), and other libraries to handle data efficiently.
+
+Apache Arrow is available by default as `Arrow` in Markdown, but you can import it explicitly like so:
+
 ```js echo
 import * as Arrow from "npm:apache-arrow";
 ```
+
+For example, let’s create a table representing a year’s worth of random walk:
+
+```js echo
+const date = d3.utcDay.range(new Date("2023-01-01"), new Date("2024-01-02"));
+const random = d3.randomNormal.source(d3.randomLcg(42))(); // seeded random
+const value = d3.cumsum(date, random);
+const table = Arrow.tableFromArrays({date, value});
+display([...table]);
+```
+
+```js echo
+display(Plot.plot({
+  marks: [
+    Plot.ruleY([0]),
+    Plot.lineY(table, {x: "date", y: "value"})
+  ]
+}));
+```

docs/lib/d3.md

@@ -1,5 +1,13 @@
 # D3
 
+[D3](https://d3js.org) (or D3.js) is a free, open-source JavaScript library for visualizing data. Its low-level approach built on web standards offers unparalleled flexibility in authoring dynamic, data-driven graphics.
+
+D3 is available by default as `d3` in Markdown, but you can import it explicitly like so:
+
 ```js echo
 import * as d3 from "npm:d3";
 ```
+
+We recommend using [Observable Plot](plot) if you want to create _simple_ charts from your data; but for more complex needs, including interactivity and animations, and more generally for bespoke data visualization, you will most probably want to use D3.
+
+Check out [D3’s extensive documentation](https://d3js.org/) for examples.

docs/lib/dot.md

@@ -41,11 +41,12 @@ digraph G {
   subgraph cluster_0 {
     a0 -> a1 -> a2 -> a3
     label = "process #1"
+    color = lightblue
   }
   subgraph cluster_1 {
     b0 -> b1 -> b2 -> b3
     label = "process #2"
-    color = blue
+    color = orange
   }
   start -> a0
   start -> b0
@@ -54,7 +55,7 @@ digraph G {
   a3 -> a0
   a3 -> end
   b3 -> end
-  start [shape = Mdiamond]
-  end [shape = Msquare]
+  start [shape = diamond]
+  end [shape = square]
 }
 ```

docs/lib/htl.md

@@ -1,13 +1,45 @@
 # Hypertext Literal
 
+[Hypertext Literal](https://github.com/observablehq/htl) is a tagged template literal for HTML which interpolates _values based on context_, allowing automatic escaping and the interpolation of non-serializable values.
+
+Hypertext Literal is available by default as `htl` in Markdown, together with its methods `html` and `svg`. You can import it explicitly like so:
+
 ```js echo
 import {html} from "npm:htl";
 ```
 
+```js echo
+html`<span ${{
+  style: {
+    background: "yellow",
+    padding: "3px",
+    cursor: "pointer",
+    userSelect: "none"
+  },
+  onclick() {
+    this.style.background = d3.interpolateRainbow(Math.random());
+  }
+}}>Click me!</span>`
+```
+
+The `svg` method likewise generates contextual SVG fragments, which can be useful, say, to position two charts side by side:
+
 ```js echo
 import {svg} from "npm:htl";
 ```
 
+```js echo
+const chart1 = Plot.barY([3, 4, 2, 7, 5]).plot({width: 120, height: 80});
+const chart2 = Plot.barY([5, 1, 7, 6, 2]).plot({width: 120, height: 80});
+display(svg`<svg width=260 height=80>
+  <g>${chart1}</g>
+  <g ${{transform: "translate(140,0)"}}>${chart2}</g>
+</svg>`);
+```
+
+If you prefer using `htl.html` and `htl.svg`, just import everything:
+
 ```js echo
 import * as htl from "npm:htl";
 ```
+

docs/lib/inputs.md

@@ -1,9 +1,19 @@
 # Observable Inputs
 
+[Observable Inputs](https://github.com/observablehq/inputs) provides lightweight interface components — buttons, sliders, dropdowns, tables, and the like — to help you explore data and build interactive displays.
+
+Observable Inputs is available by default as `Inputs` in Markdown, but you can import it explicitly like so:
+
 ```js echo
 import * as Inputs from "npm:@observablehq/inputs";
 ```
 
+or just import the inputs you use:
+
+```js echo
+import {Button, Color} from "npm:@observablehq/inputs";
+```
+
 These basic inputs will get you started.
 
 * [Button](#button) - do something when a button is clicked

docs/lib/leaflet.md

@@ -1,12 +1,18 @@
 # Leaflet
 
+[Leaflet](https://leafletjs.com/) is an open-source JavaScript library for mobile-friendly interactive maps.
+
+Leaflet is available by default as `L` in Observable markdown, you can also import it explicitly:
+
 ```js echo
 import * as L from "npm:leaflet";
 ```
 
+To create a map, follow the [tutorial](https://leafletjs.com/examples/quick-start/):
+
 ```js echo
 const div = Object.assign(display(document.createElement("div")), {style: "height: 400px;"});
 const map = L.map(div).setView([51.505, -0.09], 13);
 L.tileLayer("https://tile.openstreetmap.org/{z}/{x}/{y}.png").addTo(map);
-L.marker([51.5, -0.09]).addTo(map).bindPopup("A pretty CSS popup.<br> Easily customizable.").openPopup();
+L.marker([51.5, -0.09]).addTo(map).bindPopup("A nice popup<br> indicating a point of interest.");
 ```

docs/lib/plot.md

@@ -1,9 +1,35 @@
 # Observable Plot
 
+[Observable Plot](https://observablehq.com/plot/) is a JavaScript library for exploratory data visualization, made by the same team as [D3](d3). Plot is available by default as `Plot` in Markdown, but you can import it explicitly like so:
+
 ```js echo
 import * as Plot from "npm:@observablehq/plot";
 ```
 
+To display a chart in Observable Markdown, simply call `Plot.plot` in a JavaScript expression code block:
+
+````md
+```js
+Plot.plot({
+  marks: [
+    Plot.barY(alphabet, {x: "letter", y: "frequency"})
+  ]
+})
+```
+````
+
+For example, here’s a Voronoi chart:
+
 ```js echo
-Plot.frame().plot()
+const random = d3.randomLcg(42);
+const chart = Plot.voronoi(Array.from({length: 100}, () => [random(), random()])).plot({nice: true}); 
+
+display(chart);
 ```
+
+Or, to include a ${Plot.lineY([1, 2, 0, 4, 0, 3, 1, 5, 7, 2, 3]).plot({axis: null, width: 80, height: 18})} sparkline in your text — or bars ${Plot.barY([1, 2, 4, 3, 1, 5], {fill: Plot.identity}).plot({axis: null, width: 80, height: 18})} — just call:
+
+```md
+… include a ${Plot.lineY([1, 2, 0, 4, 0, 3, 1, 5, 7, 2, 3]).plot({axis: null, width: 80, height: 18})} sparkline…
+… bars ${Plot.lineY([1, 2, 4, 3, 1, 5], {fill: Plot.identity}).plot({axis: null, width: 80, height: 18})} — just…
+```

docs/lib/tex.md

@@ -52,3 +52,5 @@ c = \pm\sqrt{a^2 + b^2}
     \f\hat\xi\,e^{2 \pi i \xi x}
     \,d\xi
 ```
+
+For more, see [the documentation website](https://katex.org/), in particular the [list of supported functions](https://katex.org/docs/supported).

docs/lib/topojson.md

@@ -1,5 +1,57 @@
 # TopoJSON
 
-```js echo
+[TopoJSON](https://github.com/topojson/topojson) is an extension of [GeoJSON](https://geojson.org/), a format for encoding geometry and geographic data structures, that further encodes topology.
+
+The [TopoJSON client](https://github.com/topojson/topojson-client) library for working with TopoJSON is available in Observable Markdown as `topojson`, allowing you to transform compact TopoJSON files to GeoJSON and display a map with — for instance — [Leaflet](leaflet), [D3](d3), or [Observable Plot](plot).
+
+If you prefer to import the TopoJSON client explicitly:
+
+```js echo run=false
 import * as topojson from "npm:topojson-client";
 ```
+
+For an example, let’s load a file that describes the counties, states and general outline of the United States, already projected using [Albers’ equal area-conic projection](https://d3js.org/d3-geo/conic#geoAlbersUsa) to a frame of 975×610 pixels:
+
+```js echo
+const us = FileAttachment("counties-albers-10m.json").json();
+```
+
+We can then create a GeoJSON object for each feature we want to display. First, the general outline of the nation:
+
+```js echo
+const nation = topojson.feature(us, us.objects.nation);
+```
+
+The counties mesh, which includes each of the delimitations once (instead of once per county). This avoids an additional stroke on the perimeter of the map, which would otherwise mask intricate features such as islands and inlets.
+
+```js echo
+const countiesmesh = topojson.mesh(us, us.objects.counties);
+```
+
+The _statemesh_ likewise contains the internal borders between states, _i.e._, everything but the coastlines and country borders.
+
+```js echo
+const statemesh = topojson.mesh(us, us.objects.states, (a, b) => a !== b)
+```
+
+```js echo
+Plot.plot({
+  projection: "identity",
+  width: 975,
+  height: 610,
+  marks: [
+    Plot.geo(countiesmesh, {strokeOpacity: 0.5}),
+    Plot.geo(statemesh, {strokeWidth: 0.75}),
+    Plot.geo(nation, {strokeWidth: 1.5})
+  ]
+})
+```
+
+If you need to manipulate topologies, for example to simplify the shapes on-the-fly, you may need to import the [TopoJSON server](https://github.com/topojson/topojson-server) and [TopoJSON simplify](https://github.com/topojson/topojson-simplify) libraries, too.
+
+```js echo run=false
+import {topology} from "npm:topojson-server";
+import {presimplify, simplify} from "npm:topojson-simplify";
+```
+
+For more details, please refer to the [TopoJSON documentation](https://github.com/topojson).