correction/edits

doc/build/content/namespaces.txt

@@ -5,7 +5,7 @@ Namespaces are used to organize groups of components into categories, and also t
 
 If the file `components.html` defines these two components:
 
-    # components.html
+    ## components.html
     <%def name="comp1()">
         this is comp1
     </%def>
@@ -16,7 +16,7 @@ If the file `components.html` defines these two components:
     
 You can make another file, for example `index.html`, that pulls those two components into a namespace called `comp`:
 
-    # index.html
+    ## index.html
     <%namespace name="comp" file="components.html"/>
     
     Heres comp1:  ${comp.comp1()}
@@ -61,14 +61,14 @@ Note that the `context` argument is not needed in the call; the `namespace` tag
 
 The `<%namespace>` tag supports the definition of `<%defs>` directly inside the tag.  These defs become part of the namespace like any other function, and will override the definitions pulled in from a remote template or module:
     
-    # define a namespace
+    ## define a namespace
     <%namespace name="stuff">
         <%def name="comp1()">
             comp1
         </%def>
     </%namespace>
     
-    # then call it
+    ## then call it
     ${stuff.comp1()}
 
 ### The "body()" method {@name=body}
@@ -116,16 +116,18 @@ The `self` namespace, in the case of a template that does not use inheritance, i
 
 ### Inheritable Namespaces
 
-The `<%namespace>` tag includes an optional attribute `inheritable="True"`, which will cause the namespace to be attached to the `self` namespace.  Since `self` is globally available throughout an inheritance chain (described in the next section), all the templates in an inheritance chain can get at the namespace via self.
-
+The `<%namespace>` tag includes an optional attribute `inheritable="True"`, which will cause the namespace to be attached to the `self` namespace.  Since `self` is globally available throughout an inheritance chain (described in the next section), all the templates in an inheritance chain can get at the namespace imported in a super-template via `self`.
+    
     ## base.html
     <%namespace name="foo" file="foo.html" inheritable="True"/>
     
     ${next.body()}
 
     ## somefile.html
-    <%import file="base.html"/>
+    <%inherit file="base.html"/>
     
     ${self.foo.bar()}
-    
-The `import="*"` part of the `<%namespace>` tag doesn't yet interact with the `inheritable` flag, more on that in a future release.
\ No newline at end of file
+
+This allows a super-template to load a whole bunch of namespaces that its inheriting templates can get to, without them having to explicitly load those namespaces themselves.
+
+The `import="*"` part of the `<%namespace>` tag doesn't yet interact with the `inheritable` flag, so currently you have to use the explicit namespace name off of `self`, followed by the desired function name.  But more on this in a future release.