Title fonts and sizes

Title fonts and sizes
	Chapter 12. Print customizations

The font families and sizes used for most titles are defined as part of the titlepage setup. See Chapter 10, Title page customization for the general process of customizing titlepages. The titlepage specs also include other elements such as author and publisher. Customizing titlepages for print output is covered more completely in the section “Print title pages”

Some titles also have attribute-sets that can override the titlepage specs. This makes customization a bit easier since you don't have to regenerate XSL templates, but then you have to be careful to not try to change a title through both methods. Some titles also have their own templates, which can be customized to any degree you need.

Your choice of font names depends on those available in the back end XSL-FO processor that converts your FO file to a print format. The processors usually have some built-in font families, and can be configured to add other fonts. Consult your processor documentation for details. Two font names that can reliably be used with any of the XSL-FO processors are Helvetica and Times Roman.

You can also choose to make a title font bold or italic. You can choose bold by specifying font-weight="bold" in the titlepage spec file. You can specify italic by adding font-style="italic". If you specify both properties, you will get bold-italic.

Book titles

A book title's format is specified by the titlepage spec file. If you copied the original fo/titlepage.templates.xml titlepage spec file to create your customized version, it includes a set of entities declared at the top of the file.

<!DOCTYPE t:templates [
<!ENTITY hsize0 "10pt">
<!ENTITY hsize1 "12pt">
<!ENTITY hsize2 "14.4pt">
<!ENTITY hsize3 "17.28pt">
<!ENTITY hsize4 "20.736pt">
<!ENTITY hsize5 "24.8832pt">
<!ENTITY hsize0space "7.5pt"> <!-- 0.75 * hsize0 -->
<!ENTITY hsize1space "9pt"> <!-- 0.75 * hsize1 -->
<!ENTITY hsize2space "10.8pt"> <!-- 0.75 * hsize2 -->
<!ENTITY hsize3space "12.96pt"> <!-- 0.75 * hsize3 -->
<!ENTITY hsize4space "15.552pt"> <!-- 0.75 * hsize4 -->
<!ENTITY hsize5space "18.6624pt"> <!-- 0.75 * hsize5 -->
]>

The set of hsize entities are candidates for use in the titlepage templates. The hsize*space entities are used to set space-before (space above) a heading. These entities are used further down in the spec file where the titlepages for individual elements are defined. The entities let you define a set of sizes that can be used by titles more several elements, giving your document a consistent look. Using an entity lets you change all of them at once by just changing the entity value. In your custom titlepage spec file, you can add and use your own entities as needed, or you can enter specific values in any font-size specification. Regardless of how the values are specified, they are converted to the numbers when the spec file is processed into the titlepage template file that becomes part of your customization layer.

Here are the specs for a book title:

<t:titlepage element="book" wrapper="fo:block">
    <t:titlepage-content side="recto">
      <title
             named-template="division.title"
             param:node="ancestor-or-self::book[1]"
             text-align="center"
             font-size="&hsize5;"
             space-before="&hsize5space;"
             font-weight="bold"
             font-family="{$title.fontset}"/>
     ...

The font-size and space-before specs use entities that were declared at the top of the file. In your customization, you can change the value of the entities, add your own entities, or put your values directly in the spec file, such as font-size="36pt". You can also change or add other properties for the title, and they will be used after you regenerate the titlepage templates from the spec file.

The font-family property is set to the value of the title.fontset parameter. That is an internal parameter that uses the title.font.family parameter that you can specify in your customization layer. That parameter value will be resolved when the generated template is used to process XML files to produce FO output. The actual font family name can be set at runtime on the command line, or in a customization layer. A parameter is used to permit global changes in all titles by simply setting the parameter value. Of course, you don't have to use the parameter in your specification. You can specify individual font names in each spec, or declare some font-family entities as was done for font sizes and use those entity references in your specs. Once you do that, the parameter won't have any effect on those titles. Your XSL-FO processor must be configured for any font you specify, though.

