4.8. Listings and program codes

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.