From ebc022e475c918719736395a0a5fdb7db077810c Mon Sep 17 00:00:00 2001
From: Filipe Silva <filipematossilva@gmail.com>
Date: Thu, 28 Apr 2016 11:18:52 -0700
Subject: [PATCH] docs: update prose for the `let` change to ngFor

---
 .../cookbook/a1-a2-quick-reference.jade       |   6 +-
 .../cookbook/component-communication.jade     |   2 +-
 .../docs/ts/latest/guide/displaying-data.jade |   8 +-
 public/docs/ts/latest/guide/forms.jade        |  10 +-
 .../ts/latest/guide/server-communication.jade |   2 +-
 .../latest/guide/structural-directives.jade   |   5 +-
 .../docs/ts/latest/guide/template-syntax.jade | 113 ++++++++----------
 public/docs/ts/latest/guide/user-input.jade   |  12 +-
 public/docs/ts/latest/tutorial/toh-pt2.jade   |   6 +-
 9 files changed, 74 insertions(+), 90 deletions(-)

diff --git a/public/docs/ts/latest/cookbook/a1-a2-quick-reference.jade b/public/docs/ts/latest/cookbook/a1-a2-quick-reference.jade
index 5ce28ad2d3..6976f95af4 100644
--- a/public/docs/ts/latest/cookbook/a1-a2-quick-reference.jade
+++ b/public/docs/ts/latest/cookbook/a1-a2-quick-reference.jade
@@ -97,12 +97,12 @@ table(width="100%")
         ### Local variables
       +makeExample('cb-a1-a2-quick-reference/ts/app/app.component.html', 'local')(format="." )
       :marked
