From b2f41484721265026c87fb5c8780a8a4a57d5b61 Mon Sep 17 00:00:00 2001
From: Ward Bell <wardbell@hotmail.com>
Date: Mon, 6 Feb 2017 18:35:49 -0800
Subject: [PATCH] chore(quickstart): restore app.module and main (#3166)

We seemed to create more confusion by omitting app.module (and main) in QS than we gained in simplicity of QS
Every other example requires these files.
This PR restores them to QS _but doesn't talk about them_ in QS, leaving _that_ to the Setup guide.
---
 .../src/systemjs.config.web.build.js          | 52 -------------------
 .../_boilerplate/src/systemjs.config.web.js   | 52 -------------------
 .../docs/_examples/quickstart/ts/plnkr.json   |  2 +
 .../_examples/quickstart/ts/src/index.html    |  5 --
 public/docs/ts/latest/cli-quickstart.jade     | 32 ++++++------
 public/docs/ts/latest/guide/_data.json        |  1 -
 public/docs/ts/latest/guide/appmodule.jade    | 37 +++++++------
 public/docs/ts/latest/guide/architecture.jade |  2 +-
 .../ts/latest/guide/learning-angular.jade     |  5 +-
 public/docs/ts/latest/guide/ngmodule.jade     |  4 +-
 public/docs/ts/latest/guide/setup.jade        | 24 ++++-----
 11 files changed, 50 insertions(+), 166 deletions(-)

diff --git a/public/docs/_examples/_boilerplate/src/systemjs.config.web.build.js b/public/docs/_examples/_boilerplate/src/systemjs.config.web.build.js
index bfb9dbcd99..c27642ce02 100644
--- a/public/docs/_examples/_boilerplate/src/systemjs.config.web.build.js
+++ b/public/docs/_examples/_boilerplate/src/systemjs.config.web.build.js
@@ -79,58 +79,6 @@
     }
   });
 
