Hi folks,
In an attempt to document the results of a discussion about the
interface between Shindig and the Cajoler, I modified this document --
http://google-caja.googlecode.com/svn/trunk/doc/html/cajaOpenSocialGadgetRewriting/index.html
and the diffs since the last version are attached fyi.
I'm especially interested in knowing whether I got the format of the
embedded line number and source file annotations right. All other
comments are welcome too, of course! Cheers,
Ihab
--
Ihab A.B. Awad, Palo Alto, CA
Index: doc/html/cajaOpenSocialGadgetRewriting/index.html
===================================================================
--- doc/html/cajaOpenSocialGadgetRewriting/index.html (revision 407)
+++ doc/html/cajaOpenSocialGadgetRewriting/index.html (working copy)
@@ -33,7 +33,7 @@
<h2>Portions rewritten</h2>
-<p>An OpenSocial gadget is an XML document that looks like the
+<p>An OpenSocial gadget is an XML document that often looks like the
following simple example. (See the OpenSocial documentation for a
normative description of the gadget format.)</p>
@@ -51,9 +51,9 @@
</Module>
</pre>
-<p>We will rewrite the material in the content area as described
-below. All other material will be passed through verbatim,
-<em>modulo</em> sanitizing of the element attribute values.</p>
+<p>Caja -- and this specification -- are only concerned with rewriting
+the <em>content area</em>. This is done via an instance of interface <a
+href="../../../src/java/com/google/caja/opensocial/GadgetContentRewriter.java"><code>GadgetContentRewriter</code></a>.</p>
<h2>Content area rewriting</h2>
@@ -229,9 +229,34 @@
return ___.getOuters(pluginId)[handlerName](plugin_tamed(thisNode),
plugin_tamed(event));
}</pre>
-<h2>Attribute value sanitizing</h2>
-<p class="note">TBD: Discuss threat model and how it will be addressed.</p>
+<h2>Original source context</h2>
+<p>A client of the Caja rewriting can provide annotations specifying
+locations in the original source written by the gadget developer, for
+use by Caja error messages and debugging information. Regardless of
+where they appear (in JS, HTML or CSS), these will be complete lines
+of text, starting from column 0, in the following form:</p>
+
+<pre>
[EMAIL PROTECTED] LINE="<em>line</em>" FILE="<em>file</em>"<em><NL></em>
[EMAIL PROTECTED] LINE="<em>line</em>"<em><NL></em>
+</pre>
+
+<p>where we define:</p>
+
+<blockquote>
+
+<p><code><em>line</em></code> — a line number, expressed as the
+string representation of an integer.</p>
+
+<p><code><em>file</em></code> — a URL to a file.</p>
+
+<p><code><em><NL></em></code> — a newline character, which
+will be consumed by the Caja translator but will not be considered to
+be part of the original source.</p>
+
+</blockquote>
+
</body>
</html>
