1<html> 2 3<head> 4<title>Docbook Toolchain for Khronos Documents</title> 5</head> 6 7<body> 8<h1>What is Docbook?</h1> 9 10<p> <a href="http://www.docbook.org/">Docbook</a> is a widely used XML 11 schema for technical documentation(*). It is an open source project 12 with a great deal of supporting infrastructure and documentation. 13 Start with the <a href="http://www.dpawson.co.uk/docbook/">Docbook 14 FAQ</a> and the canonical text <a 15 href="http://docbook.org/tdg/">DocBook: The Definitive Guide</a> 16 (since we are using Docbook 4.x, read version 2.0 of the Guide). 17 18 19<p> Like LaTeX, Docbook is a structural description of a document. 20 Docbook does <b>not</b> define formatting. Using XSL stylesheets, 21 Docbook documents can be transformed into many other formats such as 22 XHTML, PDF, Unix nroff man pages, and Windows HTML Help. 23 24<p> Khronos has agreed to use Docbook as the format for new man pages 25 and technical specifications created within the group. 26 This document captures basic information about Docbook 27 and the toolchain required to use it. 28 29<p> (*) Actually, there are SGML and Relax NG schemas for Docbook 30 as well. However, for Khronos' purposes we concentrate on 31 the XML schema. 32 33 34<h1>Docbook Editors</h1> 35 36<p> Since Docbook documents are XML, it is possible (and perhaps 37 desirable for smaller documents) to simply use a text editor and 38 mark up XML by hand. Emacs is reputed to have a Docbook and/or XML 39 editing mode which may be useful. 40 41<p> There are a variety of free and commercial XML editors. Some are 42 described in the <a 43 href="http://www.dpawson.co.uk/docbook/reference.html#d17e1366">Docbook 44 FAQ</a>. We have experimented with the free Standard version of <a 45 href="http://www.xmlmind.com/xmleditor/">XMLMind</a> with some 46 success; unlike many of the other options, XMLMind understands the 47 Docbook schema and can render Docbook documents in a WYSIWYG-like 48 fashion, in addition to the straight XML structure editor. 49 50 51<h1>Docbook Schema</h1> 52 53<p> There are many versions of the Docbook XML Schema. We are currently 54 using Docbook 4.3 with MathML 2.0 support. See the DOCTYPE 55 declaration in the sample documents for the specific DTDs. 56 57 58<h1>XSL Stylesheets</h1> 59 60<p> To transform Docbook documents into final viewable formats, we use 61 the standard <a 62 href="http://wiki.docbook.org/topic/DocBookXslStylesheets"> Modular 63 Docbook XSL stylesheets</a> (version 1.69). These are available 64 prepackaged for modern Linux systems (although you may have to 65 manually select the packages) as well as for the Cygwin environment 66 on Windows. We are using version 1.69 of the stylesheets. 67 68<p> (<b>Note:</b> need links to Cygwin / Red Hat / other Linux distro? 69 packages). 70 71 72<h1>Tools</h1> 73 74<p> The Docbook 4.3 DTD is also prepackaged for most systems. Some 75 additional work is required to install the Docbook 4.3+MathML 2.0 76 DTD (details to be added). 77 78 (<b>Note:</b> need links to Cygwin / Red Hat / other Linux distro? packages). 79 80<p> To transform a Docbook document with the XSL Stylesheets, 81 a processor like <a href="http://wiki.docbook.org/topic/xsltproc"> 82 xsltproc</a> or Saxon is required. Again, xsltproc 83 is prepackaged. 84 85 (<b>Note:</b> again, need links to Cygwin / Red Hat / other Linux 86 distro? packages). 87 88<h1>Examples</h1> 89 90<p> A simple example package containing a Docbook document (sample man 91 page) and Makefile to transform it are <b>here (link TBD)</b>. 92 93<p> Last modified August 13, 2006 by Jon Leech 94</body> 95</html> 96