[Laszlo-checkins] r7668 - in openlaszlo/trunk/docs/src/developers: . tutorials
ben@openlaszlo.org
ben at openlaszlo.org
Tue Dec 25 15:26:13 PST 2007
Author: ben
Date: 2007-12-25 15:26:07 -0800 (Tue, 25 Dec 2007)
New Revision: 7668
Modified:
openlaszlo/trunk/docs/src/developers/doc-toolchain.dbk
openlaszlo/trunk/docs/src/developers/js2doc-ref.dbk
openlaszlo/trunk/docs/src/developers/tutorials/scripting.dbk
Log:
Change 20071225-ben-U by ben at slim.local on 2007-12-25 15:19:54 PST
in /Users/ben/src/svn/openlaszlo/trunk
for http://svn.openlaszlo.org/openlaszlo/trunk
Summary: More discussion of the documentation toolchain
Modified: openlaszlo/trunk/docs/src/developers/doc-toolchain.dbk
===================================================================
--- openlaszlo/trunk/docs/src/developers/doc-toolchain.dbk 2007-12-25 23:25:17 UTC (rev 7667)
+++ openlaszlo/trunk/docs/src/developers/doc-toolchain.dbk 2007-12-25 23:26:07 UTC (rev 7668)
@@ -8,69 +8,115 @@
<!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>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>
+ <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>
+
+ <figure>
+ <title>Documentation Toolchain</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/doc-toolchain.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>Some vocabulary will help you understand the diagram:</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>
+ <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>
+ <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>
+ <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>
+ <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>
+ <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>
+
+ <para>With those definitions in mind, let's look at a simplified version of the rather
+ intimidating diagram above: <informalfigure>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/doc_overview_simple.png"/>
+ </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 id="reference-toolchain-source-to-doc">
+ <title>The Reference Toolchain: From Source to Documentation</title>
+ <para>How do we build the reference? We build it from the source, of course. (Documentation
+ that's not in the source will fall out of date as soon as it's written. Documentation
+ <emphasis>in</emphasis> the source also tends to decay, but at least it's in the developer's
+ field of view while he's editing the code.) This section will walk you through the processes
+ which discover the documentation in various source materials, to an intermediate XML format
+ which we call "js2doc", to the end project: the HTML reference manual.</para>
+ <para>The OpenLaszlo platform is heterogenous, so our reference toolchain must accept several
+ types of source as input: a basic language definition, JavaScript sources that implement the
+ Laszlo Foundation Classes, and lzx sources that implement the lion's share of the application
+ development classes. (For the purposes of this document, we'll ignore the Java API's for the
+ parser, compiler, and servlet. Those elements use a well-known javadoc workflow.)</para>
+ <para>Let's look at that top row of the diagram above. In more detail, it becomes three rows,
+ one for each variety of source code: <informalfigure>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/doc_reference_details.png"/>
</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>
+ </mediaobject>
+ </informalfigure>
+ </para>
+ <para>This part of the toolchain unifies the various source material into js2doc format, then
+ joins them together into a massive XML file, <literal>LaszloLibrary-verbose.js2doc</literal>.
+ To understand those processes, please review <xref id="js2doc-schema"/> to grasp the kinds of
+ information that js2doc is trying to represent. The next three sections will 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. 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>
+ <programlisting language="lzx">
<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>
@@ -133,14 +179,28 @@
</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>
+ </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>
+
+ <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
@@ -148,13 +208,21 @@
* @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)));
+ 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>
+ <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>
@@ -178,21 +246,34 @@
</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
+ </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
@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">
+ <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>
@@ -210,46 +291,79 @@
</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>
+ (This fragment is in $LPS_HOME/docs/src/build/reference/LaszloLibrary-verbose.js2doc, an
+ intermediate file generated by the reference build.) </para>
</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. 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 can be traced back to their origins in the sources.</para>
+ <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>
+ <para>screengrab of a reference page with area highlighted, identified by A/B/C etc</para>
+ <para>for each highlighted area, show the xsl files in which it is created and the important templates </para>
</section>
</section>
-
+
<section>
<title>The Developer's Guide Toolchain</title>
</section>
-
+
<section>
<title>Workflow Details</title>
-
+
<section>
<title>Directory Structure</title>
+ <itemizedlist>
+ <listitem>docs/src/
+ <itemizedlist>
+ <listitem>developers/
+ <itemizedlist>
+ <listitem>tutorials/
+ <itemizedlist>
+ <listitem>programs</listitem>
+ <listitem>images</listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem>programs</listitem>
+ <listitem>images</listitem>
+ </itemizedlist>
+
+ </listitem>
+ <listitem>reference/
+ <itemizedlist>
+ <listitem>images</listitem>
+ <listitem>resources</listitem>
+ <listitem>navbuilder/ command-line tool for building the left-nav in the reference</listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem>build/ (temporary)
+ <itemizedlist>
+ <listitem>js2doc/ holds the initial js2doc output </listitem>
+ <listitem>developers/ where the processed developers guide docbook files go after they've had the examples and callouts inserted</listitem>
+ <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>
+ </itemizedlist>
+
+ </listitem>
+ </itemizedlist>
+
</section>
-
+
<section>
<title>How Ant Drives the Transformations</title>
</section>
-
+
</section>
-
+
+
</chapter>
Modified: openlaszlo/trunk/docs/src/developers/js2doc-ref.dbk
===================================================================
--- openlaszlo/trunk/docs/src/developers/js2doc-ref.dbk 2007-12-25 23:25:17 UTC (rev 7667)
+++ openlaszlo/trunk/docs/src/developers/js2doc-ref.dbk 2007-12-25 23:26:07 UTC (rev 7668)
@@ -196,7 +196,7 @@
<section><title>To Do</title>
</section>
-<section><title>JS2Doc Schema</title>
+<section id="js2doc-schema"><title>JS2Doc Schema</title>
<para>This section gives the schema describing output of the <application>js2doc</application> tool, in Relax-NG Compact notation.</para>
<programlisting>
<textobject><textdata fileref="build/developers/js2doc.rnc"/></textobject>
Modified: openlaszlo/trunk/docs/src/developers/tutorials/scripting.dbk
===================================================================
--- openlaszlo/trunk/docs/src/developers/tutorials/scripting.dbk 2007-12-25 23:25:17 UTC (rev 7667)
+++ openlaszlo/trunk/docs/src/developers/tutorials/scripting.dbk 2007-12-25 23:26:07 UTC (rev 7668)
@@ -125,7 +125,7 @@
<para>Functions are global to the LZX document, and they follow the same scope rules as JavaScript.</para>
-<para/></section><section><title>Methods</title>
+<para/></section><section id="tutorial-methods"><title>Methods</title>
<para>Methods are in some ways similar to functions. They contain blocks of code between <indexterm><primary>method</primary></indexterm><sgmltag class="element"><method></sgmltag><remark role="fixme">[unknown tag]</remark>
<!--unknown tag: method-->
More information about the Laszlo-checkins
mailing list