chore(structural-directives): drop material accidentally repeated from Template Syntax

Author: wardbell

public/docs/_examples/structural-directives/ts/app/app.component.html

@@ -33,8 +33,10 @@ <h3>Do not confuse &lt;ng-container&gt; with &lt;ng-content&gt; !</h3>
 <!-- #docregion structural-directives -->
 <!-- #docregion asterisk -->
 <div *ngIf="hero">{{hero}}</div>
+
 <div *ngFor="let hero of heroes">{{hero}}</div>
 <!-- #enddocregion asterisk -->
+
 <!-- #docregion ngSwitch -->
 <div [ngSwitch]="status">
   <template [ngSwitchCase]="'in-mission'">In Mission</template>

public/docs/ts/latest/guide/structural-directives.jade

@@ -1,19 +1,22 @@
 block includes
   include ../_util-fns
 
+// The docs standard h4 style uppercases, making code terms unreadable. Override it.
+style.
+  h4 {font-size: 17px !important; text-transform: none !important;}
+  .syntax { font-family: Consolas, 'Lucida Sans', Courier, sans-serif; color: black; font-size: 85%; }
+
 :marked
-  One of the defining features of a single page application is its manipulation
-  of the DOM tree. Instead of serving a whole new page every time a user
-  navigates, whole sections of the DOM appear and disappear according
-  to the application state. In this chapter we'll look at how Angular
-  manipulates the DOM and how we can do it ourselves in our own directives.
+  This guide looks at how Angular manipulates the DOM with **structural directives** and 
+  how you can write your own structural directives to do the same thing.
+
+  ### Table of contents
 
