More docs

docs/HyperlinkedInformation/Diffs.md

@@ -7,17 +7,21 @@ labelled "Only Before" and "Only After".  Enlightenment is nigh.
 currently in `app-db` or in a given subscription. While current values are good,
 you are often more interested to know how a value has been changed by the epoch. 
 The value might start of as, say, `X` (before the event happened) but 
-ended up as `Y`.  How are `X` and `Y` different, you wonder? 
+ended up as `X'`.  How are `X` and `X'` different, you wonder? 
 What got added or removed? What was modified? 
 
 So, how then to display changes in a way that's easy to grok?  I'm glad you asked. 
-`re-frame-trace` chooses to use the output of `(clojure.data/diff X Y)`.  Remember
+`re-frame-trace` chooses to do a calculation best shown by this pseudo code:
-`X` is the before (original) value, and `Y` is the final value. 
+```clj
+(let [[only-before only-after _] (clojure.data/diff X X')]
+   ...)
+```
+Remember X is the value `before` (this epoch). And `X'` is the value `after` (the epoch has completed). 
 
 By [looking at the docs](https://clojuredocs.org/clojure.data/diff) on `diff`, you'll see
-that it returns a triple of values. `re-frame-trace`  
+that it calculates how two values differ, and returns a triple of values. `re-frame-trace`  
-displays the first two elements of this triple as "only before" and "only after" respectively.
+captures and displays the first two elements of this triple as "only before" and "only after" 
-The 3rd element is not very interesting because it tells us what hasn't changed, so it isn't shown.  
+respectively. The 3rd element is not very interesting because it tells us what hasn't changed, so it isn't shown.  
 
 To correctly interpret "Only Before" and "Only after", you'll need to spend a bit 
 of time properly familiarising yourself with how `clojure.data/diff` works, but

docs/HyperlinkedInformation/UnchangedLayer2.md

@@ -0,0 +1,45 @@
+## Unchanged Layer 2 Subscriptions
+
+This document briefly explains why `re-frame-trace` gives you an option to 
+ignore unchanged layer 2 subscriptions. 
+
+### Background
+
+The `re-frame` docs 
+[make a distinction](https://github.com/Day8/re-frame/blob/master/docs/SubscriptionInfographic.md)
+between `layer 2` and `layer 3` subscriptions:
+  - `layer 2` subscriptions extract data directly from `app-db` and should be
+    trivial in nature. There should be no computation in them beyond
+    what is necessary to extract a value from `app-db`
+  - `layer 3` subscriptions take values from `layer 2` nodes as inputs, and 
+    compute a materialised view of those values. Just to repeat: they never directly 
+    extract values from `app-db`.  They create new values where necessary, and because of it
+    they to do more serious CPU hogging work. So we never want to run 
+    `layer 3` subscriptions unless it is necessary. 
+    
+This structure delivers efficiency. You see, **all** (currently instantiated) `layer 2` subscriptions 
+will run **every** time `app-db` changes in any way. All of them. Every time.
+And `app-db` changes on almost every event, so we want them to be computationally 
+trivial. 
+
+If the value of a `layer 2` subscription tests `=` to its previous value, then the further  
+propagation of values through the signal graph will be pruned.
+The more computationally intensive `layer 3` subscriptions, and ultimately 
+the views, will only recompute if and when there has been a change in their data inputs.  
+
+We don't want your app recomputing views only to find that nothing has changed.
+
+### Back To Tracing
+
+Because `layer 2` subs run on every single modification of `app-db`, and because
+very often nothing has changed, their trace can be a bit noisy.
+
+Yes, it happened, but it just isn't that interesting.
+
+So `re-frame-trace` gives you the option of filtering out trace for 
+the `layer 2` subscriptions where the value this time is the same as the 
+value last time.
+
+On the other hand, if a `layer 2` subscription runs and its value is 
+different to last time, that's potentially fascinating and ypou'll want to 
+be told all about it. :-)