Chapter 17. Graphics

Graphics are a frequent cause of problems in DocBook documents. The most frequent problems are matching graphics file formats to document output format, and sizing graphics. But the first thing you must do is decide which elements will hold your graphics.

Elements for graphics

DocBook has two main graphic elements. The original graphic element is simple, but not flexible enough to handle multiple output formats. The preferred element for graphics is mediaobject. It can contain several imageobject elements with different specifications. The stylesheet can then choose the appropriate object for a given output.

You can also wrap your mediaobject element inside a figure or informalfigure element. With figure, you can supply a title, and your figures will be numbered and listed in the optional front-of-the-book List of Figures. Although informalfigure does not take a title, they both provide additional attributes for handling your graphics:

pgwide: If your print content is styled so that headings are at the left margin and body text is indented, then setting this attribute to 1 lets you indicate that the figure is wide and should be positioned at the left margin.
float, floatstyle: These attributes let you indicate that the figure can float to the top, left, or right. See the section “Figure floats” for details.

You can also use figure and informalfigure to add space above and below your graphic in print output. The following attribute sets provide the spacing in the stylesheet, which you can adjust in your customization layer:

<xsl:attribute-set name="figure.properties" 
     use-attribute-sets="formal.object.properties"/>

<xsl:attribute-set name="formal.object.properties">
  <xsl:attribute name="space-before.minimum">0.5em</xsl:attribute>
  <xsl:attribute name="space-before.optimum">1em</xsl:attribute>
  <xsl:attribute name="space-before.maximum">2em</xsl:attribute>
  <xsl:attribute name="space-after.minimum">0.5em</xsl:attribute>
  <xsl:attribute name="space-after.optimum">1em</xsl:attribute>
  <xsl:attribute name="space-after.maximum">2em</xsl:attribute>
  <xsl:attribute name="keep-together.within-column">always</xsl:attribute>
</xsl:attribute-set>

<xsl:attribute-set name="informalfigure.properties" 
     use-attribute-sets="informal.object.properties"/>

<xsl:attribute-set name="informal.object.properties">
  <xsl:attribute name="space-before.minimum">0.5em</xsl:attribute>
  <xsl:attribute name="space-before.optimum">1em</xsl:attribute>
  <xsl:attribute name="space-before.maximum">2em</xsl:attribute>
  <xsl:attribute name="space-after.minimum">0.5em</xsl:attribute>
  <xsl:attribute name="space-after.optimum">1em</xsl:attribute>
  <xsl:attribute name="space-after.maximum">2em</xsl:attribute>
</xsl:attribute-set>

The formal.object.properties attribute set is used in the attribute sets for all formal objects, including figures, tables, examples, and equations, so changing it for figure will also change it for those other elements. If that is not desirable, then add the changes to the figure.properties attribute set only. The same is true for informal.object.properties and informalfigure.properties (starting with version 1.66 of the stylesheets).

If you use example or informalexample, then you can use the example.properties or informalexample.properties instead.


Glossary database		Selecting file formats