DocBook V5.0

Question

1.1.

How do I attach a schema to a DocBook V5.0 document when I do not want to use DTDs and !DOCTYPE?

Answer 1

There is no standard way of associating a RELAX NG schema with a document. Most tools provide some mechanism for performing this association, consult the documentation for your application. In some tools you must specify schema manually each time your want to edit/process your document.

Answer 2

Modern schema languages (including RELAX NG and W3X XML Schema) do not provide any means to define entities that can be used for easier typing of special characters. Some editors provide functions or special toolbars that allow you to easily pick necessary character and insert it into document as a raw Unicode character or a numeric character reference.

Another possibility is to include entity definitions in the prolog of your document. Entity definition files are now maintained by W3C. You can reference definition files with entity definitions you are interested in and then reference imported entities. For example:

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE article [
<!ENTITY % isopub SYSTEM "http://www.w3.org/2003/entities/iso8879/isopub.ent">
%isopub;
]>
<article xmlns="http://docbook.org/ns/docbook" version="5.0">
<title>DocBook V5.0 &ndash; the superb documentation format</title>
…

Answer 3

You can use XInclude for this task. There are available alternative schemas for DocBook V5.0 that contain XInclude elements. This is necessary to make some XML editors happy. Name of these schemas ends with letters “xi”, e.g. docbookxi.rnc instead of docbook.rnc.

Answer 4

Yes, the current stylesheets (like 1.69.1) will be supported and improved further because they are very widely deployed and work with many existing XSLT processors.

Surely there will be point in a future when all new development will be switched to XSLT 2.0 based implementation only. But this will not happen before all features of the current stylesheets are implemented in the new stylesheets and before there will be more than one usable XSLT 2.0 processor.

Answer 5

Basic DocBook schema allows any elements from MathML namespace to appear inside equation element. This means that you can validate DocBook+MathML document, but MathML content will be ignored during the validation. You will also not be able to use guided editing for MathML content.

If you need strict validation of MathML content or guided editing for MathML, you can easily extend the base DocBook schema with a MathML schema.

Procedure 1. Extending the DocBook schema with MathML schema

Download MathML RELAX NG schema from http://yupotan.sppd.ne.jp/relax-ng/mml2.html and unpack it somewhere (e.g. into mathml subdirectory).

Create easy schema customization dbmathml.rnc:

namespace html = "http://www.w3.org/1999/xhtml"
namespace mml = "http://www.w3.org/1998/Math/MathML"
namespace db = "http://docbook.org/ns/docbook"

include "/path/to/docbook.rnc" {
  db._any.mml = external "mathml/mathml2.rnc"
  db._any =
    element * - (db:* | html:* | mml:*) {
      (attribute * { text }
       | text
       | db._any)*
    }
}

Or alternatively you can use XML syntax of RELAX NG—dbmathml.rng:

<?xml version="1.0" encoding="UTF-8"?>
<grammar xmlns="http://relaxng.org/ns/structure/1.0">

<include href="/path/to/docbook.rng">
  <define name="db._any.mml">
    <externalRef href="mathml/mathml2.rng"/>
  </define>

  <define name="db._any">
    <element>
      <anyName>
        <except>
          <nsName ns="http://docbook.org/ns/docbook"/>
          <nsName ns="http://www.w3.org/1999/xhtml"/>
          <nsName ns="http://www.w3.org/1998/Math/MathML"/>
        </except>
      </anyName>
      <zeroOrMore>
        <choice>
          <attribute>
            <anyName/>
          </attribute>
          <text/>
          <ref name="db._any"/>
        </choice>
      </zeroOrMore>
    </element>
  </define>
</include>

</grammar>

Now use the customized schema (dbmathml.rnc or dbmathml.rng) instead of the original DocBook schema.

Answer 6

The situation is the same as with MathML support. You can use any elements from the SVG namespace inside imageobject element.

Procedure 2. Extending the DocBook schema with SVG schema

Download SVG RELAX NG schema from http://www.w3.org/Graphics/SVG/1.1/rng/rng.zip and unpack it somewhere (e.g. into svg subdirectory).

Create easy schema customization dbsvg.rnc:

namespace html = "http://www.w3.org/1999/xhtml"
namespace db = "http://docbook.org/ns/docbook"
namespace svg = "http://www.w3.org/2000/svg"

