From c3ea468236e362e4ecc1bc27aed7a64d90e7cf81 Mon Sep 17 00:00:00 2001
From: Marshall Lochbaum <mwlochbaum@gmail.com>
Date: Thu, 2 Jun 2022 21:42:44 -0400
Subject: Always use "index list", not "list index", for a full element index

---
 docs/doc/glossary.html |  1 +
 docs/doc/identity.html |  2 +-
 docs/doc/indices.html  | 10 +++++-----
 docs/doc/pick.html     |  2 +-
 docs/doc/range.html    |  2 +-
 5 files changed, 9 insertions(+), 8 deletions(-)

(limited to 'docs/doc')

diff --git a/docs/doc/glossary.html b/docs/doc/glossary.html
index ee3cddb4..85591356 100644
--- a/docs/doc/glossary.html
+++ b/docs/doc/glossary.html
@@ -76,6 +76,7 @@
 </ul>
 <ul>
 <li><a href="indices.html"><strong>Index</strong></a>: One of a variety of ways to select an element, cell, axis, or position along an axis of an array.</li>
+<li><a href="indices.html#element-indices"><strong>Index list</strong></a>: A list of numbers indicating a single element of an array.</li>
 </ul>
 <h2 id="operations"><a class="header" href="#operations">Operations</a></h2>
 <ul>
