Skip to content

Commit 3e54a1b

Browse files
IgorMinarIgorMinar
committed
doc(tutorial): fixes and improvements from Toni and Ben
1 parent 4b90f65 commit 3e54a1b

File tree

13 files changed

+196
-183
lines changed

13 files changed

+196
-183
lines changed

‎docs/content/tutorial/index.ngdoc

Lines changed: 79 additions & 80 deletions
Original file line numberDiff line numberDiff line change
@@ -2,40 +2,40 @@
22
@name Tutorial
33
@description
44

5-
A great way to get introduced to angular is to work through this tutorial, which walks you through
6-
the construction of an angular web app. The app you will build is a catalog that displays a list of
7-
Android devices, lets you filter the list to see only devices that interest you, and then view
5+
A great way to get introduced to Angular is to work through this tutorial, which walks you through
6+
the construction of an AngularJS web app. The app you will build is a catalog that displays a list
7+
of Android devices, lets you filter the list to see only devices that interest you, and then view
88
details for any device.
99

1010
<img src="img/tutorial/catalog_screen.png">
1111

12-
As you work through this tutorial, you will learn how angular makes browsers smarter — without the
13-
use of extensions or plugins.
12+
Work through the tutorial to see how Angular makes browsers smarter — without the use of extensions
13+
or plug-ins. As you work through the tutorial, you will:
1414

15-
* You will see examples of how to use client-side data binding and dependency injection to build
16-
dynamic views of data that change immediately in response to user actions.
17-
* You will see how angular creates listeners on your data without the need for DOM manipulation.
18-
* You will learn a better, easier way to test your web apps.
19-
* You will learn how to use angular services to make common web tasks, such as getting data into
20-
your app, easier.
15+
* See examples of how to use client-side data binding and dependency injection to build dynamic
16+
views of data that change immediately in response to user actions.
17+
* See how Angular creates listeners on your data without the need for DOM manipulation.
18+
* Learn a better, easier way to test your web apps.
19+
* Learn how to use Angular services to make common web tasks, such as getting data into your app,
20+
easier.
2121

22-
And all of this works in any browser without modifications!
22+
And all of this works in any browser without modification to the browser!
2323

2424
When you finish the tutorial you will be able to:
2525

26-
* Create a dynamic application that works in any browser
27-
* Define the differences between angular and common JavaScript frameworks
28-
* Understand how data binding works in angular
29-
* Use the angular-seed project to quickly boot-strap your own projects
30-
* Create and run tests
31-
* Identify resources for learning more about angular
26+
* Create a dynamic application that works in any browser.
27+
* Define the differences between Angular and common JavaScript frameworks.
28+
* Understand how data binding works in AngularJS.
29+
* Use the angular-seed project to quickly boot-strap your own projects.
30+
* Create and run tests.
31+
* Identify resources for learning more about AngularJS.
3232

33-
The tutorial is will guide you through the process of building a simple application, including
34-
writing and running unit and end-to-end tests, and will allow you to experiment with angular and
35-
the application through experiments suggested at the end of each step.
33+
The tutorial guides you through the entire process of building a simple application, including
34+
writing and running unit and end-to-end tests. Experiments at the end of each step provide
35+
suggestions for you learn more about AngularJS and the application you are building.
3636

3737
You can go through the whole tutorial in a couple of hours or you may want to spend a pleasant day
38-
really digging into it. If you're looking for a shorter introduction to angular, check out the
38+
really digging into it. If you're looking for a shorter introduction to AngularJS, check out the
3939
{@link misc/started Getting Started} document.
4040

4141

@@ -46,11 +46,11 @@ really digging into it. If you're looking for a shorter introduction to angular,
4646

4747
# Working with the code
4848

