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