Richard Hamilton | 22 Oct 18:48 2014

epub3 and named entities

It looks as though the next version of epubcheck may reject epub3 files that use named character entities
(&, etc.).

Right now, the stylesheets will generate at least some of these, even if you use the numeric equivalent
(e.g., if you use & for ampersand in your source, the output will be &).

Is there an option that will keep Saxon (which is what we currently use) from making this change? Or are there
options with other processors that might be a better choice?

Dick Hamilton
XML Press
XML for Technical Communicators
hamilton <at>
Olivier Ishacian | 21 Oct 19:41 2014

[ANN] Release of XMLmind XML Editor v6.1

XMLmind is happy to announce the version 6.1 of XMLmind XML Editor.

XMLmind XML Editor Evaluation Edition v6.1 can be downloaded from

Professional Edition users, please upgrade using this form:

(The above form is usually accessed through

XMLmind XML Editor v6.1 (October 20, 2014)

* Many enhancements making XMLmind XML Editor more powerful
   and more comfortable to use.

* Some important bug fixes.

* New documentation. See below.

More information:

XMLmind XML Editor - Support of XPath 1.0

(Continue reading)

Janice Manwiller | 16 Oct 13:44 2014

Trouble formatting PDF TOC entries

I'm trying to update the formatting of a PDF TOC. I mostly want to add additional space above and bold the chapter entries.

I found the following sample for in the DocBook XSL reference, and as a test added it to my FO stylesheet.

<xsl:attribute-set name=""> <xsl:attribute name="font-size">10pt</xsl:attribute> <xsl:attribute name="font-weight"> <xsl:when test="self::chapter | self::preface | self::appendix">bold</xsl:when> <xsl:otherwise>normal</xsl:otherwise> </xsl:attribute> </xsl:attribute-set>
According to the guide, this should make all entries 10pt and chapter entries bold.

However, when I try to generate the DocBook output using our maven docbkx tool, it doesn't generate at all, and I get an error indicating that a "when" element must always be enclosed by a "choose" element.

If I add the choose element, like:
<xsl:attribute-set name=""> <xsl:attribute name="font-size">10pt</xsl:attribute> <xsl:attribute name="font-weight"> <choose> <xsl:when test="self::chapter | self::preface | self::appendix">bold</xsl:when> <xsl:otherwise>normal</xsl:otherwise> </choose> </xsl:attribute> </xsl:attribute-set>
then the output generates, but there is no effect on the TOC formatting. The chapter entries aren't bold.

Any ideas on how to get this to work?


Thomas Schraitle | 16 Oct 10:56 2014

Tests Framework for DocBook Stylesheets & Customizations?


when developing customizations for the DocBook stylesheets I have
always the feeling I forget something important and work without any
"safey net". ;)
As such, it would be great to have a "test framework" which could
automatically check the transformation results with the expected

I know of XSpec from Jeni Tennison which goes in this direction.
However, as far as I know, this is for XSLT 2, not XSLT 1. It's used
for developing and testing the upcoming XSLT 2 DocBook stylesheets.

I'm not sure how easily could this be adapted to our current XSLT 1
base. Are there other (better?) solutions?

How do *you* develop and test your stylesheets? Has anybody used such
frameworks? Any help is greatly appreciated. :)


    Thomas Schraitle
Thomas Schraitle | 14 Oct 14:11 2014

Multiple Languages in one DocBook Document


ok, lets assume, we have an article. Its main language is in English.
Furthermore, our document needs some paragraphs in a different language.
The natural way would be to use the lang attribute like in the
following excerpt (DocBook 4.5):

 <article lang="en">
    <title>Language Test</title>
    <para lang="de">Dies ist ein deutscher Absatz.</para>
    <para lang="ar">هذه هي الفقرة العربية.</para>

Transforming* the above document into XSL-FO leads to the following
fo:block structures:

  <fo:block space-before.optimum="1em" space-before.minimum="0.8em"
        space-before.maximum="1.2em">Dies ist ein deutsches

  <fo:block space-before.optimum="1em" space-before.minimum="0.8em"
        space-before.maximum="1.2em"> هذه هي الفقرة العربية.</fo:block>

I would have expected to see a language attribute (and perhaps a
writing-mode as well). Unfortunately, it's not there. As such, in the
German and Arabic paragraph English hyphenation rules are applied. This
is obviously not correct. :)

I tried a sect1 element with a lang attribute with the same result.

Looking into the FO stylesheets, I identified some spots which I would
consider it as "fishy":

1. fo/param.xsl, parameter writing.mode
   Its default value is taken from the language file by using the
   gentext template. 
   However, the lang argument is set to "/*[1]" which is valid for a
   document with one main language. Unfortunately, this value does not
   help when using multiple languages.

2. fo/block.xsl, template match="para"
   The para template does not contain any code which would add the
   missing language or writing-mode attributes.

I tried it also with the latest snapshot release (28-Sep-2014 17:02,
r9945) but the results are the same.

Could someone confirm or extend my analysis? Does someone know what goes
wrong here? :)

* Used 1.78.1 of the DocBook XSL stylesheets
  libxml2: 2.9.1
  libxslt: 1.1.28


    Thomas Schraitle
Richard Hamilton | 2 Oct 02:22 2014

Bad DOCTYPE on toc.ncx in epub2 stylesheets snapshot

The subject line says nearly everything.

If I try to create an epub2 file using a recent snapshot (Sept. 28), toc.ncx gets written correctly, except
it has a DOCTYPE for an xhtml file:

  PUBLIC "-//W3C//DTD XHTML 1.1//EN" "">

There is a valid xmlns attribute on the root element, and if you remove the DOCTYPE lines completely, the
file is fine. In 1.78.1 this does not happen.

