Clean up description of self-hosted BQN instances

4 files changed, 23 insertions, 13 deletions

diff --git a/docs/implementation/vm.html b/docs/implementation/vm.html
index 57f328e6..5a6e77c4 100644
--- a/docs/implementation/vm.html
+++ b/docs/implementation/vm.html
@@ -5,7 +5,8 @@
 </head>
 <div class="nav"><a href="https://github.com/mlochbaum/BQN">BQN</a> / <a href="../index.html">main</a> / <a href="index.html">implementation</a></div>
 <h1 id="the-bqn-virtual-machine-and-runtime">The BQN virtual machine and runtime</h1>
-<p>BQN's self-hosted compiler and runtime mean that only a small amount of native code is needed to run BQN on any given platform. For example, the <a href="https://github.com/mlochbaum/BQN/blob/master/implementation/../docs/bqn.js">Javascript environment</a> requires about 300 lines of Javascript code even though it compiles BQN bytecode to Javascript, a more complex strategy than interpreting it directly. This makes it fairly easy to port BQN to new platforms, allowing BQN to run &quot;natively&quot; within other programming languages and interact with arrays in those languages.</p>
+<p>BQN's self-hosted compiler and runtime mean that only a small amount of native code is needed to run BQN on any given platform. For example, the <a href="https://github.com/mlochbaum/BQN/blob/master/implementation/../docs/bqn.js">Javascript environment</a> requires about 300 lines of Javascript code even though it compiles BQN bytecode to Javascript, a more complex strategy than interpreting it directly. This makes it fairly easy to port BQN to new platforms, allowing BQN to be <a href="../doc/embed.html">embedded</a> within other programming languages and interact with arrays or functions in those languages.</p>
+<p>The way data is represented is part of the VM implementation: it can use native arrays or a custom data structure, depending on what the language supports. An initial implementation will be very slow, but can be improved by replacing functions from the BQN-based runtime with native code. As the VM system can be hard to work with if you're not familiar with it, I advise you to contact me to discuss implementing a VM if you are interested.</p>
 <h2 id="bytecode">Bytecode</h2>
 <p>The BQN implementation here and dzaima/BQN share a stack-based object code format used to represent compiled code. This format is a list of numbers of unspecified precision (small precision will limit the length of list literals and number of locals per block, blocks, and constants). Previously it was encoded as bytes with the <a href="https://en.wikipedia.org/wiki/LEB128">LEB128</a> format; while it no longer has anything to do with bytes it's called a &quot;bytecode&quot; because this is shorter than &quot;object code&quot;.</p>
 <p>The self-hosted compiler uses a simpler, and less capable, format for block and variable data than dzaima/BQN. Only this format is described here; <a href="https://github.com/mlochbaum/BQN/blob/master/implementation/../dc.bqn">dc.bqn</a> adapts it to be compatible with dzaima/BQN.</p>
diff --git a/docs/running.html b/docs/running.html
index 457941ce..10e72c01 100644
--- a/docs/running.html
+++ b/docs/running.html
@@ -5,12 +5,17 @@
 </head>
 <div class="nav"><a href="https://github.com/mlochbaum/BQN">BQN</a> / <a href="index.html">main</a></div>
 <h1 id="how-to-run-bqn">How to run BQN</h1>
-<p>There are currently two active BQN implementations: the self-hosted one in this repository, and the independent dzaima/BQN. Neither is entirely complete but they are quite capable for pure programming tasks (say, implementing a compiler). dzaima/BQN has good performance while self-hosted is about a thousand times slower. I tend to develop parts of applications in the online REPL and move to dzaima/BQN scripts in order to run them.</p>
-<h3 id="bqn">BQN</h3>
+<p>There are currently two active BQN implementations: the self-hosted one in this repository, and the independent dzaima/BQN. Neither is entirely complete but they are quite capable for pure programming tasks (say, implementing a compiler). dzaima/BQN has good performance while self-hosted is a few hundred times slower. I tend to develop parts of applications in the online REPL and move to dzaima/BQN scripts in order to run them.</p>
+<h3 id="self-hosted-bqn">Self-hosted BQN</h3>
 <p>The online REPL is <a href="https://mlochbaum.github.io/BQN/try.html">here</a>. The file <a href="https://github.com/mlochbaum/BQN/blob/master/docs/bqn.js">docs/bqn.js</a> is zero-dependency Javascript, and can be loaded from HTML or Node.js. For command line use, call the Node.js script <a href="https://github.com/mlochbaum/BQN/blob/master/bqn.js">bqn.js</a>, passing a file and <code><span class='Value'>•args</span></code>, or <code><span class='Function'>-</span><span class='Value'>e</span></code> to execute all remaining arguments directly and print the results. <a href="https://observablehq.com/@lsh/bqn">This notebook</a> shows how to run it in an Observable notebook.</p>
