[Laszlo-checkins] r7671 - in openlaszlo/trunk/docs/src/developers: . images
ben@openlaszlo.org
ben at openlaszlo.org
Wed Dec 26 18:10:41 PST 2007
Author: ben
Date: 2007-12-26 18:10:36 -0800 (Wed, 26 Dec 2007)
New Revision: 7671
Added:
openlaszlo/trunk/docs/src/developers/images/js2doc2dbk.graffle
openlaszlo/trunk/docs/src/developers/images/js2doc2dbk.png
Modified:
openlaszlo/trunk/docs/src/developers/doc-toolchain.dbk
Log:
Change 20071226-ben-7 by ben at slim.local on 2007-12-26 18:06:19 PST
in /Users/ben/src/svn/openlaszlo/trunk
for http://svn.openlaszlo.org/openlaszlo/trunk
Summary: Checkpointing more work on doctools explanatory chapter
Documentation:
Filled out a section about how js2doc intermediate files are
transformed into docbook files. This is the second major phase
of the documentation toolchain. (The remaining major phase is
docbook to html.)
A new diagram helps focus attention on this phase of the transformation.
This checkin also includes some advice on how to learn and
modify the documentation toolchain.
This checkin also adds emphasis to fragments of the program
listings.
Tests:
Modified: openlaszlo/trunk/docs/src/developers/doc-toolchain.dbk
===================================================================
--- openlaszlo/trunk/docs/src/developers/doc-toolchain.dbk 2007-12-27 02:10:13 UTC (rev 7670)
+++ openlaszlo/trunk/docs/src/developers/doc-toolchain.dbk 2007-12-27 02:10:36 UTC (rev 7671)
@@ -114,10 +114,9 @@
<para>
<literal>langref.xml</literal> is itself a js2doc file, so it doesn't need any processing to
go into the next phase (js2doc2dbk) of the reference toolchain. Consider the "method" tag. An example of a method tag would be the <literal>moveWindow</literal> method in the example in <xref linkend="tutorial-methods"/>. We're not talking about documenting an <emphasis>instance of the method tag</emphasis>; rather, we're talking about documenting <emphasis>the method tag itself:</emphasis> Here's the js2doc fragment
- describing the method tag:</para>
- <programlistingco>
+ describing the method tag:</para>
<programlisting language="lzx">
- <property id="tag.method" topic="LZX" subtopic="Basics" access="public">
+ <property<emphasis> id="tag.method"</emphasis> topic="LZX" subtopic="Basics" access="public">
<doc>
<tag name="shortdesc"><text>Attaches a function or event handler to an object or class.</text></tag>
<tag name="lzxname"><text>method</text></tag>
@@ -180,16 +179,6 @@
</class>
</property>
</programlisting>
- <areaspec> <!-- these callouts aren't working, but I'm not sure why bshine 12.25.2007 -->
- <area units="other" otherunits="/property[1]/@name"/>
- </areaspec>
- <areaspec>
- <area units="other" otherunits="/property[1]/doc/text"/>
- </areaspec>
- <areaspec>
- <area units="other" otherunits="/property[1]/function/parameter"/>
- </areaspec>
- </programlistingco>
Later in this document, we'll see how this js2doc intermediate fragment becomes the reference
page for the method tag. </section>
@@ -203,9 +192,9 @@
<programlisting>
/**
* returns true if the point is contained within the view.
- * @param Number x: an x value relative to the this view's coordinates
- * @param Number y: an y value relative to the this view's coordinates
- * @return Boolean: boolean indicating whether or not the point lies within the view
+ * <emphasis>@param Number x: an x value relative to the this view's coordinates</emphasis>
+ * <emphasis>@param Number y: an y value relative to the this view's coordinates</emphasis>
+ * <emphasis>@return Boolean: boolean indicating whether or not the point lies within the view</emphasis>
*/
function containsPt( x,y ) {
return (((this.getAttribute("height")>= y) && (y >= 0)) &&
@@ -228,19 +217,19 @@
<text>returns true if the point is contained within the view.</text>
</doc>
<function>
- <parameter name="x" type="Number">
+ <emphasis> <parameter name="x" type="Number"></emphasis>
<doc>
- <text>an x value relative to the this view's coordinates</text>
+ <emphasis> <text>an x value relative to the this view's coordinates</text></emphasis>
</doc>
</parameter>
- <parameter name="y" type="Number">
+ <emphasis><parameter name="y" type="Number"></emphasis>
<doc>
- <text>an y value relative to the this view's coordinates</text>
+ <emphasis><text>an y value relative to the this view's coordinates</text></emphasis>
</doc>
</parameter>
- <returns type="Boolean">
+ <emphasis> <returns type="Boolean"></emphasis>
<doc>
- <text>boolean indicating whether or not the point lies within the view</text>
+ <emphasis><text>boolean indicating whether or not the point lies within the view</text></emphasis>
</doc>
</returns>
</function>
@@ -263,7 +252,7 @@
<programlisting><!--- Brings the window to front when it has the
windowfocus and sets the 'state' to 2, the selected state.
Subclasses may override to create different behavior
- at param Boolean windowfocus: whether the window should be selected
+<emphasis>@param Boolean windowfocus: whether the window should be selected</emphasis>
-->
<method name="setWindowFocus" args="windowfocus"></programlisting>
<para>This example shows the doc-comment for the method <literal>setWindowFocus</literal> of
@@ -273,7 +262,7 @@
xsl worksheet, <literal>$LPS_HOME/docs/src/xsl/lzx2js2doc.xsl</literal>, which discovers the
doc comments in the lzx source, parses them, and outputs js2doc files. The js2doc output for
the setWindowFocus method above looks like this:
- <programlisting><property id="lz.basewindow.prototype.setWindowFocus" name="setWindowFocus" access="public">
+ <programlisting><property <emphasis>id="lz.basewindow.prototype.setWindowFocus"</emphasis> name="setWindowFocus" access="public">
<function>
<parameter name="windowfocus" type="Boolean">
<doc>
@@ -283,11 +272,11 @@
</function>
<doc>
<tag name="lzxname">
- <text>setWindowFocus</text>
+ <text><emphasis>setWindowFocus</emphasis></text>
</tag>
- <text>Brings the window to front when it has the
+ <text><emphasis>Brings the window to front when it has the
windowfocus and sets the 'state' to 2, the selected state.
- Subclasses may override to create different behavior</text>
+ Subclasses may override to create different behavior</emphasis></text>
</doc>
</property>
</programlisting>
@@ -297,13 +286,192 @@
<section>
<title>Turning the API into the Reference: js2doc2dbk</title>
+ <para>So far, we've seen how the js2doc intermediate form is generated from various source files. The next step in the transformation is to build a docbook representation of the reference material. Let's look at the detailed diagram for this transformation:
+ <informalfigure>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/js2doc2dbk.png"/>
+ </imageobject>
+ </mediaobject>
+ </informalfigure>That looks simple and straightforward, with just one path through the transformation. Actually, this transformation is the most complicated part of the documentation toolchain. The complexity is all located within the js2doc2dbk XSL transformation.</para>
+ <para>Consider this step abstractly: <emphasis>From a large, structured set of information, construct another large, structured set of information.</emphasis> The linear order in which XSL transformations execute isn't really important, but it helps to think of this transformation procedurally. (XSL's functional programming style can be very intimidating; it helps to trace it through as if it were procedural.) </para>
+ <orderedlist>
+ <listitem>For each section of the reference, create a docbook file to contain the reference docbook content for that section. (Sections are listed in <literal>docs/src/reference/index.dbk</literal>, and the section docbook files are generated in <literal>docs/src/build/reference/[lfcref.dbk|lzxref.dbk|compref.dbk|...]</literal>.)
+ <orderedlist>
+ <listitem>Identify the pages in that section.</listitem>
+ <listitem>For each page in the reference:
+ <orderedlist>
+ <listitem>Describe the class by name, inheritance chain, and introductory text.</listitem>
+ <listitem>List all of the attributes for that class. Also list all of the inherited attributes for that class.</listitem>
+ <listitem>List all of the methods for that class. Also list all of the inherited methods for that class.</listitem>
+ <listitem>List all of the events for that class. Also list all of the inherited events for that class.</listitem>
+ </orderedlist>
+ </listitem>
+ </orderedlist>
+ </listitem>
+ </orderedlist>
+ <para>The docbook output at this step is a semantic representation of the content we'll see on the output reference HTML pages. It is almost but not quite a listing of the words that will appear in the output HTML, with lots of semantic markup. The markup will give the final stage in the transformation (docbook to html) information necessary to format the output nicely. For example, consider this fragment of <literal>docs/src/build/reference/lfcref.dbk</literal>, describing the <view> tag: </para>
+ <informalexample>
+ <programlisting>
+ <refentry <emphasis>xreflabel="&lt;view&gt;" id="LzView"</emphasis>>
+ <anchor id="tag.view"/>
+ <refmeta>
+ <refentrytitle>&lt;view&gt;</refentrytitle>
+ </refmeta>
+ <refnamediv>
+ <refdescriptor>
+ <indexterm zone="LzView">
+ <primary>LzView</primary>
+ <secondary>Described</secondary>
+ <seealso>view</seealso>
+ </indexterm>
+ <indexterm zone="LzView">
+ <primary>view</primary>
+ <see>LzView</see>
+ </indexterm>
+ <indexterm zone="views.LaszloView.lzs">
+ <primary>LzView</primary>
+ <secondary>Declared in</secondary>
+ </indexterm>&lt;view&gt;</refdescriptor>
+ <refname role="javascript">LzView</refname>
+ <refname role="lzx">view</refname>
+ <refpurpose>The most basic viewable element.</refpurpose>
+ </refnamediv>
+ <refsynopsisdiv>
+ <refsect1>JavaScript: LzView</refsect1>
+ <refsect1>Extends <xref linkend="LzNode"/> » </refsect1>
+ </refsynopsisdiv>
+ </programlisting>
+ </informalexample>
+ <para>Also consider this fragment of the same file, describing the <literal>containsPt</literal> method:</para>
+ <informalexample>
+ <programlisting>
+ <varlistentry>
+ <term <emphasis>xreflabel="LzView.containsPt()"</emphasis> id="LzView.prototype.containsPt">
+ <indexterm zone="LzView.prototype.containsPt">
+ <primary>containsPt</primary>
+ </indexterm>containsPt()</term>
+ <listitem>
+ <refsect3>
+ <<emphasis>methodsynopsis</emphasis> language="javascript">
+ <methodname>view.containsPt</methodname>
+ <methodparam>
+ <emphasis><parameter>x</parameter></emphasis>
+ <emphasis><type role="javascript">Number</type></emphasis>
+ </methodparam>
+ <methodparam>
+ <emphasis><parameter>y</parameter></emphasis>
+ <emphasis><type role="javascript">Number</type></emphasis>
+ </methodparam>
+ </methodsynopsis>
+ </refsect3>
+ <refsect3><emphasis>returns true if the point is contained within the view.</emphasis></refsect3>
+ <refsect3>
+ <informaltable pgwide="1" rowsep="0" colsep="0" frame="none">
+ <tgroup cols="3">
+ <colspec colname="Name"/>
+ <colspec colname="Type"/>
+ <colspec colname="Description"/>
+ <thead>
+ <row>
+ <entry align="left">Parameter Name</entry>
+ <entry align="left">Type</entry>
+ <entry align="left">Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+<emphasis> <entry class="parametername">x</entry>
+ <entry>Number</entry>
+ <entry>an x value relative to the this view's coordinates</entry>
+</emphasis> </row>
+ <row>
+<emphasis> <entry class="parametername">y</entry>
+ <entry>Number</entry>
+ <entry>an y value relative to the this view's coordinates</entry>
+</emphasis> </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </refsect3>
+ <refsect3>
+ <informaltable pgwide="1" rowsep="0" colsep="0" frame="none">
+ <tgroup cols="2">
+ <colspec colname="Type"/>
+ <colspec colname="Description"/>
+ <thead>
+ <row>
+ <entry align="left" nameend="Description" namest="Type">Returns</entry>
+ </row>
+ <row>
+ <entry align="left">Type</entry>
+ <entry align="left">Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>Boolean</entry>
+ <entry>boolean indicating whether or not the point lies within the view</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </refsect3>
+ </listitem>
+ </varlistentry>
+ </programlisting>
+ </informalexample>
+ <para>Each nugget of information in those two docbook fragments can be found in the js2doc output generated in the previous steps of the transformation pipeline. To understand how, a detailed walkthrough of the many stylesheets that make up the jsdoc2dbk transformation is necessary. A developer who wishes to understand this transformation must simply sit down and follow the code himself. (This writer does not know what all of the templates in docs/src/xsl do, or whether some of them are invoked at all.) This document will provide an overview map of what happens in which stylesheets, and which templates are important, as well as a guide to some of the idioms and OpenLaszlo-specific patterns employed herein. </para>
+ <para>The stylesheets in <literal>docs/src/xsl</literal> participate in all of the xsl transformations in the documentation toolchain: from lzx to js2doc, from js2doc to dbk, and from dbk to html (details on this later). When looking at a particular stylesheet, or looking <emphasis>for</emphasis> a particular template, it is useful to consider which stage of the transformation interests you. </para>
+ <section><title>Idioms and Entities</title>
+ <para>Each xsl stylesheet begins by declaring several entities. These are XPath macros which make the templates that follow more succinct and hopefully readable. Take the time to read these over and grasp their meaning. </para>
+ </section>
+ <section><title>Main Stylesheets and Templates in js2doc2dbk</title>
+ <para>The main transformation lives in <literal>docs/src/xsl/js2doc2dbk.xsl</literal>, and within that, the main template for generating a complete reference page is <literal><xsl:template match="property" mode="refentry"></literal></para>
+ </section>
+ <section><title>Utility Stylesheets and Templates in js2doc2dbk</title>
+ <itemizedlist>
+ <listitem>docs/src/xsl/js2doc2dbk/synopsis.xsl</listitem>
+ <listitem>docs/src/xsl/js2doc2dbk/utilities.xsl</listitem>
+ </itemizedlist>
+
+ </section>
+ <section><title>Modes and Roles</title>
+ <para>Modes and roles are attributes of xsl templates which provide another way to slice the same information, akin to double-dispatch: there are several ways to handle an element, and the appropriate one for a given moment depends both on the element (primary dispatch by XPath matching of the template) and on the current mode (secondary matching by mode). A single template may call other templates in various modes. This pattern is pervasive in the js2doc2dbk stylesheets, but it is not used much currently. It supports building <emphasis>multiple references from the same js2doc</emphasis>: different references for the swf runtime versus the dhtml runtime, different references for the public api's than for internal api's, and so on. In particular, the <literal>detailed-synopsis</literal> mode is unused.</para>
+ </section>
+ <section><title>Parameters for controlling the js2doc2dbk transformation</title>
+ <itemizedlist>
+ <listitem>generating warnings, errors, fixme's</listitem>
+ </itemizedlist>
+ </section>
+ <section><title>Indicies, Appendices, Cross-references, etc</title>
+ </section>
+ <section><title>OpenLaszlo-specific docbook elements</title>
+ <itemizedlist>
+ <listitem>Embedded live examples</listitem>
+ </itemizedlist>
+ </section>
+ <section>
+ <title>Very complex templates</title>
+ <itemizedlist>
+ <listitem>Subclass and superclass chains</listitem>
+ <listitem>Attributes list (with lzxtype, final, read-only, initialize-only)</listitem>
+ </itemizedlist>
+ </section>
</section>
<section>
<title>Docbook to Output, at Last!</title>
+ <para>The docbook customization layer. See <ulink linkend="http://www.sagehill.net/docbookxsl/">DocBook XSL: The Complete Guide by Bob Stayton</ulink>. </para>
+ <itemizedlist>
+ <listitem>common-html.xsl</listitem>
+ <listitem>conditional-html.xsl</listitem>
+ <listitem>styles.css</listitem>
+ <listitem>lzx-pretty-print.css</listitem>
+ </itemizedlist>
+
</section>
- <para>the docbook customization layer. See stayton. </para>
-
+
<section>
<title>The Backwards Transformation: From Reference Page to Source</title>
<para>In this section, we will show where several elements on the end product reference page
@@ -315,10 +483,23 @@
<section>
<title>The Developer's Guide Toolchain</title>
+ <section><title>Important Stylesheets</title>
+ <itemizedlist>
+ <listitem>dguide.xsl</listitem>
+ <listitem>dbkpreprocessexamples.xsl</listitem>
+ <listitem>lzx-pretty-print.xsl</listitem>
+ </itemizedlist>
+ </section>
</section>
<section>
<title>Workflow Details</title>
+
+ <section><title>Figuring things out</title>
+ <para>The docbook toolchain is long and complicated, and the builds take upwards of ten minutes, as much as 40 minutes for a complete build. Do not allow this slow debug-edit-compile loop to dictate the pace of your progress! This author found that it was very effective to work on well-formed subsets of the data, and transform those subsets through a driver stylesheet containing only the templates of interest. With this technique, a debug-edit-compile iteration can take seconds, not hours. The source code includes a simple driver, aptly named <literal>docs/src/xsl/simple-driver.xsl</literal>, which is currently configured to investigate methods of <literal>LzBrowser</literal> when applied to <literal>LaszloLibrary-verbose.js2doc</literal>.</para>
+ <para>A simpler way of figuring things out is just to run XPath queries against <literal>LaszloLibrary-verbose.js2doc</literal> Various XML editors support live XPath queries, including <ulink linkend="http://www.oxygenxml.com/">Oxygen XML Editor</ulink></para>
+ </section>
+
<section>
<title>Directory Structure</title>
@@ -352,6 +533,7 @@
<listitem>reference/ where the js2doc output is joined together into LaszloLibrary-verbose.js2doc, and where the processed reference guide docbook files go after they've had the examples and callouts inserted</listitem>
</itemizedlist>
</listitem>
+ <listitem>xsl/ (holds the xsl templates for both the conversion from lzx to js2doc, and from js2doc to docbook)</listitem>
</itemizedlist>
</listitem>
Added: openlaszlo/trunk/docs/src/developers/images/js2doc2dbk.graffle
Property changes on: openlaszlo/trunk/docs/src/developers/images/js2doc2dbk.graffle
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: openlaszlo/trunk/docs/src/developers/images/js2doc2dbk.png
Property changes on: openlaszlo/trunk/docs/src/developers/images/js2doc2dbk.png
___________________________________________________________________
Name: svn:mime-type
+ image/png
More information about the Laszlo-checkins
mailing list