49-
There are two ways that you can you follow this tutorial and hack on the code, both available on
50-
Mac/Linux or Windows environment. The first work flow uses Git versioning system for source code
51-
management, the second work flow doesn't depend on any source control system and instead uses
52-
scripts to copy snapshots of project files into your workspace (`sandbox`) directory. Choose the
53-
one you prefer:
49+
You can follow this tutorial and hack on the code in either the Mac/Linux or the Windows
50+
environment. Options for working with the tutorial are to use the Git versioning system for source
51+
code management or to use scripts that copy snapshots of project files into your workspace
52+
(`sandbox`) directory. Select one of the tabs below and follow the instructions for setting up your
53+
computer for your preferred option.
5454

5555
<doc:tutorial-instructions show="true">
5656
<doc:tutorial-instruction id="git-mac" title="Git on Mac/Linux">
@@ -59,93 +59,92 @@ one you prefer:
5959
following command in a terminal window:</p>
6060
<pre><code>java -version</code></pre>
6161
<p>You will need Java to run unit tests.</p></li>
62-
<li><p>Get Git from <a href="http://git-scm.com/download">here</a></p>
63-
<p>You can build it from source or use pre-compiled package.</p></li>
62+
<li><p>Download Git from the <a href="http://git-scm.com/download">Git</a> site.</p>
63+
<p>You can build Git from source or use the pre-compiled package.</p></li>
6464
<li><p>Clone the angular-phonecat repository located at <a
65-
href="https://github.com/angular/angular-phonecat">Github</a> by running this command:</p>
65+
href="https://github.com/angular/angular-phonecat">Github</a> by running the following command:</p>
6666
<pre><code>git clone git://github.com/angular/angular-phonecat.git</code></pre>
67-
<p>This will create <code>angular-phonecat</code> directory in current directory.</p></li>
67+
<p>This command creates the <code>angular-phonecat</code> directory in your current
68+
directory.</p></li>
6869
<li><p>Change your current directory to <code>angular-phonecat</code>:</p>
6970
<pre><code>cd angular-phonecat</code></pre>
70-
<p>The tutorial instructions assume you are running all commands from this directory.</p></li>
71-
<li><p>You'll also need an http server running on your system. Mac and Linux machines
72-
typically have Apache preinstalled.</p>
73-
<p>If you don't already have an http server installed, you can <a
71+
<p>The tutorial instructions assume you are running all commands from the angular-phonecat
72+
directory.</p></li>
73+
<li><p>You will need an http server running on your system. Mac and Linux machines typically
74+
have Apache pre-installed, but If you don't already have one installed, you can <a
7475
href="https://github.com/joyent/node/wiki/Installing-Node.js-via-package-manager">install
75-
node.js</a> and use it to run <code>scripts/web-server.js</code> — a simple bundled http
76-
server.</p></li>
76+
node.js</a>. Use <code>node</code> to run <code>scripts/web-server.js</code>, a simple bundled
77+
http server.</p></li>
7778
</ol>
7879
</doc:tutorial-instruction>
7980

