Documentation Primer/Manual/DocBook Reference/Callouts

Making Callouts

Callouts are difficult, so they have their own chapter. Use callouts when you want to refer from text to specific parts of an image, programlisting, or synopsis. Using callouts with graphics is currently unused, and is somewhat problematic, so they will not (yet) be described here.

<calloutlist>

A list element that contains the callouts themselves. That is, a list of the explanations that belong to the indicated areas in the item being explained.

<callout arearefs="">

The actual explanation or description of the called out area or line. The arearefs attribute should contain the id of the appropriate callout you are referring to.

<programlistingco> and <screenco>

Callouts applied to a programlisting or a screen element. Although they look more difficult than just embedding the callouts directly in the text, they really aren't too hard. The programlistingco contains one areaspec, and one programlisting. The screenco contains one areaspec and one screen element. The programlisting and screen elements are exactly as you would normally have.

<areaspec>

The areaspec contains a list of area elements, each of which describes one single callout.

<area coords="" id=""/>

The area is another of the very few empty elements, so there is no </area>. The id attribute should contain a unique name for the item. The coords contains a pair of numbers which indicate first the line and then the column where the co should appear. The line and column refer to the position in relation to the container element, not the entire document!. That is, in a screenco, the line and column numbers refer to the line within the screen element.

Example: Marking up callouts with <screenco>

<screenco>
	<areaspec>
	  <area coords="2 65" id="currentdir"/>
	  <area coords="3 65" id="updir"/>
	  <area coords="4 75" id="hiddenfile"/>
	  <area coords="10 75" id="backupfile"/>
	  <area coords="13 70" id="hiddendir"/>

<screen>
total 864
drwx------   8 vampyr   vampyr       4096 Oct  2 18:01 ./             
drwxr-xr-x  13 root     root         4096 Oct  1 16:32 ../    
-rw-------   1 vampyr   vampyr         32 Sep  2 14:21 .MCOP-random-seed  
-rw-------   1 vampyr   vampyr          0 Sep  2 14:42 .Xauthority
-rw-r--r--   1 vampyr   vampyr       1899 Aug  6 19:32 .Xdefaults
-rw-------   1 vampyr   vampyr        261 Sep 29 22:59 .bash_history
-rw-r--r--   1 vampyr   vampyr         24 Aug  6 19:32 .bash_logout
-rw-r--r--   1 vampyr   vampyr        285 Aug  6 19:34 .bash_profile
-rw-r--r--   1 root     root          230 Aug  6 19:32 .bash_profile~ 
-rw-r--r--   1 vampyr   vampyr        559 Aug  6 19:32 .bashrc
-rw-r--r--   1 vampyr   vampyr       4044 Aug  6 19:32 .emacs
drwxr-xr-x   7 vampyr   vampyr       4096 Sep 29 17:31 .kde/  
</screen>
</screenco>
<calloutlist>
<callout arearefs="currentdir1"><para>The current folder.</para>
</callout>
<callout arearefs="updir1">
<para>One folder up in the tree.</para>
</callout>
<callout arearefs="hiddenfile1">
<para>A hidden file, indicated by the . beginning the name.</para>
</callout>
<callout arearefs="backupfile1">
<para>A backup or temporary file, indicated by the ~ ending the name.</para>
</callout>
<callout arearefs="hiddendir1">
<para>A hidden folder, which, like a hidden file, is indicated by the . at
the start of the name.</para>
</callout>
</calloutlist>

All this markup above, while it looks complicated is really quite simple if you study it closely. It would generate the following:

total 864
drwx------   8 vampyr   vampyr       4096 Oct  2 18:01 ./             
drwxr-xr-x  13 root     root         4096 Oct  1 16:32 ../    
-rw-------   1 vampyr   vampyr         32 Sep  2 14:21 .MCOP-random-seed  
-rw-------   1 vampyr   vampyr          0 Sep  2 14:42 .Xauthority
-rw-r--r--   1 vampyr   vampyr       1899 Aug  6 19:32 .Xdefaults
-rw-------   1 vampyr   vampyr        261 Sep 29 22:59 .bash_history
-rw-r--r--   1 vampyr   vampyr         24 Aug  6 19:32 .bash_logout
-rw-r--r--   1 vampyr   vampyr        285 Aug  6 19:34 .bash_profile
-rw-r--r--   1 root     root          230 Aug  6 19:32 .bash_profile~ 
-rw-r--r--   1 vampyr   vampyr        559 Aug  6 19:32 .bashrc
-rw-r--r--   1 vampyr   vampyr       4044 Aug  6 19:32 .emacs
drwxr-xr-x   7 vampyr   vampyr       4096 Sep 29 17:31 .kde/