-        In Angular&nbsp;2, we have true local template variables that are explicitly defined using the hash (#) symbol.
+        In Angular&nbsp;2, we have true template reference variables that are explicitly defined using the hash (#) symbol.
         
-        Using a local template variable, we can move data between elements in the template. We can use the local template
+        Using a template reference variable, we can move data between elements in the template. We can use the  template reference
         variable on the same element, on sibling elements, or on any child elements.
         
-        For more information see [Template Syntax](../guide/template-syntax.html#local-vars).
+        For more information see [Template Syntax](../guide/template-syntax.html#ref-vars).
 :marked
   [Back to top](#top)
   
diff --git a/public/docs/ts/latest/cookbook/component-communication.jade b/public/docs/ts/latest/cookbook/component-communication.jade
index f69046e241..c9e9c91748 100644
--- a/public/docs/ts/latest/cookbook/component-communication.jade
+++ b/public/docs/ts/latest/cookbook/component-communication.jade
@@ -180,7 +180,7 @@ parent-to-child-local-var
   
   A parent component cannot use data binding to read child properties
   or invoke child methods. We can do both 
-  by creating a template local variable for the child element
+  by creating a template reference variable for the child element
   and then reference that variable *within the parent template*
   as seen in the following example.
 
diff --git a/public/docs/ts/latest/guide/displaying-data.jade b/public/docs/ts/latest/guide/displaying-data.jade
index 0b2539e896..b5ce5966a9 100644
--- a/public/docs/ts/latest/guide/displaying-data.jade
+++ b/public/docs/ts/latest/guide/displaying-data.jade
@@ -140,12 +140,12 @@ figure.image-display
 .alert.is-important
   :marked
     Don't forget the leading asterisk (\*) in `*ngFor`. It is an essential part of the syntax.
-    Learn more about this and `NgFor` in the [Template Syntax](./template-syntax.html#ngFor) chapter.
+    Learn more about this and `ngFor` in the [Template Syntax](./template-syntax.html#ngFor) chapter.
 
 :marked
-  Notice the `#hero` in the `NgFor` double-quoted instruction.
-  The `#hero` is a [local template variable](./template-syntax.html#local-vars) declaration.
-  The `#` prefix declares a local variable name named `hero`.
+  Notice the `#hero` in the `ngFor` double-quoted instruction.
+  The `#hero` is a [template input variable](./template-syntax.html#ngForMicrosyntax) declaration.
+  The `let` keyword declares a local variable name named `hero`.
 
   Angular duplicates the `<li>` for each item in the list, setting the `hero` variable
   to the item (the hero) in the current iteration. Angular uses that variable as the
diff --git a/public/docs/ts/latest/guide/forms.jade b/public/docs/ts/latest/guide/forms.jade
index 3cd1515643..8c8834e863 100644
--- a/public/docs/ts/latest/guide/forms.jade
+++ b/public/docs/ts/latest/guide/forms.jade
@@ -236,7 +236,7 @@ ol
 
 :marked
   We are repeating the `<options>` tag for each power in the list of Powers.
-  The `#p` local template variable is a different power in each iteration;
+  The `p` template input variable is a different power in each iteration;
   we display its name using the interpolation syntax with the double-curly-braces.
 
 <a id="ngModel"></a>
@@ -408,7 +408,7 @@ table
     td <code>ng-valid</code>
     td <code>ng-invalid</code>
 :marked
-  Let's add a temporary [local template variable](./template-syntax.html#local-vars) named **spy**
+  Let's add a temporary [template reference variable](./template-syntax.html#ref-vars) named **spy**
   to the "Name" `<input>` tag and use the spy to display those classes.
 
 +makeExample('forms/ts/app/hero-form.component.html', 'ngControl-2','app/hero-form.component.html (excerpt)')(format=".")
@@ -464,7 +464,7 @@ figure.image-display
 
 :marked
   To achieve this effect we extend the `<input>` tag with
-  1. a [local template variable](./template-syntax.html#local-vars)
+  1. a [template reference variable](./template-syntax.html#ref-vars)
   1. the "*is required*" message in a nearby `<div>` which we'll display only if the control is invalid.
 
   Here's how we do it for the *name* input box:
@@ -472,7 +472,7 @@ figure.image-display
   'name-with-error-msg', 
   'app/hero-form.component.html (excerpt)')(format=".")
 :marked
-  We need a template local variable to access the input box's Angular control from within the template.
+  We need a template reference variable to access the input box's Angular control from within the template.
   Here we created a variable called `name` and gave it the value "ngForm".
 .l-sub-section
   :marked
@@ -607,7 +607,7 @@ figure.image-display
   wire the button's enable/disabled state to the form's validity without Angular's help?
 
   For us, it was as simple as
-  1. Define a template local variable on the (enhanced) form element
+  1. Define a template reference variable on the (enhanced) form element
   2. Reference that variable in a button some 50 lines away.
 
 .l-main-section
diff --git a/public/docs/ts/latest/guide/server-communication.jade b/public/docs/ts/latest/guide/server-communication.jade
index 248aa33c14..2e286084ac 100644
--- a/public/docs/ts/latest/guide/server-communication.jade
+++ b/public/docs/ts/latest/guide/server-communication.jade
@@ -82,7 +82,7 @@ figure.image-display
 :marked
   Beneath the heroes is an input box and an *Add Hero* button where we can enter the names of new heroes
   and add them to the database. 
-  We use a [local template variable](template-syntax.html#local-vars), `newHero`, to access the 
+  We use a [template reference variable](template-syntax.html#ref-vars), `newHero`, to access the 
   value of the input box in the `(click)` event binding. 
   When the user clicks the button, we pass that value to the component's `addHero` method and then
   clear it to make ready for a new hero name.
diff --git a/public/docs/ts/latest/guide/structural-directives.jade b/public/docs/ts/latest/guide/structural-directives.jade
index ca7e15c176..ab53753ea8 100644
--- a/public/docs/ts/latest/guide/structural-directives.jade
+++ b/public/docs/ts/latest/guide/structural-directives.jade
@@ -212,10 +212,9 @@ figure.image-display
   and move the directive onto the `<template>`.
 
   There are extra nuances stemming from
-  Angular's [ngFor micro-syntax](template-syntax.html#ngfor-micro-syntax) which expands
+  Angular's [ngFor micro-syntax](template-syntax.html#ngForMicrosyntax) which expands
   into an additional `ngForOf` property binding (the iterable) and
-  the `#hero` [local template variable](template-syntax.html#local-vars)
-  (the current item in each iteration).
+  the `hero` template input variable (the current item in each iteration).
 
 <a id="unless"></a>
 .l-main-section
diff --git a/public/docs/ts/latest/guide/template-syntax.jade b/public/docs/ts/latest/guide/template-syntax.jade
index 2eda5f7643..4dd3130378 100644
--- a/public/docs/ts/latest/guide/template-syntax.jade
+++ b/public/docs/ts/latest/guide/template-syntax.jade
@@ -24,7 +24,7 @@ include ../_util-fns
     * [NgSwitch](#ngSwitch)
     * [NgFor](#ngFor)
   * [* and &lt;template>](#star-template)
-  * [Local template variables](#local-vars)
+  * [Template reference variables](#ref-vars)
   * [Input and output properties](#inputs-outputs)
   * [Template expression operators](#expression-operators)
     * [pipe](#pipe)
@@ -148,7 +148,7 @@ include ../_util-fns
   the template expression usually references that component.
 
   The expression context can include objects other than the component.
-  A [local template variable](#local-vars) is one such alternative context object.
+  A [template reference variable](#ref-vars) is one such alternative context object.
 // #enddocregion template-expressions-context
 
 // #docregion template-expressions-guidelines
@@ -251,7 +251,7 @@ include ../_util-fns
   The *onSave* in `(click)="onSave()"` is sure to be a method of the data-bound component instance.
 
   The statement context may include an object other than the component.
-  A [local template variable](#local-vars) is one such alternative context object.
+  A [template reference variable](#ref-vars) is one such alternative context object.
   We'll frequently see the reserved `$event` symbol in event binding statements,
   representing the "message" or "payload" of the raised event.
 
@@ -1186,17 +1186,16 @@ figure.image-display
 // #enddocregion directives-ngFor-3
 
 // #docregion directives-ngFor-4
-.l-sub-section
-  :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 "#hero of heroes" means:
+<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.*
+  >*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.
-    We’ll talk about this in the next section.
+  Angular translates this instruction into a new set of elements and bindings.
 // #enddocregion directives-ngFor-4
 // #docregion directives-ngFor-5
 :marked
@@ -1204,8 +1203,13 @@ figure.image-display
   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 hash (`#`) character before "hero" creates a [local template variable](#local-vars) called `hero`.
+  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)!
+
+: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,
@@ -1216,7 +1220,7 @@ figure.image-display
 :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 local template variable and use it in our  template.
+  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".
 // #enddocregion directives-ngFor-6
@@ -1363,79 +1367,60 @@ figure.image-display
   Using the `*ngFor` syntax is much easier than writing out this expanded HTML ourselves.
 // #enddocregion star-template-ngFor-4
 
-// #docregion local-vars-1
-<a id="local-vars"></a>
+// #docregion ref-vars-1
+<a id="ref-vars"></a>
 .l-main-section
 :marked
-  ## Local template variables
+  ## Template reference variables
 
-  A **local template variable** is a vehicle for moving data across element lines.
+  A **Template reference variable** is a reference to an DOM element or directive within a template.
 
-  We've seen `#hero` used to declare a local template variable several times in this chapter,
-  most prominently when writing [NgFor](#ngFor) repeaters.
+  It can be used with native DOM elements but also with Angular 2 components - in fact, it will work with any custom web component.
 
-  In [* and &lt;templates>](#star-template), we learned how Angular expands
-  an `*ngFor` on a component tag into a `<template>` that wraps the component.
-// #enddocregion local-vars-1
-+makeExample('template-syntax/ts/app/app.component.html', 'Template-4')(format=".")
-// #docregion local-vars-2
+// #docregion ref-vars-refs
 :marked
-  The hash (`#`) prefix to "hero" means that we're defining a `hero` variable.
+  ### Referencing a template reference variable
+
+  We can reference a template reference variable on the same element, on a sibling element, or on
+  any child elements.
+
+  Here are two other examples of creating and consuming a Template reference variable:
+// #enddocregion ref-vars-refs
++makeExample('template-syntax/ts/app/app.component.html', 'ref-phone')(format=".")
+// #docregion ref-vars-value
+:marked
+  The hash (`#`) prefix to "phone" means that we're defining a `phone` variable.
 .l-sub-section
   :marked
     Folks who don't like using the `#` character can use its canonical alternative,
-    the `var-` prefix. For example, we can declare the our `hero` variable using
-    either `#hero` or `var-hero`.
-:marked
-  We define `hero` on the outer `<template>` element, where it becomes the current hero item
-  as Angular iterates through the list of heroes.
+    the `ref-` prefix. For example, we can declare the our `phone` variable using
+    either `#phone` or `ref-phone`.
 
-  The `hero` variable appears again in the binding on the inner `<hero-detail>` component element.
-  That's how each instance of the `<hero-detail>` gets its hero.
-// #enddocregion local-vars-2
-
-// #docregion local-vars-refs
-:marked
-  ### Referencing a local template variable
-
-  We can reference a local template variable on the same element, on a sibling element, or on
-  any child elements.
-
-  Here are two other examples of creating and consuming a local template variable:
-// #enddocregion local-vars-refs
-+makeExample('template-syntax/ts/app/app.component.html', 'var-phone')(format=".")
-// #docregion local-vars-value
 :marked
   ### How a variable gets its value
-  The value assigned to a variable depends upon the context.
 
-  When a directive is present on the element, as it is in the earlier NgFor `<hero-detail>` component example,
-  the directive sets the value.  Accordingly, the `NgFor` directive
-  sets the `hero` variable to a hero item from the `heroes` array.
-
-  When no directive is present, as in phone and fax examples,
   Angular sets the variable's value to the element on which it was defined.
   We defined these variables on the `input` elements.
   We’re passing those `input` element objects across to the
   button elements, where they're used in arguments to the `call` methods in the event bindings.
-// #enddocregion local-vars-value
+// #enddocregion ref-vars-value
 
-// #docregion local-vars-form-1
+// #docregion ref-vars-form-1
 :marked
-  ### NgForm and local template variables
-  Let's look at one final example: a form, the poster child for local template variables.
+  ### NgForm and template reference variables
+  Let's look at one final example: a form, the poster child for template reference variables.
 
   The HTML for a form can be quite involved, as we saw in the [Forms](forms.html) chapter.
   The following is a *simplified* example &mdash; and it's not simple at all.
-// #enddocregion local-vars-form-1
-+makeExample('template-syntax/ts/app/app.component.html', 'var-form')(format=".")
-// #docregion local-vars-form-2
+// #enddocregion ref-vars-form-1
++makeExample('template-syntax/ts/app/app.component.html', 'ref-form')(format=".")
+// #docregion ref-vars-form-2
 :marked
-  A local template variable, `theForm`, appears three times in this example, separated
+  A template reference variable, `theForm`, appears three times in this example, separated
   by a large amount of HTML.
-// #enddocregion local-vars-form-2
-+makeExample('template-syntax/ts/app/app.component.html', 'var-form-a')(format=".")
-// #docregion local-vars-form-3
+// #enddocregion ref-vars-form-2
++makeExample('template-syntax/ts/app/app.component.html', 'ref-form-a')(format=".")
+// #docregion ref-vars-form-3
 :marked
   What is the value of `theForm`?
 
@@ -1447,7 +1432,7 @@ figure.image-display
 
   This explains how we can disable the submit button by checking `theForm.form.valid`
   and pass an object with rich information to the parent component's `onSubmit` method.
-// #enddocregion local-vars-form-3
+// #enddocregion ref-vars-form-3
 
 // #docregion inputs-outputs-1
 <a id="inputs-outputs"></a>
diff --git a/public/docs/ts/latest/guide/user-input.jade b/public/docs/ts/latest/guide/user-input.jade
index 5898c376a5..f1fe56fb06 100644
--- a/public/docs/ts/latest/guide/user-input.jade
+++ b/public/docs/ts/latest/guide/user-input.jade
@@ -82,18 +82,18 @@ figure.image-display
 
 .l-main-section
 :marked
-  ## Get user input from a local template variable
+  ## Get user input from a template reference variable
   There's another way to get the user data without the `$event` variable.
 
-  Angular has a syntax feature called [**local template variables**](./template-syntax.html#local-vars).
+  Angular has a syntax feature called [**template reference variables**](./template-syntax.html#ref-vars).
   These variables grant us direct access to an element.
-  We declare a local template variable by preceding an identifier with a hash/pound character (#).
+  We declare a template reference variable by preceding an identifier with a hash/pound character (#).
 
-  Here's an example of using a local template variable
+  Here's an example of using a template reference variable
   to implement a clever keystroke loopback in an ultra-simple template.
 +makeExample('user-input/ts/app/loop-back.component.ts', 'loop-back-component', 'app/loop-back.component.ts')(format=".")
 :marked
-  We've declared a template local variable named `box` on the `<input>` element.
+  We've declared a template reference variable named `box` on the `<input>` element.
   The `box` variable is a reference to the `<input>` element itself, which means we can
   grab the input element's `value` and display it
   with interpolation between `<p>` tags.
@@ -116,7 +116,7 @@ figure.image-display
     We're binding to the number 0, the shortest statement we can think of.
     That is all it takes to keep Angular happy. We said it would be clever!
 :marked
-  That local template variable is intriguing. It's clearly easier to get to the textbox with that
+  That template reference variable is intriguing. It's clearly easier to get to the textbox with that
   variable than to go through the `$event` object. Maybe we can rewrite our previous
   keyup example so that it uses the variable to get the user's input. Let's give it a try.
 +makeExample('user-input/ts/app/keyup.components.ts', 'key-up-component-2' ,'app/keyup.components.ts (v2)')(format=".")
diff --git a/public/docs/ts/latest/tutorial/toh-pt2.jade b/public/docs/ts/latest/tutorial/toh-pt2.jade
index b9fd02530a..d0aba75a14 100644
--- a/public/docs/ts/latest/tutorial/toh-pt2.jade
+++ b/public/docs/ts/latest/tutorial/toh-pt2.jade
@@ -105,10 +105,10 @@ code-example(format="." language="bash").
     “*take each hero in the `heroes` array, store it in the local `hero` variable,
     and make it available to the corresponding template instance*”.
 
-    The `#` prefix before "hero" identifies the `hero` as a local template variable.
+    The `let` keyword before "hero" identifies the `hero` as a template input variable.
     We can reference this variable within the template to access a hero’s properties.
 
-    Learn more about `ngFor` and local template variables in the
+    Learn more about `ngFor` and template input variables in the
     [Displaying Data](../guide/displaying-data.html#ngFor) and
     [Template Syntax](../guide/template-syntax.html#ngFor) chapters.
 
@@ -167,7 +167,7 @@ code-example(format="." language="bash").
   :marked
     The parenthesis identify the `<li>` element’s  `click` event as the target.
     The expression to the right of the equal sign calls the  `AppComponent` method, `onSelect()`,
-    passing the local template variable `hero` as an argument.
+    passing the template input variable `hero` as an argument.
     That’s the same `hero` variable we defined previously in the `ngFor`.
   .l-sub-section
     :marked