Revision of docs (#10)

* Port updates back to chapter 2

* Update older visuals to match new format

* Update older visuals to match new format

* update docs

5 files changed, 144 insertions, 41 deletions

diff --git a/chapter01/README.md b/chapter01/README.md
index 57caa801..e09b61a3 100644
--- a/chapter01/README.md
+++ b/chapter01/README.md
@@ -29,8 +29,7 @@ We design our parser and compiler to illustrate some key aspects of the Sea of N
 Intermediate Representation: 
 
 * We construct the intermediate Sea of Nodes representation directly as we parse the language. There is no Abstract Syntax Tree representation.
-
-* The compiler will perform a few basic local optimizations as we build the IR; this is a key benefit of the Sea of Nodes IR. This aspect is more fully explored from Chapter 2 onwards.
+* The compiler will perform a few basic local optimizations as we build the IR; this is a key benefit of the Sea of Nodes IR. This aspect is more fully explored from [Chapter 2](../chapter02/README.md) onwards.
 
 ## Data Structures
 
@@ -50,7 +49,57 @@ The intermediate representation is a graph of Node objects. The `Node` class is
 The `Node` class provides common capabilities that are inherited by all subtypes. 
 Each subtype implements semantics relevant to that subtype.
 
-There are two types of Nodes in the representation.
+Each `Node` represents an "instruction" as it may appear in traditional IRs.
+
+### Nodes are in a Graph
+
+The key idea of the Sea of Nodes IR is that each Node is linked to other Nodes by def-use dependencies.
+As this is such an important and fundamental aspect of the IR, it is important to understand how we implement this, and depict in graph visuals.
+
+The base `Node` class maintains a list of Nodes that are inputs to it. An input is an edge from a "def" to a "use". What this means is that if `B` is definition, and `A` uses `B`,
+then there is a def-use edge from `B` to `A`.
+
+Visually we show an arrow from the "use" to the "def". Here is an example:
+
+![Use Def](./docs/01-use-def.svg)
+
+From an implementation point of view, our `Node` type also maintains a reverse link.
+This means that in the above scenario:
+
+* Since `A` is a "use" of `B`, then `B` will appear in `A`'s list of inputs.
+* Conversely, `B` maintains a list of outputs, and `A` will appear in this list.
+* A key invariant is that these edges must be in sync at all times.
+
+Here is how this looks in the `Node` class:
+
+```java
+public abstract class Node {
+
+    /**
+     * Inputs to the node. These are use-def references to Nodes.
+     * <p>
+     * Generally fixed length, ordered, nulls allowed, no unused trailing space.
+     * Ordering is required because e.g. "a/b" is different from "b/a".
+     * The first input (offset 0) is often a Control node.
+     */
+    public final ArrayList<Node> _inputs;
+
+    /**
+     * Outputs reference Nodes that are not null and have this Node as an
+     * input.  These nodes are users of this node, thus these are def-use
+     * references to Nodes.
+     * <p>
+     * Outputs directly match inputs, making a directed graph that can be
+     * walked in either direction.  These outputs are typically used for
+     * efficient optimizations but otherwise have no semantics meaning.
+     */
+    public final ArrayList<Node> _outputs;
+}
+```
+
+### Types of Nodes
+
+There are two categories of Nodes in the intermediate representation.
 
 * **Control Nodes** - these represent the control flow subgraph (CFG) of the compiled program
 * **Data Nodes** - these capture the data semantics
@@ -80,7 +129,7 @@ graph.  We discuss Node equality in Chapter 8 Global Value Numbering.
 
 The Start node represents the start of the function.  For now, we do not have any inputs to Start because our function does not 
 yet accept parameters.  When we add parameters the value of Start will be a tuple, and will require Projections to extract the values. 
-We discuss this in detail in Chapter 9: Functions and Calls.
+We discuss this in detail in [Chapter 4](../chapter04/README.md).
 
 ### Constant Node
 
@@ -101,7 +150,7 @@ The Return node has two inputs.  The first input is a control node and the
 second is the data node that supplies the return value.
 
 In this presentation, Return functions as a Stop node, since multiple `return` statements are not possible.
-The Stop node will be introduced in Chapter 6 when we implement `if` statements. 
+The Stop node will be introduced in Chapter 5 when we implement `if` statements. 
 
 The Return's output is the value from the data node.
 
diff --git a/chapter01/docs/01-graph.gv b/chapter01/docs/01-graph.gv
index 40181544..82d1b40a 100644
--- a/chapter01/docs/01-graph.gv
+++ b/chapter01/docs/01-graph.gv
@@ -1,9 +1,11 @@
-digraph chapter01 
-{
-    start [shape=box, label="Start"];
-    constant [label="Constant 1"];
-    return [shape=box, label="Return"];
-    constant -> return;
-    edge [color=red];
-    start -> return [style=bold];
-}
\ No newline at end of file
+digraph chapter01 {
+	rankdir=BT;
+	subgraph cluster_Nodes {
+		Start1 [ shape=box style=filled fillcolor=yellow label="Start" ];
+		Con12 [ label="Con1" ];
+		Return3 [ shape=box style=filled fillcolor=yellow label="Return" ];
+	}
+	Con12 -> Start1 [style=dotted];
+	Return3 -> Start1 [color=red];
+	Return3 -> Con12;
+}
diff --git a/chapter01/docs/01-graph.svg b/chapter01/docs/01-graph.svg
index fbf92d7d..8e478f4d 100644
--- a/chapter01/docs/01-graph.svg
+++ b/chapter01/docs/01-graph.svg
@@ -4,40 +4,50 @@
 <!-- Generated by graphviz version 2.43.0 (0)
  -->
 <!-- Title: chapter01 Pages: 1 -->
-<svg width="204pt" height="116pt"
- viewBox="0.00 0.00 203.74 116.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
-<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 112)">
+<svg width="128pt" height="220pt"
+ viewBox="0.00 0.00 128.00 220.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 216)">
 <title>chapter01</title>