The book's title is finally processed by calling the template named division.title. That template is called within the block that has already set the properties according to the spec file. So you could override the spec file properties by customizing that template. If you do so, be sure to copy the original from the fo/divsion.xsl stylesheet file to add your customizations, because it performs other functions such as adding the id attribute and PDF bookmark.

Chapter titles

Chapter titles can be customized in three ways, listed here from lowest to highest precedence:

Customize the titlepage spec file.
Customize the attribute-set named component.title.properties.
Customize the template named component.title.

Here is the titlepage specification for chapter title, recto side.

<t:titlepage element="chapter" wrapper="fo:block">
    <t:titlepage-content side="recto">
      <title
             named-template="component.title"
             param:node="ancestor-or-self::chapter[1]"
             margin-left="{$title.margin.left}"
             font-size="&hsize5;"
             font-weight="bold"
             font-family="{$title.font.family}"/>
     ...

This example specifies several FO properties for the title element of the chapter. Notice that font-size="&hsize5;" references one of the entities declared at the top of the file.

Here is the XSL template generated from the above spec (indented for clarity):

<xsl:template match="title" mode="chapter.titlepage.recto.auto.mode">  
  <fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" 
            xsl:use-attribute-sets="chapter.titlepage.recto.style" 
            margin-left="{$title.margin.left}" 
            font-size="24.8832pt" 
            font-weight="bold" 
            font-family="{$title.font.family}">
    <xsl:call-template name="component.title">
      <xsl:with-param name="node" select="ancestor-or-self::chapter[1]"/>
    </xsl:call-template>
  </fo:block>
</xsl:template>

You can see that the properties defined in the titlepage spec file are applied to the outer block, which then calls the template named component.title. That template is located in fo/component.xsl and can be copied and customized to any degree to format a chapter title. Inside that template is a block that applies the attribute-set named component.title.properties. Because the attribute-set is used on an inner block, it will override properties that are also specified in the titlepage spec file.

You can customize the component.title template and component.title.properties attribute-set. That template and attribute-set are shared by other component titles, including those of appendix, article, glossary, bibliography, preface, index, dedication, and colophon. So any customizations of that template and attribute-set will change the title style for all of those elements. That may be what you want for consistency of design.

If you want to change just the handling of one element's title, then you should create another template by a different name. For example, you might want to customize titles only for chapter and appendix. Here is how do so:

Copy the component.title named template from fo/component.xsl to your customization file and give it a different name, such as chapappendix.title.

Customize how the label and number are formatted in your new template. This example formats the label and title on separate lines with different attribute-sets:

<xsl:template name="chapappendix.title">
  <xsl:param name="node" select="."/>
  <xsl:variable name="id">
    <xsl:call-template name="object.id">
      <xsl:with-param name="object" select="$node"/>
    </xsl:call-template>
  </xsl:variable>

  <fo:block id="{$id}"
            xsl:use-attribute-sets="chap.label.properties">
    <xsl:call-template name="gentext">
      <xsl:with-param name="key">
        <xsl:choose>
          <xsl:when test="$node/self::chapter">chapter</xsl:when>
          <xsl:when test="$node/self::appendix">appendix</xsl:when>
        </xsl:choose>
      </xsl:with-param>
    </xsl:call-template>
    <xsl:text> </xsl:text>
    <xsl:apply-templates select="$node" mode="label.markup"/>
  </fo:block>
  <fo:block xsl:use-attribute-sets="chap.title.properties">
    <xsl:apply-templates select="$node" mode="title.markup"/>
  </fo:block>
</xsl:template>

The gentext templates generate the appropriate Chapter or Appendix text (in the right language). The mode="label.markup" generates just the label number, and the mode="title.markup" generates the title.

Add your new template to the titlepage spec file in place of component.title where appropriate. For example:

<t:titlepage t:element="chapter" t:wrapper="fo:block"
             font-family="{$title.fontset}">
  <t:titlepage-content t:side="recto" margin-left="{$title.margin.left}">
    <title t:named-template="chappendix.title"
           param:node="ancestor-or-self::chapter[1]"/>
