Style and clarity edits to How jQuery Works article

evangoer · ajpiano · commit c46fce3a5e4a · 2013-01-10T01:04:35.000-05:00
diff --git a/page/about-jquery/how-jquery-works.md b/page/about-jquery/how-jquery-works.md
@@ -5,8 +5,8 @@ level: beginner
 ### jQuery: The Basics
 
 This is a basic tutorial, designed to help you get started using jQuery. If you
-don't have a test page setup yet, start by creating a new HTML page with the
-following contents:
+don't have a test page setup yet, start by creating the following HTML page: 
+
 ```
 <!doctype html>
 <html>
@@ -18,33 +18,32 @@ following contents:
     <a href="http://jquery.com/">jQuery</a>
     <script src="jquery.js"></script>
     <script>
-      var foo = "bar";
+      // Your code goes here
     </script>
   </body>
 </html>
 ```
 
-Edit the `src` attribute in the script tag to point to your copy of jquery.js.
-For example, if jquery.js is in the same directory as your HTML file, you
-can use:
-```
-  <script src="jquery.js"></script>
-```
-
-Download a copy of jQuery from the [Downloading jQuery](http://jquery.com/download/) page.
+The `src` attribute in the `<script>` element must point to a copy of jQuery.
+Download a copy of jQuery from the [Downloading jQuery](http://jquery.com/download/) page
+and store the `jquery.js` file in the same directory as your HTML file.
 
 ### Launching Code on Document Ready
-The first thing that most Javascript programmers end up doing is adding some code to their program, similar to this:
+
+To ensure that their code runs after the browser finishes loading the document, 
+many JavaScript programmers wrap their code in an `onload` function:
+
 ```
 window.onload = function() {
 
   alert("welcome");
 
 }
 ```
-Inside of which is the code that you want to run right when the page is loaded. Problematically, however, the Javascript code isn't run until all images are finished downloading (this includes banner ads). The reason for using `window.onload` in the first place is that the HTML 'document' isn't finished loading yet, when you first try to run your code.
 
-To circumvent both problems, jQuery has a simple statement that checks the `document` and waits until it's ready to be manipulated, known as the [ ready event ](http://api.jquery.com/ready):
+Unfortunately, the code doesn't run until all images are finished downloading, including banner ads.
+To run code as soon as the `document` is ready to be manipulated, jQuery has a statement 
+known as the [ ready event ](http://api.jquery.com/ready):
 
 ```
 $( document ).ready( function() {
@@ -54,7 +53,7 @@ $( document ).ready( function() {
 });
 ```
 
-Inside the ready event, add a click handler to the link:
+For example, inside the `ready` event, you can add a click handler to the link:
 
 ```
 $( document ).ready(function() {
@@ -67,9 +66,13 @@ $( document ).ready(function() {
 
 });
 ```
-Save your HTML file and reload the test page in your browser. Clicking the link on the page should make a browser's alert pop-up, before leaving to go to the main jQuery page.
 
-For click and most other [events](http://api.jquery.com/category/events/), you can prevent the default behaviour - here, following the link to jquery.com - by calling event.preventDefault() in the event handler:
+Save your HTML file and reload the test page in your browser. 
+Clicking the link should now first display an alert pop-up, 
+then continue with the default behavior of navigating to http://jquery.com.
+
+For `click` and most other [events](http://api.jquery.com/category/events/), 
+you can prevent the default behavior by calling `event.preventDefault()` in the event handler:
 
 ```
 $( document ).ready(function() {
@@ -87,49 +90,47 @@ $( document ).ready(function() {
 
 ### Complete Example
 
-The following is an example of what the complete HTML file might look like if
-you were to use the script in your own file. Note that it links to Google's
-[CDN](http://code.google.com/apis/libraries/) to load the jQuery core file.
-Also, while the custom script is included in the `<head>`, it is generally
-preferable to place it in a separate file and refer to that file with the script
-element's `src` attribute.
+The following example illustrates the click handling code discussed above,
+embedded directly in the HTML `<body>`. Note that in practice,
+it is usually better to place your code in a separate JS file 
+and load it on the page with a `<script>` element's `src` attribute.
 
 ```
 <!doctype html>
-<html lang="en">
-<head>
-  <meta charset="utf-8">
-  <title>jQuery demo</title>
-</head>
-<body>
-  <a href="http://jquery.com/">jQuery</a>
-  <script src="http://ajax.googleapis.com/ajax/libs/jquery/1.5/jquery.min.js"></script>
-  <script>
+<html>
+  <head>
+    <meta charset="utf-8">
+    <title>Demo</title>
+  </head>
+  <body>
+    <a href="http://jquery.com/">jQuery</a>
+    <script src="jquery.js"></script>
+    <script>
 
-    $( document ).ready(function() {
+      $( document ).ready(function() {
 
-      $("a").click(function( event ) {
+        $("a").click(function( event ) {
 
-        alert("The link will no longer take you to jquery.com");
+          alert("The link will no longer take you to jquery.com");
 
-        event.preventDefault();
+          event.preventDefault();
 
-      });
+        });
 
-    });
+      });
 
-  </script>
-</body>
+    </script>
+  </body>
 </html>
 ```
 
 ### Adding and Removing an HTML Class
 
-**Important:** *The remaining jQuery examples will need to be placed inside the ready event so that they are executed when the document is ready to be worked on.*
+**Important:** *You must place the remaining jQuery examples inside the `ready` event so that your code executes when the document is ready to be worked on.*
 
-Another common task is adding (or removing) a `class`.
+Another common task is adding or removing a `class`.
 
-First, add some style information into the `head` of the document, like this:
+First, add some style information into the `<head>` of the document, like this:
 
 ```
 <style>
@@ -139,25 +140,25 @@ First, add some style information into the `head` of the document, like this:
 </style>
 ```
 
-Next, add the [addClass](http://api.jquery.com/addClass) call to the script:
+Next, add the [addClass()](http://api.jquery.com/addClass) call to the script:
 
 ```
 $("a").addClass("test");
 ```
 
-All `a` elements will now be bold.
+All `a` elements are now bold.
 
-To remove the `class`, use [removeClass](http://api.jquery.com/removeClass):
+To remove an existing `class`, use [removeClass()](http://api.jquery.com/removeClass):
 
 ```
 $("a").removeClass("test");
 ```
 
 ### Special Effects
 
-In jQuery, a couple of handy [effects](http://api.jquery.com/category/effects/)
-are provided, to really make web sites stand out. For example,
-change the click you added earlier to the following:
+jQuery also provides some handy [effects](http://api.jquery.com/category/effects/)
+to help you make your web sites stand out.
+For example, if you create a click handler of:
 
 ```
 $("a").click(function( event ){
@@ -169,50 +170,50 @@ $("a").click(function( event ){
 });
 ```
 
-Now, the link should slowly disappear when clicked.
+then the link slowly disappears when clicked.
 
 ## Callbacks and Functions
 
-A callback is a function that is passed as an argument to another function and
-is executed after its parent function has completed. The special thing about a
-callback is that functions that appear after the "parent" can execute before
-the callback executes.  Another important thing to know is how to properly pass
-the callback.
+Unlike many other programming languages, JavaScript enables you to freely pass functions around to be executed at a later time.
+A *callback* is a function that is passed as an argument to another function and
+is executed after its parent function has completed. Callbacks are special because
+they patiently wait to execute until their parent finishes.
+Meanwhile, the browser can be executing other functions or doing all sorts of other work. 
+
+To use callbacks, it is important to know how to pass them into their parent function.
 
 ### Callback *without* Arguments
 
-Pass callbacks with no arguments like this:
+If a callback has no arguments, you can pass it in like this:
 
 ```
 $.get( "myhtmlpage.html", myCallBack );
 ```
 
-**Note** that the second parameter here is simply the function name (but *not* as a string and without parentheses). Functions in Javascript are 'First class citizens' and can be passed around like variable references and executed at a later time.
+When [$.get](http://api.jquery.com/jQuery.get/) finishes getting the page `myhtmlpage.html`, it executes the `myCallBack` function.
+**Note** that the second parameter here is simply the function name (but *not* as a string and without parentheses).
 
 ### Callback *with* Arguments
 
-Executing callbacks with arguments can be tricky. The below example illustrates how to think about callbacks with arguments:
+Executing callbacks with arguments can be tricky. 
 
 #### Wrong
-The Wrong Way (will ***not*** work!)
+This code example will ***not*** work:
 
 ```
 $.get( "myhtmlpage.html", myCallBack(param1, param2) );
 ```
 
-
-This will not work because it calls `myCallBack( param1, param2 )` and then passes the return value as the second parameter to [$.get()](http://api.jquery.com/jQuery.get/).
+The reason this fails is that the code executes `myCallBack( param1, param2 )` immediately 
+and then passes the myCallBack's *return value* as the second parameter to `$.get`.
+We actually want to pass in `myCallBack` the function, not `myCallBack`'s return value
+(which might or might not be a function).  So, how to pass in `myCallBack` *and* include its arguments?
 
 #### Right
 
-The problem with the above example is that `myCallBack( param1, param2 )` is
-evaluated before being passed as a function. Javascript (and by extension, jQuery)
-expects a function pointer in cases like these, e.g., `setTimeout( function() {}, 100)`.
-
-In the example below, an anonymous function is created (just a block of
-statements) and is registered as the callback function.  Note the use of
-`function() {`.  The anonymous function does exactly one thing:  calls
-`myCallBack`, with the values of `param1` and `param2` from the outer scope.
+To defer executing `myCallBack` with its parameters, you can use an anonymous function as a wrapper.
+Note the use of `function() {`.  The anonymous function does exactly one thing:  calls
+`myCallBack`, with the values of `param1` and `param2`. 
 
 ```
  $.get( "myhtmlpage.html", function() {
@@ -222,4 +223,5 @@ statements) and is registered as the callback function.  Note the use of
  });
 ```
 
-`param1` and `param2` are evaluated as a callback when the `$.get` is done getting the page.
+When `$.get` finishes getting the page `myhtmlpage.html`, it executes the anonymous function,
+which executes `myCallBack( param1, param2 )`. 
