[Laszlo-checkins] r7695 - openlaszlo/trunk/docs/src/developers
ben@openlaszlo.org
ben at openlaszlo.org
Tue Jan 1 18:30:51 PST 2008
Author: ben
Date: 2008-01-01 18:30:47 -0800 (Tue, 01 Jan 2008)
New Revision: 7695
Modified:
openlaszlo/trunk/docs/src/developers/doc-backwards-xform.dbk
Log:
Change 20080101-ben-m by ben at slim.local on 2008-01-01 18:26:23 PST
in /Users/ben/src/svn/openlaszlo/trunk
for http://svn.openlaszlo.org/openlaszlo/trunk
Summary: Description of how to trace the reference page contents back to the source
Documentation:
Febrile quest to trace important sections of the output reference *back*
to the xsl templates, js2doc intermediates, and docbook intermediates from
where they originate.
After the next build, this chapter will be available at:
http://labs.openlaszlo.org/trunk-nightly/docs/developers/doc-backwards.html
Modified: openlaszlo/trunk/docs/src/developers/doc-backwards-xform.dbk
===================================================================
--- openlaszlo/trunk/docs/src/developers/doc-backwards-xform.dbk 2008-01-02 02:30:26 UTC (rev 7694)
+++ openlaszlo/trunk/docs/src/developers/doc-backwards-xform.dbk 2008-01-02 02:30:47 UTC (rev 7695)
@@ -1,168 +1,266 @@
<?xml version="1.0"?>
<!-- * X_LZ_COPYRIGHT_BEGIN ***************************************************
-* Copyright 2007 Laszlo Systems, Inc. All Rights Reserved. *
-* Use is subject to license terms. *
-* X_LZ_COPYRIGHT_END ****************************************************** -->
+ * Copyright 2008 Laszlo Systems, Inc. All Rights Reserved. *
+ * Use is subject to license terms. *
+ * X_LZ_COPYRIGHT_END ****************************************************** -->
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter language="en" id="doc-backwards">
<title>The Backwards Transformation: From Reference Page to Source</title>
<para>In this chapter, we will show where several elements on the end product reference page
- can be traced back to their origins in the sources.</para>
+ can be traced back to their origins in the sources. </para>
+ <note>At this point we strongly, strongly encourage the reader
+ to undergo an investigation of XPath 1.0 and to find an XML editor which is capable of doing live
+ XPath queries. (Oxygen XML Editor works.) Then, <emphasis>actually run some queries on a js2doc dataset</emphasis>.
+ Without this exercise, the remainder of this chapter will be utter gobbledygook.
+ </note>
- <figure>
- <title>Page Header</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/reference-header-explanation.png"/>
- </imageobject>
- </mediaobject>
- </figure>
-
- <informaltable colsep="0" frame="none">
- <tgroup cols="2">
- <colspec colname="Region"/>
- <colspec colname="Docbook Element"/>
- <colspec colname="js2doc2dbk template"/>
- <colspec colname="js2doc Element"/>
- <thead>
- <row>
- <entry align="left">Region</entry>
- <entry align="left">Docbook Element</entry>
- <entry align="left">Relevant Templates</entry>
- <entry align="left">js2doc Element</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>A</entry>
- <entry>header navigation</entry>
- <entry>parameters.xsl: navig.showtitles, suppress.header.navigation </entry>
- <entry>-</entry>
- </row>
- <row>
- <entry>B</entry>
- <entry><refentry xreflabel="<text>" id="LzText" ...></entry>
- <entry><xsl:template match="property" mode="refentry"></entry>
- <entry>WORKHERENOW</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
+ <section><title>Page Header</title>
+ <figure>
+ <title>Page Header</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/reference-header-explanation.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <informaltable colsep="0" frame="none">
+ <tgroup cols="2">
+ <colspec colname="Region"/>
+ <colspec colname="Docbook Element"/>
+ <colspec colname="js2doc2dbk template"/>
+ <colspec colname="js2doc Element"/>
+ <thead>
+ <row>
+ <entry align="left">Region</entry>
+ <entry align="left">Docbook Element</entry>
+ <entry align="left">Relevant Templates</entry>
+ <entry align="left">js2doc Element</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>A</entry>
+ <entry>header navigation</entry>
+ <entry>parameters.xsl: navig.showtitles, suppress.header.navigation </entry>
+ <entry>-</entry>
+ </row>
+ <row>
+ <entry>B</entry>
+ <entry><refentry xreflabel="<text>" id="LzText" ...></entry>
+ <entry><xsl:template match="property" mode="refentry"> <emphasis>("main class template")</emphasis></entry>
+ <entry><property id="LzText" name="LzText" .../></entry>
+ </row>
+ <row>
+ <entry>C</entry>
+ <entry>header navigation</entry>
+ <entry>parameters.xsl: navig.showtitles, suppress.header.navigation </entry>
+ <entry>-</entry>
+ </row>
+ <row>
+ <entry>D</entry>
+ <entry><refsynopsisdiv></entry>
+ <entry>js2doc2dbk.xsl: insert-refinfo</entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry>E</entry>
+ <entry><refsect1></entry>
+ <entry>js2doc2dbk.xsl: generated in main class template</entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry>F</entry>
+ <entry><refpurpose></entry>
+ <entry>js2doc2dbk.xsl: generated in main class template</entry>
+ <entry></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </section>
- <figure>
+
+ <section>
<title>A Live Example</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/reference-example-explanation.png"/>
- </imageobject>
- </mediaobject>
- </figure>
+ <figure>
+ <title>A Live Example</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/reference-example-explanation.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>All of the elements in the live example are contained within a <div class="informalexample"> (in html) which comes from a <literal><informalexample role="live-example"> </literal>docbook element. That, in turn, comes from an <example> in the js2doc, which appears as something that matches this XPath query: <literal>"/js2doc/property/doc/text/example"</literal>. All the way back in the source (<literal>WEB-INF/lps/lfc/views/LzText.lzs</literal>, in this case), here's what this started out as:</para>
+ <informalexample><programlisting>/**
+ * <p>This class is used for non-editable text fields (as opposed to
+ * <tagname>inputtext</tagname>. A text field can be initalized
+ * with text content at compile time.</p>
+ *
+ * <example>
+ *
+ * &lt;canvas height="30"&gt;
+ * &lt;text&gt;Hello world!&lt;/text&gt;
+ * &lt;/canvas&gt;
+ * </example>
+ ... */
+ </programlisting></informalexample>
+
+ <para>Many, many templates are involved in generating the inside of that live example. This is so complicated that we'll leave the table format used above, and instead break it down element by element, in excruciating detail.</para>
+
+ <section><title>Element H: The embedded OpenLaszlo application</title>
+ <para>In the output HTML, there's just a little script here:
+ <informalexample><programlisting><div class="embedded-canvas"><script language="JavaScript" type="text/javascript">
+Lz.swfEmbed({url: 'programs/LFC-$10.lzx?lzt=swf', id: 'd0e165236SWF', history: false, width: 500,
+ height: 30,
+});
+</script></div></programlisting></informalexample>
+ The <literal>Lz.swfEmbed</literal> function is defined in embed-compressed.js, which is included in the page's head. The embed-compressed.js file comes from <literal>$LPS_HOME/lps/includes/embed-compressed.js</literal>, and calling <literal>Lz.swfEmbed</literal> generates an embedded flash player:
+ <informalexample><programlisting><div id="d0e165236SWFContainer" style="width: 500px; height: 30px;">
+ <embed id="d0e165236SWF" width="500" height="30" align="middle" pluginspage="http://www.macromedia.com/go/getflashplayer" type="application/x-shockwave-flash" allowscriptaccess="sameDomain" swliveconnect="true" flashvars="lzt=swf&lzr=swf8&id=d0e165236SWF" name="d0e165236SWF" wmode="window" bgcolor="#ffffff" quality="high" <emphasis>src="programs/LFC-$10.lzx?lzt=swf&lzr=swf8"</emphasis>/>
+ </div></programlisting></informalexample>
+ </para>
+ <para>The highlighted section above is the important part; it tells the flash player what content to load. In this case, it's loading the results of an http query <literal>programs/LFC-$10.lzx?lzt=swf&lzr=swf8</literal>, which, if you remember your OpenLaszlo query args, means <emphasis>compile the program named programs/LFC-$10.lzx for the swf8 runtime and return it as a compiled object, with no wrapper</emphasis>.</para>
+ <para>The file <literal>programs/LFC-$10.lzx</literal> contains just exactly the code that was in the <literal><example> </literal>tag in the lzs source. Somehow, probably in <literal>dbkpreprocessexamples.xsl</literal>, the contents of the <literal><example></literal> tag were extracted and tucked away in <literal>docs/src/build/developers/programs/LFC-$10.lzx</literal>, and then that file was copied from the build directory to the output directory, as <literal>docs/developers/programs/LFC-$10.lzx</literal>.</para>
+ <para><literal>Lz.swfEmbed</literal> was inserted by a template in <literal>common-html.xsl</literal>: <literal> <xsl:template match="programlisting[@language='lzx' and textobject/textdata/@fileref]"></literal>. This template both embeds the live example and handles the program listing and edit button, described below.</para>
+ </section>
+
+ <section><title>Element I: The program listing</title>
+ <para>The program listing seems like it should be simple, but notice that it's pretty-printed. The html output here looks like this:
+ <informalexample><programlisting><pre class="programlisting">
+ <span>
+ <span class="markup"><</span>
+ <code <emphasis>class="sgmltag-element"</emphasis>>canvas</code>
+ <code class="sgmltag-attribute">height</code>="
+ <code class="sgmltag-attvalue">30</code>"
+ <span class="markup">></span>
+ </programlisting></informalexample>
+ Notice that this <literal>sgmltag</literal> stuff isn't present in the lfcref.dbk intermediate file; it must be inserted by the docbook processing itself. Indeed, it is inserted by the docbook customization layer, in the <literal>lzx-pretty-print.xsl</literal> worksheet, which is included by <literal>common-html.xsl</literal>, which is in turn invoked in the ant task, <literal>book.html.generate</literal>.
+ </para>
+ </section>
+
+ <section><title>Element J: The edit button</title>
+ <para>The edit button ties together a few separate threads of complexity. The windows builds, in particular, are subject to troubles here. The edit button must point an external jsp (editor.jsp) at the program file associated with this program listing. We leave the details of this as an exercise to the reader, except to note that the insertion of the edit button is guarded by the statement <literal><xsl:if test="$live"></literal> which in turn consults the value of a variable computed like this:
+ <programlisting><xsl:variable name="live" select="ancestor::example[<emphasis>@role='live-example'</emphasis>] or
+ ancestor::informalexample[@<emphasis>role='live-example'</emphasis>]"/></programlisting>
+ Remember the docbook element that we found in the docbook intermediate file? <literal><informalexample role="live-example"> </literal> matches the second option in the XPath query for <literal>$live</literal> above, and that's why this example is live.
+ </para>
+
+ </section>
+ </section>
- <informaltable colsep="0" frame="none">
- <tgroup cols="2">
- <colspec colname="Region"/>
- <colspec colname="Docbook Element"/>
- <colspec colname="js2doc2dbk template"/>
- <colspec colname="js2doc Element"/>
- <thead>
- <row>
- <entry align="left">Region</entry>
- <entry align="left">Docbook Element</entry>
- <entry align="left">Relevant Templates</entry>
- <entry align="left">js2doc Element</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>H</entry>
- <entry>-</entry>
- </row>
- <row>
- <entry>I</entry>
- </row>
- <row>
- <entry>J</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
-
- <figure>
+ <section>
<title>The Attributes Table</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/reference-attributes-explanation.png"/>
- </imageobject>
- </mediaobject>
- </figure>
+
+
+ <figure>
+ <title>The Attributes Table</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/reference-attributes-explanation.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>The attributes table is generated by a set of coherent templates and patterns. There's a lot of them, but they're not very complicated. It is all run by this template, in <literal>js2doc2dbk.xsl</literal>:
+<programlisting><xsl:template match="property" mode="refentry-details"></programlisting>
+ </para>
+ <para>
+ This template calls the <literal>describe-members</literal> template repeatedly with different parameters, depending on which kind of members are being described. For the attributes table, the <literal>describe-members</literal> template calls the <literal>describe-members-grid</literal> template, which generates a <refsect2> element, which in turn generates the "Attributes" header indicated in region P. Region Q is the <thead> element of a docbook <informaltable>, and regions R, S, and T are each instances of the docbook element <row>
+
+ Each row (regions R, S, T) in the attributes table are elements of the result of this XPath, which is passed in as the <literal>members</literal> parameter to <literal>describe-members-grid</literal>:
+ <programlisting>$ivars[not &isevent;] | $svars[not &isevent;]</programlisting></para>
+ <para><literal>$ivars</literal> is a local variable containing descriptions of the instance variables for the current class:
+ <programlisting><xsl:variable name="ivars" select="&objectvalue;/property[@name='__ivars__']/object/property[&isvisible;]"/>
+ </programlisting>
+ and <literal>$svars</literal> is a local variable containing descriptions of the "setters" for the current class:
+ <programlisting>
+ <xsl:variable name="svars" select="&objectvalue;/property[@name='setters']/object/property[&isvisible;]"/>
+ </programlisting>
+ The value of these variables is a result tree fragment; it's not just the name of the variables. This becomes important when we descend into the <literal>describe-members</literal> template.</para>
+ <note>Review the table in <xref linkend="LFC-to-js2doc"/> to get a feel for why these XPath's return the desired result sets.</note>
+ <para>This all ends up down in the <literal>member-data-row</literal> template in js2doc2dbk.xsl, which fill in columns K, L, M, N, and O in the diagram above. Turn to LzText.lzs, to find where these variables were declared:</para>
+ <informalexample><programlisting>
+ /**
+ * <emphasis>@lzxtype</emphasis> numberExpression (region L)
+ * <emphasis>@modifiers</emphasis> read-only (region O)
+ */
+ var <emphasis>maxlength</emphasis>; (region K)
+ </programlisting></informalexample>
+ </section>
- <informaltable colsep="0" frame="none">
- <tgroup cols="2">
- <colspec colname="Region"/>
- <colspec colname="Docbook Element"/>
- <colspec colname="js2doc2dbk template"/>
- <colspec colname="js2doc Element"/>
- <thead>
- <row>
- <entry align="left">Region</entry>
- <entry align="left">Docbook Element</entry>
- <entry align="left">Relevant Templates</entry>
- <entry align="left">js2doc Element</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>K</entry>
- <entry>-</entry>
- </row>
- <row>
- <entry>L</entry>
- </row>
- <row>
- <entry>M</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
-
- <figure>
+ <section>
<title>Method Details</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/reference-methods-explanation.png"/>
- </imageobject>
- </mediaobject>
- </figure>
-
- <informaltable colsep="0" frame="none">
- <tgroup cols="2">
- <colspec colname="Region"/>
- <colspec colname="Docbook Element"/>
- <colspec colname="js2doc2dbk template"/>
- <colspec colname="js2doc Element"/>
- <thead>
- <row>
- <entry align="left">Region</entry>
- <entry align="left">Docbook Element</entry>
- <entry align="left">Relevant Templates</entry>
- <entry align="left">js2doc Element</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>1</entry>
- </row>
- <row>
- <entry>2</entry>
- </row>
- <row>
- <entry>3</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
-
+ <figure>
+ <title>Method Details</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/reference-methods-explanation.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>The reference for a function is generated by the call to <literal><xsl:apply-templates select="." mode="describe-member"></literal> in the template named <literal>describe-members-list</literal> in <literal>js2doc2dbk.xsl</literal>. <literal>select="." mode="desribe-member"</literal> means <emphasis>apply whatever templates match the current element in the describe-member mode.</emphasis></para>
+ <para>That takes us to the template <programlisting> <xsl:template match="initarg|property" mode="describe-member"></programlisting>
+ also in js2doc2dbk.xsl. Dancing through a variety of complex template matching, the XSL ends up examining mostly these elements of the js2doc:
+ <informalexample><programlisting>
+ <class extends="LzView">
+ <property access="private" id="LzText.tagname" <emphasis>name="tagname" value="text"></emphasis><!-- region 6 -->
+ <doc>
+ <tag name="modifiers">
+ <text>override</text>
+ </tag>
+ </doc>
+ </property>
+ ...
+ <property id="LzText.prototype.format" <emphasis>name="format"</emphasis><!-- regions 1, 2 -->
+ access="public">
+ <doc>
+ <emphasis><text>Formatted output.
+ Formats its arguments using <xref linkend="LzFormatter.formatToString"/> and sets the text of the
+ view to the result.</text></emphasis><!-- region 7 -->
+ <tag name="param">
+ <text>*... args: arguments to be formatted according to the
+ control string</text>
+ </tag>
+ </doc>
+ <function>
+ <<emphasis>parameter name="control"</emphasis> <!-- region 3, 9 -->
+ <emphasis>type="string"></emphasis> <!-- region 10 -->
+ <doc>
+<emphasis> <text>A control string where % indicates a
+subsequent argument is to be substituted</text></emphasis><!-- region 11 -->
+ </doc>
+ </parameter>
+ <emphasis> <parameter name="args"/></emphasis> <!-- region 5 -->
+ </function>
+ </property>
+
+ </programlisting></informalexample>
+ </para>
+
+ To carry this reasoning all the way back to the javascript code definining the method, in <literal>WEB-INF/lps/lfc/views/LzText.lzs</literal>:
+ <programlisting>
+ <emphasis>/**</emphasis>
+ * Formatted output.
+ * Formats its arguments using <xref
+ * linkend="LzFormatter.formatToString"/> and sets the text of the
+ * view to the result.
+ *
+ * <emphasis>@param</emphasis> string control: A control string where % indicates a
+ * subsequent argument is to be substituted
+ *
+ *<emphasis> @param</emphasis> *... args: arguments to be formatted according to the
+ * control string
+ */
+ function <emphasis>format</emphasis> (control, args) {
+ this.setText(this.formatToString.apply(this, arguments));
+ }
+ </programlisting>
+
+ </section>
</chapter>
More information about the Laszlo-checkins
mailing list