oXygen XML Editor

Docbook Title Pages

1. How to produce a titlepage in fo
2. Images on a titlepage
3. Layout driven title page
4. Using entities in titlepage templates
5. Bibliography titles
6. Chapter title layout


How to produce a titlepage in fo


If you look in the doc directory of the 1.48 stylesheet distribution, in the template directory, you should find a file called titlepage.html, which goes someway to explaining it all.

Based on that file and my own errors, this is what I do to produce a reasonable titlepage in my fo output.

Starting point. In the 1.48 distribution, in directory template (not doc/directory) you will find a file called testtemplate.xml. Use this a basis, not as a template!

Let's create an xml document called mytitlepage.xml, something like this.

Example 1. Titlepage, a starting point

<t:templates xmlns:t="http://nwalsh.com/docbook/xsl/template/1.0"
base-stylesheet="/sgml/nw/docbook/xsl148/fo/docbook.xsl">   (1)

<t:variable name="section.autonumber" select="true()"/>  (2)

<t:titlepage element="book" wrapper='fo:block' >         (3)
    <t:titlepage-content side='recto'>                   (4)
      <title predicate="[1]"/>
      <subtitle predicate="[1]"/>                        (5)

      <copyright/>                                       (6)


(1). The base stylesheet location is the path to the main stylesheet.

(2). Set this to true if you want sections numbering.

(3). I want this lot to appear as the front page of a book, rather than an article or other element. Since I'm aiming for an fo output, set the wrapper to fo:block, as apposed to a div for an html front page.

(4). In terms of content for this particular front page I want the content to be all the stuff within this wrapper. I also want this stuff to appear on the recto page... OK, the right hand page if you must. Were I true to form I would set this to 'verso', the opposite of recto. Note that I only want the first title element, and the first subtitle element, hence the use of the [1] predicate here.

if you want to also create a verso page, you add another <t:titlepage side="verso"> element that lists the elements you want on the back of the recto titlepage.

(6). author, contrib, edition, copyright, pubdate, revision? If you are familiar with docbook then these should strike you as being children of the bookinfo/articleinfo type of elements in docbook. Basically anything you can put in there, can go in here.

To put an image on a titlepage, you put a <mediaobject> element inside your <xxx info> element in your document. The <mediaobject> element specifies which graphic to use, and simply add it to the list, in the same way as other content is added.

Note that the order in which information is shown on the titlepage isn't necessarily the same as the order in which information is added within the xxxinfo section of your document. The order specified in mytitlepage.xml is the order in which stuff will be laid out.

So, thats the first job done. I've defined an XML document which specifies what I actually want on my front page. Now what?


The stylesheet distribution comes with a stylesheet called titlepage.xsl, again in the template directory. Use the file you created based on the above, and this stylesheet, to create another stylesheet which will create your front page. Follow that? Again. Use titlepage.xsl (from the templates directory), to process the xml file similar to the one above, and it will produce a file which you can then use to style your main document to produce the front page you need. For example.

saxon mytitlepage.xml -o /sgml/book/titlepage.xsl /sgml/docbook/templates/titlepage.xsl

This produces the output file /sgml/book/titlepage.xsl which is ready for use. So. Let's assume you have some customisation in a file called mydocbook.xsl, which calls up the main xsl docbook stylesheet. In that file you need to add the line which includes the titlepage processing (/sgml/book/titlepage.xsl in the example above). Something like.

<xsl:import href="/sgml/nw/docbook/xsl148/fo/docbook.xsl"/>

 <xsl:param name="stylesheet.result.type"  select="'fo'"/>


  <xsl:include href="/sgml/book/mytitlepage.xsl"/> 

So the processing sequence then applies your customisations, includes the titlepage processing and produces the needed output.


Images on a titlepage

Norm Walsh

| Is it possible to have an image on a book's titlepage in
| the xsl-fo stylesheets?
| If so, which element I have to use?

The right element is mediaobject with an imageobject inside it. But you'll also have to tinker with the titlepage setup

See my article


Layout driven title page

Bob Stayton

I think for a layout-driven title page where you know exactly what you want, you are better off abandoning the title page generator process. The stylesheet generator is useful when you just need to select the titlepage elements and their order. But getting it to generate a complex FO table is harder than simply writing the FO table as an XSL template as you have done.

So just create a file named something like mytitlepage.xsl containing what you want:

