[Laszlo-checkins] r7678 - in openlaszlo/trunk/docs/src/developers: . images
ben@openlaszlo.org
ben at openlaszlo.org
Fri Dec 28 21:53:55 PST 2007
Author: ben
Date: 2007-12-28 21:53:26 -0800 (Fri, 28 Dec 2007)
New Revision: 7678
Added:
openlaszlo/trunk/docs/src/developers/images/doc-ant-build.graffle
openlaszlo/trunk/docs/src/developers/images/doc-ant-build.png
Modified:
openlaszlo/trunk/docs/src/developers/doc-toolchain.dbk
Log:
Change 20071228-ben-o by ben at slim.local on 2007-12-28 21:50:31 PST
in /Users/ben/src/svn/openlaszlo/trunk
for http://svn.openlaszlo.org/openlaszlo/trunk
Summary: doctools explanation: the ant build process, directory structure.
Documentation:
Added a diagram and explanation of how the ant build works and where
the important directories are and what the ant properties are that
match the actual directories.
Modified: openlaszlo/trunk/docs/src/developers/doc-toolchain.dbk
===================================================================
--- openlaszlo/trunk/docs/src/developers/doc-toolchain.dbk 2007-12-29 05:52:12 UTC (rev 7677)
+++ openlaszlo/trunk/docs/src/developers/doc-toolchain.dbk 2007-12-29 05:53:26 UTC (rev 7678)
@@ -542,47 +542,131 @@
<title>Workflow Details</title>
<section id="directory-structure">
<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>
- <listitem>xsl/ (holds the xsl templates for both the conversion from lzx to js2doc, and from js2doc to docbook)</listitem>
- </itemizedlist>
-
- </listitem>
- </itemizedlist>
+ <para>There are several important directories for the documentation toolchain.</para>
+ <informaltable colsep="0" frame="none">
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry align="left">Path</entry>
+ <entry align="left">Ant Property</entry>
+ <entry align="left">Purpose</entry>
+ <entry align="left">Ships in binary distros</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>$LPS_HOME/docs/src/xsl</literal></entry>
+ <entry>(no associated property)</entry>
+ <entry>Holds the stylesheets that do the transformations</entry>
+ <entry>no</entry>
+ </row>
+ <row>
+ <entry><literal>$LPS_HOME/docs/src/developers</literal></entry>
+ <entry><literal>$developers.src.dir</literal></entry>
+ <entry>Holds the source for the developer's guide </entry>
+ <entry>no</entry>
+ </row>
+ <row>
+ <entry><literal>$LPS_HOME/docs/src/build/developers</literal></entry>
+ <entry><literal>$developers.build.dir</literal></entry>
+ <entry>Holds intermediate files for the developer's guide build</entry>
+ <entry>no</entry>
+ </row>
+ <row>
+ <entry><literal>$LPS_HOME/docs/developers</literal></entry>
+ <entry><literal>$developers.output.dir</literal></entry>
+ <entry>Holds the output html for the developer's guide </entry>
+ <entry>yes</entry>
+ </row>
+ <row>
+ <entry><literal>$LPS_HOME/docs/src/reference</literal></entry>
+ <entry><literal>reference.src.dir</literal></entry>
+ <entry>Holds the source for the reference</entry>
+ <entry>no</entry>
+ </row>
+ <row>
+ <entry><literal>$LPS_HOME/docs/src/build/reference</literal></entry>
+ <entry><literal>reference.build.dir</literal></entry>
+ <entry>Holds intermediate files for the reference build</entry>
+ <entry>no</entry>
+ </row>
+ <row>
+ <entry><literal>$LPS_HOME/docs/reference</literal></entry>
+ <entry><literal>reference.output.dir</literal></entry>
+ <entry>Holds the output html for reference</entry>
+ <entry>yes</entry>
+ </row>
+ <row>
+ <entry><literal>$LPS_HOME/WEB-INF/lps/server/src/org/openlaszlo/js2doc</literal></entry>
+ <entry>(no associated property)</entry>
+ <entry>Contains the code for the js2doc java tool</entry>
+ <entry>no</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ <para>Here's that same information, organized hierarchically:
+ <itemizedlist>
+ <listitem>$LPS_HOME
+ <itemizedlist>
+ <listitem>docs
+ <itemizedlist>
+ <listitem>reference/ ($reference.output.dir)</listitem>
+ <listitem>developers/ ($developers.output.dir)</listitem>
+ <listitem>src/ ($docs.src.dir)
+ <itemizedlist>
+ <listitem>xsl/ (holds the xsl templates for both the conversion from lzx to js2doc, and from js2doc to docbook)</listitem>
+ <listitem>developers/ ($developers.src.dir)
+ <itemizedlist>
+ <listitem>tutorials/
+ <itemizedlist>
+ <listitem>programs</listitem>
+ <listitem>images</listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem>programs</listitem>
+ <listitem>images</listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem>reference/ ($reference.src.dir)
+ <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) ($docs.build.dir)
+ <itemizedlist>
+ <listitem>js2doc/ (js2doc.build.dir) holds the initial js2doc output </listitem>
+ <listitem>developers/ ($developers.build.dir) where the processed developers guide docbook files go after they've had the examples and callouts inserted</listitem>
+ <listitem>reference/ ($reference.build.dir) 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>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </itemizedlist>
+ </para>
</section>
<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>
+ <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 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 <ulink url="http://www.yworks.com/en/products_antexplorer_about.htm">yWorks Ant Explorer</ulink> which provides a visualization of the build file.</para>
+ <para>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 <xref linkend="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.</para>
+ <para>In this diagram of the major targets in the reference build, parameterized targets are highlighted:
+ <informalfigure><mediaobject><imageobject>
+ <imagedata fileref="images/doc-ant-build.png"/>
+ </imageobject>
+ </mediaobject></informalfigure>
+ </para>
+ <para><literal>reference.js2doc.generate</literal> drives the creation of the js2doc intermediate file, <literal>LaszloLibrary-verbose.js2doc</literal>, from the several sources (langref.xml, lzx files, and js files).</para>
+ <para><literal>dbk.topic.generate</literal> drives the js2doc2dbk transformation. It says, "find all the elements in the input file ( <literal>LaszloLibrary-verbose.js2doc</literal> for the reference) that match the topic specified in the <literal>filter.topic</literal> parameter. Apply the transformations in <literal>js2doc2dbk.xsl</literal> to those elements, and output the results to the file specified in the <literal>local.output.file</literal>." </para>
+ <para><literal>book.html.generate</literal> drives the docbook to HTML transformation.</para>
+ <para><literal>dbk.examples.preprocess</literal> prepares the examples in the specified docbook for rendering and final output, by running the docbook through <literal>xsl/dbkpreprocessexamples.xsl</literal>.</para>
</section>
</section>
Added: openlaszlo/trunk/docs/src/developers/images/doc-ant-build.graffle
Property changes on: openlaszlo/trunk/docs/src/developers/images/doc-ant-build.graffle
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: openlaszlo/trunk/docs/src/developers/images/doc-ant-build.png
Property changes on: openlaszlo/trunk/docs/src/developers/images/doc-ant-build.png
___________________________________________________________________
Name: svn:mime-type
+ image/png
More information about the Laszlo-checkins
mailing list