Create and document stencil object.

File                             Raw         Min         Zip     Min/Zip
index.js                 30967/30.24 10077/09.84  7617/07.44  3848/03.76

Closes #119.

README.md

@@ -146,28 +146,26 @@ pleasing.
 But, again, why? Only because I'm doing this stupid thing with prototypes that
 I'm going to try to document right here...
 
-### The `stencil` Variable
-
-The `stencil` variable is a special object added to the context by the Stencil
-that has properties of the current template. It is not visible in the ordinary
-scope of template, (why? why not? I mean really, why was this important? now you
-have to add a paragraph explaining special properties? Are you just being a
-bonehead? Didn't we talk about that? No really, I can't wait to see this...)
-
-You can distinguish the context variables set by the Stencil engine from the
-context variables set by your application using `hasOwnProperty`. I'm not sure
-if this is useful, but it's there.
-
-(Oh, you're a real prize. Can we please [kill this
-poodle](http://www.lileks.com/bleats/archive/03/0103/010301.html#010303)? You
-know how else you could distinguish between a property set by the Stencil engine
-and a property provided by your application? `key == "stencil"`. Yes. You are a
-bonehead. TODO: Don't be such a bonehead. Then you don't have to document this.
-You might not be able to accept this right now, but there are people in this
-world how are smart enough to figure that out for themselves, I know, hard to
-accept that world won't embrace the genius of your using object prototypes to do
-something, that you know what you're doing, but there are object prototypes
-involved and that's really special, so, I can't even, I can't.)
+### The `stencil` Object
+
+The `stencil` variable contains a special object added to the context by the
+Stencil that has properties of the current template. The `stencil` variable is
+constantly reset and overrides and variable assignments by the user.
+
+The `stencil` Object offers the following properties and methods.
+
+ * `url` — The URL of the current Stencil.
+ * `absolutize(base, path)` — Creates an absolute path using the given
+   base and sub-path. If the sub-path begins with a `/`, it is treated as a full
+   qualified path.
+ * `normalize(path)` — Normalizes a file path so that
+   `/docs/./articles/../posts/post.html` is normalized to
+   `/docs/posts/post.html`.
+ * `json(url)` — Returns a Stencil callback that will fetch the given URL
+   and parse it as JSON.
+
+TK: Find a place to write more about `json(url)` and send the readers of this
+section to that place.
 
 ## Tag Libraries
 

index.js

@@ -479,7 +479,8 @@
   function rewrite (parent, frames, page, template, includes, named,
                     directives, path, context, generating, callback) {
     var okay = validator(callback), prefix = '$';
-    context = extend(Object.create(template.context), context);
+    context = extend({}, context);
+    context.stencil = template.stencil;
     if (frames[0].attributes) {
       frames[0].attributes.forEach(function (attributes) {
         context[prefix + 'attributes'] = attributes;
@@ -655,10 +656,8 @@
       // Create our template.
       templates[url] = {
         url: url, page: page, directives: directives, tags: tags,
-        context: {
-          stencil: {
-            url: url, absolutize: absolutize, normalize: normalize, json: json
-          }
+        stencil: {
+          url: url, absolutize: absolutize, normalize: normalize, json: json
         }
       };