Discuss the pure-functional nature of primitives in primitive.md

3 files changed, 9 insertions, 3 deletions

diff --git a/doc/primitive.md b/doc/primitive.md
index 12e221b6..eabebbdd 100644
--- a/doc/primitive.md
+++ b/doc/primitive.md
@@ -2,7 +2,11 @@
 
 # BQN primitives
 
-*Primitives* are functions and modifiers that are built into the language.
+*Primitives* are functions and modifiers that are built into the language and written with individual glyphs. The role of a primitive when written always matches its type (but you can use its value in other roles by assigning it or various other methods).
+
+Primitives have no side effects other than errors, and can't perform infinite computations, except in the case that the operand to a primitive modifier is a function that has side effects or never returns (primitive modifiers never perform computation when passed operands—they always bind the operands and act when called on arguments). Side effects here include both writing state such as variables or printed output, and reading any outside state, so that a function with no side effects always returns the same result if passed the same arguments. Trains and list notation have the same properties, so that tacit code written entirely with primitives, trains, and lists always describes finite, self-contained computations.
+
+Recursion is the primary way to perform potentially infinite computations in BQN, and it can be packaged into [control structures](control.md) like `While` for ease of use. A given BQN implementation might also provide [system values](../spec/system.md) for "impure" tasks like file access or other I/O.
 
 ## Functions
 
diff --git a/docs/doc/primitive.html b/docs/doc/primitive.html
index c5d89a0b..d9d696dc 100644
--- a/docs/doc/primitive.html
+++ b/docs/doc/primitive.html
@@ -5,7 +5,9 @@
 </head>
 <div class="nav"><a href="https://github.com/mlochbaum/BQN">BQN</a> / <a href="../index.html">main</a> / <a href="index.html">doc</a></div>
 <h1 id="bqn-primitives">BQN primitives</h1>
-<p><em>Primitives</em> are functions and modifiers that are built into the language.</p>
+<p><em>Primitives</em> are functions and modifiers that are built into the language and written with individual glyphs. The role of a primitive when written always matches its type (but you can use its value in other roles by assigning it or various other methods).</p>
+<p>Primitives have no side effects other than errors, and can't perform infinite computations, except in the case that the operand to a primitive modifier is a function that has side effects or never returns (primitive modifiers never perform computation when passed operands—they always bind the operands and act when called on arguments). Side effects here include both writing state such as variables or printed output, and reading any outside state, so that a function with no side effects always returns the same result if passed the same arguments. Trains and list notation have the same properties, so that tacit code written entirely with primitives, trains, and lists always describes finite, self-contained computations.</p>
+<p>Recursion is the primary way to perform potentially infinite computations in BQN, and it can be packaged into <a href="control.html">control structures</a> like <code><span class='Function'>While</span></code> for ease of use. A given BQN implementation might also provide <a href="../spec/system.html">system values</a> for &quot;impure&quot; tasks like file access or other I/O.</p>
 <h2 id="functions">Functions</h2>
 <p>Functions that have significant differences from APL functions are marked with an asterisk. Links for these entries go to dedicated BQN documentation while other links go to the APL Wiki.</p>
 <table>
diff --git a/docs/try.html b/docs/try.html
index d6617dbb..865fd36c 100644
--- a/docs/try.html
+++ b/docs/try.html
@@ -30,7 +30,7 @@
   <p>
     Notes:
     <ul>
-      <li>You can type special characters with a back<em>slash</em> prefix, as shown by hovering over the character bar above. Documentation links for primitives are <a href="doc/primitive.html">here</a>.</li>
+      <li>You can type special characters with a back<em>slash</em> prefix, as shown by hovering over the character bar above. Documentation links for primitives are <a href="doc/primitive.html#functions">here</a>.</li>
       <li>Any modifier with enter will execute, not just shift. The code window is vertically resizeable.</li>
       <li>Support for function headers and multiple bodies is missing.</li>
       <li>It's slow, but not <em>that</em> slow: usually most of the time is spent compiling your code, and sometimes from formatting the output. Chrome is faster than Firefox here, and speeds up over a few runs as JIT compilation kicks in.</li>