docs: rewrite structural-directives.md (#40015)

PR Close #40015

aio/content/examples/structural-directives/src/app/app.component.css

@@ -42,9 +42,7 @@ td, th {
   vertical-align: top;
 }
 
-/* #docregion p-span */
 p span { color: red; font-size: 70%; }
-/* #enddocregion p-span */
 
 .unless {
   border: 2px solid;

aio/content/examples/structural-directives/src/app/app.component.html

@@ -5,27 +5,21 @@ <h1>Structural Directives</h1>
 <p>Conditional display of hero</p>
 
 <blockquote>
-<!-- #docregion built-in, asterisk, ngif -->
+<!-- #docregion asterisk -->
 <div *ngIf="hero" class="name">{{hero.name}}</div>
-<!-- #enddocregion built-in, asterisk, ngif -->
+<!-- #enddocregion asterisk -->
 </blockquote>
 
 <p>List of heroes</p>
-<!-- #docregion built-in -->
 
 <ul>
-  <!-- #docregion ngfor-li -->
   <li *ngFor="let hero of heroes">{{hero.name}}</li>
-  <!-- #enddocregion ngfor-li -->
 </ul>
 
-<!-- #enddocregion built-in -->
-
 <hr>
 
 <h2 id="ngIf">NgIf</h2>
 
-<!-- #docregion ngif-true -->
 <p *ngIf="true">
   Expression is true and ngIf is true.
   This paragraph is in the DOM.
@@ -34,9 +28,7 @@ <h2 id="ngIf">NgIf</h2>
   Expression is false and ngIf is false.
   This paragraph is not in the DOM.
 </p>
-<!-- #enddocregion ngif-true -->
 
-<!-- #docregion display-none -->
 <p [style.display]="'block'">
   Expression sets display to "block".
   This paragraph is visible.
@@ -45,7 +37,6 @@ <h2 id="ngIf">NgIf</h2>
   Expression sets display to "none".
   This paragraph is hidden but still in the DOM.
 </p>
-<!-- #enddocregion display-none -->
 
 <h4>NgIf with template</h4>
 <p>&lt;ng-template&gt; element</p>
@@ -72,18 +63,17 @@ <h4>*ngIf with a &lt;ng-container&gt;</h4>
   and continued on my way.
 </p>
 <!-- #enddocregion ngif-ngcontainer -->
-<!-- #docregion ngif-span -->
+
 <p>
   I turned the corner
   <span *ngIf="hero">
     and saw {{hero.name}}. I waved
   </span>
   and continued on my way.
 </p>
-<!-- #enddocregion ngif-span -->
 
 <p><i>&lt;select&gt; with &lt;span&gt;</i></p>
-<!-- #docregion select-span -->
+
 <div>
   Pick your favorite hero
   (<label><input type="checkbox" checked (change)="showSad = !showSad">show sad</label>)
@@ -95,7 +85,6 @@ <h4>*ngIf with a &lt;ng-container&gt;</h4>
     </span>
   </span>
 </select>
-<!-- #enddocregion select-span -->
 
 <p><i>&lt;select&gt; with &lt;ng-container&gt;</i></p>
 <!-- #docregion select-ngcontainer -->
@@ -148,17 +137,14 @@ <h2 id="ngSwitch">NgSwitch</h2>
 
 <h4>NgSwitch</h4>
 
-<!-- #docregion built-in , ngswitch -->
 <div [ngSwitch]="hero?.emotion">
   <app-happy-hero    *ngSwitchCase="'happy'"    [hero]="hero"></app-happy-hero>
   <app-sad-hero      *ngSwitchCase="'sad'"      [hero]="hero"></app-sad-hero>
   <app-confused-hero *ngSwitchCase="'confused'" [hero]="hero"></app-confused-hero>
   <app-unknown-hero  *ngSwitchDefault           [hero]="hero"></app-unknown-hero>
 </div>
-<!-- #enddocregion built-in, ngswitch -->
 
 <h4>NgSwitch with &lt;ng-template&gt;</h4>
-<!-- #docregion ngswitch-template -->
 <div [ngSwitch]="hero?.emotion">
   <ng-template [ngSwitchCase]="'happy'">
     <app-happy-hero [hero]="hero"></app-happy-hero>
@@ -173,7 +159,6 @@ <h4>NgSwitch with &lt;ng-template&gt;</h4>
     <app-unknown-hero [hero]="hero"></app-unknown-hero>
   </ng-template>
 </div>
-<!-- #enddocregion ngswitch-template -->
 
 <hr>
 
@@ -189,6 +174,7 @@ <h2>&lt;ng-template&gt;</h2>
 <hr>
 
 <h2 id="appUnless">UnlessDirective</h2>
+<!-- #docregion toggle-info -->
 <p>
   The condition is currently
   <span [ngClass]="{ 'a': !condition, 'b': condition, 'unless': true }">{{condition}}</span>.
@@ -198,6 +184,8 @@ <h2 id="appUnless">UnlessDirective</h2>
     Toggle condition to {{condition ? 'false' : 'true'}}
   </button>
 </p>
+<!-- #enddocregion toggle-info -->
+
 <!-- #docregion appUnless-->
 <p *appUnless="condition" class="unless a">
   (A) This paragraph is displayed because the condition is false.

aio/content/examples/structural-directives/src/app/app.component.ts

@@ -10,8 +10,9 @@ import { Hero, heroes } from './hero';
 export class AppComponent {
   heroes = heroes;
   hero = this.heroes[0];
-
+  // #docregion condition
   condition = false;
+  // #enddocregion condition
   logs: string[] = [];
   showSad = true;
   status = 'ready';

aio/content/guide/ajs-quick-reference.md

@@ -140,7 +140,7 @@ The following table lists some of the key AngularJS template features with their
 
       Angular has true template input variables that are explicitly defined using the `let` keyword.
 
-      For more information, see the [Template input variables](guide/structural-directives#template-input-variable) section of [Structural Directives](guide/structural-directives).
+      For more information, see the [Structural directive shorthand](guide/structural-directives#shorthand) section of [Structural Directives](guide/structural-directives).
     </td>
 
   </tr>

aio/content/guide/architecture-components.md

@@ -166,8 +166,8 @@ The example template uses two built-in structural directives to add application
 
 <code-example path="architecture/src/app/hero-list.component.1.html" header="src/app/hero-list.component.html (structural)" region="structural"></code-example>
 
-* [`*ngFor`](guide/structural-directives#inside-ngfor) is an iterative; it tells Angular to stamp out one `<li>` per hero in the `heroes` list.
-* [`*ngIf`](guide/structural-directives#ngif-case-study) is a conditional; it includes the `HeroDetail` component only if a selected hero exists.
+* [`*ngFor`](guide/built-in-directives#ngFor) is an iterative; it tells Angular to stamp out one `<li>` per hero in the `heroes` list.
+* [`*ngIf`](guide/built-in-directives#ngIf) is a conditional; it includes the `HeroDetail` component only if a selected hero exists.
 
 #### Attribute directives
 

aio/content/guide/built-in-directives.md

@@ -198,7 +198,7 @@ The string `"let item of items"` instructs Angular to do the following:
   * Translate `"let item of items"` into an `<ng-template>` around the host element
   * Repeat the `<ng-template>` for each `item` in the list
 
-For more information see the [`<ng-template>` section](guide/structural-directives#the-ng-template) of [Structural directives](guide/structural-directives).
+For more information see the [Structural directive shorthand](guide/structural-directives#shorthand) section of [Structural directives](guide/structural-directives).
 ### Repeating a component view
 
 To repeat a component element, apply `*ngFor` to the selector.
@@ -215,7 +215,7 @@ The following example references `item` first in an interpolation and then passe
 
 <code-example path="built-in-directives/src/app/app.component.html" region="NgFor-1-2" header="src/app/app.component.html"></code-example>
 
-For more information about template input variables, see [Structural Directives](guide/structural-directives#template-input-variable).
+For more information about template input variables, see [Structural directive shorthand](guide/structural-directives#shorthand).
 
 ### Getting the `index` of `*ngFor`
 
@@ -228,8 +228,12 @@ The following example gets the `index` in a variable named `i` and displays it w
 
 The index property of the `NgFor` directive context returns the zero-based index of the item in each iteration.
 
-{@a one-per-element}
+Angular translates this instruction into an `<ng-template>` around the host element,
+then uses this template repeatedly to create a new set of elements and bindings for each `item`
+in the list.
+For more information about shorthand, see the [Structural Directives](guide/structural-directives#shorthand) guide.
 
+{@a one-per-element}
 ## Repeating elements when a condition is true
 
 To repeat a block of HTML when a particular condition is true, put the `*ngIf` on a container element that wraps an `*ngFor` element.
@@ -278,7 +282,7 @@ They do not have special access to any private APIs that other directives can't
 
 The Angular `<ng-container>` is a grouping element that doesn't interfere with styles or layout because Angular doesn't put it in the DOM.
 
-You can use [`<ng-container>`](guide/structural-directives#ngcontainer) when there's no single element to host the directive.
+You can use `<ng-container>` when there's no single element to host the directive.
 
 Here's a conditional paragraph using `<ng-container>`.
 
@@ -339,8 +343,6 @@ For example, you could replace the `<app-best-item>` switch case with a `<div>`
 
 <code-example path="built-in-directives/src/app/app.component.html" region="NgSwitch-div" header="src/app/app.component.html"></code-example>
 
-<hr />
-
 ## What's next
 
 For information on how to build your own custom directives, see [Attribute Directives](guide/attribute-directives) and [Structural Directives](guide/structural-directives).

aio/content/guide/example-apps-list.md

@@ -180,7 +180,7 @@ For more information, see [Template reference variables](guide/template-referenc
 <live-example name="ngcontainer"></live-example>
 
 Demonstrates `<ngcontainer>`.
-For more information, see the [ngtemplate section](guide/structural-directives#ngcontainer) of [Structural directives](guide/structural-directives) .
+For more information, see the [ng-container section](guide/built-in-directives#ngcontainer) of [Built-in directives](guide/structural-directives) .
 
 ### Pipes
 

aio/content/guide/glossary.md

@@ -340,6 +340,12 @@ Angular supplies a number of built-in directives that begin with the `ng` prefix
 You can also create new directives to implement your own functionality.
 You associate a *selector* (an HTML tag such as `<my-directive>`) with a custom directive, thereby extending the [template syntax](guide/template-syntax) that you can use in your apps.
 
+**UpperCamelCase**, such as `NgIf`, refers to a directive class.
+You can use **UpperCamelCase** when describing properties and directive behavior.
+
+**lowerCamelCase**, such as `ngIf` refers to a directive's attribute name.
+You can use **lowerCamelCase** when describing how to apply the directive to an element in the HTML template.
+
 {@a dom}
 
 ## domain-specific language (DSL)

aio/content/guide/interpolation.md

@@ -86,7 +86,7 @@ In the following snippet, the expression `recommended` and the expression `itemI
 
 <code-example path="interpolation/src/app/app.component.html" region="component-context" header="src/app/app.component.html"></code-example>
 
-An expression can also refer to properties of the _template's_ context such as a [template input variable](guide/structural-directives#template-input-variables) or a [template reference variable](guide/template-reference-variables).
+An expression can also refer to properties of the _template's_ context such as a [template input variable](guide/structural-directives#shorthand) or a [template reference variable](guide/template-reference-variables).
 
 The following example uses a template input variable of `customer`.