5.7. Images

Important:

Image support in the documentation is currently extremely experimental. The mechanisms described here are unlikely to change, but that is not guaranteed.

Installation of the graphics/ImageMagick port is required. It is used to convert between the different image formats. This port is not in the textproc/docproj meta port, it must be installed by hand.

The best example of what follows in practice is the doc/en_US.ISO8859-1/articles/vm-design/ document. If the description that follows is unclear, take a look at the files in that directory to see how everything hangs together. Experiment with creating different formatted versions of the document to see how the image markup appears in the formatted output.

5.7.1. Image Formats

Two image formats are currently supported. Which to choose will depend on the nature of the image.

Images that are primarily vector based, such as network diagrams, time lines, and similar, should be in EPS (Encapsulated Postscript) format. These images have a .eps extension.

For bitmaps, such as screen captures, use the PNG (Portable Network Graphic) format. These images have the .png extension.

These are the only formats in which images should be committed to the Subversion repository.

Use the appropriate format for each image. It is to be expected that documentation will have a mix of EPS and PNG images. The Makefiles ensure that the correct format image is chosen depending on the output format that you use for your documentation. Do not commit the same image to the repository in two different formats.

Important:

It is anticipated that the Documentation Project will switch to using the SVG (Scalable Vector Graphic) format for vector images. However, the current state of SVG capable editing tools makes this impractical.

5.7.2. Image Markup

The markup for an image is relatively simple. First, markup a mediaobject. The mediaobject can contain other, more specific objects. We are concerned with two, the imageobject and the textobject.

Include one imageobject, and two textobject elements. The imageobject will point to the name of the image file (without the extension). The textobject elements contain information that will be presented to the user as well as, or instead of, the image itself.

There are two circumstances where this can happen.

  • When the reader is viewing the documentation in HTML. In this case, each image will need associated alternate text to show the user, typically while the image is loading, or if they hover the mouse pointer over the image.

  • When the reader is viewing the documentation in plain text. In this case, each image should have an ASCII art equivalent to show the user.

An example will make things easier to understand. Suppose there is an image called fig1.png that is to be included in the document. This image is of a rectangle with an A inside it. The markup for this would be as follows.

<mediaobject> <imageobject> <imagedata fileref="fig1"> 1 </imageobject> <textobject> <literallayout class="monospaced">+---------------+ 2 | A | +---------------+</literallayout> </textobject> <textobject> <phrase>A picture</phrase> 3 </textobject> </mediaobject>

1

Include an imagedata element inside the imageobject element. The fileref attribute should contain the filename of the image to include, without the extension. The stylesheets will work out which extension should be added to the filename automatically.

2

The first textobject contains a literallayout element, where the class attribute is set to monospaced. This is an opportunity to demonstrate ASCII art skills. This content will be used if the document is converted to plain text.

Notice how the first and last lines of the content of the literallayout element butt up next to the element's tags. This ensures no extraneous white space is included.

3

The second textobject contains a single phrase element. The contents of this phrase will become the alt attribute for the image when this document is converted to HTML.

5.7.3. Image Makefile Entries

Images must be listed in the Makefile in the IMAGES variable. This variable must contain the names of all the source images. For example, if there are three figures, fig1.eps, fig2.png, fig3.png, then the Makefile should have lines like this in it.

… IMAGES= fig1.eps fig2.png fig3.png …

or

… IMAGES= fig1.eps IMAGES+= fig2.png IMAGES+= fig3.png …

Again, the Makefile will work out the complete list of images it needs to build the source document, you only need to list the image files you provided.

5.7.4. Images and Chapters in Subdirectories

Be careful when separating documentation into smaller files in different directories (see Section 3.7.1, “Using General Entities to Include Files”).

Suppose there is a book with three chapters, and the chapters are stored in their own directories, called chapter1/chapter.xml, chapter2/chapter.xml, and chapter3/chapter.xml. If each chapter has images associated with it, it is suggested to place those images in each chapter's subdirectory (chapter1/, chapter2/, and chapter3/).

However, doing this requires including the directory names in the IMAGES variable in the Makefile, and including the directory name in the imagedata element in the document document.

For example, if the book has chapter1/fig1.png, then chapter1/chapter.xml should contain:

<mediaobject> <imageobject> <imagedata fileref="chapter1/fig1"> 1 </imageobject> … </mediaobject>

1

The directory name must be included in the fileref attribute.

The Makefile must contain:

… IMAGES= chapter1/fig1.png …

Then everything will work.

This, and other documents, can be downloaded from http://ftp.FreeBSD.org/pub/FreeBSD/doc/

For questions about FreeBSD, read the documentation before contacting <questions@FreeBSD.org>.

For questions about this documentation, e-mail <doc@FreeBSD.org>.