Add glossary to documentation

4 files changed, 278 insertions, 0 deletions

diff --git a/doc/README.md b/doc/README.md
index 823456a9..4969357c 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -28,6 +28,7 @@ Primitives:
 - [Windows](windows.md) (`↕`)
 
 References:
+- [Glossary](glossary.md)
 - [BQN-Dyalog dictionary](fromDyalog.md)
 
 Speculation:
diff --git a/doc/glossary.md b/doc/glossary.md
new file mode 100644
index 00000000..eba5e8c3
--- /dev/null
+++ b/doc/glossary.md
@@ -0,0 +1,131 @@
+*View this file with results and syntax highlighting [here](https://mlochbaum.github.io/BQN/doc/glossary.html).*
+
+# BQN glossary
+
+Below are short, and sometimes vague, definitions of terms used to describe BQN code.
+
+## Types
+
+* **Value**: Something that can be stored in variables and manipulated by a BQN programmer.
+* [**Type**](types.md): One of six possible kinds of value.
+
+The possible types are:
+* [**Number**](types.md#numbers): Like some caveman was counting but then forty thousand years of math happened to it.
+* [**Character**](types.md#characters): A Unicode code point.
+* [**Array**](types.md#arrays): A multidimensional collection of values.
+* [**Function**](types.md#functions): An operation that is called on one or two arguments.
+* [**1-modifier**](types.md#modifiers): An operation that is called on one operand.
+* [**2-modifier**](types.md#modifiers): An operation that is called on two operands.
+
+A few terms refer to multiple types collectively:
+* **Atom**: A value that's not an array.
+* **Modifier**: A 1-modifier or 2-modifier.
+* **Data type**: Number, character, or array.
+* **Operation type**: Function, 1-modifier, or 2-modifier.
+
+BQN uses standard terminology for particular sets of numbers, with natural numbers starting at 0.
+* **Boolean**: 0 or 1.
+* **Natural number**: 0, or 1 plus a natural number; alternatively, a non-negative integer.
+* **Integer**: A natural number or its negation (use "whole number" instead whenever you can get away with it).
+* **Real number** (more accurately, approximate doubly-extended real number): A number with no complex part.
+* **Complex number**: A real number plus *i* (one of the square roots of -1) times another real number.
+
+## Roles
+
+* [**Syntactic role**](context.md): One of four possible types for an expression, which are determined by the expression itself and not outside context and describe how it interacts with other parts of the syntax.
+
+The possible roles are:
+* **Subject**: Can be passed to a function or modifier.
+* **Function**: Can be called on subjects or passed to a modifier.
+* **1-modifier**: Can be called on one subject or function.
+* **2-modifier**: Can be called on two subjects or functions.
+
+## Arrays
+
+* **Array**: A multidimensional collection of values.
+* **Element**: One of the values contained in an array.
+* **Axis**: One dimension or direction in an array.
+* **Rank**: The number of dimensions an array has.
+* **Shape**: The number of elements an array has along each dimension.
+* **Length**: The number of elements an array has along the first dimension, or 1 if it has rank 0.
+* [**Depth**](depth.md): The greatest number of times an element can be selected from a value before reaching an atom.
+* **Fill**: A "prototypical" array element used in certain operations; it's an inferred property of an array.
+
+* **Empty**: Having no elements. An array is empty if its shape contains 0.
+* **Cell**: An array containing all elements of the original array whose indices share a particular prefix.
+* **k-Cell**: A cell of rank *k*.
+* **Major cell**: A cell with rank one less than the original array.
+* **Agreement**: The way elements are paired when a function maps over two arrays.
+* **Frame**: A prefix of an array's shape, used for agreement with the Rank modifier.
+
+* **Unit**: An array of rank 0, or an atom.
+* **Unit array**: An array of rank 0 other than an atom.
+* **List**: An array of rank 1.
+* **String**: A list of characters.
+* **Table**: An array of rank 2.
+
+* [**Index**](indices.md): One of a variety of ways to select an element, cell, axis, or position along an axis of an array.
+
+## Operations
+
+* **Operation**: A value that is called on inputs to perform computation and return a result or cause an error.
+* **Call**: Submit inputs to an operation and receive any result.
+* **Input**: A value given (*passed*) to an operation when it's called.
+* **Result**: A value returned from an operation when called.
+* **Argument**: An input to a function.
+* **Operand**: An input to a modifier.
+* **Valence**: The number of arguments that can be or are passed to a function.
+* **Ambivalent**: A function that can be called with one or two arguments without causing an error.
+* **Monadic**: Called with one argument, either always (a monadic function) or in a particular instance (a monadic call).
+* **Dyadic**: Called with two arguments, always or in a particular instance.
+
+* **Derived function**: A function produced by binding operands to a deferred modifier; doing so does not cause any computation.
+* **Train**: A function composed of two or more functions.
+* **Identity element**: An inferred property of a function: the result of a reduction with this function on an empty array.
+
+* **Error**: A condition that stops compilation or execution.
+* **Inferred property**: A property of a value that is derived by BQN based on constraints. If it cannot be derived then the value will not have the property.
+
+## Tokens
+
+* **Token formation** or tokenization: Splitting source code into a sequence of tokens.
+* **Token**: A name, literal, primitive, or other syntactic element.
+* **Literal**: A token that indicates a fixed value of a data type.
+* **Primitive**: One of several fixed operations defined by the language, denoted by a single-character token.
+* **Word**: A sequence of alphabetic or numeric characters.
+* **Name**: A word that starts with an alphabetic character. Names are compared case-insensitively and ignoring underscores `_`.
+* **Numeric literal**: A word that starts with a numeric character, indicating a number.
+* **String literal**: A literal written with double quotes `""`, indicating a string.
+* **Character literal**: A literal written with single quotes `''`, indicating a string.
+* **Null literal**: The literal `@`, indicating the null character (code point 0).
+
+## Parsing
+
+* **Parsing**: Analysis of the tokens of a program, which determines which actions will be taken to evaluate it.
+* [**Expression**](syntax.md#expressions): A piece of code that defines a (not necessarily constant) variable.
+* **Nothing**: A special value-like entity that comes from `·`, `𝕨` in a function with no left argument, or a function called on nothing.
+* **Statement**: An expression, or nothing (`·`).
+* **Ligature**: The character `‿`.
+* [**List notation**](syntax.md#list-notation): The angle brackets `⟨⟩` or ligatures used to indicate a list.
+
+## Assignment and scoping
+
+* [**Assignment**](syntax.md#assignment): An operation that sets a variable's value. Definition (`←`) or a change of definition (`↩`).
+* **Assignment arrow**: `←` or `↩`, used to denote assignment.
+* **Definition**: The first assignment of a variable, which must be performed with `←`.
+
+* **Scope**: An environment where variables are defined and manipulated, which is created before evaluating a body.
+* **Identifier**: An instance of a name in a program, with two identifiers considered the same if they correspond to the same definition.
+
+## Blocks
+
+* [**Block**](block.md): A syntactic element surrounded in curly braces `{}`, which encapsulates code.
+* **Immediate block**: A block that is evaluated and returns a value immediately; it has a subject role.
+* **Block function**: A block defining a function.
+* **Block modifier**: A block defining a 1- or 2-modifier.
+* **Immediate modifier**: A modifier that's evaluated as soon as it receives its operands.
+* **Deferred modifier**: The opposite of an immediate modifier, one that's only evaluated when called with operands and arguments.
+* [**Header**](block.md#block-headers): A preface to a body in a block function or modifier indicating possible inputs, which is followed by a colon `:`.
+* [**Label**](block.md#short-headers): A header consisting of a single name.
+* **Body**: One sequence of statements in a block. Bodies, possibly preceded by headers, are separated by semicolons `;`.
+* **Tacit**: Code that defines functions or modifiers without using blocks.
diff --git a/docs/doc/glossary.html b/docs/doc/glossary.html
new file mode 100644
index 00000000..f6f2cc30
--- /dev/null
+++ b/docs/doc/glossary.html
@@ -0,0 +1,145 @@
+<head>
+  <link href="../favicon.ico" rel="shortcut icon" type="image/x-icon"/>
+  <link href="../style.css" rel="stylesheet"/>
+  <title>BQN glossary</title>
+</head>
+<div class="nav"><a href="https://github.com/mlochbaum/BQN">BQN</a></div>
+<h1 id="bqn-glossary">BQN glossary</h1>
+<p>Below are short, and sometimes vague, definitions of terms used to describe BQN code.</p>
+<h2 id="types">Types</h2>
+<ul>
+<li><strong>Value</strong>: Something that can be stored in variables and manipulated by a BQN programmer.</li>
+<li><a href="types.html"><strong>Type</strong></a>: One of six possible kinds of value.</li>
+</ul>
+<p>The possible types are:</p>
+<ul>
+<li><a href="types.html#numbers"><strong>Number</strong></a>: Like some caveman was counting but then forty thousand years of math happened to it.</li>
+<li><a href="types.html#characters"><strong>Character</strong></a>: A Unicode code point.</li>
+<li><a href="types.html#arrays"><strong>Array</strong></a>: A multidimensional collection of values.</li>
+<li><a href="types.html#functions"><strong>Function</strong></a>: An operation that is called on one or two arguments.</li>
+<li><a href="types.html#modifiers"><strong>1-modifier</strong></a>: An operation that is called on one operand.</li>
+<li><a href="types.html#modifiers"><strong>2-modifier</strong></a>: An operation that is called on two operands.</li>
+</ul>
+<p>A few terms refer to multiple types collectively:</p>
+<ul>
+<li><strong>Atom</strong>: A value that's not an array.</li>
+<li><strong>Modifier</strong>: A 1-modifier or 2-modifier.</li>
+<li><strong>Data type</strong>: Number, character, or array.</li>
+<li><strong>Operation type</strong>: Function, 1-modifier, or 2-modifier.</li>
+</ul>
+<p>BQN uses standard terminology for particular sets of numbers, with natural numbers starting at 0.</p>
+<ul>
+<li><strong>Boolean</strong>: 0 or 1.</li>
+<li><strong>Natural number</strong>: 0, or 1 plus a natural number; alternatively, a non-negative integer.</li>
+<li><strong>Integer</strong>: A natural number or its negation (use &quot;whole number&quot; instead whenever you can get away with it).</li>
+<li><strong>Real number</strong> (more accurately, approximate doubly-extended real number): A number with no complex part.</li>
+<li><strong>Complex number</strong>: A real number plus <em>i</em> (one of the square roots of -1) times another real number.</li>
+</ul>
+<h2 id="roles">Roles</h2>
+<ul>
+<li><a href="context.html"><strong>Syntactic role</strong></a>: One of four possible types for an expression, which are determined by the expression itself and not outside context and describe how it interacts with other parts of the syntax.</li>
+</ul>
+<p>The possible roles are:</p>
+<ul>
+<li><strong>Subject</strong>: Can be passed to a function or modifier.</li>
+<li><strong>Function</strong>: Can be called on subjects or passed to a modifier.</li>
+<li><strong>1-modifier</strong>: Can be called on one subject or function.</li>
+<li><strong>2-modifier</strong>: Can be called on two subjects or functions.</li>
+</ul>
+<h2 id="arrays">Arrays</h2>
+<ul>
+<li><strong>Array</strong>: A multidimensional collection of values.</li>
+<li><strong>Element</strong>: One of the values contained in an array.</li>
+<li><strong>Axis</strong>: One dimension or direction in an array.</li>
+<li><strong>Rank</strong>: The number of dimensions an array has.</li>
+<li><strong>Shape</strong>: The number of elements an array has along each dimension.</li>
+<li><strong>Length</strong>: The number of elements an array has along the first dimension, or 1 if it has rank 0.</li>
+<li><a href="depth.html"><strong>Depth</strong></a>: The greatest number of times an element can be selected from a value before reaching an atom.</li>
+<li><strong>Fill</strong>: A &quot;prototypical&quot; array element used in certain operations; it's an inferred property of an array.</li>
+</ul>
+<ul>
+<li><strong>Empty</strong>: Having no elements. An array is empty if its shape contains 0.</li>
+<li><strong>Cell</strong>: An array containing all elements of the original array whose indices share a particular prefix.</li>
+<li><strong>k-Cell</strong>: A cell of rank <em>k</em>.</li>
+<li><strong>Major cell</strong>: A cell with rank one less than the original array.</li>
+<li><strong>Agreement</strong>: The way elements are paired when a function maps over two arrays.</li>
+<li><strong>Frame</strong>: A prefix of an array's shape, used for agreement with the Rank modifier.</li>
+</ul>
+<ul>
+<li><strong>Unit</strong>: An array of rank 0, or an atom.</li>
+<li><strong>Unit array</strong>: An array of rank 0 other than an atom.</li>
+<li><strong>List</strong>: An array of rank 1.</li>
+<li><strong>String</strong>: A list of characters.</li>
+<li><strong>Table</strong>: An array of rank 2.</li>
+</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>
+</ul>
+<h2 id="operations">Operations</h2>
+<ul>
+<li><strong>Operation</strong>: A value that is called on inputs to perform computation and return a result or cause an error.</li>
+<li><strong>Call</strong>: Submit inputs to an operation and receive any result.</li>
+<li><strong>Input</strong>: A value given (<em>passed</em>) to an operation when it's called.</li>
+<li><strong>Result</strong>: A value returned from an operation when called.</li>
+<li><strong>Argument</strong>: An input to a function.</li>
+<li><strong>Operand</strong>: An input to a modifier.</li>
+<li><strong>Valence</strong>: The number of arguments that can be or are passed to a function.</li>
+<li><strong>Ambivalent</strong>: A function that can be called with one or two arguments without causing an error.</li>
+<li><strong>Monadic</strong>: Called with one argument, either always (a monadic function) or in a particular instance (a monadic call).</li>
+<li><strong>Dyadic</strong>: Called with two arguments, always or in a particular instance.</li>
+</ul>
+<ul>
+<li><strong>Derived function</strong>: A function produced by binding operands to a deferred modifier; doing so does not cause any computation.</li>
+<li><strong>Train</strong>: A function composed of two or more functions.</li>
+<li><strong>Identity element</strong>: An inferred property of a function: the result of a reduction with this function on an empty array.</li>
+</ul>
+<ul>
+<li><strong>Error</strong>: A condition that stops compilation or execution.</li>
+<li><strong>Inferred property</strong>: A property of a value that is derived by BQN based on constraints. If it cannot be derived then the value will not have the property.</li>
+</ul>
+<h2 id="tokens">Tokens</h2>
+<ul>
+<li><strong>Token formation</strong> or tokenization: Splitting source code into a sequence of tokens.</li>
+<li><strong>Token</strong>: A name, literal, primitive, or other syntactic element.</li>
+<li><strong>Literal</strong>: A token that indicates a fixed value of a data type.</li>
+<li><strong>Primitive</strong>: One of several fixed operations defined by the language, denoted by a single-character token.</li>
+<li><strong>Word</strong>: A sequence of alphabetic or numeric characters.</li>
+<li><strong>Name</strong>: A word that starts with an alphabetic character. Names are compared case-insensitively and ignoring underscores <code><span class='Modifier2'>_</span></code>.</li>
+<li><strong>Numeric literal</strong>: A word that starts with a numeric character, indicating a number.</li>
+<li><strong>String literal</strong>: A literal written with double quotes <code><span class='String'>&quot;&quot;</span></code>, indicating a string.</li>
+<li><strong>Character literal</strong>: A literal written with single quotes <code><span class='String'>''</span></code>, indicating a string.</li>
+<li><strong>Null literal</strong>: The literal <code><span class='String'>@</span></code>, indicating the null character (code point 0).</li>
+</ul>
+<h2 id="parsing">Parsing</h2>
+<ul>
+<li><strong>Parsing</strong>: Analysis of the tokens of a program, which determines which actions will be taken to evaluate it.</li>
+<li><a href="syntax.html#expressions"><strong>Expression</strong></a>: A piece of code that defines a (not necessarily constant) variable.</li>
+<li><strong>Nothing</strong>: A special value-like entity that comes from <code><span class='Nothing'>·</span></code>, <code><span class='Value'>𝕨</span></code> in a function with no left argument, or a function called on nothing.</li>
+<li><strong>Statement</strong>: An expression, or nothing (<code><span class='Nothing'>·</span></code>).</li>
+<li><strong>Ligature</strong>: The character <code><span class='Ligature'>‿</span></code>.</li>
+<li><a href="syntax.html#list-notation"><strong>List notation</strong></a>: The angle brackets <code><span class='Bracket'>⟨⟩</span></code> or ligatures used to indicate a list.</li>
+</ul>
+<h2 id="assignment-and-scoping">Assignment and scoping</h2>
+<ul>
+<li><a href="syntax.html#assignment"><strong>Assignment</strong></a>: An operation that sets a variable's value. Definition (<code><span class='Gets'>←</span></code>) or a change of definition (<code><span class='Gets'>↩</span></code>).</li>
+<li><strong>Assignment arrow</strong>: <code><span class='Gets'>←</span></code> or <code><span class='Gets'>↩</span></code>, used to denote assignment.</li>
+<li><strong>Definition</strong>: The first assignment of a variable, which must be performed with <code><span class='Gets'>←</span></code>.</li>
+</ul>
+<ul>
+<li><strong>Scope</strong>: An environment where variables are defined and manipulated, which is created before evaluating a body.</li>
+<li><strong>Identifier</strong>: An instance of a name in a program, with two identifiers considered the same if they correspond to the same definition.</li>
+</ul>
+<h2 id="blocks">Blocks</h2>
+<ul>
+<li><a href="block.html"><strong>Block</strong></a>: A syntactic element surrounded in curly braces <code><span class='Brace'>{}</span></code>, which encapsulates code.</li>
+<li><strong>Immediate block</strong>: A block that is evaluated and returns a value immediately; it has a subject role.</li>
+<li><strong>Block function</strong>: A block defining a function.</li>
+<li><strong>Block modifier</strong>: A block defining a 1- or 2-modifier.</li>
+<li><strong>Immediate modifier</strong>: A modifier that's evaluated as soon as it receives its operands.</li>
+<li><strong>Deferred modifier</strong>: The opposite of an immediate modifier, one that's only evaluated when called with operands and arguments.</li>
+<li><a href="block.html#block-headers"><strong>Header</strong></a>: A preface to a body in a block function or modifier indicating possible inputs, which is followed by a colon <code><span class='Value'>:</span></code>.</li>
+<li><a href="block.html#short-headers"><strong>Label</strong></a>: A header consisting of a single name.</li>
+<li><strong>Body</strong>: One sequence of statements in a block. Bodies, possibly preceded by headers, are separated by semicolons <code><span class='Value'>;</span></code>.</li>
+<li><strong>Tacit</strong>: Code that defines functions or modifiers without using blocks.</li>
+</ul>
+
diff --git a/docs/doc/index.html b/docs/doc/index.html
index ca968875..44888e64 100644
--- a/docs/doc/index.html
+++ b/docs/doc/index.html
@@ -34,6 +34,7 @@
 </ul>
 <p>References:</p>
 <ul>
+<li><a href="glossary.html">Glossary</a></li>
 <li><a href="fromDyalog.html">BQN-Dyalog dictionary</a></li>
 </ul>
 <p>Speculation:</p>