15bd8deadSopenharmony_ci<html> 25bd8deadSopenharmony_ci 35bd8deadSopenharmony_ci<head> 45bd8deadSopenharmony_ci<title>Docbook Toolchain for Khronos Documents</title> 55bd8deadSopenharmony_ci</head> 65bd8deadSopenharmony_ci 75bd8deadSopenharmony_ci<body> 85bd8deadSopenharmony_ci<h1>What is Docbook?</h1> 95bd8deadSopenharmony_ci 105bd8deadSopenharmony_ci<p> <a href="http://www.docbook.org/">Docbook</a> is a widely used XML 115bd8deadSopenharmony_ci schema for technical documentation(*). It is an open source project 125bd8deadSopenharmony_ci with a great deal of supporting infrastructure and documentation. 135bd8deadSopenharmony_ci Start with the <a href="http://www.dpawson.co.uk/docbook/">Docbook 145bd8deadSopenharmony_ci FAQ</a> and the canonical text <a 155bd8deadSopenharmony_ci href="http://docbook.org/tdg/">DocBook: The Definitive Guide</a> 165bd8deadSopenharmony_ci (since we are using Docbook 4.x, read version 2.0 of the Guide). 175bd8deadSopenharmony_ci 185bd8deadSopenharmony_ci 195bd8deadSopenharmony_ci<p> Like LaTeX, Docbook is a structural description of a document. 205bd8deadSopenharmony_ci Docbook does <b>not</b> define formatting. Using XSL stylesheets, 215bd8deadSopenharmony_ci Docbook documents can be transformed into many other formats such as 225bd8deadSopenharmony_ci XHTML, PDF, Unix nroff man pages, and Windows HTML Help. 235bd8deadSopenharmony_ci 245bd8deadSopenharmony_ci<p> Khronos has agreed to use Docbook as the format for new man pages 255bd8deadSopenharmony_ci and technical specifications created within the group. 265bd8deadSopenharmony_ci This document captures basic information about Docbook 275bd8deadSopenharmony_ci and the toolchain required to use it. 285bd8deadSopenharmony_ci 295bd8deadSopenharmony_ci<p> (*) Actually, there are SGML and Relax NG schemas for Docbook 305bd8deadSopenharmony_ci as well. However, for Khronos' purposes we concentrate on 315bd8deadSopenharmony_ci the XML schema. 325bd8deadSopenharmony_ci 335bd8deadSopenharmony_ci 345bd8deadSopenharmony_ci<h1>Docbook Editors</h1> 355bd8deadSopenharmony_ci 365bd8deadSopenharmony_ci<p> Since Docbook documents are XML, it is possible (and perhaps 375bd8deadSopenharmony_ci desirable for smaller documents) to simply use a text editor and 385bd8deadSopenharmony_ci mark up XML by hand. Emacs is reputed to have a Docbook and/or XML 395bd8deadSopenharmony_ci editing mode which may be useful. 405bd8deadSopenharmony_ci 415bd8deadSopenharmony_ci<p> There are a variety of free and commercial XML editors. Some are 425bd8deadSopenharmony_ci described in the <a 435bd8deadSopenharmony_ci href="http://www.dpawson.co.uk/docbook/reference.html#d17e1366">Docbook 445bd8deadSopenharmony_ci FAQ</a>. We have experimented with the free Standard version of <a 455bd8deadSopenharmony_ci href="http://www.xmlmind.com/xmleditor/">XMLMind</a> with some 465bd8deadSopenharmony_ci success; unlike many of the other options, XMLMind understands the 475bd8deadSopenharmony_ci Docbook schema and can render Docbook documents in a WYSIWYG-like 485bd8deadSopenharmony_ci fashion, in addition to the straight XML structure editor. 495bd8deadSopenharmony_ci 505bd8deadSopenharmony_ci 515bd8deadSopenharmony_ci<h1>Docbook Schema</h1> 525bd8deadSopenharmony_ci 535bd8deadSopenharmony_ci<p> There are many versions of the Docbook XML Schema. We are currently 545bd8deadSopenharmony_ci using Docbook 4.3 with MathML 2.0 support. See the DOCTYPE 555bd8deadSopenharmony_ci declaration in the sample documents for the specific DTDs. 565bd8deadSopenharmony_ci 575bd8deadSopenharmony_ci 585bd8deadSopenharmony_ci<h1>XSL Stylesheets</h1> 595bd8deadSopenharmony_ci 605bd8deadSopenharmony_ci<p> To transform Docbook documents into final viewable formats, we use 615bd8deadSopenharmony_ci the standard <a 625bd8deadSopenharmony_ci href="http://wiki.docbook.org/topic/DocBookXslStylesheets"> Modular 635bd8deadSopenharmony_ci Docbook XSL stylesheets</a> (version 1.69). These are available 645bd8deadSopenharmony_ci prepackaged for modern Linux systems (although you may have to 655bd8deadSopenharmony_ci manually select the packages) as well as for the Cygwin environment 665bd8deadSopenharmony_ci on Windows. We are using version 1.69 of the stylesheets. 675bd8deadSopenharmony_ci 685bd8deadSopenharmony_ci<p> (<b>Note:</b> need links to Cygwin / Red Hat / other Linux distro? 695bd8deadSopenharmony_ci packages). 705bd8deadSopenharmony_ci 715bd8deadSopenharmony_ci 725bd8deadSopenharmony_ci<h1>Tools</h1> 735bd8deadSopenharmony_ci 745bd8deadSopenharmony_ci<p> The Docbook 4.3 DTD is also prepackaged for most systems. Some 755bd8deadSopenharmony_ci additional work is required to install the Docbook 4.3+MathML 2.0 765bd8deadSopenharmony_ci DTD (details to be added). 775bd8deadSopenharmony_ci 785bd8deadSopenharmony_ci (<b>Note:</b> need links to Cygwin / Red Hat / other Linux distro? packages). 795bd8deadSopenharmony_ci 805bd8deadSopenharmony_ci<p> To transform a Docbook document with the XSL Stylesheets, 815bd8deadSopenharmony_ci a processor like <a href="http://wiki.docbook.org/topic/xsltproc"> 825bd8deadSopenharmony_ci xsltproc</a> or Saxon is required. Again, xsltproc 835bd8deadSopenharmony_ci is prepackaged. 845bd8deadSopenharmony_ci 855bd8deadSopenharmony_ci (<b>Note:</b> again, need links to Cygwin / Red Hat / other Linux 865bd8deadSopenharmony_ci distro? packages). 875bd8deadSopenharmony_ci 885bd8deadSopenharmony_ci<h1>Examples</h1> 895bd8deadSopenharmony_ci 905bd8deadSopenharmony_ci<p> A simple example package containing a Docbook document (sample man 915bd8deadSopenharmony_ci page) and Makefile to transform it are <b>here (link TBD)</b>. 925bd8deadSopenharmony_ci 935bd8deadSopenharmony_ci<p> Last modified August 13, 2006 by Jon Leech 945bd8deadSopenharmony_ci</body> 955bd8deadSopenharmony_ci</html> 96