Revisit main README

1 files changed, 14 insertions, 14 deletions

diff --git a/docs/index.html b/docs/index.html
index 6881ee8f..4f199a5e 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -19,25 +19,25 @@
   </div>
   <pre class='rslt'>"B Q N"</pre>
 </div>
-<p><strong>BQN</strong> is a new programming language in the APL lineage, which aims to remove inconsistent and burdensome aspects of the APL tradition and put the great ideas on a firmer footing. BQN is aimed at existing and aspiring APL-family programmers, and using it requires a solid understanding of functions and multidimensional arrays. However, because of its focus on providing simple, consistent, and powerful array operations, BQN should also be a good language for learning array programming and building stronger array intuition.</p>
+<p><strong>BQN</strong> is a new programming language in the APL lineage, which aims to remove irregular and burdensome aspects of the APL tradition and put the great ideas on a firmer footing. While its use demands a solid understanding of functions and multidimensional arrays, BQN's focus on providing simple, consistent, and powerful array operations (and documentation!) makes it a good language for learning array programming and building stronger array intuition.</p>
 <p>BQN maintains many of the ideas that made APL\360 revolutionary in 1966:</p>
 <ul>
-<li>Human-friendly <strong>infix notation</strong> with no precedence rules to remember.</li>
-<li><strong>Built-in array operations</strong> handle any number of dimensions easily.</li>
+<li>Human-friendly <strong>infix notation</strong> has no precedence rules to remember.</li>
+<li><a href="doc/primitive.html"><strong>Built-in array operations</strong></a> handle any number of dimensions easily.</li>
 <li><strong>Higher-order functions</strong> allow basic functions to be applied in more powerful ways.</li>
 </ul>
 <p>It incorporates concepts developed over years of APL practice:</p>
 <ul>
-<li>The <a href="doc/leading.html"><strong>leading axis model</strong></a>, which allows for simpler built-in functions.</li>
-<li><a href="doc/train.html">Trains</a> and combinators for <strong>tacit programming</strong>.</li>
-<li>Lightweight <a href="doc/block.html"><strong>anonymous functions</strong></a> (like <a href="https://aplwiki.com/wiki/Dfn">dfns</a>).</li>
+<li>With the <a href="doc/leading.html"><strong>leading axis model</strong></a>, simpler primitives span the same functionality.</li>
+<li><a href="doc/train.html">Trains</a> and combinators enable <strong>tacit programming</strong>.</li>
+<li>Lightweight <a href="doc/block.html"><strong>anonymous functions</strong></a> (like <a href="https://aplwiki.com/wiki/Dfn">dfns</a>) borrow some power from Lisp.</li>
 </ul>
 <p>But BQN is redesigned from the ground up, with brand new ideas to make these paradigms easier to use and less likely to fail.</p>
 <ul>
 <li>The <a href="doc/based.html"><strong>based array model</strong></a> makes non-arrays (called atoms) a fundamental part of the language, and removes the surprise of floating arrays and the hassle of explicit boxes. New <strong>array notation</strong> eliminates the gotchas of <a href="https://aplwiki.com/wiki/Strand_notation">stranding</a>.</li>
 <li>A <a href="doc/context.html"><strong>context-free grammar</strong></a> where a value's syntactic role is determined by its spelling makes it easier for machines and humans to understand code.</li>
-<li>Oh, and it naturally leads to <a href="doc/functional.html"><strong>first-class functions</strong></a>, a feature often missed in APL.</li>
-<li>The <strong>new symbols</strong> for built-in functionality allow the syntactic role of a primitive to be distinguished at a glance, and aim to be more consistent and intuitive.</li>
+<li>Oh, and it naturally leads to <a href="doc/functional.html"><strong>first-class functions</strong></a>, which for example can be used to <a href="doc/control.html">reinvent control structures</a>.</li>
+<li><strong>New symbols</strong> for built-in functionality make the syntactic role of every primitive instantly visible, and aim to be more consistent and intuitive.</li>
 </ul>
 <h2 id="what-kind-of-name-is-bqn">What kind of name is &quot;BQN&quot;?</h2>
 <p>It's three letters, that happen to match the capitals in &quot;Big Questions Notation&quot;. You can pronounce it &quot;bacon&quot;, but are advised to avoid this unless there's puns.</p>
