Docbook Customisation

Jirka Kosek

docbook at Sourceforge is not enough for you? Parameters here are grouped together by their nature.

Mike Smith

The way you'd want to add your elements is through a "customization layer" to DocBook, not by making any direct changes to the DocBook DTD itself. For instructions on creating DocBook customization layers, you'll need to read chapter 5, "Customizing DocBook", of "DocBook: The Definitive Guide":

I think you'll be happy to find out that DocBook is designed to be customized. The DTD contains many parameter-entity hooks that are to there to make it easier for DTD implementors like you to make changes.

But before you do any customizing, I also recommend that you read at least Part III, "Development" of Eve Maler and Jeanne El Andaloussi's book "Developing SGML DTDs: From Text to Model to Markup", especially chapter 10, "Techniques for Reuse and Modification":

And so that you can post questions and get answers if you run into problems, you'll probably also want to subscribe to the docbook@lists.oasis-open.org mailing list:

Also, there a few free tools for looking at DTDs that I think will help you a lot when working with the DocBook DTD and assessing/ debugging your customizations:

Bob Stayton's LiveDTD creates hyperlinked HTML versions of DTDs http://www.sagehill.net/livedtd/index.html

Norm Walsh's DTDParse generates human-readable DTD documentation (hyperlinked HTML) http://dtdparse.sourceforge.net

Earl Hood's perlSGML generates human-readable DTD documentation (hyperlinked HTML) also contains dtddiff for generating diffs of two DTDs and dtdview for interactively navigating a DTD http://www.oac.uci.edu/indiv/ehood/perlSGML.html

Ian Graham's modified version of perlSGML includes dtd2html-table, which generates more readable DTD documentation than Earl Hood's original dtd2html http://www.java.utoronto.ca/DTDs/perlSGML.1996Aug20-Ian.tar.gz

One thing you need to remember is that if you add elements in a customization layer DTD and want to use the standard DocBook stylesheets to process documents authored with that DTD, you'll also need to create a stylesheet customization layer.

