# HG changeset patch
# User Jeff Hammel <jhammel@mozilla.com>
# Date 1294724552 28800
# Node ID 672d2d3ee322cf9d655c154003a00a03ddc0207e
# Parent  26b9c3bba04e1e7181616d6ce733ddfc4c845e15
document a bit and add a test for an include example

diff -r 26b9c3bba04e -r 672d2d3ee322 README.txt
--- a/README.txt	Mon Jan 10 21:33:03 2011 -0800
+++ b/README.txt	Mon Jan 10 21:42:32 2011 -0800
@@ -13,3 +13,17 @@
 And this is the time of the iceberg.  If it really is a one-off, who
 cares?  But quickly one-offs become a deployment story, and not a very
 efficient one.  
+
+Variable Conventions
+--------------------
+
+MakeItSo! provides a few variables for you.  You can include another
+file or URL using {{include(URI)}}, where URI is the file path or the
+URL (of course, internet is required to include remote resources). The
+included resource is not included.
+
+Files and URLS being interpolated also have the variable %(here)s,
+which is the parent of their resource.  Therefor, using sensible path
+conventions, a neighboring file may be (e.g.) included like
+
+{{include(here + 'foo.txt')}}
diff -r 26b9c3bba04e -r 672d2d3ee322 examples/doctest.txt
--- a/examples/doctest.txt	Mon Jan 10 21:33:03 2011 -0800
+++ b/examples/doctest.txt	Mon Jan 10 21:42:32 2011 -0800
@@ -37,6 +37,14 @@
     'Hello fleem'
     >>> os.remove(buffer)
 
+Including a file::
+
+    >>> include_example = os.path.join(here, 'include-example.txt')
+    >>> buffer = tempfile.mktemp()
+    >>> template = makeitso.PolyTemplate([include_example], interactive=False)
+    >>> template.substitute({}, buffer)
+    >>> os.remove(buffer)
+
 Directory case::
 
     >>> exampledir = os.path.join(here, 'directory-example')