[gnome-devel-docs] platform-demos: Edited the Hello World java script tutorial for clarity

[Tiffany Antopolski <antopolski src gnome org>]

commit 4071b8fef60c6dc145664de0a9b0cbcab92655d9
Author: Taryn Fox <jewelfox fursona net>
Date:   Fri Mar 30 02:44:55 2012 -0400

    platform-demos: Edited the Hello World java script tutorial for clarity
    
    The original tutorial had improper grammar and spelling, and left out
    one line of code in the step-by-step examples. It also told the reader
    about making the resulting script executable long before the script was
    finished and saved to disc. These edits are intended to make the tutorial
    qeasier to read and complete, and less likely to stymie the reader.

 platform-demos/C/helloWorld.js.page |   68 ++++++++++++++++++++--------------
 1 files changed, 40 insertions(+), 28 deletions(-)
---
diff --git a/platform-demos/C/helloWorld.js.page b/platform-demos/C/helloWorld.js.page
index afc13cf..8383d13 100644
--- a/platform-demos/C/helloWorld.js.page
+++ b/platform-demos/C/helloWorld.js.page
@@ -11,12 +11,12 @@
       <years>2012</years>
     </credit>
 
-    <desc>Tutorial for a hello world application</desc>
+    <desc>A basic "hello, world" application</desc>
   </info>
   <title>Hello World</title>
 
   <synopsis>
-    <p>In this tutorial we'll construct a small application, Hello World, using JavaScript and GTK+. To do and run all the code examples yourself, you need an editor to write code in, Terminal and GNOME 3 or higher installed into your computer. In this tutorial we'll go through the following parts:</p>
+    <p>In this tutorial we'll construct a small application, Hello World, using JavaScript and GTK+. To write and run all the code examples yourself, you need an editor to write code in, Terminal, and GNOME 3 or higher installed into your computer. In this tutorial we'll go through the following parts:</p>
     <list>
       <item><p> <link xref="#script">Script for running the application</link> </p></item>
       <item><p> <link xref="#imports">Libraries to import</link> </p></item>
@@ -27,74 +27,86 @@
     </list> 
    
   </synopsis>
