Cleanup on some of the ts guide files

naomiblack · naomiblack · commit f4d5d163ac5e · 2015-10-10T03:29:34.000-07:00
diff --git a/public/docs/ts/latest/guide/_data.json b/public/docs/ts/latest/guide/_data.json
@@ -9,7 +9,7 @@
     "title": "Getting Started"
   },
   "toh-pt1": {
-    "title": "Tour of Heros Begins"
+    "title": "Tour of Heroes Begins"
   },
   "displaying-data": {
     "title": "Displaying Data",
diff --git a/public/docs/ts/latest/guide/application-under-test.jade b/public/docs/ts/latest/guide/application-under-test.jade
@@ -3,17 +3,18 @@ include ../../../../_includes/_util-fns
 :markdown
 	We’ll need an Angular application to test, one as simple as possible while having all the angular features we want to test.
 
-	We have such an app that you can download [here](./#). It’s a one-screen variation on the “Tour of Heroes” that should be familiar to you as a reader of this Developers Guide.
+	<!-- TODO We have such an app that you can download [here](./#). -->It’s a one-screen variation on the “Tour of Heroes” that should be familiar to you as a reader of this Developers Guide.
 
 	Our test app displays a list of heroes - all favorites of the user named “Bongo”. It looks like this:
 
 figure.image-display
-	img(src='https://github.com/resources/images/devguide/application-under-test/bongos-heroes.png' style="width:400px;" alt="Bong's Heroes")
+	img(src='https://github.com/resources/images/devguide/application-under-test/bongos-heroes.png'
+	style="width:400px;" alt="Bongo's Heroes")
 
 :markdown
 	At the top is a master list of heroes; at the bottom the detail for the current hero. Click a hero in the list to change the current hero. Change the name in the textbox and that name updates everywhere. The *Update* button modifies the `Hero.name` in an arbitrary way and that change also propagates everywhere on screen. The *Delete* button deletes the hero from the list and a new hero becomes current. *Refresh* clears both the list and detail, then restores the original list of heroes.
 
-	You can see a short video of the app in action [here](./#)
+	<!-- TODO You can see a short video of the app in action [here](./#) -->
 
 	This simple app illustrates a number of Angular features that we’d like to test.
 
@@ -26,8 +27,8 @@ figure.image-display
 	- The `name` textbox illustrates two-way databinding
 	- The update button demonstrates that a programmatic change to the databound model propagates to both component views
 	- The delete button triggers an event that is caught by the parent component
-	- [TBD: need to add a filter and a directive to this sample]
-	- [TBD: need to shoehorn the router in somehow]
+	<!-- TODO - [TBD: need to add a filter and a directive to this sample] -->
+	<!-- TODO - [TBD: need to shoehorn the router in somehow] -->
 
 	We’ll examine the implementation details as we evolve our tests.
 
diff --git a/public/docs/ts/latest/guide/first-app-tests.jade b/public/docs/ts/latest/guide/first-app-tests.jade
@@ -15,8 +15,7 @@ include ../../../../_includes/_util-fns
 
 	- you’ve learned the basics of Angular 2, from this Developers Guide or elsewhere. We won’t re-explain the Angular 2 architecture, its key parts, or the recommended development techniques.
 	  you’ve read the [Jasmine 101](./jasmine-testing-101.html) chapter.
-
-	- you’ve downloaded the [Heroes application we’re about to test](./#).
+	- you’ve downloaded the [Heroes application we’re about to test](./#). <!-- TODO add link -->
 
 	## Create the test-runner HTML
 
@@ -55,9 +54,7 @@ include ../../../../_includes/_util-fns
 pre.prettyprint.lang-bash
 	code npm install jasmine-core --save-dev --save-exact
 
-.alert.is-important
-	:markdown
-		Be sure to install `jasmine-core` , not `jasmine`!
+.alert.is-important Be sure to install <code>jasmine-core</code> , not <code>jasmine</code>!
 
 :markdown
 	Update the Typescript typings aggregation file (`tsd.d.ts`)  with the Jasmine typings file.
@@ -265,7 +262,8 @@ figure.image-display
 	1. import our test files
 	1. tell Jasmine to run the imported tests
 
-	These step are all clearly visible, in exactly that order, in the following lines that replace the `<body>` contents in `unit-tests.html`:
+	These steps are all clearly visible, in exactly that order, in the following lines that
+	replace the `<body>` contents in `unit-tests.html`:
 
 	```
 	<body>
diff --git a/public/docs/ts/latest/guide/gettingStarted.jade b/public/docs/ts/latest/guide/gettingStarted.jade
@@ -146,12 +146,11 @@ include ../../../../_includes/_util-fns
     in this manner for quite some time.
 
     For a number of reasons this isn't a good approach for building an application.
+    <!-- TODO The formatting here is a little weird. Should improve readability. -->
 
     * Transpiling TypeScript in the browser becomes tediously slow when our
-    app grows beyond a few files. We certainly won't do that in production.
-
-      We should learn to compile locally and
-      push the generated JavaScript to the server. We'll need some tools for that.
+    app grows beyond a few files. We certainly won't do that in production. We should learn to
+    compile locally and push the generated JavaScript to the server. We'll need some tools for that.
 
 
     * We are writing TypeScript because we want strong-typing and some information
@@ -164,13 +163,9 @@ include ../../../../_includes/_util-fns
     * Downloading JavaScript libraries from the web is OK for demos but
     it slows our development. Every time our app reloads, it must refetch these libraries.
     Don't count on browser caching.
-    Our debugging and live-reload techniques will bust the browser cache.
-
-      Loading libraries from the web also prevents us from developing our
-      application offline or where connectivity is poor.
-
-      Let's learn to download the libraries to our machine and serve
-      them locally.
+    Our debugging and live-reload techniques will bust the browser cache. Loading libraries
+    from the web also prevents us from developing our application offline or where connectivity is
+    poor. Let's learn to download the libraries to our machine and serve them locally.
 
 
     * We want our development cycle to be as fast and friction-free as possible.
diff --git a/public/docs/ts/latest/guide/testing-an-angular-pipe.jade b/public/docs/ts/latest/guide/testing-an-angular-pipe.jade
@@ -33,9 +33,9 @@ code-example(format="linenums").
 	- test this custom Angular pipe class
 	- load multiple test files in our test harness, using system.js
 
-.alert.is-critical
-	:markdown
-		This chapter assumes familiarity with basic Angular 2 concepts, the tools we introduced in [Getting Started](./gettingStarted.html) and [Tour of Heroes](./#), and earlier chapters of this Unit Testing series.
+.callout.is-helpful
+	header Prior Knowledge
+	p This chapter assumes familiarity with basic Angular 2 concepts, the tools we introduced in <a href="./gettingStarted.html">Getting Started</a> and <a href="./toh-pt1.html">Tour of Heroes</a>, and earlier chapters of this Unit Testing series.
 
 :markdown
 	## Add the Angular library
@@ -49,7 +49,8 @@ figure.image-display
 :markdown
 	If we then opened the browser’s Developer Tools (F12, Ctrl-Shift-I) and looked in the console window, we would see.
 
-	`GET http://127.0.0.1:8080/src/angular2/angular2 404 (Not Found)`
+	`GET http://127.0.0.1:8080/src/angular2/angular2 404 (Not Found)` <!--TODO probably belongs
+	in a code box not as an inline code style -->
 
 	It is missing indeed!
 
diff --git a/public/docs/ts/latest/guide/toh-pt1.jade b/public/docs/ts/latest/guide/toh-pt1.jade
@@ -17,25 +17,26 @@ include ../../../../_includes/_util-fns
 
     We’ll cover just enough of the core fundamentals to get us started and build an app. Since we are covering a lot of ground, we’ll be able to go deeper on topics by following links as we go.
 
-    Selectable List of Heroes
+    **Selectable List of Heroes**
   figure.image-display
     img(src='https://github.com/resources/images/devguide/toh/heroes-list-1.png' alt="Output of heroes list app")
 
   :markdown
-    Hero Details
+    **Hero Details**
   figure.image-display
     img(src='https://github.com/resources/images/devguide/toh/hero-details-1.png' alt="Details of hero in app")
 
   :markdown
     ### **This is How We Roll**
     We’ll be building the Tour of Heroes together, step by step. Along the way we’ll learn many of the core fundamentals of Angular 2 as we construct the application. Each step is motivated by a requirement. Everything has a reason. We’ll motivate the direction the Tour of Heroes takes, and learn how to solve common application needs with Angular 2’s fundamentals.
 
-    ## Getting Started
+    ## Initial App Setup
+    <aside class="is-right">Find the basics of app setup in the Getting Started chapter.</aside>
 
     ### **Creating Tour of Heroes**
-    After following Getting Started, copy the code to a new folder and rename the folder `angular2-tour-of-heroes`
 
-    *Sidenote: Follow the Getting Start guide in the [getting started chapter]*
+    After following [Getting Started](../guide/gettingStarted.html), copy the code to a new folder and rename the folder
+    `angular2-tour-of-heroes`
 
     Our starting app from Getting Started should look like the following structure:
 
@@ -66,13 +67,20 @@ include ../../../../_includes/_util-fns
   :markdown
     This will keep the application running while we continue to build the Tour of Heroes.
 
-    Note: These steps will watch the existing files and recompile and re-run the app when they change. However, if you notice the watchers do not pick up renamed or new files, stop these commands in terminal by typing `CTRL+C` and then re-run both commands.
+    <!--TODO: style this with callout style and set a header-->Note: These steps will watch the
+    existing files and
+    recompile
+    and re-run
+    the app
+    when they
+    change. However, if you notice the watchers do not pick up renamed or new files, stop these commands in terminal by typing `CTRL+C` and then re-run both commands.
 
 .l-main-section
 
   :markdown
     ## Let's Show our Hero
-    We want to show data in our app, so let’s start by creating a title for our Tour of Heroes. We’ll also create a hero and display him.
+    We want to show data in our app, so let’s start by creating a title for our Tour of Heroes.
+    We’ll also create a hero and display her.
 
     ### **Displaying Data**
     We need to add properties in our component to store the title and the hero’s name. Let’s create `title` and  `hero` properties in the component. We’ll set the title to Tour of Heroes and set the hero to Windstorm.
@@ -96,10 +104,11 @@ include ../../../../_includes/_util-fns
 
     The curly braces tell our app to read the `title` and `hero` properties from the component and render them.
 
-    *Sidenote: Learn more about one-way binding in the [data binding chapter]*
+    Learn more about one-way binding in the <!--TODO link-->Data Binding chapter.
 
     ### **Hero Object**
-    Our hero has a name, but we want to him to have more properties. We’ll do this in TypeScript by creating a `Hero` class.
+    Our hero has a name, but we want to her to have more properties. We’ll do this in TypeScript
+    by creating a `Hero` class.
 
     Let’s create the `Hero` class with `id` and `name` properties. We’ll put this in the `app.ts` file for now.
 
@@ -191,7 +200,8 @@ include ../../../../_includes/_util-fns
 
     Let’s fix that next by letting Angular know we want to use the ng-model directive.
 
-    *Sidenote: Learn more about ng-model in the [data binding chapter]*
+    <!-- TODO style with a class and add a link *Sidenote: Learn more about ng-model in the [data
+    binding chapter]* -->
 
     ### **FORM Directives**
     We just used the `ng-model` directive, but we must tell the component which directives we will use in the template. When we know which directives we want to use, we can import them from Angular 2 and tell the component’s view that we want to use them.
@@ -239,19 +249,22 @@ include ../../../../_includes/_util-fns
 
     Angular bundles all the binding directives for forms together into `FORM_DIRECTIVES`. This is all we need to remember to light up our template. Fortunately, we can bundle a collection of directives together in an array, give it a catchy name, and we can plug that array into the `directives` property.
 
-    *Sidenote: Learn more about Angular 2 Forms in the [Forms chapter]*
+    <!-- TODO *Sidenote: Learn more about Angular 2 Forms in the [Forms chapter]* -->
 
     ## Recap
 
     ### **The Road We’ve Travelled**
-    Let’s take stock in what we’ve built.
-
-    > [formatting = undordered list. how?]
-    > Our Tour of Heroes now includes one-way data binding to display a hero by wrapping properties with double curly braces in our template.
-    > || We added two-way data binding so we can change the hero’s name and see those changes throughout all places the hero’s name is bound in the template.
-    > || We built our template in the component’s file using ES2015’s template strings feature.
-    > || We declared that we use the Form directives in our component and view.
-    > || We used the special built-in `ng-model` directive with the `<input>` element to make the hero’s name display in the template.  `ng-model` also helps us propagate any changes we make throughout all places bound to `hero.name` in the template.
-
-    ### **The Road Ahead**
-    Our Tour of Heroes only displays one hero and we really want to display a list of heroes. We also want to allow the user to select a hero and display his details. We’ll learn more about how to retrieve lists, bind them to the template, and allow a user to select it in the next chapter.
+    Let’s take stock of what we’ve built.
+
+    *  Our Tour of Heroes now includes one-way data binding to display a hero by wrapping
+    properties with double curly braces in our template.
+    * We added two-way data binding so we can change the hero’s name and see those changes throughout all places the hero’s name is bound in the template.
+    * We built our template in the component’s file using ES2015’s template strings feature.
+    * We declared that we use the Form directives in our component and view.
+    * We used the special built-in `ng-model` directive with the `<input>` element to make the hero’s name display in the template.  `ng-model` also helps us propagate any changes we make throughout all places bound to `hero.name` in the template.
+
+    <!-- TODO: Add this in when the next chapter exists ### **The Road Ahead**
+    Our Tour of Heroes only displays one hero and we really want to display a list of heroes. We also want to allow the user to select a hero and display their details.  We’ll learn more about
+     how to retrieve lists, bind them to the
+    template, and
+    allow a user to select it in the next chapter. -->
diff --git a/public/docs/ts/latest/guide/unit-testing-01.jade b/public/docs/ts/latest/guide/unit-testing-01.jade
@@ -64,6 +64,7 @@ figure.image-display
   * when to mock and how
 
   ## Unit Testing Chapters
+  <!-- TODO This toc feels out of place here -->
 
   Here is what we’ll learn in the unit testing chapters.
 
@@ -111,9 +112,8 @@ figure.image-display
   It’s a big agenda. Fortunately, you can learn a little bit at a time and put each lesson to use.
 
 .callout.is-helpful
-  p These Unit Testing chapters build upon each other. We recommend reading them in order. <br/>We assume familiarity with basic Angular 2 concepts and the tools we introduced in
-  <a href="./gettingStarted.html">Getting Started</a> and
-  <a href="./toh-pt1.html">Tour of Heroes</a> such as `npm`, `gulp`, and `live-server`.
+  header How to Use This Guide
+  p The three Unit Testing chapters build upon each other. We recommend reading them in order. We're also assuming that you're already comfortable with basic Angular 2 concepts and the tools we introduced in <a href="./gettingStarted.html">Getting Started</a> and <a href="./toh-pt1.html">Tour of Heroes</a> such as <code>npm</code>, <code>gulp</code>, and <code>live-server</code>.
 
 :markdown
   Let’s get started!