-<p>The version of BQN in this repository is implemented mainly in BQN itself—the compiler is entirely self-hosted, while the runtime is built from a small number of starting functions using preprocessed BQN. It completely supports the core language except for block headers and multiple body syntax, and a few cases of structural Under (<code><span class='Modifier2'>⌾</span></code>). The Javascript-based compiler is also slow, taking about 0.01 seconds plus 0.3 seconds per kilobyte of source (this is purely due to the slow runtime, as dzaima+reference achieves 1ms/kB with the same compiler once warmed up).</p>
-<p>Because self-hosted BQN requires only a simple virtual machine to run, it is <a href="implementation/vm.html">fairly easy</a> to embed it in another programming language by implementing this virtual machine. The way data is represented is part of the VM implementation: it can use native arrays or a custom data structure, depending on what the language supports. An initial implementation will be very slow, but can be improved by replacing functions from the BQN-based runtime with native code. As the VM system can be hard to work with if you're not familiar with it, I advise you to contact me to discuss this option it you are interested.</p>
-<p>In progress VMs are <a href="https://github.com/dzaima/CBQN">CBQN</a> in C, and <a href="https://github.com/cannadayr/ebqn">ebqn</a> in Erlang. Although both of these execute BQN just like the JS version, neither is considered useful for any purpose yet. CBQN is likely to become the main high-performance BQN implementation but is currently only a few times faster than Javascript and has an interface that's only useful for testing. ebqn is extremely slow—hours to compile.</p>
+<p>Fully supports all primitives except a few cases of structural Under (<code><span class='Modifier2'>⌾</span></code>), but still missing some advanced features: namespaces, block headers and multiple body syntax, derived 1-modifiers, and block returns.</p>
+<p>This version of BQN is <a href="implementation/index.html">implemented</a> mainly in BQN itself, but a host language supplies basic functionality and can also replace primitives for better performance. This also allows <a href="doc/embed.html">embedding</a>, where programs in the host language can include BQN code. Support in the following languages has been implemented:</p>
+<ul>
+<li>Javascript; see above. Slow (compiles at ~5kB/s) but usable.</li>
+<li>dzaima/BQN (<a href="https://github.com/mlochbaum/BQN/blob/master/bqn.bqn">bqn.bqn</a>), mainly for testing.</li>
+<li><a href="https://github.com/dzaima/CBQN">C</a>, for an eventual high-performace implementation. Currently slower than dzaima/BQN and missing usability features.</li>
+<li><a href="https://github.com/cannadayr/ebqn">Erlang</a>, intended for embedding. Too slow to be practical yet: minutes to compile short programs.</li>
+</ul>
 <h3 id="dzaimabqn">dzaima/BQN</h3>
 <p><a href="https://github.com/dzaima/BQN/">dzaima/BQN</a> is an implementation in Java created by modifying the existing dzaima/APL. It should be easy to run on desktop Linux and Android. It is still in development and has almost complete syntax support but incomplete primitive support: major missing functionality is dyadic Depth (<code><span class='Modifier2'>⚇</span></code>), Windows (<code><span class='Function'>↕</span></code>), and many cases of set functions (<code><span class='Function'>⊐⊒∊⍷</span></code>, mostly with rank &gt;1).</p>
 <p>In this repository and elsewhere, dzaima/BQN scripts are called with <code><span class='Comment'>#! /usr/bin/env dbqn</span></code>. This requires an executable file <code><span class='Value'>dbqn</span></code> somewhere in your path with the following contents:</p>
diff --git a/implementation/vm.md b/implementation/vm.md
index c9d089d9..0211bd1d 100644
--- a/implementation/vm.md
+++ b/implementation/vm.md
@@ -2,7 +2,9 @@
 
 # The BQN virtual machine and runtime
 
