--- a/docs.html	Thu Sep 10 17:05:05 2009 -0700
+++ b/docs.html	Thu Sep 10 22:32:45 2009 -0700
@@ -13,6 +13,12 @@
 <p>Pydertron is a high-level wrapper for <a class="reference" href="http://code.google.com/p/pydermonkey">Pydermonkey</a> that
 provides convenient, secure object wrapping between JS and Python
 space.</p>
+<p>Note that Pydertron is just one example of a high-level interface
+between Python and JavaScript: it assumes, for instance, that the JS
+code it executes isn't trusted, which affects the nature of the
+inter-language interaction.</p>
+<div class="section">
+<h1><a id="the-basics" name="the-basics">The Basics</a></h1>
 <p>The <tt class="docutils literal"><span class="pre">JsSandbox</span></tt> class encapsulates a JavaScript runtime, context, global
 object, and a simple <a class="reference" href="http://wiki.commonjs.org/wiki/CommonJS/Modules/SecurableModules">SecurableModule</a> implementation that complies
 with the <a class="reference" href="http://wiki.commonjs.org/wiki/CommonJS">CommonJS</a> standard. It also provides a high-level bridge between
@@ -90,10 +96,42 @@
 -1
 </pre>
 </blockquote>
-<p>Note that the traceback displayed is actually referring to
-JavaScript code: one of Pydertron's helpful conveniences is that
-it makes debugging JS code as much like debugging Python code as
-possible.</p>
+<p>Note that the traceback displayed is actually referring to JavaScript
+code: one of Pydertron's aims is to make debugging JS code as much
+like debugging Python code as possible.</p>
+</div>
+<div class="section">
+<h1><a id="exceptions" name="exceptions">Exceptions</a></h1>
+<p>Any exceptions raised by wrapped Python functions need to be of type
+<tt class="docutils literal"><span class="pre">pydermonkey.error</span></tt> to be propagated into calling JavaScript code;
+if they're not, then for security purposes, the entire JavaScript call
+stack is unrolled.</p>
+<p>For example, here's a function that's bound to fail:</p>
+<blockquote>
+<pre class="doctest-block">
+&gt;&gt;&gt; &#64;jsexposed
+... def fail():
+...   o()
+&gt;&gt;&gt; sandbox.root.fail = fail
+</pre>
+</blockquote>
+<p>Now, even though the following JS code calls the function in a
+try-catch block, the JS code doesn't catch anything and its execution
+is simply halted:</p>
+<blockquote>
+<pre class="doctest-block">
+&gt;&gt;&gt; sandbox.run_script(&quot;try { fail(); } catch (e) {}&quot;,
+...                    stderr=sys.stdout)  #doctest: +ELLIPSIS
+An internal error occurred.
+Traceback (most recent call last):
+...
+NameError: global name 'o' is not defined
+-1
+</pre>
+</blockquote>
+<p>Note that a <tt class="docutils literal"><span class="pre">KeyboardInterrupt</span></tt> triggered while JS is executing will
+have similar effect.</p>
+</div>
 </div>
 <div class="footer">
 <hr class="footer" />