docs(dart): update BASICS intro (#1410)

Also copy edited the TS version a bit.

public/_includes/_util-fns.jade

@@ -2,7 +2,7 @@
 
 //- _docsFor: used to identify the language this version of the docs if for;
 //- Should be one of: 'ts', 'dart' or 'js'. Set in lang specific _util-fns file.
-- var _docsFor = ''; 
+- var _docsFor = '';
 
 //- Should match `_docsFor`, but in this case provides the full capitalized
 //- name of the language.
@@ -29,6 +29,10 @@
 - var _Promise = 'Promise';
 - var _Observable = 'Observable';
 
+//- Location of sample code
+- var _liveLink = 'live link';
+
+
 //- Used to prefix identifiers that are private. In Dart this will be '_'.
 - var _priv = '';
 
@@ -46,7 +50,7 @@ mixin adjExPath(path)
     | #{adjustExamplePath(path)}
   else
     | #{path}
-  
+
 mixin includeShared(filePath, region)
   - var newPath = translatePath(filePath, region);
   !=partial(newPath)
@@ -69,8 +73,8 @@ mixin makeExample(_filePath, region, _title, stylePatterns)
   code-example(language="#{language}" format="#{format}")
     != styleString(frag, stylePatterns)
 
-//- Like makeExample, but the first argument is a path that is 
+//- Like makeExample, but the first argument is a path that is
-//- relative to the project root. Unless title is defined, 
+//- 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();
@@ -83,7 +87,7 @@ mixin makeProjExample(projRootRelativePath, region, title, stylePatterns)
   +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. 
+//- 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
@@ -164,7 +168,7 @@ script.
     el.style.display = isVerbose ? 'block' : 'none';
     var el = document.querySelector('button.verbose.on');
     el.style.display = isVerbose ? 'none' : 'block';
-    
+
     CCSStylesheetRuleStyle('main','.l-verbose-section', 'display',
       isVerbose ? 'block' : 'none');
   }

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

@@ -11,13 +11,14 @@ include ../../../_includes/_util-fns
 - var _Lang = 'Dart';
 - var _Promise = 'Future';
 - var _Observable = 'Stream';
+- var _liveLink = 'sample repo';
 
 mixin liveExampleLink(linkText, exampleUrlPartName)
   a(href='https://angular-examples.github.io/#{exampleUrlPartName}' target="_blank")= linkText
 
 mixin liveExampleLink2(linkText, exampleUrlPartName)
   - var liveExampleSourceLinkText = attributes.srcLinkText || 'view source'
