docs: template syntax refresh for style, accuracy, understanding

Move details of structural directives from template-syntax to structural-directives guide/structural-directives
Add <ng-container> to structural-directives
Touch up glossary
Better conformance to google doc guidelines: we->you
closes angular#2303, angular#2885

Author: wardbell

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

@@ -1,6 +1,34 @@
 <!-- #docplaster -->
 <!-- #docregion -->
+<style>
+  .syntax { font-family: Consolas, 'Lucida Sans', Courier, sans-serif;}
+</style>
 <h1>Structural Directives</h1>
+<h3>Do not confuse &lt;ng-container&gt; with &lt;ng-content&gt; !</h3>
+<p>&lt;ng-content&gt;this is an Angular parse error&lt;/ng-content&gt;</p>
+  <div [style.font-family]="'courier, sans-serif'">Template parse errors:<br>
+  &lt;ng-content&gt; element cannot have content.</div>
+
+<p [style.maxWidth]="'40em'">
+  The HTML &lt;template&gt; element is a mechanism for holding client-side content that is
+  not to be rendered when a page is loaded but may subsequently be instantiated during runtime using JavaScript.
+  - <a href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/template" target="_blank">MDN on &lt;template&gt;</a>
+</p>
+<p><b>&lt;template&gt;Inside template&lt;/template&gt;</b> <i>nothing to see</i>:</p>
+<template>Inside template</template>
+<p><b>&lt;ng-container&gt;Inside ng-container&lt;/ng-container&gt;</b></p>
+<ng-container>Inside ng-container</ng-container>
+<p><b>&lt;span *ngFor="let hero of heroes"&gt;</b> <i>&lt;span&gt; is repeated</i>:</p>
+<span *ngFor="let hero of heroes">{{hero.fullName}} </span>
+
+<p><b>&lt;template *ngFor="let hero of heroes"&gt;</b> <i>nothing to see</i>:</p>
+<template *ngFor="let hero of heroes">{{hero.fullName}} </template>
+
+<p><b>&lt;template ngFor let-hero [ngForOf]="heroes"&gt;:</b></p>
+<template ngFor let-hero [ngForOf]="heroes">{{hero.fullName}} </template>
+
+<p><b>&lt;ng-container *ngFor="let hero of heroes"&gt;:</b></p>
+<ng-container *ngFor="let hero of heroes">{{hero.fullName}} </ng-container>
 
 <!-- #docregion structural-directives -->
 <!-- #docregion asterisk -->
@@ -63,17 +91,11 @@ <h4>heavy-loader log:</h4>
 <hr>
 
 <!-- #docregion template-tag -->
-<p>
-  Hip!
-</p>
+<p>Hip!</p>
 <template>
-  <p>
-    Hip!
-  </p>
+  <p>Hip!</p>
 </template>
-<p>
-  Hooray!
-</p>
+<p>Hooray!</p>
 <!-- #enddocregion template-tag -->
 
 <hr>

public/docs/_examples/structural-directives/ts/app/structural-directives.component.ts renamed to public/docs/_examples/structural-directives/ts/app/app.component.ts

@@ -1,19 +1,17 @@
-// #docplaster
 // #docregion
 import { Component } from '@angular/core';
 
 @Component({
   moduleId: module.id,
-  selector: 'structural-directives',
-  templateUrl: './structural-directives.component.html',
+  selector: 'my-app',
+  templateUrl: './app.component.html',
   styles: ['button { min-width: 100px; }']
 })