-  if (global.autoBootstrap) { bootstrap(); }
-
-  // Bootstrap with a default `AppModule`
-  // ignore an `app/app.module.ts` and `app/main.ts`, even if present
-  // This function exists primarily (exclusively?) for the QuickStart
-  function bootstrap() {
-    console.log('Auto-bootstrapping');
-
-    // Stub out `app/main.ts` so System.import('app') doesn't fail if called in the index.html
-    System.set(System.normalizeSync('app/main.ts'), System.newModule({ }));
-
-    // bootstrap and launch the app (equivalent to standard main.ts)
-    Promise.all([
-      System.import('@angular/platform-browser-dynamic'),
-      getAppModule()
-    ])
-    .then(function (imports) {
-      var platform = imports[0];
-      var app      = imports[1];
-      platform.platformBrowserDynamic().bootstrapModule(app.AppModule);
-    })
-    .catch(function(err){ console.error(err); });
-  }
-
-  // Make the default AppModule
-  // returns a promise for the AppModule
-  function getAppModule() {
-    console.log('Making a bare-bones, default AppModule');
-
-    return Promise.all([
-      System.import('@angular/core'),
-      System.import('@angular/platform-browser'),
-      System.import('app/app.component')
-    ])
-    .then(function (imports) {
-
-      var core    = imports[0];
-      var browser = imports[1];
-      var appComp = imports[2].AppComponent;
-
-      var AppModule = function() {}
-
-      AppModule.annotations = [
-        new core.NgModule({
-          imports:      [ browser.BrowserModule ],
-          declarations: [ appComp ],
-          bootstrap:    [ appComp ]
-        })
-      ]
-      return {AppModule: AppModule};
-    })
-  }
 })(this);
 
 /*
diff --git a/public/docs/_examples/_boilerplate/src/systemjs.config.web.js b/public/docs/_examples/_boilerplate/src/systemjs.config.web.js
index 576bded343..dc0234a172 100644
--- a/public/docs/_examples/_boilerplate/src/systemjs.config.web.js
+++ b/public/docs/_examples/_boilerplate/src/systemjs.config.web.js
@@ -66,58 +66,6 @@
     }
   });
 
-  if (global.autoBootstrap) { bootstrap(); }
-
-  // Bootstrap with a default `AppModule`
-  // ignore an `app/app.module.ts` and `app/main.ts`, even if present
-  // This function exists primarily (exclusively?) for the QuickStart
-  function bootstrap() {
-    console.log('Auto-bootstrapping');
-
-    // Stub out `app/main.ts` so System.import('app') doesn't fail if called in the index.html
-    System.set(System.normalizeSync('app/main.ts'), System.newModule({ }));
-
-    // bootstrap and launch the app (equivalent to standard main.ts)
-    Promise.all([
-      System.import('@angular/platform-browser-dynamic'),
-      getAppModule()
-    ])
-    .then(function (imports) {
-      var platform = imports[0];
-      var app      = imports[1];
-      platform.platformBrowserDynamic().bootstrapModule(app.AppModule);
-    })
-    .catch(function(err){ console.error(err); });
-  }
-
-  // Make the default AppModule
-  // returns a promise for the AppModule
-  function getAppModule() {
-    console.log('Making a bare-bones, default AppModule');
-
-    return Promise.all([
-      System.import('@angular/core'),
-      System.import('@angular/platform-browser'),
-      System.import('app/app.component')
-    ])
-    .then(function (imports) {
-
-      var core    = imports[0];
-      var browser = imports[1];
-      var appComp = imports[2].AppComponent;
-
-      var AppModule = function() {}
-
-      AppModule.annotations = [
-        new core.NgModule({
-          imports:      [ browser.BrowserModule ],
-          declarations: [ appComp ],
-          bootstrap:    [ appComp ]
-        })
-      ]
-      return {AppModule: AppModule};
-    })
-  }
 })(this);
 
 /*
diff --git a/public/docs/_examples/quickstart/ts/plnkr.json b/public/docs/_examples/quickstart/ts/plnkr.json
index 5fb55b50ad..8edf7c25ea 100644
--- a/public/docs/_examples/quickstart/ts/plnkr.json
+++ b/public/docs/_examples/quickstart/ts/plnkr.json
@@ -3,6 +3,8 @@
   "basePath": "src/",
   "files": [
     "app/app.component.ts",
+    "app/app.module.ts",
+    "main.ts",
     "index.html"
   ],
   "open": "app/app.component.ts",
diff --git a/public/docs/_examples/quickstart/ts/src/index.html b/public/docs/_examples/quickstart/ts/src/index.html
index a6d62dae0a..21fb56edb9 100644
--- a/public/docs/_examples/quickstart/ts/src/index.html
+++ b/public/docs/_examples/quickstart/ts/src/index.html
@@ -16,11 +16,6 @@
 
     <script src="node_modules/zone.js/dist/zone.js"></script>
     <script src="node_modules/systemjs/dist/system.src.js"></script>
-
-    <!-- #docregion autobootstrap-->
-    <script> window.autoBootstrap = true; </script>
-    <!-- #enddocregion autobootstrap-->
-
     <script src="systemjs.config.js"></script>
     <script>
       System.import('main.js').catch(function(err){ console.error(err); });
diff --git a/public/docs/ts/latest/cli-quickstart.jade b/public/docs/ts/latest/cli-quickstart.jade
index dc649d957f..56eb83ab47 100644
--- a/public/docs/ts/latest/cli-quickstart.jade
+++ b/public/docs/ts/latest/cli-quickstart.jade
@@ -8,13 +8,13 @@ include _util-fns
   that can create a project, add files, and perform a variety of on-going development tasks such 
   as testing, bundling, and deployment.
   
-  Our goal in this CLI QuickStart chapter is to build and run a super-simple Angular 
+  The goal in this CLI QuickStart chapter is to build and run a super-simple Angular 
   application in TypeScript, using Angular-CLI 
   while adhering to the [Style Guide](./guide/style-guide.html) recommendations that
   benefit _every_ Angular project.
   
   By the end of the chapter, you'll have a basic understanding of development with the CLI
-  and a foundation for both these documentation samples and our real world applications.
+  and a foundation for both these documentation samples and for real world applications.
 
   You'll pursue these ends in the following high-level steps:
   
@@ -27,7 +27,7 @@ include _util-fns
 .l-main-section
 h2#devenv Step 1. Set up the Development Environment
 :marked
-  You need to set up our development environment before you can do anything.
+  You need to set up your development environment before you can do anything.
    
   Install **[Node.js® and npm](https://nodejs.org/en/download/)**
   if they are not already on your machine.
@@ -68,18 +68,18 @@ code-example(language="sh" class="code-shell").
   ng serve
   
 :marked
-  The `ng serve` command launches the server, watches our files, 
-  and rebuilds the app as you make changes to the files.
+  The `ng serve` command launches the server, watches your files, 
+  and rebuilds the app as you make changes to those files.
   
-  Open a browser on `http://localhost:4200/`; the app greets us with a message:
+  Open a browser on `http://localhost:4200/`; the app greets you with a message:
   
 figure.image-display
-  img(src='/resources/images/devguide/cli-quickstart/app-works.png' alt="Our app works!")
+  img(src='/resources/images/devguide/cli-quickstart/app-works.png' alt="The app works!")
 
 .l-main-section
-h2#first-component Step 4: Edit our first Angular component
+h2#first-component Step 4: Edit your first Angular component
 :marked
-  The CLI created our first Angular component for us. 
+  The CLI created the first Angular component for you. 
   This is the _root component_ and it is named `app-root`.
   You can find it in `./src/app/app.component.ts`.
 
@@ -91,7 +91,7 @@ h2#first-component Step 4: Edit our first Angular component
 :marked
   The browser reloads automatically and we see the revised title. That's nice, but we can make it look better.
   
-  Open `src/app/cli-quickstart.component.css` and give our component some style 
+  Open `src/app/cli-quickstart.component.css` and give the component some style 
 
 +makeExample('cli-quickstart/ts/src/app/app.component.css', null, 'src/app/app.component.css')(format=".")
 
@@ -175,10 +175,9 @@ table(width="100%")
     td <code>app/app.module.ts</code>
     td
       :marked
-        Defines `AppModule`, the [root module](guide/appmodule.html "AppModule: the root module") 
-        that tells Angular how to assemble the application.
-        Right now it declares only the `AppComponent`. 
-        Soon there will be more components to declare. 
+        Defines `AppModule`, the [root module](guide/appmodule.html "AppModule: the root module") that tells Angular how to assemble the application.
+        Right now it declares only the `AppComponent`.
+        Soon there will be more components to declare.
   tr
     td <code>assets/*</code>
     td
@@ -215,9 +214,8 @@ table(width="100%")
     td
       :marked
         The main entry point for your app.
-        Compiles the application with the [JiT compiler](glossary.html#jit)
-        and [bootstraps](guide/appmodule.html#main "bootstrap the application") 
-        the application to run in the browser.
+        Compiles the application with the [JIT compiler](glossary.html#jit)
+        and bootstraps the application's root module (`AppModule`) to run in the browser.
         You can also use the [AoT compiler](glossary.html#ahead-of-time-aot-compilation)
         without changing any code by passing on `--aot` to `ng build` or `ng serve`.
   tr
diff --git a/public/docs/ts/latest/guide/_data.json b/public/docs/ts/latest/guide/_data.json
index 30987f9add..2b87139b4c 100644
--- a/public/docs/ts/latest/guide/_data.json
+++ b/public/docs/ts/latest/guide/_data.json
@@ -33,7 +33,6 @@
     "basics": true
   },
 
-
   "appmodule": {
     "title": "AppModule: the root module",
     "navTitle": "The Root Module",
diff --git a/public/docs/ts/latest/guide/appmodule.jade b/public/docs/ts/latest/guide/appmodule.jade
index 1941335d97..49c7e51e4d 100644
--- a/public/docs/ts/latest/guide/appmodule.jade
+++ b/public/docs/ts/latest/guide/appmodule.jade
@@ -22,7 +22,7 @@ include ../_util-fns
   * **_declarations_** &mdash; the application's lone component, which is also ...
   * **_bootstrap_** &mdash; the _root_ component that Angular creates and inserts into the `index.html` host web page.
  
-  The [Angular Modules (NgModules)](ngmodule.html) guide dives deeply into the details of Angular modules.
+  The [Angular Modules (NgModule)](ngmodule.html) guide dives deeply into the details of Angular modules.
   All you need to know at the moment is a few basics about these three properties.  
 
 a#imports
@@ -43,27 +43,31 @@ a#imports
 
 .alert.is-important
    :marked
-     **Only `NgModule` classes** go in the `imports` array. Don't put any other kind of class in `imports`.
+     **Only `NgModule` classes** go in the `imports` array. Do not put any other kind of class in `imports`.
 
 .l-sub-section
   :marked
-    Don't confuse the `import` statements at the top of the file with the Angular module's `imports` array.
-    They have different jobs.
+    The `import` statements at the top of the file and the Angular module's `imports` array
+    are unrelated and have completely different jobs.
 
     The _JavaScript_ `import` statements give you access to symbols _exported_ by other files
-    so you can reference them within _this_ file. 
+    so you can reference them within _this_ file.
+    You add `import` statements to almost every application file. 
     They have nothing to do with Angular and Angular knows nothing about them.
 
-    The _module's_ `imports` array tells Angular about specific Angular modules &mdash; classes decorated with `@NgModule` &mdash;
+    The _module's_ `imports` array appears _exclusively_ in the `@NgModule` metadata object.
+    It tells Angular about specific _other_ Angular modules &mdash; all of them classes decorated with `@NgModule` &mdash;
     that the application needs to function properly.
 a#declarations
 :marked
   ### The _declarations_ array
   
-  You must declare _every_ component in one (and _only one_) `NgModule` class.
   You tell Angular which components belong to the `AppModule` by listing it in the module's `declarations` array.
   As you create more components, you'll add them to `declarations`.
   
+  You must declare _every_ component in an `NgModule` class. 
+  If you use a component without declaring it, you'll see a clear error message in the browser console.
+
   You'll learn to create two other kinds of classes &mdash; 
   [directives](attribute-directives.html) and [pipes](pipes.html) &mdash;
   that you must also add to the `declarations` array.
@@ -71,7 +75,7 @@ a#declarations
 .alert.is-important
    :marked
       **Only _declarables_** &mdash; _components_, _directives_ and _pipes_ &mdash; belong in the `declarations` array. 
-      Don't put any other kind of class in `declarations`; _not_ `NgModule` classes, _not_ service classes, _not_ model classes.
+      Do not put any other kind of class in `declarations`; _not_ `NgModule` classes, _not_ service classes, _not_ model classes.
 
 a#bootstrap-array
 :marked
@@ -121,18 +125,13 @@ l-main-section
 
   This file is very stable. Once you've set it up, you may never change it again.
 
-a#quickstart-appmodule
 l-main-section
 :marked
-  ## QuickStart's _AppModule_
-  Every Angular application must have a root `NgModule`, even the [QuickStart](../quickstart.html).
-  You didn't see it but it was there.
+  ## More about Angular Modules
 
-  A script in the `index.html` generated a hidden `AppModule` and bootstrapped it for you
-  so you could focus on the `AppComponent` and discover the _essential Angular_ more quickly.
+  Your initial app has only a single module, the _root_ module.
+  As your app grows, you'll consider subdividing it into multiple "feature" modules,
+  so of which can be loaded later ("lazy loaded") if and when the user chooses
+  to visit those features.
 
-  If you're feeling adventurous, add your own `AppModule` and `main.ts` to the
-  live code in the _QuickStart_ plunker.
-
-  Remove the following `<script>` tag from the `index.html` and see _your_ work in action.
-+makeExample('quickstart/ts/src/index.html','autobootstrap','Remove this script tag from "index.html"')(format='.')
+  When you're ready to explore these possibilities, visit the [Angular Modules (NgModule)](ngmodule.html) guide.
diff --git a/public/docs/ts/latest/guide/architecture.jade b/public/docs/ts/latest/guide/architecture.jade
index aff14f5124..fd4d1e9965 100644
--- a/public/docs/ts/latest/guide/architecture.jade
+++ b/public/docs/ts/latest/guide/architecture.jade
@@ -57,7 +57,7 @@ block angular-modules
 
   <br class="l-clear-both"><br>
   :marked
-    Every Angular app has at least one Angular module class, [the _root module_](appmodule.html "AppModule: the root module"), 
+    Every Angular app has at least one Angular module class, [the _root module_](appmodule.html "AppModule: the root module"),  
     conventionally named `AppModule`.
 
     While the _root module_ may be the only module in a small application, most apps have many more 
diff --git a/public/docs/ts/latest/guide/learning-angular.jade b/public/docs/ts/latest/guide/learning-angular.jade
index ed8c79798f..070314b594 100644
--- a/public/docs/ts/latest/guide/learning-angular.jade
+++ b/public/docs/ts/latest/guide/learning-angular.jade
@@ -18,9 +18,8 @@ figure
     a sensible project structure, data binding, master/detail, services, dependency injection, navigation, and remote data access.
 
   1. <a id="architecture"></a>Read the [Architecture](architecture.html) overview for the big picture.
-  <li if-docs="ts"><p>
-    [The Root Module](appmodule.html) introduces the `NgModule` class that tells Angular how to compile and run your application.
-  </p></li>
+  
+  1. [The Root Module](appmodule.html) introduces the `NgModule` class that tells Angular how to compile and run your application.
 
   1. [Displaying Data](displaying-data.html) shows how data binding puts component property values on screen.
 
diff --git a/public/docs/ts/latest/guide/ngmodule.jade b/public/docs/ts/latest/guide/ngmodule.jade
index 7135048355..c61ff30533 100644
--- a/public/docs/ts/latest/guide/ngmodule.jade
+++ b/public/docs/ts/latest/guide/ngmodule.jade
@@ -14,11 +14,11 @@ block includes
   It may add service providers to the application dependency injectors.
   And there are many more options covered here.
 
-  [The Root Module](appmodule.html) page introduced Angular Modules and the essentials 
+  [The Root Module](appmodule.html) guide introduced Angular Modules and the essentials
   of creating and maintaining a single _root_ `AppModule` for the entire application.
   Read that first.
 
-  This page goes into much greater depth as this extensive table of contents reveals.
+  This page goes into Angular modules in much greater depth.
 
   ## Table of Contents
   * [Angular modularity](#angular-modularity "Add structure to the app with NgModule")
diff --git a/public/docs/ts/latest/guide/setup.jade b/public/docs/ts/latest/guide/setup.jade
index 2eaa95ee69..439b51b411 100644
--- a/public/docs/ts/latest/guide/setup.jade
+++ b/public/docs/ts/latest/guide/setup.jade
@@ -20,11 +20,6 @@ a#develop-locally
   Setting up a new project on your machine is quick and easy with the **QuickStart seed**,
   maintained [on github](!{_qsRepo} "Install the github QuickStart repo"). 
 
-.l-sub-section
-  :marked
-    The <live-example title="QuickStart Seed in Plunker">QuickStart seed live-example</live-example> is QuickStart
-    _plus_ the `app.module.ts` and `main.ts` application files ([described below](#app-files "QuickStart application files")) that facilitate richer application examples.
-
 :marked
   Make sure you have [!{_prereq} installed](#install-prerequisites "What if you don't have !{_prereq}?").
   Then ...
@@ -81,9 +76,9 @@ a#non-essential
 
   ### OS/X (bash)
 code-example(language="sh" class="code-shell").
-  xargs -a non-essential-files.txt rm -rf
+  xargs rm -rf &lt; non-essential-files.osx.txt
   rm src/app/*.spec*.ts
-  rm non-essential-files.txt
+  rm non-essential-files.osx.txt
 
 :marked
   ### Windows
@@ -159,18 +154,19 @@ table(width="100%")
     td <code>app/app.module.ts</code>
     td
       :marked
-        Defines `AppModule`, the [root module](appmodule.html "AppModule: the root module") that tells Angular how to assemble the application.
-        Right now it declares only the `AppComponent`. 
-        Soon there will be more components to declare. 
+        Defines `AppModule`, the  [root module](appmodule.html "AppModule: the root module") that tells Angular how to assemble the application.
+        Right now it declares only the `AppComponent`.
+        Soon there will be more components to declare.
   tr
     td <ngio-ex>main.ts</ngio-ex>
     td
       :marked
-        Compiles the application with the [JIT compiler](../glossary.html#jit)
-        and [bootstraps](appmodule.html#main "bootstrap the application") the application to run in the browser.
-        That's a reasonable choice for the development of most projects and
+        Compiles the application with the [JIT compiler](../glossary.html#jit) and
+        [bootstraps](appmodule.html#main "bootstrap the application") 
+        the application's main module (`AppModule`) to run in the browser.
+        The JIT compiler is a reasonable choice during the development of most projects and
         it's the only viable choice for a sample running in a _live-coding_ environment like Plunker.
-        You'll learn about alternative compiling and deployment options later in the documentation.
+        You'll learn about alternative compiling and [deployment](deployment.html) options later in the documentation.
 
 .l-sub-section
   :marked