Steps 1 & 2 appear sane.

5 files changed, 52 insertions, 31 deletions

diff --git a/docs/tutorials/lxmlgraph/step01.rst b/docs/tutorials/lxmlgraph/step01.rst
index bf0f29085..6c6f93191 100644
--- a/docs/tutorials/lxmlgraph/step01.rst
+++ b/docs/tutorials/lxmlgraph/step01.rst
@@ -2,13 +2,14 @@
 Step 1: Getting Started
 =======================
 
-To get started, run ``paster create -t bfg`` as described in
-:ref:_project_narr to create your lxmlgraph project::
+To get started, using the ``paster`` command from a :term:`virtualenv`
+you've created that has ``repoze.bfg`` installed, run ``paster create
+-t bfg`` as described in :ref:`project_narr` to create your lxmlgraph
+project::
 
 
- $ paster create -t bfg
-  Selected and implied templates:
-    repoze.bfg#bfg  repoze.bfg starter project
+ $ paster create -t bfg Selected and implied templates: repoze.bfg#bfg
+  repoze.bfg starter project
 
   Enter project name: lxmlgraph
   ...
@@ -17,4 +18,8 @@ To get started, run ``paster create -t bfg`` as described in
 You now have a project named ``lxmlgraph`` in your current directory.
 We'll add to this project in subsequent steps.
 
-
+To get your project ready for development and execution, use the
+``setup.py develop`` command within the same virtualenv as bfg is
+installed as documented in :ref:`project_narr` .  You'll need to do
+this in order to run the ``lxmlgraph`` application in subsequent
+steps.
diff --git a/docs/tutorials/lxmlgraph/step02.rst b/docs/tutorials/lxmlgraph/step02.rst
index ab2faf572..19d8a192e 100644
--- a/docs/tutorials/lxmlgraph/step02.rst
+++ b/docs/tutorials/lxmlgraph/step02.rst
@@ -2,8 +2,8 @@
 Step 2: Hello World as XML
 ================================================
 
-We now have a default project named ``lxmlgraph``.  It contains a
-*package* (also) named ``lxmlgraph``.
+We now have a project named ``lxmlgraph``.  It contains a *package*
+(also) named ``lxmlgraph``.
 
 In this step we will add an XML document to the *package* as our model
 data.  We will leverage the following ``repoze.bfg`` machinery:
@@ -14,15 +14,16 @@ data.  We will leverage the following ``repoze.bfg`` machinery:
 
 Our application will need to do these things:
 
-  - Our model class needs to use lxml to inject itelf into the XML
-    nodes
+  - Use lxml Element classes to inject ``repoze.bfg`` behavior into
+    ``lxml`` nodes
 
-  - That model class needs to implement the "handshake"
+  - That model class needs to implement the ``repoze.bfg`` publishing
+    contract
 
 All of the below filenames are relative to the ``lxmlgraph`` *package*
-rather than the project.
+rather than the *project*.
 
-File ``samplemodel.xml``
+``samplemodel.xml``
 -----------------------------------
 
 We're going to add an XML document that will serve as a source for
@@ -38,15 +39,16 @@ model data named ``samplemodel.xml``.
 #. In lines 3-4, the ``<site>`` contains 2 top-level children: a and
    b.  These are provided as an element name ``<document>``.  This,
    also, is meaningfless as far as ``repoze.bfg`` is concerned.
-   However, this is where you compose th information model you are
+   However, this is where you compose the information model you are
    publishing.
 
 The only special constraint is that a node that wants to be "found" by
 ``repoze.bfg`` in during traversal *must* have an ``name`` attribute.
 (The use of ``@name`` corresponds to ``__name__`` in the
-``repoze.bfg`` handshake.)  Each hop in the URL tries to grab a child
-with an attribute matching the next hop.  Also, the value of the
-``@name`` should be unique in its containing node.
+``repoze.bfg`` sense of ``repoze.bfg`` :term:`location`).  Each hop in
+the URL tries to grab a child with an attribute matching the next hop.
+Also, the value of the ``@name`` should be unique in its containing
+node.
 
 
 Module ``models.py``