8081
<doc:tutorial-instruction id="git-win" title="Git on Windows">
8182
<ol>
82-
<li><p>Verify that you have <a href="http://java.com/">Java</a> installed and that the
83-
<code>java</code> executable is on your <code>PATH</code> by running this command in windows
84-
command line:</p>
83+
<li><p>You will need Java to run unit tests, so run the following command to verify that you
84+
have <a href="http://java.com/">Java</a> installed and that the <code>java</code> executable is on
85+
your <code>PATH</code>.</p>
8586
<pre><code>java -version</code></pre>
86-
<p>You will need Java to run unit tests.</p></li>
87-
<li><p>Install msysGit from <a href="http://git-scm.com/download">here</a></p></li>
87+
<p></p></li>
88+
<li><p>Install msysGit from <a href="http://git-scm.com/download">the Git</a> site.</p></li>
8889
<li><p>Open msysGit bash and clone the angular-phonecat repository located at <a
89-
href="https://github.com/angular/angular-phonecat">Github</a> by running this command:</p>
90+
href="https://github.com/angular/angular-phonecat">Github</a> by running the following command:</p>
9091
<pre><code>git clone git://github.com/angular/angular-phonecat.git</code></pre>
91-
<p>This will create angular-phonecat directory in your current directory.</p></li>
92-
<li><p>Change your current directory to angular-phonecat:</p>
92+
<p>This command creates the angular-phonecat directory in your current directory.</p></li>
93+
<li><p>Change your current directory to angular-phonecat.</p>
9394
<pre><code>cd angular-phonecat</code></pre>
94-
<p>The tutorial instructions assume you are running all commands from this directory.</p>
95+
<p>The tutorial instructions assume you are running all commands from the angular-phonecat
96+
directory.</p>
9597
<p>You should run all <code>git</code> commands from msysGit bash.</p>
96-
<p>Other commands like <code>test-server.bat</code> or <code>test.bat</code> that will be
97-
introduced soon, should be executed from the windows command line.</li>
98-
<li><p>You'll also need an http server running on your system.</p>
99-
<p>If you don't already have an http server installed, you can install <a
100-
href="http://nodejs.org/">node.js</a>. Just download <a
101-
href="http://node-js.prcn.co.cc/">pre-compiled binaries</a>, unzip them and add
102-
<code>nodejs\bin</code> into your <code>PATH</code> and use <code>node</code> to run
103-
<code>scripts\web-server.js</code> — a simple bundled http server.</p></li>
98+
<p>Other commands like <code>test-server.bat</code> or <code>test.bat</code> should be
99+
executed from the Windows command line.</li>
100+
<li><p>You need an http server running on your system. If you don't already have one
101+
installed, you can install <a href="http://nodejs.org/">node.js</a>. Download the <a
102+
href="http://node-js.prcn.co.cc/">pre-compiled binaries</a>, unzip them, and then add
103+
<code>nodejs\bin</code> into your <code>PATH</code>. Use <code>node</code> to run
104+
<code>scripts\web-server.js</code>, a simple, bundled http server.</p></li>
104105
</ol>
105106
</doc:tutorial-instruction>
106107

107108
<doc:tutorial-instruction id="ss-mac" title="Snapshots on Mac/Linux">
108109
<ol>
109-
<li><p>Verify that you have <a href="http://java.com/">Java</a> installed by running the
110-
following command in a terminal window:</p>
110+
<li><p>You need Java to run unit tests, so verify that you have <a
111+
href="http://java.com/">Java</a> installed by running the following command in a terminal
112+
window:</p>
111113
<pre><code>java -version</code></pre>
112-
<p>You will need Java to run unit tests.</p></li>
113-
<li><p>Download the <a href="http://code.angularjs.org/angular-phonecat/">zip archive</a>
114-
with all files and unzip them into [tutorial-dir] directory</p></li>
115-
<li><p>Change your current directory to [tutorial-dir]/sanbox:</p>
114+
<li><p>Download the <a href="http://code.angularjs.org/angular-phonecat/">zip archive</a>
115+
containing all of the files and unzip them into the [tutorial-dir] directory</p>.</li>
116+
<li><p>Change your current directory to [tutorial-dir]/sandbox, as follows:</p>
116117
<pre><code>cd [tutorial-dir]/sandbox</code></pre>
117-
<p>The tutorial instructions assume you are running all commands from this directory.</p></li>
118-
<li><p>You'll also need an http server running on your system. Mac and Linux machines
119-
typically have Apache preinstalled.</p>
120-
<p>If you don't already have an http server installed, you can <a
118+
<p>The tutorial instructions assume you are running all commands from your
119+
<code>sandbox</code> directory.</p></li>
120+
<li><p>You need an http server running on your system and Mac and Linux machines typically
121+
have Apache pre-installed. If you don't have an http server installed, you can <a
121122
href="https://github.com/joyent/node/wiki/Installing-Node.js-via-package-manager">install
122-
node.js</a> and use it to run <code>scripts/web-server.js</code> — a simple bundled http
123+
node.js</a> and use it to run <code>scripts/web-server.js</code>, a simple bundled http
123124
server.</p></li>
124125
</ol>
125126
</doc:tutorial-instruction>
126127