-<polygon fill="white" stroke="transparent" points="-4,4 -4,-112 199.74,-112 199.74,4 -4,4"/>
-<!-- start -->
+<polygon fill="white" stroke="transparent" points="-4,4 -4,-216 124,-216 124,4 -4,4"/>
+<g id="clust1" class="cluster">
+<title>cluster_Nodes</title>
+<polygon fill="none" stroke="black" points="8,-8 8,-204 112,-204 112,-8 8,-8"/>
+</g>
+<!-- Start1 -->
 <g id="node1" class="node">
-<title>start</title>
-<polygon fill="none" stroke="black" points="54,-108 0,-108 0,-72 54,-72 54,-108"/>
-<text text-anchor="middle" x="27" y="-86.3" font-family="Times,serif" font-size="14.00">Start</text>
+<title>Start1</title>
+<polygon fill="yellow" stroke="black" points="83,-196 29,-196 29,-160 83,-160 83,-196"/>
+<text text-anchor="middle" x="56" y="-174.3" font-family="Times,serif" font-size="14.00">Start</text>
+</g>
+<!-- Con12 -->
+<g id="node2" class="node">
+<title>Con12</title>
+<ellipse fill="none" stroke="black" cx="70" cy="-106" rx="34.39" ry="18"/>
+<text text-anchor="middle" x="70" y="-102.3" font-family="Times,serif" font-size="14.00">Con1</text>
+</g>
+<!-- Con12&#45;&gt;Start1 -->
+<g id="edge1" class="edge">
+<title>Con12&#45;&gt;Start1</title>
+<path fill="none" stroke="black" stroke-dasharray="1,5" d="M66.61,-123.95C65.07,-131.65 63.21,-140.97 61.47,-149.64"/>
+<polygon fill="black" stroke="black" points="57.98,-149.23 59.46,-159.72 64.85,-150.61 57.98,-149.23"/>
 </g>
-<!-- return -->
+<!-- Return3 -->
 <g id="node3" class="node">
-<title>return</title>
-<polygon fill="none" stroke="black" points="113,-36 47,-36 47,0 113,0 113,-36"/>
-<text text-anchor="middle" x="80" y="-14.3" font-family="Times,serif" font-size="14.00">Return</text>
+<title>Return3</title>
+<polygon fill="yellow" stroke="black" points="92,-52 26,-52 26,-16 92,-16 92,-52"/>
+<text text-anchor="middle" x="59" y="-30.3" font-family="Times,serif" font-size="14.00">Return</text>
 </g>
-<!-- start&#45;&gt;return -->
+<!-- Return3&#45;&gt;Start1 -->
 <g id="edge2" class="edge">
