--- a/docs/tutorial.rst	Sun Jul 21 14:30:12 2013 -0500
+++ b/docs/tutorial.rst	Tue Jul 23 20:18:05 2013 -0500
@@ -11,7 +11,7 @@
 detailed the numerous wheel pin and lug settings that needed to be made for
 a given day. Because there are so many settings, the ``m209`` utility allows
 users to store key lists in a key file for convenience. So let us first create
-a key file that hold 30 key lists::
+a key file that holds 30 key lists::
 
    $ m209 keygen -n 30
 
@@ -38,17 +38,18 @@
 .. NOTE:: 
    If you are following along at home, you'll probably get different
    output than what is shown here. This is because the key lists are generated
-   at random, and it is very unlikely that your key list matches mine!
+   at random, and it is very unlikely that your key list will match mine!
 
 Here we can see that the first key list in our file has the indicator ``AB``
 (shown in square brackets), and we can see the settings for the lugs and six
-wheels. The notation is explained later. Also included is a so-called check
-string. Because there are so many settings, it is quite error-prone to set up
-an M-209. This check string allows the operator to verify their work.  After
-configuring the M-209 with the given settings, the operator can set the six key
-wheels to ``AAAAAA``, then encipher the letter ``A`` 26 times. If the message
-that appears on the paper tape matches the check string, the operator knows the
-machine is set up correctly for the day.
+wheels. This notation is explained later (see :ref:`key-list-file-format-label`).
+Also included is a so-called check string. Because there are so many settings,
+it is quite error-prone to set up an M-209. This check string allows the
+operator to verify their work.  After configuring the M-209 with the given
+settings, the operator can set the six key wheels to ``AAAAAA``, then encipher
+the letter ``A`` 26 times. If the message that appears on the paper tape
+matches the check string, the operator knows the machine is set up correctly
+for the day.
 
 After the key list ``AB``, the key list ``AK`` starts, and so on for all 30 key
 lists.
@@ -57,7 +58,7 @@
 ``m209`` utility has many options to let you have fine control over the various
 encryption parameters. These are explained in detail later. If you omit these
 parameters they are simply chosen at random. Here is the simplest example of
-encryping a message::
+encrypting a message::
 
    $ m209 encrypt -t "THE PIZZA HAS ARRIVED STOP NO SIGN OF ENEMY FORCES STOP"
    IIPDU FHLMB LASGD KTLDO OSRMZ PWGEB HYMCB IKSPT IUEPF FUHEO NQTWI VTDPC GSPQX IIPDU FHLMB
@@ -66,13 +67,14 @@
 ``m209keys.cfg`` was used. Since we did not specify a key list indicator, one
 was chosen randomly from the key file. Other encryption parameters, explained
 later, were also randomly chosen. Next, the message given on the command-line
-was encrypted using the standard US Army procedure described in the references.
-This resulted in the encrypted message, which is displayed in 5-letter groups.
-Notice that the first and last 2 groups are identical. These are special
-indicators that tell the receiver how to decrypt the message. In particular
-note that the last 2 letters in the second and last groups are ``MB``. This is
-the key list indicator and tells the receiver what key list was used. The
-remaining groups in the middle make up the encrypted message.
+was encrypted using the standard US Army procedure described in
+:ref:`references-label` (see [5] and [7]). This resulted in the encrypted
+message, which is displayed in 5-letter groups.  Notice that the first and last
+2 groups are identical. These are special indicators that tell the receiver how
+to decrypt the message. In particular note that the last 2 letters in the
+second and last groups are ``MB``. This is the key list indicator and tells
+the receiver what key list was used. The remaining groups in the middle make
+up the encrypted message.
 
 Astute M-209 enthusiasts will note that our message included spaces. Actual
 M-209 units only allow the input of the letters ``A`` through ``Z``. Whenever
@@ -98,9 +100,9 @@
 an actual M-209 operates. Recall that an operator must substitute a letter
 ``Z`` whenever a space is needed. The M-209 helpfully replaces the letter ``Z``
 in the decrypt output with a space as an aid to the operator. As a side effect,
-legitimate uses of the letter ``Z`` are blanked out. But usually it is clear
-from context what has happened, and the operator has to put them back into the
-message before passing it up the chain of command.
+legitimate uses of the letter ``Z`` are blanked out. Usually it is clear from
+context what has happened, and the operator has to put the ``Z``'s back into
+the message before passing it up the chain of command.
 
 It may also happen that the original message did not fit perfectly into an even
 number of 5-letter groups. In that case the encrypted message would be padded
@@ -110,16 +112,16 @@
 not exhibit this behavior.
 
 This is all you need to know to start creating your own M-209 messages! For
-more details, consult the command-line ``m209`` documentation.
+more details, consult the :doc:`commandline`.
 
 Library Tutorial
 ----------------
 
 Here is one way to perform the encrypt and decrypt operations from the
-command-line tutorial, above. In order to produce the same output, we explicity
+command-line tutorial, above. In order to produce the same output, we explicitly
 specify the encryption parameters: the key list, the external message
-indicator, and the system indicator. These parameters are explained in the
-reference documentation.
+indicator, and the system indicator. These parameters are explained in
+:ref:`references-label` [5] & [7].
 
 .. literalinclude:: ../examples/encrypt.py
 
@@ -127,14 +129,15 @@
 
    IIPDU FHLMB LASGD KTLDO OSRMZ PWGEB HYMCB IKSPT IUEPF FUHEO NQTWI VTDPC GSPQX IIPDU FHLMB
 
-A decrypt is just a bit more complicated. After constructing a ``StdProcedure``
-object, you hand it the encrypted message to analyze. The procedure object
-examines the groups in the message and extracts all the indicators. These are
-returned as a ``DecryptParams`` named tuple which indicates, amongst other
-things, what key list is required. It is then up to you to obtain this key list
-somehow. Here we use the ``read_key_list()`` function to do so. After
-installing the key list into the procedure object, you can finally call
-``decrypt()``:
+A decrypt is just a bit more complicated. After constructing
+a :class:`~m209.procedure.StdProcedure` object, you hand it the encrypted
+message to analyze. The procedure object examines the groups in the message and
+extracts all the indicators. These are returned as a ``DecryptParams`` named
+tuple which indicates, amongst other things, what key list is required. It is
+then up to you to obtain this key list somehow. Here we use the
+:func:`~m209.keylist.config.read_key_list` function to do so. After installing
+the key list into the procedure object with :meth:`~.StdProcedure.set_key_list`,
+you can finally call :meth:`~.StdProcedure.decrypt`:
 
 .. literalinclude:: ../examples/decrypt.py