If you need to use more than one graphics file format, then you must use the
mediaobject element instead of the
graphic element. You could use profiling to select from among several
graphic elements, but
mediaobject is designed to do it without the need for the profiling step.
mediaobject element is a container for one or more
imageobject elements, each of which has an
imagedata element. Usually, the various images in a
mediaobject are different formats of the same illustration, with the idea that only one of them at a time will be used by the stylesheet. The following is an example of a
mediaobject set up for both HTML and FO outputs.
Example 17.1. Multiple graphics in a mediaobject
<mediaobject id="MousePicture"> <imageobject role="html"> <imagedata format="PNG" fileref="mouse.png"/> </imageobject> <imageobject role="fo"> <imagedata format="PDF" fileref="mouse.pdf"/> </imageobject> </mediaobject>
Note these features of this example:
The DocBook stylesheets can automatically select the right graphic if the
imageobject elements have a
role attribute of either
fo. When you process this example with the html stylesheet, you get the
PNG graphic, and when you process it with the FO stylesheet,
you get the PDF graphic. Remember that the role attribute goes on the
imageobject element, not the
If you are using the xhtml stylesheet, then you can use
role="xhtml" if you need a different format for that output. Otherwise the xhtml stylesheet falls back to the object with
role="html". Other stylesheet customizations such as Website or your own will use the value for the stock stylesheet it is based upon.
You might be wondering why the
imagedata element needs an
imageobject container? Because
imageobject can also contain an
objectinfo element. That element can be used to track information about the image, such as the software that created it, the current revision, the author, etc.
The automatic selection behavior is controlled by the
use.role.for.mediaobject parameter. If it is nonzero, then the role
considered during the selection process. You can turn that behavior
off if you set the parameter to zero.
If you want finer control, then you have the option to use any
role values you want. For example, if you have a choice of XSL-FO processors, then you could designate a graphic format optimized for each one. You might set the role values for two different vector graphics to
fo-xep. Then you pass the selected
role value in a command line parameter
<mediaobject id="MousePicture"> <imageobject role="html"> <imagedata format="PNG" fileref="mouse.png"/> </imageobject> <imageobject role="fo-fop"> <imagedata format="SVG" fileref="mouse.svg"/> </imageobject> <imageobject role="fo-xep"> <imagedata format="PDF" fileref="mouse.pdf"/> </imageobject> </mediaobject>
If you are processing with the FOP processor, then set the parameter
preferred.mediaobject.role="fo-fop" on the command line. The DocBook stylesheet will use the SVG graphic reference into the FO output file. If you are using XEP, then set the parameter
preferred.mediaobject.role="fo-xep" to use the PDF graphic instead.
If you don't use the
role attribute to select from among several
imageobject elements, then the stylesheets will try to make a choice based on file format. The stylesheets contain several lists of file formats that are acceptable for each output type. For the various XSL-FO processors, it checks to see if any of the parameters
xep.extensions is set.
The process of selection by format goes like this:
It looks at the first
imageobject inside the
imagedata element contains a complete SVG graphic and the parameter
use.svg is nonzero, then it accepts that object and doesn't
consider any others.
imagedata element does not contain an SVG graphic, but has a
format attribute, it checks to see if its value is on the format list for that output. If so, then it accepts that object and doesn't consider any others.
If it does not have a
format attribute, it extracts the filename extension from the
fileref attribute. If that value is on the list of extensions for that output, then it accepts that object and doesn't consider any others.
fileref does not have an extension, it checks the
graphic.default.extension parameter to see what extension would be added to such a
file reference. If that value is on the list of extensions for that
output, then it accepts that object and doesn't consider any
If all of these tests fail on the first
imageobject, it repeats them on subsequent objects until it finds an acceptable one.
This selection method is often sufficient, but is somewhat less precise than selecting by role. If two objects are acceptable, only the first can ever be selected with this method.
|DocBook XSL: The Complete Guide - 3rd Edition||PDF version available|
Copyright © 2002-2005 Sagehill Enterprises