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