Update the README

README.md

@@ -1,28 +1,30 @@
-diffHTML: A JavaScript View Layer
----------------------------------
+# <div style="background-color: #FFF; display: inline-block; padding: 10px 0px; color: #333;"><±/> diffHTML</div>
 
-Latest stable version: 0.9.1
+*A powerful JavaScript library for building user interfaces.*
 
 [![Build Status](https://travis-ci.org/tbranyen/diffhtml.svg?branch=master)](https://travis-ci.org/tbranyen/diffhtml)
 [![Coverage
 Status](https://coveralls.io/repos/tbranyen/diffhtml/badge.svg?branch=master&service=github)](https://coveralls.io/github/tbranyen/diffhtml?branch=master) 
 [![Join the chat at https://gitter.im/tbranyen/diffhtml](https://img.shields.io/badge/GITTER-join%20chat-green.svg)](https://gitter.im/tbranyen/diffhtml)
 
-Inspired by React and motivated by the Web, this is a lowish-level tool which
-aims to help web developers write components for the web. By focusing on the
-markup representing how your application state should look, diffHTML will
-figure out how to modify the page with a minimal amount of operations. This
-tool is designed and optimized around HTML and standards features within
-JavaScript.
+Stable version: 0.9.1
 
-It works by parsing your HTML markup into a lightweight JSON-serializable
-Virtual DOM heirarchy. I refer to these as Virtual Trees or *VTree*. These
-element (and attribute) objects are pooled to provide consistent memory
-management and garbage collection. diffHTML maintains a single VTree root that
-mirrors a mounted element in the DOM, it reconciles all future renders into
-this tree and the DOM.
+Inspired by React and motivated by the Web, this is a library designed to help
+web developers write components for the web. By focusing on the markup
+representing how your application state should look, diffHTML will figure out
+how to modify the page with a minimal amount of operations. This tool is
+designed and optimized around HTML and standard features within JavaScript.
 
-#### Features
+## Quick Jump
+
+- [Features](#features)
+- [Install](#install)
+- [Quick start](#quick-start)
+- [API](#API)
+
+## Features
+
+[Back to quick jump...](#quick-jump)
 
 - Helps you build components using HTML and JavaScript
 - [Provides a tagged template
@@ -32,30 +34,59 @@ this tree and the DOM.
 - Object pooling to avoid GC thrashing and expensive childNode/attribute/uuid
   generation
 
-### Install
+#### Browser support
+
+## Install
 
-The latest built version is available for quick download from the [master
+[Back to quick jump...](#quick-jump)
+
+The latest built version (but not necessarily the latest stable) is available
+for quick download from the [master
 branch](https://raw.githubusercontent.com/tbranyen/diffhtml/master/dist/diffhtml.js).
+Use this to test the bleeding edge.
 
 Or you can use npm:
 
 ``` sh
-npm install diffhtml
+npm install diffhtml --save
 ```
 
 The module can be required via Node or browser environments. It is exported as
-a global named `diff` unless loaded as a module.
+a global named `diff` unless loaded as a module, in which case you determine
+the name.
+
+In the browser:
+
+``` html
+<script src="node_modules/diffhtml/dist/diffhtml.js"></script>
+<script>diff.innerHTML(document.body, 'Hello world!');</script>
+```
 
-You can import only what you need if you're using ES6 modules with a
-transpiler:
+With CommonJS you can import the entire module:
 
 ``` javascript
-import { innerHTML } from 'diffhtml';
+const diff = require('diffhtml');
+diff.innerHTML(document.body, 'Hello world!');
+```
+
+You can import only what you need if you're using ES Modules:
 
+``` javascript
+import { innerHTML } from 'diffhtml';
 innerHTML(document.body, 'Hello world!');
 ```
 
-##### Polyfills
+#### Module format locations
+
+This library is authored in vanilla ES2015 with no experimental syntax enabled, the syntax is ES Modules and is transpiled to CJS with Babel. The UMD build is generated by browserify.
+
+| Format                   | Location
+| ------------------------ | ---------------------------
+| UMD (AMD/CJS/Browser)    | `diffhtml/dist/diffhtml.js`
+| CJS                      | `diffhtml/dist/cjs/*`
+| ES6                      | `diffhtml/lib/*`
+
+#### Supporting legacy browsers
 
 diffHTML is authored using many modern browser features, such as
 [Set](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set),
@@ -67,16 +98,9 @@ polyfill loaded first:
 
 https://babeljs.io/docs/usage/polyfill/
 
-##### Module format locations
-
-The codebase is authored with JavaScript (ES6 enhancements) and transpiled into
-ES5 (CJS) into the `dist/cjs` folder on every NPM publish. If you want
-to reference the ES5 files, point your entry to `diffhtml/dist/cjs`. If you
-want ES6, point to `diffhtml/lib`. If you want the UMD build you can simply
-point to `diffhtml` as it is the default or reference `dist/diffhtml.js` in
-your browser.
+## Quick start
 
-### Quick start
+[Back to quick jump](#quick-jump)
 
 Before diving into all the API details, the easiest way to understand using
 diffHTML is to replace the usage of `innerHTML`.
@@ -111,7 +135,7 @@ function render(string) {
 }
 ```
 
-### API
+## API
 
 The exposed API provides the following methods:
 
@@ -129,14 +153,14 @@ The follow error types are exposed so you can test exceptions:
 - TransitionStateError - Happens when errors occur during transitions.
 - DOMException - Happens whenever a DOM manipulation fails.
 
-##### Options
+#### Options
 
 This is an optional argument that can be passed to any diff method. The `inner`
 property can only be used with the element method.
 
 - `inner` - Boolean that determines if `innerHTML` is used.
 
-##### Diff an element with markup
+### Diff an element with markup
 
 This method will take in a string of markup that matches the element root you
 are diffing against.  This allows you to change attributes and text on the
@@ -149,7 +173,7 @@ You cannot override the `inner` options property here.
 diff.outerHTML(document.body, '<body class="test"><h1>Hello world!</h1></body>');
 ```
 
-##### Diff an element's children with markup
+### Diff an element's children with markup
 
 This method also takes in a string of markup, but unlike `outerHTML` this is
 children-only markup that will be nested inside the element passed.
@@ -161,7 +185,7 @@ You cannot override the `inner` options property here.
 diff.innerHTML(document.body, '<h1>Hello world!</h1>');
 ```
 
-##### Diff an element to another element
+### Diff an element to another element
 
 Unlike the previous two methods, this will take in two elements and diff them
 together.
@@ -188,7 +212,7 @@ h1.innerHTML = 'Hello world!';
 diff.element(document.body, h1, { inner: true });
 ```
 
-##### Release element
+### Release element
 
 Use this method if you need to clean up memory allocations and anything else
 internal to diffHTML associated with your element. This is very useful for unit
@@ -203,7 +227,7 @@ diff.element(document.body, h1, { inner: true });
 diff.release(document.body);
 ```
 
-##### Add a transition state callback
+### Add a transition state callback
 
 Adds a global transition listener.  With many elements this could be an
 expensive operation, so try to limit the amount of listeners added if you're
@@ -245,7 +269,7 @@ Format is: `name[callbackArgs]`
 - `textChanged[element, oldValue, newValue]`
   For when text has changed in either TextNodes or SVG text elements.
 
-##### A note about detached/replaced element accuracy
+### A note about detached/replaced element accuracy
 
 When rendering Nodes that contain lists of identical elements, you may not
 receive the elements you expect in the detached and replaced transition state
@@ -307,7 +331,7 @@ Now the transformative operations are:
 
 1. Remove the second element
 
-##### Remove a transition state callback
+### Remove a transition state callback
 
 Removes a global transition listener.
 
@@ -326,7 +350,7 @@ diff.removeTransitionState('attached');
 diff.removeTransitionState('attached', callbackReference);
 ```
 
-#### HTML
+### HTML
 
 You can use the `diff.html` tagged template helper to build up dynamic trees in
 a way that looks very similar to JSX.
@@ -385,7 +409,7 @@ diff.outerHtml(fixture, html`
 `);
 ```
 
-#### [Prollyfill](https://twitter.com/slexaxton/status/257543702124306432)
+### [Prollyfill](https://twitter.com/slexaxton/status/257543702124306432)
 
 *Click above to learn what prollyfill "means".*
 
@@ -410,15 +434,15 @@ Scans for changes in attributes and text on the parent, and all child nodes.
 document.querySelector('main').diffOuterHTML = '<new markup to diff/>';
 ```
 
-##### `Element.prototype.diffInnerHTML`
+### `Element.prototype.diffInnerHTML`
 
 Only scans for changes in child nodes.
 
 ``` javascript
 document.querySelector('main').diffInnerHTML = '<new child markup to diff/>';
 ```
 
-##### `Element.prototype.diffElement`
+### `Element.prototype.diffElement`
 
 Compares the two elements for changes like `outerHTML`, if you pass `{ inner:
 true }` as the second argument it will act like `innerHTML`.
@@ -430,7 +454,7 @@ newElement.innerHTML = '<div></div>';
 document.querySelector('main').diffElement(newElement);
 ```
 
-##### `Element.prototype.diffRelease`
+### `Element.prototype.diffRelease`
 
 Cleans up after diffHTML and removes the associated worker.
 
@@ -441,4 +465,34 @@ newElement.innerHTML = '<div></div>';
 document.querySelector('main').diffRelease(newElement);
 ```
 
+<<<<<<< Updated upstream
+=======
+### Middleware
+
+A controlled way of exposing the internals of diffHTML to external tooling and
+has a very simple interface for creating and consuming.
+
+Two interesting projects that illustrate use cases for middleware:
+
+- [Logger](https://github.com/tbranyen/diffhtml-logger)
+- [Components](https://github.com/tbranyen/diffhtml-components)
+
+### Consuming
+
+Very simple, use the `use` method.
+
+``` javascript
+import logger from 'diffhtml-logger';
+import { use } from 'diffhtml';
+
+use(logger);
+```
+
+### Create
+
+``` javascript
+const logMiddleware = (
+```
+
+>>>>>>> Stashed changes
 [More information and a demo are available on http://www.diffhtml.org/](http://www.diffhtml.org/)