Writing documentation with DocBook-XML 4.2 |  |
Writing documentation with DocBook-XML 4.2 | |
You can easily include images in a DocBook document. However, you may have to produce two different versions of some images so that they will look decent in both print and Web presentation.
A formal figure is a graphic image presented with a title. For example, suppose you have scanned a photo and called the result lanai.jpg. Here is how you would include that photo as a formal figure:
<figure>
<title>Lanai from the air</title>
<mediaobject>
<imageobject>
<imagedata fileref="lanai.jpg"/>
</imageobject>
</mediaobject>
</figure> |
An informal figure is just a figure without the title. To present the same graphic as an informal figure:
<informalfigure>
<mediaobject>
<imageobject>
<imagedata fileref="lanai.jpg"/>
</imageobject>
</mediaobject>
</informalfigure> |
If you want to change the displayed size of the image, add an attributes scale="P" to the <imagedata> element, where P is the percentage size, e.g., 33 for one-third size.
Here is an example of a 500x100-pixel panel from Pokey the Penguin shown first at half size (scale="50"), then at one-quarter size (scale="25").
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.
For Web presentation, prepare the graphic as one of the common rasterized formats: JPEG, PNG, or GIF.
If possible, use PDF format for print presentation. PDF format is a scalable vector representation that allows the graphic to be scaled in a way optimized for the specific printer being used to render it.
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. Tag the <mediaobject> element with the Web version with an attribute role="html", and tag the print <mediaobject> with 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 on the <imagedata> elements.
When sizing a figure for presentation, there are two different areas involved:
The image size is the size of the image itself.
The viewport is the area in which the figure is supposed to be presented.
If one dimension of the image is smaller than that dimension of the viewport, the result will be empty space around the figure. But what if the viewport is smaller than the image? In print presentation, the image will be cropped; but in Web presentation the image will not be cropped.
In general there are six different attributes of <imagedata> that affect scaling:
These attributes set the desired image size. The attribute value must be a number, optionally followed by one of the dimension codes px (pixels, the default), pt (points), cm (centimeters), mm (millimeters), pc (picas), in (inches), em (ems), or % (percent, relative to the page width for horizontal dimensions).
For example, if you want the image to be 125mm×75mm, use:
<imagedata contentwidth="125mm" contentdepth="75mm" ...> |
You need only specify one of these two attributes; if only one dimension is specified, the other dimension will be scaled to preserve the aspect ratio (ratio of height to width).
These attributes size the viewport. If you specify the width as a percentage (%), it will be treated as a percentage of the available page width.
Resizes the graphic as a percentage of the original; omit the % symbol from the attribute value. For example, to render a graphic half-size, use scale="50".
If you specify scalefit="1", the graphic will be scaled to fit the available area—either the graphic size or the viewport size, whichever is filled first. If you specified no other sizing attributes, the graphic will be scaled to fit the page width.
To include an inline figure in the middle of a paragraph, use the <inlinemediaobject> element. Inside this element, place an <imageobject> as above to specify the image, and also include a <textobject> element with the text that should appear in situations where the image cannot be displayed, such as browsers for the visually impaired.
Here is an example:
Use this icon
to create a circle by specifying its diameter.
And here is the source for this paragraph:
<para>Use this icon
<inlinemediaobject>
<imageobject>
<imagedata fileref="circle-2.jpg"/>
</imageobject>
<textobject><phrase>Icon for circle by diameter</phrase>
</textobject>
</inlinemediaobject>
to create a circle by specifying its diameter.</para> |
To capture an image from your screen, follow the procedure below for your operating system.
On Windows 2000 and later systems, press the PrintScrn button. This will take a shot of the entire screen. You can then use the paste function in your favorite photo editor to make a copy of this screen shot, crop out the part you want, and so forth.
To capture an image of a specific rectangular area, press Apple-shift-4 (that is, while holding down the Apple and shift keys, press 4). The cursor will turn into a crosshair symbol. Move the mouse to one corner of the desired area, press and hold the left button, drag the mouse to the opposite corner of the area, and release the button. An icon named “Picture 1” (or other number) will appear in your desktop; this will contain the image of the selected area in PNG (Portable Network Graphics) format.
To capture an image of one window, press Apple-shift-4, and when the cursor turns into a crosshair symbol, press the space bar. The cursor turns into a picture of a camera. Move the mouse into the window you want to photograph, and that window will turn slightly gray. Click the left button and the image icon will appear on your desktop.
To capture an image of the entire screen, use Apple-shift-3.
Gimp, a public-domain package similar to Photoshop, makes it easy to get a screen shot.
Bring up Gimp. From the menu, select , then .
From the Gimp menu, select , then , then .
To capture an image of one window, select the radiobutton for , increase the delay time under , and click . After the delay you have specified, the cursor will turn into a crosshair symbol. Move the cursor into the desired window and click the left mouse button.
To capture an image of the entire screen, select the radiobutton for , increase the delay time under , and click OK. After the delay you have specified, Gimp will take a snapshot of the whole screen.
A window containing your snapshot will appear on your screen. You can use Gimp to crop the image, adjust color and contrast, and the other usual photo processing options. Most operations start by right-clicking on the image.
To save the image to a file, move the mouse into the image window and right-click. Then select , then .
You can navigate to any directory by clicking in the Folder window. Click on “../” to go up one directory; to move down into a directory, click on that directory's name in the Folder window.
Once you are in the right directory, type the name you want to give the graphics file in the Selection field, including the file type suffix such as .png or .jpg, and press Enter.