[Laszlo-checkins] r7975 - openlaszlo/trunk/docs/src/developers
lou@openlaszlo.org
lou at openlaszlo.org
Thu Feb 7 04:37:25 PST 2008
Author: lou
Date: 2008-02-07 04:36:53 -0800 (Thu, 07 Feb 2008)
New Revision: 7975
Modified:
openlaszlo/trunk/docs/src/developers/doc-toolchain.dbk
Log:
Change 20080207-lou-Z by lou at loumac.local on 2008-02-07 08:31:24 AST
in /Users/lou/src/svn/openlaszlo/trunk
for http://svn.openlaszlo.org/openlaszlo/trunk
Summary: make sure the doc tool chain chapter of the dguide is valid DocBook, fix broken links and spelling errors
New Features:
Bugs Fixed: LPP-5409
Technical Reviewer: (pending)
QA Reviewer: (pending)
Doc Reviewer: (pending)
Tests: validate against DocBook dtd, manually verify links
Modified: openlaszlo/trunk/docs/src/developers/doc-toolchain.dbk
===================================================================
--- openlaszlo/trunk/docs/src/developers/doc-toolchain.dbk 2008-02-07 12:35:31 UTC (rev 7974)
+++ openlaszlo/trunk/docs/src/developers/doc-toolchain.dbk 2008-02-07 12:36:53 UTC (rev 7975)
@@ -5,9 +5,9 @@
* 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">
+<!DOCTYPE chapter 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">
+<chapter id="doc-toolchain">
<title>The Documentation Toolchain</title>
<para>The documentation for OpenLaszlo, including this chapter of the developer's guide, is built
@@ -30,37 +30,37 @@
<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
+ <listitem><para>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>
+ schema.</para></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><para>Laszlo Foundation Classes. For the purposes of the documentation toolchain, the LFC
+ consists of classes which are written in JavaScript.</para></listitem>
</varlistentry>
<varlistentry>
<term>Developer's Guide</term>
- <listitem>The Developer's Guide, which you are reading, is a text about developing with
+ <listitem><para>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>
+ performance, how to debug a live application, or why to choose a SOLO deployment.</para></listitem>
</varlistentry>
<varlistentry>
<term>Reference Guide</term>
- <listitem>The Reference Guide is a detailed reference manual of all of the public API's in
+ <listitem><para>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>
+ <literal>drawview</literal>, or what events a <literal>button</literal> might
+ generate.</para></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><para>The term doc-comment is shorthand to refer to a special comment in a source file
+ whose purpose is to document the nearby code.</para> </listitem>
</varlistentry>
</variablelist>
-
+
<para>With those definitions in mind, let's look at a simplified version of the rather
intimidating diagram above: <informalfigure>
<mediaobject>
@@ -70,17 +70,17 @@
</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
+ labeled DocBook processing, turns intermediate files into the output html that you are probably
reading right now. </para>
<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>
+ <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 url="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:
+ <para>Another way to understand the documentation toolchain centers on DocBook. Various processes create DocBook files, then a giant XSL transformation converts those DocBook files into output HTML. This diagram shows the whole process from this point of view:
<informalfigure>
<mediaobject>
<imageobject>
@@ -88,7 +88,7 @@
</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>
+ 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">
@@ -99,7 +99,7 @@
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
+ <para>The OpenLaszlo platform is heterogeneous, 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
@@ -193,13 +193,13 @@
</class>
</property>
</programlisting>
- Later in this document, we'll see how this js2doc intermediate fragment becomes the reference
- page for the method tag. </section>
+ <para>Later in this document, we'll see how this js2doc intermediate fragment becomes the reference
+ page for the method tag.</para></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
+ is inline with their implementation. <xref linkend="LzView" /> 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>
@@ -321,11 +321,11 @@
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>
+ <para>The source for <xref linkend="lz.basewindow" />
(<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
+ 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.
@@ -364,7 +364,7 @@
<section id="js2doc2dbk">
<title>Turning the API into the Reference: js2doc2dbk</title>
- <para>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:
+ <para>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:
<informalfigure>
<mediaobject>
<imageobject>
@@ -374,15 +374,17 @@
</informalfigure>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.</para>
<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>.)
+ <listitem><para>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>.)</para>
<orderedlist>
- <listitem>Identify the pages in that section.</listitem>
- <listitem>For each page in the reference:
+ <listitem><para>Identify the pages in that section.</para></listitem>
+ <listitem><para>For each page in the reference:</para>
<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>
+ <listitem><para>Describe the class by name, inheritance chain, and introductory text.</para></listitem>
+ <listitem><para>List all of the attributes for that class. Also list all of the inherited attributes for that class.</para></listitem>
+ <listitem><para>List all of the methods for that class. Also list all of the inherited methods for that class.</para></listitem>
+ <listitem><para>List all of the events for that class. Also list all of the inherited events for that class.</para></listitem>
</orderedlist>
</listitem>
</orderedlist>
@@ -401,8 +403,8 @@
</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>
+ <listitem><para>docs/src/xsl/js2doc2dbk/synopsis.xsl</para></listitem>
+ <listitem><para>docs/src/xsl/js2doc2dbk/utilities.xsl</para></listitem>
</itemizedlist>
</section>
@@ -411,30 +413,34 @@
</section>
<section id="js2doc2dbk-params"><title>Parameters for controlling the js2doc2dbk transformation</title>
<itemizedlist>
- <listitem>generating warnings, errors, fixme's</listitem>
+ <listitem><para>generating warnings, errors, fixme's</para></listitem>
</itemizedlist>
</section>
- <section id="js2doc2dbk-indices"><title>Indicies, Appendices, Cross-references, etc</title>
+ <section id="js2doc2dbk-indices">
+ <title>Indicies, Appendices, Cross-references, etc</title>
+ <para></para>
</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>
+ <listitem><para>Subclass and superclass chains</para></listitem>
+ <listitem><para>Attributes list (with lzxtype, final, read-only, initialize-only)</para></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>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:
+ <note><para>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.</para></note>
+ <para>Let's look at the reference page for <xref linkend="LzText" />. 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>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.</para>
</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
+ <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>
@@ -468,19 +474,19 @@
...</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>
+ <note><para>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.</para></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:
+ <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>
+ <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><para>In DocBook files, the trick for finding a particular element is the same as in LaszloLibrary-verbose; just search for <literal>id="LzText"</literal></para></note>
<informalexample><programlisting><<emphasis>refentry xreflabel="&lt;text&gt;" id="LzText"></emphasis>
<emphasis><anchor id="tag.text"/></emphasis>
<refnamediv>
@@ -491,25 +497,25 @@
</refnamediv>
...</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>
+ <note><para>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>.</para></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><para>You can now open the door and turn your phone's ringer back on -- you're through the worst of it!</para></note>
</section>
</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>
+ <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:
+ <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 url="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>
+ <listitem><para>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>.</para></listitem>
+ <listitem><para>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.</para></listitem>
</orderedlist>
</para>
<informalfigure><mediaobject><imageobject>
@@ -518,18 +524,18 @@
</mediaobject></informalfigure>
<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>
+ <listitem><para>common-html.xsl</para></listitem>
+ <listitem><para>conditional-html.xsl</para></listitem>
+ <listitem><para>styles.css</para></listitem>
+ <listitem><para>lzx-pretty-print.css</para></listitem>
+ <listitem><para>dguide.xsl</para></listitem>
+ <listitem><para>dbkpreprocessexamples.xsl</para></listitem>
+ <listitem><para>lzx-pretty-print.xsl</para></listitem>
</itemizedlist>
<section>
<title>How the copyright gets generated</title>
<para>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
+ 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.</para>
<para>The copyright notice for files that are <emphasis>not generated</emphasis> is entered manually.</para>
</section>
@@ -607,39 +613,39 @@
<para>Here's that same information, organized hierarchically:
<itemizedlist>
- <listitem>$LPS_HOME
+ <listitem><para>$LPS_HOME</para>
<itemizedlist>
- <listitem>docs
+ <listitem><para>docs</para>
<itemizedlist>
- <listitem>reference/ ($reference.output.dir)</listitem>
- <listitem>developers/ ($developers.output.dir)</listitem>
- <listitem>src/ ($docs.src.dir)
+ <listitem><para>reference/ ($reference.output.dir)</para></listitem>
+ <listitem><para>developers/ ($developers.output.dir)</para></listitem>
+ <listitem><para>src/ ($docs.src.dir)</para>
<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)
+ <listitem><para>xsl/ (holds the xsl templates for both the conversion from lzx to js2doc, and from js2doc to DocBook)</para></listitem>
+ <listitem><para>developers/ ($developers.src.dir)</para>
<itemizedlist>
- <listitem>tutorials/
+ <listitem><para>tutorials/</para>
<itemizedlist>
- <listitem>programs</listitem>
- <listitem>images</listitem>
+ <listitem><para>programs</para></listitem>
+ <listitem><para>images</para></listitem>
</itemizedlist>
</listitem>
- <listitem>programs</listitem>
- <listitem>images</listitem>
+ <listitem><para>programs</para></listitem>
+ <listitem><para>images</para></listitem>
</itemizedlist>
</listitem>
- <listitem>reference/ ($reference.src.dir)
+ <listitem><para>reference/ ($reference.src.dir)</para>
<itemizedlist>
- <listitem>images</listitem>
- <listitem>resources</listitem>
- <listitem>navbuilder/ command-line tool for building the left-nav in the reference</listitem>
+ <listitem><para>images</para></listitem>
+ <listitem><para>resources</para></listitem>
+ <listitem><para>navbuilder/ command-line tool for building the left-nav in the reference</para></listitem>
</itemizedlist>
</listitem>
- <listitem>build/ (temporary) ($docs.build.dir)
+ <listitem><para>build/ (temporary) ($docs.build.dir)</para>
<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>
+ <listitem><para>js2doc/ (js2doc.build.dir) holds the initial js2doc output</para> </listitem>
+ <listitem><para>developers/ ($developers.build.dir) where the processed developers guide DocBook files go after they've had the examples and callouts inserted</para></listitem>
+ <listitem><para>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</para></listitem>
</itemizedlist>
</listitem>
</itemizedlist>
@@ -664,8 +670,8 @@
</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>
+ <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>
<para>This diagram shows the major targets in the developer's guide build. As before, parameterized targets are highlighted:
<informalfigure><mediaobject><imageobject>
<imagedata fileref="images/doc-ant-build-developers.png"/>
More information about the Laszlo-checkins
mailing list