Graphics are mentioned briefly in Chapter 3 and Chapter 6 in the discussions of blocks and inlines. You will need to consult your formatter's documentation to determine what graphics formats are viable. All the formatters I've used are happy with JPEG.
Color is one of the most generally applicable properties in the specification, which makes it somewhat harder to describe concisely. If you have a CSS background, you might already be familiar with its use on web pages. The coverage is just as broad as in CSS, and indeed many of the properties carry over directly from CSS. The specification of color is quite similar to that in CSS; colors can be specified by name or as Red-Green-Blue (RGB) color value numbers. However, XSL-FO includes additional, more sophisticated ways to specify colors.
While color can add value to presentation, it can also spoil it. It should support your message, not overwhelm it. Use it carefully and it will work well.
The fo:external-graphic formatting object is always inline. If you want it to act like a block, you have to wrap it in a block.
The fo:instream-foreign-object is often used to include Scalable Vector Graphics (SVG) directly in the file, and it has all the same properties as an external-graphic.
fo:external-graphic provides the wrapper for graphics. Why external? Because the actual graphic's file is external to the XML source document. If wrapped in a block or inline, the graphic is appropriately laid out by the formatter, as shown in Example 7-1 and illustrated in Figure 7-1. The size is determined naturally by the actual graphic size; text-align and display-align are used to align the graphic with respect to its area. You can use the content-height and content-width properties to resize a graphic.
<fo:block> <fo:block >Title for the figure</fo:block> <fo:external-graphic src="url(images/pig.jpg)"  content-height="300%" scaling="uniform"/> </fo:block> <fo:block>fo:external-graphic wrapped in a block, and</fo:block> <fo:block>a block containing the graphic wrapped in an inline container, <fo:inline> <fo:external-graphic src="url(images\1.png)"/> </fo:inline> with content both before and after the graphic. </fo:block>
Applies the scaling
The external graphic formatting object acts like a big character, meaning it generates an area with a certain size. The actual size may be defined in a number of ways, which may seem confusing at first. There are, in fact, two pairs of properties that affect the size of the generated area and how the image is displayed in that area. To understand how that works, you need to understand one of the basic concepts underlying the XSL formatting model: the concept of a viewport area/reference area pair. This pair acts like a scrollable window, and the content (in this case, your graphic) is viewed in that window. The viewport area defines the size of the window area, and the reference area defines the size of the graphic area. The viewport area is used when positioning the graphic with respect to other elements in the same line.
The height and width properties of fo:external-graphic (or the writing-mode neutral equivalents, block-progression-dimension and inline-progression-dimension) define the dimensions of the viewport area. The content-height and content-width properties define the dimensions of the reference (graphic) area. Both sets of properties can be specified as fixed-length values or as the special value auto. If the viewport size properties are set to auto, the content size of the graphic determines both the reference area and the viewport area dimensions. If both the content-height and content-width properties are set to auto, the intrinsic size of the graphic, as modified by the value of the property scaling, determines the size.
If one of the content-height or content-width properties is not auto (the default), the formatter should calculate a scale factor and apply it to both dimensions. If both are specified, the behavior depends on whether the property scaling is set to uniform (the default value) or non-uniform. uniform implies that the aspect ratio should be maintained.
If you know how much space you want your graphic to occupy, set the dimensions using width and height, and set the values of content-width and content-height to scale-to-fit. This will make the reference area the same size as the viewport area by scaling the graphic appropriately.
If you have set a specific value for the viewport dimensions and left the content dimensions set to auto, or set them to a different specific value, the reference area is aligned with respect to the viewport area using the text-align and display-align traits. If it is too large for the viewport-area, the graphic is aligned as if it would fit and the overflow trait controls the clipping. If the graphic is smaller than the viewport area, the space around it will be filled according to the background-color or background property.
You might be wondering how the processor knows what to do with the graphic. The content-type property may be used to specify the format explicitly. It may be either a mime-type, specified as content-type='content-type:binary/jpeg', or a namespace prefix. If no content-type attribute is specified, the processor will use an implementation-dependent way of recognizing the graphic format.
What formats does your XSL-FO processor support? If you are lucky, the documentation will tell you. It might also say which compression options are supported for formats both on input and output. When creating PDF files, for example, some graphic formats can be compressed quite effectively (for example, JPEG, bilevel TIFF with the CCITT compression). Try out the combinations until you reach what is probably a compromise: the output satisfies your needs and the processor supports that format, combined with the bandwidth impact on your delivery methods. The higher the quality resolution of the graphic, the greater the space needed for that graphic. (All the examples in this book were created in PNG format, simply because I know the processor I'm using supports it.)
XSL-FO has several properties where color values can be specified. The most common is background-color, which can be specified on most formatting objects. The color property describes the foreground color of text and text decorations, such as under- or over-scoring. It can be specified on fo:block or fo:character (see Chapter 8) and a number of inline formatting objects (see Section 7.5 later in this chapter). In addition to these, color may be specified in the various border properties and in the text-shadow property.
Of the various color-related properties, only the color property itself is automatically inherited. That means that if you specify color='red' on an fo:block, all text in that block and any of its descendants will be red, except where a different color value is specified for a nested flow object. Although the background-color property isn't inherited, you may be fooled into thinking that it is, because the default value for this property is transparent. So if you have specified background-color='red' on an fo:block, its background will be red. Any nested objects for which you don't specify background-color will thus let the underlying color show through.
Which object's background-color is visible depends on the layering of the areas that are generated by formatting objects. This is fairly intuitive, but it can become complicated when using absolutely positioned objects (as with block-container) and in tables where there are several levels. Tables, rows, and columns can each have a background-color. This can mean that different parts of a spanning cell could have different background colors!
Following are a few basic examples to show color use in its more common application. An initial warning: if you are not used to using color in document delivery, please don't get carried away with it. XSL-FO can apply color nearly anywhere and everywhere. Use it carefully and it will enhance you document; abuse it and it will spoil your document. Example 7-2 shows the use of background and border colors, and Figure 7-2 shows the results.
<fo:block background-color="aqua" border-after-color="red" border-after-width="1.2em" border-before-color="blue" border-before-width="1em" border-end-color="silver" border-end-width="1em" border-start-color="green" border-start-width="1em" border-style="solid" padding="6pt" start-indent="1in" end-indent="2in" > A paragraph with a completely specified border. Style is not specified. color varies on each edge</fo:block>
Example 7-3 shows the use of background-color and color when flow objects are nested. Figure 7-3 shows the result.
<fo:block background-color="yellow" color="blue"> A paragraph with blue text on a yellow border. Nested in the text are two inline objects, one of which specifies a different 'color' and one which specifies a different 'background-color' value. Here is the <fo:inline color='green'>green inline</fo:inline>. And here is the <fo:inline background-color='white'>white background inline </fo:inline>. More text in the block after the inlines.</fo:block>
The XSL-FO specification uses the keyword color to designate the value type for color-related properties. There are several ways of specifying the actual color value. As in CSS, a predefined color keyword may be used. The list of keyword color names is as follows: aqua, black, blue, fuchsia, gray, green, lime, maroon, navy, olive, purple, red, silver, teal, white, and yellow. These 16 colors are defined in HTML.
When this range of base colors fails to meet your needs, you may specify the color more exactly using a hexidecimal RGB form such as #FFCCAA. Note that it is not case-sensitive. The format of an RGB value in hexadecimal notation is a # immediately followed by either three or six hexadecimal characters. The three-digit RGB notation (#rgb) is converted into six-digit form (#rrggbb) by replicating digits, not by adding zeros. For example, #fb0 expands to #ffbb00. This ensures that white (#ffffff) can be specified with the short notation (#fff) and removes any dependencies on the color depth of the display.
The specification also defines three built-in functions that may be used to specify a color value. These are:
rgb(numeric, numeric, numeric)
rgb-icc(numeric, numeric, numeric, NCName, numeric, numeric, ...)
The rgb function gives the same result as the hexidecimal form of the specification. In other words, color="#FFCCAA" has the same effect as color="rgb(255, 204, 176)".
The rgb-icc function returns a color from an International Color Consortium (ICC) color profile. The profile to use is defined by the NCName parameter, which is the fourth argument to the function. This must match the name declared in the fo:color-profile element, which is part of the declarations section described in Section 7.4. The first three arguments designate a fallback RGB value, and the fifth and following arguments designate a color in the ICC profile. The number and value of the arguments depend on the specific profile being used. This function is intended for more sophisticated color specifications, such as CMYK, often used in printing.
The system-color function, as the name indicates, provides a way to obtain a system-dependent color value. For example, in an X Window environment this might be one of the colors defined in the X Color database. Or a specific formatter might provide a list of extra named colors accessible in this way.
The fo:color-profile formatting object appears in the fo:declarations formatting object (which appears after the fo:layout-master-set). An XSL-FO stylesheet may contain several color-profile declarations. Each defines a profile named using the color-profile-name attribute. The actual profile definition is designated with the src attribute, which is a URI value. The URI may be a conventional value that is interpreted by the processor or may name an actual external resource containing the ICC profile description. Example 7-4 shows a color profile in use.
<fo:declarations> <fo:color-profile src="url('./myprofile.icc')" color-profile-name="cp1"/> </fo:declarations> <-- Intervening stuff --> <fo:block color='icc-color(200, 200, 50, cp1, 1.45, 2.22)'> A block whose text color is defined using the profile named cp1 </fo:block>
The color-profile declaration can also bear a rendering-intent attribute. The specification says in Section 7.17.3:
rendering-intent permits the specification of a color-profile rendering-intent other than the default. rendering-intent is applicable primarily to color-profiles corresponding to CMYK color spaces. The different options cause different methods to be used for translating colors to the color gamut of the target rendering device.
This section outlines the applicability of color to the various formatting objects available in XSL-FO and provides a few examples.
The various color properties may be applied to the formatting objects listed in Table 7-1.
All page-region objects, block, block-container, all table objects, list-block, list-item, inline, inline-container, external-graphic, foreign-instream-object, character, leader, initial-property-set, bidi-override, page-number, page-number-citation
Same formatting objects as background-color, except for page-region objects and some special cases in tables
block, character, inline, leader, initial-property-set, bidi-override
text-shadow (colors the shadow)
character, leader, page-number, page-number-citation, initial-property-set
The application of color to your document content is a personal thing. It's highly likely that whatever you do with color, some of your readers will object. The only advice is to avoid overdoing it. Color adds visual presentation value, up to a point. Use it sparingly and wisely to enhance your documents.