docs(typings): add typings.d.ts for module.id and __moduleName; update docs

closes #1355 and #1312

public/docs/_examples/.gitignore

@@ -20,7 +20,7 @@ _test-output
 _temp
 **/ts/**/*.js
 **/ts-snippets/**/*.js
-**/ts/**/*.d.ts
+*.d.ts
 
 !**/*e2e-spec.js
 !systemjs.config.1.js

public/docs/_examples/quickstart/ts/typings.d.1.ts

@@ -0,0 +1,14 @@
+// #docregion
+/**
+ * Declares the 'commonjs' format module object that identifies the "module id" for the current module.
+ * Set a component's `moduleId` metadata property to `module.id` for module-relative urls
+ * when the generated module format is 'commonjs'.
+ */
+declare var module: {id: string};
+
+/**
+ * Declares the 'system' format string that identifies the "module id" for the current module.
+ * Set a component's `moduleId` metadata property to `__moduleName` for module-relative urls
+ * when the generated module format is 'system'.
+ */
+declare var __moduleName: string;

public/docs/_examples/typings/typings.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Declares the 'commonjs' format module object that identifies the "module id" for the current module.
+ * Set a component's `moduleId` metadata property to `module.id` for module-relative urls
+ * when the generated module format is 'commonjs'.
+ */
+declare var module: {id: string};
+
+/**
+ * Declares the 'system' format string that identifies the "module id" for the current module.
+ * Set a component's `moduleId` metadata property to `__moduleName` for module-relative urls
+ * when the generated module format is 'system'.
+ */
+declare var __moduleName: string;

public/docs/ts/latest/guide/component-styles.jade

@@ -345,16 +345,18 @@ block module-id
 
     Our challenge is to calculate the base path with minimal effort. 
     If it's too hard, we shouldn't bother; we should just write the full path to the root and move on.
+    Fortunately, *certain* module loaders make it relatively easy to find the base path.
 
-    Fortunately, *certain* module loaders make it easy.
-    SystemJS (starting in v.0.19.19) sets a special `__moduleName` variable to the URL of the component file.
+    SystemJS (starting in v.0.19.19) sets a *semi-global* variable to the URL of the component file.
+    That makes it trivial to set the component metadata `moduleId` property to the component's URL 
+    and let Angular determine the module-relative paths for style and template URLs from there.
     