@@ -46,13 +46,13 @@
 <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4oqRK2DiiJjijL3ijZ8xMuKGlTIgICMgVGhlIDEydGggRmlib25hY2NpIG51bWJlcg==&run">↗️</a><pre>    <span class='Function'>⊑+</span><span class='Modifier'>`</span><span class='Modifier2'>∘</span><span class='Function'>⌽</span><span class='Modifier2'>⍟</span><span class='Number'>12</span><span class='Function'>↕</span><span class='Number'>2</span>  <span class='Comment'># The 12th Fibonacci number
 </span>144
 </pre>
-<p>For longer samples, you can <a href="https://github.com/mlochbaum/BQN/blob/master/src/c.bqn">gaze into the abyss</a> that is the self-hosted compiler, or the <a href="https://github.com/mlochbaum/BQN/blob/master/src/r.bqn">shallower but wider abyss</a> of the runtime, or take a look at the friendlier <a href="https://github.com/mlochbaum/BQN/blob/master/md.bqn">markdown processor</a> used to format and highlight documentation files. There are also <a href="https://github.com/mlochbaum/BQN/blob/master/examples/fifty.bqn">some translations</a> from <a href="https://www.jsoftware.com/papers/50/">&quot;A History of APL in 50 Functions&quot;</a> here.</p>
+<p>More snippets are programmed into the live demo at the top of the page: hit the arrow at the right of the code window to see them. For longer samples, you can <a href="https://github.com/mlochbaum/BQN/blob/master/src/c.bqn">gaze into the abyss</a> that is the self-hosted compiler, or the <a href="https://github.com/mlochbaum/BQN/blob/master/src/r.bqn">shallower but wider abyss</a> of the runtime, or take a look at the friendlier <a href="https://github.com/mlochbaum/BQN/blob/master/md.bqn">markdown processor</a> used to format and highlight documentation files. This repository also has <a href="https://github.com/mlochbaum/BQN/blob/master/examples/fifty.bqn">some translations</a> from <a href="https://www.jsoftware.com/papers/50/">&quot;A History of APL in 50 Functions&quot;</a>.</p>
 <h2 id="how-do-i-work-with-the-character-set">How do I work with the character set?</h2>