-<title>start&#45;&gt;return</title>
-<path fill="none" stroke="red" stroke-width="2" d="M40.1,-71.7C46.39,-63.39 54.05,-53.28 60.96,-44.14"/>
-<polygon fill="red" stroke="red" stroke-width="2" points="63.8,-46.19 67.05,-36.1 58.22,-41.96 63.8,-46.19"/>
-</g>
-<!-- constant -->
-<g id="node2" class="node">
-<title>constant</title>
-<ellipse fill="none" stroke="black" cx="134" cy="-90" rx="61.99" ry="18"/>
-<text text-anchor="middle" x="134" y="-86.3" font-family="Times,serif" font-size="14.00">Constant 1</text>
+<title>Return3&#45;&gt;Start1</title>
+<path fill="none" stroke="red" d="M45.44,-52.03C38.44,-61.91 30.63,-74.95 27,-88 22.71,-103.41 23.04,-108.5 27,-124 29.38,-133.3 33.76,-142.73 38.42,-151"/>
+<polygon fill="red" stroke="red" points="35.54,-153.01 43.69,-159.78 41.54,-149.41 35.54,-153.01"/>
 </g>
-<!-- constant&#45;&gt;return -->
-<g id="edge1" class="edge">
-<title>constant&#45;&gt;return</title>
-<path fill="none" stroke="black" d="M120.93,-72.05C114.52,-63.75 106.68,-53.58 99.58,-44.38"/>
-<polygon fill="black" stroke="black" points="102.21,-42.06 93.33,-36.28 96.66,-46.33 102.21,-42.06"/>
+<!-- Return3&#45;&gt;Con12 -->
+<g id="edge3" class="edge">
+<title>Return3&#45;&gt;Con12</title>
+<path fill="none" stroke="black" d="M61.72,-52.3C62.93,-60.02 64.39,-69.29 65.74,-77.89"/>
+<polygon fill="black" stroke="black" points="62.3,-78.56 67.31,-87.9 69.22,-77.47 62.3,-78.56"/>
 </g>
 </g>
 </svg>
diff --git a/chapter01/docs/01-use-def.gv b/chapter01/docs/01-use-def.gv
new file mode 100644
index 00000000..d0e84ecb
--- /dev/null
+++ b/chapter01/docs/01-use-def.gv
@@ -0,0 +1,7 @@
+digraph chapter01 {
+	rankdir=BT;
+	subgraph cluster_Nodes {
+		A, B;
+	}
+    A -> B;
+}
diff --git a/chapter01/docs/01-use-def.svg b/chapter01/docs/01-use-def.svg
new file mode 100644
index 00000000..644ab5a2
--- /dev/null
+++ b/chapter01/docs/01-use-def.svg
@@ -0,0 +1,35 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
+ "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<!-- Generated by graphviz version 2.43.0 (0)
+ -->
+<!-- Title: chapter01 Pages: 1 -->
+<svg width="94pt" height="148pt"
+ viewBox="0.00 0.00 94.00 148.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 144)">
+<title>chapter01</title>
+<polygon fill="white" stroke="transparent" points="-4,4 -4,-144 90,-144 90,4 -4,4"/>
+<g id="clust1" class="cluster">
+<title>cluster_Nodes</title>
+<polygon fill="none" stroke="black" points="8,-8 8,-132 78,-132 78,-8 8,-8"/>
+</g>
+<!-- A -->
+<g id="node1" class="node">
+<title>A</title>
+<ellipse fill="none" stroke="black" cx="43" cy="-34" rx="27" ry="18"/>
+<text text-anchor="middle" x="43" y="-30.3" font-family="Times,serif" font-size="14.00">A</text>
+</g>
+<!-- B -->
+<g id="node2" class="node">
+<title>B</title>
+<ellipse fill="none" stroke="black" cx="43" cy="-106" rx="27" ry="18"/>
+<text text-anchor="middle" x="43" y="-102.3" font-family="Times,serif" font-size="14.00">B</text>
+</g>
+<!-- A&#45;&gt;B -->
+<g id="edge1" class="edge">
+<title>A&#45;&gt;B</title>
+<path fill="none" stroke="black" d="M43,-52.3C43,-60.02 43,-69.29 43,-77.89"/>
+<polygon fill="black" stroke="black" points="39.5,-77.9 43,-87.9 46.5,-77.9 39.5,-77.9"/>
+</g>
+</g>
+</svg>