Docbook Title Pages

DaveP

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.

Notes:

(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?

Processing.

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.

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.

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

Norm Walsh

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

See my article

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:block>
    <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-body>
         <fo:table-row >
         <fo:table-cell   border-width="0.1pt" border-style="solid">
          <fo:block>
            ORIGINATOR :
            <xsl:apply-templates 
	  mode="book.titlepage.recto.auto.mode" select="b
ookinfo/corpauthor"/> 
          </fo:block>
         </fo:table-cell  >
 [etc.]

</xsl:template>
</xsl:stylesheet>

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">
  <fo:block>
    <xsl:text> </xsl:text>
    <xsl:apply-templates/>
  </fo:block>
</xsl:template>

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

David Cramer

I use the following technique to get full page covers when I couldn't figure out how to make the titlepage templates do it. If there's a cleaner way, I'd like to hear about it. In any case, you really need a new pagemaster and a background image. If you use a fo:block, then the image can never be 100% of the page.

Just to make sure it's clear, this does not use the titlepage template system to generate text that appears on the cover, though it could be made to do that. As shown, you get a cover with full page sized image, followed by the recto and verso titlepages as defined in your titlepage templates. To alter the placement of text on the cover, you edit the cover xsl directly. The full page cover technique works fine, but if you need to support multiple page sizes, you'd might need to add some intelligence to the xsl.

<!DOCTYPE xsl:stylesheet>

<!-- This customization of the docbook xsls -->
<!-- (http://docbook.sourceforge.net/) adds a full page -->
<!-- cover to a pdf using an image as a background image. -->
<!-- eps images work best for this kind of thing and will -->
<!-- fill the entire page. If you are using xep, you can use a bitmap -->
<!-- and an xep extension scales it to the right -->
<!-- size. The extension is only used if xep.extensions is -->
<!-- set to 1.  -->

<!-- To use this, just change the xsl:import to point to a -->
<!-- local version of the docbook xsls and put in a valid -->
<!-- value for the cover.path parameter (or pass it in from -->
<!-- the command line.  -->

<!-- I have only tested this with XEP. If it works with -->
<!-- other renderers or if it works, but only with some -->
<!-- changes, let me know: dcramer@broadjump.com -->

<!-- This can and probably be made to work with the -->
<!-- titlepage template system, so that you let the template -->
<!-- system control the text that appears on the -->
<!-- cover. Likewise, you can adapt it to give you full page -->
<!-- cover images on part titlepages. -->

<xsl:stylesheet 
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  xmlns:fo="http://www.w3.org/1999/XSL/Format"
  xmlns:rx="http://www.renderx.com/XSL/Extensions"
  version='1.0'>

<!-- Adjust this to point to your docbook distribution. I've -->
<!-- tested it with 1.55.0, but it probably works with other -->
<!-- versions. -->
<xsl:import href="../../../../DocBookXSL/1.55.0/fo/docbook.xsl"/>

<!-- This is stuff I needed to have for my environment. Delete or -->
<!-- change as you wish.  -->
<xsl:param name="draft.watermark.image" select="'../common/draft.png'"/>
<xsl:param name='admon.graphics.path' select="'../common/'"/>
<xsl:param name="callout.graphics.path" select="'../common/'"/>
<!-- End of stuff I needed to have for my env.  -->

<!-- Define the path to your cover here. You might also so -->
<!-- something like:
  <xsl:param name="cover.path"><xsl:value-of 
  select="normalize-space(//bookinfo//imagedata/@fileref)"/></xsl:param>
  Assuming that you've got an image defined in your bookinfo.
 -->
<xsl:param name="cover.path">../common/AE.cover.eps</xsl:param>
<xsl:param name="xep.extensions" select="1"/>

  <xsl:template name="user.pagemasters">

	<fo:simple-page-master
	  margin-right="0in" 
	  margin-left="0in" 
	  margin-bottom="0in" 
	  margin-top="0in"
	  page-height="{$page.height}" 
	  page-width="{$page.width}" 
	  master-name="cover">

	  <fo:region-body
		margin-bottom="0in"
		margin-top="0in"
		margin-left="0in"
		margin-right="0in"
		background-repeat="no-repeat"
		background-image="{$cover.path}">
		<!-- This _should_ work :) If the filename of the
		cover doesn't end in eps and you're using XEP, then
		use XEP's extensions to side the cover image to 8.5
		x 11.  -->
		<xsl:if 
		  test="not(substring(translate($cover.path, 
		  'ABCDEFGHIJKLMNOPQRSTUVWXYZ',
		  'abcdefghijklmnopqrstuvwxyz'),
		  (string-length(normalize-space($cover.path)) - 2), 3) = 'eps') and
		  $xep.extensions != '0'">
		  <xsl:attribute name="rx:background-content-width">
			<xsl:value-of select="$page.width"/>
		  </xsl:attribute>
		  <xsl:attribute name="rx:background-content-height">
			<xsl:value-of select="$page.height"/>
		  </xsl:attribute>
		</xsl:if>
	  </fo:region-body>
	  <fo:region-before 
		extent="0pt"
		display-align="after"
		region-name="xsl-region-before-first"/>
	  <fo:region-after 
		extent="0pt"
		display-align="after"
		region-name="xsl-region-after-first"/>
	</fo:simple-page-master>

	<fo:page-sequence-master master-name="coversequence">
	  <fo:repeatable-page-master-alternatives>
		<fo:conditional-page-master-reference 
			master-reference="cover" page-position="first"/>
		  <fo:conditional-page-master-reference 
		  	master-reference="blank" blank-or-not-blank="blank"/>
	  </fo:repeatable-page-master-alternatives>
	</fo:page-sequence-master>

  </xsl:template>

