12. Callouts

Callouts are used to draw attention to a specific area. They are a little complex so it's best if you experiment with them a little as you go. Here is an example <callout>:

<screen>
bash@host:~/cvs/newbiedoc$ ls -l
total 48
<co id="perm">drwxr-sr-x    2 jesse    jesse        4096 May  4 16:26 CVS<co id="cvs">
drwxr-sr-x    3 jesse    jesse        4096 Mar 29 03:29 dev
drwxr-sr-x    3 jesse    jesse        4096 Apr  8 19:31 general
drwxr-sr-x    3 jesse    jesse        4096 Apr  9 00:15 images
-rw-r--r--    1 jesse    jesse        4133 Apr 22 05:18 index.sgml
drwxr-sr-x    3 jesse    jesse        4096 Apr  2 02:25 metadoc
drwxr-sr-x    3 jesse    jesse        4096 May  4 19:33 metatools
drwxr-sr-x    3 jesse    jesse        4096 Apr  9 02:02 system
drwxr-sr-x    3 jesse    jesse        4096 Mar 29 01:24 text_editing
drwxr-sr-x    3 jesse    jesse        4096 May  4 00:17 tips
drwxr-sr-x    3 jesse    jesse        4096 Mar 29 01:24 utils
</screen>

<calloutlist>
   <callout arearefs="cvs">
      <para>
      This is the CVS directory.  CVS files are stored here.
      </para>
   </callout>

   <callout arearefs="perm">
      <para>
      These are the permissions for the CVS directory.
      </para>
   </callout>
</calloutlist>

Below is an explanation and how it looks formatted.

bash@host:~/cvs/newbiedoc$ ls -l total 48 drwxr-sr-x 2 jesse jesse 4096 May 4 16:26 CVS drwxr-sr-x 3 jesse jesse 4096 Mar 29 03:29 dev drwxr-sr-x 3 jesse jesse 4096 Apr 8 19:31 general drwxr-sr-x 3 jesse jesse 4096 Apr 9 00:15 images -rw-r--r-- 1 jesse jesse 4133 Apr 22 05:18 index.sgml drwxr-sr-x 3 jesse jesse 4096 Apr 2 02:25 metadoc drwxr-sr-x 3 jesse jesse 4096 May 4 19:33 metatools drwxr-sr-x 3 jesse jesse 4096 Apr 9 02:02 system drwxr-sr-x 3 jesse jesse 4096 Mar 29 01:24 text_editing drwxr-sr-x 3 jesse jesse 4096 May 4 00:17 tips drwxr-sr-x 3 jesse jesse 4096 Mar 29 01:24 utils

First we'll start with the <callout> tags themselves. As you can see above they can pretty much be placed anywhere as long as they are contained by the <calloutlist> and </calloutlist> tags. They must have an arearefs="something" attribute. This is essentially a "pointer" which points to the <co> tag which tells the parser where to place the callout graphic. You'll notice that the graphics are in reverse order. This is because the parser parses the code from left to right and top to bottom, one line at a time. I did this by accident but it illustrates something to watch for. In html documents, the callouts are also hyperlinked. A maximum of 10 total callouts can be used. After that, plain text numbers will be used. To get a better understanding of callout graphics, experiment, and reference [ DocBook: The Definitive Guide ]