docs(router): copyedits (#3025)

public/docs/_examples/router/ts/app/app.component.2.ts

@@ -1,6 +1,4 @@
 /* Second Heroes version */
-// #docplaster
-
 // #docregion
 import { Component } from '@angular/core';
 

public/docs/ts/latest/guide/router.jade

@@ -19,7 +19,7 @@ include ../../../_includes/_see-addr-bar
   * Click the browser's back and forward buttons and the browser navigates
   backward and forward through the history of pages you've seen.
 
-  The Angular *`Router` ("the router") borrows from this model.
+  The Angular `Router` ("the router") borrows from this model.
   It can interpret a browser URL as an instruction to navigate to a client-generated view.
   It can pass optional parameters along to the supporting view component that help it decide what specific content to present.
   You can bind the router to links on a page and it will navigate to
@@ -32,35 +32,35 @@ include ../../../_includes/_see-addr-bar
 
   * Setting the [base href](#base-href)
   * Importing from the [router library](#import)
-  * [configuring the router](#route-config)
+  * [Configuring the router](#route-config)
-  * handling unmatched URLs with a [wildcard route](#wildcard-route)
+  * Handling unmatched URLs with a [wildcard route](#wildcard-route)
-  * the [link parameters array](#link-parameters-array) that propels router navigation
+  * The [link parameters array](#link-parameters-array) that propels router navigation
-  * setting the [default route](#default-route) where the application navigates at launch
+  * Setting the [default route](#default-route) where the application navigates at launch
-  * [redirecting](#redirect) from one route to another
+  * [Redirecting](#redirect) from one route to another
-  * navigating when the user clicks a data-bound [RouterLink](#router-link)
+  * Navigating when the user clicks a data-bound [RouterLink](#router-link)
-  * navigating under [program control](#navigate)
+  * Navigating under [program control](#navigate)
-  * retrieving information from the [route](#activated-route)
+  * Retrieving information from the [route](#activated-route)
-  * [animating](#route-animation) transitions for route components
+  * [Animating](#route-animation) transitions for route components
-  * navigating [relative](#relative-navigation) to the current URL
+  * Navigating [relative](#relative-navigation) to the current URL
-  * toggling css classes for the [active router link](#router-link-active)
+  * Toggling css classes for the [active router link](#router-link-active)
-  * embedding critical information in the URL with [route parameters](#route-parameters)
+  * Embedding critical information in the URL with [route parameters](#route-parameters)
-  * providing non-critical information in [optional route parameters](#optional-route-parameters)
+  * Providing non-critical information in [optional route parameters](#optional-route-parameters)
-  * refactoring routing into a [routing module](#routing-module)
+  * Refactoring routing into a [routing module](#routing-module)
-  * add [child routes](#child-routing-component) under a feature section
+  * Add [child routes](#child-routing-component) under a feature section
-  * [grouping child routes](#component-less-route) without a component
+  * [Grouping child routes](#component-less-route) without a component
-  * displaying [multiple routes](#named-outlets) in separate outlets
+  * Displaying [multiple routes](#named-outlets) in separate outlets
-  * confirming or canceling navigation with [guards](#guards)
+  * Confirming or canceling navigation with [guards](#guards)
     * [CanActivate](#can-activate-guard) to prevent navigation to a route
     * [CanActivateChild](#can-activate-child-guard) to prevent navigation to a child route
     * [CanDeactivate](#can-deactivate-guard) to prevent navigation away from the current route
     * [Resolve](#resolve-guard) to pre-fetch data before activating a route
     * [CanLoad](#can-load-guard) to prevent asynchronous routing
-  * providing optional information across routes with [query parameters](#query-parameters)
+  * Providing optional information across routes with [query parameters](#query-parameters)
-  * jumping to anchor elements using a [fragment](#fragment)
+  * Jumping to anchor elements using a [fragment](#fragment)
-  * loading feature areas [asynchronously](#asynchronous-routing)
+  * Loading feature areas [asynchronously](#asynchronous-routing)
-  * preloading feature areas [during navigation](#preloading)
+  * Preloading feature areas [during navigation](#preloading)
-  * using a [custom strategy](#custom-preloading) to only preload certain features
+  * Using a [custom strategy](#custom-preloading) to only preload certain features
-  * choosing the "HTML5" or "hash" [URL style](#browser-url-styles)
+  * Choosing the "HTML5" or "hash" [URL style](#browser-url-styles)
 
 .l-main-section
 :marked
@@ -69,10 +69,11 @@ include ../../../_includes/_see-addr-bar
   This guide proceeds in phases, marked by milestones, starting from a simple two-pager
   and building toward a modular, multi-view design with child routes.
 
-  An introduction to a few core Router concepts will help orient you to the details that follow.
+  An introduction to a few core router concepts will help orient you to the details that follow.
 
 :marked
   ### *<base href>*
+
   Most routing applications should add a `<base>` element to the `index.html` as the first child in the  `<head>` tag
   to tell the router how to compose navigation URLs.
 
@@ -83,6 +84,7 @@ include ../../../_includes/_see-addr-bar
 
 :marked
   ### Router imports
+
   The Angular Router is an optional service that presents a particular component view for a given URL.
   It is not part of the Angular core. It is in its own library package, `@angular/router`.
   Import what you need from it as you would from any other Angular package.
@@ -94,6 +96,7 @@ include ../../../_includes/_see-addr-bar
     You'll learn about more options in the [details below](#browser-url-styles).
 :marked
   ### Configuration
+
   A routed Angular application has one, singleton instance of the *`Router`* service. 
   When the browser's URL changes, that router looks for a corresponding `Route`
   from which it can determine the component to display.
@@ -140,14 +143,18 @@ a#example-config
 
 :marked
   ### Router Outlet
+
   Given this configuration, when the browser URL for this application becomes `/heroes`,
   the router matches that URL to the route path `/heroes` and displays the `HeroListComponent`
   _after_ a `RouterOutlet` that you've placed in the host view's HTML.
+
 code-example(language="html").
   &lt;router-outlet>&lt;/router-outlet>
   &lt;!-- Routed views go here -->
+
 :marked
   ### Router Links
+
   Now you have routes configured and a place to render them, but
   how do you navigate? The URL could arrive directly from the browser address bar.
   But most of the time you navigate as a result of some user action such as the click of
@@ -157,7 +164,7 @@ code-example(language="html").
 
 +makeExcerpt('app/app.component.1.ts', 'template', '')
 :marked
-  The `RouterLink` directive on the anchor tags gives the router control over those elements. 
+  The `RouterLink` directives on the anchor tags give the router control over those elements. 
   The navigation paths are fixed, so you can assign a string to the `routerLink` (a "one-time" binding).
 
   Had the navigation path been more dynamic, you could have bound to a template expression that
@@ -170,6 +177,7 @@ code-example(language="html").
 
 :marked
   ### Router State
+
   After the end of each successful navigation lifecycle, the router builds a tree of `ActivatedRoute` objects
   that make up the current state of the router. You can access the current `RouterState` from anywhere in the
   application using the `Router` service and the `routerState` property.
@@ -218,7 +226,7 @@ table
     td.
       The directive for binding a clickable HTML element to
       a route. Clicking an anchor tag with a <code>routerLink</code> directive
-      that is bound to a <i>string</i> or a <i>Link Parameters Array</i> triggers a navigation.
+      that is bound to a <i>string</i> or a <i>link parameters array</i> triggers a navigation.
   tr
     td <code>RouterLinkActive</code>
     td.
@@ -235,17 +243,16 @@ table
       The current state of the router including a tree of the currently activated
       routes together with convenience methods for traversing the route tree.
   tr
-    td <code><i>Link Parameters Array</i></code>
+    td <b><i>Link Parameters Array</i></b>
     td.
       An array that the router interprets as a routing instruction.
       You can bind that array to a <code>RouterLink</code> or pass the array as an argument to
       the <code>Router.navigate</code> method.
   tr
-    td <code><i>Routing Component</i></code>
+    td <b><i>Routing Component</i></b>
     td.
       An Angular component with a <code>RouterOutlet</code> that displays views based on router navigations.
 
-a#getting-started
 .l-main-section
 :marked
   ## The Sample Application
@@ -302,8 +309,10 @@ figure.image-display
   Angular app navigation updates the browser history as normal web navigation does.
 
   Now click the *Crisis Center* link for a list of ongoing crises.
+
 figure.image-display
   img(src='/resources/images/devguide/router/crisis-center-list.png' alt="Crisis Center List" width="250")
+
 :marked
   Select a crisis and the application takes you to a crisis editing screen.
   The _Crisis Detail_ appears in a child view on the same page, beneath the list. 
@@ -313,6 +322,7 @@ figure.image-display
   
 figure.image-display
   img(src='/resources/images/devguide/router/crisis-center-detail.png' alt="Crisis Center Detail" width="250")
+
 :marked
   Unlike *Hero Detail*, which updates as you type, 
   *Crisis Detail* changes are temporary until you either save or discard them by pressing the "Save" or "Cancel" buttons.
@@ -322,6 +332,7 @@ figure.image-display
   Click the browser back button or the "Heroes" link instead.
 
   Up pops a dialog box.
+
 figure.image-display
   img(src='/resources/images/devguide/router/confirm-dialog.png' alt="Confirm Dialog" width="250")
 
@@ -336,18 +347,19 @@ figure.image-display
   
   Proceed to the first application milestone.
 
-.l-main-section
+.l-main-section#getting-started
 :marked
   ## Milestone #1: Getting Started with the Router
 
   Begin with a simple version of the app that navigates between two empty views.
 figure.image-display
-  img(src='/resources/images/devguide/router/router-1-anim.gif' width="250px" alt="App in action" )
+  img(src='/resources/images/devguide/router/router-1-anim.gif' alt="App in action" width="250")
 
 a#base-href
 :marked
   ### Set the *&lt;base href>*
-  The Router uses the browser's
+
+  The router uses the browser's
   [history.pushState](https://developer.mozilla.org/en-US/docs/Web/API/History_API#Adding_and_modifying_history_entries)
   for navigation. Thanks to `pushState`, you can make in-app URL paths look the way you want them to
   look, e.g. `localhost:3000/crisis-center`. The in-app URLs can be indistinguishable from server URLs.
@@ -373,14 +385,15 @@ a#base-href
 
 +makeExcerpt('index.html', 'base-href')
 
-:marked
+.callout.is-important
-.l-sub-section
+  header Live example note
   :marked
-    #### Live example note
     A live coding environment like Plunker sets the application base address dynamically so you can't specify a fixed address.
     That's why the example code replaces the `<base href...>` with a script that writes the `<base>` tag on the fly.
-  code-example(format="")
+
+  code-example(language="html").
     &lt;script>document.write('&lt;base href="' + document.location + '" />');&lt;/script>
+
   :marked
     You should only need this trick for the live example, not production code.
 
@@ -389,7 +402,6 @@ a#import
   ### Configure the routes for the Router
 
   Begin by importing some symbols from the router library.
-
   The Router is in its own `@angular/router` package.
   It's not part of the Angular core. The router is an optional service because not all applications
   need routing and, depending on your requirements, you may need a different routing library.
@@ -397,8 +409,9 @@ a#import
   You teach the router how to navigate by configuring it with routes.
 
 a#route-config
-h4#define-routes Define routes
 :marked
+  #### Define routes
+
   A router must be configured with a list of route definitions.
 
   The first configuration defines an array of two routes with simple paths leading to the
@@ -411,13 +424,14 @@ h4#define-routes Define routes
   The router draws upon its registry of such route definitions when the browser URL changes
   or when application code tells the router to navigate along a route path.
 
-  In plain English, you might say of the first route:
+  In simpler terms, you might say of the first route:
-  * *When the browser's location URL changes to match the path segment `/crisis-center`, create or retrieve an instance of
-  the `CrisisListComponent` and display its view.*
 
-  * *When the application requests navigation to the path `/crisis-center`, create or retrieve an instance of
+  - When the browser's location URL changes to match the path segment `/crisis-center`, create or retrieve an instance of
+  the `CrisisListComponent` and display its view.
+
+  - When the application requests navigation to the path `/crisis-center`, create or retrieve an instance of
   the `CrisisListComponent`, display its view, and update the browser's address location and history with the URL
-  for that path.*
+  for that path.
 
 :marked
   Here is the first configuration. Pass the array of routes to the `RouterModule.forRoot` method.
@@ -436,10 +450,13 @@ h4#define-routes Define routes
 :marked
   Providing the `RouterModule` in the `AppModule` makes the Router available everywhere in the application.
 
-h3#shell The <i>AppComponent</i> shell
+a#shell
 :marked
+  ### The *AppComponent* shell
+
   The root `AppComponent` is the application shell. It has a title at the top, a navigation bar with two links,
-  and a *Router Outlet* at the bottom where the router swaps views on and off the page. Here's what you mean:
+  and a *router outlet* at the bottom where the router swaps views on and off the page. Here's what you get:
+
 figure.image-display
   img(src='/resources/images/devguide/router/shell-and-outlet.png' alt="Shell" width="300" )
 
@@ -455,16 +472,19 @@ a#router-outlet
 
   The `RouterOutlet` is a directive from the router library that marks
   the spot in the template where the router should display the views for that outlet.
+
 .l-sub-section
   :marked
     It renders in the the DOM as a `<router-outlet>` element.
-    The router inserts the outlet's view components as sibling elements, immediately _after_ the closing `</router-outlet>` tag.
+    The router inserts the outlet's view components as sibling elements,
+    immediately _after_ the closing `</router-outlet>` tag.
 
 a#router-link
 :marked
   ### *RouterLink* binding
 
-  Above the outlet, within the anchor tags, you see [Property Bindings](template-syntax.html#property-binding) to
+  Above the outlet, within the anchor tags, you see
+  [attribute bindings](template-syntax.html#attribute-binding) to
   the `RouterLink` directive that look like `routerLink="..."`.
 
   The links in this example each have a string path, the path of a route that
@@ -479,8 +499,9 @@ a#router-link
     Learn about the how you can also use the _link parameters array_ in the [appendix below](#link-parameters-array).
 
 a#router-link-active
-h3#router-link <i>RouterLinkActive</i> binding
 :marked
+  ### *RouterLinkActive* binding
+
   On each anchor tag, you also see [Property Bindings](template-syntax.html#property-binding) to
   the `RouterLinkActive` directive that look like `routerLinkActive="..."`.
 
@@ -494,17 +515,20 @@ h3#router-link <i>RouterLinkActive</i> binding
   To override this behavior, you can bind to the `[routerLinkActiveOptions]` input binding with the `{ exact: true }` expression.
   By using `{ exact: true }`, a given `RouterLink` will only be active if its URL is an exact match to the current URL.
 
-h3#router-directives <i>Router Directives</i>
+a#router-directives
 :marked
+  ### *Router Directives*
+
   `RouterLink`, `RouterLinkActive` and `RouterOutlet` are directives provided by the Angular `RouterModule` package.
   They are readily available for you to use in the template.
-:marked
+
   The current state of `app.component.ts` looks like this:
 
 +makeExcerpt('app/app.component.1.ts')
 
-h3#wildcard-route <i>Wildcard Routes</i>
 :marked
+  ### Wildcard route
+
   You've created two routes in the app so far, one to `/crisis-center` and the other to `/heroes`. 
   Any other URL causes the router to throw an error and crash the app.
   
@@ -515,7 +539,7 @@ h3#wildcard-route <i>Wildcard Routes</i>
 
 .l-sub-section
   :marked
-    The `Router` selects the route with a [_first match wins_](#example-config) strategy.
+    The router selects the route with a [_first match wins_](#example-config) strategy.
     Wildcard routes are the least specific routes in the route configuration.
     Be sure it is the _last_ route in the configuration.
 
@@ -606,6 +630,7 @@ a#redirect
   when the user clicks a link.
 
   You've learned how to
+
   * load the router library
   * add a nav bar to the shell template with anchor tags, `routerLink`  and `routerLinkActive` directives
   * add a `router-outlet` to the shell template where views will be displayed
@@ -618,6 +643,7 @@ a#redirect
   Here are the details for readers inclined to build the sample through to this milestone.
 
   The starter app's structure looks like this:
+
 .filetree
   .file router-sample
   .children
@@ -748,7 +774,7 @@ a#why-routing-module
   and add *Hero Management* feature files there.
 
   This example is pretty much a copy of the code and capabilities in the "[Tutorial: Tour of Heroes](../tutorial/index.html)".
-  There's not need to be more creative. 
+  There's no need to be more creative. 
 
   Here's how the user will experience this version of the app
 figure.image-display
@@ -1752,9 +1778,7 @@ a#clear-secondary-routes
   This time, the value of `'popup'` is `null`. That's not a route, but it is a legitimate value.
   Setting _popup_ `RouterOutlet` to `null` clears the outlet and removes the secondary "popup" route from the current URL.
 
-<a id="guards"></a>
+.l-main-section#guards
-.l-main-section
-h2#guards Route Guards
 :marked
   ## Milestone #5: Route Guards
 
@@ -2261,8 +2285,7 @@ include ../../../_includes/_see-addr-bar
     The `query params` and `fragment` can also be preserved using a `RouterLink` with
     the `preserveQueryParams` and `preserveFragment` bindings respectively.
 
-<a id="asynchronous-routing"></a>
+.l-main-section#asynchronous-routing
-.l-main-section
 :marked
   ## Milestone #6: Asynchronous Routing