The font families and sizes used for most titles are defined as part of the titlepage setup. See Chapter 11, 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 do not 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.
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
do not 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 will not 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 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.
The following 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. The following example formats the label and title on separate lines with different attribute-sets:
<xsl:template name="chapappendix.title"> <xsl:param name="node" select="."/> <fo:block 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.
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 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.level
attribute-sets, where X
.title.properties
is the section level (1 to 6) that the properties are
applied to.X
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 do not 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.
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.
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 do not 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.
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.
The following 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.
Run-in titles. A run-in title is one that appears as the first part of a paragraph, like this paragraph. A formalpara
element is formatted like this in DocBook. You might want to use this for section titles below a certain level, such as for sect3
.
This effect can be accomplished for section titles using a customization. You have to put the title and first paragraph inside a single fo:block
to prevent a line break after the title. It is a bit more complicated than for formalpara
, because a section can start with many elements that are not para
. For sections that do not start with a para
, a run-in title should be avoided, and instead the title should be stacked above the first element in the section.
<xsl:template name="sect3.titlepage"> <fo:block xsl:use-attribute-sets="normal.para.spacing"> <xsl:apply-templates select="title" mode="inline.title"/> <xsl:if test="para[preceding-sibling::*[1][self::title]]"> <xsl:text>: </xsl:text> <xsl:apply-templates select="para[preceding-sibling::*[1][self::title]]" mode="inline.para"/> </xsl:if> </fo:block> </xsl:template> <xsl:template match="sect3/title" mode="inline.title"> <fo:inline xsl:use-attribute-sets="inline.sect3.title.properties"> <xsl:apply-templates/> </fo:inline> </xsl:template> <xsl:attribute-set name="inline.sect3.title.properties"> <xsl:attribute name="font-weight">bold</xsl:attribute> </xsl:attribute-set> <xsl:template match="sect3/para[preceding-sibling::*[1][self::title]]" mode="inline.para"> <xsl:apply-templates/> </xsl:template> <xsl:template match="sect3/para[preceding-sibling::*[1][self::title]]"> </xsl:template>
Replace the original template named | |
Start a block to contain the run-in title and paragraph, and use this standard attribute-set or create a custom one. | |
Select and process the section title in a new mode that does not generate its own block. | |
Test that a | |
Add a colon and space to separate the title from the paragraph text. | |
Select and process the para after the title in a new mode that prevents it from starting its own | |
Process the title in its new mode as an | |
Define whatever inline formatting properties you want for the title. | |
Process the | |
Turn off normal mode processing of this |
You can use attribute-sets to generate page breaks on a given section level. These are attribute-sets 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 do not want your
refentry
elements to force a page
break, then set this parameter to zero.
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.
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 do not 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.
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.
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
). See the section “Formal title customization” for an example.
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 do not end up with an empty property in your XSL-FO output. In this case, the other formal elements will inherit the body font family.
DocBook XSL: The Complete Guide - 4th Edition | PDF version available | Copyright © 2002-2007 Sagehill Enterprises |