include "/path/to/docbook.rnc" {
  db._any.svg = external "svg/svg11.rnc"
  db._any =
    element * - (db:* | html:* | svg:*) {
      (attribute * { text }
       | text
       | db._any)*
    }
}

Or alternatively you can use XML syntax of RELAX NG—dbsvg.rng:

<?xml version="1.0" encoding="UTF-8"?>
<grammar xmlns="http://relaxng.org/ns/structure/1.0">

<include href="/path/to/docbook.rng">
  <define name="db._any.svg">
    <externalRef href="svg/svg11.rng"/>
  </define>

  <define name="db._any">
    <element>
      <anyName>
        <except>
          <nsName ns="http://docbook.org/ns/docbook"/>
          <nsName ns="http://www.w3.org/1999/xhtml"/>
          <nsName ns="http://www.w3.org/2000/svg"/>
        </except>
      </anyName>
      <zeroOrMore>
        <choice>
          <attribute>
            <anyName/>
          </attribute>
          <text/>
          <ref name="db._any"/>
        </choice>
      </zeroOrMore>
    </element>
  </define>
</include>

</grammar>

Now use the customized schema (dbsvg.rnc or dbsvg.rng) instead of the original DocBook schema.

Answer 7

Yes, you can create a special schema customization that combines both MathML and SVG with the DocBook schema. In compact syntax, merged schema is:

namespace html = "http://www.w3.org/1999/xhtml"
namespace mml = "http://www.w3.org/1998/Math/MathML"
namespace db = "http://docbook.org/ns/docbook"
namespace svg = "http://www.w3.org/2000/svg"

include "/path/to/docbook.rnc" {
  db._any.mml = external "mahtml/mathml2.rnc"
  db._any.svg = external "svg/svg11.rnc"
  db._any =
    element * - (db:* | html:* | mml:* | svg:*) {
      (attribute * { text }
       | text
       | db._any)*
    }
}

Or alternatively in full RELAX NG syntax:

<?xml version="1.0" encoding="UTF-8"?>
<grammar xmlns="http://relaxng.org/ns/structure/1.0">

<include href="/path/to/docbook.rng">
  <define name="db._any.mml">
    <externalRef href="mathml/mathml2.rng"/>
  </define>

  <define name="db._any.svg">
    <externalRef href="svg/svg11.rng"/>
  </define>

  <define name="db._any">
    <element>
      <anyName>
        <except>
          <nsName ns="http://docbook.org/ns/docbook"/>
          <nsName ns="http://www.w3.org/1999/xhtml"/>
          <nsName ns="http://www.w3.org/1998/Math/MathML"/>
          <nsName ns="http://www.w3.org/2000/svg"/>
        </except>
      </anyName>
      <zeroOrMore>
        <choice>
          <attribute>
            <anyName/>
          </attribute>
          <text/>
          <ref name="db._any"/>
        </choice>
      </zeroOrMore>
    </element>
  </define>
</include>

</grammar>

Answer 8

XMLSpy always uses its own bundled version of xml.xsd which unfortunately doesn't define xml:id attribute. The bundled version of xml.xsd is hardwired into the program and can not be replaced by a newer version. To solve this problem you must upgrade to version 2006 SP1.

Old name	New name
`sgmltag`	`tag`
`bookinfo`, `articleinfo`, `chapterinfo`, `*info`	`info`
`authorblurb`	`personblurb`
`collabname`, `corpauthor`, `corpcredit`, `corpname`	`orgname`
`isbn`, `issn`, `pubsnumber`	`biblioid`
`lot`, `lotentry`, `tocback`, `tocchap`, `tocfront`, `toclevel1`, `toclevel2`, `toclevel3`, `toclevel4`, `toclevel5`, `tocpart`	`tocdiv`
`graphic`, `graphicco`, `inlinegraphic`, `mediaobjectco`	`mediaobject` and `inlinemediaobject`
`ulink`	`link`

1. Authoring
1.1. How do I attach a schema to a DocBook V5.0 document when I do not want to use DTDs and !DOCTYPE? 1.2. How do I use entities like – in DocBook V5.0? 1.3. How to modularize documents?
1.1.	How do I attach a schema to a DocBook V5.0 document when I do not want to use DTDs and !DOCTYPE?
	There is no standard way of associating a RELAX NG schema with a document. Most tools provide some mechanism for performing this association, consult the documentation for your application. In some tools you must specify schema manually each time your want to edit/process your document.
