21.7. Using images

Screen shots are very useful for providing information to users on how particular actions should be performed. DocBook has no intrinsic mechanisms to know exactly how an image should be rendered in the final document. Therefore, it is necessary to provide instructions through element attributes. The following XML code fragment demonstrates how an image can be specified to occupy 80% of the available page width. For screen shots in landscape format, this seems to be an appropriate amount. You may need to experiment a bit to obtain a proper width for your image. Alternatively, you can edit the resolution of the image itself, in order to obtain a proper size during rendering.

<screenshot>
 <title>DHIS2 Login screen</title>
  <mediaobject>
   <imageobject> 
    <imagedata fileref="resources/images/login/dhis2_login_screen.jpg" format="JPG" width="80%"/>
   </imageobject>
  </mediaobject> 
</screenshot>

For other images, depending on their size, a different value may be necessary. If you do not specify a width for you image, and its intrinsic size is larger than the available screen width, the image may overflow in certain document types with a fixed width, such as PDF.

Its is important that all images begin with resources/images/XXXX where XXXX is the folder where the image is actually located. When the documentation is actually built, the images will be copied into the correct location for the different formats. If you are having trouble seeing the image in your editor, be sure you create a symlink to this folder in the corresponding documents content folder.