docs: revert Jade to markdown

Previously, the markdown of some chapters was converted to Jade markup
to support the conditional exclusion of TS prose parts in Dart
chapters. This commit reverts some of that back to clean markdown,
thanks to a few custom directives.

Author: chalin

public/_includes/_scripts-include.jade

@@ -21,6 +21,7 @@ script(src="https://ajax.googleapis.com/ajax/libs/angular_material/1.0.0/angular
 
 <!-- Angular.io Site JS -->
 script(src="/resources/js/site.js")
+script(src="/resources/js/util.js")
 script(src="/resources/js/controllers/app-controller.js")
 script(src="/resources/js/controllers/resources-controller.js")
 script(src="/resources/js/directives/cheatsheet.js")
@@ -32,6 +33,9 @@ script(src="/resources/js/directives/copy.js")
 script(src="/resources/js/directives/code-tabs.js")
 script(src="/resources/js/directives/code-pane.js")
 script(src="/resources/js/directives/code-example.js")
+script(src="/resources/js/directives/if-docs.js")
+script(src="/resources/js/directives/live-example.js")
+script(src="/resources/js/directives/ngio-ex-path.js")
 script(src="/resources/js/directives/scroll-y-offset-element.js")
 
 <!-- GA -->

public/docs/dart/latest/_util-fns.jade

@@ -20,12 +20,14 @@ include ../../../_includes/_util-fns
 - var _indexHtmlDir = 'web';
 - var _mainDir = 'web';
 
+//- Deprecated
 mixin liveExampleLink(linkText, exampleUrlPartName)
   - var text = linkText || 'live example';
   - var ex = exampleUrlPartName || getExampleName();
   - var href = 'http://angular-examples.github.io/' + ex;
   a(href='#{href}' target="_blank")= text
 
+//- Deprecated
 mixin liveExampleLink2(linkText, exampleUrlPartName)
   - var srcText = attributes.srcText || 'view source';
   - var ex = exampleUrlPartName || attributes.example || getExampleName();

public/docs/dart/latest/guide/dependency-injection.jade

@@ -10,21 +10,12 @@ block ctor-syntax
       We also leveraged Dart's constructor syntax for declaring parameters and
       initializing properties simultaneously.
 
-block service-in-its-own-file
-  //- N/A
-
-block one-class-per-file-ts-tradeoffs
-  //- N/A
-
 block injectable-not-always-needed-in-ts
   //- The [Angular 2 Dart Transformer](https://github.com/angular/angular/wiki/Angular-2-Dart-Transformer)
   //- generates static code to replace the use of dart:mirrors. It requires that types be
   //- identified as targets for static code generation. Generally this is achieved
   //- by marking the class as @Injectable (though there are other mechanisms).
 
-block ts-any-decorator-will-do
-  //- N/A
-
 block always-include-paren
   :marked
     Always write `@Injectable()`, not just `@Injectable`.
@@ -43,11 +34,6 @@ block real-logger
       A real implementation would probably use the
       [logging package](https://pub.dartlang.org/packages/logging).
 
-block canonical-provider-expr
-  |  that creates a new instance of the 
-  a(href="../api/core/Provider-class.html") Provider
-  |  class:
-
 block provider-ctor-args
   - var _secondParam = 'named parameter, such as <code>useClass</code>' 
   :marked

public/docs/dart/latest/guide/server-communication.jade

@@ -8,16 +8,9 @@ block includes
   - var _Angular_http_library = 'Dart <a href="' + _httpUrl + '"><b>http</b></a> library'
 
 block demos-list
-  li #[a(href="#http-client") HTTP client: Tour of Heroes]
-  li #[a(href="#cors") JSONP client: Wikipedia to fetch data from a service that does not support CORS] #[b (under development)]
-
-block rxjs-import
-  //- N/A
-
-block http-client
-  
-block system-config-of-http
-  //- N/A
+  :marked
+    - [HTTP client: Tour of Heroes](#http-client)
+    - [JSONP client: Wikipedia to fetch data from a service that does not support CORS (**under development**)](#cors)
 
 block http-providers
   :marked
@@ -50,9 +43,6 @@ block getheroes-and-addhero
     programming in Dart, or the tutorial on 
     [_Asynchronous Programming: Futures_](https://www.dartlang.org/docs/tutorials/futures/).
 
-block rxjs
-  //- N/A
-
 block parse-json
   :marked
     The response data are in JSON string form.
@@ -65,7 +55,7 @@ block error-handling
 block hlc-error-handling
   :marked
     Back in the `HeroListComponent`, we wrapped our call to
-    `#{_priv}heroService.getHeroes()` in a `try` clause. When an exception is
+    `!{_priv}heroService.getHeroes()` in a `try` clause. When an exception is
     caught, the `errorMessage` variable &mdash; which we've bound conditionally in the
     template &mdash; gets assigned to.
 
@@ -75,9 +65,6 @@ block hero-list-comp-add-hero
     awaits for the *service's* asynchronous `addHero()` to return, and when it does,
     the new hero is added to the `heroes` list for presentation to the user.
 
-block promises
-  //- N/A
-
 block wikipedia-jsonp+
   :marked
     Wikipedia offers a modern `CORS` API and a legacy `JSONP` search API.

public/docs/dart/latest/tutorial/index.jade

@@ -1,8 +1,5 @@
 include ../_util-fns
 
 +includeShared('{ts}', 'intro')
-
-p Run the #[+liveExampleLink2('', 'toh-5')].
-
 +includeShared('{ts}', 'main')
 

public/docs/dart/latest/tutorial/toh-pt1.jade

@@ -33,7 +33,8 @@ include ../_util-fns
 
 .callout.is-helpful
   header Source code
-  p Run the #[+liveExampleLink2('', 'toh-1')] for this part.
+  :marked
+    Run the <live-example></live-example> for this part.
 
 :marked
   ## Keep the app compiling and running

public/docs/dart/latest/tutorial/toh-pt2.jade

@@ -6,8 +6,8 @@ include ../_util-fns
   We’ll expand our Tour of Heroes app to display a list of heroes,
   allow the user to select a hero, and display the hero’s details.
 
-p Run the #[+liveExampleLink2('', 'toh-2')] for this part.
-:marked
+  Run the <live-example></live-example> for this part.
+
   Let’s take stock of what we’ll need to display a list of heroes.
   First, we need a list of heroes. We want to display those heroes in the view’s template,
   so we’ll need a way to do that.
@@ -294,8 +294,8 @@ code-example(language="bash").
   * We added the ability to select a hero and show the hero’s details
   * We learned how to use the built-in directives `ngIf` and `ngFor` in a component’s template
 
-p Run the #[+liveExampleLink2('', 'toh-2')] for this part.
-:marked
+  Run the <live-example></live-example> for this part.
+
   ### The Road Ahead
   Our Tour of Heroes has grown, but it’s far from complete.
   We can't put the entire app into a single component.

public/docs/dart/latest/tutorial/toh-pt3.jade

@@ -4,7 +4,7 @@ include ../_util-fns
   Our app is growing.
   Use cases are flowing in for reusing components, passing data to components, and creating more reusable assets. Let's separate the heroes list from the hero details and make the details component reusable.
 
-p Run the #[+liveExampleLink2('', 'toh-3')] for this part.
+  Run the <live-example></live-example> for this part.
 
 .l-main-section
 :marked
@@ -240,7 +240,7 @@ code-example(format=".")
   * We learned to bind a parent component to a child component.
   * We learned to declare the application directives we need in a `directives` list.
 
-p Run the #[+liveExampleLink2('', 'toh-3')] for this part.
+  Run the <live-example></live-example> for this part.
 
 .l-main-section
 :marked

public/docs/dart/latest/tutorial/toh-pt4.jade

@@ -15,7 +15,7 @@ include ../_util-fns
   Because data services are invariably asynchronous,
   we'll finish the chapter with a **!{_Promise}**-based version of the data service.
 
-p Run the #[+liveExampleLink2('', 'toh-4')] for this part.
+  Run the <live-example></live-example> for this part.
 
 .l-main-section
 :marked

public/docs/dart/latest/tutorial/toh-pt5.jade

@@ -18,7 +18,7 @@ figure.image-display
     The [Routing and Navigation](../guide/router.html) chapter covers the router in more detail
     than we will in this tutorial.
 
-p Run the #[+liveExampleLink2('', 'toh-5')] for this part.
+  Run the <live-example></live-example> for this part.
 
 .l-main-section
 :marked
@@ -653,11 +653,10 @@ figure.image-display
 .l-main-section
 :marked
   ## Application structure and code
-p.
-  Review the sample source code in the #[+liveExampleLink2('', 'toh-5')] for this chapter.
+
+  Review the sample source code in the <live-example></live-example> for this chapter.
   Verify that we have the following structure:
 
-:marked
 .filetree
   .file angular2_tour_of_heroes
   .children

public/docs/ts/latest/_util-fns.jade

@@ -4,12 +4,14 @@ include ../../../_includes/_util-fns
 - var _docsFor = 'ts';
 //- Other values match the defaults.
 
+//- Deprecated
 mixin liveExampleLink(linkText, exampleUrlPartName)
   - var text = linkText || 'live example';
   - var ex = exampleUrlPartName || getExampleName();
   - var href = '/resources/live-examples/' + ex + '/ts/plnkr.html';
   a(href='#{href}' target="_blank")= text
 
+//- Deprecated
 mixin liveExampleLink2(linkText, exampleUrlPartName)
   //- In Dart this gives 2 links: to the demo and to the source.
   +liveExampleLink(linkText, exampleUrlPartName)

public/docs/ts/latest/guide/attribute-directives.jade

@@ -11,9 +11,8 @@ block includes
   * [respond to user-initiated events](#respond-to-user)
   * [pass values into the directive using data binding](#bindings)
 
-p Try the #[+liveExampleLink2()].
+  Try the <live-example></live-example>.
 
-:marked
   ## Directives overview
 
   There are three kinds of directives in Angular:

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

@@ -20,7 +20,7 @@ block includes
   * [Appendix 1: Inspecting the generated runtime component styles](#inspect-generated-css)
   * [Appendix 2: Loading Styles with Relative URLs](#relative-urls)
 
-p Run the #[+liveExampleLink2()] of the code shown in this chapter.
+  Run the <live-example></live-example> of the code shown in this chapter.
 
 .l-main-section
 :marked

public/docs/ts/latest/guide/dependency-injection.jade

@@ -17,7 +17,7 @@ block includes
   - [Dependency injection tokens](#dependency-injection-tokens)
   - [Summary](#summary)
 
-p Run the #[+liveExampleLink2()].
+  Run the <live-example></live-example>.
 
 .l-main-section#why-di
 :marked
@@ -427,7 +427,7 @@ block injectable-not-always-needed-in-ts
   fact `InjectableMetadata` #{_decorator}s that
   identify a class as a target for instantiation by an injector.
 
-block ts-any-decorator-will-do
++ifDocsFor('ts')
   .l-sub-section
     :marked
       Injectors use a class's constructor metadata to determine dependent types as
@@ -508,20 +508,25 @@ code-example(format="nocode").
   What matters is that the injector has a provider to go to when it needs a `Logger`.
 
 //- Dart limitation: the provide function isn't const so it cannot be used in an annotation.
-- var __andProvideFn = _docsFor == 'dart' ? '' : 'and <i>provide</i> object literal';
+- var _andProvideFn = _docsFor == 'dart' ? '' : 'and <i>provide</i> object literal';
 #provide
 :marked
-  ### The *Provider* class !{__andProvideFn}
+  ### The *Provider* class !{_andProvideFn}
 
 :marked
   We wrote the `providers` #{_array} like this:
 
 +makeExample('dependency-injection/ts/app/providers.component.ts','providers-1')
 
-p
-  | This is actually a short-hand expression for a provider registration
-  block canonical-provider-expr
-    | &nbsp;using a <i>provider</i> object literal with two properties:
+:marked
+  This is actually a short-hand expression for a provider registration
+  <span if-docs="ts">
+    using a _provider_ object literal with two properties:
+  </span>
+  <span if-docs="dart">
+    that creates a new instance of the
+    [Provider](../api/core/Provider-class.html) class:
+  </span>
 
 +makeExample('dependency-injection/ts/app/providers.component.ts','providers-3')
 
@@ -861,7 +866,7 @@ block dart-map-alternative
     Framework developers may take this approach when they
     must acquire services generically and dynamically.
 
-block one-class-per-file-ts-tradeoffs
++ifDocsFor('ts')
   .l-main-section#one-class-per-file
   :marked
     ## Appendix: Why we recommend one class per file

public/docs/ts/latest/guide/hierarchical-dependency-injection.jade

@@ -13,7 +13,7 @@ block includes
 
   In this chapter we explore these points and write some code.
 
-p Try the #[+liveExampleLink2()].
+  Try the <live-example></live-example>.
 
 .l-main-section
 :marked

public/docs/ts/latest/guide/lifecycle-hooks.jade

@@ -24,7 +24,7 @@ block includes
     * [AfterViewInit and AfterViewChecked](#afterview)
     * [AfterContentInit and AfterContentChecked](#aftercontent)
 
-p Try the #[+liveExampleLink2()].
+  Try the <live-example></live-example>.
 
 a#hooks-overview
 .l-main-section
@@ -195,14 +195,14 @@ a(id="other-lifecycles")
   3rd party libraries might implement their hooks as well in order to give us, the developers, more
   control over how these libraries are used.
 
-a#the-sample
-.l-main-section
-h2 Lifecycle exercises
-p.  
-  The #[+liveExampleLink()]
+.l-main-section#the-sample
+:marked
+  ## Lifecycle exercises
+
+  The <live-example></live-example>
   demonstrates the lifecycle hooks in action through a series of exercises
   presented as components under the control of the root `AppComponent`.
-:marked
+
   They follow a common pattern:  a *parent* component serves as a test rig for 
   a *child* component that illustrates one or more of the lifecycle hook methods.
 

public/docs/ts/latest/guide/pipes.jade

@@ -15,9 +15,9 @@ block includes
   desire many of the same transformations repeatedly, both within and across many applications.
   We almost think of them as styles.
   In fact, we'd like to apply them in our HTML templates as we do styles.
-p.
+
   Introducing Angular pipes, a way to write display-value transformations that we can declare in our HTML!
-  Try the #[+liveExampleLink2()].
+  Try the <live-example></live-example>.
 
 .l-main-section
 :marked
@@ -168,11 +168,10 @@ figure.image-display
     Angular built-in pipes are pre-registered.
     Custom pipes must be registered manually.
 
-p.
-  If we try the #[+liveExampleLink()],
+:marked
+  If we try the <live-example></live-example>,
   we can probe its behavior by changing the value and the optional exponent in the template.
 
-:marked
   ## Power Boost Calculator (extra-credit)
 
   It's not much fun updating the template to test our custom pipe.
@@ -219,10 +218,10 @@ a#change-detection
   Here's the `FlyingHeroesPipe` implementation which follows the pattern for custom pipes we saw earlier.
 +makeExample('pipes/ts/app/flying-heroes.pipe.ts', 'pure', 'app/flying-heroes.pipe.ts')(format='.')
 
-p.
-  When we run the sample now we see odd behavior (try it in the #[+liveExampleLink()]).
-  Every hero we add is a flying hero but none of them are displayed.
 :marked
+  When we run the sample now we see odd behavior (try it in the <live-example></live-example>).
+  Every hero we add is a flying hero but none of them are displayed.
+
   Although we're not getting the behavior we want, Angular isn't broken.
   It's just using a different change detection algorithm &mdash; one that ignores changes to the list or any of its items.
 
@@ -328,11 +327,10 @@ block pure-change
 
   We can derive a `FlyingHeroesImpureComponent` that we derive from the `FlyingHeroesComponent`.
 +makeExample('pipes/ts/app/flying-heroes.component.ts','impure-component','app/flying-heroes.component.ts (FlyingHeroesImpureComponent)')(format='.')
-p.
+:marked
   The only substantive change is the pipe.
-  We can confirm in the #[+liveExampleLink()] that the #[i flying heroes]
-  display updates as we enter new heroes even when we mutate the
-  #[code heroes] #{_array}.
+  We can confirm in the <live-example></live-example> that the _flying heroes_
+  display updates as we enter new heroes even when we mutate the `heroes` #{_array}.
 
 - var _dollar = _docsFor === 'ts' ? '$' : '';
 h3#async-pipe The impure #[i AsyncPipe]