...

Make a similar change for the appendix title in the spec file since it is to share the same customized template.

Create your own attribute-sets named chap.label.properties and chap.title.properties to apply formatting attributes.

Other component titles

The titles of all of the following component elements are processed like chapter titles:

appendix                 preface
article                  index
glossary                 dedication
bibliography             colophon

By default, they all share the use of the component.title template and the component.title.properties attribute-set. They can have their own specs in the titlepage spec file, but such specs can be overriden by the template and attribute-set.

You can customize the title of any of these components in a manner similar to the way chapter titles are customized. See the section “Chapter titles” for examples.

Section titles

Section titles can be customized in three ways, listed from lowest to highest precedence:

Customize properties in the section.title.properties attribute-set, which apply to titles in all section levels.
Customize properties in one of the section.levelX.title.properties attribute-sets, where X is the section level (1 to 6) that the properties are applied to.
Customize the template named section.heading.

You may notice that the titlepage spec file is not included in this list. Although some section title specs are in the titlepage spec file, those specifications are overridden by these attribute-sets. In the case of section titles, attribute-sets are used because there is no way to specify the multiple font sizes for the section element in the titlepage spec syntax, since section can nest to form different section levels.

The formatting properties for section titles are primarily controlled by the attribute-sets, which are defined in the fo/param.xsl stylesheet file, and can be customized in your customization layer.

The style properties for a given section title level are controlled by two attribute sets. The first is section.title.properties which defines properties for all levels of section titles. That is where you put the common properties that give your section titles a consistent look, such as font-family.

There is another attribute-set for each section level, such as section.title.level2.properties, which adds properties only for level 2 sections. A level 2 section uses either the sect2 element, or a section element nested inside another section element. These attribute-sets are where you put properties specific to each section level, such as font-size. These properties can also override any of the same name in section.title.properties.

The following example shows the default section.title.properties attribute set from the fo/param.xsl stylesheet file:

<xsl:attribute-set name="section.title.properties">
  <xsl:attribute name="font-family">
    <xsl:value-of select="$title.font.family"/>
  </xsl:attribute>
  <xsl:attribute name="font-weight">bold</xsl:attribute>
  <!-- font size is calculated dynamically by section.heading template -->
  <xsl:attribute name="keep-with-next.within-column">always</xsl:attribute>
  <xsl:attribute name="text-align">left</xsl:attribute>
  <xsl:attribute name="space-before.minimum">0.8em</xsl:attribute>
  <xsl:attribute name="space-before.optimum">1.0em</xsl:attribute>
  <xsl:attribute name="space-before.maximum">1.2em</xsl:attribute>
</xsl:attribute-set>

It defines the font family using a parameter value, sets all headings to bold, and adds a keep-with-next property so there is no page break right after the title. This example also makes the titles left-aligned, so that if you have line justification turned on for your document you don't get large gaps when section titles are justified. Then it assigns several vertical spacing values, using the em unit so they scale relative to each title's font size.

Here is the default section.title.level2.properties attribute-set:

<xsl:attribute-set name="section.title.level2.properties">
  <xsl:attribute name="font-size">
    <xsl:value-of select="$body.font.master * 1.728"/>
    <xsl:text>pt</xsl:text>
  </xsl:attribute>
</xsl:attribute-set>

This attribute set has only the font size for this section level.

Changing section title sizes

As you can see from the above examples, one attribute-set defines all the shared properties for section titles. Then there are individual attribute-sets for each section level for properties specific to each level. Since font size is usually specific to each level, you need to customize the attribute-sets named like section.title.level1.properties. Here are two examples:

<xsl:attribute-set name="section.title.level1.properties">
  <xsl:attribute name="font-size">
    <xsl:value-of select="$body.font.master * 1.8"/>
    <xsl:text>pt</xsl:text>
  </xsl:attribute>
</xsl:attribute-set>

<xsl:attribute-set name="section.title.level2.properties">
  <xsl:attribute name="font-size">16pt</xsl:attribute>
