5. Inserting Pictures

It is necessary to insert pictures formats for all possible finished document types. For example: JPG files for web pages and EPS for PostScript and PDF files.

If you use the TeX format you'll need the images as a PostScript file. For on-line publishing you can use any kind of common image file, such as JPG, GIF or PNG.

The easiest way to insert pictures is to use the fileref attribute. Usually pictures are generated in JPG and in PostScript (PS or EPS).

Example D.6. Inserting a picture

<figure>
   <title>Picture's
   Title</title> <graphic fileref="images/file"></graphic>
</figure> 

Replacing <figure> by <informalfigure> eliminates the need to insert a title for the picture.

There's still the float attribute on which the value 0 indicates that the picture should be placed exactly where the tag appears. The value 1 allows the picture to be moved to a more convenient location (this location can be described on the style sheet, or it can be controlled by the application).

5.1. Graphics formats

When submitting graphics to the LDP, please submit one set of graphics in .eps, and another in .gif, .jpg or .png. The preferred format is .png or .jpg due to patent problems with .gif.

You can use .jpg files for continuous-tone images such as photos or images with gradual changes in color. Use .png for simple images like diagrams, some screen shots, and images with a low number of colors.

5.2. Alternative Methods

The first alternative to Example D.6, “Inserting a picture” is to eliminate the <figure> or <informalfigure> elements.

Another interesting alternative when you have decided to publish the text on media where pictures are not accepted, is the use of a wrapper, <imageobject>.

Example D.7. Using <imageobject>

<figure>
   <title>Title</title> 
   <mediaobject>
      <imageobject>
	 <imagedata fileref="images/file.eps" format="EPS">
      </imageobject> 
   <imageobject>
	 <imagedata fileref="images/file.jpg" format="JPG">
      </imageobject> 
      <textobject>
	 <phrase>Here there's an image of this example</phrase>
      </textobject> 
   <caption>
   <para>Image Description. Optional. </para>
   </caption>
   </mediaobject>
</figure> 

Files using the following formats are available BMP, CGM-BINARY, CGM-CHAR, CGM-CLEAR, DITROFF, DVI, EPS, EQN, FAX, GIF, GIF87A, GIF89A, IGES, JPEG, JPG, LINESPECIFIC, PCX, PIC, PS, SGML, TBL, TEX, TIFF, WMF, WPG.

This method presents an advantage: a better control of the application. The elements <imageobject> are consecutively tested until one of them is accepted. If the output format does not support images the <textobject> element will be used. However, the biggest advantage in usage of the format Example D.7, “Using <imageobject> is that in DocBook 5.0, the <graphic> element will cease to exist.

As a disadvantage, there is the need for more than one representation code of the same information. It is up to the author to decide how they will implement illustrations and pictures in the document, but for compatibility with future versions I recommend the use of this method for pictures and graphics.

Title page exception

<mediaobject>s will not display if they are used on a title page. For more information read: http://www.sagehill.net/docbookxsl/HtmlCustomEx.html#HTMLTitlePage

ASCII Images

You may also want to try converting your image to an ASCII representation of the file. JavE (Java ASCII Versatile Editor) can do this conversion for you. It can be downloaded from http://www.jave.de/. It has an easy to use GUI interface.

If you're more command-line oriented you may want to try: tgif (http://bourbon.usc.edu:8001/tgif/) and AA-Lib (http://aa-project.sourceforge.net/).