Writing documentation with DocBook-XML 4.3

For some types of graphics, such as photos or screenshots, the technique above will work fine.

However, due to the different resolutions of screens and printers, some types of graphics—especially diagrams and other vector-type drawings—will not look right both in Web and print presentation.

Consider the case of a graphic prepared using a drawing program such as xfig. If the graphic is exported as a JPEG or GIF image, it must be rasterized. If it rasterized at its design size, it might look okay on a screen, but in print it is likely to suffer from aliasing, the “stairstep” effects caused by not enough dots.

A solution that works for print presentation is to export the figure at some large magnification, like 200% or 400%, and then use scale="50" or scale="25" to shrink it down so it fits into the right space on the printed page.

However, the problem with that approach is that the graphic will now be two or four times too large in its Web form.

The solution is to prepare two different forms of the original graphic, one optimized for print presentation and one for Web use.

Once you have prepared the two forms, you can then include them in the same document as two different imageobject elements within the same mediaobject element.

In the HTML version, add to the mediaobject element an attribute role="html". In the PDF version, add an attribute role="fo".

For example, suppose you have produced a diagram in the xfig drawing program and called it flow.fig. For HTML, export it as in PNG format as flow.png; then export it in PDF format as flow.pdf. To include both figures, you might use this construct:

<figure>
  <title>Mill flow diagram</title>
  <mediaobject>
    <imageobject role="html">
      <imagedata fileref="flow.png"/>
    </imageobject>        
    <imageobject role="fo">
      <imagedata fileref="flow.pdf"/>
    </imageobject>        
  </mediaobject>
</figure>

Once you have this dual presentation in place, you can adjust the size of each figure independently by using scale="…" attributes in the imagedata elements.