langref.xml 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 $LPS_HOME/docs/src/reference/langref.xml.

langref.xml 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 moveWindow method in the example in Section 5, “Methods”. We're not talking about documenting an instance of the method tag; rather, we're talking about documenting the method tag itself: Here's the js2doc fragment describing the method tag:

            
            <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>            
      

Later in this document, we'll see how this js2doc intermediate fragment becomes the reference page for the method tag.

The LFC (Laszlo Foundation Classes) are written in JavaScript, and their documentation is inline with their implementation. <view> 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 ($LPS_HOME/WEB-INF/lps/lfc/views/LaszloView.lzs):

            /**
            * 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.height>= y) && (y >= 0)) &&
                ((this.width>= x) && (x >= 0)));
            }            
          

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 WEB-INF/lps/server/src/org/openlaszlo/js2doc. It's really quite clever: the js2doc tool uses exactly the same parsing code as the OpenLaszlo script compiler. 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 -- complete with the comments embedded as documentation!

This will make more sense when we look at the js2doc output from the containsPt code above:

            <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>            
          

A note on id's: the id 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:

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 basewindow, insert <xref linkend="lz.basewindow"/> which yields this result: <basewindow>

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.

The source for <basewindow> (lps/components/base/basewindow.lzx) 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. Chapter 57, JS2Doc Reference describes the available annotations within a doc comment in lzx.

<!--- 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">

This example shows the doc-comment for the method setWindowFocus of the basewindow class. It indicates that there is a single parameter, windowfocus which should be a Boolean.

lzx2js2doc processes commented lzx source files into js2doc intermediate files. It is an xsl worksheet, $LPS_HOME/docs/src/xsl/lzx2js2doc.xsl, 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:

<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>
            

(This fragment is in $LPS_HOME/docs/src/build/reference/LaszloLibrary-verbose.js2doc, an intermediate file generated by the reference build.)

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:

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.

Consider this step abstractly: From a large, structured set of information, construct another large, structured set of information. 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.)

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, Section 3.4.1, “Reading js2doc2dbk Stylesheets”

3.4.2. js2doc2dbk walkthrough

	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.

Let's look at the reference page for <text>. The js2doc description of it is in docs/src/xsl/build/reference/LaszloLibrary-verbose.js2doc. Open that file and find the element describing lz.text. Copy that element into a smaller file so you can look at it in detail. The element describing the lz.text class begins with this line:

<property id="LzText" name="LzText" unitid="views.LzText.lzs" access="public" topic="LFC" subtopic="Text">

	Note
	To find a particular item in the giant LaszloLibrary-verbose.js2doc file, just search for it by id. This works because id's are globally unique.

Notice that the containing element here is <property>. In js2doc, property is the element that represents a useful chunk of the api. This particular element describes everything there is to know about lz.text.

The main template for generating a page in the reference is in the file docs/src/xsl/js2doc2dbk.xsl. We can tell from the js2doc output below, and our knowledge of DocBook, that the output begins with a <refentry> tag, so we can find the template that generates it by searching js2doc2dbk.xsl for <refentry or by performing the equivalent XPath query: //refentry. This takes us to two templates, one that starts with

<xsl:template match="property" mode="refentry">

and another that starts with

<xsl:template match="unit" mode="refentry">

We're trying to match a property tag, so the first of those templates is the one that will match.

The beginning of that template declares several variables and determines their values:

        
            <xsl:variable name="jsname" select="@name"/>
            <xsl:variable name="lzxname" select="&tagname;"/>
          

These lines establish variables named $jsname and $lzxname. For $jsname, select="@name" means "run the XPath query '@name' on the current node, and set the value of the $jsname variable to the result of that query." In your XML editor, run that query yourself; the result should be lz.text.

The declaration of $lzxname is more complicated, even though it looks just as simple as $jsname. Here we have select="&tagname;". That's a reference to an entity; find that entity's definition at the beginning of js2doc2dbk.xsl:

<!ENTITY tagname        '(doc/tag[@name="lzxname"]/text)'>

Remember that entities are text substitutions, so after entity expansion, the lzxname declaration above would read:

<xsl:variable name="lzxname" select="(doc/tag[@name="lzxname"]/text)/>

That's an XPath query which means "find a child of the current node who has a child element of type tag who has an attribute name whose value is lzxname. Return the textual content of that tag node's child text node." Consulting the js2doc fragment for lz.text again, we can evaluate this query:

            <property id="LzText" name="LzText" unitid="views.LzText.lzs" access="public" topic="LFC" subtopic="Text">
            <doc>
            <text>
            <p>This class is used for non-editable text .... 
            </p>
            </text>
            <tag name="shortdesc">
            <text>The basic text display element.</text>
            </tag>
            <tag name="devnote">
            <text>This is for regular and input text.</text>
            </tag>
            <tag name="lzxname">
            <text>text</text>
            </tag>  
            ...

So the value of $lzxname is "text".

	Note
	The double meaning of "text" and "tag" here is unavoidable. Keep track of when we're talking about a domain concept -- lz.text, aka "text," is a concept in the OpenLaszlo domain -- and when we're talking about a tools concept -- the text value of an XML element.

Continuing our walkthrough of the main template for a reference entry in js2doc2dbk.xsl, skip over the next few variable declarations. Now we're at the first output instructions:

<refentry id="{$id-for-output}" xreflabel="{$desc}">
            <xsl:if test="$lzxname"><anchor id="{concat('tag.',$lzxname)}"/></xsl:if> 
            ...

$id-for-output was one of the variables we skipped over; experience reveals that $id-for-output evaluates to lz.text and that $desc evaluates to <text>. The next line says, "if the variable named $lzxname has a non-null value, output an <anchor> tag with an id of 'tag.' + $lzxname." For lz.text, we figured out above that $lzxname is text.

Now we can predict the DocBook output from this part of the template:

<refentry xreflabel="&lt;text&gt;" id="LzText">
            <anchor id="tag.text"/>

To verify that's the output we'll get, look at the DocBook output for lz.text. If you've done a documentation build, the lz.text reference entry will be in docs/src/build/reference/lfcref.dbk. Open that file, and again find the lz.text section.

	Note
	In DocBook files, the trick for finding a particular element is the same as in LaszloLibrary-verbose; just search for id="LzText"

<refentry xreflabel="&lt;text&gt;" id="LzText">        
          <anchor id="tag.text"/>        
          <refnamediv>
          ...
          <refname role="javascript">LzText</refname>
          <refname role="lzx">text</refname>
          <refpurpose>The basic text display element.</refpurpose>
          </refnamediv>
          ...

See if you can find where the refnamediv element in the listing above come from.

	Note
	A DocBook reference entry is a <refentry> tag. See the DocBook reference for refentry.

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.

	Note
	You can now open the door and turn your phone's ringer back on -- you're through the worst of it!

There is a copyright notice at the bottom of every dguide and reference page. This notice is generated during the DocBook transform by the template user.footer.content in the file common-html.xsl. To change to copyright date for all generated documents, change the date in this template.

The copyright notice for files that are not generated is entered manually.

There are several important directories for the documentation toolchain.

Here's that same information, organized hierarchically:

The build file in docs/src/build.xml is arguably the most complicated build file in the entire OpenLaszlo platform. It has several layers of abstraction, which, when combined with the doc toolchain's complexities we've already explored, make following the ant file nearly impossible. The way to make sense of the build file is to think of what we already have learned the process is, as described in the rest of this chapter. In this discussion, we'll favor concepts over details, lest we drown in details. You may also wish to try yWorks Ant Explorer which provides a visualization of the build file.

The build file is composed of both specific targets and parameterized targets. The parameterized targets do most of the work, and the specific targets set up the right parameters with which to call the parameterized targets. In Section 6.1, “Directory Structure”, the ant properties corresponding to particular directories in the LPS tree are listed; understanding those mappings is crucial to being able to read and follow the build.

In this diagram of the major targets in the reference build, parameterized targets are highlighted:

reference.js2doc.generate drives the creation of the js2doc intermediate file, LaszloLibrary-verbose.js2doc, from the several sources (langref.xml, lzx files, and js files).

dbk.topic.generate drives the js2doc2dbk transformation. It says, "find all the elements in the input file ( LaszloLibrary-verbose.js2doc for the reference) that match the topic specified in the filter.topic parameter. Apply the transformations in js2doc2dbk.xsl to those elements, and output the results to the file specified in the local.output.file."

book.html.generate drives the DocBook to HTML transformation.

dbk.examples.preprocess prepares the examples in the specified DocBook for rendering and final output, by running the DocBook through xsl/dbkpreprocessexamples.xsl.

This diagram shows the major targets in the developer's guide build. As before, parameterized targets are highlighted: