[Laszlo-checkins] r7986 - openlaszlo/trunk/docs/src/developers
lou@openlaszlo.org
lou at openlaszlo.org
Fri Feb 8 09:49:36 PST 2008
Author: lou
Date: 2008-02-08 09:49:07 -0800 (Fri, 08 Feb 2008)
New Revision: 7986
Modified:
openlaszlo/trunk/docs/src/developers/doc-backwards-xform.dbk
openlaszlo/trunk/docs/src/developers/docbook-code.dbk
openlaszlo/trunk/docs/src/developers/docbook-local.dbk
openlaszlo/trunk/docs/src/developers/js2doc-ref.dbk
Log:
Change 20080208-lou-l by lou at loumac.local on 2008-02-08 13:42:43 AST
in /Users/lou/src/svn/openlaszlo/trunk
for http://svn.openlaszlo.org/openlaszlo/trunk
Summary: fix DocBook so these files validate against the DocBook dtd.
Bugs Fixed: LPP-5417
Technical Reviewer: (pending)
QA Reviewer: (pending)
Doc Reviewer: (pending)
Details: DocBook tools are not very forgiving with files that are valid. Fix it.
Tests: xmllint -dtdvalid ~/src/svn/vendor/docbook-xml-4.5/docbookx.dtd <filename>
Modified: openlaszlo/trunk/docs/src/developers/doc-backwards-xform.dbk
===================================================================
--- openlaszlo/trunk/docs/src/developers/doc-backwards-xform.dbk 2008-02-08 17:47:46 UTC (rev 7985)
+++ openlaszlo/trunk/docs/src/developers/doc-backwards-xform.dbk 2008-02-08 17:49:07 UTC (rev 7986)
@@ -5,16 +5,16 @@
* 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-backwards">
+<chapter id="doc-backwards">
<title>The Backwards Transformation: From Reference Page to Source</title>
<para>In this chapter, we will show where several elements on the end product reference page
can be traced back to their origins in the sources. </para>
- <note>At this point we strongly, strongly encourage the reader
+ <note><para>At this point we strongly, strongly encourage the reader
to undergo an investigation of XPath 1.0 and to find an XML editor which is capable of doing live
XPath queries. (Oxygen XML Editor works.) Then, <emphasis>actually run some queries on a js2doc dataset</emphasis>.
- Without this exercise, the remainder of this chapter will be utter gobbledygook.
+ Without this exercise, the remainder of this chapter will be utter gobbledygook.</para>
</note>
<section><title>Page Header</title>
@@ -182,7 +182,7 @@
<xsl:variable name="svars" select="&objectvalue;/property[@name='setters']/object/property[&isvisible;]"/>
</programlisting>
The value of these variables is a result tree fragment; it's not just the name of the variables. This becomes important when we descend into the <literal>describe-members</literal> template.</para>
- <note>Review the table in <xref linkend="LFC-to-js2doc"/> to get a feel for why these XPath's return the desired result sets.</note>
+ <note><para>Review the table in <xref linkend="LFC-to-js2doc"/> to get a feel for why these XPath's return the desired result sets.</para></note>
<para>This all ends up down in the <literal>member-data-row</literal> template in js2doc2dbk.xsl, which fill in columns K, L, M, N, and O in the diagram above. Turn to LzText.lzs, to find where these variables were declared:</para>
<informalexample><programlisting>
/**
@@ -243,7 +243,7 @@
</programlisting></informalexample>
</para>
- To carry this reasoning all the way back to the javascript code definining the method, in <literal>WEB-INF/lps/lfc/views/LzText.lzs</literal>:
+ <para>To carry this reasoning all the way back to the javascript code definining the method, in <literal>WEB-INF/lps/lfc/views/LzText.lzs</literal>:</para>
<programlisting>
<emphasis>/**</emphasis>
* Formatted output.
Modified: openlaszlo/trunk/docs/src/developers/docbook-code.dbk
===================================================================
--- openlaszlo/trunk/docs/src/developers/docbook-code.dbk 2008-02-08 17:47:46 UTC (rev 7985)
+++ openlaszlo/trunk/docs/src/developers/docbook-code.dbk 2008-02-08 17:49:07 UTC (rev 7986)
@@ -1,36 +1,44 @@
<?xml version="1.0"?>
-
<!-- * X_LZ_COPYRIGHT_BEGIN ***************************************************
* Copyright 2007 Laszlo Systems, Inc. All Rights Reserved. *
* 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">
-
-<chapter language="en" id="docbook-code">
-<title>Documenting Your Code</title>
-
-<section><title>The Basics</title>
-</section>
-
-<section><title>Documenting LZX classes</title>
- <section><title>Using comments</title>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<chapter id="docbook-code">
+ <title>Documenting Your Code</title>
+ <para></para>
+ <section>
+ <title>The Basics</title>
+ <para></para>
</section>
-
- <section><title>Using the <sgmltag>doc</sgmltag> tag</title>
+ <section>
+ <title>Documenting LZX classes</title>
+ <para></para>
+ <section>
+ <title>Using comments</title>
+ <para></para>
+ </section>
+ <section>
+ <title>Using the
+ <sgmltag>doc</sgmltag>tag</title>
+ <para></para>
+ </section>
</section>
-</section>
-
-<section><title>Documenting JavaScript files</title>
-
- <section><title>JS2 class declarations</title>
+ <section>
+ <title>Documenting JavaScript files</title>
+ <para></para>
+ <section>
+ <title>JS2 class declarations</title>
+ <para></para>
+ </section>
+ <section>
+ <title>Function-as-class declarations</title>
+ <para></para>
+ </section>
+ <section>
+ <title>Object-as-singleton declarations</title>
+ <para></para>
+ </section>
</section>
-
- <section><title>Function-as-class declarations</title>
- </section>
-
- <section><title>Object-as-singleton declarations</title>
- </section>
-
-</section>
</chapter>
Modified: openlaszlo/trunk/docs/src/developers/docbook-local.dbk
===================================================================
--- openlaszlo/trunk/docs/src/developers/docbook-local.dbk 2008-02-08 17:47:46 UTC (rev 7985)
+++ openlaszlo/trunk/docs/src/developers/docbook-local.dbk 2008-02-08 17:49:07 UTC (rev 7986)
@@ -1,222 +1,286 @@
<?xml version="1.0"?>
-
<!-- * X_LZ_COPYRIGHT_BEGIN ***************************************************
* Copyright 2007 Laszlo Systems, Inc. All Rights Reserved. *
* 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">
-
-<chapter language="en" id="docbook-local">
-<title>Local Docbook Style Guide</title>
-
-<section><title>Introduction</title>
-
- <para>This chapter contains information about writing Docbook documentation within the OpenLaszlo project. It builds on the standard information available about <ulink url="http://www.docbook.org/tdg/en/html/docbook.html">Docbook itself</ulink> and the <ulink url="http://www.sagehill.net/docbookxsl/">Docbook-XSL tool</ulink>. Content in this chapter assumes you are familiar with the basic information available in those references. For general information about the local Docbook-based OpenLaszlo documentation tool chain, see <xref linkend="doc-toolchain"/>.</para>
-
-</section>
-
-<section><title>General information</title>
-
- <section><title>Index term label generation</title>
- <para>When using an <sgmltag class="element">indexterm</sgmltag> tag, be aware that the text of the corresponding entry in the index will be generated from the <sgmltag class="element">title</sgmltag> or <sgmltag class="attribute">xreflabel</sgmltag> found nearest to the <sgmltag class="element">indexterm</sgmltag> itself.</para>
-
- <informalexample><programlisting><section>
- <title>Including HTML markup in OpenLaszlo applications</title>
- <para>Openlaszlo provides support for incorporating HTML. Here's a list of tags that are supported:</para>
- <simplelist>
- <listitem>
- <indexterm><primary>a</primary></indexterm>
- <sgmltag class="element"><a></sgmltag>
- </listitem>
- <listitem>
- <indexterm><primary>font</primary></indexterm>
- <sgmltag class="element"><font></sgmltag>
- </listitem>
- </simplelist>
-</section>
-</programlisting></informalexample>
-
- <para>Here, the index entry text for <sgmltag class="element">a</sgmltag> and <sgmltag class="element">font</sgmltag> both read, "Including HTML markup in OpenLaszlo applications."</para>
-
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<chapter id="docbook-local">
+ <title>Local Docbook Style Guide</title>
+ <section>
+ <title>Introduction</title>
+ <para>This chapter contains information about writing Docbook
+ documentation within the OpenLaszlo project. It builds on the
+ standard information available about
+ <ulink url="http://www.docbook.org/tdg/en/html/docbook.html">
+ Docbook itself</ulink>and the
+ <ulink url="http://www.sagehill.net/docbookxsl/">Docbook-XSL
+ tool</ulink>. Content in this chapter assumes you are familiar
+ with the basic information available in those references. For
+ general information about the local Docbook-based OpenLaszlo
+ documentation tool chain, see
+ <xref linkend="doc-toolchain" />.</para>
</section>
-
-</section>
-
-<section><title>Markup for class members</title>
-
- <para>Mentions of class members (properties, methods, etc.) within the text that have been properly declared are automatically expanded to include index entries and hyperlinks to the appropriate section of the reference guide.</para>
-
- <para>For example, this declaration:</para>
-
- <informalexample><programlisting><sgmltag class="attribute" role="<replaceable>LzView.__ivars__.resourcewidth</replaceable>"><replaceable>resourcewidth</replaceable></sgmltag></programlisting></informalexample>
-
- <para>is expanded to this Docbook markup:</para>
-
- <informalexample><programlisting><indexterm>
- <primary>resourcewidth</primary>
-</indexterm>
-<link linkend="LzView.__ivars__.resourcewidth">
- <sgmltag class="attribute">resourcewidth</sgmltag>
-</link></programlisting></informalexample>
-
- <para>The <sgmltag class="element">indexterm</sgmltag> block generates an entry in the index. The entry text is automatically derived from the nearest surrounding section title.</para>
-
- <para>The <sgmltag class="element">link</sgmltag> block is a hypertext link into the appropriate reference page. The value of the <sgmltag class="attribute">role</sgmltag> attribute is the same as the automatically-generated <sgmltag class="attribute">id</sgmltag> of that member in the js2doc output.</para>
-
- <section><title>Markup tags that are automatically expanded</title>
- <para>Expansion of markup occurs in the preprocess stage, and requires inclusion of the <sgmltag class="attribute">role</sgmltag> attribute in the relevant tag. The tags currently supported are:
- <simplelist type='inline'>
- <member><sgmltag class="element">structfield</sgmltag></member>
- <member><sgmltag class="element">property</sgmltag></member>
- <member><sgmltag class="element">methodname</sgmltag></member>
- <member><sgmltag class="element">sgmltag</sgmltag></member>
- </simplelist>
- .</para>
- <para>Note that <sgmltag class="element">classname</sgmltag>, <sgmltag class="element">tag</sgmltag>, and other potentially relevant tags, are not currently supported. Adding support should be relatively straightforward, perhaps as simple as adding a new match clause to the relevant XSLT template.</para>
+ <section>
+ <title>General information</title>
+ <section>
+ <title>Index term label generation</title>
+ <para>When using an
+ <sgmltag class="element">indexterm</sgmltag>tag, be aware
+ that the text of the corresponding entry in the index will be
+ generated from the
+ <sgmltag class="element">title</sgmltag>or
+ <sgmltag class="attribute">xreflabel</sgmltag>found nearest
+ to the
+ <sgmltag class="element">indexterm</sgmltag>itself.</para>
+ <informalexample>
+ <programlisting><section> <title>Including HTML
+ markup in OpenLaszlo applications</title>
+ <para>Openlaszlo provides support for incorporating
+ HTML. Here's a list of tags that are
+ supported:</para> <simplelist> <listitem>
+ <indexterm><primary>a</primary></indexterm>
+ <sgmltag class="element"><a></sgmltag>
+ </listitem> <listitem>
+ <indexterm><primary>font</primary></indexterm>
+ <sgmltag class="element"><font></sgmltag>
+ </listitem> </simplelist>
+ </section></programlisting>
+ </informalexample>
+ <para>Here, the index entry text for
+ <sgmltag class="element">a</sgmltag>and
+ <sgmltag class="element">font</sgmltag>both read, "Including
+ HTML markup in OpenLaszlo applications."</para>
+ </section>
</section>
-
- <section><title>Determining <sgmltag class="attribute">role</sgmltag> values</title>
- <para>The simplest way of determining what string to put into the <sgmltag class="attribute">role</sgmltag> value is to find the desired entry in the HTML version of the Reference Guide and note the first <sgmltag class="element">a</sgmltag> tag in the member entry.</para>
-
- <informalexample><programlisting>
- <span class="term">
- <a name="LzView.__ivars__.resourcewidth">
- <a class="indexterm" name="d0e187250">
- "resourcewidth"
- </span>
- </programlisting></informalexample>
-
+ <section>
+ <title>Markup for class members</title>
+ <para>Mentions of class members (properties, methods, etc.)
+ within the text that have been properly declared are
+ automatically expanded to include index entries and hyperlinks
+ to the appropriate section of the reference guide.</para>
+ <para>For example, this declaration:</para>
+ <informalexample>
+ <programlisting><sgmltag class="attribute" role="
+ <replaceable>
+ LzView.__ivars__.resourcewidth</replaceable>">
+ <replaceable>
+ resourcewidth</replaceable></sgmltag></programlisting>
+ </informalexample>
+ <para>is expanded to this Docbook markup:</para>
+ <informalexample>
+ <programlisting><indexterm>
+ <primary>resourcewidth</primary>
+ </indexterm> <link
+ linkend="LzView.__ivars__.resourcewidth"> <sgmltag
+ class="attribute">resourcewidth</sgmltag>
+ </link></programlisting>
+ </informalexample>
+ <para>The
+ <sgmltag class="element">indexterm</sgmltag>block generates an
+ entry in the index. The entry text is automatically derived
+ from the nearest surrounding section title.</para>
+ <para>The
+ <sgmltag class="element">link</sgmltag>block is a hypertext
+ link into the appropriate reference page. The value of the
+ <sgmltag class="attribute">role</sgmltag>attribute is the same
+ as the automatically-generated
+ <sgmltag class="attribute">id</sgmltag>of that member in the
+ js2doc output.</para>
+ <section>
+ <title>Markup tags that are automatically expanded</title>
+ <para>Expansion of markup occurs in the preprocess stage, and
+ requires inclusion of the
+ <sgmltag class="attribute">role</sgmltag>attribute in the
+ relevant tag. The tags currently supported are:
+ <simplelist type='inline'>
+ <member>
+ <sgmltag class="element">structfield</sgmltag>
+ </member>
+ <member>
+ <sgmltag class="element">property</sgmltag>
+ </member>
+ <member>
+ <sgmltag class="element">methodname</sgmltag>
+ </member>
+ <member>
+ <sgmltag class="element">sgmltag</sgmltag>
+ </member>
+ </simplelist>.</para>
+ <para>Note that
+ <sgmltag class="element">classname</sgmltag>,
+ <sgmltag class="element">tag</sgmltag>, and other potentially
+ relevant tags, are not currently supported. Adding support
+ should be relatively straightforward, perhaps as simple as
+ adding a new match clause to the relevant XSLT
+ template.</para>
+ </section>
+ <section>
+ <title>Determining
+ <sgmltag class="attribute">role</sgmltag>values</title>
+ <para>The simplest way of determining what string to put into
+ the
+ <sgmltag class="attribute">role</sgmltag>value is to find the
+ desired entry in the HTML version of the Reference Guide and
+ note the first
+ <sgmltag class="element">a</sgmltag>tag in the member
+ entry.</para>
+ <informalexample>
+ <programlisting><span class="term"> <a
+ name="LzView.__ivars__.resourcewidth"> <a
+ class="indexterm" name="d0e187250"> "resourcewidth"
+ </span></programlisting>
+ </informalexample>
+ </section>
</section>
-
-</section>
-
-<section><title>Inline examples</title>
-
- <section><title>Basic inline examples</title>
- <para>Here is an simple version of an inline example:</para>
-
- <informalexample><programlisting><example>
- <title>A simple animator</title>
- <programlisting language="lzx">
-&lt;canvas height="100" width="500"&gt;
- &lt;window&gt;
- &lt;animator attribute="x" to="100" duration="1000"/&gt;
- &lt;/window&gt;
-&lt;/canvas&gt;</programlisting>
-</example></programlisting></informalexample>
-
- <para>Here is a version that transcludes the source code.</para>
-
- <informalexample><programlisting><example>
- <title>A simple animator</title>
- <programlisting language="lzx" >
- <emphasis><textobject>
- <textdata fileref="programs/animation-$4.lzx"/>
- </textobject></emphasis>
- </programlisting>
-</example></programlisting></informalexample>
-
+ <section>
+ <title>Inline examples</title>
+ <section>
+ <title>Basic inline examples</title>
+ <para>Here is an simple version of an inline example:</para>
+ <informalexample>
+ <programlisting><example> <title>A simple
+ animator</title> <programlisting
+ language="lzx"> &lt;canvas height="100"
+ width="500"&gt; &lt;window&gt; &lt;animator
+ attribute="x" to="100" duration="1000"/&gt;
+ &lt;/window&gt;
+ &lt;/canvas&gt;</programlisting>
+ </example></programlisting>
+ </informalexample>
+ <para>Here is a version that transcludes the source
+ code.</para>
+ <informalexample>
+ <programlisting><example> <title>A simple
+ animator</title> <programlisting language="lzx"
+ >
+ <emphasis><textobject> <textdata
+ fileref="programs/animation-$4.lzx"/>
+ </textobject></emphasis></programlisting>
+ </example></programlisting>
+ </informalexample>
+ </section>
+ <section>
+ <title>Live examples</title>
+ <para>Here is a version that runs within the documentation
+ page:</para>
+ <informalexample>
+ <programlisting><example
+ <emphasis>role="live-example"</emphasis>>
+ <title>Importing a resource</title>
+ <programlisting language="lzx"> <textobject>
+ <textdata fileref="programs/animation-$4.lzx" />
+ </textobject> </programlisting>
+ </example></programlisting>
+ </informalexample>
+ </section>
+ <section>
+ <title>Emphasized Areas</title>
+ <para>Here is a version with highlighted areas:</para>
+ <informalexample>
+ <programlisting><example role="live-example">
+ <title>Controlling animation with a
+ script</title>
+ <emphasis>
+ <programlistingco></emphasis><programlisting
+ language="lzx"> <textobject><textdata
+ fileref="programs/animation-$4.lzx"/></textobject>
+ </programlisting>
+ <emphasis><areaspec> <area units="other"
+ otherunits="/canvas[1]/view[1]/@onclick"/>
+ </areaspec></emphasis>
+ <emphasis>
+ </programlistingco></emphasis></example></programlisting>
+ </informalexample>
+ <para>The
+ <sgmltag class="element">areaspec</sgmltag>block is an
+ OpenLaszlo specialization of Docbook-XSL that highlights any
+ portion of an LZX program that matches the given XPath
+ expression. Here, we are targeting a section of the following
+ LZX source:</para>
+ <informalexample>
+ <programlisting><canvas height="100" width="500">
+ <view bgcolor="red" width="100" height="100"
+ <emphasis>
+ onclick="this.myAnimator.doStart()"</emphasis>>
+ <animator name="myAnimator" attribute="x" to="100"
+ duration="1000" start="false"/> </view>
+ </canvas></programlisting>
+ </informalexample>
+ <para>The XPath expression refers to the attribute
+ highlighted in the above source.</para>
+ </section>
+ <section>
+ <title>Callouts</title>
+ <para>Less commonly, there is a need to use callouts within
+ live examples.</para>
+ <informalexample>
+ <programlisting><example role="live-example">
+ <title>Using attributes and class children
+ together</title> <programlisting
+ language="lzx"> <textobject><textdata
+ fileref="programs/class-1.lzx"/></textobject>
+ </programlisting> </example>
+ <calloutlist> <callout
+ arearefs="N10086"><para>Blah
+ blah</para></callout> <callout
+ arearefs="N10090"><para>Blah
+ blah</para></callout>
+ </calloutlist></programlisting>
+ </informalexample>
+ <para>To accomplish this, we can't use XPath expressions, so
+ we have to embed processing instructions into the
+ source.</para>
+ <informalexample>
+ <programlisting><canvas height="40"> <class
+ name="myframe" extends="view"><?lzx-co N10086 ?>
+ <attribute name="bgcolor" value="red"/> <view
+ x="5" y="5" width="${parent.width-10}"
+ height="${parent.height-10}" bgcolor="blue"/>
+ </class> <myframe width="40"
+ height="40"/><?lzx-co N10090 ?>
+ </canvas></programlisting>
+ </informalexample>
+ </section>
+ <section>
+ <title>Current Gotchas</title>
+ <itemizedlist>
+ <listitem>
+ <para><ulink url="http://www.openlaszlo.org/jira/browse/LPP-4308">
+ LPP-4308</ulink>: Examples whose text is not transcluded
+ (included from an external file) are not
+ pretty-printed.</para></listitem>
+ <listitem>
+ <para> <ulink url="http://www.openlaszlo.org/jira/browse/LPP-4033">
+ LPP-4033</ulink>: Long source code lines are not
+ auto-wrapped.</para></listitem>
+ <listitem>
+ <para><ulink url="http://www.openlaszlo.org/jira/browse/LPP-4146">
+ LPP-4146</ulink>: Reports of erroneously-compiled example
+ scripts are too small to read in devguide.</para></listitem>
+ </itemizedlist>
+ </section>
</section>
-
- <section><title>Live examples</title>
-
- <para>Here is a version that runs within the documentation page:</para>
-
- <informalexample><programlisting><example <emphasis>role="live-example"</emphasis>>
- <title>Importing a resource</title>
- <programlisting language="lzx">
- <textobject>
- <textdata fileref="programs/animation-$4.lzx" />
- </textobject>
- </programlisting>
-</example>
- </programlisting></informalexample>
-
- </section>
-
- <section><title>Emphasized Areas</title>
-
- <para>Here is a version with highlighted areas:</para>
-
- <informalexample><programlisting><example role="live-example">
- <title>Controlling animation with a script</title>
- <emphasis><programlistingco></emphasis>
- <programlisting language="lzx">
- <textobject><textdata fileref="programs/animation-$4.lzx"/></textobject>
- </programlisting>
- <emphasis><areaspec>
- <area units="other" otherunits="/canvas[1]/view[1]/@onclick"/>
- </areaspec></emphasis>
- <emphasis></programlistingco></emphasis>
-</example></programlisting></informalexample>
-
- <para>The <sgmltag class="element">areaspec</sgmltag> block is an OpenLaszlo specialization of Docbook-XSL that highlights any portion of an LZX program that matches the given XPath expression. Here, we are targeting a section of the following LZX source:</para>
-
- <informalexample><programlisting><canvas height="100" width="500">
- <view bgcolor="red" width="100" height="100" <emphasis>onclick="this.myAnimator.doStart()"</emphasis>>
- <animator name="myAnimator" attribute="x" to="100" duration="1000" start="false"/>
- </view>
-</canvas></programlisting></informalexample>
-
- <para>The XPath expression refers to the attribute highlighted in the above source.</para>
-
- </section>
-
- <section><title>Callouts</title>
-
- <para>Less commonly, there is a need to use callouts within live examples. </para>
-
- <informalexample><programlisting><example role="live-example">
- <title>Using attributes and class children together</title>
- <programlisting language="lzx">
- <textobject><textdata fileref="programs/class-1.lzx"/></textobject>
- </programlisting>
-</example>
-<calloutlist>
- <callout arearefs="N10086"><para>Blah blah</para></callout>
- <callout arearefs="N10090"><para>Blah blah</para></callout>
-</calloutlist></programlisting></informalexample>
-
- <para>To accomplish this, we can't use XPath expressions, so we have to embed processing instructions into the source.</para>
-
- <informalexample><programlisting><canvas height="40">
- <class name="myframe" extends="view"><?lzx-co N10086 ?>
- <attribute name="bgcolor" value="red"/>
- <view x="5" y="5" width="${parent.width-10}"
- height="${parent.height-10}"
- bgcolor="blue"/>
- </class>
-
- <myframe width="40" height="40"/><?lzx-co N10090 ?>
-</canvas></programlisting></informalexample>
-
- </section>
-
- <section><title>Current Gotchas</title>
+ <section>
+ <title>Runtime-specific content</title>
+ <para>Docbook content can be marked as runtime specific. This
+ is done using the
+ <sgmltag class="attribute">condition</sgmltag>attribute within
+ a selection of Docbook markup tags.</para>
+ <para>The currently-supported list of tags is
<itemizedlist>
- <listitem><ulink url="http://www.openlaszlo.org/jira/browse/LPP-4308">LPP-4308</ulink>: Examples whose text is not transcluded (included from an external file) are not pretty-printed.</listitem>
- <listitem><ulink url="http://www.openlaszlo.org/jira/browse/LPP-4033">LPP-4033</ulink>: Long source code lines are not auto-wrapped</listitem>
- <listitem><ulink url="http://www.openlaszlo.org/jira/browse/LPP-4146">LPP-4146</ulink>: Reports of erroneously-compiled example scripts are too small to read in devguide</listitem>
+ <listitem>
+ <para><sgmltag class="element">para</sgmltag></para>
+ </listitem>
+ <listitem>
+ <para><sgmltag class="element">title</sgmltag> within a
+ <sgmltag class="element">section</sgmltag></para></listitem>
</itemizedlist>
+ </para>
+ <para>Support within other tags is possible by editing the
+ relevant portion of
+ <literal>docs/src/xsl/conditional-html.xsl</literal>.</para>
+ <para>Currently only one runtime may be given within an
+ <sgmltag class="attribute">condition</sgmltag>attribute.</para>
</section>
-
-</section>
-
-<section><title>Runtime-specific content</title>
-
- <para>Docbook content can be marked as runtime specific. This is done using the <sgmltag class="attribute">condition</sgmltag> attribute within a selection of Docbook markup tags.</para>
-
- <para>The currently-supported list of tags is
- <simplelist type="inline">
- <listitem><sgmltag class="element">para</sgmltag></listitem>
- <listitem><sgmltag class="element">title</sgmltag> within a <sgmltag class="element">section</sgmltag></listitem>
- </simplelist></para>
-
- <para>Support within other tags is possible by editing the relevant portion of <literal>docs/src/xsl/conditional-html.xsl</literal>.</para>
-
- <para>Currently only one runtime may be given within an <sgmltag class="attribute">condition</sgmltag> attribute.</para>
-
-</section>
-
</chapter>
Modified: openlaszlo/trunk/docs/src/developers/js2doc-ref.dbk
===================================================================
--- openlaszlo/trunk/docs/src/developers/js2doc-ref.dbk 2008-02-08 17:47:46 UTC (rev 7985)
+++ openlaszlo/trunk/docs/src/developers/js2doc-ref.dbk 2008-02-08 17:49:07 UTC (rev 7986)
@@ -5,30 +5,30 @@
* 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="js2doc-reference">
+<chapter id="js2doc-reference">
<title>JS2Doc Reference</title>
-<note>This book part is currently being drafted. Stay tuned for more contents!</note>
+<note><para>This book part is currently being drafted. Stay tuned for more contents!</para></note>
+
+ <section><title>Overview</title>
+
+ <para>The <application>js2doc</application> tool extracts reference documentation from ECMAScript (ECMA-262) 3rd Edition source code, with some provision for ECMAScript 4th Edition extensions such as <literal>class</literal>. (It is intended that eventually <application>js2doc</application> will support the full <acronym>ES4</acronym> language once that standard has been finalized.) The tool generates an XML representation of the declarations in the source, augmented by material extracted from specially-formatted comments found adjacent to the program declarations. This XML output can be used to generate human-readable documentation in a number of different formats, or to extract information about the program source under study.</para>
-<section><title>Overview</title>
-
- <para>The <application>js2doc</application> tool extracts reference documentation from ECMAScript (ECMA-262) 3rd Edition source code, with some provision for ECMAScript 4th Edition extensions such as <literal>class</literal>. (It is intended that eventually <application>js2doc</application> will support the full <acronym>ES4</acronym> language once that standard has been finalized.) The tool generates an XML representation of the declarations in the source, augmented by material extracted from specially-formatted comments found adjacent to the program declarations. This XML output can be used to generate human-readable documentation in a number of different formats, or to extract information about the program source under study.</para>
-
- <note>The <application>js2doc</application> tool was built to document JavaScript source associated with the OpenLaszlo project, and as such contains several proprietary extensions in support of OpenLaszlo. The intention is to remove these extensions as the <acronym>ES4</acronym> language nears acceptance.</note>
-
-</section>
-
-<section><title>Format of Structured Comments</title>
-
- <para>Structured comments generally follow the format defined for <ulink url="http://java.sun.com/j2se/javadoc/">javadoc</ulink>.</para>
-</section>
-
-<section><title>Matching Comments to Declarations</title>
-
- <para>The js2doc tool works by matching comments to declarations. Generally speaking, the comment immediately preceding the declaration is matched if it has the correct format. The comment must immediately precede the declaration: if an improperly-formatted (or unformatted) comment intervenes between a properly formatted comment and a declaration, there is no match. Note that special rules apply to a structured comment intended to apply to the source file as a whole; see below for details.</para>
+ <note><para>The <application>js2doc</application> tool was built to document JavaScript source associated with the OpenLaszlo project, and as such contains several proprietary extensions in support of OpenLaszlo. The intention is to remove these extensions as the <acronym>ES4</acronym> language nears acceptance.</para></note>
+
+ </section>
+ <section><title>Format of Structured Comments</title>
+
+ <para>Structured comments generally follow the format defined for <ulink url="http://java.sun.com/j2se/javadoc/">javadoc</ulink>.</para>
+ </section>
+
+ <section><title>Matching Comments to Declarations</title>
+
+ <para>The js2doc tool works by matching comments to declarations. Generally speaking, the comment immediately preceding the declaration is matched if it has the correct format. The comment must immediately precede the declaration: if an improperly-formatted (or unformatted) comment intervenes between a properly formatted comment and a declaration, there is no match. Note that special rules apply to a structured comment intended to apply to the source file as a whole; see below for details.</para>
+
<para>Here is a simple example:</para>
<informalexample><programlisting>/** Whether the process is complete **/
@@ -70,13 +70,13 @@
<para>The js2doc tool tracks the use of top-level conditional expressions and automatically annotates its output with information about those conditionals. Two types of constants are tracked: <emphasis>runtime designators</emphasis>, and <emphasis>build types</emphasis>.</para>
- <para>In the following example, the js2doc output will annotate the <literal>foo</literal> variable as if it had an associated comment with the field <code>@runtimes $swf7</code>.</para>
+ <para>In the following example, the js2doc output will annotate the <literal>foo</literal> variable as if it had an associated comment with the field <literal>@runtimes $swf7</literal>.</para>
<informalexample><programlisting>if ($swf7) {
var foo = 10;
}</programlisting></informalexample>
- <para>Only boolean literals (<literal>true</literal> or <literal>false</literal>) or predefined constants are tracked, but complex boolean expressions combining those elements are supported. In the following example, with a set of three known runtime constants (<literal>$swf7</literal>, <literal>$swf8</literal>, and <literal>$dhtml</literal>) <literal>foo</literal> is annotated as if by <code>@runtimes $swf7 $swf8</code>, and <literal>bar</literal> is annotated as if by <code>@runtimes $dhtml</code>.</para>
+ <para>Only boolean literals (<literal>true</literal> or <literal>false</literal>) or predefined constants are tracked, but complex boolean expressions combining those elements are supported. In the following example, with a set of three known runtime constants (<literal>$swf7</literal>, <literal>$swf8</literal>, and <literal>$dhtml</literal>) <literal>foo</literal> is annotated as if by <literal>@runtimes $swf7 $swf8</literal>, and <literal>bar</literal> is annotated as if by <literal>@runtimes $dhtml</literal>.</para>
<informalexample><programlisting>if ($swf7 || $swf8) {
var foo = 10;
@@ -99,44 +99,44 @@
<varlistentry>
<term>topic</term>
<term>subtopic</term>
- <listitem>The topic and subtopic used to organize this declaration within its output book. Valid only for file-level and top-level declarations.</listitem>
+ <listitem><para>The topic and subtopic used to organize this declaration within its output book. Valid only for file-level and top-level declarations.</para></listitem>
</varlistentry>
- <varlistentry>
- <term>copyright</term>
- <listitem></listitem>
- </varlistentry>
+ <varlistentry>
+ <term>copyright</term>
+ <listitem><para></para></listitem>
+ </varlistentry>
<varlistentry>
<term>access</term>
- <listitem>The visibility (private|public|protected) of the declaration.</listitem>
+ <listitem><para>The visibility (private|public|protected) of the declaration.</para></listitem>
</varlistentry>
<varlistentry>
<term>type</term>
- <listitem>The JavaScript type of the declaration. Will become unnecessary once type declaration support is added to the compiler. May not exist if @lzxtype is given since in that case the JS type can be trivially derived (<code>lz.<replaceable>lzxtype</replaceable></code>).</listitem>
+ <listitem><para>The JavaScript type of the declaration. Will become unnecessary once type declaration support is added to the compiler. May not exist if @lzxtype is given since in that case the JS type can be trivially derived (<literal>lz.<replaceable>lzxtype</replaceable></literal>).</para></listitem>
</varlistentry>
<varlistentry>
- <term>modifiers</term> <listitem>(final|virtual|deprecated|override|abstract|const|readonly|read-only)</listitem>
+ <term>modifiers</term> <listitem><para>(final|virtual|deprecated|override|abstract|const|readonly|read-only)</para></listitem>
</varlistentry>
- <varlistentry>
- <term>param</term>
- <listitem>Used to describe a particular function or method parameter. Format is <code>@param [<replaceable>jstype</replaceable>] <replaceable>name</replaceable> : <replaceable>description</replaceable></code>. The description may be multi-line, as with all comment fields. Ignored if not given as part of a function or method comment.</listitem>
+ <varlistentry>
+ <term>param</term>
+ <listitem><para>Used to describe a particular function or method parameter. Format is <literal>@param [<replaceable>jstype</replaceable>] <replaceable>name</replaceable> : <replaceable>description</replaceable></literal>. The description may be multi-line, as with all comment fields. Ignored if not given as part of a function or method comment.</para></listitem>
</varlistentry>
- <varlistentry>
- <term>return</term>
- <term>returns</term>
- <listitem>Used to describe the return value of a function or method. Format is <code>@param [<replaceable>jstype</replaceable> : ] <replaceable>description</replaceable></code>. The description may be multi-line, as with all comment fields. Ignored if not given as part of a function or method comment.</listitem>
+ <varlistentry>
+ <term>return</term>
+ <term>returns</term>
+ <listitem><para>Used to describe the return value of a function or method. Format is <literal>@param [<replaceable>jstype</replaceable> : ] <replaceable>description</replaceable></literal>. The description may be multi-line, as with all comment fields. Ignored if not given as part of a function or method comment.</para></listitem>
</varlistentry>
- <varlistentry>
- <term>keyword</term>
- <term>keywords</term>
- <listitem>
- <para>The <literal>keywords</literal> field is a mechanism to give various forms of modifiers.</para>
- <variablelist><title>Standard Comment Keywords</title>
+ <varlistentry>
+ <term>keyword</term>
+ <term>keywords</term>
+ <listitem>
+ <para>The <literal>keywords</literal> field is a mechanism to give various forms of modifiers.</para>
+ <variablelist><title>Standard Comment Keywords</title>
<varlistentry>
<term>public</term>
<term>protected</term>
<term>private</term>
- <listitem>Equivalent to giving <code>@access</code>.</listitem>
+ <listitem><para>Equivalent to giving <literal>@access</literal>.</para></listitem>
</varlistentry>
<varlistentry>
<term>final</term>
@@ -147,28 +147,28 @@
<term>const</term>
<term>readonly</term>
<term>read-only</term>
- <listitem>Equivalent to giving <code>@modifiers</code>.</listitem>
+ <listitem><para>Equivalent to giving <literal>@modifiers</literal>.</para></listitem>
</varlistentry>
- </variablelist>
+ </variablelist>
</listitem>
</varlistentry>
</variablelist>
<variablelist><title>OpenLaszlo-specific Comment Fields</title>
<varlistentry>
<term>initarg</term>
- <listitem></listitem>
+ <listitem><para></para></listitem>
</varlistentry>
<varlistentry>
<term>runtimes</term>
- <listitem></listitem>
+ <listitem><para></para></listitem>
</varlistentry>
<varlistentry>
<term>lzxtype</term>
- <listitem></listitem>
+ <listitem><para></para></listitem>
</varlistentry>
<varlistentry>
<term>lzxname</term>
- <listitem></listitem>
+ <listitem><para></para></listitem>
</varlistentry>
</variablelist>
</section>
@@ -193,7 +193,9 @@
</section>
-<section><title>To Do</title>
+<section>
+ <title>To Do</title>
+ <para></para>
</section>
<section id="js2doc-schema"><title>JS2Doc Schema</title>
More information about the Laszlo-checkins
mailing list