-  .alert.is-important
-    :marked
-      Caution: we currently regard the *__moduleName* feature as experimental.
+    The name of the *semi-global* variable depends upon whether we told TypeScript to transpile to
+    'system' or 'commonjs' format (see the `module` option in the
+    [TypeScript compiler documentation](http://www.typescriptlang.org/docs/handbook/compiler-options.html)).
+    The variables are `__moduleName` and `module.id` respectively.
     
-  :marked
-    Now it's trivial to set the `moduleId` to the `__moduleName` and write module-relative paths for style and template URLs.
+    Here's an example in which we set the metadata `moduleId` with one of these variables.
 
   +makeExample('component-styles/ts/app/quest-summary.component.ts','', 'app/quest-summary.component.ts')
 

public/docs/ts/latest/guide/typescript-configuration.jade

@@ -11,6 +11,9 @@ include ../_util-fns
   This chapter covers some aspects of TypeScript configuration and the TypeScript environment
   that are important to Angular developers.
   
+  * [tsconfig.json](#tsconfig) - TypeScript compiler configuration.
+  * [typings](#typings) - TypesScript declaration files.
+
 a(id="tsconfig")
 .l-main-section
 :marked
@@ -77,7 +80,7 @@ a(id="typings")
   
   **We need do nothing to get *typings* files for library packages which include *d.ts* files — as all Angular packages do.**
   
-  ### Manual typings
+  ### Installable typings files
   Sadly, many libraries — jQuery, Jasmine, and Lodash among them — do *not* include `d.ts` files in their npm packages.
   Fortunately, either their authors or community contributors have created separate *d.ts* files for these libraries and 
   published them in well-known locations.
@@ -88,8 +91,8 @@ a(id="typings")
   to run that tool automatically after *npm* installation completes.
 +makeJson('quickstart/ts/package.1.json', {paths: 'scripts.postinstall'}, 'package.json (postinstall)')(format=".")
 :marked
-  This *typings* tool command installs the *d.ts* files that we identify in a `typings.json` file 
-  such as this one from the [QuickStart](../quickstart.html):
+  This *typings* tool command installs the *d.ts* files that we identify in a `typings.json` file into the **typings** folder.
+  We created a `typings.json` file in the [QuickStart](../quickstart.html):
 +makeJson('quickstart/ts/typings.1.json', null, 'typings.json')(format=".")
 :marked
   We identified two *typings* file in the QuickStart, the *d.ts* file for 
@@ -101,9 +104,14 @@ a(id="typings")
   and most of us would be disappointed if typical ES2015 features didn't work out-of-the-box
   or we didn't support testing.
 
-  We can also run the *typings* tool ourselves. The following command lists the locally installed typings files.
+  We can also run the *typings* tool ourselves.
+  The following command (re)installs the typings files, as is sometimes necessary when the `postInstall` hook fails to do so.
 code-example(format="").
-  npm run typings -- list
+  npm run typings install
+:marked
+  This command lists the installed typings files:
+code-example(format="").
+  npm run typings list
 :marked
   The following command installs the typings file for the Jasmine test library and updates the `typings.config` 
   so we that we get it automatically the next time.
@@ -116,7 +124,18 @@ code-example(format="").
     
     Learn about the features of the *typings* tool at its [site on github](https://github.com/typings/typings/blob/master/README.md).
 :marked
-  #### Typing file collisions
+  ### *typings.d.ts*
+  In the [QuickStart](../quickstart.html) we added a custom `typings.d.ts` file to the *typings* folder.
++makeExample('quickstart/ts/typings.d.1.ts', null, 'typings/typings.d.ts')(format=".")
+:marked
+  The `typings.d.ts` file is the place to declare so-called *ambient* objects that will be globally available at runtime.
+  We only need it when there is *no typings file* to declare it for us.
+  
+  This example declares objects that we need in order to tell Angular how to load templates and styles with [module-relative URLs](component-styles.html#!#relative-urls).
+  A module loader creates one or the other object dynamically as it loads a module.
+  These semi-globals are not described in any other `d.ts` file at this time so we have to declare them ourselves.
+  
+  ### Typing file collisions
   
   The TypeScript compiler does not tolerate redefinition of a type. For example, it throws an error if it's given two definitions for
   the `Promise` type.
@@ -145,6 +164,7 @@ code-example(format="").
   .children
      .file browser.d.ts
      .file main.d.ts
+     .file typings.d.ts
 :marked
   The `es6-shim` typings are duplicated and the `browser.d.ts` and `main.d.ts` have overlapping content.
   

public/docs/ts/latest/quickstart.jade

@@ -85,7 +85,9 @@ a(id="typings")
 :marked
   Add a **typings.json** file to the project folder and copy/paste the following:
 +makeJson('quickstart/ts/typings.1.json', null, 'typings.json')(format=".")
-
+:marked
+  Add a **typings** folder to the project folder and then add the following file to that *typings* folder:
++makeExample('quickstart/ts/typings.d.1.ts', null, 'typings/typings.d.ts')(format=".")
 .l-verbose-section
   :marked
     Many JavaScript libraries extend the JavaScript environment with features and syntax
@@ -130,7 +132,7 @@ a(id="package-json")
     * `npm run lite` - runs the <a href="https://www.npmjs.com/package/lite-server" target="_blank">lite-server</a>, 
     a light-weight, static file server with excellent support for Angular apps that use routing
     
-    * `npm run typings` - runs the [*typings* tool](#typings)
+    * `npm run typings` - runs the [*typings* tool](#typings) separately
     
     * `npm run postinstall` - called by *npm* automatically *after* it successfully completes package installation.
     This script installs the [TypeScript definition files](#typings) defined in `typings.json`