[Laszlo-checkins] r5691 - in openlaszlo/branches/legals/docs/src/contributors: . images
jgrandy@openlaszlo.org
jgrandy at openlaszlo.org
Tue Jul 17 16:21:15 PDT 2007
Author: jgrandy
Date: 2007-07-17 16:16:20 -0700 (Tue, 17 Jul 2007)
New Revision: 5691
Added:
openlaszlo/branches/legals/docs/src/contributors/docbook-code.dbk
Modified:
openlaszlo/branches/legals/docs/src/contributors/doc-toolchain.dbk
openlaszlo/branches/legals/docs/src/contributors/docbook-local.dbk
openlaszlo/branches/legals/docs/src/contributors/images/doc-toolchain.graffle
openlaszlo/branches/legals/docs/src/contributors/images/doc-toolchain.png
openlaszlo/branches/legals/docs/src/contributors/index.dbk
Log:
Change 20070717-jgrandyw-1 by jgrandyw at jgrandy-mbp.local on 2007-07-17 16:15:36 PDT
in /Users/jgrandyw/dev/svn/openlaszlo/branches/legals2
for http://svn.openlaszlo.org/openlaszlo/branches/legals
Summary: Update doc toolchain diagram, flesh out Docbook local style guide.
New Features:
Bugs Fixed:
Technical Reviewer: (pending)
QA Reviewer: (pending)
Doc Reviewer: (pending)
Documentation:
Release Notes:
Details:
Tests:
Modified: openlaszlo/branches/legals/docs/src/contributors/doc-toolchain.dbk
===================================================================
--- openlaszlo/branches/legals/docs/src/contributors/doc-toolchain.dbk 2007-07-17 23:04:43 UTC (rev 5690)
+++ openlaszlo/branches/legals/docs/src/contributors/doc-toolchain.dbk 2007-07-17 23:16:20 UTC (rev 5691)
@@ -7,8 +7,8 @@
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
-<chapter language="en">
-<title>Documentation Toolchain Overview</title>
+<chapter language="en" id="doc-toolchain">
+<title>Toolchain Overview</title>
<figure>
<title>Toolchain</title>
Copied: openlaszlo/branches/legals/docs/src/contributors/docbook-code.dbk (from rev 5686, openlaszlo/branches/legals/docs/src/contributors/docbook-local.dbk)
Modified: openlaszlo/branches/legals/docs/src/contributors/docbook-local.dbk
===================================================================
--- openlaszlo/branches/legals/docs/src/contributors/docbook-local.dbk 2007-07-17 23:04:43 UTC (rev 5690)
+++ openlaszlo/branches/legals/docs/src/contributors/docbook-local.dbk 2007-07-17 23:16:20 UTC (rev 5691)
@@ -7,30 +7,216 @@
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
-<chapter language="en">
-<title>Documenting Your Code</title>
+<chapter language="en" id="docbook-local">
+<title>Local Docbook Style Guide</title>
-<section><title>The Basics</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>Documenting LZX classes</title>
- <section><title>Using comments</title>
+<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><title>Using the <sgmltag>doc</sgmltag> tag</title>
+</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>
+
+ <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><title>Documenting JavaScript files</title>
+<section><title>Inline examples</title>
- <section><title>JS2 class declarations</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>Function-as-class declarations</title>
+ <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>Object-as-singleton declarations</title>
+ <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><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>
+ </itemizedlist>
+ </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>Currently only one runtime may be given within an <sgmltag class="attribute">condition</sgmltag> attribute.</para>
+
+</section>
+
</chapter>
Modified: openlaszlo/branches/legals/docs/src/contributors/images/doc-toolchain.graffle
===================================================================
(Binary files differ)
Modified: openlaszlo/branches/legals/docs/src/contributors/images/doc-toolchain.png
===================================================================
(Binary files differ)
Modified: openlaszlo/branches/legals/docs/src/contributors/index.dbk
===================================================================
--- openlaszlo/branches/legals/docs/src/contributors/index.dbk 2007-07-17 23:04:43 UTC (rev 5690)
+++ openlaszlo/branches/legals/docs/src/contributors/index.dbk 2007-07-17 23:16:20 UTC (rev 5691)
@@ -52,6 +52,10 @@
<xi:fallback><para>Missing: Docbook Local Style Guide</para></xi:fallback>
</xi:include>
+ <xi:include href="docbook-code.dbk">
+ <xi:fallback><para>Missing: Docbook Code Comment Style Guide</para></xi:fallback>
+ </xi:include>
+
<xi:include href="js2doc-ref.dbk">
<xi:fallback><para>Missing: JS2Doc Reference</para></xi:fallback>
</xi:include>
More information about the Laszlo-checkins
mailing list