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 you 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 is an alternative schema for DocBook V5.0 that contains XInclude elements. This is necessary to make some XML editors happy. This schema can be found in files that end 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 a point in a future when all new development will be switched to the XSLT 2.0 based implementation. But this will not happen until all features of the current stylesheets are implemented in the new stylesheets and until there is more than one usable XSLT 2.0 processor available.

Answer 5

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

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

Procedure 1. Extending the DocBook schema with the MathML schema

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

Create a schema customization in compact syntax—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 the 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 elements from the SVG namespace inside the imageobject element.

Procedure 2. Extending the DocBook schema with the SVG schema

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

Create a schema customization in compact syntax—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 the 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, the 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 the 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 the xml:id attribute. The bundled version of xml.xsd is hardwired into the program and cannot 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`

Old name	Recommended mapping
`action`	Use `<phrase remap="action">`.
`beginpage`	Remove: `beginpage` is advisory only and has tended to cause confusion. A processing instruction or comment should be a workable replacement if one is needed.
`highlights`	Use `abstract`. Note that because `highlights` has a broader content model, you may need to wrap contents in a `para` inside `abstract`.
`interface`	Use one of the “gui*” elements (`guibutton`, `guiicon`, `guilabel`, `guimenu`, `guimenuitem`, or `guisubmenu`).
`invpartnumber`	Use `<biblioid class="other" otherclass="medialabel">`. The `productnumber` element is another alternative.
`medialabel`	Use `<citetitle pubwork="mediatype">`, where `mediatype` is the type of media being labeled (e.g.,`cdrom` or `dvd`).
`modespec`	No longer needed. The current processing model for `olink` renders `modespec` unnecessary.
`structfield`, `structname`	Use `varname`. If you need to distinguish between the two, use `<varname remap="structname or structfield">`. In some contexts, it may also be appropriate to use `property` for `structfield`.

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 you 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 is an alternative schema for DocBook V5.0 that contains XInclude elements. This is necessary to make some XML editors happy. This schema can be found in files that end with letters “xi”, e.g. `docbookxi.rnc` instead of `docbook.rnc`.
2. Stylesheets
2.1. Will the current DocBook XSL stylesheets (XSLT 1.0 based implementation) be maintained and improved in the future since work on a new XSLT 2.0 based implementation has started?
2.1.	Will the current DocBook XSL stylesheets (XSLT 1.0 based implementation) be maintained and improved in the future since work on a new XSLT 2.0 based implementation has started?
	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 a point in a future when all new development will be switched to the XSLT 2.0 based implementation. But this will not happen until all features of the current stylesheets are implemented in the new stylesheets and until there is more than one usable XSLT 2.0 processor available.
3. Schema customizations
3.1. How can I extend the DocBook schema with MathML elements? 3.2. How can I extend the DocBook schema with SVG elements? 3.3. Is it possible to use the previous two customizations for MathML and SVG together?
3.1.	How can I extend the DocBook schema with MathML elements?
	The basic DocBook schema allows elements from the MathML namespace to appear inside the `equation` element. This means that you can validate a DocBook+MathML document, but MathML content will be ignored during the validation. You will also not be able to use guided editing for the MathML content. If you need strict validation of MathML content or guided editing for MathML, you can easily extend the base DocBook schema with the MathML schema. Procedure 1. Extending the DocBook schema with the MathML schema Download the MathML RELAX NG schema from http://yupotan.sppd.ne.jp/relax-ng/mml2.html and unpack it somewhere (e.g. into a `mathml` subdirectory). Create a schema customization in compact syntax—`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 the 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 the DocBook schema with SVG elements?
	The situation is the same as with MathML support. You can use elements from the SVG namespace inside the `imageobject` element. Procedure 2. Extending the DocBook schema with the SVG schema Download the SVG RELAX NG schema from http://www.w3.org/Graphics/SVG/1.1/rng/rng.zip and unpack it somewhere (e.g. into an `svg` subdirectory). Create a schema customization in compact syntax—`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 the 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 the 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, the 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 the 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 the W3C XML Schema (docbook.xsd). XMLSpy complains about undefined xml:id attributes?
4.1.	I'm using Altova XMLSpy to validate DocBook V5.0 instances against the W3C XML Schema (`docbook.xsd`). XMLSpy complains about undefined `xml:id` attributes?
	XMLSpy always uses its own bundled version of `xml.xsd` which unfortunately doesn't define the `xml:id` attribute. The bundled version of `xml.xsd` is hardwired into the program and cannot be replaced by a newer version. To solve this problem you must upgrade to version 2006 SP1.

DocBook V5.0

The Transition Guide

01 March 2006

This version:

Latest version:

Previous versions:

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 re-implementation

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