<xsl:stylesheet etc. >
<xsl:template name="book.titlepage.recto">
    <fo:table border-width="0.1pt" border-style="solid">
       <fo:table-column column-width="50mm"/>
       <fo:table-column column-width="50mm"/>
        <fo:table-column column-width="50mm"/>
         <fo:table-row >
         <fo:table-cell   border-width="0.1pt" border-style="solid">
            ORIGINATOR :
	  mode="book.titlepage.recto.auto.mode" select="b
         </fo:table-cell  >


And then add this line to your fo customization layer after you import the main fo stylesheet:

  <xsl:include href="mytitlepage.xsl"/>

Your template will simply override the default of the same name, and you don't have to do any maintenance when you upgrade the stylesheet release.

You may want further control over how particular elements are handled (for example, the default handling of corpauthor is to precede it with the word "by"). You could add a template like:

<xsl:template match="bookinfo/corpauthor" mode="book.titlepage.recto.mode">
    <xsl:text> </xsl:text>

And do that for any other element you need special handling for on the title page.


Using entities in titlepage templates

Jirka Kosek

> Up to now I could not find a way to use entities (&nbsp;, &szlig;, ...) 
> in the titlepage template system and still have to use the UTF-8 
> equivalents (&#160;, &#223;, ...) for these characters, which is not 
> very comfortable.

Yes, there is a way. Start your template by this code:

<?xml version="1.0"?>
<!DOCTYPE t:templates [
	"ISO 8879:1986//ENTITIES Numeric and Special Graphic//EN//XML"
... repeat above for all entity sets you want to use ...
<t:templates xmlns:t="http://nwalsh.com/docbook/xsl/template/1.0"


Bibliography titles

Bob Stayton

> I produce PDF documents with help of XEP and DocBook XSL/FO. One of my 
> documents contains the element hierarchy sect1/bibliography/title. The 
> resulting document contains always a huge headline for the title of the 
> bibliography. In fo/bibliography I found an empty template 
> bibliography/title which doesn't match the hierarchy above. How can I 
> control the font properties for this title element?

The stylesheets assume a bibliography is at the same level as chapter. As with most elements, the title is handled by the stylesheet titlepage mechanism. The specs for bibliography titles are in fo/titlepage.templates.xml. It shows that the <title> element of bibliography is handled by the 'component.title' template, which is used for chapters and such.

To change it, you should edit a copy of titlepage.templates.xml, generate your own titlepage.templates.xsl, and include that in your stylesheet customization. You could have the specs call a new template such as "bibliography.title" instead of component.title. That template could check to see if the parent element is something other than book, and if so apply smaller formatting properties. If the parent is book, then call component.title.

Don't try to just put something in the empty template with match="bibliography/title". That is empty because the title element is handled by the template for the bibliography element. That empty template prevents the title from being processed (and output) twice. This is a method commonly used in the stylesheets.

BTW, there is talk in the DocBook Technical Committee about adding a more lightweight bibliolist element for minor bibliographies within other elements. This is analogous to glosslist and glossary.


Chapter title layout

Bob Stayton

>  I'd like to figure out how to completely restructure chapter title
> layout.  More so than just removing the "Chapter 5:" the default "Chapter
> 5: My Chapter" as is stated in most guides.  I'd like to get really nice
> pretty chapter titles like you'd see in an O'Reilly book, ie:
> ----------------
> |      Chapter |
> |            5 |
> |     My Title |
> |     -------- |
> ~~~~~~~~~~~~~~~~

You should take a look at the template named 'component.title' in fo/component.xsl. The titlepage.templates.xml specification file specifies that this template should be used to process chapter and other component titles.

I would suggest you change titlepage.templates.xml to call a new template such as 'chapter.title' instead of component.title, and add the 'chapter.title' named template to your customization layer. It needs to generate three fo:blocks stacked one after another for 'Chapter', '5', and the title, and with the text-align="right" property set. You can add any other attributes you feel necessary to format the title as well. Inside each fo:block template, you call templates to generate the text for that block.

To generate the word 'Chapter', you want to call the template named 'gentext' with a parameter named 'key' whose value is the string 'chapter'. That will look up the generated text label in the right language.

<xsl:call-template name="gentext">
  <xsl:with-param name="key" select="'chapter'"/>

To generate the chapter number, use apply-templates with mode="label.mode"

<xsl:apply-templates select="." mode="label.markup"/>

To generate the chapter title, use:

<xsl:apply-templates select="." mode="title.markup"/>