Dag-Erling Smørgrav

These stylesheets are intented for quick previews of DocBook XML documents in CSS- and XSLT-capable web browsers. The main advantage is that you can preview a document that you are working on with no further ado than pressing "reload" in your browser. They are also useful for situations such as browsing a Subversion repository using mod_dav_svn or a similar web interface; with the proper magic, when viewing a DocBook document, the user's browser will immediately load the stylesheet, and the user will see a readable document instead of a sea of XML tags. The XSLT version generates valid and easily stylable XHTML 1.0 Strict documents. It is accompanied by a simple but fairly pleasant (to the author's eye) CSS stylesheet, but it is also designed to produce output suitable for viewing with browsers that do not support CSS, or with CSS disabled. This is achieved by adhering to the following principles: Use standard HTML elements to approximate the result one would normally expect in the absence of a CSS stylesheet. For instance, <emphasis> is translated to <em>, <filename> is translated to <tt> and <screen> is translated to <pre>. Keep the HTML code simple. The XSLT stylesheet does not use any pre-CSS HTML tricks, such as using tables to control positioning, or <b> and <big> to control the appearance of a subtitle. Preserve structural information. For instance, sections, chapters etc. are wrapped in <div> elements to preserve the structure of the original document. Preserve semantical information. This means that for most DocBook elements, the corresponding HTML element has a class attribute with the name of the original DocBook element. For instance, although <programlisting> and <screen> are both translated to <pre>, they have different class attributes, so a CSS stylesheet can distinguish between them and render them differently. The first two principles ensure that the resulting HTML document is viewable in non-CSS-capable browsers, including text-only browsers such as Lynx and w3m. The last two ensure that the HTML document contains as much information as possible about the original DocBook document, to allow more effective use of CSS to control the final layout. The CSS version simply provides information on how to render the raw XML. The result is not particularly good, since CSS doesn't allow you to manipulate the order in which elements are displayed or transform the content in any significant manner, but it is good enough for proof-reading.

To use the XSLT version, add the following line at the top of your DocBook document, immediately after the XML declaration and before the document type declaration: <?xml-stylesheet type="application/xml" href="docbook-html.xsl"?> IMPORTANT NOTE: the value of the type attribute must match the Content-Type your web server specifies for the stylesheet. By default, Apache 2 uses application/xml for .xsl files and application/xslt+xml for .xslt files. The former is the correct MIME type according to the XSLT 1.0 specification. The latter is correct according to the XSLT 2.0 draft specification, but has not yet been registered with IANA. Currently, the safest option seems to be to stick with application/xml. This assumes that the stylesheet is located in the same directory as the document; otherwise, adjust the href attribute to point at the correct URL.

To use the CSS version, add the following line at the top of your DocBook document, immediately after the XML declaration andx before the document type declaration: <?xml-stylesheet type="text/css" href="docbook-xml.css"?> This assumes that the stylesheet is located in the same directory as the document; otherwise, adjust the href attribute to point at the correct URL.

Gecko-based browsers (such as Firefox and Galeon) won't load a stylesheet located on a different server than the document. When using the CSS version, ordered lists will not render properly in Gecko-based browsers, due to a bug in Gecko's implementation of counters (see Mozilla bug 4522).

These stylesheets implement only a fairly small subset of DocBook. Specifically, the stylesheets implement the bits of DocBook that I a) use frequently and b) could figure out how to implement easily in XSLT or CSS. In theory, the feature set of the XSLT stylesheet should be a strict superset of the feature set of the CSS stylesheet, but this may not be the case, as the development process for these stylesheets is rather haphazard. The most obviously useful parts of DocBook that I haven't implemented at all (yet) are images and other embedded media.

Internal links don't work properly, except for those in the table of contents. In <table> and <informaltable>, only the first <tgroup> is rendered. Row and column spans are not implemented; expect surprising results. The XSLT stylesheet has been designed for use with UTF-8 documents (which includes documents written in pure ASCII), and has not been tested with other encodings.

Links, whether internal or external, don't work.

XSLT version: CSS version:

Copyright © 2004-2009 Dag-Erling Smørgrav. Distributed under the Creative Commons Attribution-Share Alike 3.0 license.