-  In this chapter we will
-  - [learn what structural directives are](#definition)
-  - [study *ngIf*](#ngIf)
-  - [discover the <template> element](#template)
-  - [understand the asterisk (\*) in **ngFor*](#asterisk)
-  - [write our own structural directive](#unless)
+  - [What structural directives are](#definition)
+  - [*NgIf* case study](#ngIf)
+  - [The <template> element](#template)
+  - [The asterisk (\*) prefix](#asterisk)
+  - [Write a structural directive](#unless)
 
   Try the <live-example></live-example>.
 
@@ -22,25 +25,28 @@ block includes
 :marked
   ## What are structural directives?
 
-  There are three kinds of Angular directives:
-  1. Components
-  1. Attribute directives
-  1. Structural directives
-
-  The *Component* is really a directive with a template.
-  It's the most common of the three directives and we write lots of them as we build our application.
+  Structural directives are responsible for HTML layout.
+  They shape or reshape the DOM's _structure_, typically by adding, removing, or manipulating
+  elements and their children.
 
-  The [*Attribute* directive](attribute-directives.html) changes the appearance or behavior of an element.
-  The built-in [NgStyle](template-syntax.html#ngStyle) directive, for example,
-  can change several element styles at the same time.
-  We can use it to render text bold, italic, and lime green by binding to a
-  component property that requests such a sickening result.
+  Three of the common, built-in structural directives &mdash; 
+  [ngIf](template-syntax.html#ngIf), [ngSwitch](template-syntax.html#ngSwitch) and [ngFor](template-syntax.html#ngFor) &mdash;
+  are described in the [_Template Syntax_](template-syntax.html) guide and seen in samples throughout the Angular documentation.
 
-  A *Structural* directive changes the DOM layout by adding and removing DOM elements.
-  We've seen three of the built-in structural directives in other chapters: [ngIf](template-syntax.html#ngIf),
-  [ngSwitch](template-syntax.html#ngSwitch) and [ngFor](template-syntax.html#ngFor).
+  Here are examples of all three:
 
 +makeExample('structural-directives/ts/app/app.component.html', 'structural-directives')(format=".")
+.l-sub-section
+  :marked
+    There are two other kinds of Angular directives, described extensively elsewhere: (1)&nbsp;components and (2)&nbsp;attribute directives.
+  
+    A *component* manages a region of HTML in the manner of a native HTML element.
+    Technically it's a directive with a template. 
+
+    An [*attribute* directive](attribute-directives.html) changes the appearance or behavior of an element.
+    For example, the built-in [NgStyle](template-syntax.html#ngStyle) directive
+    changes several element styles at the same time.
+
 
 <a id="ngIf"></a>
 .l-main-section
@@ -261,176 +267,6 @@ figure.image-display
   What does this have to do with `ngIf` and `ngFor`?  We didn't use a `<template>` tag with those directives.
   But Angular did.
 
-<a id="ngIf"></a>
-.l-main-section
-:marked
-  ### NgIf
-  We can add an element subtree (an element and its children) to the DOM  by binding an `NgIf` directive to a #{_truthy} expression.
-+makeExample('template-syntax/ts/app/app.component.html', 'NgIf-1')(format=".")
-
-.alert.is-critical
-  :marked
-    Don't forget the asterisk (`*`) in front of `ngIf`.
-    For more information, see [\* and &lt;template>](#star-template).
-:marked
-  Binding to a #{_falsy} expression removes the element subtree from the DOM.
-+makeExample('template-syntax/ts/app/app.component.html', 'NgIf-2')(format=".")
-
-block dart-no-truthy-falsy
-  //- N/A
-
-:marked
-  #### Visibility and NgIf are not the same
-  We can show and hide an element subtree (the element and its children) with a
-  [class](#class-binding) or [style](#style-binding) binding:
-+makeExample('template-syntax/ts/app/app.component.html', 'NgIf-3')(format=".")
-:marked
-  Hiding a subtree is quite different from excluding a subtree with `NgIf`.
-
-  When we hide the element subtree, it remains in the DOM.
-  Components in the subtree are preserved, along with their state.
-  Angular may continue to check for changes even to invisible properties.
-  The subtree may tie up substantial memory and computing resources.
-
-  When `NgIf` is `false`, Angular physically removes the element subtree from the DOM.
-  It destroys components in the subtree, along with their state, potentially freeing up substantial resources and
-  resulting in better performance for the user.
-
-  The show/hide technique is probably fine for small element trees.
-  We should be wary when hiding large trees; `NgIf` may be the safer choice. Always measure before leaping to conclusions.
-
-<a id="ngSwitch"></a>
-.l-main-section
-:marked
-  ### NgSwitch
-  We bind to `NgSwitch` when we want to display *one* element tree (an element and its children)
-  from a *set* of possible element trees, based on some condition.
-  Angular puts only the *selected* element tree into the DOM.
-
-  Here's an example:
-+makeExample('template-syntax/ts/app/app.component.html', 'NgSwitch')(format=".")
-:marked
-  We bind the parent `NgSwitch` directive to an expression returning a *switch value*.
-  The value is a string in this example, but it can be a value of any type.
-
-  In this example, the parent `NgSwitch` directive controls a set of child `<span>` elements.
-  A `<span>` is either pegged to a *match value* expression or marked as the default.
-
-  **At any particular moment, at most one of these *spans* is in the DOM.**
-
-  If the *span*'s *match value* equals the switch value, Angular adds the `<span>` to the DOM.
-  If none of the *spans* is a match, Angular adds the default *span* to the DOM.
-  Angular removes and destroys all other *spans*.
-.l-sub-section
-  :marked
-    We could substitute any element for the *span* in this example.
-    That element could be a `<div>` with a vast subtree of its own elements.
-    Only the matching `<div>` and its subtree would appear in the DOM;
-    the others would be removed.
-:marked
-  Three collaborating directives are at work here:
-  1. `ngSwitch`: bound to an expression that returns the switch value
-  1. `ngSwitchCase`: bound to an expression returning a match value
-  1. `ngSwitchDefault`: a marker attribute on the default element
-
-.alert.is-critical
-  :marked
-    **Do *not*** put the asterisk (`*`) in front of `ngSwitch`. Use the property binding instead.
-
-    **Do** put the asterisk (`*`) in front of `ngSwitchCase` and `ngSwitchDefault`.
-    For more information, see [\* and &lt;template>](#star-template).
-
-<a id="ngFor"></a>
-.l-main-section
-:marked
-  ### NgFor
-  `NgFor` is a _repeater_ directive &mdash; a way to customize data display.
-
-  Our goal is to present a list of items. We define a block of HTML that defines how a single item should be displayed.
-  We tell Angular to use that block as a template for rendering each item in the list.
-
-  Here is an example of `NgFor` applied to a simple `<div>`:
-+makeExample('template-syntax/ts/app/app.component.html', 'NgFor-1')(format=".")
-:marked
-  We can also apply an `NgFor` to a component element, as in this example:
-+makeExample('template-syntax/ts/app/app.component.html', 'NgFor-2')(format=".")
-
-.alert.is-critical
-  :marked
-    Don't forget the asterisk (`*`) in front of `ngFor`.
-    For more information, see [\* and &lt;template>](#star-template).
-:marked
-  The text assigned to `*ngFor` is the instruction that guides the repeater process.
-
-<a id="ngForMicrosyntax"></a>
-:marked
-  #### NgFor microsyntax
-  The string assigned to `*ngFor` is not a [template expression](#template-expressions).
-  It's a *microsyntax* &mdash; a little language of its own that Angular interprets. In this example, the string `"let hero of heroes"` means:
-
-  > *Take each hero in the `heroes` #{_array}, store it in the local `hero` variable, and make it available to the templated HTML for each iteration.*
-
-  Angular translates this instruction into a new set of elements and bindings.
-
-  In the two previous examples, the `ngFor` directive iterates over the `heroes` #{_array} returned by the parent component's `heroes` property,
-  stamping out instances of the element to which it is applied.
-  Angular creates a fresh instance of the template for each hero in the array.
-
-  The `let` keyword before `hero` creates a template input variable called `hero`.
-
-.alert.is-critical
-  :marked
-     A **template _input_ variable** is **_not_** the same as a [**template _reference_ variable**](#ref-vars),
-     neither _semantically_ nor _syntactically_.
-
-     The name in a template _input_ variable declaration is preceded by `let`.
-     The name in a template _reference_ variable declaration is preceded by `#`.
-
-:marked
-  We use this variable within the template to access a hero's properties,
-  as we're doing in the interpolation.
-  We can also pass the variable in a binding to a component element,
-  as we're doing with `hero-detail`.
-
-:marked
-  #### NgFor with index
-  The `ngFor` directive supports an optional `index` that increases from 0 to the length of the array for each iteration.
-  We can capture the index in a template input variable and use it in our template.
-
-  The next example captures the index in a variable named `i`, using it to stamp out rows like "1 - Hercules Son of Zeus".
-+makeExample('template-syntax/ts/app/app.component.html', 'NgFor-3')(format=".")
-.l-sub-section
-  :marked
-    Learn about other special *index-like* values such as `last`, `even`, and `odd` in the [NgFor API reference](../api/common/index/NgFor-directive.html).
-
-:marked
-  #### NgForTrackBy
-  The `ngFor` directive has the potential to perform poorly, especially with large lists.
-  A small change to one item, an item removed, or an item added can trigger a cascade of DOM manipulations.
-
-  For example, we could refresh the list of heroes by re-querying the server.
-  The refreshed list probably contains most, if not all, of the previously displayed heroes.
-
-  *We* know this because the `id` of each hero hasn't changed.
-  But Angular sees only a fresh list of new object references.
-  It has no choice but to tear down the old list, discard those DOM elements, and re-build a new list with new DOM elements.
-
-  Angular can avoid this churn if we give it a *tracking* function that tells it what we know:
-  that two objects with the same `hero.id` are the same *hero*. Here is such a function:
-+makeExample('template-syntax/ts/app/app.component.ts', 'trackByHeroes')(format=".")
-:marked
-  Now set the `NgForTrackBy` directive to that *tracking* function.
-+makeExample('template-syntax/ts/app/app.component.html', 'NgForTrackBy-2')(format=".")
-:marked
-  The *tracking* function doesn't eliminate all DOM changes.
-  Angular may have to update the DOM element if the same-hero *properties* have changed.
-  But if the properties haven't changed &mdash; and most of the time they will not have changed &mdash;
-  Angular can leave those DOM elements alone. The list UI will be smoother and more responsive.
-
-  Here is an illustration of the `NgForTrackBy` effect.
-figure.image-display
-  img(src='/resources/images/devguide/template-syntax/ng-for-track-by-anim.gif' alt="NgForTrackBy")
-
 <a id="asterisk"></a>
 .l-main-section
 :marked
@@ -561,7 +397,7 @@ figure.image-display
 .l-main-section
 :marked
   ## Wrap up
-  Here is the pertinent source for this chapter.
+  Here is the pertinent source for this guide.
 
 +makeTabs(`
   structural-directives/ts/app/unless.directive.ts,
@@ -585,4 +421,4 @@ figure.image-display
   and incorporate that content within their own templates.
   Tab and tab pane controls are good examples.
 
-  We'll learn about structural components in a future chapter.
+  We'll learn about structural components in a future guide.

public/docs/ts/latest/guide/template-syntax.jade

@@ -960,9 +960,9 @@ a#attribute-directives
   other HTML elements, attributes, properties, and components. 
   They are usually applied to elements as if they were HTML attributes, hence the name.
 
-  Many details are covered in the [_Attribute Directives_](guide/attribute-directives.html) guide.
-  Many Angular modules such the [`RouterModule`](guide/router.html "Routing and Navigation") 
-  and the [`FormsModule`](guide/forms.html "Forms") have their own attribute directives.
+  Many details are covered in the [_Attribute Directives_](attribute-directives.html) guide.
+  Many Angular modules such the [`RouterModule`](router.html "Routing and Navigation") 
+  and the [`FormsModule`](forms.html "Forms") have their own attribute directives.
   This section is an introduction to the most commonly used attribute directives:
 
   * [`NgClass`](#ngClass) - add and remove a set of CSS classes
@@ -1098,11 +1098,13 @@ a#structural-directives
   ## Built-in _structural_ directives
 
   Structural directives are responsible for HTML layout.
-  They shape or reshape the element _structure_, typically by adding, removing, or manipulating
+  They shape or reshape the DOM's _structure_, typically by adding, removing, or manipulating
   elements and their children.
 
-  Deeper details are in the [_Structural Directives_](guide/structural-directives.html) guide.
-  This section is an introduction to the most commonly used structural directives:
+  The deep details of how structural directives work are covered in the [_Structural Directives_](structural-directives.html) guide.
+  There you'll learn why these directives are usually [**prefixed with an asterisk**](structural-directives.html#star-template).
+
+  _This_ section is an introduction to the most commonly used structural directives and how to use them:
 
   * [`NgIf`](#ngIf) - conditionally add or remove an element from the DOM
   * [`NgSwitch`](#ngSwitch) - switch among alternative elements