10. Listings and program codes

An interesting feature is to show parts of code and the possibility to comment on them. The DocBook allows the insertion of the program code and also callouts to specific lines of this code.

Such a feature was used, for example, to demonstrate how a catalogue file is configured (see Section 4).

The used code was demonstrated below. In case the callout feature isn't desired, it's 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 on the document's body without the need of the element <example> or <para>.

The calling coordinates specifications are done with reference to the code line which will be commented.