127128
<doc:tutorial-instruction id="ss-win" title="Snapshots on Windows">
128129
<ol>
129130
<li><p>Verify that you have <a href="http://java.com/">Java</a> installed and that the
130-
<code>java</code> executable is on your <code>PATH</code> by running this command in windows
131-
command line:</p>
131+
<code>java</code> executable is on your <code>PATH</code> by running the following command in the
132+
Windows command line:</p>
132133
<pre><code>java -version</code></pre>
133-
<p>You will need Java to run unit tests.</p></li>
134-
<li><p>Download the <a href="http://code.angularjs.org/angular-phonecat/">zip archive</a>
135-
with all files and unzip them into [tutorial-dir] directory</p></li>
136-
<li><p>Change your current directory to [tutorial-dir]/sanbox:</p>
134+
<p>You need Java to run unit tests, so download the <a
135+
href="http://code.angularjs.org/angular-phonecat/">zip archive</a> that contains all of the files
136+
and unzip the files into the [tutorial-dir] directory</p></li>
137+
<li><p>Change your current directory to [tutorial-dir]/sandbox, as follows:</p>
137138
<pre><code>cd [tutorial-dir]/sandbox</code></pre>
138139
<p>The tutorial instructions assume you are running all commands from this directory.</p></li>
139-
<li><p>You'll also need an http server running on your system.</p>
140-
<p>If you don't already have an http server installed, you can install <a
141-
href="http://nodejs.org/">node.js</a>. Just download <a
142-
href="http://node-js.prcn.co.cc/">pre-compiled binaries</a>, unzip them and add
143-
<code>nodejs\bin</code> into your <code>PATH</code> and use <code>node</code> to run
144-
<code>scripts\web-server.js</code> — a simple bundled http server.</p></li>
140+
<li><p>You need an http server running on your system, but if you don't already have one
141+
already installed, you can install <a href="http://nodejs.org/">node.js</a>. Download the <a
142+
href="http://node-js.prcn.co.cc/">pre-compiled binaries</a>, unzip them, and then add
143+
<code>nodejs\bin</code> into your <code>PATH</code>. Use <code>node</code> to run
144+
<code>scripts\web-server.js</code>, a simple bundled http server.</p></li>
145145
</ol>
146146
</doc:tutorial-instruction>
147147
</doc:tutorial-instructions>
148148

149-
For either work flow you'll also need a web browser and your favorite text editor.
150-
151-
Let's get going with {@link step_00 step 0}.
149+
The last thing to do is to make sure your computer has a web browser and a good text editor
150+
installed. Now, let's get going with {@link step_00 step 0}.

‎docs/content/tutorial/step_00.ngdoc

Lines changed: 13 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,8 @@
55
<ul doc:tutorial-nav="0"></ul>
66

77

8-
You are now ready to build the phonecat application. In this step, you will become familiar with
9-
the most important source code files, learn how to start the development servers bundled with
8+
You are now ready to build the Angular phonecat application. In this step, you will become familiar
9+
with the most important source code files, learn how to start the development servers bundled with
1010
angular-seed, and run the application in the browser.
1111

1212

@@ -78,7 +78,7 @@ directory.</li>
7878

7979
<doc:tutorial-instruction id="ss-mac" title="Snapshots on Mac/Linux">
8080
<ol>
81-
<li><p>In angular-phonecat directory, run this command:</p>
81+
<li><p>In the angular-phonecat directory, run this command:</p>
8282
<pre><code>./goto_step.sh 0</code></pre>
8383
<p>This resets your workspace to step 0 of the tutorial app.</p>
8484
<p>You must repeat this for every future step in the tutorial and change the number to
@@ -110,7 +110,7 @@ href="http://localhost:8000/app/index.html">http://localhost:8000/app/index.html
110110

