When using an indexterm tag, be aware that the text of the corresponding entry in the index will be generated from the title or xreflabel found nearest to the indexterm itself.

<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 a and font both read, "Including HTML markup in OpenLaszlo applications."

Expansion of markup occurs in the preprocess stage, and requires inclusion of the role attribute 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 role value is to find the desired entry in the HTML version of the Reference Guide and note the first a tag 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 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>

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 areaspec 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:

<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>