--- a/docs.css	Thu Sep 10 17:05:05 2009 -0700
+++ b/docs.css	Thu Sep 10 22:32:45 2009 -0700
@@ -3,7 +3,7 @@
     font-size: 12pt;
 }
 
-.title {
+h1 {
     font-weight: normal;
 }
 

--- 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" />

--- a/docs.txt	Thu Sep 10 17:05:05 2009 -0700
+++ b/docs.txt	Thu Sep 10 22:32:45 2009 -0700
@@ -6,6 +6,14 @@
 provides convenient, secure object wrapping between JS and Python
 space.
 
+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.
+
+The Basics
+----------
+
 The ``JsSandbox`` class encapsulates a JavaScript runtime, context, global
 object, and a simple `SecurableModule`__ implementation that complies
 with the `CommonJS`__ standard. It also provides a high-level bridge between
@@ -77,7 +85,36 @@
   ReferenceError: bar is not defined
   -1
 
-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.
+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.
+
+Exceptions
+----------
+
+Any exceptions raised by wrapped Python functions need to be of type
+``pydermonkey.error`` to be propagated into calling JavaScript code;
+if they're not, then for security purposes, the entire JavaScript call
+stack is unrolled.
+
+For example, here's a function that's bound to fail:
+
+  >>> @jsexposed
+  ... def fail():
+  ...   o()
+  >>> sandbox.root.fail = fail
+
+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:
+
+  >>> sandbox.run_script("try { fail(); } catch (e) {}",
+  ...                    stderr=sys.stdout)  #doctest: +ELLIPSIS
+  An internal error occurred.
+  Traceback (most recent call last):
+  ...
+  NameError: global name 'o' is not defined
+  -1
+
+Note that a ``KeyboardInterrupt`` triggered while JS is executing will
+have similar effect.

--- a/pydertron.py	Thu Sep 10 17:05:05 2009 -0700
+++ b/pydertron.py	Thu Sep 10 22:32:45 2009 -0700
@@ -587,8 +587,8 @@
             stderr.write("%(stack_trace)s\n%(error)s\n" % params)
         except InternalError, e:
             stderr.write("An internal error occurred.\n")
-            traceback.print_tb(e.exc_info[2], None, stderr)
-            stderr.write("%s\n" % e.exc_info[1])
+            traceback.print_exception(e.exc_info[0], e.exc_info[1],
+                                      e.exc_info[2], None, stderr)
         return retval
 
 class HttpFileSystem(object):