-  | #[+liveExampleLink(linkText, exampleUrlPartName)] 
+  | #[+liveExampleLink(linkText, exampleUrlPartName)]
   | (#[a(href='https://github.com/angular-examples/#{exampleUrlPartName}' target="_blank") #{liveExampleSourceLinkText}])
 
 - var adjustExamplePath = function(_path) {
@@ -29,7 +30,7 @@ mixin liveExampleLink2(linkText, exampleUrlPartName)
 -   var baseName = getBaseFileName(path) || path; // TODO: have getBaseFileName() return path
 -   var baseNameNoExt = baseName.substr(0,baseName.length - (extn.length + 1));
 -   var inWebFolder = baseNameNoExt.match(/^(main|index(\.\d)?)$/);
--   // Adjust the folder path, e.g., ts -> dart 
+-   // Adjust the folder path, e.g., ts -> dart
 -   folder = folder.replace(/(^|\/)ts($|\/)/, '$1dart$2').replace(/(^|\/)app($|\/)/, inWebFolder ? '$1web$2' : '$1lib$2');
 -   // Special case not handled above: e.g., index.html -> web/index.html
 -   if(baseNameNoExt.match(/^(index|styles)(\.\d)?$/)) folder = (folder ? folder + '/' : '') + 'web';

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

@@ -1,93 +1,13 @@
-include ../_util-fns
+extends ../../../ts/latest/guide/index.jade
 
-:marked
+block includes
-  This Developers Guide is a practical guide to Angular for experienced programmers who
+  include ../_util-fns
-  are building client applications in HTML and Dart.
-figure
-  img(src="/resources/images/devguide/intro/people.png" alt="Us" align="left" style="width:200px; margin-left:-40px;margin-right:10px" )
-:marked
-  We are on a journey together to understand how Angular works and, more importantly,
-  how to make it work for us. We look at our application requirements and we see problems to solve.
-  <br clear="all">
 
-  * How do we get data onto the screen and handle user interactions?
+block example-links
-  * How do we organize our code into manageable, cohesive chunks of functionality that work together?
+  :marked
-  * What are the essential Angular building blocks and how do they help?
+    Look for a link to that sample near the top of each page.
-  * How do we minimize routine, mechanical coding in favor of declarative, higher level constructs without losing control?
+    For example, the sample repo https://github.com/angular-examples/architecture
-
+    contains the code
-  This chapter begins the journey.
+    for the [Architecture](architecture.html) chapter's sample.
-
+    A running version of that sample is at
-<a id="how-to-read"></a>
+    https://angular-examples.github.io/architecture/.
-:marked
-  # How to read this guide
-  Each chapter of this guide targets an Angular feature,
-  showing how to use it to solve a programming problem.
-
-  All the chapters include code snippets ... snippets we can reuse in our own applications.
-  Typically, these snippets are excerpts from a sample application that accompanies the chapter.
-
-  **All the source files** for each sample app are displayed together at the **end of each chapter.**
-
-  <!-- Although a few early chapters are written as tutorials, most later chapters
-  don't explain how to build the accompanying sample.
-  These non-tutorial chapters highlight key points in code but generally don't include the entire source. -->
-
-  <!-- We don't have to read this guide straight through. -->
-  <!-- The "[Cheat Sheet](cheatsheet.html)" is a handy map to Angular overall. -->
-  <!-- A few early chapters are arranged sequentially and best read together to establish a foundation in Angular.
-  But most chapters stand on their own. We can browse to any of them as our interest or some necessity moves us. -->
-
-  Here is a learning path we might follow:
-
-  1. First, be familiar with Dart programming and with web concepts such as
-  the DOM, HTML, and CSS. Dart tutorials such as
-  [Get Started](https://www.dartlang.org/docs/tutorials/get-started/) and
-  [Connect Dart & HTML](https://www.dartlang.org/docs/tutorials/connect-dart-html/)
-  are a great way to start.
-
-  1. Follow the [QuickStart](../quickstart.html), which is the "Hello, World" of Angular 2.
-  It shows how to set up the libraries and tools needed to write *any* Angular app.
-  It ends with a "proof of life", a running Angular app.
-
-  1. Next, read the Developers Guide chapters in order:
-    <!-- TODO: adjust this text once we have non-introductory/tutorial chapters -->
-    1. The rest of this chapter, especially the Architecture overview
-    1. [Displaying Data](displaying-data.html)
-    1. [User Input](user-input.html)
-    1. [Forms](forms.html)
-    <!-- add dependency injection when it exists -->
-    <!-- add text about template syntax, once that exists -->
-
-  1. Consider hopping over to the [TypeScript docs](/docs/ts/latest/)
-     since they're currently ahead of the Dart docs. (We're working on that!)
-     Especially check out the [Tutorial](/docs/ts/latest/tutorial/) and
-     [Cheat Sheet](/docs/ts/latest/guide/cheatsheet.html), and the guide chapters
-     [Dependency Injection](/docs/ts/latest/guide/dependency-injection.html)
-     and [Template Syntax](/docs/ts/latest/guide/template-syntax.html).
-
-  <!-- Follow your own star from there, wherever it leads. -->
-
-  Don't miss the [Cheat Sheet](cheatsheet.html), a handy map to Angular.
-
-<a id="toh"></a>
-.l-main-section
-:marked
-  # Appendix: The Hero Staffing Agency
-
-  There's a backstory to the <!-- the "Tour of Heroes" and --> samples in this guide.
-
-  The world is full of crises large and small.
-  Fortunately, courageous heroes are prepared to take on every challenge.
-  The shadowy Hero Staffing Agency matches crises to heroes.
-
-  We are contract developers, hired by the Agency to build an application to manage their operations.
-  The Agency maintains a stable of heroes with special powers.
-  Ordinary humans submit crises as job requests. The heroes bid to take the job, and the Agency
-  assigns each job accordingly.
-
-  Our application handles every detail of recruiting, tracking, and job assignment.
-  For example, the [Forms](forms.html) chapter features a screen for
-  entering personal information about heroes:
-
-figure.image-display
-  img(src="/resources/images/devguide/forms/hero-form-1.png" width="400px" alt="Clean Form")

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

@@ -1,4 +1,5 @@
-include ../_util-fns
+block includes
+  include ../_util-fns
 
 // #docregion intro
 - var langName = current.path[1] == 'ts' ? 'TypeScript' : 'JavaScript'
@@ -17,7 +18,7 @@ figure
 <a id="learning-path"></a>
 :marked
   # Organization
-  
+
   The documentation is divided into major thematic sections, each
   a collection of chapters devoted to that theme.
 // #enddocregion how-to-read-1
@@ -26,14 +27,16 @@ figure
 table(width="100%")
   col(width="15%")
   col
+  tr(style=top)
+    td <b>QuickStart</b>
+    td
+      :marked
+        The foundation for every chapter and sample in this documentation.
   tr(style=top)
     td <b>Tutorial</b>
     td
       :marked
-        A step-by-step, immersive approach to learning Angular. 
+        A step-by-step, immersive approach to learning Angular that
-        It begins with the [QuickStart](../quickstart.html), 
-        the foundation for every chapter and sample in this documentation,
-        followed by the [*Tour of Heroes* tutorial](../tutorial) that
         introduces the major features of Angular in an application context.
   tr(style=top)
     td <b>Basics</b>
@@ -44,86 +47,83 @@ table(width="100%")
     td <b>Developer Guide</b>
     td
       :marked
-        In depth analysis of Angular features and development practices.
+        In-depth analysis of Angular features and development practices.
   tr(style=top)
     td <b>Cookbook</b>
     td
       :marked
         Recipes for specific application challenges, mostly code snippets with a minimum of exposition.
   tr(style=top)
-    td <b>Reference</b>
+    td <b>API Reference</b>
     td
       :marked
-        Angular-specific reference material, most notably the [API Guide](../api)
+        Authoritative details about each member of the Angular libraries.
-        with its authoritative details about each member in the Angular libraries.
-  tr(style=top)
-    td <b>Resources</b>
-    td
-      :marked
-        Other places to go for help and information.
 :marked
-  # Learning Path
+  # Learning path
-  We don't have to read the guide straight through.  Most chapters stand on their own. 
+  We don't have to read the guide straight through.  Most chapters stand on their own.
-   
+
-  We recommend a learning path for those new to Angular. 
+  We recommend a learning path for those new to Angular.
   Most of that path runs through the *Basics* section:
 
-  1. Read the [Architecture Overview](architecture.html) to get the big picture.
+  1. Read the [Architecture](architecture.html) overview to get the big picture.
-  
+
-  1. Try the [QuickStart](../quickstart.html). The QuickStart is the "Hello, World" of Angular 2. 
+  1. Try the [QuickStart](../quickstart.html). The QuickStart is the "Hello, World" of Angular 2.
-  It shows us how to setup the libraries and tools we'll need to write *any* Angular app. 
+  It shows us how to set up the libraries and tools we'll need to write *any* Angular app.
-  
+
-  1. Take the *Tour of Heroes* [Tutorial](../tutorial) which picks up from where the QuickStart leaves off 
+  1. Take the *Tour of Heroes* [Tutorial](../tutorial), which picks up from where the QuickStart leaves off
-  and builds a simple data-driven app. 
+  and builds a simple data-driven app.
   Simple, yes, but with the essential characteristics we'd expect of a professional application:
-  a sensible project structure, data binding, master/detail, services, dependency injection, navigation, and remote data access. 
+  a sensible project structure, data binding, master/detail, services, dependency injection, navigation, and remote data access.
-  
+
     Return to the *Basics* section and continue in the suggested order:
-    
+
   1. [Displaying Data](displaying-data.html) explains how to get information on to the screen.
-  
+
   1. [User Input](user-input.html) covers the basics of responding to user behavior.
-  
+
   1. [Forms](forms.html) handle user data entry and validation within the UI.
-  
+
   1. [Dependency Injection](dependency-injection.html) is the way we build large, maintainable applications
-  from small, single purpose parts.
+  from small, single-purpose parts.
-  
+
-  1. [Template Syntax](template-syntax.html) is a comprehensive study of Angular template HTML. 
+  1. [Template Syntax](template-syntax.html) is a comprehensive study of Angular template HTML.
 
   With this foundation, we can read and understand any chapter in the guide.
 // #enddocregion how-to-read-2
 // #docregion the-rest
 :marked
-  # Code Samples
+  # Code samples
-  
+
-  Every chapter includes code snippets that we can reuse in our own applications. 
+  Every chapter includes code snippets that we can reuse in our own applications.
   These snippets are excerpts from a sample application that accompanies the chapter.
-  
+
-  Look for a link to a running version of that sample near the top of each page
+block example-links
-  such as this [live example](/resources/live-examples/architecture/ts/plnkr.html) from the [Architecture](architecture.html) chapter.
+  :marked
-  
+    Look for a link to a running version of that sample near the top of each page,
-  The link launches a browser-based code editor where we can inspect, modify, save, and download the code.
+    such as this [live example](/resources/live-examples/architecture/ts/plnkr.html) from the [Architecture](architecture.html) chapter.
-  
+
-  A few early chapters are written as tutorials and are clearly marked as such. 
+    The link launches a browser-based code editor where we can inspect, modify, save, and download the code.
-  Most chapters are *not* tutorials. 
+
+:marked
+  A few early chapters are written as tutorials and are clearly marked as such.
+  Most chapters are *not* tutorials.
   They highlight key points in code rather than explain each step necessary to build the sample.
-  We can always get the full source by way of the live link.
+  We can always get the full source by way of the #{_liveLink}.
-  
+
-  ## References
+  # Reference pages
-    
+
   The [Cheat Sheet](cheatsheet.html) lists Angular syntax for common scenarios.
-    
+
   The [Glossary](glossary.html) defines terms that Angular developers should know.
-  
+
-  The [API Guide](../api/) is the authority on every public-facing member of the Angular libraries.
+  The [API Reference](../api/) is the authority on every public-facing member of the Angular libraries.
- 
+
   # Feedback
-  
+
   We welcome feedback! Leave a comment by clicking the icon in upper right corner of the banner.
-  
+
-  Post *documentation* issues and pull requests on the 
+  Post *documentation* issues and pull requests on the
   [angular.io](https://github.com/angular/angular.io) github repository.
-  
+
   Post issues with *Angular 2 itself* to the [angular](https://github.com/angular/angular) github repository.
 // #enddocregion the-rest