[Checkins] SVN: manuel/trunk/src/manuel/table-example.txt work on the table example a bit more

[Benji York]

Log message for revision 101239:
  work on the table example a bit more
  

Changed:
  U   manuel/trunk/src/manuel/table-example.txt

-=-
Modified: manuel/trunk/src/manuel/table-example.txt
===================================================================
--- manuel/trunk/src/manuel/table-example.txt	2009-06-22 23:27:58 UTC (rev 101238)
+++ manuel/trunk/src/manuel/table-example.txt	2009-06-22 23:54:38 UTC (rev 101239)
@@ -18,8 +18,6 @@
 can check to see if the assertions made in the tables match reality, and a
 formatter to display the results if they don't.
 
-    >>> import manuel
-
 We'll use `reST <http://docutils.sourceforge.net/rst.html>`_ tables as the
 table format.  The table source will look like this::
 
@@ -34,29 +32,38 @@
     True   True   True
     =====  =====  ======
 
-When rendered, it will look like this:
+.. -> example_table_1
 
-=====  =====  ======
-\      A or B
---------------------
-  A      B    Result
-=====  =====  ======
-False  False  False
-True   False  True
-False  True   True
-True   True   True
-=====  =====  ======
+When rendered to HTML, it will look like this:
 
-The source for our test...
+    =====  =====  ======
+    \      A or B
+    --------------------
+      A      B    Result
+    =====  =====  ======
+    False  False  False
+    True   False  True
+    False  True   True
+    True   True   True
+    =====  =====  ======
 
-.. code-block:: python
+.. -> example_table_2
 
-    source = """\
+    >>> example_table_1 == example_table_2
+    True
+
+
+Documents
+---------
+
+Manuel plug-ins operate on instances of :class:`manuel.Document`.  As an
+example we'll construct one with these contents::
+
     The "or" operator
     =================
-    
+
     Here is an example of the "or" operator in action:
-    
+
     =====  =====  ======
     \      A or B
     --------------------
@@ -67,12 +74,14 @@
     False  True   True
     True   True   True
     =====  =====  ======
-    """
 
-...will be stored in a Manuel Document:
+.. -> source
 
+Manuel plug-ins operate on instances of :class:`manuel.Document`.
+
 .. code-block:: python
 
+    import manuel
     document = manuel.Document(source, location='fake.txt')
 
 
@@ -80,7 +89,7 @@
 -------
 
 
-First we need an object to represent the tables.
+We need an object to represent the tables.
 
 .. code-block:: python
 
@@ -155,8 +164,8 @@
 to check them for correctness.
 
 The evaluate_table function will run each set of inputs through the given
-expression and compare the result with what was expected, recording any
-discrepancies.
+expression and compare the result with what was expected, recording each
+discrepancie as a :class:`TableError` stored in a :class:`TableErrors` object.
 
 .. code-block:: python
 
@@ -207,9 +216,9 @@
     source_with_errors = """\
     The "or" operator
     =================
-    
+
     Here is an (erroneous) example of the "or" operator in action:
-    
+
     =====  =====  ======
     \      A or B
     --------------------
@@ -284,7 +293,7 @@
                 [format_table_errors])
 
 Now we can create a fresh document and tell it to do all the above steps
-(parse, evaluate, format) an instance of our table example Manuel.
+(parse, evaluate, format) using an instance of our plug-in.
 
     >>> m = Manuel()
     >>> document = manuel.Document(source_with_errors, location='fake.txt')