[Laszlo-checkins] r7673 - openlaszlo/trunk/docs/src/developers
ben@openlaszlo.org
ben at openlaszlo.org
Thu Dec 27 13:57:35 PST 2007
Author: ben
Date: 2007-12-27 13:57:29 -0800 (Thu, 27 Dec 2007)
New Revision: 7673
Modified:
openlaszlo/trunk/docs/src/developers/doc-toolchain.dbk
Log:
Change 20071227-ben-y by ben at slim.local on 2007-12-27 13:55:42 PST
in /Users/ben/src/svn/openlaszlo/trunk
for http://svn.openlaszlo.org/openlaszlo/trunk
Summary: Additional content for the chapter describing the doctools
Documentation:
Added examples of many different id's and explained their structure.
Rearranged the js2doc2dbk section.
Modified: openlaszlo/trunk/docs/src/developers/doc-toolchain.dbk
===================================================================
--- openlaszlo/trunk/docs/src/developers/doc-toolchain.dbk 2007-12-27 06:00:04 UTC (rev 7672)
+++ openlaszlo/trunk/docs/src/developers/doc-toolchain.dbk 2007-12-27 21:57:29 UTC (rev 7673)
@@ -76,6 +76,11 @@
the reference. The bottom row is how we build the developer's guide. The final transformation,
labeled docbook processing, turns intermediate files into the output html that you are probably
reading right now. </para>
+
+ <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 id="reference-toolchain-source-to-doc">
<title>The Reference Toolchain: From Source to Documentation</title>
@@ -236,6 +241,70 @@
</property>
</programlisting>
</para>
+ <para>A note on id's: the <literal>id</literal> of a property in the js2doc structure is a globally-unique identifier. (At least, it is globally unique if the tools are all working correctly.) The form of the id is based on the semantics of the thing-it's-identifying. A few examples will clarify the patterns: </para>
+ <informaltable colsep="0" frame="none">
+ <tgroup cols="4">
+ <colspec colname="Example"/>
+ <colspec colname="Meaning"/>
+ <thead>
+ <row>
+ <entry align="left">Example id</entry>
+ <entry align="left">Meaning</entry>
+ <entry align="left">Comments</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>id="LzView"</literal></entry>
+ <entry>The <literal>LzView</literal> class</entry>
+ <entry>The use of capital "Lz" indicates that the class LzView is part of the LFC. </entry>
+ </row>
+ <row>
+ <entry><literal>id="LzView.prototype.containsPt"</literal></entry>
+ <entry>The <literal>containsPt</literal> method of <literal>LzView</literal></entry>
+ <entry>The presence of <literal>prototype</literal> means that the property being identified is present on all instances of the class. The use of capital "Lz" indicates that the class LzView is part of the LFC. </entry>
+ </row>
+ <row>
+ <entry><literal>id="tag.method"</literal></entry>
+ <entry>The <literal>method</literal> tag</entry>
+ <entry>The <literal>tag.</literal> prefix means that the class being identified is a tag, part of the language. </entry>
+ </row>
+
+ <row>
+ <entry><literal>id="lz.basewindow"</literal></entry>
+ <entry>The <literal><basewindow></literal> class</entry>
+ <entry>The prefix <literal>lz.</literal> means that the class being identified is a vanilla tag, not part of the LFC.</entry>
+ </row>
+
+ <row>
+ <entry><literal>id="lz.basewindow.prototype.setWindowFocus"</literal></entry>
+ <entry>The <literal>setWindowFocus</literal> method of the <literal>basewindow</literal> class </entry>
+ <entry>The presence of <literal>prototype</literal> means that the property being identified is present on all instances of the class.</entry>
+ </row>
+ <row>
+ <entry><literal>id="lz.basewindow.__ivars__.minwidth"</literal></entry>
+ <entry>The <literal>minwidth</literal> attribute of an instance of the <literal>basewindow</literal> class </entry>
+ <entry>The <literal>__ivars__</literal> indicates that the property being identified is present on each individual instance of the <literal>basewindow</literal> class.</entry>
+ </row>
+ <row>
+ <entry><literal>id="LzBrowser+dhtml"</literal></entry>
+ <entry>the <literal>LzBrowswer</literal> class, as it exists only in the dhtml runtime.</entry>
+ <entry>The <literal>+<runtime></literal> suffix indicates runtime-specific behavior.</entry>
+ </row>
+ <row>
+ <entry><literal>id="LzBrowser+swf7+swf8+swf9"</literal></entry>
+ <entry>the <literal>LzBrowswer</literal> class, as it exists in the swf7, swf8, and swf9 runtimes.</entry>
+ <entry>Several runtimes can be appended to a class name to indicate that this behavior applies to all of the specified runtimes..</entry>
+ </row>
+ <row>
+ <entry><literal>id="services.platform.dhtml.LzKeys.js"</literal></entry>
+ <entry>the file named <literal>LzKeys.js</literal></entry>
+ <entry>This is an id for a <unit>, not a <property> and refers to a file, not an API element</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ <para>Throughout the entire toolchain, when you want to refer to a particular class, method, attribute, event, or file, you can specify it by id. For example, to link to the reference for the class <literal>basewindow</literal>, insert <literal><xref linkend="lz.basewindow"/></literal> which yields this result: <xref linkend="lz.basewindow"/></para>
</section>
<section id="lzx2js2doc">
<title>lzx2js2doc</title>
@@ -284,7 +353,7 @@
intermediate file generated by the reference build.) </para>
</section>
- <section>
+ <section id="js2doc2dbk">
<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>
@@ -310,148 +379,39 @@
</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>Now consider this step concretely. This is the core of the documentation toolchain, so it is worth investigating in detail. First you must learn to navigate and understand the important stylesheets, which is the subject of the next section, <xref linkend="reading-js2doc2dbk-stylesheets"/></para>
+ <section id="reading-js2doc2dbk-stylesheets">
+ <title>Reading js2doc2dbk Stylesheets</title>
<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>
+ <section id="idioms-and-entities"><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>
+ <section id="main-stylesheets"><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>
+ <section id="utility-stylesheets"><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>
+ <section id="modes-and-roles"><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>
+ <section id="js2doc2dbk-params"><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 id="js2doc2dbk-indices"><title>Indicies, Appendices, Cross-references, etc</title>
</section>
- <section><title>OpenLaszlo-specific docbook elements</title>
+ <section id="js2doc2dbk-laszlo-specific"><title>OpenLaszlo-specific docbook elements</title>
<itemizedlist>
<listitem>Embedded live examples</listitem>
</itemizedlist>
</section>
- <section>
+ <section id="very-complex-templates">
<title>Very complex templates</title>
<itemizedlist>
<listitem>Subclass and superclass chains</listitem>
@@ -459,8 +419,129 @@
</itemizedlist>
</section>
</section>
+ <section id="js2doc2dbk-walkthrough">
+ <title>js2doc2dbk walkthrough</title>
+ <note>Get a beverage and a comfortable chair, then turn off the phone and lock the door. The next section is the very heart of the reference toolchain, and understanding it requires holding a lot of context in your head all at once.</note>
+ <para>WORK HERE NOW</para>
+ </section>
+ <section id="docbook-output-fragments">
+ <title>Fragments of docbook output from js2doc2dbk</title>
+ <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.) </para>
+ </section>
+ </section>
- <section>
+ <section id="docbook-to-output">
<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>
@@ -472,7 +553,7 @@
</section>
- <section>
+ <section id="backwards-transformation">
<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
can be traced back to their origins in the sources.</para>
@@ -481,7 +562,7 @@
</section>
</section>
- <section>
+ <section id="developers-guide-toolchain">
<title>The Developer's Guide Toolchain</title>
<section><title>Important Stylesheets</title>
<itemizedlist>
@@ -492,16 +573,13 @@
</section>
</section>
- <section>
+ <section id="workflow-details">
<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>
+ <section id="directory-structure">
<title>Directory Structure</title>
<itemizedlist>
<listitem>docs/src/
@@ -541,7 +619,7 @@
</section>
- <section>
+ <section id="how-ant-drives">
<title>How Ant Drives the Transformations</title>
</section>
More information about the Laszlo-checkins
mailing list