docs(cookbook-aot-compiler): improve Ahead-of-Time compilation cookbook (#2798)

closes #2790

Author: wardbell

public/docs/_examples/toh-6/ts/app/main.ts

@@ -1,6 +1,6 @@
 // #docregion
-// main entry point
 import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
+
 import { AppModule } from './app.module';
 
 platformBrowserDynamic().bootstrapModule(AppModule);

public/docs/ts/latest/cookbook/aot-compiler.jade

@@ -341,9 +341,11 @@ a#toh
 
   Fortunately, the source code can be compiled either way without change _if_ you account for a few key differences.
 
-  ***Index.html***
+  ***index.html***
 
-  The JiT and AoT apps are setup and launched so differently that they require their own `index.html` files. 
+  The JiT and AoT apps require their own `index.html` files because they setup and launch so differently. 
+  **Put the AoT version in the `/aot` folder** because two `index.html` files can't be in the same folder. 
+  
   Here they are for comparison:
 
 +makeTabs(
@@ -355,35 +357,47 @@ a#toh
 )
 
 :marked
-  They can't be in the same folder. 
-  ***Put the AoT version in the `/aot` folder***.
-
   The JiT version relies on `SystemJS` to load individual modules and requires the `reflect-metadata` shim. 
   Both scripts appear in its `index.html`.
 
   The AoT version loads the entire application in a single script, `aot/dist/build.js`.
   It does not need `SystemJS` or the `reflect-metadata` shim; those scripts are absent from its `index.html`
+  
+  ***main.ts***
+  
+  JiT and AoT applications boot in much the same way but require different Angular libraries to do so.
+  The key differences, covered in the [Bootstrap](#bootstrap) section above,
+  are evident in these `main` files which can and should reside in the same folder: 
+
++makeTabs(
+  `toh-6/ts/app/main-aot.ts,
+   toh-6/ts/app/main.ts`,
+  null,
+  `app/main-aot.ts (AoT),
+   app/main.ts (JiT)`
+)
 
-  *Component-relative Template URLS*
+:marked
+  ***Component-relative Template URLS***
 
   The AoT compiler requires that `@Component` URLS for external templates and css files be _component-relative_.
-  That means that the value of `@Component.templateUrl` is a URL value relative to the component class file:
-  `foo.component.html` no matter where `foo.component.ts` sits in the project folder structure.
+  That means that the value of `@Component.templateUrl` is a URL value _relative_ to the component class file.
+  For example, a `'hero.component.html'` URL means that the template file is a sibling of its companion `hero.component.ts` file.
 
   While JiT app URLs are more flexible, stick with _component-relative_ URLs for compatibility with AoT compilation.
 
-  JiT-compiled apps, using the SystemJS loader and _component-relative_ URLs *must set the* `@Component.moduleId` *property to* `module.id`.
+  JiT-compiled applications that use the SystemJS loader and _component-relative_ URLs *must set the* `@Component.moduleId` *property to* `module.id`.
   The `module` object is undefined when an AoT-compiled app runs. 
-  The app fails unless you assign a global `module` value in the `index.html` like this:
+  The app fails with a null reference error unless you assign a global `module` value in the `index.html` like this:
 +makeExample('toh-6/ts/aot/index.html','moduleId')(format='.')  
 .l-sub-section
   :marked
     Setting a global `module` is a temporary expedient. 
 :marked
-  *TypeScript configuration*
+  ***TypeScript configuration***
 
-  JiT-compiled apps transpile to `commonjs` modules.
-  AoT-compiled apps transpile to _ES2015_/_ES6_ modules to facilitate Tree Shaking. 
+  JiT-compiled applications transpile to `commonjs` modules.
+  AoT-compiled applications transpile to _ES2015_/_ES6_ modules to facilitate Tree Shaking. 
   AoT requires its own TypeScript configuration settings as well.
 
   You'll need separate TypeScript configuration files such as these:
@@ -396,6 +410,17 @@ a#toh
    tsconfig.json (JiT)`
 )
 
+.callout.is-helpful
+  header @Types and node modules
+  :marked
+    In the file structure of _this particular sample project_,
+    the `node_modules` folder happens to be two levels up from the project root. 
+    Therefore, `"typeRoots"` must be set to `"../../node_modules/@types/"`. 
+    
+    In a more typical project, `node_modules` would be a sibling of `tsconfig-aot.json`
+    and `"typeRoots"` would be set to `"node_modules/@types/"`.
+    Edit your `tsconfig-aot.json` to fit your project's file structure.
+
 :marked
   ### Tree Shaking