1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
|
<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>
|
