Miscellaneous doc tweaks

docs/Basic-App-Structure.md

@@ -9,7 +9,7 @@ To build a re-frame app, you:
 For simpler apps, you should put code for each layer into separate files:
 ```
 src
-├── core.cljs         <--- entry point, plus history
+├── core.cljs         <--- entry point, plus history, routing, etc
 ├── db.cljs           <--- schema, validation, etc  (data layer)
 ├── subs.cljs         <--- subscription handlers  (query layer)
 ├── views.cljs        <--- reagent components (view layer)
@@ -18,20 +18,27 @@ src
 
 For a living example of this approach, look at the [todomvc example](https://github.com/Day8/re-frame/tree/master/examples/todomvc).
 
-### There's A Gotcha
+### There's A Small Gotcha
 
 If you adopt this structure there's a gotcha. 
 
-events.cljs and subs.cljs will never be `required` by any other namespaces. To the Google Closure dependency mechanism it appears as if these two namespaces are not needed and it doesn't load them.
+`events.cljs` and `subs.cljs` will never be `required` by any other 
+namespaces. To the Google Closure dependency mechanism it appears as 
+if these two namespaces are not needed and it doesn't load them.
 
-And, if the code in these namespaces does not get loaded, the registrations in them never happen. You'll be baffled as to why none of your events handlers are registered.
+And, if the code does not get loaded, the registrations in these namespaces
+never happen. You'll then be baffled as to why none of your events handlers 
+are registered.
 
-Once you twig to what's going on, the solution is easy.  You must explicitly `require` both namespaces, `events` and `subs`, in your `core` namespace. Then they'll be loaded and the registrations will occur as the loading happens. 
+Once you twig to what's going on, the solution is easy.  You must 
+explicitly `require` both namespaces, `events` and `subs`, in your `core` 
+namespace. Then they'll be loaded and the registrations will occur 
+as that loading happens. 
 
 ## Larger Apps
 
-Assuming your larger apps has multiple "panels" (or "views") which are relatively independent, you might use this structure:
+Assuming your larger apps has multiple "panels" (or "views") which are 
-
+relatively independent, you might use this structure:
 ```
 src
 ├── panel-1

docs/EffectfulHandlers.md

@@ -298,7 +298,7 @@ More on side effects in a minute, but let's double back to coeffects.
 
 ### The Coeffects
 
-So far we've written our new style `-fx handlers like this:
+So far we've written our new style `-fx` handlers like this:
 ```clj
 (reg-event-fx
    :my-event
@@ -314,10 +314,11 @@ It is now time to name that first argument:
        { ... }))
 ```
 
-When you use the `-fx` form of registration, the first argument of your handler will be a map of coeffects which we name `cofx`.  
+When you use the `-fx` form of registration, the first argument 
+of your handler will be a map of coeffects which we name `cofx`.  
 
 In that map will be the complete set of "inputs" required by your function.  The complete 
-set of computational resources (data) needed to perform its computation. But how?  
+set of computational resources (data) needed to perform its computation. But how?
 This will be explained in an upcoming tutorial, I promise, but for the moment, 
 take it as a magical given. 
 
@@ -332,7 +333,8 @@ Remember this impure handler from before:
        (assoc db :defaults defaults))))
 ```
 
-We'd now rewrite that as a pure handler, like this:
+It was impure because it obtained an input from other than its arguments. 
+We'd now rewrite it as a pure handler, like this:
 ```clj
 (reg-event-fx             ;; notice the -fx
    :load-localstore

docs/coeffects.md

@@ -35,7 +35,7 @@ handler, making this common case easy to program.
 
 But sometimes an event handler needs other data inputs
 to perform its computation.  Things like a random number, or a GUID,
-or the current datetime. It might even need access to a
+or the current datetime. Perhaps it needs access to a
 DataScript connection.
 
 
@@ -50,17 +50,17 @@ This handler obtains data directly from LocalStore:
        (assoc db :defaults val))))
 ```
 
-This works, but there's a cost. 
+This works, but there's a cost.
 
 Because it has directly accessed LocalStore, this event handler is not 
-pure, and impure functions cause well-documented paper cuts. 
+pure, and impure functions cause well-documented paper cuts.
 
 ### How We Want It
 
-Our goal in this tutorial is to rewrite this event handler so 
+Our goal in this tutorial will be to rewrite this event handler so 
-that it __only__ uses data from arguments.
+that it __only__ uses data from arguments. This will take a few steps.
  
-To make this happen, we first switch to
+The first is that we first switch to
 using `reg-event-fx` (instead of `reg-event-db`).
 
 Event handlers registered via `reg-event-fx` are slightly 
@@ -85,8 +85,9 @@ right value. Nice! But how do we make this magic happen?
  
 ### Abracadabra 
 
-Each time an event handler is executed, a brand new `context` is created, and within that 
+Each time an event handler is executed, a brand new `context` 
-`context` is a brand new `:coeffect` map, which is initially totally empty.
+is created, and within that `context` is a brand new `:coeffect` 
+map, which is initially totally empty.
 
 That pristine `context` value (containing a pristine `:coeffect` map) is threaded 
 through a chain of Interceptors before it finally reaches our event handler,
@@ -114,11 +115,11 @@ Something like this (this handler is the same as before, except for one detail):
        {:db (assoc db :defaults val))})) 
 ```
 
-Look at that - my event handler has a new Interceptor!  It is injecting the right key/value pair (`:local-store`)
+Look at that - my event handler has a new Interceptor!  It is injecting the 
-into `context's` `:coeffeects`, which then goes on to be the first argument 
+right key/value pair (`:local-store`)
+into `context's` `:coeffeects`, which itself then goes on to be the first argument 
 to our event handler (`cofx`).
 
-
 ### `inject-cofx`
 
 `inject-cofx` is part of the re-frame API.

images/logo/README.md

@@ -13,23 +13,23 @@ Bruce Lee wielded nunchucks.
 
 ## Genesis Theories
 
-While we shouldn't presume to fathom the cavernous depths of Martin's creativity, 
+Great, unexplained works always encourage fan theories, and the re-frame logo
-great, unexplained works always encourage fan theories. 
+is no exception.
 
-Some have 
+Some speculate @martinklepsch created it as a bifarious rainbow omage
-speculated the re-frame logo was created as a bifarious rainbow omage to Frank Lloyd Wright's Guggenheim.
+to a utilities room in Frank Lloyd Wright's Guggenheim.
 
 ![](Guggenheim.jpg)
 
 <br><br>
-Others disagree and, instead, insist he visually folded (foldv) the cljs logo across re-frame's official 
+Others see the cljs logo folded across re-frame's official 
-architecture diagram to form a flowing poststructuralist rebuttal of OO's tyrannical duplicate 
+architecture diagram, forming a flowing poststructuralist rebuttal of OO's 
-letter adjacency.
+duplicate letter adjacency, and Jackson Pollock's Fractal Expressionism.
 
 
 ![](Genesis.png)
 
-But, are we better off never knowing?  Art requires no answer.
+You be the judge.
 
 ### Instructions