From 59ab5338d4e23eb108a43f876aa979238ae2490e Mon Sep 17 00:00:00 2001
From: Marshall Lochbaum <mwlochbaum@gmail.com>
Date: Fri, 12 Nov 2021 22:15:44 -0500
Subject: Slightly less APL-centric documentation

---
 docs/doc/arithmetic.html | 6 +++---
 docs/doc/logic.html      | 4 ++--
 docs/doc/search.html     | 4 ++--
 docs/doc/transpose.html  | 4 ++--
 4 files changed, 9 insertions(+), 9 deletions(-)

(limited to 'docs/doc')

diff --git a/docs/doc/arithmetic.html b/docs/doc/arithmetic.html
index 22dc233b..99dd7e11 100644
--- a/docs/doc/arithmetic.html
+++ b/docs/doc/arithmetic.html
@@ -5,8 +5,8 @@
 </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="arithmetic-functions"><a class="header" href="#arithmetic-functions">Arithmetic functions</a></h1>
-<p>BQN's arithmetic functions use mostly the same symbols as APL, and the functionality is actually defined by the language implementation's number system and not the specification, so there's not too much to say about them.</p>
-<p>Summary of differences for APLers:</p>
+<p>Since BQN's function syntax was designed to mirror mathematical operators, its arithmetic tends to look a lot like mathematical notation. Individual functions are listed below. As an array language, BQN applies arithmetic element-wise to arrays, a system known as <a href="#pervasion">pervasion</a>. A distinctive feature of BQN is its <a href="#character-arithmetic">character arithmetic</a>, which allows <code><span class='Function'>+</span></code> and <code><span class='Function'>-</span></code> to manipulate characters without explicitly transforming them to numbers.</p>
+<p>Summary of other differences from APL:</p>
 <ul>
 <li>Exponentiation is represented with the star character <code><span class='Function'>⋆</span></code>, since asterisk <code><span class='Value'>*</span></code> is rendered inconsistently across fonts and sometimes appears as a superscript.</li>
 <li>There's a root function <code><span class='Function'>√</span></code>.</li>
@@ -87,7 +87,7 @@
 ⟨ 1 2.718281828459045 7.38905609893065 ⟩
 
     <span class='Function'>√</span> <span class='Number'>0</span><span class='Ligature'>‿</span><span class='Number'>1</span><span class='Ligature'>‿</span><span class='Number'>2</span><span class='Ligature'>‿</span><span class='Number'>4</span>
