chore(docs): revise makeExcerpt mixin, add makeProjExample mixin

Be more DRY when referencing examples and excerpts. E.g.,
```jade
+makeExcerpt('quickstart/ts/app/app.component.ts', 'import',
'app/app.component.ts (import)')
```
can now be just
```jade
+makeExcerpt('app/app.component.ts', 'import')
```
Defined new mixin for examples named `makeProjExample` using this new
scheme.
The original `makeExample` has been left untouched.

Applied new mixins to quickstart.

closes #1420

Author: chalin

public/_includes/_util-fns.jade

@@ -68,13 +68,43 @@ mixin makeExample(_filePath, region, _title, stylePatterns)
       .example-title #{title}
   code-example(language="#{language}" format="#{format}")
     != styleString(frag, stylePatterns)
-    
-//- Like makeExample, but doesn't show line numbers and
-//- title is appened with `(excerpt)` if it doesn't already
-//- end with a parenthetical remark.
-mixin makeExcerpt(_filePath, region, _title, stylePatterns)
-  - if (_title && !_title.match(/\([\w ]+\)$/)) _title = _title + ' (excerpt)';
-  +makeExample(_filePath, region, _title, stylePatterns)(format='.')
+
+//- Like makeExample, but the first argument is a path that is 
+//- relative to the project root. Unless title is defined, 
+//- the project relative path will be used.
+mixin makeProjExample(projRootRelativePath, region, title, stylePatterns)
+  - var relPath = projRootRelativePath.trim();
+  - var filePath = getExampleName() + '/ts/' + relPath;
+  - if (!title) {
+  -   // Is path like styles.1.css? Then drop the '.1' qualifier:
+  -   var matches = relPath.match(/^(.*)\.\d(\.\w+)$/);
+  -   title = matches ? matches[1] + matches[2] : relPath;
+  - }
+  +makeExample(filePath, region, title, stylePatterns)
+
+//- Like makeExample, but doesn't show line numbers, and the first
+//- argument is a path that is relative to the example project root. 
+//- Unless title is defined, the project relative path will be used.
+//- Title will always end with a phrase in parentheses; if no such
+//- ending is given, then the title will be suffixed with
+//- either "(excerpt)", or "(#{region})" when region is defined.
+mixin makeExcerpt(projRootRelativePath, region, title, stylePatterns)
+  - var relPath = projRootRelativePath.trim();
+  - var filePath = getExampleName() + '/ts/' + relPath;
+  - if (!title) {
+  -   // Is path like styles.1.css? Then drop the '.1' qualifier:
+  -   var matches = relPath.match(/^(.*)\.\d(\.\w+)$/);
+  -   title = matches ? matches[1] + matches[2] : relPath;
+  - }
+  - var excerpt = region || 'excerpt';
+  - if (title && !title.match(/\([\w ]+\)$/)) title = title + ' (' + excerpt + ')';
+  +makeExample(filePath, region, title, stylePatterns)(format='.')
+
+//- Extract the doc example name from `current`.
+- var getExampleName = function() {
+-   var dir = current.path[current.path.length - 1];
+-   return dir == 'latest' ? current.source : dir;
+- };
 
 mixin makeTabs(filePaths, regions, tabNames, stylePatterns)
   - filePaths = strSplit(filePaths);

public/docs/_examples/quickstart/ts/app/main.ts

@@ -1,8 +1,8 @@
 // #docregion
 import { bootstrap }    from '@angular/platform-browser-dynamic';
 
-// #docregion app-component
+// #docregion import
 import { AppComponent } from './app.component';
-// #enddocregion app-component
+// #enddocregion import
 
 bootstrap(AppComponent);

public/docs/ts/latest/quickstart.jade

@@ -208,7 +208,7 @@ p.
   #[b Create the component file]
   #[code #[+adjExPath('app/app.component.ts')]] (in this newly created directory) with the following content:
 
-+makeExample('quickstart/ts/app/app.component.ts', '', 'app/app.component.ts')(format='.')
++makeProjExample('app/app.component.ts')
 
 .l-verbose-section
   :marked
@@ -241,7 +241,7 @@ p.
     Here we import the Angular 2 core so that our component code can have access to
     the `@Component` #{_decorator}.
 
-  +makeExcerpt('quickstart/ts/app/app.component.ts', 'import', 'app/app.component.ts (import)')
+  +makeExcerpt('app/app.component.ts', 'import')
 
   h3#component-decorator @Component #{_decorator}
   +ifDocsFor('ts')
@@ -254,7 +254,7 @@ p.
     component class.
     The metadata tells Angular how to create and use this component.
 
-  +makeExcerpt('quickstart/ts/app/app.component.ts', 'metadata', 'app/app.component.ts (metadata)')(format='.')
+  +makeExcerpt('app/app.component.ts', 'metadata')
 
   block annotation-fields
     :marked
@@ -279,7 +279,7 @@ p.
   :marked
     ### Component class
     At the bottom of the file is an empty, do-nothing class named `AppComponent`.
-  +makeExcerpt('quickstart/ts/app/app.component.ts', 'class', 'app/app.component.ts (class)')
+  +makeExcerpt('app/app.component.ts', 'class')
   :marked
     When we're ready to build a substantive application,
     we can expand this class with properties and application logic.
@@ -297,7 +297,7 @@ block create-main
     Now we need something to tell Angular to load the root component.
     Create the file #[code #[+adjExPath('app/main.ts')]] with the following content:
 
-+makeExample('quickstart/ts/app/main.ts', '', 'app/main.ts')(format='.')
++makeProjExample('app/main.ts')
 
 .l-verbose-section
   :marked
@@ -342,7 +342,7 @@ h2#index Step 4: Add #[code index.html]
   In the *#{_indexHtmlDir}* folder
   create an `index.html` file and paste the following lines into it:
 
-+makeExample('quickstart/ts/index.html', '', 'index.html')(format='.')
++makeProjExample('index.html')
 
 .l-verbose-section
   :marked
@@ -360,7 +360,7 @@ h2#index Step 4: Add #[code index.html]
     :marked
       ### Libraries
       We loaded the following scripts
-    +makeExcerpt('quickstart/ts/index.html', 'libraries', 'index.html')
+    +makeExcerpt('index.html', 'libraries')
     :marked
       We begin with es6-shim which monkey patches the global context (window) with essential features of ES2015 (ES6).
       Next are the polyfills for Angular2, `zone.js` and `reflect-metadata`.
@@ -407,7 +407,7 @@ h2#index Step 4: Add #[code index.html]
 
       Our QuickStart makes such requests when one of its
       application TypeScript files has an import statement like this:
-    +makeExcerpt('quickstart/ts/app/main.ts', 'app-component', 'main.ts (excerpt)')
+    +makeExcerpt('app/main.ts', 'import')
     :marked
       Notice that the module name (after `from`) does not mention a filename extension.
       In the configuration we tell SystemJS to default the extension to `js`, a JavaScript file.
@@ -463,7 +463,7 @@ h2#index Step 4: Add #[code index.html]
   Create a `styles.css` file in the *#{_indexHtmlDir}* folder and start styling, perhaps with the minimal
   styles shown below. For the full set of master styles used by the documentation samples,
   see [styles.css](https://github.com/angular/angular.io/blob/master/public/docs/_examples/styles.css).
-+makeExcerpt('quickstart/ts/styles.1.css', '', 'styles.css')
++makeExcerpt('styles.1.css')
 
 .l-main-section
 h2#build-and-run Step 5: Build and run the app!