</xsl:attribute-set>

The first example alters the calculation for computing the size of the level 1 headings relative to the body font size. The second example just sets a hard-coded font-size that does not change with the body size. You can use either method in your customization.

Generally the line-height property will adjust appropriately to the new font size to provide adequate vertical spacing of text lines. But you can also add your own line-height property in the attribute-set.

Changing section title styles

During processing, the stylesheet first applies the common attributes and then the level-specific attributes. So if you wanted your level 1 section titles to be italic instead of bold, and blue instead of black, you could add this to your customization layer:

<xsl:attribute-set name="section.title.level1.properties">
  <xsl:attribute name="font-weight">normal</xsl:attribute>
  <xsl:attribute name="font-style">italic</xsl:attribute>
  <xsl:attribute name="color">blue</xsl:attribute>
</xsl:attribute-set>

Since attribute-sets of the same name are merged, you don't need to repeat the font size value. In addition to setting the font-style to italic, you also need to set the font-weight to normal or you will get bold-italic because the bold font-weight will be inherited. This attribute-set does not affect the font-style or weight of the other section levels.

These attribute-sets let you add or modify many other style properties for section headings, such as text alignment, line height, color, background, or borders. See a good XSL-FO reference for full details.

Section rule lines

If your page design calls for drawing rule lines above or below section titles at some levels, you can accomplish that with the section title attribute-sets. That is because the attribute-set is applied to the fo:block containing the title, and such blocks can take border properties that you specify.

A horizontal rule line can be drawn using the border-top property to draw a line above, or the border-bottom property to draw a line below. The line will extend the length of the block. That is usually from where the title starts to the right margin. You may also want to use a padding property to add some space between the rule and the title text.

This example draws solid rule lines above and below the level 1 section titles:

<xsl:attribute-set name="section.title.level1.properties">
  <xsl:attribute name="border-top">0.5pt solid black</xsl:attribute>
  <xsl:attribute name="border-bottom">0.5pt solid black</xsl:attribute>
  <xsl:attribute name="padding-top">6pt</xsl:attribute>
  <xsl:attribute name="padding-bottom">3pt</xsl:attribute>
</xsl:attribute-set>

If you want to put your titles inside a box, then just use the border property, which will draw lines on all sides of the block.

Section page breaks

You can also use other attribute-sets to generate page breaks on a given section level. These are attributes that apply to the whole section, not just the title. For example, if you wanted to start each new section level 1 on a new page, you could add this to your customization layer:

<xsl:attribute-set name="section.level1.properties">
  <xsl:attribute name="break-before">page</xsl:attribute>
</xsl:attribute-set>

When the level 1 section (either a sect1 or equivalent section) is processed into an fo:block, this attribute value will force the block to a new page.

If you want your DocBook refentry elements to each start on a new page, that will be done automatically by the print stylesheet. The breaking behavior is controlled by a stylesheet parameter named refentry.pagebreak, whose default value is 1. If you don't want your refentry elements to force a page break, then set this parameter to zero.

Simplesects

A simplesect element is like a section element, but it cannot contain any other sections. For that reason, they always appear at the end of their container element, after any other sections.

By default, simplesects do not appear in the table of contents because they are usually not considered part of the document's structural hierarchy. But if you set the stylesheet parameter named simplesect.in.toc to a nonzero value, then all simplesects will be added to the table of contents.

Simplesect titles are normally formatted like the titles of section elements, whose format depends on the level of section nesting. Their formatting is controlled by the same mechanisms, as described in the section “Section titles”. If you want to differentiate simplesect titles, you can customize the template named simplesect.titlepage. That template normally would handle all aspects of the elements on a simplesect title page, but in most cases only the title is output. If you do create your own template of that name, you may need to add a priority attribute with a value greater than zero. That's because you need to override the template of the same name in titlepage.templates.xsl, which may be at the same import precedence as your new template.

Bridgeheads