-⟨ 0 1 1.4142135623730951 2 ⟩
+⟨ 0 1 1.414213562373095 2 ⟩
 </pre>
 <p>Take note of the difference between the function <code><span class='Function'>-</span></code>, and the &quot;high minus&quot; character <code><span class='Number'>¯</span></code>, which is a part of <a href="syntax.html#constants">numeric notation</a>. Also shown is the number <code><span class='Number'>∞</span></code>, which BQN supports along with <code><span class='Number'>¯∞</span></code> (but depending on implementation BQN may or may not keep track of <code><span class='Number'>¯0</span></code>. Integer optimization loses the distinction so it's best not to rely on it).</p>
 <p>The logarithm is written with Undo: <code><span class='Function'>⋆</span><span class='Modifier'>⁼</span></code>. As with Power, the default base is <em>e</em>, giving a natural logarithm.</p>
diff --git a/docs/doc/logic.html b/docs/doc/logic.html
index 92a03e43..19d4f294 100644
--- a/docs/doc/logic.html
+++ b/docs/doc/logic.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="logic-functions-and-or-not-also-span"><a class="header" href="#logic-functions-and-or-not-also-span">Logic functions: And, Or, Not (also Span)</a></h1>
-<p>BQN retains the APL symbols <code><span class='Function'>∧</span></code> and <code><span class='Function'>∨</span></code> for logical <em>and</em> and <em>or</em>, and changed APL's <code><span class='Value'>~</span></code> to <code><span class='Function'>¬</span></code> for <em>not</em>, since <code><span class='Value'>~</span></code> looks too much like <code><span class='Modifier'>˜</span></code> and <code><span class='Function'>¬</span></code> is more common in mathematics today. Like J, BQN extends Not to the linear function <code><span class='Number'>1</span><span class='Modifier2'>⊸</span><span class='Function'>-</span></code>. However, it discards <a href="https://aplwiki.com/wiki/GCD">GCD</a> and <a href="https://aplwiki.com/wiki/LCM">LCM</a> as extensions of And and Or, and instead uses bilinear extensions: And is identical to Times (<code><span class='Function'>×</span></code>), while Or is <code><span class='Function'>×</span><span class='Modifier2'>⌾</span><span class='Function'>¬</span></code>, following De Morgan's laws (other ways of obtaining a function for Or give an equivalent result—there is only one bilinear extension).</p>
+<p>BQN uses the mathematical symbols <code><span class='Function'>∧</span></code> and <code><span class='Function'>∨</span></code> for logical <em>and</em> and <em>or</em>, and <code><span class='Function'>¬</span></code> for <em>not</em> (APL's <code><span class='Value'>~</span></code> is discarded since it looks like <code><span class='Modifier'>˜</span></code>, and is less common in mathematics today). These functions are arithmetically extended to apply to all numbers. In the case of Not, that means the linear function <code><span class='Number'>1</span><span class='Modifier2'>⊸</span><span class='Function'>-</span></code>. The two-argument functions have bilinear extensions: And is identical to Times (<code><span class='Function'>×</span></code>), while Or is <code><span class='Function'>×</span><span class='Modifier2'>⌾</span><span class='Function'>¬</span></code>, following De Morgan's laws (other ways of obtaining a function for Or give an equivalent result—there is only one bilinear extension).</p>
 <p>If the arguments are probabilities of independent events, then an extended function gives the probability of the boolean function on their outcomes (for example, if <em>A</em> occurs with probability <code><span class='Value'>a</span></code> and <em>B</em> with probability <code><span class='Value'>b</span></code> independent of <em>A</em>, then <em>A</em> or <em>B</em> occurs with probability <code><span class='Value'>a</span><span class='Function'>∨</span><span class='Value'>b</span></code>). These extensions have also been used in complexity theory, because they allow mathematicians to transfer a logical circuit from the discrete to the continuous domain in order to use calculus on it.</p>
 <p>Both valences of <code><span class='Function'>¬</span></code> are equivalent to the fork <code><span class='Number'>1</span><span class='Function'>+-</span></code>. The dyadic valence, called &quot;Span&quot;, computes the number of integers in the range from <code><span class='Value'>𝕩</span></code> to <code><span class='Value'>𝕨</span></code>, inclusive, when both arguments are integers and <code><span class='Value'>𝕩</span><span class='Function'>≤</span><span class='Value'>𝕨</span></code> (note the reversed order, which is used for consistency with subtraction). This function has many uses, and in particular is relevant to the <a href="windows.html">Windows</a> function.</p>
 <p>These functions are considered <a href="arithmetic.html">arithmetic</a> functions and thus are <a href="arithmetic.html#pervasion">pervasive</a>.</p>
@@ -39,7 +39,7 @@
 </pre>
 <p>As with logical And and Or, any value and 0 is 0, while any value or 1 is 1. The other boolean values give the identity values for the two functions: 1 and any value gives that value, as does 0 or the value.</p>
 <h2 id="why-not-gcd-and-lcm"><a class="header" href="#why-not-gcd-and-lcm">Why not GCD and LCM?</a></h2>
-<p>The main reason for omitting these functions is that they are complicated and, when applied to real or complex numbers, require a significant number of design decisions where there is no obvious choice (for example, whether to use comparison tolerance). On the other hand, these functions are fairly easy to implement, which allows the programmer to control the details, and also add functionality such as the extended GCD. Possible implementations for GCD and LCM are shown in <a href="https://mlochbaum.github.io/bqncrate">bqncrate</a> (<a href="https://mlochbaum.github.io/bqncrate/?q=gcd">GCD</a>, <a href="https://mlochbaum.github.io/bqncrate/?q=lcm">LCM</a>).</p>
+<p>APL provides <a href="https://aplwiki.com/wiki/GCD">GCD</a> and <a href="https://aplwiki.com/wiki/LCM">LCM</a> as extensions of And and Or, while BQN doesn't make these functions primitives. The main reason for omitting them functions is that they are complicated and, when applied to real or complex numbers, require a significant number of design decisions where there is no obvious choice (for example, whether to use comparison tolerance). On the other hand, these functions are fairly easy to implement, which allows the programmer to control the details, and also add functionality such as the extended GCD. Possible implementations for GCD and LCM are shown in <a href="https://mlochbaum.github.io/bqncrate">bqncrate</a> (<a href="https://mlochbaum.github.io/bqncrate/?q=gcd">GCD</a>, <a href="https://mlochbaum.github.io/bqncrate/?q=lcm">LCM</a>).</p>
 <p>A secondary reason is that the GCD falls short as an extension of Or, because its identity value 0 is not total. <code><span class='Number'>0</span><span class='Function'>∨</span><span class='Value'>x</span></code>, for a real number <code><span class='Value'>x</span></code>, is actually equal to <code><span class='Function'>|</span><span class='Value'>x</span></code> and not <code><span class='Value'>x</span></code>: for example, <code><span class='Number'>0</span><span class='Function'>∨</span><span class='Number'>¯2</span></code> is <code><span class='Number'>2</span></code> in APL. This means the identity <code><span class='Number'>0</span><span class='Function'>∨</span><span class='Value'>x</span> <span class='Gets'>←→</span> <span class='Value'>x</span></code> isn't reliable in APL.</p>
 <h2 id="identity-values"><a class="header" href="#identity-values">Identity values</a></h2>
 <p>It's common to apply a <a href="fold.html">fold</a> <code><span class='Function'>∧</span><span class='Modifier'>´</span></code> or <code><span class='Function'>∨</span><span class='Modifier'>´</span></code> to a list (checking whether all elements are true and whether any are true, respectively), and so it's important for extensions to And and Or to share their <a href="fold.html#identity-values">identity</a> value. <a href="arithmetic.html#additional-arithmetic">Minimum and Maximum</a> do match And and Or when restricted to booleans, but they have different identity values. It would be dangerous to use Maximum to check whether any element of a list is true because <code><span class='Function'>⌈</span><span class='Modifier'>´</span><span class='Bracket'>⟨⟩</span></code> yields <code><span class='Number'>¯∞</span></code> instead of <code><span class='Number'>0</span></code>—a bug waiting to happen. To avoid this the programmer would have to use an initial value <code><span class='Value'>𝕨</span></code> of <code><span class='Number'>0</span></code>, which is easy to forget.</p>
diff --git a/docs/doc/search.html b/docs/doc/search.html
index 7834a06d..28e0081d 100644
--- a/docs/doc/search.html
+++ b/docs/doc/search.html
@@ -146,7 +146,7 @@
     <span class='String'>&quot;initial set&quot;</span> <span class='Paren'>(</span><span class='Function'>¬</span><span class='Modifier2'>∘</span><span class='Function'>∊/⊣</span><span class='Paren'>)</span> <span class='String'>&quot;difference&quot;</span>  <span class='Comment'># Remove 𝕩
 </span>"tal st"
 </pre>
-<p>These are the APL functions Intersect (<code><span class='Value'>∩</span></code>) and Without (<code><span class='Value'>~</span></code>). Really, only <code><span class='Value'>𝕩</span></code> is treated like a set, while the ordering and multiplicity of elements of <code><span class='Value'>𝕨</span></code> are maintained. I think the explicit implementations show this well, since <code><span class='Value'>𝕩</span></code> is only used as the right argument to <code><span class='Function'>∊</span></code>, and prefer this clarity to the brevity of a single symbol.</p>
+<p>These functions appear in APL as Intersect (<code><span class='Value'>∩</span></code>) and Without (<code><span class='Value'>~</span></code>). Really, only <code><span class='Value'>𝕩</span></code> is treated like a set, while the ordering and multiplicity of elements of <code><span class='Value'>𝕨</span></code> are maintained. I think the explicit implementations show this well, since <code><span class='Value'>𝕩</span></code> is only used as the right argument to <code><span class='Function'>∊</span></code>, and prefer this clarity to the brevity of a single symbol.</p>
 <h2 id="index-of"><a class="header" href="#index-of">Index of</a></h2>
 <p>Index of (<code><span class='Function'>⊐</span></code>) returns the index of the first occurrence of each entry in <code><span class='Value'>𝕨</span></code>, or <code><span class='Function'>≠</span><span class='Value'>𝕨</span></code> if an entry doesn't appear in <code><span class='Value'>𝕨</span></code> at all.</p>
 <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=Inplcm8i4oC/Im9uZSLigL8idHdvIuKAvyJ0aHJlZSIg4oqQICJvbmUi4oC/ImVpZ2h0IuKAvyJ0d28i">↗️</a><pre>    <span class='String'>&quot;zero&quot;</span><span class='Ligature'>‿</span><span class='String'>&quot;one&quot;</span><span class='Ligature'>‿</span><span class='String'>&quot;two&quot;</span><span class='Ligature'>‿</span><span class='String'>&quot;three&quot;</span> <span class='Function'>⊐</span> <span class='String'>&quot;one&quot;</span><span class='Ligature'>‿</span><span class='String'>&quot;eight&quot;</span><span class='Ligature'>‿</span><span class='String'>&quot;two&quot;</span>
@@ -178,7 +178,7 @@
     <span class='String'>&quot;aabbcc&quot;</span> <span class='Paren'>((</span><span class='Function'>⊒</span><span class='Modifier'>˜</span><span class='Function'>=≠</span><span class='Modifier2'>∘</span><span class='Function'>⊢</span><span class='Paren'>)</span><span class='Function'>/⊣</span><span class='Paren'>)</span> <span class='String'>&quot;baa&quot;</span>  <span class='Comment'># Multiset difference
 </span>"bcc"
 </pre>
-<p>This primitive gives an interesting way to implement the <a href="order.html#ordinals">ordinals</a> pattern that might be easier to understand than the APL classic <code><span class='Function'>⍋⍋</span></code> (it's probably a little slower though). The idea is to use the sorted array as the left argument to <code><span class='Function'>⊒</span></code>. Now the index returned for each cell is just where it ended up in that sorted order. If we used ordinary Index of then equal cells would share the smallest index; Progressive Index of means ties are broken in favor of earlier cells.</p>
+<p>This primitive gives an interesting way to implement the <a href="order.html#ordinals">ordinals</a> pattern that might be easier to understand than the classic <code><span class='Function'>⍋⍋</span></code> (it's probably a little slower though). The idea is to use the sorted array as the left argument to <code><span class='Function'>⊒</span></code>. Now the index returned for each cell is just where it ended up in that sorted order. If we used ordinary Index of then equal cells would share the smallest index; Progressive Index of means ties are broken in favor of earlier cells.</p>
 <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4o2L4oiY4o2LICJhZGViY2VkYmEiCgriiKfiirjiipIgImFkZWJjZWRiYSIKCuKIp+KKuOKKkCAiYWRlYmNlZGJhIiAgIyBUaWVzIGluY2x1ZGVk">↗️</a><pre>    <span class='Function'>⍋</span><span class='Modifier2'>∘</span><span class='Function'>⍋</span> <span class='String'>&quot;adebcedba&quot;</span>
 ⟨ 0 5 7 2 4 8 6 3 1 ⟩
 
diff --git a/docs/doc/transpose.html b/docs/doc/transpose.html
index 1cf882dc..fca1d637 100644
--- a/docs/doc/transpose.html
+++ b/docs/doc/transpose.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="transpose"><a class="header" href="#transpose">Transpose</a></h1>
-<p>Transpose (<code><span class='Function'>⍉</span></code>) is a tool for rearranging the axes of an array. BQN's version is tweaked relative to APL to align better with the leading axis model and make common operations easier.</p>
+<p>Transpose (<code><span class='Function'>⍉</span></code>) is a tool for rearranging the axes of an array <code><span class='Value'>𝕩</span></code>. Without a left argument, it moves the first axis to the end, while a left argument can specify an arbitrary rearrangement. Both cases are tweaked relative to APL to align better with the <a href="leading.html">leading axis</a> model and make common operations easier.</p>
 <h2 id="transpose-basics"><a class="header" href="#transpose-basics">Transpose basics</a></h2>
 <p>The name for the primitive <code><span class='Function'>⍉</span></code> comes from the <a href="https://en.wikipedia.org/wiki/Transpose">Transpose</a> operation on matrices. Given a matrix as an array of rank 2, <code><span class='Function'>⍉</span></code> will transpose it:</p>
 <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4oqiIG1hdCDihpAgMuKAvzMg4qWKIOKGlTYK4o2JIG1hdA==">↗️</a><pre>    <span class='Function'>⊢</span> <span class='Value'>mat</span> <span class='Gets'>←</span> <span class='Number'>2</span><span class='Ligature'>‿</span><span class='Number'>3</span> <span class='Function'>⥊</span> <span class='Function'>↕</span><span class='Number'>6</span>
@@ -100,7 +100,7 @@
 <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4omiIDHigL8z4oC/MuKAvzDigL80IOKNieKBvCBhMjM0NTY=">↗️</a><pre>    <span class='Function'>≢</span> <span class='Number'>1</span><span class='Ligature'>‿</span><span class='Number'>3</span><span class='Ligature'>‿</span><span class='Number'>2</span><span class='Ligature'>‿</span><span class='Number'>0</span><span class='Ligature'>‿</span><span class='Number'>4</span> <span class='Function'>⍉</span><span class='Modifier'>⁼</span> <span class='Value'>a23456</span>
 ⟨ 3 5 4 2 6 ⟩
 </pre>
-<p>So far, all like APL. BQN makes one little extension, which is to allow only some axes to be specified. Then <code><span class='Value'>𝕨</span></code> will be matched up with <a href="leading.html">leading axes</a> of <code><span class='Value'>𝕩</span></code>. Those axes are moved according to <code><span class='Value'>𝕨</span></code>, and remaining axes are placed in order into the gaps between them.</p>
+<p>BQN makes one further extension, which is to allow only some axes to be specified (this is the only difference in dyadic <code><span class='Function'>⍉</span></code> relative to APL). Then <code><span class='Value'>𝕨</span></code> will be matched up with <a href="leading.html">leading axes</a> of <code><span class='Value'>𝕩</span></code>. Those axes are moved according to <code><span class='Value'>𝕨</span></code>, and remaining axes are placed in order into the gaps between them.</p>
 <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4omiIDDigL8y4oC/NCDijYkgYTIzNDU2">↗️</a><pre>    <span class='Function'>≢</span> <span class='Number'>0</span><span class='Ligature'>‿</span><span class='Number'>2</span><span class='Ligature'>‿</span><span class='Number'>4</span> <span class='Function'>⍉</span> <span class='Value'>a23456</span>
 ⟨ 2 5 3 6 4 ⟩
 </pre>
-- 
cgit v1.2.3