1.2.	How do I use entities like `–` in DocBook V5.0?
	Modern schema languages (including RELAX NG and W3X XML Schema) do not provide any means to define entities that can be used for easier typing of special characters. Some editors provide functions or special toolbars that allow you to easily pick necessary character and insert it into document as a raw Unicode character or a numeric character reference. Another possibility is to include entity definitions in the prolog of your document. Entity definition files are now maintained by W3C. You can reference definition files with entity definitions you are interested in and then reference imported entities. For example: <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE article [ <!ENTITY % isopub SYSTEM "http://www.w3.org/2003/entities/iso8879/isopub.ent"> %isopub; ]> <article xmlns="http://docbook.org/ns/docbook" version="5.0"> <title>DocBook V5.0 – the superb documentation format</title> …
1.3.	How to modularize documents?
	You can use XInclude for this task. There are available alternative schemas for DocBook V5.0 that contain XInclude elements. This is necessary to make some XML editors happy. Name of these schemas ends with letters “xi”, e.g. `docbookxi.rnc` instead of `docbook.rnc`.
2. Stylesheets
2.1. Will be the current DocBook XSL stylesheets (XSLT 1.0 based implementation) maintained and improved in the future if a new work on a new XSLT 2.0 based implementation started already?
2.1.	Will be the current DocBook XSL stylesheets (XSLT 1.0 based implementation) maintained and improved in the future if a new work on a new XSLT 2.0 based implementation started already?
	Yes, the current stylesheets (like 1.69.1) will be supported and improved further because they are very widely deployed and work with many existing XSLT processors. Surely there will be point in a future when all new development will be switched to XSLT 2.0 based implementation only. But this will not happen before all features of the current stylesheets are implemented in the new stylesheets and before there will be more than one usable XSLT 2.0 processor.
3. Schema customizations
3.1. How can I extend DocBook schema with MathML elements? 3.2. How can I extend DocBook schema with SVG elements? 3.3. Is it possible to use previous two customizations for MathML and SVG together?
3.1.	How can I extend DocBook schema with MathML elements?
	Basic DocBook schema allows any elements from MathML namespace to appear inside `equation` element. This means that you can validate DocBook+MathML document, but MathML content will be ignored during the validation. You will also not be able to use guided editing for MathML content. If you need strict validation of MathML content or guided editing for MathML, you can easily extend the base DocBook schema with a MathML schema. Procedure 1. Extending the DocBook schema with MathML schema Download MathML RELAX NG schema from http://yupotan.sppd.ne.jp/relax-ng/mml2.html and unpack it somewhere (e.g. into `mathml` subdirectory). Create easy schema customization `dbmathml.rnc`: namespace html = "http://www.w3.org/1999/xhtml" namespace mml = "http://www.w3.org/1998/Math/MathML" namespace db = "http://docbook.org/ns/docbook" include "/path/to/docbook.rnc" { db._any.mml = external "mathml/mathml2.rnc" db._any = element * - (db:* \| html:* \| mml:) { (attribute { text } \| text \| db._any)* } } Or alternatively you can use XML syntax of RELAX NG—`dbmathml.rng`: <?xml version="1.0" encoding="UTF-8"?> <grammar xmlns="http://relaxng.org/ns/structure/1.0"> <include href="/path/to/docbook.rng"> <define name="db._any.mml"> <externalRef href="mathml/mathml2.rng"/> </define> <define name="db._any"> <element> <anyName> <except> <nsName ns="http://docbook.org/ns/docbook"/> <nsName ns="http://www.w3.org/1999/xhtml"/> <nsName ns="http://www.w3.org/1998/Math/MathML"/> </except> </anyName> <zeroOrMore> <choice> <attribute> <anyName/> </attribute> <text/> <ref name="db._any"/> </choice> </zeroOrMore> </element> </define> </include> </grammar> Now use the customized schema (`dbmathml.rnc` or `dbmathml.rng`) instead of the original DocBook schema.
