diff --git a/tconfpy.3 b/tconfpy.3
index 7d304ee..629a221 100644
--- a/tconfpy.3
+++ b/tconfpy.3
@@ -1078,33 +1078,141 @@
     [FOO[BAR]] = Something Or Other
 .fi
 
-.SS Lexical Namespaces
+.SS Introducing Lexical Namespaces
 
-The discussion of variable assignment and reference needs to be
-expanded now to include the idea of "lexical namespaces".  Think of a
-namespace as just being the current context for variables - a way to
-group variables together.  The idea is that a variable name or
-reference is always relative to the current namespace.  That is, the
-"real" name of the variable is the concatenation of the current
-namespace with the variable's name.
-
-For instance, suppose the current namespace is "MYNS" and we see the
-following in a configuration file:
+So far,the discussion of variables and references has conveniently
+ignored the presence of another related \*(TC feature, "lexical
+namespaces."  Namespaces are a way to automatically group 
+related variables together.  Suppose you wanted to describe
+the options on your car in a configuration file.  You might do
+this:
 
 .nf
-    Foo = Bar
-    Baz = [Foo]
+    MyCar.Brand = Ferrari
+    MyCar.Model = 250 GTO
+    MyCar.Color = Red
+ 
+    # And so on ...
 .fi
 
-What this
-.B really
-means to \*(TC is this:
+You'll notice that every variable start with the "thing" that 
+each item has in common - they are features of \'MyCar\'.
+We can simplify this considerably by introducing a lexical namespace:
 
 .nf
-    MYNS.Foo = MYNS.Bar
-    MYNS.Baz = [MYNS.Foo]
+    [MyCar]
+
+    Brand = Ferrari
+    Model = 250 GTO
+    Color = Red
 .fi
 
+The first statement looks like a variable reference, but it is not.
+.B A string inside square brackets by itself on a line introduces a namespace.
+The first statement in this example sets the namespace to \'MyCar\'.
+From that point forward until the namespace is changed again, every
+variable assignment
+.B and
+reference is "relative" to the namespace.  What this really means is
+that \*(TC sticks the namspace plus a period in front of every
+variable assigned or referenced.  It does this automatically and
+invisibly, so \'Brand\' is turned into \'MyCar.Brand\' and so on.  You
+can actually check this by loading the example above into a test
+configuration file and running the \'test-tc\' program on it.  You will
+see the "fully qualified" variable names that actually were loaded
+into the symbol table, each beginning with \'MyCar.\' and ending with
+the variable name you specified.
+
+Realize that this is entirely a naming "trick".  \*(TC has no clue
+what the namespace
+.B means,
+it just combines the current namespace with the variable name to
+create the actual variable name that will be returned in the symbol
+table. 
+
+You're likely scratching your head wondering why on earth this
+feature present in \*(TC.  There are, in fact, several reasons for it:
+
+.IP \(bu 4
+
+It reduces typing repetetive information throughout the configuration
+file.  In turn, this reduces the likelyhood of a typographical or
+spelling error.
+
+.IP \(bu 4
+
+It helps visibly organize the configuration file.  A namespace makes
+it clear which variables are related to each other somehow.  This is no
+big deal in small configurations, but \*(TC was written with the idea
+of supporting configuration files that might contain thousands or
+even tens of thousands of entries.
+
+.IP \(bu 4
+
+It simplifies the application programmer's job.  Say I want to write a
+program that extracts all the information about your car from the
+configuration file, but I don't know ahead of time how many things you
+will describe.  All I really have to know is that you are using
+\'MyCar\' as the namespace for this information.  My program can then
+just scan the symbol table after the configuration file has been parsed,
+looking for variables whose name begins with \'MyCar.\'.  So if you
+want to add other details about your auto like, say, \'Age\', \'Price\',
+and so on, you can do so later
+.B and the program does not have to be rewritten.
+
+.IP \(bu 4
+
+It helps enforce correct configuration files.  By default, you can
+introduce new namespaces into the configuration file any time you
+like.  However, as described in the previous section on the 
+\*(TC API, the application programmer can limit you to a pre-defined
+set of legal namespaces (via the \'AllowNewNamespaces=False\' API
+option).  By doing this, the programmer is helping you avoid
+incorrect configuration file entries by limiting just which
+namespaces you can enter to reference or create variables.
+
+
+.SS Lexical Namespace Specifics
+
+Creating and using lexical namespaces is fairly straightforward,
+but there are a few restrictions and rules:
+
+.IP \(bu 4
+
+The default initial namespace is the empty string, "".  In this one case,
+\*(TC does nothing to variables assigned or referenced.  That's
+why our early examples of how to assign a value to a variable and
+then reference those value in the previous section worked.
+When the namespace is "", nothing is done to the variable names.
+The namespace, "", is also called the "root namespace."
+
+Bear in mind that the programmer can change this default namespace to
+something other than "" before the configuration file is parsed.  If
+they do this, they would be well advised to let their users know this
+fact.
+
+.IP \(bu 4
+There two ways to change to a new namespace:
+
+.nf
+    [NewNameSpace]   # Must appear on a line by itself or with a comment only
+    NAMESPACE = NewNamespace
+.fi
+
+If, at any point, you want to return to the root namespace, you can use
+one of these two methods:
+
+.nf
+    []
+    NAMESPACE =
+.fi
+
+So, why are there two ways to do the same thing? 
+
+
+
+
+
 In other words, \*(TC always prepends the current namespace (plus a
 separating period) to any variable assignment or reference it finds in
 a configuration.  The one exception is when the namespace is "", in