README: Restructure everything, overhaul details, add logo

README.md

@@ -1,34 +1,15 @@
-## Learn the tech
+# Pointer Events Polyfill - making pointer events usable today
 
-### Why Pointer Events?
+![PEP logo](pep-logo-shield.png)
 
-Mouse Events and Touch Events are fundamentally different beasts in browsers today, and that makes it hard to write cross-platform apps.
-
-For example, a simple finger paint app needs plenty of work to behave correctly with mouse and touch:
-
-Current platforms that implement touch events also provide mouse events for backward compatibility; however, only a subset of Mouse Events are fired and the semantics are changed.
-
-- Mouse Events are only fired after the touch sequence ends.
-- Mouse Events are not fired on elements without a `click` event handler. One must be attached by default, or directly on the element with `onclick`.
-- `click` events are not fired if the content of the page changes in a `mousemove` or `mouseover` event.
-- `click` events are fired 300ms after the touch sequence ends.
-- More information: [Apple Developer Documentation](http://developer.apple.com/library/safari/#documentation/appleapplications/reference/safariwebcontent/HandlingEvents/HandlingEvents.html).
+PEP polyfills pointer events in all browsers that haven't yet implemented them, providing a unified, responsive input model for all devices and input types. You can [read more about Pointer Events below](#why-pointer-events).
 
-Additionally, Touch Events are sent only to the element that received the `touchstart`. This is fundamentally different than Mouse Events, which fire on the element that is under the mouse. To make them behave similarly, Touch Events need to be retargeted with `document.elementFromPoint`.
-
-These incompatibilities lead to applications having to listen to 2 sets of events, mouse on desktop and touch for mobile.
+## Getting Started
 
-**This forked interaction experience is cumbersome and hard to maintain.**
-
-Instead, there should exist a set of events that are normalized such that they behave exactly the same, no matter the source: touch, mouse, stylus, skull implant, etc. To do this right, this normalized event system needs to be available for all the web platform to use.
-
-*Thus, Pointer Events!*
-
-### Basic Usage
-
-By default, no Pointer Events are sent from an element. This maximizes possibility that a browser can deliver smooth scrolling and jank-free gestures. If you want to receive events, you must set the `touch-action` property of that element.
+1. Place the PEP script in the document head
+  - `<script src="https://code.jquery.com/pep/0.4.0/pep.js"></script>`
 
-1. Set up some elements to create events with the [`touch-action` attribute](http://www.w3.org/TR/pointerevents/#the-touch-action-css-property).
+1. By default, no Pointer Events are sent from an element. This maximizes the possibility that a browser can deliver smooth scrolling and jank-free gestures. If you want to receive events, you must set the `touch-action` property of that element. Set up some elements to create events with the [`touch-action` attribute](http://www.w3.org/TR/pointerevents/#the-touch-action-css-property).
 
 1. Listen for the desired events
   - `pointermove`: a pointer moves, similar to touchmove or mousemove.
@@ -42,9 +23,10 @@ By default, no Pointer Events are sent from an element. This maximizes possibili
 
 1. As elements come and go, or have their `touch-action` attribute changed, they will send the proper set of Pointer Events.
 
-See also the [examples in the W3C Pointer Events specification](http://www.w3.org/TR/pointerevents/#examples).
 
-#### Using PEP with jQuery
+See also the [examples in the W3C Pointer Events specification](http://www.w3.org/TR/pointerevents/#examples) and our own [samples for using PEP](http://jquery.github.io/PEP/).
+
+### Using PEP with jQuery
 
 You can use pointer events with jQuery and PEP:
 ```html
@@ -61,18 +43,30 @@ Check out [this jsbin demo](http://jsbin.com/bojumofowa/1/edit?html,css,js,outpu
 
 jQuery doesn't copy all properties from the original event object to the event object provided in the event handler. You can find [a list of copied and normalized properties on the jQuery API docs](http://api.jquery.com/category/events/event-object/). To access any other original properties, use `event.originalEvent`.
 
-## Polyfill Details
 
-### Getting Started
+## Why Pointer Events?
 
-1. Place the PEP script in the document head
-  - `<script src="https://code.jquery.com/pep/0.3.0/pep.js"></script>`
-1. Set up your event listeners
-1. You're done!
+Mouse Events and Touch Events are fundamentally different beasts in browsers today, and that makes it hard to write cross-platform apps.
 
-### Samples
+For example, a simple finger paint app needs plenty of work to behave correctly with mouse and touch:
+
+Current platforms that implement touch events also provide mouse events for backward compatibility; however, only a subset of Mouse Events are fired and the semantics are changed.
 
-Check out some of the samples at http://jquery.github.io/PEP/.
+- Mouse Events are only fired after the touch sequence ends.
+- Mouse Events are not fired on elements without a `click` event handler. One must be attached by default, or directly on the element with `onclick`.
+- `click` events are not fired if the content of the page changes in a `mousemove` or `mouseover` event.
+- `click` events are fired 300ms after the touch sequence ends.
+- More information: [Apple Developer Documentation](http://developer.apple.com/library/safari/#documentation/appleapplications/reference/safariwebcontent/HandlingEvents/HandlingEvents.html).
+
+Additionally, Touch Events are sent only to the element that received the `touchstart`. This is fundamentally different than Mouse Events, which fire on the element that is under the mouse. To make them behave similarly, Touch Events need to be retargeted with `document.elementFromPoint`.
+
+These incompatibilities lead to applications having to listen to 2 sets of events, mouse on desktop and touch for mobile.
+
+**This forked interaction experience is cumbersome and hard to maintain.**
+
+Instead, there should exist a set of events that are normalized such that they behave exactly the same, no matter the source: touch, mouse, stylus, skull implant, etc. To do this right, this normalized event system needs to be available for all the web platform to use.
+
+*Thus, Pointer Events!*
 
 ## Polyfill Limitations
 
@@ -87,4 +81,4 @@ Touches will not generate events unless inside of an area that has a valid `touc
 
 ### Browser Compatibility
 
-PEP should work on IE 10+ and the latest versions of Chrome, Safari, Firefox, and Opera.
+PEP should work on IE 10+ and the latest versions of Chrome, Safari, Firefox, and Opera. In any [browser implementing Pointer Events natively](http://caniuse.com/#feat=pointer) (detected by checking for `window.PointerEvent`), PEP won't do anything.