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 [EMAIL PROTECTED] 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>
_______________________________________________
Laszlo-checkins mailing list
[email protected]
http://www.openlaszlo.org/mailman/listinfo/laszlo-checkins
