docs/toolchain.html

<html>

<head>
<title>Docbook Toolchain for Khronos Documents</title>
</head>

<body>
<h1>What is Docbook?</h1>

<p> <a href="http://www.docbook.org/">Docbook</a> is a widely used XML
    schema for technical documentation(*). It is an open source project
    with a great deal of supporting infrastructure and documentation.
    Start with the <a href="http://www.dpawson.co.uk/docbook/">Docbook
    FAQ</a> and the canonical text <a
    href="http://docbook.org/tdg/">DocBook: The Definitive Guide</a>
    (since we are using Docbook 4.x, read version 2.0 of the Guide).


<p> Like LaTeX, Docbook is a structural description of a document.
    Docbook does <b>not</b> define formatting. Using XSL stylesheets,
    Docbook documents can be transformed into many other formats such as
    XHTML, PDF, Unix nroff man pages, and Windows HTML Help.

<p> Khronos has agreed to use Docbook as the format for new man pages
    and technical specifications created within the group.
    This document captures basic information about Docbook
    and the toolchain required to use it.

<p> (*) Actually, there are SGML and Relax NG schemas for Docbook
    as well. However, for Khronos' purposes we concentrate on
    the XML schema.


<h1>Docbook Editors</h1>

<p> Since Docbook documents are XML, it is possible (and perhaps
    desirable for smaller documents) to simply use a text editor and
    mark up XML by hand. Emacs is reputed to have a Docbook and/or XML
    editing mode which may be useful.

<p> There are a variety of free and commercial XML editors. Some are
    described in the <a
    href="http://www.dpawson.co.uk/docbook/reference.html#d17e1366">Docbook
    FAQ</a>. We have experimented with the free Standard version of <a
    href="http://www.xmlmind.com/xmleditor/">XMLMind</a> with some
    success; unlike many of the other options, XMLMind understands the
    Docbook schema and can render Docbook documents in a WYSIWYG-like
    fashion, in addition to the straight XML structure editor.


<h1>Docbook Schema</h1>

<p> There are many versions of the Docbook XML Schema. We are currently
    using Docbook 4.3 with MathML 2.0 support. See the DOCTYPE
    declaration in the sample documents for the specific DTDs.


<h1>XSL Stylesheets</h1>

<p> To transform Docbook documents into final viewable formats, we use
    the standard <a
    href="http://wiki.docbook.org/topic/DocBookXslStylesheets"> Modular
    Docbook XSL stylesheets</a> (version 1.69). These are available
    prepackaged for modern Linux systems (although you may have to
    manually select the packages) as well as for the Cygwin environment
    on Windows. We are using version 1.69 of the stylesheets.

<p> (<b>Note:</b> need links to Cygwin / Red Hat / other Linux distro?
    packages).


<h1>Tools</h1>

<p> The Docbook 4.3 DTD is also prepackaged for most systems. Some
    additional work is required to install the Docbook 4.3+MathML 2.0
    DTD (details to be added).

    (<b>Note:</b> need links to Cygwin / Red Hat / other Linux distro? packages).

<p> To transform a Docbook document with the XSL Stylesheets,
    a processor like <a href="http://wiki.docbook.org/topic/xsltproc">
    xsltproc</a> or Saxon is required. Again, xsltproc
    is prepackaged.

    (<b>Note:</b> again, need links to Cygwin / Red Hat / other Linux
    distro? packages).

<h1>Examples</h1>

<p> A simple example package containing a Docbook document (sample man
    page) and Makefile to transform it are <b>here (link TBD)</b>.

<p> Last modified August 13, 2006 by Jon Leech
</body>
</html>