-    <p>After reading this tutorial, you should see this in your screen:</p>
+    <p>After taking this tutorial, you should see this on your screen:</p>
     <media type="image" mime="image/png" src="media/helloWorldJs.png"/>
     <section id="script">
     <title>Script for running the application</title>
     <code mime="text/javascript" style="numbered"><![CDATA[
-  #!/usr/bin/gjs]]></code>
-    <p>  This line tells how to run the script. It needs to be the first line of the code and it needs to be executable. To get the execution rights go to terminal and run in right folder: chmod +x scriptname. Or you can use the graphical filemanager. Just go to the right folder where your code is, right click you code file, choose properties, click the permissions tab and check the box for allow executing file as a program  
-    </p>
+#!/usr/bin/gjs]]></code>
+    <p>  This needs to be the first line of your script, because it tells GNOME that we'll be using Gjs -- the JavaScript bindings for GNOME -- in order to run it.</p>
   </section>
   
   <section id="imports">
     <title>Libraries to import</title>
     <code mime="text/javascript" style="numbered"><![CDATA[
 var Gtk = imports.gi.Gtk;]]></code>
-    <p>In order to have a working program we need to import a GObject Introspection -library to our use. For working UI, we need Gtk. Gtk is imported in the beginning so we have it in our use everywhere.</p>
+    <p>In order for our script to work with GNOME, we need to import GNOME libraries via GObject Introspection. In this case, we're importing GTK+, the most basic library that contains the graphical widgets used to make GNOME apps.</p>
     </section>
 
    <section id="mainwindow">
     <title>Creating the main window for the application</title> 
     <code mime="text/javascript" style="numbered"><![CDATA[
-// Initialize the gtk
+// Initialize GTK+
 Gtk.init(null, 0);
-//create your window, name it and connect the x to quit function. Remember that window is a taken word
+
+// Create your window, name it, and connect the "click x to quit" function.
+// The word "window" all by itself is reserved for use by GNOME, so we have to
+// call it something different.
 var mywindow = new Gtk.Window({type: Gtk.WindowType.TOPLEVEL});
 mywindow.title = "Hello World!";
 mywindow.connect("destroy", function(){Gtk.main_quit()});
-
-
-mywindow.show();
-//and run it
-Gtk.main();]]></code>
-    <p>After importing Gtk, we need to initialize it. After initializing Gtk we can start building our first window. We do this by creating a variable mywindow and assign it a new Gtk.Window of type TOPLEVEL.</p> <p>After setting up our first window we'll give the window a property called title. Title can be any string you want it to be, to be on the safe side it is good to stick to UTF-8 encoding.</p> <p>The next major improvement to our application is connecting the automatically with the window generated close button with a functionality. The close button has only one reasonable function and that is to close the window. The connecting happens with the method connect. The signal the window is listening to is "destroy", so when the close button is pressed it gives out the signal "destroy". Just listening the signal is not enough, it needs to launch an action. in this case we want it to close the window, so quit he main loop should do the trick. So after "destroy", we'll ad 
 function(){Gtk.main_quit()} to do the actual closing.</p><p>Now we have a window that has a title and a functionality of closing the window. If we would run th application at this stage it wouldnt show anything, so we need to tell our window to show itself with the method show() and we need to also run the whole application in order for anything to happen.</p>
+</code>
+    <p>After importing Gtk, we need to initialize it. After that, we can start building our first window. We do this by creating a variable called mywindow and assigning it a new Gtk.Window of type TOPLEVEL.</p> <p>After setting up our first window we'll give the window a property called title. The title can be any string you want it to be. To be on the safe side, it's best to stick to UTF-8 encoding.</p> <p>The next thing we need to do for our application is connect the close button that's automatically generated along with the window to the close functionality. That happens with the method connect(). When the close button is pressed it gives out the signal "destroy", so in this part we're connecting the "destroy" signal to function(){Gtk.main_quit()}, which does the actual closing.</p><p>Now we have a window that has a title and a working "close" button. Let's add the actual "Hello, world" text.</p>
     </section>
     
     <section id="label">
   <title>Label for the window</title>
   <code mime="text/javascript" style="numbered"><![CDATA[
-//Set some text to your window
+// Add some text to your window
 var label = new Gtk.Label({label: "Hello World"});
-mywindow.add(label);]]></code>
-  <p>Now all the hard parts are done. The only thing we need now is to put something inside our window. A label telling what this is about is the easiest thing to do, so we create a new variable called label and assign it a new Gtk.Lablel. With the label we're using a different method of giving it properties, we are giving the properties inside curly braces {}. The label has to be added to the window in order for the method show() applying also to it. For the future it is good to know that Gtk.Window can only contain one widget at the time. To be able to construct more elaborate programs you need to create a holder widget (Gtk.Box, Gtk.Grid, Gtk.Application and so on) of some kind under the window and then adding all the other widgets to that.</p>
+mywindow.add(label);
+
+// Make the label and the window itself visible to the user
+label.show();
+mywindow.show();
+
+// Let the user run the app
+Gtk.main();]]></code>
+  <p>A text label is one of the GTK+ widgets we can use, on account of having imported the GTK+ library. To use it, we create a new variable called label, and assign it a new Gtk.Label. Then we give it properties inside the curly braces {}. In this case, we're setting the text that the label will hold. Finally, we tell GNOME to show the label and the window containing it to the user, and call Gtk.main() to get the app itself started.</p>
+  <p>For the future, keep in mind that Gtk.Window can only hold one widget at a time. To construct more elaborate programs you need to create a holder widget (Gtk.Box, Gtk.Grid, Gtk.Application, and so on) of some kind inside the window, and then add all the other widgets to it.</p>
   </section>
   <section id="js">
     <title>helloWorld.js</title>
-    <p>This is what the whole program looks like.</p>
+    <p>Here's what the completed program looks like.</p>
       <code mime="text/javascript" style="numbered"><![CDATA[
 #!/usr/bin/gjs
-//The previous line is a hash bang tells how to run the script.
+//The previous line is a hash bang which tells how to run the script.
 // Note that the script has to be executable (run in terminal in the right folder: chmod +x scriptname)
 
-var Gtk = imports.gi.Gtk;
-// Initialize the gtk
+// Initialize GTK+
 Gtk.init(null, 0);
-//create your window, name it and connect the x to quit function. Remember that window is a taken word
+
+// Create your window, name it, and connect the "click x to quit" function.
+// The word "window" all by itself is reserved for use by GNOME, so we have to
+// call it something different.
 var mywindow = new Gtk.Window({type: Gtk.WindowType.TOPLEVEL});
 mywindow.title = "Hello World!";
 mywindow.connect("destroy", function(){Gtk.main_quit()});
-//Set some text to your window
+
+// Add some text to your window
 var label = new Gtk.Label({label: "Hello World"});
 mywindow.add(label);
-//show everything you have done
+
+// Make the label and the window itself visible to the user
 label.show();
 mywindow.show();
-//and run it
+
+// Let the user run the app
 Gtk.main();]]></code>
   </section>
   <section id="terminal">
-  <title>Running the application form Terminal</title>
-  <p>To run this application open Terminal, go to the folder where your application is stored and then run</p> <screen> <output style="prompt">$ </output><input> GJS_PATH=`pwd` gjs helloWorld.js</input> </screen>
+  <title>Running the application from Terminal</title>
+  <p>To run this application, first save it as helloWorld.js. Then open Terminal, go to the folder where your application is stored and run</p> <screen> <output style="prompt">$ </output><input> chmod +x helloWorld.js</input> </screen>
+  <p>This makes your script executable. After that, run</p> <screen> <output style="prompt">$ </output><input> GJS_PATH=`pwd` gjs helloWorld.js</input> </screen>
     </section>
 </page>