[Laszlo-checkins] r7663 - in openlaszlo/trunk/docs/src/developers: . images
ben@openlaszlo.org
ben at openlaszlo.org
Fri Dec 21 21:32:54 PST 2007
Author: ben
Date: 2007-12-21 21:32:44 -0800 (Fri, 21 Dec 2007)
New Revision: 7663
Added:
openlaszlo/trunk/docs/src/developers/images/doc_overview_simple.png
openlaszlo/trunk/docs/src/developers/images/doc_reference_details.png
Modified:
openlaszlo/trunk/docs/src/developers/doc-toolchain.dbk
Log:
Change 20071221-ben-X by ben at slim.local on 2007-12-21 21:24:33 PST
in /Users/ben/src/svn/openlaszlo/trunk
for http://svn.openlaszlo.org/openlaszlo/trunk
Summary: Add explanation of first part of reference doc build
Documentation:
This checkin fills in the documentation toolchain chapter in the
developer's guide with an overview and then with a walkthrough of
each of the code entry points into the reference build data flow,
with examples of the relevant source and intermediate products.
I've also added two diagrams based on the doc-toolchain.graffle
dataflow diagram; the first, doc_overview_simple.png, is a
much simpler (but less accurate) representation of the doctools.
The second, doc_reference_details.png, is a simplified magnification
of three strands of the reference guide workflow.
We're keeping the original, highly-detailed data flow diagram,
of course.
Release Notes:
Details:
Tests:
Modified: openlaszlo/trunk/docs/src/developers/doc-toolchain.dbk
===================================================================
--- openlaszlo/trunk/docs/src/developers/doc-toolchain.dbk 2007-12-22 05:29:42 UTC (rev 7662)
+++ openlaszlo/trunk/docs/src/developers/doc-toolchain.dbk 2007-12-22 05:32:44 UTC (rev 7663)
@@ -1,20 +1,255 @@
<?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 2007 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-toolchain">
-<title>Toolchain Overview</title>
-
-<figure>
- <title>Toolchain</title>
- <mediaobject>
- <imageobject><imagedata fileref="images/doc-toolchain.png"/></imageobject>
- </mediaobject>
-</figure>
-
+
+ <title>The Documentation Toolchain</title>
+ <para>The documentation for OpenLaszlo, including this chapter of the developer's guide, is built with a federation of tools and technologies based on Java and XML. To understand the doc toolchain at all, you'll need to be comfortable with the fundamental concepts employed in XSLT 1.0 and ant. The toolchain is too complicated to understand all at once, as you can see from the figure below. This chapter will break it down into two processes that are hopefully easier to grasp: how the developer's guide is built, as a fairly straightforward docbook, and then how the reference guide is built, with a much trickier process. This chapter will then look at the same process in reverse, to identify where the pieces of a reference page originate. Finally, this chapter will touch on the other parts of the doc toolchain, including the server API and the language reference.</para>
+ <para>Some vocabulary will simplify the discussion:</para>
+ <variablelist>
+ <varlistentry>
+ <term>js2doc</term>
+ <listitem>Think of this as the xml schema to describe JavaScript 2. The '2' in the term <literal>js2doc</literal> refers to the version of javascript, not to a transformation. "js2doc files" refers to a collection of xml files which follow the js2doc schema.</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>LFC</term>
+ <listitem>Laszlo Foundation Classes. For the purposes of the documentation toolchain, the LFC consists of classes which are written in JavaScript.</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Developer's Guide</term>
+ <listitem>The Developer's Guide, which you are reading, is a text about developing with OpenLaszlo. It is mostly written as sentences and paragraphs by human technical writers. The developer's guide is where one would look when trying to figure out how to improve startup performance, how to debug a live application, or why to choose a SOLO deployment.</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Reference Guide</term>
+ <listitem>The Reference Guide is a detailed reference manual of all of the public API's in OpenLaszlo. It is where one would look to find out what methods are available on <literal>drawview</literal>, or what events a <literal>button</literal> might generate.</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>doc-comment</term>
+ <listitem>The term doc-comment is shorthand to refer to to a special comment in a source file whose purpose is to document the nearby code. </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ <figure>
+ <title>Documentation Toolchain</title>
+ <mediaobject>
+ <imageobject><imagedata fileref="images/doc-toolchain.png"/></imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>That's a rather intimidating diagram. Let's simplify it a bit:
+ <informalfigure><mediaobject><imageobject>
+ <imagedata fileref="images/doc_overview_simple.png"></imagedata>
+ </imageobject>
+ </mediaobject>
+ </informalfigure>Much better: two rows, unified in one final step. The top row is how we build 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>The Reference Toolchain</title>
+ <section>
+ <title>The Forwards Transformation: Source to Documentation</title>
+ <section>
+
+ <title>Documentation in the Source</title>
+ <para>Let's look at that top row in more detail; it becomes three rows:
+ <informalfigure><mediaobject><imageobject>
+ <imagedata fileref="images/doc_reference_details.png"></imagedata>
+ </imageobject>
+ </mediaobject></informalfigure>
+ </para>
+ <para>The next three sections walk through each of the three paths in the diagram above: from langref.xml, from javascript code, and from lzx source code, all to the js2doc intermediate format.</para>
+
+ <section id="langref.xml">
+ <title>Basic Language Constructs as js2doc</title>
+ <para><literal>langref.xml</literal> is an xml file which documents the lzx language itself: things like attribute tag, the class tag, the event and handler tags, and so on. Find it in the source distribution at <literal>$LPS_HOME/docs/src/reference/langref.xml</literal>.</para>
+ <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. Here's the js2doc fragment describing the method tag:</para>
+ <programlisting>
+ <property id="tag.method" 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>
+ <text>
+ <p>Attaches a method to the object that contains this element. The
+ method must have a <attribute>name</attribute>.</p>
+
+ <p>The <attribute>name</attribute> attribute
+ allows the method to be invoked from JavaScript with this name.
+ For example, if a method is defined via:</p>
+
+ <example extract="false">
+ &lt;view id="obj"&gt;
+ &lt;method name="f" args="a, b"&gt;
+ return a+b;
+ &lt;/method&gt;
+ &lt;/view&gt;
+ </example>
+
+ <p>
+ then script code
+ can invoke <code>obj.f(1, 2)</code> to add two
+ numbers.</p>
+ </text>
+ </doc>
+ <class>
+ <property name="__ivars__" access="public">
+ <object>
+ <property name="name" modifiers="final">
+ <doc>
+ <tag name="lzxtype"><text>token</text></tag>
+ <text>The name of the method.</text>
+ </doc>
+ </property>
+ <property name="event" type="String">
+ <doc>
+ <text>The name of the event that this method is invoked in response
+ to.</text>
+ </doc>
+ </property>
+ <property name="reference" type="Object">
+ <doc>
+ <tag name="lzxdefault"><text>"this"</text></tag>
+ <tag name="lzxtype"><text>reference</text></tag>
+ <text>If this attribute is present, it is a JavaScript expression
+ that evaluates to an object. The code in this method executes
+ when this object sends the event named by the @a{event}
+ attribute. This attribute may be present only if
+ the @a{event} attribute is present too.</text>
+ </doc>
+ </property>
+ <property name="args" type="String" modifiers="final">
+ <doc>
+ <text>The parameter names of this method. The value of this attribute
+ is a comma-separated list of JavaScript identifiers.</text>
+ </doc>
+ </property>
+ </object>
+ </property>
+ </class>
+ </property>
+ </programlisting>
+ Later in this document, we'll see how this js2doc intermediate fragment becomes the reference page for the method tag.
+ </section>
+
+ <section id="LFC-to-js2doc">
+ <title>JavaScript to js2doc</title>
+ <para>The LFC (Laszlo Foundation Classes) are written in JavaScript, and their documentation is inline with their implementation. <xref linkend="LzView">LzView</xref> is an example of an LFC class. In javascript, comments are indicated with the javadoc-style comment, beginning with a slash followed by two asterisks. Here's an example, from LaszloView.lzs (<literal>$LPS_HOME/WEB-INF/lps/lfc/views/LaszloView.lzs</literal>):</para>
+ <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
+ */
+ function containsPt( x,y ) {
+ return (((this.getAttribute("height")>= y) && (y >= 0)) &&
+ ((this.getAttribute("width")>= x) && (x >= 0)));
+ }
+ </programlisting>
+ <para>Turning those structured comments into the js2doc intermediate format is achieved by a java application called (not very helpfully) js2doc. This application is found in the source tree in <literal>WEB-INF/lps/server/src/org/openlaszlo/js2doc</literal>. <emphasis>It's really quite clever: the js2doc tool uses exactly the same parsing code as the OpenLaszlo script compiler.</emphasis> Instead of emitting swf bytecodes representing the class as defined in the parsed javascript, js2doc emits an xml description of the API defined in the parsed javascript -- <emphasis>complete with the comments embedded as documentation!</emphasis></para>
+ <para>This will make more sense when we look at the js2doc output from the containsPt code above:
+ <programlisting>
+ <property id="LzView.prototype.containsPt" name="containsPt">
+ <doc>
+ <text>returns true if the point is contained within the view.</text>
+ </doc>
+ <function>
+ <parameter name="x" type="Number">
+ <doc>
+ <text>an x value relative to the this view's coordinates</text>
+ </doc>
+ </parameter>
+ <parameter name="y" type="Number">
+ <doc>
+ <text>an y value relative to the this view's coordinates</text>
+ </doc>
+ </parameter>
+ <returns type="Boolean">
+ <doc>
+ <text>boolean indicating whether or not the point lies within the view</text>
+ </doc>
+ </returns>
+ </function>
+ </property>
+ </programlisting>
+ </para>
+ </section>
+ <section id="lzx2js2doc">
+ <title>lzx2js2doc</title>
+ <para>Most code which application developers write, and which contributors will examine, is lzx code. lzx is the language in which all of the components are described, all of the extensions, all of the utilities, and so forth. When you think about developing an OpenLaszlo application, you are probably thinking about writing lzx code. </para>
+ <para>The source for <xref linkend="lz.basewindow">basewindow</xref> (<literal>lps/components/base/basewindow.lzx</literal>) is a typical lzx file for which the doctools generate documentation. In an lzx file, documentation comments are set apart by beginning an XML comment with three hyphens, instead of the customary two. <xref linkend="js2doc-reference"/> describes the available annotations within a doc comment in lzx.</para>
+ <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
+-->
+<method name="setWindowFocus" args="windowfocus"></programlisting>
+<para>This example shows the doc-comment for the method <literal>setWindowFocus</literal> of the <literal>basewindow</literal> class. It indicates that there is a single parameter, <literal>windowfocus</literal> which should be a Boolean.</para>
+ <para>lzx2js2doc processes commented lzx source files into js2doc intermediate files. It is an 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">
+ <function>
+ <parameter name="windowfocus" type="Boolean">
+ <doc>
+ <text>whether the window should be selected</text>
+ </doc>
+ </parameter>
+ </function>
+ <doc>
+ <tag name="lzxname">
+ <text>setWindowFocus</text>
+ </tag>
+ <text>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>
+ </doc>
+ </property>
+ </programlisting>
+ (This fragment is in $LPS_HOME/docs/src/build/reference/LaszloLibrary-verbose.js2doc, an intermediate file generated by the reference build.)
+ </para>
+ </section>
+ </section>
+
+ <section>
+ <title>js2doc files: the Intermediate Form</title>
+ </section>
+
+ <section>
+ <title>Turning the API into the Reference: js2doc2dbk</title>
+ </section>
+
+ <section>
+ <title>Docbook to Output, at Last!</title>
+ </section>
+ <para>the docbook customization layer</para>
+ </section>
+
+ <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 can be traced back to their origins in the sources.</para>
+ </section>
+ </section>
+
+ <section>
+ <title>The Developer's Guide Toolchain</title>
+ </section>
+
+ <section>
+ <title>Workflow Details</title>
+
+ <section>
+ <title>Directory Structure</title>
+ </section>
+
+ <section>
+ <title>How Ant Drives the Transformations</title>
+ </section>
+
+ </section>
+
</chapter>
Added: openlaszlo/trunk/docs/src/developers/images/doc_overview_simple.png
Property changes on: openlaszlo/trunk/docs/src/developers/images/doc_overview_simple.png
___________________________________________________________________
Name: svn:mime-type
+ image/png
Added: openlaszlo/trunk/docs/src/developers/images/doc_reference_details.png
Property changes on: openlaszlo/trunk/docs/src/developers/images/doc_reference_details.png
___________________________________________________________________
Name: svn:mime-type
+ image/png
More information about the Laszlo-checkins
mailing list