[Laszlo-checkins] r7675 - in openlaszlo/trunk/docs/src/developers: . images
ben@openlaszlo.org
ben at openlaszlo.org
Thu Dec 27 20:04:47 PST 2007
Author: ben
Date: 2007-12-27 20:04:34 -0800 (Thu, 27 Dec 2007)
New Revision: 7675
Added:
openlaszlo/trunk/docs/src/developers/images/doc-toolchain-is-docbook.graffle
openlaszlo/trunk/docs/src/developers/images/doc-toolchain-is-docbook.png
openlaszlo/trunk/docs/src/developers/images/docbook-to-html.graffle
openlaszlo/trunk/docs/src/developers/images/docbook-to-html.png
Modified:
openlaszlo/trunk/docs/src/developers/doc-toolchain.dbk
Log:
Change 20071227-ben-a by ben at slim.local on 2007-12-27 20:02:53 PST
in /Users/ben/src/svn/openlaszlo/trunk
for http://svn.openlaszlo.org/openlaszlo/trunk
Summary: Improve structure of doctools chapter
Documentation:
This change improves the structure of the doctools chapter,
adds more diagrams, and cleans up the dataflow description to
match the document structure.
Modified: openlaszlo/trunk/docs/src/developers/doc-toolchain.dbk
===================================================================
--- openlaszlo/trunk/docs/src/developers/doc-toolchain.dbk 2007-12-28 04:04:06 UTC (rev 7674)
+++ openlaszlo/trunk/docs/src/developers/doc-toolchain.dbk 2007-12-28 04:04:34 UTC (rev 7675)
@@ -14,12 +14,8 @@
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 below. This chapter will break it down into nearly-manageable chunks.
+ </para>
<figure>
<title>Documentation Toolchain</title>
@@ -31,7 +27,7 @@
</figure>
<para>Some vocabulary will help you understand the diagram:</para>
- <variablelist>
+ <variablelist id="doctools-vocabulary">
<varlistentry>
<term>js2doc</term>
<listitem>Think of this as the xml schema to describe JavaScript 2. The '2' in the term
@@ -77,13 +73,26 @@
labeled docbook processing, turns intermediate files into the output html that you are probably
reading right now. </para>
- <section><title>Figuring things out</title>
+ <section id="figuring-things-out"><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="docbook-is-central">
+ <title>DocBook is the Center of the Documentation Toolchain</title>
+ <para>Another way to understand the documentation toolchain centers on docbook. Various processes create docbook files, then a giant XSL transformation convertse those docbook files into output HTML. This diagram shows the whole process from this point of view:
+ <informalfigure>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/doc-toolchain-is-docbook.png"/>
+ </imageobject>
+ </mediaobject>
+ </informalfigure>
+ The rest of this document is structured like the image above: first we describe how to get to docbook files for the reference, then for the developer's guide; then we describe how to generate HTML output from the docbook files. Finally, we'll consider the "backwards" transformation, tracing elements in an output page of the reference back to their origins in comments.</para>
+ </section>
<section id="reference-toolchain-source-to-doc">
- <title>The Reference Toolchain: From Source to Documentation</title>
+ <title>The Reference Toolchain: From Source to DocBook</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
@@ -366,219 +375,171 @@
<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>
+ <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>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 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 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 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 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 id="js2doc2dbk-params"><title>Parameters for controlling the js2doc2dbk transformation</title>
- <itemizedlist>
- <listitem>generating warnings, errors, fixme's</listitem>
- </itemizedlist>
- </section>
- <section id="js2doc2dbk-indices"><title>Indicies, Appendices, Cross-references, etc</title>
+
+ <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 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 id="js2doc2dbk-laszlo-specific"><title>OpenLaszlo-specific docbook elements</title>
- <itemizedlist>
- <listitem>Embedded live examples</listitem>
- </itemizedlist>
+ <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 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 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 id="js2doc2dbk-params"><title>Parameters for controlling the js2doc2dbk transformation</title>
+ <itemizedlist>
+ <listitem>generating warnings, errors, fixme's</listitem>
+ </itemizedlist>
+ </section>
+ <section id="js2doc2dbk-indices"><title>Indicies, Appendices, Cross-references, etc</title>
+ </section>
+ <section id="very-complex-templates">
+ <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 id="very-complex-templates">
- <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 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>
+ <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>Let's look at the reference page for <xref linkend="LzText">LzText</xref>. The js2doc description of it is in <literal>docs/src/xsl/build/reference/LaszloLibrary-verbose.js2doc</literal>. Open that file and find the element describing <literal>LzText</literal>. Copy that element into a smaller file so you can look at it in detail. The element describing the <literal>LzText</literal> class begins with this line:
+ <programlisting><<emphasis>property</emphasis> id="LzText" name="LzText" unitid="views.LzText.lzs" access="public" topic="LFC" subtopic="Text"></programlisting>
+ </para>
+ <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.
+ </note>
+ <para>Notice that the containing element here is <literal><property></literal>. In js2doc, property is the element that represents a useful chunk of the api. This particular element describes everything there is to know about <literal>LzText</literal>.</para>
+
+ <para>The main template for generating a page in the reference is in the file <literal>docs/src/xsl/js2doc2dbk.xsl</literal>. 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 <literal>js2doc2dbk.xsl</literal> for <literal><refentry</literal> or by performing the equivalent XPath query: <literal>//refentry</literal>. This takes us to two templates, one that starts with
+ <programlisting><xsl:template <emphasis>match="property" </emphasis>mode="refentry"></programlisting>
+ and another that starts with
+ <programlisting><xsl:template <emphasis>match="unit"</emphasis> mode="refentry"></programlisting>
+ We're trying to match a <literal>property</literal> tag, so the first of those templates is the one that will match.</para>
+ <para>The beginning of that template declares several variables and determines their values:
+ <programlisting>
+ <xsl:variable name="<emphasis>jsname</emphasis>" select="<emphasis>@name</emphasis>"/>
+ <xsl:variable name="<emphasis>lzxname</emphasis>" select="<emphasis>&tagname</emphasis>;"/>
+ </programlisting>These lines establish variables named $jsname and $lzxname. For <literal>$jsname</literal>, <literal>select="@name" </literal> means "run the XPath query <literal>'@name'</literal> on the current node, and set the value of the <literal>$jsname</literal> variable to the result of that query." In your XML editor, run that query yourself; the result should be <literal>LzText</literal>. </para>
+ <para>The declaration of <literal>$lzxname</literal> is more complicated, even though it looks just as simple as <literal>$jsname</literal>. Here we have <literal>select="&tagname;"</literal>. That's a reference to an entity; find that entity's definition at the beginning of js2doc2dbk.xsl:
+ <programlisting><!ENTITY tagname '(doc/tag[@name="lzxname"]/text)'></programlisting>
+ Remember that entities are text substitutions, so after entity expansion, the lzxname declaration above would read:
+ <programlisting><xsl:variable name="lzxname" select="(doc/tag[@name="lzxname"]/text)/></programlisting>
+ That's an XPath query which means "find a child of the current node who has a child element of type <literal>tag</literal> who has an attribute <literal>name</literal> whose value is <literal>lzxname</literal>. Return the textual content of that tag node's child <literal>text</literal> node." Consulting the js2doc fragment for LzText again, we can evaluate this query:
+ <informalexample><programlisting>
+ <<emphasis>property</emphasis> id="LzText" name="LzText" unitid="views.LzText.lzs" access="public" topic="LFC" subtopic="Text">
+ <<emphasis>doc</emphasis>>
+ <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>
+ <emphasis><tag</emphasis> <emphasis>name="lzxname"></emphasis>
+ <text><emphasis>text</emphasis></text>
+ </tag>
+ ...</programlisting></informalexample>
+ So the value of <literal>$lzxname</literal> is "text".
+ </para>
+ <note>The double meaning of "text" and "tag" here is unavoidable. Keep track of when we're talking about a domain concept -- LzText, 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.</note>
+
+ <para>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:
+ <programlisting><refentry id="{$id-for-output}" xreflabel="{$desc}">
+ <xsl:if test="$lzxname"><anchor id="{concat('tag.',$lzxname)}"/></xsl:if>
+ ...</programlisting>
+ <literal>$id-for-output</literal> was one of the variables we skipped over; experience reveals that <literal>$id-for-output</literal> evaluates to <literal>LzText</literal> and that $desc evaluates to <literal><text></literal>. 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 LzText, we figured out above that <literal>$lzxname</literal> is <literal>text</literal>.</para>
+ <para> Now we can predict the docbook output from this part of the template:
+ <informalexample><programlisting><refentry xreflabel="&lt;text&gt;" id="LzText">
+ <anchor id="tag.text"/></programlisting></informalexample>
+ </para>
+ <para>To verify that's the output we'll get, look at the docbook output for <emphasis>LzText</emphasis>. If you've done a documentation build, the LzText reference entry will be in <literal>docs/src/build/reference/lfcref.dbk</literal>. Open that file, and again find the <emphasis>LzText</emphasis> section.</para>
+ <note>In docbook files, the trick for finding a particular element is the same as in LaszloLibrary-verbose; just search for <literal>id="LzText"</literal></note>
+ <informalexample><programlisting><<emphasis>refentry xreflabel="&lt;text&gt;" id="LzText"></emphasis>
+ <emphasis><anchor id="tag.text"/></emphasis>
<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>
+ ...
+ <refname role="javascript">LzText</refname>
+ <refname role="lzx">text</refname>
+ <refpurpose>The basic text display 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>
+ ...</programlisting></informalexample>
+ <para>See if you can find where the <emphasis>refnamediv</emphasis> element in the listing above come from.</para>
+ <note>A docbook reference entry is a <literal><refentry></literal> tag. See <ulink url="http://www.docbook.org/tdg/en/html/refentry.html">the DocBook reference for refentry</ulink>.</note>
+ <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.</para>
+ <note>You can now open the door and turn your phone's ringer back on -- you're through the worst of it!</note>
+ </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>
- <listitem>common-html.xsl</listitem>
- <listitem>conditional-html.xsl</listitem>
- <listitem>styles.css</listitem>
- <listitem>lzx-pretty-print.css</listitem>
- </itemizedlist>
-
- </section>
+ </section>
+
+ <section id="developers-guide-toolchain">
+ <title>Developer's Guide Toolchain: Just DocBook</title>
+ <para>After all that, you may be relieved to learn that the developer's guide is far simpler. Chapters in the developer's guide are written as docbook files directly, so no transformation is necessary to create docbook files. The developer's guide docbook files enter the docbook-xsl processing stage in the same conceptual role as do the reference guide docbook files. </para>
+ </section>
+
+ <section id="docbook-to-output">
+ <title>Docbook to Output, at Last!</title>
+ <para>The last step in the transformation process is not as complicated as the preceding steps. This final step is mostly just the vanilla transformation of docbook files to html files, using the vanilla docbook-xsl transformations. <ulink linkend="http://www.sagehill.net/docbookxsl/">DocBook XSL: The Complete Guide by Bob Stayton</ulink> is an excellent reference on this topic.</para>
+ <para>There are two ways in which the OpenLaszlo docbook to html transformation differs from the standard docbook-xsl transformation:
+ <orderedlist>
+ <listitem>Customizations to standard docbook-xsl templates, also known as the "docbook customization layer." This is such a common pattern for customization that the DocBook-XSL book referenced above has a <ulink url="http://www.docbook.org/tdg/en/html/ch05.html">chapter about customizing docbook</ulink>. We customize the standard docbook by specifying parameters in <literal>docs/src/xsl/parameters.xsl</literal>.</listitem>
+ <listitem>Inclusion of specially-formatted examples. DocBook includes the notion of program listings and embedded illustrations, but it doesn't know about <emphasis>live</emphasis> examples, or how to format lzx code, or how to emphasize parts of example listings. The step labeled "docbook-preprocess" in the diagram below represents some of this process, but the truth is more complicated.</listitem>
+ </orderedlist>
+ </para>
+ <informalfigure><mediaobject><imageobject>
+ <imagedata fileref="images/docbook-to-html.png"/>
+ </imageobject>
+ </mediaobject></informalfigure>
- <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
+ <itemizedlist>
+ <listitem>common-html.xsl</listitem>
+ <listitem>conditional-html.xsl</listitem>
+ <listitem>styles.css</listitem>
+ <listitem>lzx-pretty-print.css</listitem>
+ <listitem>dguide.xsl</listitem>
+ <listitem>dbkpreprocessexamples.xsl</listitem>
+ <listitem>lzx-pretty-print.xsl</listitem>
+ </itemizedlist>
+
+ </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>
- <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>
+ <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 id="developers-guide-toolchain">
- <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 id="workflow-details">
<title>Workflow Details</title>
-
-
-
-
<section id="directory-structure">
<title>Directory Structure</title>
<itemizedlist>
@@ -621,6 +582,7 @@
<section id="how-ant-drives">
<title>How Ant Drives the Transformations</title>
+ <para>The build file in <literal>docs/src/build.xml</literal> 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 build.xml nearly impossible. An additional problem is that tools for visualizing ant files break on this one, because it calls itself, and because it calls other ant files entirely. (In fact, it calls the second-most complicated ant file in the OpenLaszlo platform, <literal>WEB-INF/lps/server/build.xml</literal>.) 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. </para>
</section>
</section>
Added: openlaszlo/trunk/docs/src/developers/images/doc-toolchain-is-docbook.graffle
Property changes on: openlaszlo/trunk/docs/src/developers/images/doc-toolchain-is-docbook.graffle
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: openlaszlo/trunk/docs/src/developers/images/doc-toolchain-is-docbook.png
Property changes on: openlaszlo/trunk/docs/src/developers/images/doc-toolchain-is-docbook.png
___________________________________________________________________
Name: svn:mime-type
+ image/png
Added: openlaszlo/trunk/docs/src/developers/images/docbook-to-html.graffle
Property changes on: openlaszlo/trunk/docs/src/developers/images/docbook-to-html.graffle
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: openlaszlo/trunk/docs/src/developers/images/docbook-to-html.png
Property changes on: openlaszlo/trunk/docs/src/developers/images/docbook-to-html.png
___________________________________________________________________
Name: svn:mime-type
+ image/png
More information about the Laszlo-checkins
mailing list