-BQN's self-hosted compiler and runtime mean that only a small amount of native code is needed to run BQN on any given platform. For example, the [Javascript environment](../docs/bqn.js) requires about 300 lines of Javascript code even though it compiles BQN bytecode to Javascript, a more complex strategy than interpreting it directly. This makes it fairly easy to port BQN to new platforms, allowing BQN to run "natively" within other programming languages and interact with arrays in those languages.
+BQN's self-hosted compiler and runtime mean that only a small amount of native code is needed to run BQN on any given platform. For example, the [Javascript environment](../docs/bqn.js) requires about 300 lines of Javascript code even though it compiles BQN bytecode to Javascript, a more complex strategy than interpreting it directly. This makes it fairly easy to port BQN to new platforms, allowing BQN to be [embedded](../doc/embed.md) within other programming languages and interact with arrays or functions in those languages.
+
+The way data is represented is part of the VM implementation: it can use native arrays or a custom data structure, depending on what the language supports. An initial implementation will be very slow, but can be improved by replacing functions from the BQN-based runtime with native code. As the VM system can be hard to work with if you're not familiar with it, I advise you to contact me to discuss implementing a VM if you are interested.
 
 ## Bytecode
 
diff --git a/running.md b/running.md
index 5df36550..a09ce488 100644
--- a/running.md
+++ b/running.md
@@ -2,17 +2,19 @@
 
 # How to run BQN
 
-There are currently two active BQN implementations: the self-hosted one in this repository, and the independent dzaima/BQN. Neither is entirely complete but they are quite capable for pure programming tasks (say, implementing a compiler). dzaima/BQN has good performance while self-hosted is about a thousand times slower. I tend to develop parts of applications in the online REPL and move to dzaima/BQN scripts in order to run them.
+There are currently two active BQN implementations: the self-hosted one in this repository, and the independent dzaima/BQN. Neither is entirely complete but they are quite capable for pure programming tasks (say, implementing a compiler). dzaima/BQN has good performance while self-hosted is a few hundred times slower. I tend to develop parts of applications in the online REPL and move to dzaima/BQN scripts in order to run them.
 
-### BQN
+### Self-hosted BQN
 
 The online REPL is [here](https://mlochbaum.github.io/BQN/try.html). The file [docs/bqn.js](docs/bqn.js) is zero-dependency Javascript, and can be loaded from HTML or Node.js. For command line use, call the Node.js script [bqn.js](bqn.js), passing a file and `•args`, or `-e` to execute all remaining arguments directly and print the results. [This notebook](https://observablehq.com/@lsh/bqn) shows how to run it in an Observable notebook.
 
-The version of BQN in this repository is implemented mainly in BQN itself—the compiler is entirely self-hosted, while the runtime is built from a small number of starting functions using preprocessed BQN. It completely supports the core language except for block headers and multiple body syntax, and a few cases of structural Under (`⌾`). The Javascript-based compiler is also slow, taking about 0.01 seconds plus 0.3 seconds per kilobyte of source (this is purely due to the slow runtime, as dzaima+reference achieves 1ms/kB with the same compiler once warmed up).
+Fully supports all primitives except a few cases of structural Under (`⌾`), but still missing some advanced features: namespaces, block headers and multiple body syntax, derived 1-modifiers, and block returns.
 
-Because self-hosted BQN requires only a simple virtual machine to run, it is [fairly easy](implementation/vm.md) to embed it in another programming language by implementing this virtual machine. The way data is represented is part of the VM implementation: it can use native arrays or a custom data structure, depending on what the language supports. An initial implementation will be very slow, but can be improved by replacing functions from the BQN-based runtime with native code. As the VM system can be hard to work with if you're not familiar with it, I advise you to contact me to discuss this option it you are interested.
-
-In progress VMs are [CBQN](https://github.com/dzaima/CBQN) in C, and [ebqn](https://github.com/cannadayr/ebqn) in Erlang. Although both of these execute BQN just like the JS version, neither is considered useful for any purpose yet. CBQN is likely to become the main high-performance BQN implementation but is currently only a few times faster than Javascript and has an interface that's only useful for testing. ebqn is extremely slow—hours to compile.
+This version of BQN is [implemented](implementation/README.md) mainly in BQN itself, but a host language supplies basic functionality and can also replace primitives for better performance. This also allows [embedding](doc/embed.md), where programs in the host language can include BQN code. Support in the following languages has been implemented:
+- Javascript; see above. Slow (compiles at ~5kB/s) but usable.
+- dzaima/BQN ([bqn.bqn](bqn.bqn)), mainly for testing.
+- [C](https://github.com/dzaima/CBQN), for an eventual high-performace implementation. Currently slower than dzaima/BQN and missing usability features.
+- [Erlang](https://github.com/cannadayr/ebqn), intended for embedding. Too slow to be practical yet: minutes to compile short programs.
 
 ### dzaima/BQN