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 [EMAIL PROTECTED] 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;/[EMAIL
PROTECTED]'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>
_______________________________________________
Laszlo-checkins mailing list
[email protected]
http://www.openlaszlo.org/mailman/listinfo/laszlo-checkins