111111
<doc:tutorial-instruction id="ss-win" title="Snapshots on Windows">
112112
<ol>
113-
<li><p>Open windows command line and run this command (in angular-phonecat directory):</p>
113+
<li><p>Open windows command line and run this command (in the angular-phonecat directory):</p>
114114
<pre><code>goto_step.bat 0</code></pre>
115115
<p>This resets your workspace to step 0 of the tutorial app.</p>
116116
<p>You must repeat this for every future step in the tutorial and change the number to
@@ -144,7 +144,7 @@ href="http://localhost:8000/app/index.html">http://localhost:8000/app/index.html
144144
You can now see the page in your browser. It's not very exciting, but that's OK.
145145

146146
The static HTML page that displays "Nothing here yet!" was constructed with the HTML code shown
147-
below. The code contains some key angular elements that we will need going forward.
147+
below. The code contains some key Angular elements that we will need going forward.
148148

149149
__`app/index.html`:__
150150
<pre>
@@ -172,33 +172,33 @@ __`app/index.html`:__
172172

173173
<html xmlns:ng="http://angularjs.org">
174174

175-
This `xmlns` declaration for the `ng` namespace must be specified in all angular applications in
176-
order to make angular work with XHTML and IE versions older than 9 (regardless of whether you are
175+
This `xmlns` declaration for the `ng` namespace must be specified in all Angular applications in
176+
order to make Angular work with XHTML and IE versions older than 9 (regardless of whether you are
177177
using XHTML or HTML).
178178

179-
* angular script tag
179+
* Angular script tag
180180

181181
<script src="lib/angular/angular.js" ng:autobind>
182182

183183
This single line of code is all that is needed to bootstrap an angular application.
184184

185185
The code downloads the `angular.js` script and registers a callback that will be executed by the
186-
browser when the containing HTML page is fully downloaded. When the callback is executed, angular
187-
looks for the {@link api/angular.directive.ng:autobind ng:autobind} attribute. If angular finds
186+
browser when the containing HTML page is fully downloaded. When the callback is executed, Angular
187+
looks for the {@link api/angular.directive.ng:autobind ng:autobind} attribute. If Angular finds
188188
`ng:autobind`, it creates a root scope for the application and associates it with the `<html>`
189189
element of the template:
190190

191191
<img src="img/tutorial/tutorial_00_final.png">
192192

193-
As you will see shortly, everything in angular is evaluated within a scope. We'll learn more
193+
As you will see shortly, everything in Angular is evaluated within a scope. We'll learn more
194194
about this in the next steps.
195195

196196

197197
## What are all these files in my working directory?
198198

199199
Most of the files in your working directory come from the {@link
200200
https://github.com/angular/angular-seed angular-seed project} which is typically used to bootstrap
201-
new angular projects. The seed project includes the latest angular libraries, test libraries,
201+
new Angular projects. The seed project includes the latest Angular libraries, test libraries,
202202
scripts and a simple example app, all pre-configured for developing a typical web app.
203203

204204
For the purposes of this tutorial, we modified the angular-seed with the following changes:
@@ -210,7 +210,7 @@ For the purposes of this tutorial, we modified the angular-seed with the followi
210210

211211
# Summary
212212

213-
Now let's go to step 1 and add some content to the web app.
213+
Now let's go to {@link step_01 step 1} and add some content to the web app.
214214

215215

216216
<ul doc:tutorial-nav="0"></ul>

‎docs/content/tutorial/step_01.ngdoc

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -50,8 +50,8 @@ __`app/index.html`:__
5050

5151
# Summary
5252

53-
This addition to your app uses static HTML to display the list. Now, let's go to step 2 to learn
54-
how to use angular to dynamically generate the same list.
53+
This addition to your app uses static HTML to display the list. Now, let's go to {@link step_02
54+
step 2} to learn how to use angular to dynamically generate the same list.
5555

5656

5757
<ul doc:tutorial-nav="1"></ul>

0 commit comments

Comments
 (0)