diff --git a/README.md b/README.md
index 326d778..2bbf7b0 100644
--- a/README.md
+++ b/README.md
@@ -1,29 +1,26 @@
# picturePolyfill
-A Responsive Images approach that you can use today that mimics the [proposed picture element](http://www.w3.org/TR/2013/WD-html-picture-element-20130226/) using a single `span` (for safety sake) with a JSON notation of `source`, with `media` and `srcset` attributes.
+A Responsive Images approach that you can use today that uses the **real [`picture` element](http://www.w3.org/TR/2013/WD-html-picture-element-20130226/)** along with children `source` elements with `media` and `srcset` attributes.
* Author: Andrea Verlicchi (c) 2014
* License: MIT/GPLv2
### **[DEMO](http://verlok.github.io/picturePolyfill/)**
-**Note:** picturePolyfill works best in browsers that support CSS3 media queries. The demo page references (externally) the [matchMedia polyfill](https://github.com/paulirish/matchMedia.js/) which makes matchMedia work in `media-query`-supporting browsers that don't support `matchMedia`. The `matchMedia` polyfill is not required for `picturePolyfill` to work, but it's required to support the `media` property specified in the data-picture attribute. In non-media query-supporting browsers, the `matchMedia` polyfill will allow for querying native media types, such as `screen`, `print`, etc.
-
## picturePolyfill advantages
PicturePolyfill is fast and easy to use because:
-* **loading performance**: it serves only one image, no other double HTTP requests are made
-* **computing performance**: it doesn't execute while a smooth (animated or manually dragged) browser resize is in progress, avoiding useless DOM parsing and HTTP requests to mid-breakpoints images that the user might not need
-* **support to HD (Retina) displays** easily made (no need to prefix HD media queries with the `-webkit-` prefix)
-* **small html markup** thanks to the possibility to specify multiple values in the `srcset` property
+* **markup & go**: it uses the picture tag, easy to markup, and futureproof
+* **loading performance**: it serves only one image to your website users, no double HTTP requests are made
+* **computing performance**: it's designed and coded keeping performance in mind. For example, it doesn't execute while a smooth (animated or manually dragged) browser resize is in progress (avoiding useless DOM parsing and useless HTTP requests to mid-breakpoints images that the user might not need) and it caches the `source` elements data
+* **support to HD (Retina) displays** easily made via the `srcset` attribute of `source` tags
### Differences with picturefill
picturePolyfill is better than picturefill because:
-* it gives you the **`srcset` attribute**, which gives you easier support for retina displays. picturefill requires more lines of markup code (and the `-webkit-` prefix) to support different media queries.
-* it makes you **choose a default image** that you want to show on Internet Explorer 8. picturefill always serves the smaller one
-* it's **faster**, as it relies on a `JSON` object, that is much faster to be parsed then many span elements required by picturefill (see "performance" section on this readme)
+* it uses the **real `picture` markup**
+* it gives you the ability to **choose a default image** that you want to show on Internet Explorer desktop, without the need to add any comment
## Markup pattern and explanation
@@ -32,19 +29,15 @@ picturePolyfill is better than picturefill because:
To support HD (Retina) images, mark up your responsive images like this.
```html
-
+
+
+
+
+
-
+
```
### Without HD (Retina) support
@@ -52,53 +45,34 @@ To support HD (Retina) images, mark up your responsive images like this.
If you don't need to support HD (Retina) images, you can mark up your responsive images like this.
```html
-
+
+
+
+
+
-
+
```
-### The `data-picture` attribute array
-
-The `data-picture` attribute accepts an array. In each element, it accepts:
-* `media`: any and all CSS3 media queries—such as `min-width` or `max-width`
-* `srcset`: the image URL (string) at the corresponding `media`, or an array of image URLs. To support only standard displays, just pass in a string. To support HD (Retina) displays, pass an array of values: the first value for standard displays, the second value for HD displays (Retina; double density), and more for triple and quad density.
-* `standard`: a boolean value, `true` if you want this to be the image picked by browsers without media query support (like IE 8 or below). If srcset is an array, these browser will always load the first `srcset` element.
-
-**Note:** As the `data-picture` attribute array is read from left to right, the array elements with `media` property set to `min-width` must be placed in increasing `min-width` order, e.g. 321px, 481px, 769px, etc.
-
-### Notes on the markup above...
-
-* The `data-picture` attribute must contain a JSON array which can contain any number of elements. The above example may contain more than the average situation may call for. I recommend to generate this array using a helper on a server side language (like PHP or similar).
-* The `span[data-picture]` element's `data-alt` attribute is used as alternate text for the `img` element that picturePolyfill generates upon a successful.
-* It's generally a good idea to leave one element of the `data-picture` array with no `media` qualifier, so it'll apply everywhere - typically a mobile-optimized image is ideal here.
-* Each element of the `data-picture` array can have an optional `media` attribute to make it apply in specific media settings. Both media types and queries can be used, like a native `media` attribute, but support for media _queries_ depends on the browser (unsupporting browsers fail silently).
-* The `noscript` element wraps the fallback image for non-JavaScript environments and search engines, and including this wrapper prevents browsers from fetching the fallback image during page load (causing unnecessary overhead).
+### Notes about the markup
-### About the real `picture` element
+`picture` tag:
+* `data-default-src` attribute: the image URL that you want to load in IE Desktop < 10.
+* `data-alt` attribute: the alternative text that will be set in the `img` tag
-Some developers are [wondering](http://www.linkedin.com/groupItem?view=&gid=2071438&type=member&item=5846510553693986816&commentID=5848302870645993472): **will I have to re-code my HTML** when the real `picture` element will be standard and supported?
-
-Please note that there's a version of picturePolyfill, under the [usingPictureMarkup](https://github.com/verlok/picturePolyfill/tree/master/usingPictureMarkup) folder, which makes it possible to **use the real `picture` + `source` tags today**, but this version is supporting Internet Explorer 10 and above (no support for versions 8 and 9).
-
-If you need to support IE 8 and 9 the answer is yes, recoding will be necessary when the real `picture` tag will be a standard.
-
-What I suggest is to **generate the responsive images markup** using some function written in a **server side language** (like PHP or similar), with a simple configuration to **switch** to make it generate the `span[data-picture]` element today (required by picturePolyfill) or the real `picture` element when fully supported.
+`source` tags:
+* `media` attribute: any media query, but it's adviced to use a `min-width` media query to follow the "mobile first" approach.
+* `srcset` attribute: the image URL or comma separated URLs at the corresponding `media`
+`noscript` tag:
+* This should wrap the fallback image for non-JavaScript environments and search engines. You *could* avoid wrapping the `img` tag in `noscript`, but this will make browsers to fetch the fallback image during page load, causing unnecessary overhead.
### How the `img` is appended and updated
Upon finding a matching media in the `data-picture` array, picturePolyfill will generate an `img` element and inside that span.
-The `img`'s `src` attribute is updated at browser resize, after a small delay (100ms) to prevent the script to be executed too many times during smooth (animated or manually dragged) browser resize.
+The `img`'s `src` attribute is then updated at browser resize (see _computing performance_ section above to read about performance at browser resize)
## Server-side scaling/cropping tool
@@ -109,79 +83,90 @@ It's then a good practice to have a server-side picture scaling service (like [p
If you want to use an image server, you can code your HTML like the following:
```html
-
-
-
-
-
+
+
+
+
+
+
+
```
-Use an array in the srcset property and double size images to support HD/retina displays, as you can see in the "With HD (Retina) images support" section of this readme.
+Note that you should serve double resolution images (double width and double height) for HD/retina displays, as you can see in the "With HD (Retina) images support" section of this readme.
[Take a look at the demo](http://verlok.github.io/picturePolyfill/).
-## Usage
+## Installation
+
+### Manual
+
+* Download picturePolyfill from GitHub
+* Include the minified file in your project script directory
+
+### Using bower
+
+You can install the latest version of picturePolyfill using [bower](http://www.bower.io)
+
+```Shell
+bower install picturePolyfill
+```
+
+## Inclusion
+
+To use picturePolyfill, just include the script tag at the end of your html file, in the `head` section of your `HTML` pages, OR just before the closure of the `body` tag.
+
+Including the `defer` attribute in the `script` tag will prevent the script download to block page rendering while in progress.
-To use picturePolyfill, just insert the script tag at the end of your html file, just right the closure of the `body` tag.
-If picturePolyfill is put in the head of the document of deferred until after load is fired, images will not load unless the browser window is resized.
+### In the `head` section
```html
Your HEAD content
+
- Your BODY + your responsive images markup, as described
-
+ Your BODY content
```
-### Later calls
-
-picturePolyfill is intentionally exposed to the global space, so you can call it later, as you need it.
-
-* **AJAX calls**: after your new DOM has been injected on the page, just call `window.picturePolyfill()`
-* **document ready**: if you insert the `
+
-
-
+
+