This feature allows authors to show parts of code. It also lets allows the author to insert comments within the code using callouts.
This was used to demonstrate how a catalogue file is configured (see Section 4.3). That code is shown below. If the callout feature is not needed, it is possible to eliminate the areas between <areaspec> and <calloutlist>.
<example id="sample-catalog">
<title>Catalog Sample</title>
<programlistingco>
<areaspec>
<area coords="1" id="ex.catalogue.comment">
<area coords="5" id="ex.catalogue.definition">
<area coords="11" id="ex.catalogue.eof">
</areaspec>
<programlisting>
-- Catalogues for the Conectiva S.A. Style --
OVERRIDE YES
PUBLIC "-//Conectiva SA//DTD books V1.0//EN" "/home/ldp/estilos/livros.dtd"
DELEGATE "-//OASIS" "/home/ldp/SGML/dtds/catalog.dtd"
DOCTYPE BOOK /home/ldp/SGML/dtds/docbook/db31/docbook.dtd
-- EOF --
</programlisting>
<calloutlist>
<callout arearefs="ex.catalogue.comment">
<to> Comment. Comments begin with <quote>--</quote>
and follows to the end of the line. </to>
</callout>
<callout arearefs="ex.catalogue.definition">
<to> The public type association
<parameter class="option">"-//Conectiva SA//DTD books V1.0//EN"</parameter>
with the file <filename>books.dtd</filename> on the directory
<filename class="directory">/home/ldp/estilos</filename>. </para>
</callout>
<callout arearefs="ex.catalogue.eof">
<para> Comment informing the end of the file. </para>
</callout>
</calloutlist>
</programlistingco>
</example>
|
The listings can be directly inserted in the document's body without the need of the <example> or <para> elements.
The calling coordinates' specifications are done with reference to the code line which will be commented upon.