tutorial: minor fixes

--HG--
branch : feature-sphinx

1 files changed, 35 insertions, 30 deletions

diff --git a/docs/tutorial/index.rst b/docs/tutorial/index.rst
index c822a54..4fe4f3b 100644
--- a/docs/tutorial/index.rst
+++ b/docs/tutorial/index.rst
@@ -27,11 +27,14 @@ screen and will run until interrupted with *CTRL+C* (*^C*).
   This Filler will align our Text to the top of the screen, filling all the
   rows below with blank lines. Widgets which are given both the number of
   columns and number of rows they must be displayed in are called "box
-  widgets". The "topmost" widget displayed on the screen must be a box widget.
+  widgets".
 
 * The :class:`MainLoop` class handles displaying our widgets as
-  well as accepting input from the user. In this case our widgets can't handle
-  the input so we need to interrupt the program to exit with *^C*.
+  well as accepting input from the user.
+  The widget passed to :class:`MainLoop` is called the "topmost" widget.
+  The topmost widget is used to render the whole screen and so it must be a box widget.
+  In this case our widgets can't handle any user input so we need to interrupt
+  the program to exit with *^C*.
 
 .. image:: minimal1.png
 
@@ -46,9 +49,9 @@ each key pressed, exiting when the user presses *Q*.
    :linenos:
 
 * The :class:`MainLoop` class has an optional function
-  parameter *unhandled_input* This function will be called once for each
+  parameter *unhandled_input*. This function will be called once for each
   keypress that is not handled by the widgets being displayed.
-  Since of the widgets being displayed here handle input, every key the user
+  Since none of the widgets being displayed here handle input, every key the user
   presses will be passed to the *show_or_exit* function.
 
 * The :exc:`ExitMainLoop` exception is used to exit
@@ -134,8 +137,9 @@ background and setting values are documented in :ref:`foreground-background`.
   is put into 256-color mode by using the screen object's
   :meth:`raw_display.Screen.set_terminal_properties` method.
 
-This example builds the widgets to display in a top-down order. In some
-places we need to use a ``placeholder`` widget because we must provide
+This example also demonstrates how you can build the widgets to display
+in a top-down order instead of the usual bottom-up order. In some
+places we need to use a *placeholder* widget because we must provide
 a widget before the correct one has been created.
 
 * We change the topmost widget used by the :class:`MainLoop` by
@@ -149,8 +153,8 @@ a widget before the correct one has been created.
   colored with :class:`AttrMap`.
 
 * :ref:`container-widgets` like :class:`Pile` have a
-  ``contents`` property that we can treat like a collection of
-  widgets and options.  :attr:`Pile.contents` supports normal list
+  ``contents`` property that we can treat like a list of
+  ``(widget, options)`` tuples.  :attr:`Pile.contents` supports normal list
   operations including ``append()`` to add child widgets.
   :meth:`Pile.options` is used to generate the default options
   for the new child widgets.
@@ -176,7 +180,7 @@ Here we are customizing the :class:`Filler` decoration widget that is holding
 our :class:`Edit` widget by subclassing it and defining a new ``keypress()``
 method.  Customizing decoration or container widgets to handle input this way
 is a common pattern in Urwid applications.  This pattern is easier to maintain
-and extend than handling all special input in an ``unhandled_input`` function.
+and extend than handling all special input in an *unhandled_input* function.
 
 * In ``QuestionBox.keypress()`` all keypresses except *ENTER* are passed along to
   the default :meth:`Filler.keypress` which sends them to the
@@ -185,10 +189,10 @@ and extend than handling all special input in an ``unhandled_input`` function.
   widget without causing the program to exit because :meth:`Edit.keypress`
   indicates that it has handled the key by returning ``None``.
   See :meth:`Widget.keypress` for more information.
-* When *ENTER* is pressed the child widget (``original_widget``) is changed
-  to :class:`Text` widget.
+* When *ENTER* is pressed the child widget ``original_widget`` is changed
+  to a :class:`Text` widget.
 * :class:`Text` widgets don't handle any keyboard input so all input
