An imagemap displays an image in an HTML browser that has active areas that a user can click on to jump to another location. The DocBook HTML stylesheets have some support for creating client-side imagemaps using the mediaobjectco element. But there are some limitations in how imagemaps are supported in the HTML stylesheets.

If you can live with these limitations, imagemaps can be quite useful for certain kinds of documentation efforts. Because the area links must land inside the current document, they are best used for providing dynamic explanation of a diagram., or a graphical map to the rest of the documentation. Unfortunately, none of the area links will be active in a PDF version if you produce that also.

A DocBook imagemap is created using the DocBook elements mediaobjectco, imageobjectco, imagedata, areaspec and area. An optional calloutlist can be used for the link destinations. The following example shows the DocBook elements to produce an imagemap with one area specified.

Example 18.3. DocBook imagemap using calspair units

<mediaobjectco>  1
  <imageobjectco>  2
    <areaspec id="map1"  3
              units="calspair">  4
      <area linkends="callout1"  5
            coords="1000,5000 6000,8000"  6
            id="area1"/>  7
      <imagedata fileref="tablerules.png" />
      <callout arearefs="area1" 8
               id="callout1">  9
        <para>My only callout</para>


You must use a mediaobjecto element instead of a mediaobject element. It can be contained in a figure or example element in you want to add a title.


The imageobjectco element contains a required areaspec, an imageobject, and an optional calloutlist. You do not have to use a calloutlist. The area links can be to any elements inside your documents.


The areaspec element is the container for one or more area elements. Its id attribute becomes the map name in the HTML output.


The units attribute is used to specify what kind of units the coords attribute contains. Only a calspair value and a nonstandard imagemap value are supported currently. You can put a units attribute on each area element, or put one units attribute on areaspec and it will be inherited by all the area elements contained by it.


The area element specifies one area to become a link. Its linkends attribute should contain a reference to an id somewhere in the document. In this case, it is to a callout element below it. Although the DocBook linkends attribute allows more than one id value in it, the HTML imagemap can only take one reference.


The coords attribute specifies the area size and location, using calspair units in this example. See the section “Using calspair coords” for details.


You can specify an optional id attribute on each area, which you can link to from other locations. In most browsers, such links go to the whole graphic, not the specific area in it.


If you use callout as the destination for an area link, then it must have an arearefs attribute that specifies an id for the callout to link back to. Most browsers follow such links to the overall image, not the specific area within the image. A callout is also numbered, so it might be useful to include the numbers in the image if you want them to correspond. Alternatively, you could use a bullet list item or ordinary paragraph with the id as the target of an imagemap link.


The id on the callout element is the destination of the area link in this example.

The following shows how the DocBook XHTML stylesheet renders this imagemap. The various id and coordinate values are shown in bold.

<div class="mediaobjectco">
  <img border="0" usemap="#map1" src="tablerules.png" alt="imagemap"/>
  <map name="map1">
    <area shape="rect" href="#callout1" coords="102,154,614,384"/>
  <div class="calloutlist">
    <table border="0" summary="Callout list">
        <td width="5%" valign="top" align="left">
          <a id="callout1"/>
          <img src="images/callouts/1.png" alt="1" border="0"/>
        <td valign="top" align="left">
          <p>My only callout</p>

Using calspair coords

The hardest part of creating an imagemap in DocBook using calspair units is figuring out how to express the HTML coordinates in the CALS semantics. Here is the description of calspair from DocBook: The Definitive Guide.

The format of the coordinates is "x1,y1 x2,y2". This identifies a rectangle with the lower-left corner at (x1,y1) and the upper-right corner at (x2,y2). The X and Y coordinates are integers in the range 0 to 10000; they express a percentage of the total distance from 0.00 to 100.00%. The lower-left corner is (0,0).

You measure the area in hundredths of percentage of whatever is the size of the graphic, measured from the lower left corner. Note the space between the two pairs of numbers. In Figure 18.1, “DocBook calspair coordinates”, the calspair values are shown as ordinary percentages on the diagram.

Figure 18.1. DocBook calspair coordinates

Since calspair are proportional units, the stylesheet has to determine what the intrinsic pixel size of the whole image is so it can compute the HTML imagemap area, which must be in pixels. Getting the intrinsic image size requires a stylesheet extension. This means you must use either Saxon or Xalan as your XSLT processor, and you must have the appropriate DocBook Java extensions .jar file in your processor's CLASSPATH (see the section “DocBook Saxon and Xalan extensions” for more information). The stylesheet parameters graphicsize.extension and use.extensions must both be set to 1. When these conditions are met, the stylesheet computes the equivalent HTML imagemap pixel units as shown in Figure 18.2, “HTML Imagemap Area Coordinates”.

Norman Walsh has written an article called Image callouts that describes a method and provides a Perl script for creating callouts on images using calspair coordinates without having to perform hand calculations.

Using imagemap coords

If you are using mediaobjectco only to create HTML imagemaps, then the stylesheets provide an easier way to specify the area coordinates. The DocBook DTD enumerates the types of units that can be used in the units attribute, of which only calspair is supported by the stylesheet. However, the enumeration also permits specifying units="other", and then specifying the type of units in the otherunits attribute.

The DocBook stylesheets support setting units="other" and otherunits="imagemap", and then entering the imagemap pixel ranges directly in the coords attribute of a DocBook area element. An imagemap coords value is four numbers in the form x1,y1,x2,y2 (all comma separated). These specify the positions of the upper-left corner (x1,y1) and the lower-right corner (x2,y2) of the area, measured in pixels. The upper-left corner of the entire image is (0,0). The following is an example.

Example 18.4. DocBook imagemap using “imagemap” units

    <areaspec id="map1">  
      <area linkends="callout1"  
      <imagedata fileref="tablerules.png" />

When otherunits="imagemap", the stylesheet just copies the value of the input coords attribute to the output coords attribute. The following figure shows how the same output as the previous calspair example can be achieved by entering the pixel values directly.

Figure 18.2. HTML Imagemap Area Coordinates