Introduction

The docbook-html5 project is a set of XSLT stylesheets for transforming DocBook 5 XML into (X)HTML5 documents, developed as part of the Research & Education Space project in order to produce specific mark-up from our DocBook 5 sources.

The stylesheets have no direct connection to the extremely comprehensive official DocBook XSL stylesheets, and don't have the same level of element coverage, but you may find them easier to modify to suit your needs than the official XSL package thanks to to their relative simplicity.

Usage

If your XSLT processor supports it, docbook-html5 can be used either remotely, or you can include a copy in your project (for example, as a git submodule), and used locally.

Examples given here use xsltproc, an open source cross-platform XSLT processor included with most Linux and Unix distributions.

To use docbook-html5 remotely:—

$  xsltproc --xinclude -o OUTPUT.html http://bbcarchdev.github.io/docbook-html5/docbook-html5.xsl INPUT.xml

To use docbook-html5 locally, simply specify the filesystem path to docbook-html5.xsl in place of the URL:—

$  xsltproc --xinclude --nonet -o OUTPUT.html http://bbcarchdev.github.io/docbook-html5/docbook-html5.xsl INPUT.xml

When using the stylesheets locally, the --nonet option may be supplied, which prevents xsltproc from performing any requests to remote network hosts.

Parameters

The stylesheets support a number of parameters which alter the output which is produced.

html.linksfile: Specifies the URL of an XML file whose contents will be substituted into the output document’s <head> element, and typically contains <link> and <meta> elements. See links-sample.xml for an example. Note that the URL specified will be interpreted as relative to the stylesheets URL, and so you may need to specify an absolute file:/// URL.
html.navfile: Specifies the URL of an XML file whose contents will be substituted into the output document’s global <nav> element (which appears, if this parameter is specified, within the document-level <header>). See nav-sample.xml for an example. Note that the URL specified will be interpreted as relative to the stylesheets URL, and so you may need to specify an absolute file:/// URL.
html.ie78css: Specifies the URL of the CSS stylesheet which targets Microsoft Internet Explorer 7 and 8, and will be referenced by a <link> element within the HTML document’s <head> element, and is emitted as a conditional comment which is ignored by other web browsers.

Example

$  xsltproc --xinclude \
	-o OUTPUT.html \
	--param html.linksfile "'file://`pwd`/links-sample.xml'" \
	--param html.navfile "'file://`pwd`/nav-sample.xml'" \
	--param html.ie78css "'http://docs.example.com/stylesheets/ie78.css'" \
	/path/or/url/to/docbook-html5/docbook-html5.xsl \
	INPUT.xml