-<p>I enter the special characters using a backslash prefix, so that, for example, <code><span class='Value'>\z</span></code> is translated to <code><span class='Function'>⥊</span></code> (the backslash character itself is not used by BQN). The online REPL supports this method out of the box, and this repository also has <a href="https://github.com/mlochbaum/BQN/tree/master/editors">scripts</a> to support it, along with the standard syntax highlighting and indentation, in Vim and <a href="https://kakoune.org/">Kakoune</a>. When starting out, it may be easier to use the bar above the REPL: hover over a character to see a short description, and click to insert it into the editor. Finally, on Linux <a href="https://github.com/mlochbaum/BQN/blob/master/editors/bqn">this configuration file</a> for <a href="https://en.wikipedia.org/wiki/X_keyboard_extension">XKB</a> can be used to allow typing glyphs with a modifier key system-wide.</p>
-<p>Few existing monospace fonts support all the BQN characters (double-struck letters like <code><span class='Value'>𝕩</span></code> are a particular sticking point), which can cause these characters to be rendered with a fallback font and have the wrong width or look inconsistent. Two fonts modified to support BQN are available currently. This site uses a <a href="https://github.com/mlochbaum/BQN/blob/master/docs/DejaVuBQNSansMono.ttf">modified DejaVu Sans Mono</a>, and another, more playful option is <a href="https://github.com/dzaima/BQN386">BQN386</a>, based on <a href="https://abrudz.github.io/APL386/">APL386</a>. Existing font <a href="http://www.kreativekorp.com/software/fonts/fairfaxhd.shtml">Fairfax HD</a> has excellent BQN support, but be careful not to confuse single quote (<code><span class='String'>'</span></code>) with the smaller acute accent (<code><span class='Modifier'>´</span></code>). <a href="https://github.com/cormullion/juliamono">Julia Mono</a> also supports all BQN characters, but with widely varying styles and weights.</p>
+<p>I type the special characters using a backslash escape, so that, for example, typing <code><span class='Value'>\</span></code> then <code><span class='Value'>z</span></code> writes <code><span class='Function'>⥊</span></code> (the backslash character itself is not used by BQN). The online REPL supports this method out of the box, and this repository also has <a href="https://github.com/mlochbaum/BQN/tree/master/editors">scripts</a> to support it, along with the standard syntax highlighting and indentation, in Vim and <a href="https://kakoune.org/">Kakoune</a>. When starting out, it may be easier to use the bar above the REPL: hover over a character to see a short description, and click to insert it into the editor. Finally, on Linux <a href="https://github.com/mlochbaum/BQN/blob/master/editors/bqn">this configuration file</a> for <a href="https://en.wikipedia.org/wiki/X_keyboard_extension">XKB</a> can be used to allow typing glyphs with a modifier key system-wide.</p>
+<p>Few existing monospace fonts support all the BQN characters (double-struck letters like <code><span class='Value'>𝕩</span></code> are a particular sticking point), which can cause these characters to be rendered with a fallback font and have the wrong width or look inconsistent. Two fonts modified to support BQN are available currently. This site uses a <a href="https://github.com/mlochbaum/BQN/blob/master/docs/DejaVuBQNSansMono.ttf">modified DejaVu Sans Mono</a>, and another, more playful option is <a href="https://github.com/dzaima/BQN386">BQN386</a> (<a href="https://dzaima.github.io/BQN386/">demo</a>). Existing font <a href="http://www.kreativekorp.com/software/fonts/fairfaxhd.shtml">Fairfax HD</a> has excellent BQN support, but be careful not to confuse single quote (<code><span class='String'>'</span></code>) with the smaller acute accent (<code><span class='Modifier'>´</span></code>). <a href="https://github.com/cormullion/juliamono">Julia Mono</a> also supports all BQN characters, but with varying styles and weights.</p>
 <h2 id="how-do-i-get-started">How do I get started?</h2>
-<p>Read the <a href="doc/index.html">documentation</a>!</p>
-<p>BQN documentation is currently written primarily for array programmers and is not comprehensive, with aspects of the language that are shared with APL poorly documented. If you're not an array programmer, it would probably be better to start with another language, or wait a few weeks. But if you're a serious language enthusiast, the <a href="spec/index.html">specification</a> is fairly complete and might be enough to fill the gaps in the documentation.</p>
-<p>If you're an array programmer, then you're in much better shape. However, you should be aware of two key differences between BQN and existing array languages beyond just the changes of <a href="doc/primitive.html">primitives</a>—if these differences don't seem important to you then you don't understand them! BQN's <a href="doc/based.html">based array model</a> is different from both a flat array model like J and a nested one like APL2, Dyalog, or GNU APL in that it has true non-array values (plain numbers and characters) that are different from depth-0 scalars. BQN also uses <a href="doc/context.html">syntactic roles</a> rather than dynamic type to determine how values interact, that is, what's an argument or operand and so on. This system, along with lexical closures, means BQN fully supports Lisp-style <a href="doc/functional.html">functional programming</a>.</p>
+<p><em>Writing good learning material for a programming language is a pretty huge task, so neither the tutorials not the documentation are complete. With some willingness to experiment and possibly outside knowledge of array programming, it's enough to get by, just not smooth sailing.</em></p>
+<p>BQN's <a href="tutorial/index.html"><strong>tutorials</strong></a> are intended as an introduction to array programming with BQN. They assume only knowledge of elementary mathematics, but will probably be hard to follow if you have <em>no</em> programming experience. BQN has a lot in common with dynamically-typed functional languages like Lisp, Julia, or Javascript, so knowledge of these languages will be particularly helpful. However, there's a significant (but shrinking) gap between the last tutorial and existing documentation. If you're motivated, you may be able to get across by reading material on other array languages like APL, J, NumPy, or Julia.</p>
+<p>If you're already an array programmer, then you're in better shape: the current <a href="doc/index.html"><strong>documentation</strong></a> covers nearly all differences from APL, and the BQN-Dyalog APL <a href="doc/fromDyalog.html">dictionary</a> might also be a useful resource. However, you should be aware of two key differences between BQN and existing array languages beyond just the changes of <a href="doc/primitive.html">primitives</a>—if these differences don't seem important to you then you don't understand them! BQN's <a href="doc/based.html">based array model</a> is different from both a flat array model like J and a nested one like APL2, Dyalog, or GNU APL in that it has true non-array values (plain numbers and characters) that are different from depth-0 scalars. BQN also uses <a href="doc/context.html">syntactic roles</a> rather than dynamic type to determine how values interact, that is, what's an argument or operand and so on. This system, along with lexical closures, means BQN fully supports Lisp-style <a href="doc/functional.html">functional programming</a>.</p>
 
 <script src='bqn.js'></script><script src='repl.js'></script>