[tor-commits] [stem/master] Revising 'The Little Relay that Could' tutorial

[atagar at torproject.org]

commit 63bad222dc4de6b7e3c8510e4704ac7af0cabcdb
Author: Damian Johnson <atagar at torproject.org>
Date:   Fri Feb 22 08:55:14 2013 -0800

    Revising 'The Little Relay that Could' tutorial
    
    Changing small bits if the tutorial page and 'hello world' tutorial, adding a
    little detail here and cleaning up the wording there.
---
 docs/tutorial.rst                             |   10 +++--
 docs/tutorial/the_little_relay_that_could.rst |   49 +++++++++++++++----------
 2 files changed, 35 insertions(+), 24 deletions(-)

diff --git a/docs/tutorial.rst b/docs/tutorial.rst
index e5afa11..68572fd 100644
--- a/docs/tutorial.rst
+++ b/docs/tutorial.rst
@@ -15,7 +15,8 @@ Tutorial
      License: Public Domain
      Alternate: https://openclipart.org/detail/174179/miroir-rectangulaire-by-defaz36-174179
 
-Getting started with any new library can be rather daunting, so let's get our feet wet by jumping straight in with a tutorial...
+Getting started with any new library can be rather daunting, so let's get our
+feet wet by jumping straight in with some tutorials...
 
 .. list-table::
    :widths: 1 10
@@ -36,7 +37,8 @@ Getting started with any new library can be rather daunting, so let's get our fe
      - .. image:: /_static/label/mirror_mirror_on_the_wall.png
           :target: tutorial/mirror_mirror_on_the_wall.html
 
-       Getting and acting on information about relays in the Tor network. This
-       walks you through Tor descriptors, both where to get them and writing a
-       small script to tell you the fastest Tor exits.
+       Getting and acting upon information about relays in the Tor network.
+       Relay information is provided through documents called **descriptors**.
+       This walks you through both where to get them and a small script to tell
+       you the fastest Tor exits.
 
diff --git a/docs/tutorial/the_little_relay_that_could.rst b/docs/tutorial/the_little_relay_that_could.rst
index e3f7675..5f85f6e 100644
--- a/docs/tutorial/the_little_relay_that_could.rst
+++ b/docs/tutorial/the_little_relay_that_could.rst
@@ -1,24 +1,32 @@
 The Little Relay that Could
 ---------------------------
 
-Let's say you just set up your very first `Tor relay <https://www.torproject.org/docs/tor-doc-relay.html.en>`_. Thank you! Now you want to write a script that tells you how much it is being used.
+Let's say you just set up your very first `Tor relay
+<https://www.torproject.org/docs/tor-doc-relay.html.en>`_ (thank you!), and now
+you want to write a script that tells you how much it is being used.
 
-First, for any script we write to be able to talk with our relay it'll need to have a control port available. This is a port that's usually only available on localhost and protected by either a password or authentication cookie.
+First, for any script to talk with your relay it will need to have a control
+port available. This is a port that's usually only available on localhost and
+protected by either a **password** or **authentication cookie**.
 
-Look at your `torrc <https://www.torproject.org/docs/faq.html.en#torrc>`_ for the following configuration options...
+Look at your `torrc <https://www.torproject.org/docs/faq.html.en#torrc>`_ for
+the following configuration options...
 
 ::
 
-  # This provides a port for the script we write to talk to. If you set this
-  # then be sure to also have either set the CookieAuthentication flag *or*
-  # provide a HashedControlPassword!
+  # This provides a port for our script to talk with. If you set this then be
+  # sure to also set either CookieAuthentication *or* HashedControlPassword!
+  #
+  # You could also use ControlSocket instead of ControlPort, which provides a
+  # file based socket. You don't need to have authentication if you use
+  # ControlSocket. For this example however we'll use a port.
   
   ControlPort 9051
   
-  # This will make Tor write an authentication cookie file. Anything that can
-  # read that file can connect to Tor. If you're going to run this script with
-  # the same user as Tor then this is the easiest method of authentication to
-  # use.
+  # Setting this will make Tor write an authentication cookie. Anything with
+  # permission to read this file can connect to Tor. If you're going to run
+  # your script with the same user or permission group as Tor then this is the
+  # easiest method of authentication to use.
   
   CookieAuthentication 1
   
@@ -28,24 +36,25 @@ Look at your `torrc <https://www.torproject.org/docs/faq.html.en#torrc>`_ for th
   # % tor --hash-password "my_password"
   # 16:E600ADC1B52C80BB6022A0E999A7734571A451EB6AE50FED489B72E3DF
   #
-  # ... and use that for the HashedControlPassword in our torrc.
+  # ... and use that for the HashedControlPassword in your torrc.
   
   HashedControlPassword 16:E600ADC1B52C80BB6022A0E999A7734571A451EB6AE50FED489B72E3DF
 
-You'll need to restart Tor or issue a SIGHUP for these new settings to take effect. Now let's write a script that tells us how many bytes Tor has sent and received...
+When you change your torrc you'll need to either restart Tor is issue a SIGHUP
+for the new settings to take effect. Now let's write a script that tells us how
+many bytes Tor has sent and received...
 
 ::
 
   from stem.control import Controller
   
-  controller = Controller.from_port(control_port = 9051)
-  controller.authenticate() # provide the password here if you set one
-  
-  bytes_read = controller.get_info("traffic/read")
-  bytes_written = controller.get_info("traffic/written")
-  
-  print "My Tor relay has read %s bytes and written %s." % (bytes_read, bytes_written)
-  controller.close()
+  with Controller.from_port(control_port = 9051) as controller:
+    controller.authenticate() # provide the password here if you set one
+
+    bytes_read = controller.get_info("traffic/read")
+    bytes_written = controller.get_info("traffic/written")
+
+    print "My Tor relay has read %s bytes and written %s." % (bytes_read, bytes_written)
 
 ::