Better organization for implementation README files

docs/implementation/compile/index.html

@@ -6,9 +6,15 @@
 </head>
 <div class="nav">(<a href="https://github.com/mlochbaum/BQN">github</a>) / <a href="../../index.html">BQN</a> / <a href="../index.html">implementation</a></div>
 <h1 id="optimizing-compilation-notes"><a class="header" href="#optimizing-compilation-notes">Optimizing compilation notes</a></h1>
-<p>Pages here discuss advanced compilation strategies for BQN, that is, steps that might take take place after compiling to bytecode or a similar intermediate representation.</p>
-<p>Most content here is currently speculative: C, Java, and Javascript backends are capable of compiling to native (x86, JVM, or Javascript) code in order to lower evaluation overhead but don't perform much if any analysis to improve this code. CBQN is likely to start making such optimizations in the future.</p>
+<p>Pages in this directory discuss advanced compilation strategies for BQN, that is, steps that might take take place after compiling to bytecode or a similar intermediate representation. Most content here is currently speculative: C, Java, and Javascript backends are capable of compiling to native (x86, JVM, or Javascript) code in order to lower evaluation overhead but don't perform much if any analysis to improve this code. CBQN is likely to start making such optimizations in the future.</p>
 <ul>
 <li><a href="intro.html">Array language compilation in context</a>, an introduction to the subject</li>
 <li><a href="dynamic.html">Dynamic compilation</a>, discussing high-level strategies</li>
 </ul>
+<p>The self-hosted bytecode compiler isn't really documented, but there are some related resources elsewhere. I held a few early chat discussions on building an array-based compiler, but aborted these because the interactive format wasn't doing too much.</p>
+<ul>
+<li><a href="../codfns.html">Comparison to Co-dfns</a>, the other array-based compiler (plus the newer Pareas).</li>
+<li>Chat: <a href="https://chat.stackexchange.com/rooms/52405/conversation/lesson-s1-parenthesis-nesting-level">Parenthesis nesting level</a></li>
+<li>Chat: <a href="https://chat.stackexchange.com/rooms/52405/conversation/lesson-s2-infix-to-rpn">Infix to RPN</a></li>
+<li>Chat: <a href="https://chat.stackexchange.com/rooms/52405/conversation/lesson-s3-parsing-expressions-with-parentheses">Parsing expressions with parentheses</a></li>
+</ul>

docs/implementation/index.html

@@ -6,18 +6,11 @@
 </head>
 <div class="nav">(<a href="https://github.com/mlochbaum/BQN">github</a>) / <a href="../index.html">BQN</a></div>
 <h1 id="bqn-implementation-notes"><a class="header" href="#bqn-implementation-notes">BQN implementation notes</a></h1>
+<center>
+
+<p><a href="primitive/index.html">primitives</a> • <a href="compile/index.html">compiling</a> • <a href="perf.html">state of CBQN</a> • <a href="vm.html">VM documentation</a></p>
+</center>
+
 <p>Notes about how BQN is or could be implemented.</p>
 <p>This repository's BQN implementation is written mainly in BQN: the bytecode <a href="https://github.com/mlochbaum/BQN/blob/master/implementation/../src/c.bqn">compiler</a> is completely self-hosted, and the majority of the runtime (<a href="https://github.com/mlochbaum/BQN/blob/master/implementation/../src/r0.bqn">r0</a>, <a href="https://github.com/mlochbaum/BQN/blob/master/implementation/../src/r1.bqn">r1</a>) is written in BQN except that it is allowed to define primitives; some preprocessing (<a href="https://github.com/mlochbaum/BQN/blob/master/implementation/../src/pr.bqn">pr</a>) turns the primitives into identifiers.</p>