@@ -54,7 +56,8 @@ Module ``models.py``
 
 At a high level, we make write a class that "extends" lxml Element
 nodes, create an lxml parser, and register the custom class with the
-parser.
+parser.  Replace the contents of the autogenerated ``models.py`` with
+the content we show below.
 
 .. literalinclude:: step02/myapp/models.py
    :linenos:
@@ -80,14 +83,15 @@ parser.
    return it.  If not, or if more than one is found, raise an error.
 
 #. As before, ``get_root`` is the function that is expected to return
-   the top of the model.  In lines 30-32 we do the lxml magic to get
-   the custom Python class registered.  We then load some XML and
-   return the top of the tree.
+   the top of the model.  In lines 30+ we do the lxml magic to get the
+   custom Python class registered.  We then load some XML and return
+   the top of the tree.
 
 Module ``views.py``
 -----------------------------
 
-Our ``views.py`` module does the following:
+Replace the autogenerated ``views.py`` code in the lxmlgraph package
+with the following::
 
 .. literalinclude:: step02/myapp/views.py
    :linenos:
@@ -98,13 +102,24 @@ Our ``views.py`` module does the following:
 #. Line 6 uses the special property we defined in our custom Python
    class to get the ``__name__`` of the context.
 
+We don't need to change the ``configure.zcml`` because the
+autogenerated one is still correct for this configuration.  It
+includes::
+
+.. literalinclude:: step02/myapp/configure.zcml
+   :linenos:
+   :language: xml
+
 Browsing the Model
 ------------------------
 
-We can use these URLs to browse the model graph and see results::
+We're done changing code.  Start the application by executing ``paster
+serve lxmlgraph.ini`` (the ``.ini`` file is in the project directory).
+It will listen on port 5432.  We can use these URLs to browse the
+model graph and see results::
 
-  http://localhost:5432/a
-  http://localhost:5432/b
+  http://localhost:5432/a (Hello to document from a @ /a)
+  http://localhost:5432/b (Hello to document from b @ /b)
   http://localhost:5432/c (Not Found)
 
 In this case, each request grabs a node in the XML and uses it as the
diff --git a/docs/tutorials/lxmlgraph/step02/myapp/configure.zcml b/docs/tutorials/lxmlgraph/step02/myapp/configure.zcml
index 540526ec9..d299dc883 100644
--- a/docs/tutorials/lxmlgraph/step02/myapp/configure.zcml
+++ b/docs/tutorials/lxmlgraph/step02/myapp/configure.zcml
@@ -5,7 +5,7 @@
 
   <bfg:view
      for=".models.IMyModel"
-     view=".views.my_hello_view"
+     view=".views.my_view"
      />
 
 </configure>
diff --git a/docs/tutorials/lxmlgraph/step02/myapp/models.py b/docs/tutorials/lxmlgraph/step02/myapp/models.py
index 3c03de1a9..1d93ccdd0 100644
--- a/docs/tutorials/lxmlgraph/step02/myapp/models.py
+++ b/docs/tutorials/lxmlgraph/step02/myapp/models.py
@@ -1,3 +1,5 @@
+import os
+
 from zope.interface import implements
 from zope.interface import Attribute
 from zope.interface import Interface
@@ -32,10 +34,9 @@ def get_root(environ):
     parser.set_element_class_lookup(parser_lookup)
 
     # Now load the XML file
-    xmlstring = open("myapp/samplemodel.xml").read()
+    here = os.path.join(os.path.dirname(__file__))
+    samplemodel = os.path.join(here, 'samplemodel.xml')
+    xmlstring = open(samplemodel).read()
     root = etree.XML(xmlstring, parser)
 
     return root
-
-
-
diff --git a/docs/tutorials/lxmlgraph/step02/myapp/views.py b/docs/tutorials/lxmlgraph/step02/myapp/views.py
index 205b4b163..75e390efb 100644
--- a/docs/tutorials/lxmlgraph/step02/myapp/views.py
+++ b/docs/tutorials/lxmlgraph/step02/myapp/views.py
@@ -1,6 +1,6 @@
 from webob import Response
 
-def my_hello_view(context, request):
+def my_view(context, request):
     response = Response('Hello to %s from %s @ %s' % (
             context.tag, 
             context.__name__,