diff --git a/docs/doc/identity.html b/docs/doc/identity.html
index 5ef3bde7..baaf7fa8 100644
--- a/docs/doc/identity.html
+++ b/docs/doc/identity.html
@@ -69,7 +69,7 @@
 </pre>
 <p>A larger class of block functions can be translated just by adding parentheses and <code><span class='Modifier'>˙</span></code> (there's a discussion of this technique in APL <a href="https://dfns.dyalog.com/n_tacit.htm">here</a>). It's helpful when writing tacit code to know that <code><span class='Function'>Fn</span><span class='Modifier2'>∘</span><span class='Function'>⊣</span></code> applies <code><span class='Function'>Fn</span></code> to the left argument only and <code><span class='Function'>Fn</span><span class='Modifier2'>∘</span><span class='Function'>⊢</span></code> applies it to the right argument—these can be read &quot;Fn of left&quot; and &quot;Fn of right&quot;.</p>
 <h2 id="one-more-thing"><a class="header" href="#one-more-thing">One more thing</a></h2>
-<p>You've probably seen <code><span class='Function'>⊢</span></code> used in documentation to display the value of a variable being assigned. This is a hack, and in most contexts <code><span class='Function'>•Show</span></code> should be used to display values.</p>
+<p>You've probably seen <code><span class='Function'>⊢</span></code> used in documentation to display the value of a variable being assigned. Normally <code><span class='Function'>•Show</span></code> is used to display values, but the website is sort of a weird context: it displays by default but disables it if the final thing done is an assignment. <code><span class='Function'>⊢</span></code> isn't assignment, so it works arround that rule.</p>
 <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4oqiIGEg4oaQICJzaG93IHRoaXMi">↗️</a><pre>    <span class='Function'>⊢</span> <span class='Value'>a</span> <span class='Gets'>←</span> <span class='String'>&quot;show this&quot;</span>
 "show this"
 </pre>
diff --git a/docs/doc/indices.html b/docs/doc/indices.html
index 36bf279c..264caec8 100644
--- a/docs/doc/indices.html
+++ b/docs/doc/indices.html
@@ -5,7 +5,7 @@
 </head>
 <div class="nav">(<a href="https://github.com/mlochbaum/BQN">github</a>) / <a href="../index.html">BQN</a> / <a href="index.html">doc</a></div>
 <h1 id="indices"><a class="header" href="#indices">Indices</a></h1>
-<p>One-dimensional arrays such as K lists or Python arrays have only one kind of index, a single number that refers to an element. For <a href="array.html">multidimensional arrays</a> using the <a href="leading.html">leading axis theory</a>, there are several types of indexing that can be useful. Historically, nested APL designs have equivocated between these, which I believe can lead to subtle errors when programming. BQN focuses on single-number (atomic) indices, which can refer to list elements or array major cells (or more generally indexing along any particular axis). When using atomic indices to select elements, the indexed array has to be a list. In contrast, elements of any array can be indicated by list indices with length equal to that array's rank. Only two BQN primitives use these list indices: <a href="range.html">Range</a> (<code><span class='Function'>↕</span></code>), which returns an array of them if given a list argument, and <a href="pick.html">Pick</a> (<code><span class='Function'>⊑</span></code>), where the depth-1 components of an array left argument are list indices.</p>
+<p>One-dimensional arrays such as K lists or Python arrays have only one kind of index, a single number that refers to an element. For <a href="array.html">multidimensional arrays</a> using the <a href="leading.html">leading axis theory</a>, there are several types of indexing that can be useful. Historically, nested APL designs have equivocated between these, which I believe can lead to subtle errors when programming. BQN focuses on single-number (atomic) indices, which can refer to list elements or array major cells (or more generally indexing along any particular axis). When using atomic indices to select elements, the indexed array has to be a list. An element of an arbitrary array can be indicated by an index list as long as that array's rank. Only two BQN primitives use these index lists: <a href="range.html">Range</a> (<code><span class='Function'>↕</span></code>), which returns an array of them if given a list argument, and <a href="pick.html">Pick</a> (<code><span class='Function'>⊑</span></code>), where the depth-1 components of an array left argument are index lists.</p>
 <p>The following functions take or return indices. Except where marked, the indices are in the result; this is by far the most common type of index use. <a href="group.html">Group</a> (<code><span class='Function'>⊔</span></code>) is given two rows as it falls into both cases. Note that in the result case, there is usually no possibility for the programmer to select the format of indices. Instead, the language should be carefully designed to make sure that the kind of index returned is as useful as possible.</p>
 <table>
 <thead>
@@ -87,11 +87,11 @@
 </table>
 <p>In <a href="transpose.html#reorder-axes">Reorder Axes</a> (<code><span class='Function'>⍉</span></code>), <code><span class='Value'>𝕨</span></code> is made up of indices into axes of <code><span class='Value'>𝕩</span></code>. Since array shape is 1-dimensional, there is only one sensible choice for these elements, a single number each.</p>
 <h2 id="element-indices"><a class="header" href="#element-indices">Element indices</a></h2>
-<p>In general, the index of an element of an array is a list whose length matches the array rank. It is also possible to use a number for an index into a list, as the list index is a singleton, but this must be kept consistent with the rest of the language. NARS-family APLs make the Index Generator (<code><span class='Function'>↕</span></code> in BQN) return a numeric list when the argument has length 1 but a nested array otherwise. This means that the depth of the result depends on the shape of the argument, inverting the typical hierarchy. BQN shouldn't have such an inconsistency.</p>
-<p>Functions <a href="range.html">Range</a> (<code><span class='Function'>↕</span></code>), <a href="replicate.html">Indices</a> (<code><span class='Function'>/</span></code>), <a href="group.html">Group</a> (<code><span class='Function'>⊔</span></code>), and <a href="pick.html">Pick</a> (<code><span class='Function'>⊑</span></code>) naturally deal with element indices. Each of these can be defined to use list indices. However, this usually rules out the possibility of using atomic indices, which makes these functions harder to use both with generic array manipulation and with the major cell indices discussed in the next section. For this reason BQN restricts <code><span class='Function'>⊔</span></code> and <code><span class='Function'>/</span></code> to use atomic indices, which comes with the requirement that the arguments to Group and Indices, and the result of Group Indices, must be lists. For dyadic Group the depth-1 elements of <code><span class='Value'>𝕨</span></code> are arrays of indices along axes of the result (<a href="group.html#multidimensional-grouping">multi-axis documentation</a>). This means each axis of <code><span class='Value'>𝕩</span></code> can only be related to one axis of the result.</p>
-<p>Unlike <code><span class='Function'>/</span></code> and <code><span class='Function'>⊔</span></code>, <code><span class='Function'>↕</span></code> and <code><span class='Function'>⊑</span></code> do use list element indices. For <code><span class='Function'>↕</span></code> this is because the output format can be controlled by the argument format: if passed a single number, the result uses atomic indices (so it's a numeric list); if passed a list, it uses list indices and the result has depth 2 (the result depth is always one greater than the argument depth). For <code><span class='Function'>⊑</span></code>, list indices are chosen because <a href="select.html">Select</a> (<code><span class='Function'>⊏</span></code>) handles atomic indices well already. When selecting multiple elements from a list, they would typically have to be placed in an array, which is equivalent to <code><span class='Function'>⊏</span></code> with a numeric list <code><span class='Value'>𝕨</span></code>. An atom <code><span class='Value'>𝕨</span></code> in Pick is converted to a list, so it can be used to select a single element if only one is wanted. To select multiple elements, <code><span class='Function'>⊑</span></code> uses each depth-1 array in <code><span class='Value'>𝕨</span></code> as an index and replaces it with that element from the right argument. Because this uses elements as elements (not cells), it is impossible to have conformability errors where elements do not fit together (invalid index errors are of course still possible). Atoms also cannot be used in this context, as it would create ambiguity: is a one-element list an index, or does it contain an index?</p>
+<p>In general, the index of an element of an array is a list whose length matches the array rank. It is also possible to use a number for an index <em>into</em> a list, as the index list is a singleton, but this must be kept consistent with the rest of the language. NARS-family APLs make the Index Generator (<code><span class='Function'>↕</span></code> in BQN) return a numeric list when the argument has length 1 but a nested array otherwise. This means that the depth of the result depends on the shape of the argument, inverting the typical hierarchy. BQN shouldn't have such an inconsistency.</p>
+<p>Functions <a href="range.html">Range</a> (<code><span class='Function'>↕</span></code>), <a href="replicate.html">Indices</a> (<code><span class='Function'>/</span></code>), <a href="group.html">Group</a> (<code><span class='Function'>⊔</span></code>), and <a href="pick.html">Pick</a> (<code><span class='Function'>⊑</span></code>) naturally deal with element indices. Each of these can be defined to use index lists. However, this usually rules out the possibility of using atomic indices, which makes these functions harder to use both with generic array manipulation and with the major cell indices discussed in the next section. For this reason BQN restricts <code><span class='Function'>⊔</span></code> and <code><span class='Function'>/</span></code> to use atomic indices, which comes with the requirement that the arguments to Group and Indices, and the result of Group Indices, must be lists. For dyadic Group the depth-1 elements of <code><span class='Value'>𝕨</span></code> are arrays of indices along axes of the result (<a href="group.html#multidimensional-grouping">multi-axis documentation</a>). This means each axis of <code><span class='Value'>𝕩</span></code> can only be related to one axis of the result.</p>
+<p>Unlike <code><span class='Function'>/</span></code> and <code><span class='Function'>⊔</span></code>, <code><span class='Function'>↕</span></code> and <code><span class='Function'>⊑</span></code> do use list element indices. For <code><span class='Function'>↕</span></code> this is because the output format can be controlled by the argument format: if passed a single number, the result uses atomic indices (so it's a numeric list); if passed a list, it uses index lists and the result has depth 2 (the result depth is always one greater than the argument depth). For <code><span class='Function'>⊑</span></code>, index lists are chosen because <a href="select.html">Select</a> (<code><span class='Function'>⊏</span></code>) handles atomic indices well already. When selecting multiple elements from a list, they would typically have to be placed in an array, which is equivalent to <code><span class='Function'>⊏</span></code> with a numeric list <code><span class='Value'>𝕨</span></code>. An atom <code><span class='Value'>𝕨</span></code> in Pick is converted to a list, so it can be used to select a single element if only one is wanted. To select multiple elements, <code><span class='Function'>⊑</span></code> uses each depth-1 array in <code><span class='Value'>𝕨</span></code> as an index and replaces it with that element from the right argument. Because this uses elements as elements (not cells), it is impossible to have conformability errors where elements do not fit together (invalid index errors are of course still possible). Atoms also cannot be used in this context, as it would create ambiguity: is a one-element list an index, or does it contain an index?</p>
 <h2 id="major-cell-indices"><a class="header" href="#major-cell-indices">Major cell indices</a></h2>
-<p>One of the successes of the <a href="https://aplwiki.com/wiki/Leading_axis_theory">leading axis model</a> is to introduce a kind of index for multidimensional arrays that is easier to work with than list indices. The model introduces <a href="https://aplwiki.com/wiki/Cell">cells</a>, where a cell index is a list of any length up to the containing array's rank. General cell indices are discussed in the next section; first we introduce a special case, indices into major cells or ¯1-cells. These cells naturally form a list, so the index of a major cell is a single number. Such an index can also be considered to select along the first axis, since an index along any axis is a single number.</p>
+<p>One of the successes of the <a href="https://aplwiki.com/wiki/Leading_axis_theory">leading axis model</a> is to introduce a kind of index for multidimensional arrays that is easier to work with than index lists. The model introduces <a href="https://aplwiki.com/wiki/Cell">cells</a>, where a cell index is a list of any length up to the containing array's rank. General cell indices are discussed in the next section; first we introduce a special case, indices into major cells or ¯1-cells. These cells naturally form a list, so the index of a major cell is a single number. Such an index can also be considered to select along the first axis, since an index along any axis is a single number.</p>
 <p><a href="order.html">Ordering</a> functions <code><span class='Function'>⍋⍒</span></code> and <a href="search.html">search</a>/<a href="selfcmp.html">self-search</a> functions <code><span class='Function'>⊐⊒</span></code> that depend on cell ordering only really make sense with major cell indices: while other indices have an ordering, it's not very natural. Note that <code><span class='Function'>⊐</span></code> only uses the ordering in an incidental way, because it's defined to return the <em>first</em> index where a cell in <code><span class='Value'>𝕩</span></code> is found. A mathematician would be more interested in a &quot;pre-image&quot; function that returns the set of all indices where a particular value appears. However, programming usefulness and consistency with the other search functions makes searching for the first index a reasonable choice.</p>
 <p>Only one other function—but an important one!—deals with cells rather than elements: <a href="select.html">Select</a> (<code><span class='Function'>⊏</span></code>). Select <a href="leading.html#multiple-axes">allows</a> either a simple first-axis case where <code><span class='Value'>𝕨</span></code> has depth 1 or less (a depth-0 argument is automatically enclosed), and a multi-axis case where it is a list of depth-1 elements. In each case the depth-1 arrays index along a single axis.</p>
 <h2 id="general-cell-indices"><a class="header" href="#general-cell-indices">General cell indices</a></h2>
diff --git a/docs/doc/pick.html b/docs/doc/pick.html
index a5e9392b..275b623a 100644
--- a/docs/doc/pick.html
+++ b/docs/doc/pick.html
@@ -82,7 +82,7 @@
     <span class='Bracket'>⟨</span><span class='Number'>2</span><span class='Ligature'>‿</span><span class='Number'>0</span><span class='Separator'>,</span> <span class='Number'>1</span><span class='Ligature'>‿</span><span class='Number'>¯1</span><span class='Separator'>,</span> <span class='Number'>3</span><span class='Ligature'>‿</span><span class='Number'>1</span><span class='Separator'>,</span> <span class='Number'>¯1</span><span class='Ligature'>‿</span><span class='Number'>¯1</span><span class='Bracket'>⟩</span> <span class='Function'>⊑</span> <span class='Value'>a</span>
 "kjqt"
 </pre>
-<p>These indices have to be lists, since if they're numbers it just looks like <code><span class='Value'>𝕨</span></code> is one list index.</p>
+<p>These indices have to be lists, since if they're numbers it just looks like <code><span class='Value'>𝕨</span></code> is an index list for one element.</p>
 <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4p+oMiwxLDAswq8x4p+pIOKKkSAiYWJjIiAgIyDwnZWpIGRvZXNuJ3QgaGF2ZSByYW5rIDQhCgrin6gyLDEsMCzCrzHin6kg4qWKwqjiirjiipEgImFiYyIKCuKfqDIsMSwwLMKvMeKfqSDiio8gImFiYyIgICMgQmV0dGVyIHdheQ==">↗️</a><pre>    <span class='Bracket'>⟨</span><span class='Number'>2</span><span class='Separator'>,</span><span class='Number'>1</span><span class='Separator'>,</span><span class='Number'>0</span><span class='Separator'>,</span><span class='Number'>¯1</span><span class='Bracket'>⟩</span> <span class='Function'>⊑</span> <span class='String'>&quot;abc&quot;</span>  <span class='Comment'># 𝕩 doesn't have rank 4!
 </span><span class='Error'>Error: ⊑: Picking item at wrong rank (index 2‿1‿0‿¯1 in array of shape ⟨3⟩)</span>
 
diff --git a/docs/doc/range.html b/docs/doc/range.html
index 6a8409ac..8065a34a 100644
--- a/docs/doc/range.html
+++ b/docs/doc/range.html
@@ -15,7 +15,7 @@
   ⟨ 1 0 ⟩ ⟨ 1 1 ⟩ ⟨ 1 2 ⟩  
                           ┘
 </pre>
-<p>It's really two different functions packed together: if <code><span class='Value'>𝕩</span></code> is a natural number—a length—then it returns a list of numeric indices, but if it's a list of numbers, then it returns an array of list indices. This means the result always has <a href="depth.html">depth</a> one more than the argument.</p>
+<p>It's really two different functions packed together: if <code><span class='Value'>𝕩</span></code> is a natural number—a length—then it returns a list of numeric indices, but if it's a list of numbers, then it returns an array of index lists. This means the result always has <a href="depth.html">depth</a> one more than the argument.</p>
 <p>The two kinds of index correspond to BQN's two selection functions: <a href="select.html">Select</a> (<code><span class='Function'>⊏</span></code>) works with indices along an axis, which are numbers, and <a href="pick.html">Pick</a> (<code><span class='Function'>⊑</span></code>) works with element indices, which are lists. The examples below would fail if we swapped these around. Each result from Range is a length-6 list, but their elements are different.</p>
 <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4oaVNgoKKOKGlTYpIOKKjyAic2VsZWN0IgoK4oaV4p+oNuKfqQoKKOKGleKfqDbin6kpIOKKkSAiIHBpY2sgIg==">↗️</a><pre>    <span class='Function'>↕</span><span class='Number'>6</span>
 ⟨ 0 1 2 3 4 5 ⟩
-- 
cgit v1.2.3