Documentation for Nothing

5 files changed, 19 insertions, 5 deletions

diff --git a/doc/arrayrepr.md b/doc/arrayrepr.md
index 5c425225..ee93b17e 100644
--- a/doc/arrayrepr.md
+++ b/doc/arrayrepr.md
@@ -102,7 +102,7 @@ Even special characters like a newline can appear in a string literal, so that s
 
 ### Brackets
 
-**List notation** uses angle brackets `⟨⟩`. The contents are structurally identical to those of a [block](block.md), that is, a list of expressions [separated](syntax.md#separators) by `,` or `⋄` or newlines. Unlike a block, a list doesn't need to have any expressions: `⟨⟩` or `⟨⋄⟩` or `⟨,,⋄,⟩` will create an empty list. Other differences are that a list doesn't introduce a new [scope](lexical.md) and all of the expressions have to result in a value, not Nothing (`·`).
+**List notation** uses angle brackets `⟨⟩`. The contents are structurally identical to those of a [block](block.md), that is, a list of expressions [separated](syntax.md#separators) by `,` or `⋄` or newlines. Unlike a block, a list doesn't need to have any expressions: `⟨⟩` or `⟨⋄⟩` or `⟨,,⋄,⟩` will create an empty list. Other differences are that a list doesn't introduce a new [scope](lexical.md) and all of the expressions have to result in a value, not [Nothing](expression.md#nothing) (`·`).
 
 Entries in a list are evaluated in source order, and the value will be the list of those results. The list has a subject role, even if it contains expressions with other roles. Any value can be an element.
 
diff --git a/doc/block.md b/doc/block.md
index 473e9c8c..7270f302 100644
--- a/doc/block.md
+++ b/doc/block.md
@@ -26,7 +26,7 @@ An immediate block is only ever evaluated once, and can't be used for control fl
 | Lowercase | Uppercase | Meaning
 |-----------|-----------|---------
 | `𝕩`       | `𝕏`       | Right [argument](#arguments)
-| `𝕨`       | `𝕎`       | Left [argument](#arguments), or Nothing (`·`)
+| `𝕨`       | `𝕎`       | Left [argument](#arguments), or [Nothing](expression.md#nothing) (`·`)
 | `𝕤`       | `𝕊`       | Function [self-reference](#self-reference)
 | `𝕗`       | `𝔽`       | Left [operand](#operands)
 | `𝕘`       | `𝔾`       | Right [operand](#operands)
@@ -42,7 +42,7 @@ The names `𝕨` and `𝕩`, and their uppercase spellings, represent function a
         { 𝕩+↩2 ⋄ 0≍𝕩 } 3
         4 { ⟨𝕩⋄-𝕨⟩ } 5
 
-A function with `𝕨` in its definition doesn't have to be called with two arguments. If it has only one, then `𝕨` is given the special value Nothing `·`. This is the only time a variable can ever be Nothing, as an assignment such as `v←·` is not allowed.
+A function with `𝕨` in its definition doesn't have to be called with two arguments. If it has only one, then `𝕨` is given the special value [Nothing](expression.md#nothing), or `·`. This is the only time a variable can ever be Nothing, as an assignment such as `v←·` is not allowed.
 
         3 { (2×𝕨)-𝕩 } 1
           { (2×𝕨)-𝕩 } 1
diff --git a/doc/expression.md b/doc/expression.md
index 6b29134c..2ec43994 100644
--- a/doc/expression.md
+++ b/doc/expression.md
@@ -19,6 +19,8 @@ BQN expressions consist of subjects, functions, and modifiers arranged in sequen
 
 The four roles (subject, function, two kinds of modifier) describe expressions, not values. When an expression is evaluated, the value's [type](types.md) doesn't have to correspond to its role, and can even change from one evaluation to another. An expression's role is determined entirely by its source code, so it's fixed.
 
+In the table, `?` marks an optional left argument. If there isn't a value in that position, or it's [Nothing](#nothing) (`·`), the middle function will be called with only one argument.
+
 If you're comfortable reading [BNF](https://en.wikipedia.org/wiki/Backus%E2%80%93Naur_form) and want to understand things in more detail than described below, you might check the [grammar specification](../spec/grammar.md) as well.
 
 ## Syntactic role
@@ -48,6 +50,18 @@ Besides these, character, string, and [list literals](arrayrepr.md#list-literals
 
 The role of a compound expression, formed by applying an operation to some inputs, depends on the operation applied. This system is discussed in the remaining sections below.
 
+## Nothing
+
+The character `·` is called Nothing. While it can be easier to think of it as a value, it can't be passed around in variables, and so can also be interpreted as an element of syntax. The special name `𝕨` also functions as Nothing if the block that contains it is called with one argument (the uppercase spelling `𝕎` doesn't, but instead immediately causes an error). Both `·` and `𝕨` have a subject role.
+
+The following rules apply to Nothing:
+- If it's the left argument in a function call, the function is called with no left argument.
+- If it's the right argument, the function isn't called, and "returns" Nothing.
+
+For example, the expression `(F 2 G ·) H I j` is equivalent to `H I j`. But functions and arguments that would be discarded by the second rule are still evaluated, so that for example `(a+↩1) F ·` increments `a` when run.
+
+Nothing can only be used as an argument to a function, or the left argument in a train (it can't be the right argument in a train because a train ends with a function by definition). In another position where a subject could appear, like as an operand or in a list, it causes an error: either at compile time, for `·`, or when the function is called with no left argument, for `𝕨`.
+
 ## Kinds of application
 
 Here is a table of the modifier and function application rules:
diff --git a/doc/glossary.md b/doc/glossary.md
index a3389e3f..f274673e 100644
--- a/doc/glossary.md
+++ b/doc/glossary.md
@@ -105,7 +105,7 @@ The possible roles are:
 
 * **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.
+* [**Nothing**](expression.md#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**](arrayrepr.md#brackets): The angle brackets `⟨⟩` or ligatures used to indicate a list.
diff --git a/doc/train.md b/doc/train.md
index 4f58f454..62127d30 100644
--- a/doc/train.md
+++ b/doc/train.md
@@ -4,7 +4,7 @@
 
 Trains are an important aspect of BQN's [tacit](tacit.md) programming capabilities. In fact, a crucial one: with trains and the [identity functions](identity.md) Left (`⊣`) and Right (`⊢`), a fully tacit program can express any explicit function whose body is a statement with `𝕨` and `𝕩` used only as arguments (that is, there are no assignments and `𝕨` and `𝕩` are not used in operands or lists. Functions with assignments may have too many variables active at once to be directly translated but can be emulated by constructing lists. But it's probably a bad idea). Without trains it isn't possible to have two different functions that each use both arguments to a dyadic function. With trains it's perfectly natural.
 
-BQN's trains are the same as those of Dyalog APL, except that Dyalog is missing the minor convenience of BQN's Nothing (`·`). There are many Dyalog-based documents and videos on trains you can view on the [APL Wiki](https://aplwiki.com/wiki/Train).
+BQN's trains are the same as those of Dyalog APL, except that Dyalog is missing the minor convenience of BQN's [Nothing](expression.md#nothing) (`·`). There are many Dyalog-based documents and videos on trains you can view on the [APL Wiki](https://aplwiki.com/wiki/Train).
 
 ## 2-train, 3-train