I poked around the stylesheets, but couldn't figure out what's going on, and I didn't see anything in the
revision history that seemed pertinent.

Has anyone run into the same thing?

Best regards,
Dick Hamilton
XML Press
XML for Technical Communicators
hamilton <at>
Richard Hamilton | 25 Sep 21:30 2014

Question on header.table template in fo stylesheets

I noticed something curious in the header.table template in pagesetup.xsl in the fo stylesheets.

The first thing this template does is set the margin-left (or margin-right for right-to-left languages)
attribute to 0pt. It doesn't change the other margin.

I noticed because I set the margin in header.content properties to a negative value to get an hanging header
(that is, I want part of the header, in this case the page number, in the outside margin). The hanging header
works everywhere except on the verso pages in the index because margin-left is reset for the index.

I'm guessing there is a good reason for this, but I'm not sure what it is.

Does anyone know why this is the case?

XML Press
XML for Technical Communicators
hamilton <at>
Andy Hatton | 22 Sep 16:59 2014

DocBook XSL 1.78.1 copyright status


I have been asked to investigate/verify the copyright status for the 
DocBook 1.78.1 stylesheets.

The distribution includes the COPYING file, which includes various 
copyright statements.

The copyrights run up to 2012, but 1.78.1 was released in 2013 (I 
think). The same statements are included in the current snapshot 

Is this just an oversight, or has the copyright situation changed after 



Andy Hatton
Janice Manwiller | 22 Sep 13:38 2014

Problems customizing WebHelp and HTML output

Still relatively new to DocBook.

In the doc set that I inherited, there are XSL files marked for FO (PDF), HTML, and WebHelp. Our doc build uses the Maven docbkx plugin to generate our documents.

I've been able use information from the DocBook XSL reference to make changes to the FO file and see the results in the PDF output. These changes include:

- Removing table and figure numbers
- Removing the lists of tables and figures
- Updating the cross-reference text to remove "the section called"

However, any changes I make in the HTML or WebHelp XSL files seem to be ignored. I've been able to update the CSS file to make changes to the look and feel of the output, but not any changes to the basic transformation.

For example, I added this chunk to the FO stylesheet to handle removing the table and figure numbers and updating the cross-reference text:

<!-- Eliminates the table and figure numbers. Also gets rid of "the section called" in cross-references -->
  <xsl:param name="local.l10n.xml" select="document('')"/>
    <l:l10n language="en">
      <l:context name="xref"> 
        <l:template name="appendix" text="%t"/> 
        <l:template name="chapter" text="%t"/> 
        <l:template name="section" text="%t"/> 
      <l:context name="title">
        <l:template name="table" text="%t"/>
      <l:context name="xref-number-and-title">
        <l:template name="table" text="&#8220;%t&#8221;"/>
      <l:context name="title">
        <l:template name="figure" text="%t"/>
      <l:context name="xref-number-and-title">
        <l:template name="figure" text="&#8220;%t&#8221;"/>

  <xsl:template match="table" mode="label.markup"/>
  <xsl:template match="figure" mode="label.markup"/> 
  <xsl:template match="appendix" mode="label.markup"/>
  <xsl:template match="chapter" mode="label.markup"/>
  <xsl:template match="section" mode="label.markup"/>

However, adding the same chunk to the WebHelp XSL file has no effect on the WebHelp output.

As another example, our HTML output still has section numbers. I added the following to the HTML stylesheet:

<xsl:param name="section.autolabel" select="0"/>

But that had no effect either - the section numbers were still there.

Am I missing something? Is there a difference in the transformation configuration for online output vs. PDF output?


Erik Rask | 22 Sep 12:13 2014

Olinking to section does not provide section number

When I use an olink to a chapter, I get the labelnumber element correctly represented. When I olink to a
section, I do not, and I get the message "Request for label of unexpected element: olink". I've tried
setting the xrefstyle with both "template:%n %t" and "select:labelnumber title" to no avail.

Is there a parameter I'm missing here, or is xsltproc not able to deduce labelnumber from section?

Erik Rask
Technical Communication Team Lead
Procera Networks
Frank Arensmeier | 18 Sep 09:14 2014

Simplified DocBook RelaxNG schema not valid?

Hi there!

For a project I am working on, I did a couple of tests with the Simplified DocBook schema. The definition I
downloaded was 5.1CR3. When I open that schema in Oxygen I see a couple of validation errors:

System ID: /Users/brillo/Downloads/sdocbook.rng
Description: multiple definitions of start without "combine" attribute
Start location: 290:11

System ID: /Users/brillo/Downloads/sdocbook.rng
Description: multiple definitions of start without "combine" attribute
Start location: 2390:11

System ID: /Users/brillo/Downloads/sdocbook.rng
Description: multiple definitions of start without "combine" attribute
Start location: 6644:11

System ID: /Users/brillo/Downloads/sdocbook.rng
Description: multiple definitions of "db.admonition.blocks" without "combine" attribute
Start location: 6736:40

System ID: /Users/brillo/Downloads/sdocbook.rng
Description: multiple definitions of "db.os.inlines" without "combine" attribute
Start location: 6826:33

System ID: /Users/brillo/Downloads/sdocbook.rng
Description: multiple definitions of "db.programming.inlines" without "combine" attribute
Start location: 6835:42

System ID: /Users/brillo/Downloads/sdocbook.rng
Description: multiple definitions of "db.markup.inlines" without "combine" attribute
Start location: 6853:37

Most of these errors seem to be caused by the fact that there are some duplicates of element definitions.
Removing those duplicates however does not make Oxygen happy. Instead, it says: found element matching
the prohibited path start//empty in the simplified XML form of the schema[…].

What is going on here? Can this be fixed? Shall I file a bug report somewhere? Do pigs fly?


Frank Arensmeier
farensmeier <at>