-<p>The remaining part, a Virtual Machine (VM), can be implemented in any language to obtain a version of BQN running in that language. The VM used for the online REPL is the <a href="https://github.com/mlochbaum/BQN/blob/master/implementation/../docs/bqn.js">Javascript implementation</a>, while <a href="https://github.com/dzaima/CBQN">CBQN</a> is a more advanced VM in C. <a href="https://github.com/dzaima/CBQN/blob/master/src/README.md">This page</a> gives an introduction to the CBQN source code. There are platform-specific and generic tests in the <a href="https://github.com/mlochbaum/BQN/blob/master/implementation/../test/">test</a> directory.</p>
-<ul>
-<li><a href="vm.html">The BQN virtual machine and runtime</a>: the non-self-hosted parts of the BQN implementation, or those needed to port it to a new platform.</li>
-<li><a href="primitive/index.html">Notes on implementing primitives</a></li>
-<li><a href="compile/index.html">Notes on compilation</a></li>
-<li><a href="codfns.html">Comparison to Co-dfns</a>, the other array-based compiler (plus the newer Pareas).</li>
-</ul>
-<p>I held a few early forum discussions on the workings of the self-hosted compiler, but aborted these because the interactive format wasn't doing too much. I haven't yet started on non-interactive replacements.</p>
-<ul>
-<li><a href="https://chat.stackexchange.com/rooms/52405/conversation/lesson-s1-parenthesis-nesting-level">Parenthesis nesting level</a></li>
-<li><a href="https://chat.stackexchange.com/rooms/52405/conversation/lesson-s2-infix-to-rpn">Infix to RPN</a></li>
-<li><a href="https://chat.stackexchange.com/rooms/52405/conversation/lesson-s3-parsing-expressions-with-parentheses">Parsing expressions with parentheses</a></li>
-</ul>
+<p>The remaining part, a Virtual Machine (VM), can be implemented in any language to obtain a version of BQN running in that language. Its required behavior is documented <a href="vm.html">here</a>. There is a pure-BQN implementation for <a href="https://github.com/mlochbaum/BQN/blob/master/implementation/../bqn.bqn">bqn.bqn</a>, but its only practical purpose is to quickly test modifications to the runtime and compiler. The VM used for the online REPL is the <a href="https://github.com/mlochbaum/BQN/blob/master/implementation/../docs/bqn.js">Javascript implementation</a>, while <a href="https://github.com/dzaima/CBQN">CBQN</a> is a more advanced VM in C. <a href="https://github.com/dzaima/CBQN/blob/master/src/README.md">This page</a> gives an introduction to the CBQN source code. There are platform-specific and generic tests in the <a href="https://github.com/mlochbaum/BQN/blob/master/implementation/../test/">test</a> directory.</p>

docs/implementation/primitive/index.html

@@ -20,5 +20,5 @@ <h1 id="primitive-implementation-notes"><a class="header" href="#primitive-imple
 <li><a href="types.html">Data types</a></li>
 </ul>
 <p>Raw speed is of course the most important factor; I also consider predictability and memory usage to be important. Predictability mostly for the benefit of the programmer, but it's also important when there are multiple algorithms to be able to compute which one will be fastest. In some cases an algorithm is best on some subset of inputs, but is effectively useless because it's too difficult to tell if the input falls in that set. Whitney and other K users sometimes profess that binary size is critically important; I don't believe this.</p>
-<p>CBQN uses 1-byte, 2-byte, and 4-byte integers, 8-byte floats, and bit booleans. These are the types handled efficiently by SIMD instructions, and I think they are the best choice for any array language without special precision requirements. I am most interested in x86 with vector extensions up to AVX2, as I think this is the hardware most users currently have.</p>
+<p>CBQN uses 1-byte, 2-byte, and 4-byte integers, 8-byte floats, and bit booleans. The various advantages of these types are discussed <a href="types.html">here</a>. We optimize for x86 and 64-bit ARM with vector extensions, focusing on AVX2 rather than AVX-512 because of the slow rollout of these wider instructions.</p>
 <p>It's difficult to know when better algorithms exist. I try to research the state of the art and to estimate how much room for improvement there is, but it will come as no surprise if I've completely overlooked something that's simple in hindsight, or postulated a lower bound that can be beaten with a clever trick.</p>

implementation/README.md

@@ -2,19 +2,14 @@
 
 # BQN implementation notes
 
-Notes about how BQN is or could be implemented.
+<center>
 
-This repository's BQN implementation is written mainly in BQN: the bytecode [compiler](../src/c.bqn) is completely self-hosted, and the majority of the runtime ([r0](../src/r0.bqn), [r1](../src/r1.bqn)) is written in BQN except that it is allowed to define primitives; some preprocessing ([pr](../src/pr.bqn)) turns the primitives into identifiers.
+[primitives](primitive/README.md) • [compiling](compile/README.md) • [state of CBQN](perf.md) • [VM documentation](vm.md)
 
