Making CalloutsCallouts 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
arearefsattribute 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>. Theidattribute should contain a unique name for the item. Thecoordscontains 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 thescreenelement.
Example A.12. 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 directory.</para>
</callout>
<callout arearefs="updir1">
<para>One directory 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 directory, 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 directory. |
❷ | One directory 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 directory, 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 A.13. 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 directory.</para> </callout> <callout arearefs="file"> <para>An ordinary file.</para> </callout> </calloutlist>
Again it is 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 ❸
<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.