Figure, table, and other titles

The following elements all share the designation of formal objects in DocBook because they include a title element and are assigned a number label:

figure
table
example
equation
procedure   if the formal.procedures parameter is set to 1

When processed, these elements have a labeled title that is generated from gentext templates for each locale. To customize the generated title text, see the section “Customizing generated text”.

Formal title placement

By default, the generated title is placed before the object itself. You can move the title to appear after the object by altering the formal.title.placement parameter. The default value of that parameter in fo/param.xsl or html/param.xsl looks like the following:

<xsl:param name="formal.title.placement">
figure before
example before
equation before
table before
procedure before
</xsl:param>

The parameter is pairs of strings, each pair matching an element name to a location string. They are all before by default. In your customization layer, you can modify this parameter to place titles after the object. The following example moves figure and equation titles to appear below their respective content:

<xsl:param name="formal.title.placement">
figure after
example before
equation after
table before
procedure before
</xsl:param>

Be sure to keep the values paired up, or the stylesheet will not parse the parameter properly. The string does not have to be after; it just has to be anything except before to work.

If you output both print and HTML, then you can put different values of this parameter in the respective stylesheet customization files.

Formal title numbering

Formal elements like table, figure, and example are all automatically numbered by the stylesheets. In general, these titles are generated by processing the formal element in mode="object.title.markup". In that mode, the element's gentext template is taken from the locale file such as common/en.xml using the context="title" section of the file. The following example shows the gentext template for figure, except the non-breaking space characters are replaced by ordinary spaces for clarity:

<l:context name="title">
  <l:template name="figure" text="Figure %n. %t"/>

The %n code is replaced by the number during processing, and the %t by the title. The number itself is generated by processing the element in mode="label.markup", and the title using mode="title.markup".

If you want to display just titles for your formal elements, you must customize its gentext templates and the label.markup mode for each element. See the section “Table titles without number labels” to see how it is done for tables.

If you want to remove just the chapter number prefix and number the elements continuously through a book, then you need to customize the template in mode="label.markup". That template is found in common/labels.xsl. Much of that template deals with generating the prefix, so if you eliminate the prefix, the template is much shorter. The key line is highlighted in this example customization:

<xsl:template match="figure|table|example" mode="label.markup">
  <xsl:choose>
    <xsl:when test="@label">
      <xsl:value-of select="@label"/>
    </xsl:when>
    <xsl:otherwise>
      <xsl:number format="1" from="book|article" level="any"/>
    </xsl:otherwise>
  </xsl:choose>
</xsl:template>

Note that the choice of using a label attribute is retained. If you want to override the number for a given formal element, you can add a label attribute to the element in your XML document. That value (any text string) will be used instead of the regular generated number for that instance.

Formal title customization

You can change some format features for titles of tables, figures, and examples in print output using the attribute-set named formal.title.properties. See the section “Formal title properties” for examples. For HTML output, similar formatting properties can be applied using CSS.

Any such properties are applied to both the number label and the title. If you want to separately format the number and the title, or change the layout of your formal element titles, then consider customizing the template named formal.object.heading from either fo/formal.xsl or html/formal.xsl. That template uses mode="object.title.markup" to generate the number and title. To separate them, you should replace that mode with separate modes for label and title. The following example customization for print output applies different attribute-sets to label and title.

<xsl:template name="formal.object.heading">
  <xsl:param name="object" select="."/>
  <xsl:param name="placement" select="'before'"/>

  <fo:block>
    <xsl:choose>
      <xsl:when test="$placement = 'before'">
        <xsl:attribute
               name="keep-with-next.within-column">always</xsl:attribute>
      </xsl:when>
      <xsl:otherwise>
        <xsl:attribute
               name="keep-with-previous.within-column">always</xsl:attribute>
      </xsl:otherwise>
    </xsl:choose>
    <fo:inline xsl:use-attribute-sets="formal.label.properties"> 
      <xsl:call-template name="gentext">
        <xsl:with-param name="key" select="local-name($object)"/>
      </xsl:call-template> 
      <xsl:text> </xsl:text>
      <xsl:apply-templates select="$object" mode="label.markup">
      <xsl:text>: </xsl:text>
    </fo:inline>
    <fo:inline xsl:use-attribute-sets="formal.title.properties"
      <xsl:apply-templates select="$object" mode="title.markup"/>
    </fo:inline>   
  </fo:block>
</xsl:template>

This customization generates the localized element name by calling the gentext template with the key parameter set to the element's name. It adds a space and then it generates the number using mode="label.markup", then adds a colon and space, and then wrapping it all in an fo:inline to apply an attribute-set. Then it generates the title using mode="title.markup" and applies a different attribute-set.

For HTML output, a similar customization can be used, except using HTML span elements with class attributes, which can then be formatted using a CSS stylesheet.