docs(browser-support): edits (#2299)

Author: wardbell

public/docs/_examples/quickstart/ts/index.html

@@ -9,10 +9,10 @@
 
     <!-- 1. Load libraries -->
     <!-- #docregion libraries -->
-    <!-- #docregion ie-polyfills -->
+    <!-- #docregion polyfills -->
      <!-- Polyfill(s) for older browsers -->
     <script src="node_modules/core-js/client/shim.min.js"></script>
-    <!-- #enddocregion ie-polyfills -->
+    <!-- #enddocregion polyfills -->
 
     <script src="node_modules/zone.js/dist/zone.js"></script>
     <script src="node_modules/reflect-metadata/Reflect.js"></script>

public/docs/dart/latest/guide/_data.json

@@ -87,6 +87,11 @@
     "intro": "Attribute directives attach behavior to elements."
   },
 
+  "browser-support": {
+    "title": "Browser support",
+    "intro": "Browser support and polyfills guide."
+  },
+
   "component-styles": {
     "title": "Component Styles",
     "intro": "Learn how to apply CSS styles to components."

public/docs/js/latest/guide/_data.json

@@ -74,6 +74,11 @@
     "intro": "Attribute directives attach behavior to elements."
   },
 
+  "browser-support": {
+    "title": "Browser support",
+    "intro": "Browser support and polyfills guide."
+  },
+
   "component-styles": {
     "title": "Component Styles",
     "intro": "Learn how to apply CSS styles to components."

public/docs/ts/latest/guide/browser-support.jade

@@ -1,3 +1,7 @@
+block includes
+  include ../_util-fns
+  - var _at_angular = '@angular'
+
 :marked
   # Browser support #  
   Angular supports most recent browsers. This includes the following specific versions:
@@ -50,88 +54,105 @@ table
     td
 
 
+.l-sub-section
+  :marked
+    Angular's continuous integration process runs unit tests of the framework on all of these browsers for every pull request, 
+    using <a href="https://saucelabs.com/" target="_blank">SauceLabs</a> and 
+    <a href="https://www.browserstack.com" target="_blank">Browserstack</a>.
+
 :marked
-  To ensure this compatibility, the unit tests of the framework are run on all of them for every pull request. 
-  This is done as part of the continuous integration setup of the project, using [SauceLabs](https://saucelabs.com/) and [Browserstack](https://www.browserstack.com).
-  
   # Polyfills #
   Angular is built on the latest standards of the web platform.
-  Targeting such a wide range of browsers can be challenging as they may not support all the features of modern browsers.
+  Targeting such a wide range of browsers is challenging because they do not support all features of modern browsers.
 
-  
-  To fill the gaps, the best solution is to use polyfills which "upgrade" old browsers by adding missing features.
-  For each browser, some polyfill may be required to run any application, and some may be needed only when some features are used.
+  You compensate by loading polyfill scripts ("polyfills") on the host web page (`index.html`)
+  that implement missing features in JavaScript.
++makeExample('quickstart/ts/index.html', 'polyfills')(format='.')
+:marked
+  A particular browser may require at least one polyfill to run _any_ Angular application. 
+  You may need additional polyfills for specific features.
 
-.alert.is-helpful 
-  span As a developer, depending on the browsers you target and on the features you use, you'll need to load a set of polyfills.
-  span  The tables below will help you making the right choices.
+  The tables below will help you determine which polyfills to load, depending on the browsers you target and the features you use.
 
-.alert.is-important 
-  span The polyfills documented here are the ones which were identified to run full Angular application.
-  span  Others may be needed if you decide to use extra features which are not supported everywhere.
-  span  On top of that, they will not magically transform an old and slow browser into a modern and fast one.
+.alert.is-important
+  :marked
+    The suggested polyfills are the ones we know will run full Angular applications.
+    You may need additional polyfills to support features not covered by this list.
+    Note that polyfills cannot magically transform an old, slow browser into a modern, fast one.
 
 :marked
   ## Mandatory polyfills ##
-  For each supported browser, these are the polyfills which are required to run an application:
+  These are the polyfills required to run an Angular application on each supported browser:
 
 table
-  tr
+  tr(style="vertical-align: top") 
     th Browsers (desktop & mobile)
     th Polyfills required
-  tr
+  tr(style="vertical-align: top") 
     td Chrome, Firefox, Edge, Safari 9+
     td None
-  tr
+  tr(style="vertical-align: top") 
     td Safari 7 & 8, IE10 & 11, Android 4.1+
-    td ES6
-  tr
+    td
+      :marked
+        [ES6](#core-es6)
+  tr(style="vertical-align: top") 
     td IE9
-    td ES6<br>classList
-    
-    
+    td
+      :marked
+        [ES6<br>classList](#classlist)
+
 :marked
   ## Optional browser features to polyfill ##
-  In addition to the mandatory polyfills, some features of Angular may require some extra polyfills.
+  Some features of Angular may require additional polyfills.
 
-  For example, the animations use the standard web animation API, which is only available in Chrome and Firefox today.
-  In order to use this feature in other browsers, the correct polyfill is needed.
+  For example, the animations library relies on the standard web animation API, which is only available in Chrome and Firefox today.
+  You'll need a polyfill to use animations in other browsers.
 
   Here are the features which may require additional polyfills:
 
 table
-  tr
+  tr(style="vertical-align: top") 
     th Feature
     th Polyfill
-    th Browsers (desktop & mobile)
-  tr
+    th(style="width: 50%")  Browsers (desktop & mobile)
+
+  tr(style="vertical-align: top") 
     td
       a(href="./animations.html") Animations
-    td Web Animations
+    td
+      :marked
+        [Web Animations](#web-animations)
     td All but Chrome and Firefox<br>Not supported in IE9
-  tr
-    td 
-      a(href="../api/common/index/DatePipe-class.html") Date
+  tr(style="vertical-align: top") 
+    td
+      a(href="../api/common/index/DatePipe-class.html" target="_blank") Date
       span ,  
-      a(href="../api/common/index/CurrencyPipe-class.html") currency
+      a(href="../api/common/index/CurrencyPipe-class.html" target="_blank") currency
       span , 
-      a(href="../api/common/index/DecimalPipe-class.html") decimal
+      a(href="../api/common/index/DecimalPipe-class.html" target="_blank") decimal
       span  and 
-      a(href="../api/common/index/PercentPipe-class.html") percent
+      a(href="../api/common/index/PercentPipe-class.html" target="_blank") percent
       span  pipes
-    td Intl API
+    td
+      :marked
+        [Intl API](#intl)
     td All but Chrome, Firefox, Edge and IE11
-  tr
+  tr(style="vertical-align: top") 
     td 
-      a(href="../api/common/index/NgClass-directive.html") NgClass
+      a(href="../api/common/index/NgClass-directive.html" target="_blank") NgClass
       span  on SVG elements
-    td classList
+    td 
+      :marked
+        [classList](#classlist)
     td IE10, IE11
-  tr
+  tr(style="vertical-align: top") 
     td
       a(href="./server-communication.html") Http
       span  when sending and receiving binary data
-    td Typed Arrays<br>Blob<br>FormData
+    td 
+      :marked
+        [Typed&nbsp;Array](#typedarray) <br>[Blob](#blob)<br>[FormData](#formdata)
     td IE 9
 
 :marked
@@ -141,51 +162,43 @@ table
 table
   tr
     th Polyfill
-    th Library
     th Licence
     th Size*
   tr
-    td ES6
-    td 
-      a(href="https://github.com/zloirock/core-js") https://github.com/zloirock/core-js
+    td
+      a#core-es6(href="https://github.com/zloirock/core-js" target="_blank") ES6
     td MIT
     td 27.4KB
   tr
-    td classList
     td
-      a(href="https://github.com/eligrey/classList.js") https://github.com/eligrey/classList.js
+     a#classlist(href="https://github.com/eligrey/classList.js" target="_blank") classList
     td Public domain
     td 1KB
   tr
-    td Intl
     td
-      a(href="https://github.com/andyearnshaw/Intl.js ") https://github.com/andyearnshaw/Intl.js 
+     a#intl(href="https://github.com/andyearnshaw/Intl.js" target="_blank") Intl
     td MIT / Unicode licence
     td 13.5KB
   tr
-    td Web Animations
-    td
-      a(href="https://github.com/web-animations/web-animations-js") https://github.com/web-animations/web-animations-js
+    td 
+      a#web-animations(href="https://github.com/web-animations/web-animations-js" target="_blank") Web Animations
     td Apache
     td 14.8KB
   tr
-    td Typed Arrays
     td
-      a(href="https://github.com/inexorabletash/polyfill/blob/master/typedarray.js") https://github.com/inexorabletash/polyfill/blob/master/typedarray.js
+      a#typedarray(href="https://github.com/inexorabletash/polyfill/blob/master/typedarray.js" target="_blank") Typed Array
     td MIT
     td 4KB
   tr
-    td Blob
-    td
-      a(href="https://github.com/eligrey/Blob.js") https://github.com/eligrey/Blob.js
+    td 
+      a#blob(href="https://github.com/eligrey/Blob.js" target="_blank") Blob
     td MIT
     td 1.3KB
   tr
-    td FormData
-    td
-      a(href="https://github.com/francois2metz/html5-formdata") https://github.com/francois2metz/html5-formdata
+    td 
+      a#formdata(href="https://github.com/francois2metz/html5-formdata" target="_blank") FormData
     td MIT
     td 0.4KB
 
 :marked
-  *Figures are for minified and gzipped code, computed with [http://closure-compiler.appspot.com/home](http://closure-compiler.appspot.com/home)
+  * Figures are for minified and gzipped code, computed with the <a href="http://closure-compiler.appspot.com/home" target="_blank">closure compiler</a>