面白い機能として、コードの一部を指定して、それにコメントを付ける というのがあります。DocBook を使えば、プログラムコードを文書に挿入して、 そのコードの特定の行に「しるし(callout)」を付けることができます。
この機能は、例えば、カタログファイルの設定方法を説明した際に、使用して います。(Section 4.3 参照)
その際に使ったコードを以下に示します。「しるし(callout)」機能の使用が 望ましくないケースでは、<areaspec> と <calloutlist> に挟まれた空間を消去する こともできます。
(訳注: Table 4-1同様、<to> </to> は <para> </para> に修正しました。)
<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">
<para> Comment. Comments begin with <quote>--</quote>
and follows to the end of the line. </para>
</callout>
<callout arearefs="ex.catalogue.definition">
<para> 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>
|
<example> や <para> エレメントを使わなくとも、コメント(listing)は、直接本文内に 書くことができます。
「しるし」の位置は、コメントが書かれたコード位置に合うように処理され ます。