-export class StructuralDirectivesComponent {
+export class AppComponent {
   heroes = ['Mr. Nice', 'Narco', 'Bombasto'];
   hero = this.heroes[0];
   condition = true;
   isVisible = true;
   logs: string[] = [];
   status = 'ready';
 }
-// #enddocregion

public/docs/_examples/structural-directives/ts/app/app.module.ts

@@ -2,17 +2,17 @@
 import { NgModule } from '@angular/core';
 import { BrowserModule } from '@angular/platform-browser';
 
-import { StructuralDirectivesComponent } from './structural-directives.component';
-import { UnlessDirective } from './unless.directive';
+import { AppComponent }         from './app.component';
+import { UnlessDirective }      from './unless.directive';
 import { HeavyLoaderComponent } from './heavy-loader.component';
 
 @NgModule({
   imports: [ BrowserModule ],
   declarations: [
-    StructuralDirectivesComponent,
+    AppComponent,
     UnlessDirective,
     HeavyLoaderComponent
   ],
-  bootstrap: [ StructuralDirectivesComponent ]
+  bootstrap: [ AppComponent ]
 })
 export class AppModule { }

public/docs/_examples/structural-directives/ts/plnkr.json

@@ -1,6 +1,9 @@
 {
   "description": "Structural directives",
-  "files": ["!**/*.d.ts", "!**/*.js"],
+  "files": [
+    "!**/*.d.ts",
+    "!**/*.js"
+  ],
   "tags": [
     "structural", "directives", "template", "ngIf",
     "ngSwitch", "ngFor"

public/docs/ts/latest/glossary.jade

@@ -54,8 +54,10 @@ a#aot
       :marked
         In practice, a synonym for [Decoration](#decorator).
 
+a#attribute-directive
+a#attribute-directives
 :marked
-  ## Attribute directive
+  ## Attribute directives
 .l-sub-section
   :marked
     A category of [directive](#directive) that can listen to and modify the behavior of
@@ -64,6 +66,8 @@ a#aot
 
     A good example of an attribute directive is the `ngClass` directive for adding and removing CSS class names.
 
+    Learn about them in the [_Attribute Directives_](!{docsLatest}/guide/attribute-directives.html) guide.
+
 .l-main-section#B
 
 +ifDocsFor('ts|js')
@@ -141,6 +145,7 @@ a#aot
     This form is also known as **lower camel case**, to distinguish it from **upper camel case**, which is [PascalCase](#pascalcase).
     When you see "camelCase" in this documentation it always means *lower camel case*.
 
+a#component
 :marked
   ## Component
 .l-sub-section
@@ -245,7 +250,7 @@ a#aot
     that "B" is a dependency of "A".
 
     You can ask a "dependency injection system" to create "A"
-    for us and handle all the dependencies.
+    and it will handle all of "A"s dependencies.
     If "A" needs "B" and "B" needs "C", the system resolves that chain of dependencies
     and returns a fully prepared instance of "A".
 
@@ -276,18 +281,20 @@ a#aot
     Registering providers is a critical preparatory step.
 
     Angular registers some of its own providers with every injector.
-    We can register our own providers.
+    You can register your own providers.
 
     Read more in the [Dependency Injection](!{docsLatest}/guide/dependency-injection.html) page.
+
+a#directive
+a#directives
 :marked
   ## Directive
 .l-sub-section
   :marked
     An Angular class responsible for creating, reshaping, and interacting with HTML elements
     in the browser DOM. Directives are Angular's most fundamental feature.
 
-    A Directive is almost always associated with an HTML element or attribute.
-    We often refer to such an element or attribute as the directive itself.
+    A directive is almost always associated with an HTML element or attribute.
     When Angular finds a directive in an HTML template,
     it creates the matching directive class instance
     and gives the instance control over that portion of the browser DOM.
@@ -300,15 +307,15 @@ a#aot
     Directives fall into one of three categories:
 
     1. [Components](#component) that combine application logic with an HTML template to
-    render application [views]. Components are usually represented as HTML elements.
+    render application [views](#view). Components are usually represented as HTML elements.
     They are the building blocks of an Angular application and the
     developer can expect to write a lot of them.
 
-    1. [Attribute directives](#attribute-directive) that can listen to and modify the behavior of
+    1. [Attribute directives](#attribute-directives) that can listen to and modify the behavior of
     other HTML elements, attributes, properties, and components. They are usually represented
     as HTML attributes, hence the name.
 
-    1. [Structural directives](#structural-directive), a directive responsible for
+    1. [Structural directives](#structural-directives), a directive responsible for
     shaping or reshaping HTML layout, typically by adding, removing, or manipulating
     elements and their children.
 
@@ -630,21 +637,24 @@ a#snake-case
     Applications often require services such as a hero data service or a logging service.
 
     A service is a class with a focused purpose.
-    We often create a service to implement features that are
+    You often create a service to implement features that are
     independent from any specific view,
     provide shared data or logic across components, or encapsulate external interactions.
 
     For more information, see the [Services](!{docsLatest}/tutorial/toh-pt4.html) page of the [Tour of Heroes](!{docsLatest}/tutorial/) tutorial.
 
+a#structural-directive
+a#structural-directives
 :marked
-  ## Structural directive
+  ## Structural directives
 .l-sub-section
   :marked
     A category of [directive](#directive) that can
     shape or reshape HTML layout, typically by adding, removing, or manipulating
-    elements and their children; for example, the `ngIf` "conditional element" directive and the `ngFor` "repeater" directive.
+    elements and their children. 
+    Examples include the `*ngIf` _conditional_ directive and the `*ngFor` _repeater_ directive.
 
-    Read more in the [Structural Directives](!{docsLatest}/guide/structural-directives.html) page.
+    Read more in the [_Structural Directives_](!{docsLatest}/guide/structural-directives.html) guide.
 
 .l-main-section#T
 :marked
@@ -699,8 +709,8 @@ a#snake-case
     A version of JavaScript that supports most [ECMAScript 2015](#es2015)
     language features such as [decorators](#decorator).
 
-    TypeScript is also noteable for its optional typing system, which gives
-    us compile-time type checking and strong tooling support (for example, "intellisense",
+    TypeScript is also noteable for its optional typing system, which enables
+    compile-time type checking and strong tooling support (for example, "intellisense",
     code completion, refactoring, and intelligent search). Many code editors
     and IDEs support TypeScript either natively or with plugins.