Table of Contents
This chapter contains information about writing Docbook documentation within the OpenLaszlo project. It builds on the standard information available about Docbook itselfand the Docbook-XSL tool. 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 Chapter 54, The Documentation Toolchain.
When using an
indextermtag, be aware
that the text of the corresponding entry in the index will be
generated from the
titleor
xreflabelfound nearest
to the
indextermitself.
<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>Here, the index entry text for
aand
fontboth read, "Including
HTML markup in OpenLaszlo applications."
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.
For example, this declaration:
<sgmltag class="attribute" role="
LzView.__ivars__.resourcewidth">
resourcewidth</sgmltag>is expanded to this Docbook markup:
<indexterm>
<primary>resourcewidth</primary>
</indexterm> <link
linkend="LzView.__ivars__.resourcewidth"> <sgmltag
class="attribute">resourcewidth</sgmltag>
</link>The
indextermblock generates an
entry in the index. The entry text is automatically derived
from the nearest surrounding section title.
The
linkblock is a hypertext
link into the appropriate reference page. The value of the
roleattribute is the same
as the automatically-generated
idof that member in the
js2doc output.
Expansion of markup occurs in the preprocess stage, and
requires inclusion of the
roleattribute in the
relevant tag. The tags currently supported are:
structfield
,
property
,
methodname
,
sgmltag
.
Note that
classname,
tag, 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.
The simplest way of determining what string to put into
the
rolevalue is to find the
desired entry in the HTML version of the Reference Guide and
note the first
atag in the member
entry.
<span class="term"> <a
name="LzView.__ivars__.resourcewidth"> <a
class="indexterm" name="d0e187250"> "resourcewidth"
</span>Here is an simple version of an inline example:
<example> <title>A simple
animator</title> <programlisting
language="lzx"> <canvas height="100"
width="500"> <window> <animator
attribute="x" to="100" duration="1000"/>
</window>
</canvas></programlisting>
</example>Here is a version that transcludes the source code.
<example> <title>A simple
animator</title> <programlisting language="lzx"
>
<textobject> <textdata
fileref="programs/animation-$4.lzx"/>
</textobject></programlisting>
</example>Here is a version that runs within the documentation page:
<example
role="live-example">
<title>Importing a resource</title>
<programlisting language="lzx"> <textobject>
<textdata fileref="programs/animation-$4.lzx" />
</textobject> </programlisting>
</example>Here is a version with highlighted areas:
<example role="live-example">
<title>Controlling animation with a
script</title>
<programlistingco><programlisting
language="lzx"> <textobject><textdata
fileref="programs/animation-$4.lzx"/></textobject>
</programlisting>
<areaspec> <area units="other"
otherunits="/canvas[1]/view[1]/@onclick"/>
</areaspec>
</programlistingco></example>The
areaspecblock 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:
<canvas height="100" width="500">
<view bgcolor="red" width="100" height="100"
onclick="this.myAnimator.doStart()">
<animator name="myAnimator" attribute="x" to="100"
duration="1000" start="false"/> </view>
</canvas>The XPath expression refers to the attribute highlighted in the above source.
Less commonly, there is a need to use callouts within live examples.
<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>To accomplish this, we can't use XPath expressions, so we have to embed processing instructions into the source.
<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>Docbook content can be marked as runtime specific. This
is done using the
conditionattribute within
a selection of Docbook markup tags.
The currently-supported list of tags is
para
title within a
section
Support within other tags is possible by editing the
relevant portion of
docs/src/xsl/conditional-html.xsl.
Currently only one runtime may be given within an
conditionattribute.
Copyright © 2002-2008 Laszlo Systems, Inc. All Rights Reserved. Unauthorized use, duplication or distribution is strictly prohibited. This is the proprietary information of Laszlo Systems, Inc. Use is subject to license terms.