A bridgehead element is considered a “free-floating heading”. Unlike section titles, bridgeheads are not part of the regular section hierarchy. They can be placed between block elements in the normal text flow, and they are not connected to their surrounding text. They can be used to indicate a change of subject in a text flow, or as simply a label for the text the follows.

By default, bridgeheads do not appear in the table of contents because they are usually not considered part of the document's structural hierarchy. But if you set the stylesheet parameter named bridgehead.in.toc to a nonzero value, then all bridgeheads will be added to the table of contents.

Bridgeheads are normally formatted like section titles. Since they are treated as being contained within a section, a bridgehead's format duplicates that of a section title one below the current section level. That is, if a bridgehead appears within a sect2 element (or an equivalent level section element), then the bridgehead formats like a sect3 title.

You can change the style of an individual bridgehead to match that of a different section level by adding a renderas attribute with a value of sect1, sect2, etc. The following example shows how it done in the document file:

<sect2>
  <title>Level 2 section<title>
  <para>Some interesting text.</para>
  <bridgehead renderas="sect4">New features</bridgehead>
  ...
</sect2>

In this example, the bridgehead element appears inside a sect2, and would normally be formatted like a sect3. But the renderas="sect4" attribute forces the style to match that of a sect4 element instead.

If you want to control bridgehead formatting beyond just the renderas attribute, then you will have to customize the bridgehead template. There are no bridgehead specifications in the titlepage.templates.xml spec file described in the section “Title page spec file”, because bridgeheads are not given real title pages. The template to copy to your customization layer is in fo/sections.xsl and starts with <xsl:template match="bridgehead">. Most of that template is used to determine the proper section level to imitate, and then it calls the template named section.heading. If you want to divorce bridgeheads completely from section titles, then don't call the section.heading template. Instead, call your own template, add your own attribute-set, or just add the formatting properties you want directly in the template.

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”.

You can choose to place formal titles above or below their element's content. See the section “Formal title placement” for a description of how to do that.

Formal title properties

You can adjust the font family, size, weight, and style, and the title vertical spacing using the formal.title.properties attribute set. The default list of attributes from fo/param.xsl looks like the following:

<xsl:attribute-set name="formal.title.properties" 
                   use-attribute-sets="normal.para.spacing">
  <xsl:attribute name="font-weight">bold</xsl:attribute>
  <xsl:attribute name="font-size">12pt</xsl:attribute>
  <xsl:attribute name="hyphenate">false</xsl:attribute>
  <xsl:attribute name="space-after.minimum">0.4em</xsl:attribute>
  <xsl:attribute name="space-after.optimum">0.6em</xsl:attribute>
  <xsl:attribute name="space-after.maximum">0.8em</xsl:attribute>
</xsl:attribute-set>

By default the font-family attribute is not included, which means the formal title font is inherited from the body font. You could change the formal titles to use, for example, 10pt Helvetica by adding the following to your customization layer:

<xsl:attribute-set name="formal.title.properties">
  <xsl:attribute name="font-size">10pt</xsl:attribute> 
  <xsl:attribute name="font-family">Helvetica</xsl:attribute>
</xsl:attribute-set>

Your new attributes will be merged with those in the default attribute-set.

All of the formally titled objects use the same properties because they all share this attribute-set. If you wanted different title properties for different formal elements, you would have to create a separate attribute-set in your customization and add some xsl:choose logic to a customized formal.object.heading template (the original is in fo/formal.xsl).

If you just want to change a single property for one formal element, you can add an xsl:choose logic to its attribute definition. For example, if you only want table titles to use Helvetica, you could do it this way:

<xsl:attribute-set name="formal.title.properties"> 
  <xsl:attribute name="font-family">
    <xsl:choose>
      <xsl:when test="self::table">Helvetica</xsl:when>
      <xsl:otherwise>inherit</xsl:otherwise>
    </xsl:choose>
  </xsl:attribute>
</xsl:attribute-set>

But sure to include the xsl:otherwise clause so you don't end up with an empty property in your XSL-FO output. In this case, the other formal elements will inherit the body font family.