-  ends up in the ``unhandled_input`` function ``exit_on_q()``, allowing the
+  ends up in the *unhandled_input* function *exit_on_q*, allowing the
   user to exit the program.
 
 
@@ -200,23 +204,23 @@ and extend than handling all special input in an ``unhandled_input`` function.
 Signal Handlers
 ---------------
 
-This program asks for your name and responds "Nice to meet you, (your name)"
+This program asks for your name and responds ``Nice to meet you, (your name)``
 *while* you type your name.  Press *DOWN* then *SPACE* or *ENTER* to exit.
 
 .. literalinclude:: frlb.py
    :linenos:
 
-* An :class:`Edit` widget and :class:`Text` reply
+* An :class:`Edit` widget and a :class:`Text` reply
   widget are created, like in the previous example.
 * The :func:`connect_signal` function is used to attach our
-  ``on_ask_change()`` function to our :class:`Edit` widget's
-  *change* signal. Now any time the content of the :class:`Edit`
-  widget changes :func:`on_ask_change` will be called and passed the new
+  *on_ask_change* function to our :class:`Edit` widget's
+  ``'change'`` signal. Now any time the content of the :class:`Edit`
+  widget changes *on_ask_change* will be called and passed the new
   content.
-* Finally we attach our ``on_exit_clicked()`` function to our
-  exit :class:`Button`'s *click* signal.
-* ``on_ask_change()`` updates the reply text as the user enters their
-  name and ``on_exit_click()`` exits.
+* Finally we attach our *on_exit_clicked* function to our
+  exit :class:`Button`'s ``'click'`` signal.
+* *on_ask_change* updates the reply text as the user enters their
+  name and *on_exit_click* exits.
 
 .. image:: frlb1.png
 .. image:: frlb2.png
@@ -236,7 +240,7 @@ be updated when you press *ENTER*. *ENTER* on a blank line exits.
 
 :class:`ListBox` widgets let you scroll through a number of flow widgets
 vertically.  It handles *UP*, *DOWN*, *PAGE UP* and *PAGE DOWN* keystrokes
-and changing the focus for you.  :ref:`listbox-contents` is managed by
+and changing the focus for you.  :ref:`listbox-contents` are managed by
 a "list walker", one of the list walkers that is easiest to use is
 :class:`SimpleFocusListWalker`.
 
@@ -247,20 +251,21 @@ automatically.
 Here we are customizing our :class:`ListBox`'s keypress handling by overriding
 it in a subclass.
 
-* ``question()`` is used to build widgets to communicate with the user.
+* The *question* function is used to build widgets to communicate with the user.
   Here we return a :class:`Pile` widget with a single :class:`Edit` widget
   to start.
 * We retrieve the name entered with :attr:`ListBox.focus` to get the
   :class:`Pile` in focus, the standard
   :ref:`container widget <container-widgets>` method ``[0]`` to get the
-  first child of the pile and :attr:`Edit.edit_text`.
+  first child of the pile and :attr:`Edit.edit_text` to get the user-entered
+  text.
 * For the response we use the fact that we can treat
-  :attr:`Pile.contents` like a list of widgets and options to create or
-  replace any existing response by assigning to ``[1:]``.  We assign
-  the new response with the default :meth:`Pile.options`.
+  :attr:`Pile.contents` like a list of ``(widget, options)`` tuples to create or
+  replace any existing response by assigning a one-tuple list to ``[1:]``.  We create
+  the default options using :meth:`Pile.options`.
 * To add another question after the current one we treat our
-  :class:`SimpleFocusListWalker` like a normal list of widgets and call
-  ``insert()``, then update the focus position to the widget we just
+  :class:`SimpleFocusListWalker` stored as :attr:`ListBox.body` like a normal
+  list of widgets and call ``insert()``, then update the focus position to the widget we just
   created.
 
 .. image:: lbcont1.png