And maybe the very first thing you should do is make an assessment of whether any of the elements you want to add are just different names for elements that already exist in DocBook. (DocBook has more than 350 elements, so there's a pretty good chance that some of your elements have direct equivalents in DocBook). It's probably best to spend some time getting really familiar with DocBook before you decide to make any changes.

DaveP

From the top then. Assuming you have an installed set of docbook XSL stylesheets, which works.

From the command line, rather than calling up the main docbook stylesheets provided by Norm and friends, call up an intermediate xsl file, which in turn calls up the main stylesheet, docbook/xsl/html/docbook.html. This intermediate file is called a driver file. In order to understand how it works, you need to understand that by importing the docbook.xsl file, any templates that you add will take precedence over Norms templates. This way, you can override the main stylesheet templates, and hence your changes will affect the overall styling of your document.

Another option is to control how the main stylesheets do their job by setting some of the parameters available to you. This can be done two ways, firstly via the command line, as a parameter, or, for more permanent changes, you can define these parameters in your driver file. Again your definitions of the parameters value takes precedence over the main stylesheet default values.

A third reason for not changing the actual main stylesheets is that the group of enthusiasts who maintain them change them quite frequently, so using this driver file rather than modifying the actual stylesheets allows you to update the main stylesheets from Sourceforge and retain your own set of preferences. I became quite cross with Norm. I would 'tweak' the stylesheets, he would update them to add features I decided I wanted, and I had to start all over again. That was my motive for finding out how the customisation worked, I'm just lazy!

A simple example driver file is shown below, which simply changes two parameters, and then imports the main stylesheet.

The import statement must come first. The next line identifies that I have a CSS stylesheet that I want to use, and names it. The last line overrides the standard processing of revision history. That's all I wanted to do. So my command line when I style a docbook stylesheet calls up this file instead of the main docbook stylesheet.

Simple really, isn't it!

Jirka Kosek

See sourceforge

Norm Walsh

I added a line-height parameter today.

DaveP

There are a few... OK there are lots. These derive from the fact that people want lots of different things from the styling that docbook provides via the main stylesheets. The files in which they are found start at param.xweb (I'm referring to version 1.46 of the xslt stylesheets, for html). From that file, others are pulled in using entities, defined in param.ent (also in the same directory). These entities refer to a whole list of files in the params directory, where the detail is to be found. To make it easy, I've included an html version of the file (all entities included) which should be a little easier to follow. Since there is no need to modify any of these files, they are there primarily to let you know which parameters are available for modification. The readable version of this file is here as param.xweb.html. Take a quick look at it, and you will see the range of parameters that are available for personalising your presentation. This file is for the HTML output, a similar one is presented for the xsl-fo stylesheets. That would work in exactly the same way. If you are interested, the parameter changed above looks like this

The parameter is defined first, with a name of html.stylesheet, and a default value of an empty string. My driver file overrides this, using xslfo.css as the filename. The purpose and description of the parameter is also provided. The doc namespace is used for self documentation. This particular parameter is described here.

The parameters range from specifying how a titlepage should be styled, through to whether to use unicode characters or small graphics for callouts. This will be described seperately, at the moment just realise its quite an extensive list.

So, how to describe the parameters. Let's start with some gross generalisations.

Even with this skimpy outline, its clear to see that there is a fair scope for customisation. Read for yourselves in the linked toc at param.xweb.html.

The rest of this file answers specific questions that have come up on the list. I hope you have enough to give you an idea of where to start.

Bob Stayton

For example, when you use xref to refer to a figure, the generated text says “Figure 3”, but perhaps you would rather it say “Fig 3: My figure title”. The generated text is controlled by text templates defined in common/en.xml or other language file in that directory. But rather than modify those files, you can change individual text templates in your stylesheet driver file. Here is how it is done for this example:

<xsl:param name="local.l10n.xml" select="document('')"/>
<l:i18n xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0">
  <l:l10n language="en">
    <l:context name="xref">
      <l:template name="figure" text="Fig %n: %t"/>
    </l:context>
  </l:l10n>
</l:i18n>                                                                       

    You may need to provide similar changes for other contexts, 
such as "title-numbered",and others defined in the common/en.xml file. 
For example:

  <l:i18n xmlns:l=http://docbook.sourceforge.net/xmlns/l10n/1.0">
    <l:l10n language="en">
    <l:context name="title">
        <l:template name="chapter" text="%n. %t"/>
      </l:context>
      <l:context name="title-numbered">
        <l:template name="chapter" text="%n. %t"/>
      </l:context>
    </l:l10n>
  </l:i18n>

In the text templates, %n inserts the number and %t inserts the title. The l:context element indicates this is for generated xref text, and the l:template's name attribute identifies which target element it is applied to.

The special trick here is the select="document('') attribute. This special syntax reads the current document (the stylesheet file) into the local.l10n.xml parameter. When the stylesheet goes to generate text, the stylesheet first scans that parameter for a match before going to the standard language files.

By default, chapter titles are presented as “Chapter 3. My Chapter Title”, but perhaps you would rather print just the title. The generated text is controlled by text templates defined in common/en.xml or other language file in that directory. But rather than modify those files, you can change individual text templates in your stylesheet driver file. Here is how it is done for this example:

<xsl:param name="local.l10n.xml" select="document('')"/>
<l:i18n xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0">
  <l:l10n language="en">
    <l:context name="title">
      <l:template name="chapter" text="%t"/>
    </l:context>
  </l:l10n>
</l:i18n>                                                                       

The original text template was Chapter %n. %t. In the text templates, %n inserts the number and %t inserts the title. Replacing the original template with just %t generates just the title of the chapter.

By default, table titles and such are presented as “Table 3. My Table Title”. Changing this format involves changing a text template similar to that for chapter titles. See the answer for changing chapter titles.

Bob Stayton

There are two section table of contents parameters. The generate.section.toc.level parameter controls which section levels will have a toc list generated at the top of the section. In other words, "the section levels in which to generate a section toc listing". If it is set to "2", then you'll see a Table of Contents listing at the top of each sect1 and sect2 (and equivalent nested section elements). The default is set to "10", so essentially all sections will have their own TOC by default.

The toc.section.depth parameter, on the other hand, controls the depth of nested sections that are included in a given toc, counting from the top. For example, if it is set to "2", then the chapter-level TOC will list its sect1 and sect2 titles, and the sect1-level TOC will list its sect2 titles. If generate.section.toc.level is greater than toc.section.depth, then tocs of further depth show only one level, their own children sections. That is to prevent showing an empty toc.

DaveP

See param.xweb.html and the following items. Control is available over the following containers.

Apart from these aspects, there are two other parameters which are usable. Firstly, label.from.part, should chapters be re-numbered seperately within each part? Defaults to no. and section.label.includes.component.label. Should section labels be included in the component label? Defaults to no.

To set any one of them on, set the parameter to 1. To turn numbering off, set it to 0.

DaveP.

Messy this one. It would appear that this is one of the favourite areas for customisation, so the actual contents of a styled document without any customisation is minimal. This operates in a slightly different way to other parameters. Rather than setting a parameter in the driver file, a seperate step is needed prior to styling your document. In the xsl distribution, you will find a directory called template. In there is a file called testtemplate.xml, and a matching stylesheet called titlepage.xsl. Running this stylesheet against testtemplate.xml produces another stylesheet, which is actually used on your document to produce the titlepage.

Having modified the testtemplate.xml, run the stylesheet to create, say mytitlepage.xsl, this resultant file is included into the driver file with a line like

Then the main stylesheet includes this styling, which styles your document to produce the titlepage that you want. Let me re-cap.

Right. Lets look a little more closely at what controls it all, the file testtemplate.xml

Leave these unless you wish to modify the stylesheet used.

The t:titlepage element has three attributes:

element The name of the source document element for which these templates apply. In other words, to make a title page for the article element, set the element attribute to article. This attribute is required.

wrapper The entire title page can be wrapped with an element. This attribute identifies that element. Not used in the example above, could be fo:block for xsl-fo, or a simple div for an html output.

class If the class attribute is set, a class attribute with this value will be added to the wrapper element that surrounds the entire title page. This would be useful if additional html styling is done by a CSS stylesheet.

This apparent random collection of tags specifies the content of the recto side of the print page (OK not in html, but you get the idea). What it is saying is that for this article, include these elements in the titlepage. The indentation implies second level terms to be included, etc. So, simply list the elements that are in your document that you want included and a stylesheet will be generated which includes this.

A little detail here. Each element may have a single attribute: predicate. The value of this attribute is used as a predicate for the expression that matches the element on which it occurs. In other words, to put only the first three authors on the recto-side of a title page, you could specify:

This would be specified using

in the template file.

The remainder of this example provides other candidates. Note that the content must follow the docbook DTD (otherwise it wouldn't be much good would it). Other than that, try adding the elements you want, from your frontmatter. Good luck.

If you want to change which elements appears on your title page, see the question on changing the content of title pages. . This answer describes how to format the elements that are included.

By default, an element on a title page is styled using the templates defined in titlepage.xsl. Those templates use the generic titlepage.mode. For example, the default template for the pubdate element looks like this:

<xsl:template match="pubdate" mode="titlepage.mode">
  <p class="{name(.)}">
    <xsl:apply-templates mode="titlepage.mode"/>
  </p>
</xsl:template>

You can customize how an element is processed by defining a template for it using a more specific mode, such as book.titlepage.recto.mode. This particular mode is called when processing in the context of a book titlepage, for the front (recto) side of the title page. This is the one used for HTML since it doesn't have page sides.

For example, if you want to add boldface to a book's pubdate, you create a new template in your customization layer like this:

<xsl:template match="pubdate" mode="book.titlepage.recto.mode">
   <p class="{name(.)}">
     <B>
       <xsl:apply-templates mode="titlepage.mode"/>
     </B>
   </p>
</xsl:template>

You should pass along the titlepage.mode in the <xsl:apply-templates> tag because modes do not automatically pass down to children. If you want to customize child elements, then pass along the more specific book.titlepage.recto.mode instead so your custom templates are used. Any children that don't have that mode defined will fall back to the default titlepage.mode, so nothing will get lost.

If you are customizing for print output, then the recto part is significant. It refers to the front side of the title page, while verso refers to the back side of the page.

DaveP

Docbook XSL stylesheets provide two primary files. If you have a look in your distribution, in the html directory, you will find a number of files which appear to relate to chunking.

Just in case, a very quick aside. Chunking is the word which has become fairly common parlance for producing multiple output files from one stylesheet. For instance, in a large book, each chapter may be needed as a seperate file, to allow a reasonable download time. Norm describes possible chunks as:

So you have quite a choice as to where you want your chunks. As usual, you'll find the parameters to set to achieve this in the params section.

Note that this information is slightly premature, since it is based on 1.46 stylesheets which as of today are still experimental. (November 2001)

In alphabetical order, these are:

Confused? I can see why. I'm writing this with the 1.46 version in front of me. If you take a look at (or are using) 1.45, same directory, you'll find one addition, xtchunk.xsl. As of 1.46, Docbook support for xt has been removed, to allow use of all the features that are missing from XT.

So, if you want to chunk your output into multiple files, there are a couple of steps needed:

Create your driver file with these parameters set as above, and run that driver against your docbook file. Hey presto, you have your multiple output files.

DaveP

Docbook stylesheets can produce table of contents, lists of tables, and many more types of tables of content (toc's), and can produce them in great profusion. Some like 'em everywhere, some don't. You choose. As an approach I'd suggest you write a basic driver file, have a look at the output, and see if it suits your tastes. When yu see too many toc's, start to remove them!

There is a whole list of elements for which toc's can be generated. Look in param.xweb.html, and search for generate.X.toc, where X is the element you want a toc in. Set that parameter to 0 to stop a toc being generated, or 1 to to enable its creation.

To create toc's (or not) in some, but not all, sections, use generate.section.toc.level. If set to 2, then for sections up to and including depth of 2, a toc will be created. For deeper nested sections, no toc will be created. For recursive sections, a seperate parameter is used, toc.section.depth. This defaults to 2, and can be set to whatever matches your needs.

Finally, there are a whole host of ancilliary attributes which can be set for toc's. Examples of these are toc.list.type which determines what type of list is used (in html) for the toc. The default is a display list (DL). Another is the separator used between labels and titles in a toc. Use autotoc.label.separator.

Finally, a silly one (it must be, since I was caught out by it :-). Its fine setting the toc related parameters, its equally nice to be able to say where in your document you want them. Use the toc element in your document (empty element), where you want the toc to appear.

DaveP

Otherwise known as Automatic labelling. All the related parameters are prefixed autolabel.X

The following variations are catered for.

If label.from.part is non-zero, components (chapters, appendixes, etc.) will be numbered from 1 in each part. Otherwise, they will be numbered monotonically throughout each book.

So each of these can be turned on and off by setting any one of these parameters in your driver file.

A slightly different one, qanda.inherit.numeration - Does enumeration of QandASet components inherit the numeration of parent elements? If true (non-zero), numbered QandADiv elements and Questions and Answers inherit the numeration of the ancestors of the QandASet. So if you have a QandASet inside a chapter numbered 3, then the numbering of qanda entries will take up that numbering, commencing from 3.something, dependent on where they are relative to the chapter structure.

Norm Walsh

There's a switch in the stylesheets to select between K&R style and ANSI style function synopses. If you turn that switch to 'ansi', I think you'll get something closer to what you want.

Mike Smith

The way you'd want to add your elements is through a "customization layer" to DocBook, not by making any direct changes to the DocBook DTD itself. For instructions on creating DocBook customization layers, you'll need to read chapter 5, , of "DocBook: The Definitive Guide": "Customizing DocBook"

I think you'll be happy to find out that DocBook is designed to be customized. The DTD contains many parameter-entity hooks that are to there to make it easier for DTD implementors like you to make changes.

But before you do any customizing, I also recommend that you read at least Part III, "Development" of Eve Maler and Jeanne El Andaloussi's book "Developing SGML DTDs: From Text to Model to Markup", especially chapter 10, "Techniques for Reuse and Modification":

And so that you can post questions and get answers if you run into problems, you'll probably also want to subscribe to the docbook@lists.oasis-open.org mailing list:

Also, there a few free tools for looking at DTDs that I think will help you a lot when working with the DocBook DTD and assessing/ debugging your customizations:

One thing you need to remember is that if you add elements in a customization layer DTD and want to use the standard DocBook stylesheets to process documents authored with that DTD, you'll also need to create a stylesheet customization layer.

And maybe the very first thing you should do is make an assessment of whether any of the elements you want to add are just different names for elements that already exist in DocBook. (DocBook has more than 350 elements, so there's a pretty good chance that some of your elements have direct equivalents in DocBook). It's probably best to spend some time getting really familiar with DocBook before you decide to make any changes.

Jirka Kosek

There are two ways how to do it, which can be sufficent enough I think.

1. You can add otherterm attribute to glosssee with ID of referenced term. This will create link for you.

<glosssee 
otherterm="loop-infinite">Loop, Infinite</glosssee>

2. If you don't want deal with IDs for terms, you can surround term name inside of glosssee with glossterm:

If you call stylesheet with param glossterm.auto.link=1, links will be created from each <glossterm/> to place of its definition.

Bob Stayton

For the specifics on customizing the footer, see: styling If you follow that FAQ, you'll create a template named 'user.footer.content', which would look something like this:

<xsl:template name="user.footer.content">
  <div class="footer.date">
    <xsl:value-of select="//bookinfo/date" />
  </div>
</xsl:template>

Norm Walsh

Set the body.font.family parameter.

Bob Stayton

There is a glossary stylesheet global variable 'glossterm-width' that should probably be promoted to a parameter and added to the params list with documentation. Setting this in your stylesheet customization file will do the trick:

Bob Stayton

Yes, the title in the appendix itself can be altered with a text template customization because appendixes use the 'title-numbered' context in the templates. Put something like this in your customization file:

<xsl:param name="local.l10n.xml" select="document('')"/>
<l:i18n xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0">
  <l:l10n language="en">
    <l:context name="title-numbered">
      <l:template name="appendix" text="Appendix %n: %t"/>
    </l:context>
  </l:l10n>
</l:i18n>

This change only applies to the English version, of course. More entries for other languages.

This is harder. There is little opportunity to customize individual lines in the TOC. The toc lists are generated using the 'subtoc' template in autotoc.xsl. It is used recursively, to get nesting, but it doesn't vary per element type. These lines in subtoc show the problem:

  <xsl:element name="{$toc.listitem.type}">
    <xsl:variable name="label">
      <xsl:apply-templates select="." mode="label.markup"/>
    </xsl:variable>
    <xsl:copy-of select="$label"/>

The first line starts the <dt> element (in html output) and the rest output the appendix number (called a label in the stylesheets). If you want the word Appendix, then it has to be inserted between them. Something like this:

  <xsl:element name="{$toc.listitem.type}">
  <xsl:if test="local-name(.) = 'appendix'">
     <xsl:text>Appendix </xsl:text>
  </xsl:if>
    <xsl:variable name="label">
      <xsl:apply-templates select="." mode="label.markup"/>
    </xsl:variable>
    <xsl:copy-of select="$label"/>

Unfortunately, to get this in there you have to copy the entire subtoc template to your customization file.

If you plan to localize, you should replace the xsl:text element with a call to a gentext template to get the word "Appendix" in the correct language.

Jirka Kosek

You can control ToC creation by parameter generate.toc. To get rid off all ToCs, you can use something like:

<xsl:param name="generate.toc">
appendix  nop
article   nop
book      nop
chapter   nop
...
</xsl:param>

in your customization layer.

David Carlisle

In file fo/inline.xsl find the template

<xsl:template match="glossterm" name="glossterm">. 

Copy this template into your customization layer and change

to

<xsl:call-template name="inline.boldseq"/>.

Bob Stayton

I assume when you say "xml docbook" you mean the XSL stylesheets?

For XSL, if you are willing to forego all the options for controlling the QandA labels and just want to hardwire your style, then add these templates to your XSL customization layer:

<xsl:template match="question" mode="label.markup">
    <xsl:text>Q</xsl:text>
    <xsl:number level="any" count="qandaentry" format="1"/>
</xsl:template>

<xsl:template match="answer" mode="label.markup">
    <xsl:text>A</xsl:text>
</xsl:template>

The <xsl:number> with level="any" counts all instances of qandaentry elements in your document, and doesn't reset.

But if you localize your doc (so 'Q' and 'A' might not be appropriate), or want the option to change labeling for a given qandaset, then you should copy the whole template from common/labels.xsl:

<xsl:template match="question|answer" mode="label.markup">

to your customization layer and make similar changes.

Jeff Beal

Yes, add this template to your driver

<xsl:template match="processing-instruction('php')">
 <xsl:processing-instruction name="php">
  <xsl:value-of select="."/>
 </xsl:processing-instruction>
</xsl:template>

Bob Stayton

Actually, this isn't a bug, it is an expression of the behavior of XSLT import precedence that shows up when you use formalpara/para.

Here is what is going on. The stock <xsl:template match="para"> template wraps its content in <p> </p>, except when its unwrap process kicks in to avoid <p> tags where HTML doesn't like them.

But the block.xsl file also has a template <xsl:template match="formalpara/para">. This template does not output <p> </p> at all, because it knows the wrapper formalpara element's template has already done that, so that the title and para are inside the <p> </p>. Because this template's match pattern is more specific, it has a higher priority that the "para" template.

Now copy the "para" template to your customization layer and import docbook.xsl. The rules of import precedence state that the importing file's templates take precedence over the imported file's templates. In general, that's how customized templates override the stock ones.

But what isn't obvious is that import precedence is stronger than priority selection. So your custom "para" template is used inside formalpara. The "formalpara/para" template has higher priority inside the stock docbook stylesheet, but not in the importing stylesheet. So you end up with nested <p> elements, which is not legal HTML.

The solution is to add another template to your customization layer:

<xsl:template match="formalpara/para">
  <xsl:apply-imports/>
</xsl:template>

Now this template has higher priority than your custom "para" template in the importing stylesheet. Its effect is to use the imported stock "formalpara/para" template, which is what you want in order to avoid the extra <p> elements.

A quick scan of the stylesheets also shows a template in footnote.xsl: <xsl:template match=""footnote/para[1]|footnote/simpara[1]" priority="2"> To avoid problems with footnote paras, you should probably add an apply-imports template for this one too.

Bob Stayton

This will require customizing an XSL template. See the FAQ for how to create a customization layer. The template you are looking for is <xsl:template name="callout-bug"> in html/callout.xsl.

You need to change <xsl:text>(</xsl:text> to <xsl:text>[</xsl:text> (and the closing brace too).

Jeff Beal

If you're using Saxon or Xalan, Norm has provided an extension function for doing exactly what you want to do:

There are a few more extensions that control the appearance of linenumbering:

Bob Stayton

Actually, this isn't a bug, it is an expression of the behavior of XSLT import precedence that shows up when you use formalpara/para.

Here is what is going on. The stock <xsl:template match="para"> template wraps its content in <p> </p>, except when its unwrap process kicks in to avoid <p> tags where HTML doesn't like them.

But the block.xsl file also has a template <xsl:template match="formalpara/para">. This template does not output <p> </p> at all, because it knows the wrapper formalpara element's template has already done that, so that the title and para are inside the <p> </p>. Because this template's match pattern is more specific, it has a higher priority that the "para" template.

Now copy the "para" template to your customization layer and import docbook.xsl. The rules of import precedence state that the importing file's templates take precedence over the imported file's templates. In general, that's how customized templates override the stock ones.

But what isn't obvious is that import precedence is stronger than priority selection. So your custom "para" template is used inside formalpara. The "formalpara/para" template has higher priority inside the stock docbook stylesheet, but not in the importing stylesheet. So you end up with nested <p> elements, which is not legal HTML.

The solution is to add another template to your customization layer:

<xsl:template match="formalpara/para">
  <xsl:apply-imports/>
</xsl:template>

Now this template has higher priority than your custom "para" template in the importing stylesheet. Its effect is to use the imported stock "formalpara/para" template, which is what you want in order to avoid the extra <p> elements.

A quick scan of the stylesheets also shows a template in footnote.xsl: <xsl:template match=""footnote/para[1]|footnote/simpara[1]" priority="2"> To avoid problems with footnote paras, you should probably add an apply-imports template for this one too.

Bob Stayton

There is no 'separator' parameter for titles, but you can still customize the titles to remove the dot. The titles use the gentext templates in common/en.xml (for English) under the 'title-numbered' context. You'll see the sect1-5 'text' attributes include the dot and a non-breaking space character.

Bob Stayton

You are in luck. Since all your changes can be done with changes to existing parameter entities, you only have to declare them before they are declared in the calstblx module. That module is pulled in by the dbpoolx module. You can put your declarations right in your main customization driver file anywhere above where the dbpoolx module is pulled in.

If this is the only change you want, then your entire customization layer could consist of just this:

<!ENTITY % tbl.table-main.mdl "(tgroup+|imageobject+)">
<!ENTITY % tbl.entry.mdl "(para|%paracon;)*">

<!ENTITY % docbook PUBLIC
     "-//OASIS//DTD DocBook XML V4.2//EN"
     "docbookx.dtd">
%docbook;

Bob Stayton

If you are using the XSL stylesheets, you can add localization entries to your customization layer without touching the distribution files. See: sagehill.net

Entries like this define general text for each language file:

The key attribute is the identifier, and the text attribute is the printable text. To call the text from an XSL template, you use the gentext template with the key parameter specified:

This will return the value of the text attribute, which is 'Abstract' in this example.

Bob Stayton

That is one way to do it, but there's a reason that component.title.properties is not used by the stylesheets. That is because it has been replaced by the fo/titlepage.templates.xml specification file. The parameter should probably be removed from the distribution because people think it is doing something, but it isn't.

The problem was that the component.title template is used by a lot of elements including article, appendix, index, bibliography, glossary, colophon, dedication, and chapter. So change one, you change them all.

The specifications in titlepage.templates.xml let you set properties for each kind of title independently, which gives you much finer control. You have to regenerate the titlepage.templates.xsl stylesheet file when you change the spec file. This URL shows you how to do that (for HTML, but the process for FO is the same):

www.sagehill.net The "Print customization examples" chapter in that book has many other formatting options as well.

Bob Stayton

Setting the stylesheet parameter 'ignore.image.scaling' to 1 should work. You'll need stylesheet version 1.59.1 or later.

Rune Lausen

Neat!

If you are willing to rely on EXSLT support in the XSLT processor, you could do like I did in our XSL-FO customization layer. It works with Saxon and xsltproc. Don't know about Xalan.

Here is what I did:

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                 xmlns:fo="http://www.w3.org/1999/XSL/Format"
                 xmlns:xlink='http://www.w3.org/1999/xlink'
                 xmlns:date="http://exslt.org/dates-and-times"
                 exclude-result-prefixes="xlink"
                 version="1.0">

<!-- Note the xmlns:date="..." above -->

<!-- SNIP (Imports and other customizations) -->

<!--
      Template formatted for readability.
      May produce extra blanks.
      Add number formatting to ensure two digits in
      time fields.
  -->
   <xsl:template match="pubdate[@role='now']" mode="titlepage.mode">
     <xsl:variable name="now" select="date:date-time()"/>
     <fo:block>
       <xsl:text>Generated at </xsl:text>
       <xsl:value-of select="date:day-in-month($now)"/>
       <xsl:text> </xsl:text>
       <xsl:value-of select="date:month-name($now)"/>
       <xsl:text> </xsl:text>
       <xsl:value-of select="date:year($now)"/>
       <xsl:text> </xsl:text>
       <xsl:value-of select="date:hour-in-day($now)"/>
       <xsl:text>:</xsl:text>
       <xsl:value-of select="date:minute-in-hour($now)"/>
       <xsl:text>:</xsl:text>
       <xsl:value-of select="date:second-in-minute($now)"/>
     </fo:block>
   </xsl:template>

<!-- ETC -->

</xsl:stylesheet>

Document:

<!DOCTYPE book PUBLIC "..." "...">

<book lang="en">
   <bookinfo>
     <title>Blah blah/title>
     <pubdate role="now"/>
     <!-- ETC -->
   </bookinfo>

<!-- ETC -->
</book>

Bob Stayton

In general, if you want to add a top level element to a titlepage, you add it in the titlepage.templates.xml specification file and generate a new titlepage.templates.xsl.

But in this case, authorgroup is already in the spec file, but you want to change what it does with its children. So it can be done by customizing existing templates.

The template you want to customize is in html/titlepage.xsl:

<xsl:template match="author" mode="titlepage.mode">
  <div class="{name(.)}">
    <h3 class="{name(.)}"><xsl:call-template name="person.name"/></h3>
    <xsl:apply-templates mode="titlepage.mode" select="./contrib"/>
    <xsl:apply-templates mode="titlepage.mode" select="./affiliation"/>
  </div>
</xsl:template>

As you can see, it is processing the name, contrib, and affiliation elements. If your email element was inside the affiliation, it would automatically appear. Otherwise, you need to add a line to this template in your customization layer:

<xsl:template match="author" mode="titlepage.mode">
  <div class="{name(.)}">
    <h3 class="{name(.)}"><xsl:call-template name="person.name"/></h3>
    <xsl:apply-templates mode="titlepage.mode" select="./contrib"/>
    <xsl:apply-templates mode="titlepage.mode" select="./affiliation"/>
    <xsl:apply-templates mode="titlepage.mode" select="./email"/>
  </div>
</xsl:template>

This template is discussed in my book in the section "Modify individual element templates" in sagehill

Bob Stayton

To customize the footers in print output, you customize the template named 'footer.content'. The original template is in fo/pagesetup.xsl. It lets you set context conditions for each of pageclass, sequence, and position.

See this reference for further explanation and an example: sagehill

Bob Stayton

The default setting for draft.mode is "maybe". That means the draft watermark is output only for pages that have a status="draft" attribute. I think this was intended as a convenience for those who want to turn on the watermark with an attribute and without having to set a parameter.

When set to "maybe", the stylesheet does not check to see if there are any instances of status="draft" in the document, it just prepares the FO page-master set so the draft page-masters are available in case they are needed.

The reason draft.png is a URL and not a local file path is because the stylesheet cannot manage local files. The stylesheet can only write a path to the FO file, and it is up to the FO processor to locate the draft.png file to integrate it into the PDF. The stylesheet could write a path relative to the stylesheet location, but the FO processor doesn't know the path to the stylesheet directories.

The use of a URL is a compromise, and can be a headache for unsuspecting users. Perhaps the default behavior of the stylesheet should be to check to see if the document has a status="draft" attribute anywhere before outputting the draft page-masters. Then you would run into the URL problem only if you are actually trying to use draft mode.

Bob Stayton

I assume you are talking about an XSL customization? If so, then it depends on whether you are chunking or not.

For nonchunked output, you want to customize the 'process.root' template in html/docbook.xsl.

For chunked output, you want to customize the 'chunk-element-content' template in html/chunk-common.xsl.

In both cases, you want to eliminate the <html> and <body> tags, as well as the calls to the header and footer templates. There won't be much left. For example, process.root would go from this original template:

<xsl:template match="*" mode="process.root">
  <xsl:variable name="doc" select="self::*"/>

  <xsl:call-template name="root.messages"/>

  <html>
    <head>
      <xsl:call-template name="system.head.content">
        <xsl:with-param name="node" select="$doc"/>
      </xsl:call-template>
      <xsl:call-template name="head.content">
        <xsl:with-param name="node" select="$doc"/>
      </xsl:call-template>
      <xsl:call-template name="user.head.content">
        <xsl:with-param name="node" select="$doc"/>
      </xsl:call-template>
    </head>
    <body>
      <xsl:call-template name="body.attributes"/>
      <xsl:call-template name="user.header.content">
        <xsl:with-param name="node" select="$doc"/>
      </xsl:call-template>
      <xsl:apply-templates select="."/>
      <xsl:call-template name="user.footer.content">
        <xsl:with-param name="node" select="$doc"/>
      </xsl:call-template>
    </body>
  </html>
</xsl:template>

To just this:

<xsl:template match="*" mode="process.root">
  <xsl:call-template name="root.messages"/>

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

</xsl:template>

Charles Plessy

I am using DocBook XML/XSL to write my biology thesis, and I use formalparas in captions for the figure legends. To make them clearly distiguishable from the text, I have set their font to sans-serif, however it looks bigger than the original one.

I modify my customisation layer to reduce the size.

 <xsl:param name="toto">
   <xsl:value-of select="$body.font.master * 0.8"/>
   <xsl:text>pt</xsl:text>
 </xsl:param>
 
 <!-- toto is the french foo -->
 
 <xsl:template match="formalpara/para">
   <fo:block font-family="sans-serif" font-size="{$toto}">
     <xsl:apply-templates/>
   </fo:block>
 </xsl:template>
 
 <!-- changes the font family and size -->

Bob Stayton

There is no stylesheet parameter to shade the background of note elements in FO output. But it can be done with attribute-sets in a customization layer:

<xsl:attribute-set name="admonition.properties">
  <xsl:attribute name="background-color">#E0E0E0</xsl:attribute>
  <xsl:attribute name="padding">0.1in</xsl:attribute>
</xsl:attribute-set>

<xsl:attribute-set name="admonition.title.properties">
  <xsl:attribute name="background-color">#E0E0E0</xsl:attribute>
  <xsl:attribute name="padding">0.1in</xsl:attribute>
</xsl:attribute-set>

Bob Stayton

Yes, you would need a new set of page masters to switch from 1-column to 2-column from chapter to chapter. See the page masters for index in fo/pagesetup.xsl for examples of 2-column layout. You can add your new pagemasters in the placeholder template named 'user.pagemasters'. Then you will need to customize the 'select.user.pagemaster' template to choose the right pagemaster.

Jirka Kosek

Add following into your customization layer:

<xsl:attribute-set name="verbatim.properties">
   <xsl:attribute name="font-size">8pt</xsl:attribute>
</xsl:attribute-set>

You can add as many FO properties as you want into the attribute set mentioned above.

Bob Stayton adds

Actually, if you want a line-height of 1.5 for everything *except* programlisting, then you can put this attribute in the root.properties attribute-set in your customization:

<xsl:attribute name="line-height">1.5</xsl:attribute>

and then put this one in the verbatim.properties attribute-set:

<xsl:attribute name="line-height">1</xsl:attribute>

Any properties in the root.properties attribute-set are inherited by all blocks in the document, unless they are overridden with a different value.

Bob Stayton

To turn off the display of the page number in the preface, you need to customize the footer.content template to add a xsl:when clause for preface. See this doc for examples: sagehill.net

It's possible to change the page numbering sequences, but currently you would have to customize both the chapter and preface templates. You need to change the initial-page-number property to be "1" in preface, and to be "auto-odd" in chapter, including the first chapter. If you are doing single-sided output, then it should be "auto" instead.

In the next release of the XSL stylesheets (real soon), a new template generates the value of the initial-page-number property for page-sequences. It will be a lot easier to customize the numbering sequences then.

Bob Stayton

The titles for index and index divisions can be customized using the titlepage.templates.xml mechanism. You should be able to add a color property and rebuild the XSL templates for title pages. See this reference for more information: sagehill.net

It describes the process for HTML titlepages, but the general method applies to FO titlepages, which are further described in: sagehill.net

Bob Stayton

First, change the 'formal.title.placement' parameter for figure as described in: http://www.sagehill.net/docbookxsl/FormalTitles.html#FormalTitleLocation

To put the caption below the title, though, you need to customize the match="mediabobject" template and the name="formal.object.heading" template. That's because the mediaobject template currently handles the caption, since caption is part of its content. Since figure is a wrapper around mediaobject, you have to tell mediaobject to not output the caption so that formal.object.heading can place it after the title. That means changing the caption line in the mediaobject template:

  <xsl:if test="not(parent::figure)">
    <xsl:apply-templates select="caption"/>
  </xsl:if>

At the end of the template named 'formal.object.heading', add:

  <!-- Add mediaobject caption below title -->
  <xsl:if test="self::figure/mediaobject/caption">
    <xsl:apply-templates select="mediaobject/caption"/>
  </xsl:if>

And then add a template to handle caption:

<xsl:template match="caption">
  <fo:block keep-with-previous.within-column="always">
    <xsl:apply-templates/>
  </fo:block>
</xsl:template>

Of course, if you are using FOP the keep won't work ... If you want this repositioning to also apply to tables, examples, etc, then don't make it dependent on figure as I have done here.

Bob Stayton

There is no stylesheet parameter that converts footnotes to endnotes, but it can be done with a customization. Take a look at the template with match="footnote" in fo/footnote.xsl, for example. You can customize that to generate endnotes.

First copy the template to your customization layer and remove the fo:footnote elements, because they generate bottom-of-page footnotes. Leave just the part that generates the footnote number, inside an fo:inline:

  <xsl:template match="footnote">
        <fo:inline>
          <xsl:call-template name="format.footnote.mark">
            <xsl:with-param name="mark">
              <xsl:apply-templates select="." mode="footnote.number"/>
            </xsl:with-param>
          </xsl:call-template>
        </fo:inline>
  </xsl:template>

The copy the same template to your customization layer and add mode="endnote". Edit this version to format the number and block of text inside an fo:block:

  <xsl:template match="footnote" mode="endnote">
        <fo:block font-family="{$body.fontset}"
                          font-size="{$footnote.font.size}"
                          font-weight="normal"
                          font-style="normal"
                          text-align="{$alignment}"
                          margin-left="0pc">
          <xsl:call-template name="format.footnote.mark">
            <xsl:with-param name="mark">
              <xsl:apply-templates select="." mode="footnote.number"/>
            </xsl:with-param>
          </xsl:call-template>
          <xsl:text> </xsl:text>
          <xsl:apply-templates/>
        </fo:block>
  </xsl:template>

Then you can generate the list of end notes by having a template like this:

<xsl:template name="make.endnotes">
    <xsl:apply-templates select="//footnote" mode="endnote"/>
</xsl:template>

The only remaining item is figuring out how to call this template at the appropriate place. I don't know how you want to present your end notes in PDF output. Perhaps in an appendix, or some other container. Or use a processing instruction that triggers a template that generates its own page-sequence for the endnotes.

You may also want to make the footnote number a hotlink, or maybe make them go both ways, by generating different ids for each end, and using fo:basic-link around the footnote numbers.