<!-- This overrides a template in fo/docbook.xsl  -->
<xsl:template match="/">
  <xsl:message>
    <xsl:text>Making </xsl:text>
    <xsl:value-of select="$page.orientation"/>
    <xsl:text> pages on </xsl:text>
    <xsl:value-of select="$paper.type"/>
    <xsl:text> paper (</xsl:text>
    <xsl:value-of select="$page.width"/>
    <xsl:text>x</xsl:text>
    <xsl:value-of select="$page.height"/>
    <xsl:text>)</xsl:text>
  </xsl:message>

  <xsl:variable name="document.element" select="*[1]"/>
  <xsl:variable name="title">
    <xsl:choose>
      <xsl:when test="$document.element/title[1]">
        <xsl:value-of select="$document.element/title[1]"/>
      </xsl:when>
      <xsl:otherwise>[could not find document title]</xsl:otherwise>
    </xsl:choose>
  </xsl:variable>

  <fo:root font-family="{$body.font.family}"
           font-size="{$body.font.size}"
           text-align="{$alignment}">
    <xsl:if test="$xep.extensions != 0">
      <xsl:call-template name="xep-document-information"/>
    </xsl:if>
    <xsl:call-template name="setup.pagemasters"/>
    <xsl:choose>
      <xsl:when test="$rootid != ''">
        <xsl:choose>
          <xsl:when test="count(id($rootid)) = 0">
            <xsl:message terminate="yes">
              <xsl:text>ID '</xsl:text>
              <xsl:value-of select="$rootid"/>
              <xsl:text>' not found in document.</xsl:text>
            </xsl:message>
          </xsl:when>
          <xsl:otherwise>
            <xsl:if test="$fop.extensions != 0">
              <xsl:apply-templates select="id($rootid)" mode="outline"/>
            </xsl:if>
            <xsl:if test="$xep.extensions != 0">
              <rx:outline xmlns:rx="http://www.renderx.com/XSL/Extensions">
                <xsl:apply-templates select="id($rootid)" mode="xep.outline"/>
              </rx:outline>
            </xsl:if>
            <xsl:apply-templates select="id($rootid)"/>
          </xsl:otherwise>
        </xsl:choose>
      </xsl:when>
      <xsl:otherwise>
        <xsl:if test="$fop.extensions != 0">
          <xsl:apply-templates mode="outline"/>
        </xsl:if>
        <xsl:if test="$xep.extensions != 0">
          <rx:outline xmlns:rx="http://www.renderx.com/XSL/Extensions">
            <xsl:apply-templates mode="xep.outline"/>
          </rx:outline>
        </xsl:if>


		  <fo:page-sequence master-reference="coversequence">
			<!-- Use no-force to prevent a blank page after the
			cover. -->
			<xsl:attribute
			  name="force-page-count">even</xsl:attribute>
			<fo:flow flow-name="xsl-region-body">
			  
			  <!-- Put whatever fo you want here. Note that if
			  you don't put at least _something_ on the
			  cover, the page isn't generated. So if you
			  have a cover graphic that already has the
			  title on it, you need to put some kind of
			  invisible character here, like a . that's 1pt.
			  The markup below just puts the doc title there.-->
				<fo:block
				  margin-top="3in"
				  margin-left="{$page.margin.inner}"
				  margin-right="{$page.margin.outer}"
				  text-align="center" 
				  color="black" 
				  font-weight="bold"
				  font-family="{$title.font.family}" 
				  font-size="30pt">
				  <xsl:value-of select="$title"/>
			  </fo:block>
 
			</fo:flow>
		  </fo:page-sequence>
		  
		  
		  <xsl:apply-templates/>
		</xsl:otherwise>
	  </xsl:choose>
	  
	</fo:root>
  </xsl:template>


</xsl:stylesheet>

Jirka Kosek

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

<?xml version="1.0"?>
<!DOCTYPE t:templates [
<!ENTITY % ISOnum PUBLIC
	"ISO 8879:1986//ENTITIES Numeric and Special Graphic//EN//XML"
	"path/to/ent/iso-num.ent">
%ISOnum;
... repeat above for all entity sets you want to use ...
]>
<t:templates xmlns:t="http://nwalsh.com/docbook/xsl/template/1.0"
	     xmlns:param="http://nwalsh.com/docbook/xsl/template/1.0/param"
              xmlns:fo="http://www.w3.org/1999/XSL/Format"
              xmlns:xsl="http://www.w3.org/1999/XSL/Transform">

Bob Stayton

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.

Bob Stayton

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'"/>
</xsl:call-template>

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"/>