People who are familiar with HTML markup often try to use the
width attribute in an
imagedata tag to scale their graphic. And often it works. But when they try to use other image attributes, they get strange results. Image sizing can be somewhat complex because there are many
imagedata attributes that affect it. In addition to sizing the image itself, you can specify a viewport area, which is the space reserved for the image. If the viewport area is larger than the final image size, then there is white space around it. If the viewport area is smaller than the final image size, then the image is supposed to be clipped (but it does not happen in HTML output, may not happen in print output).
These are the attributes available in the
imagedata element for sizing:
Imagedata scaling attributes
px Pixels (the default unit if none is specified) pt Points (1/72 of an inch) cm Centimeters mm Millimeters pc Picas (1/6 of an inch) in Inches em Ems (type size) % Percentage (of intrinsic image size)
If one of these attributes is specified, then the image is scaled proportionally to that size. You can stretch the image by specifying values for both attributes that differ from the original ratio of width to height of the image.
Specify the horizontal width and vertical height, respectively, of the viewport area, not the graphic. It uses the same units as above, except percentage is taken to be of the available area (so 50% means half the available width after the current indent is subtracted). If these attributes are not specified, then the viewport is the whole page. These attributes will not affect the size of the image itself, with one exception. For backwards compatibility, if they are used without any other scaling attributes, the stylesheets will scale the image itself to the specified sizes. Think of it as a way of specifying the viewport area with the assumption that it should be filled up.
A percentage scaling factor, but expressed without the percent sign. A value of
75 means to scale the graphic to 75% of its intrinsic size. It scales both width and height proportionally, so the image retains its original aspect ratio.
If set to a value of
1, then the processor will scale the graphic proportionally to fit the allowed area. The image is scaled to fit the specified
depth viewport dimension, whichever fills up first. If neither are specified, then it will scale to the available page width.
The definitive description of how these attributes are supposed to affect the output appears in the reference page for imagedata in DocBook: The Definitive Guide. In practice, some of the attributes are not fully supported by some processors.
Here is some guidance for using the scaling attributes.
To scale a graphic to a given width, set the
contentwidth in the
imagedata element to that size, for example
contentwidth="8.5cm". If you specify a number without units, it is assumed to be pixels.
To scale a graphic to fit the available width in printed output, use
scalefit="1" attributes. For indented text as in a list, the available width is from the current indent to the right margin.
To keep a graphic for printed output at its natural size unless it is too large to fit the available width, in which case shrink it to fit, use
To set a default viewport width for graphics that have no scaling attributes, set the stylesheet parameter
default.image.width parameter to the desired width. This sets only the
viewport size, not the image size. For HTML output, if no other
scaling attribute is used, then the image will be scaled to fit this
viewport. For print output, the image is not scaled to fit this
Using percentages in
contentwidth to scale a graphic for HTML output can be tricky. It means a percentage of the image's intrinsic width, but the XSLT processor will not be able to figure out what is the intrinsic width of a graphic unless it uses an extension function. See the section “Graphic size extension”.
In HTML output, combinations of
width are handled by putting the graphic in an HTML table. The
width attribute sets the table width to create a reserved area, and the
contentwidth is used to scale the image within the table.
The following attributes are mutually exclusive:
scalefit. If more than one of these attributes is used on an image, then the earliest one in this list takes precedence.
Some XSL-FO processors do not support all of these attributes. You may need to experiment to see what works. For example, FOP version 0.20.5 treats
width as if it were
contentwidth and ignores any real
The DocBook XSL stylesheets come with an XSL extension function written in Java that can be used to extract the intrinsic size information from an image file. Most bitmap formats include header information that identifies the width and height in pixels of the image, and sometimes intended dots per inch (dpi).
When an image is processed for print output, the stylesheet passes the image filename to the FO file. The XSL-FO processor opens the image file, reads the header information, and adjusts the size of the image based on that information as it adds the image to the PDF file. For HTML output, the styleshet passes the image filename to the HTML file, but the image file is not opened until it is read by the web browser, so no image data can be used by the stylesheet in sizing the image.
The stylesheet needs the intrinsic image size when the
contentdepth attributes in an
imagedata element are expressed as percentages. For those two attributes, the percentage is of the intrinsic image size, not the page size.
The XSLT standard does not provide a function to read image data, but the DocBook XSL stylesheets provide extension functions written in Java to do so. Since they are written in Java, they are only available with the Saxon and Xalan processors. The appropriate extension jar file needs to be configured into your Java CLASSPATH to make them available, as described in the section “Installing Saxon”.
To enable the extension function, set the
graphicsize.extension stylesheet parameter to 1, and also set the
use.extensions parameter to 1. Then if the stylesheet needs to perform any computation on the
contentwidth value, the extension function will open the image file to get intrinsic width information to use in the calculation. Without that information, the stylesheet has to fall back to the fixed value in the
nominal.image.width parameter, which has a default value of 540 pixels for HTML output. Since that is not likely the actual image size, the results will not be very satisfactory.
If you set the extensions parameters but the results are not as expected, then check to make sure your CLASSPATH is set correctly. If the stylesheet cannot find the Java graphic size extension function, it does not report an error. Instead, it falls back to a default value. That is the only extension function that does not report an error if it is not available.
One complication arises when you are using the
img.src.path parameter to prepend an output path to each
fileref value in the
src value. Normally the extension function just uses the
fileref value to locate the image file to open and read. If it needs to include the
img.src.path value to locate the file to open, then also set the stylesheet parameter
graphicsize.use.img.src.path to 1.
You may find that you need to scale an image differently in HTML than in FO output. You can do this by creating nearly duplicate
imageobject elements in a
mediaobject. You can put different values for the scaling attributes in the
imagedata element in each
imageobject. Then you let the stylesheet select the appropriate
imageobject for a given output. See the section “Selecting file formats” for more information.
If you just want to turn off scaling for HTML output, then that is even easier. If you set the stylesheet parameter
ignore.image.scaling to a non-zero value, then all images in HTML output will
appear in their intrinsic size. So you use the scaling attributes
solely for FO output, and they will be ignored for HTML
|DocBook XSL: The Complete Guide - 4th Edition||PDF version available|
Copyright © 2002-2007 Sagehill Enterprises