❶ The current folder.

❷ One folder up in the tree.

❸ A hidden file, indicated by the . beginning the name.

❹ A backup or temporary file, indicated by the ~ ending the name.

❺ A hidden folder, which, like a hidden file, is indicated by the . at the start of the name.

<co>

Indicates where a callout is. For KDE HTML documentation, a small numbered graphic will be placed here, and also at the location of the explanation. These numbered graphics are links between the two places. It is entirely possible to embed the callout elements directly in the text you are describing, and this is perhaps the easiest way to do it. It isn't the most specific, but working out the line coordinates to use the more precise elements is difficult, so this way is acceptable for now.

Example: Marking up callouts by embedding directly in text

<screen>
drwxr-xr-x   3 vampyr   vampyr       4096 Aug  6 19:32 .kde2/
lrwxrwxrwx   1 vampyr   vampyr         15 Sep  3 19:46
.kdeinit-whiterabbit.magicians.org-:0 -> /tmp/.kinV4m2iI=  <co id="symlink"/>
-rw-r--r--   1 vampyr   vampyr       2096 Aug  6 19:32 .kderc
-r--------   1 vampyr   vampyr         21 Sep  2 14:21 .kxmlrpcd
-rw-r--r--   1 vampyr   vampyr        185 Aug  6 19:32 .mailcap
-rw-------   1 vampyr   vampyr         31 Sep  2 14:21 .mcoprc
drwxr-xr-x   4 vampyr   vampyr       4096 Aug  6 19:32 .netscape/
-rw-------   1 vampyr   vampyr     777947 Sep  2 14:42 .xsession-errors
drwxr-xr-x   5 vampyr   vampyr       4096 Sep  2 14:42 Desktop/  <co id="dir"/>
drwx------   2 vampyr   vampyr       4096 Aug  6 19:32 tmp/      
-rw-r--r--   1 vampyr   vampyr       3836 Oct 13 16:44 notes.txt <co id="file"/>
</screen>

<calloutlist>
<callout arearefs="symlink">
<para>A symbolic link, indicated by the ->, and showing the location it is
linked to.</para>
</callout>
<callout arearefs="dir">
<para>An ordinary folder.</para>
</callout>
<callout arearefs="file">
<para>An ordinary file.</para>
</callout>
</calloutlist>

Again it's really not as hard as it looks on first glance. This markup would generate the following:

drwxr-xr-x   3 vampyr   vampyr       4096 Aug  6 19:32 .kde2/
lrwxrwxrwx   1 vampyr   vampyr         15 Sep  3 19:46
.kdeinit-whiterabbit.magicians.org-:0 -> /tmp/.kinV4m2iI=  ❶
-rw-r--r--   1 vampyr   vampyr       2096 Aug  6 19:32 .kderc
-r--------   1 vampyr   vampyr         21 Sep  2 14:21 .kxmlrpcd
-rw-r--r--   1 vampyr   vampyr        185 Aug  6 19:32 .mailcap
-rw-------   1 vampyr   vampyr         31 Sep  2 14:21 .mcoprc
drwxr-xr-x   4 vampyr   vampyr       4096 Aug  6 19:32 .netscape/
-rw-------   1 vampyr   vampyr     777947 Sep  2 14:42 .xsession-errors
drwxr-xr-x   5 vampyr   vampyr       4096 Sep  2 14:42 Desktop/  ❷
drwx------   2 vampyr   vampyr       4096 Aug  6 19:32 tmp/      
-rw-r--r--   1 vampyr   vampyr       3836 Oct 13 16:44 notes.txt ❸

❶ A symbolic link, indicated by the ->, and showing the location it is linked to.

❷ An ordinary folder.

❸ An ordinary file.

<imageobjectco>

Currently unused in KDE Documentation.

<mediaobjectco>

Currently unused in KDE Documentation.

<areaset>

Currently unused in KDE Documentation. This and the above two elements will be used eventually (just as soon as I figure out how they work).

<graphicco>

Not to be used in KDE Documentation at all.