<refentry id="programlistingco.element">
<?dbhtml filename="programlistingco.html"?>
<refentryinfo>
<pubdate>$Date$</pubdate>
<releaseinfo>$Revision$</releaseinfo>
</refentryinfo>

<refmeta>
<indexterm><primary>elements</primary>
<secondary>programlistingco</secondary></indexterm>
<refentrytitle>programlistingco</refentrytitle>
<refmiscinfo>Element</refmiscinfo>
</refmeta>
<refnamediv>
<refname>programlistingco</refname>
<refpurpose>&programlistingco.purpose;</refpurpose>
</refnamediv>

&programlistingco.synopsis.gen;
<refsect1 condition='ref.description'><title>Description</title>

<para>
Callouts, such as numbered bullets, are an annotation mechanism.  In an
online system, these bullets are frequently <quote>hot,</quote> and clicking on
them sends you to the corresponding annotation.
</para>
<para>
A <sgmltag>ProgramListingCO</sgmltag> is a wrapper around an <sgmltag>AreaSpec</sgmltag> and
a <sgmltag>ProgramListing</sgmltag>.  An <sgmltag>AreaSpec</sgmltag> identifies the locations
(coordinates)
in the <sgmltag>ProgramListing</sgmltag> where the callouts occur.
The <sgmltag>ProgramListingCO</sgmltag> may also contain the list of annotations in
a <sgmltag>CalloutList</sgmltag>, although the <sgmltag>CalloutList</sgmltag> may also
occur outside of the wrapper, elsewhere in the document.
</para>

<para>
It is also possible to embed <sgmltag>CO</sgmltag> elements directly in the
verbatim text, in order to avoid having to calculate the
correct coordinates.  If you decided to go this route, use a 
<sgmltag>ProgramListing</sgmltag> and a <sgmltag>CalloutList</sgmltag> without the
<sgmltag>ProgramListingCO</sgmltag> wrapper.  A <sgmltag>ProgramListingCO</sgmltag>
must specify at least one coordinate.
</para>

<para>
For a complete description of callouts, see <sgmltag>Callout</sgmltag>.
</para>

<refsect2><title>Processing expectations</title>
<para>
&format.block; &pexp.linespecific;
</para>
<para>
The mandatory processing expectations of a <sgmltag>ProgramListingCO</sgmltag> are
minimal: a system is expected to render the program listing and the
callout list, if present.
</para>
<para>
If explicit <sgmltag>CO</sgmltag> elements are embedded in a
<sgmltag>ProgramListing</sgmltag>, they must generate appropriate
callout marks.
</para>
<para>
In online environments, the processing system may be able to instantiate
the linking relationships between the callout marks in the program listing and
the annotations.
Some systems may even be able to go a step further and generate
the callout marks automatically from the coordinate information,
but this level of sophistication is not mandatory.
</para>
</refsect2>


&programlistingco.parents.gen;
&programlistingco.children.gen;
</refsect1>
<refsect1 condition='ref.elem.seealso'><title>See Also</title>
&programlistingco.seealso.gen;
</refsect1>
<refsect1><title>Examples</title>

<informalexample role="example-source">
<programlisting>&programlistingco.example.1.txt;</programlisting>
</informalexample>

<anchor id="ex.os.programlistingco.1" role="HACK-ex.out.start"/>
&programlistingco.example.1.gen;
<anchor id="ex.oe.programlistingco.1" role="HACK-ex.out.end"/>

&programlistingco.example.seealso.gen;
</refsect1>
</refentry>