3.2.	How can I extend DocBook schema with SVG elements?
	The situation is the same as with MathML support. You can use any elements from the SVG namespace inside `imageobject` element. Procedure 2. Extending the DocBook schema with SVG schema Download SVG RELAX NG schema from http://www.w3.org/Graphics/SVG/1.1/rng/rng.zip and unpack it somewhere (e.g. into `svg` subdirectory). Create easy schema customization `dbsvg.rnc`: namespace html = "http://www.w3.org/1999/xhtml" namespace db = "http://docbook.org/ns/docbook" namespace svg = "http://www.w3.org/2000/svg" include "/path/to/docbook.rnc" { db._any.svg = external "svg/svg11.rnc" db._any = element * - (db:* \| html:* \| svg:) { (attribute { text } \| text \| db._any)* } } Or alternatively you can use XML syntax of RELAX NG—`dbsvg.rng`: <?xml version="1.0" encoding="UTF-8"?> <grammar xmlns="http://relaxng.org/ns/structure/1.0"> <include href="/path/to/docbook.rng"> <define name="db._any.svg"> <externalRef href="svg/svg11.rng"/> </define> <define name="db._any"> <element> <anyName> <except> <nsName ns="http://docbook.org/ns/docbook"/> <nsName ns="http://www.w3.org/1999/xhtml"/> <nsName ns="http://www.w3.org/2000/svg"/> </except> </anyName> <zeroOrMore> <choice> <attribute> <anyName/> </attribute> <text/> <ref name="db._any"/> </choice> </zeroOrMore> </element> </define> </include> </grammar> Now use the customized schema (`dbsvg.rnc` or `dbsvg.rng`) instead of the original DocBook schema.
3.3.	Is it possible to use previous two customizations for MathML and SVG together?
	Yes, you can create a special schema customization that combines both MathML and SVG with the DocBook schema. In compact syntax, merged schema is: namespace html = "http://www.w3.org/1999/xhtml" namespace mml = "http://www.w3.org/1998/Math/MathML" namespace db = "http://docbook.org/ns/docbook" namespace svg = "http://www.w3.org/2000/svg" include "/path/to/docbook.rnc" { db._any.mml = external "mahtml/mathml2.rnc" db._any.svg = external "svg/svg11.rnc" db._any = element * - (db:* \| html:* \| mml:* \| svg:) { (attribute { text } \| text \| db._any)* } } Or alternatively in full RELAX NG syntax: <?xml version="1.0" encoding="UTF-8"?> <grammar xmlns="http://relaxng.org/ns/structure/1.0"> <include href="/path/to/docbook.rng"> <define name="db._any.mml"> <externalRef href="mathml/mathml2.rng"/> </define> <define name="db._any.svg"> <externalRef href="svg/svg11.rng"/> </define> <define name="db._any"> <element> <anyName> <except> <nsName ns="http://docbook.org/ns/docbook"/> <nsName ns="http://www.w3.org/1999/xhtml"/> <nsName ns="http://www.w3.org/1998/Math/MathML"/> <nsName ns="http://www.w3.org/2000/svg"/> </except> </anyName> <zeroOrMore> <choice> <attribute> <anyName/> </attribute> <text/> <ref name="db._any"/> </choice> </zeroOrMore> </element> </define> </include> </grammar>
4. Tool specific problems
4.1. I'm using Altova XMLSpy to validate DocBook V5.0 instances against W3C XML Schema (docbook.xsd). XMLSpy complains about undefined xml:id attribute?
4.1.	I'm using Altova XMLSpy to validate DocBook V5.0 instances against W3C XML Schema (`docbook.xsd`). XMLSpy complains about undefined `xml:id` attribute?
	XMLSpy always uses its own bundled version of `xml.xsd` which unfortunately doesn't define `xml:id` attribute. The bundled version of `xml.xsd` is hardwired into the program and can not be replaced by a newer version. To solve this problem you must upgrade to version 2006 SP1.

DocBook V5.0

The Transition Guide

28 December 2005

This version:

Latest version:

Previous version:

Authors:

Introduction

Finally in a namespace

Note

Relaxing with DocBook

Note

Why switch to DocBook V5.0?

Schema jungle

Where to get the schemas

DocBook documentation

Note

Toolchain

Editing DocBook V5.0

Emacs and nXML

Note

oXygen

XML Mind XML editor

Validating DocBook V5.0

Note

Processing DocBook V5.0

DocBook XSL Stylesheets

XSLT 2.0 based reimplementation

Markup changes

Improved cross-referencing and linking

Renamed elements

Removed elements

Converting DocBook V4.x documents to DocBook V5.0

What About Entities?

Tip

External Parsed Entities

Customizing DocBook V5.0

FAQ

1. Authoring

2. Stylesheets

3. Schema customizations

4. Tool specific problems

Bibliography