-The remaining part, a Virtual Machine (VM), can be implemented in any language to obtain a version of BQN running in that language. The VM used for the online REPL is the [Javascript implementation](../docs/bqn.js), while [CBQN](https://github.com/dzaima/CBQN) is a more advanced VM in C. [This page](https://github.com/dzaima/CBQN/blob/master/src/README.md) gives an introduction to the CBQN source code. There are platform-specific and generic tests in the [test](../test/) directory.
+</center>
 
-- [The BQN virtual machine and runtime](vm.md): the non-self-hosted parts of the BQN implementation, or those needed to port it to a new platform.
-- [Notes on implementing primitives](primitive/README.md)
-- [Notes on compilation](compile/README.md)
-- [Comparison to Co-dfns](codfns.md), the other array-based compiler (plus the newer Pareas).
+Notes about how BQN is or could be implemented.
 
-I held a few early forum discussions on the workings of the self-hosted compiler, but aborted these because the interactive format wasn't doing too much. I haven't yet started on non-interactive replacements.
+This repository's BQN implementation is written mainly in BQN: the bytecode [compiler](../src/c.bqn) is completely self-hosted, and the majority of the runtime ([r0](../src/r0.bqn), [r1](../src/r1.bqn)) is written in BQN except that it is allowed to define primitives; some preprocessing ([pr](../src/pr.bqn)) turns the primitives into identifiers.
 
-- [Parenthesis nesting level](https://chat.stackexchange.com/rooms/52405/conversation/lesson-s1-parenthesis-nesting-level)
-- [Infix to RPN](https://chat.stackexchange.com/rooms/52405/conversation/lesson-s2-infix-to-rpn)
-- [Parsing expressions with parentheses](https://chat.stackexchange.com/rooms/52405/conversation/lesson-s3-parsing-expressions-with-parentheses)
+The remaining part, a Virtual Machine (VM), can be implemented in any language to obtain a version of BQN running in that language. Its required behavior is documented [here](vm.md). There is a pure-BQN implementation for [bqn.bqn](../bqn.bqn), but its only practical purpose is to quickly test modifications to the runtime and compiler. The VM used for the online REPL is the [Javascript implementation](../docs/bqn.js), while [CBQN](https://github.com/dzaima/CBQN) is a more advanced VM in C. [This page](https://github.com/dzaima/CBQN/blob/master/src/README.md) gives an introduction to the CBQN source code. There are platform-specific and generic tests in the [test](../test/) directory.

implementation/compile/README.md

@@ -2,9 +2,14 @@
 
 # Optimizing compilation notes
 
-Pages here discuss advanced compilation strategies for BQN, that is, steps that might take take place after compiling to bytecode or a similar intermediate representation.
-
-Most content here is currently speculative: C, Java, and Javascript backends are capable of compiling to native (x86, JVM, or Javascript) code in order to lower evaluation overhead but don't perform much if any analysis to improve this code. CBQN is likely to start making such optimizations in the future.
+Pages in this directory discuss advanced compilation strategies for BQN, that is, steps that might take take place after compiling to bytecode or a similar intermediate representation. Most content here is currently speculative: C, Java, and Javascript backends are capable of compiling to native (x86, JVM, or Javascript) code in order to lower evaluation overhead but don't perform much if any analysis to improve this code. CBQN is likely to start making such optimizations in the future.
 
 - [Array language compilation in context](intro.md), an introduction to the subject
 - [Dynamic compilation](dynamic.md), discussing high-level strategies
+
+The self-hosted bytecode compiler isn't really documented, but there are some related resources elsewhere. I held a few early chat discussions on building an array-based compiler, but aborted these because the interactive format wasn't doing too much.
+
+- [Comparison to Co-dfns](../codfns.md), the other array-based compiler (plus the newer Pareas).
+- Chat: [Parenthesis nesting level](https://chat.stackexchange.com/rooms/52405/conversation/lesson-s1-parenthesis-nesting-level)
+- Chat: [Infix to RPN](https://chat.stackexchange.com/rooms/52405/conversation/lesson-s2-infix-to-rpn)
+- Chat: [Parsing expressions with parentheses](https://chat.stackexchange.com/rooms/52405/conversation/lesson-s3-parsing-expressions-with-parentheses)

implementation/primitive/README.md

@@ -17,6 +17,6 @@ Commentary on the best methods I know for implementing various primitives. Often
 
 Raw speed is of course the most important factor; I also consider predictability and memory usage to be important. Predictability mostly for the benefit of the programmer, but it's also important when there are multiple algorithms to be able to compute which one will be fastest. In some cases an algorithm is best on some subset of inputs, but is effectively useless because it's too difficult to tell if the input falls in that set. Whitney and other K users sometimes profess that binary size is critically important; I don't believe this.
 
-CBQN uses 1-byte, 2-byte, and 4-byte integers, 8-byte floats, and bit booleans. These are the types handled efficiently by SIMD instructions, and I think they are the best choice for any array language without special precision requirements. I am most interested in x86 with vector extensions up to AVX2, as I think this is the hardware most users currently have.
+CBQN uses 1-byte, 2-byte, and 4-byte integers, 8-byte floats, and bit booleans. The various advantages of these types are discussed [here](types.md). We optimize for x86 and 64-bit ARM with vector extensions, focusing on AVX2 rather than AVX-512 because of the slow rollout of these wider instructions.
 
 It's difficult to know when better algorithms exist. I try to research the state of the art and to estimate how much room for improvement there is, but it will come as no surprise if I've completely overlooked something that's simple in hindsight, or postulated a lower bound that can be beaten with a clever trick.