(back to TechNotes)
DocBook is a structured document format that allows you to write a document in SGML (or XML) and then convert it to many different formats. There are two different DTD's for DocBook: one for SGML and one for XML.
I won't talk much about SGML in this document. It's probably more powerful than XML (since XML is a subset of SGML) but I think that XML has more industry support and therefore more interesting possibilities.
home:
http://www.oasis-open.org/docbook/
HOWTO:
http://www.ibiblio.org/godoy/sgml/docbook/howto/
reference:
http://docbook.sourceforge.net/release/xsl/current/doc/
download:
http://sourceforge.net/projects/docbook
Docbook per se consists of a "Document Type Definition" or DTD which defines the strcuture of a valid docbook document. There are SGML and XML versions.
http://www.sagehill.net/docbookxsl/index.html - looks like a good guide to processing docbook using various tools. It's in html form here, but can be purchased in PDF or as a paperback book.
XML
Quick Start Guide:
http://jimweller.net/jim/dbxmlqs/
Debian HOWTO:
http://people.debian.org/~bortz//SGML-HOWTO/potato/howto.html
There are two different DTD's which you might find relevant: the full version and the simplified version. The full version implements the complete set of docbook elements and the simplified version implements a small subset (basically enough to allow you to write articles but not books).
You can serve simplified docbook files directly to modern browsers! Make sure that the content-type is text/xml (set in apache config file
mime.types
). Put the DTD and
sdocbook.css
files somewhere that the browser can find them and you should be off to the races.
I use xalan/xerces to transform docbk into html using the "standard" docbook XSL sheets for the transformation. The only issue is that xalan seems to produce rather terse error messages so it's a good idea to keep
jade
or
openjade
around if something goes wrong because they tell you what's wrong with your document in much more detail.
Images are complicated. Basically you need to use
png
format for web publishing and
eps
format for paper.
From |
To |
Stylesheet |
Tool Chain |
Docbook |
HTML |
docbook.dsl |
jade, openjade |
Docbook |
RTF |
docbook.dsl |
jade, openjade |
Docbk |
Browser |
docbook.css |
none, just serve it to the browser |
Docbk |
HTML |
docbook.dsl |
jade, openjade |
Docbk |
HTML |
docbook.xsl |
xalan |
Docbk |
PDF |
??? |
xalan, fo? |
Docbk |
RTF |
??? |
??? |
xml->pdf
Using jade : jade -> jadetex -> dvips ->ps2pdf. Export dia diagrams to
.eps
, include them in the docbk using
imageobject
and they'll end up the same size on the page that they are in dia.
Using Fop: Fop has a bug where it can't handle filenames in the format
url(filename)
properly but it looks as if the docbk xsl fo stylesheets have a workaround. In
fo/param.xml
change the
fop.extensions
param to 1, and files will be put in the
.fo
output without the url() wrapped around the filename.
param.xml
is also the place to set things like fonts and margins.
still looking for a way to pass .svg files from docbk xml docs though to pdf.
Looks as if dia 0.88.1's
.svg
export is still badly broken:
- svg's which should be as wide as a single page end up 67cm wide. (I logged this as a bug at gnome bugzilla, workaround is to remove width and height attributes from svg element)
- The text element has attributes that crash batik.
- Most shapes have a
fill: 0xffffff
element which makes them solid black.
--
TobyCabot - 28 Jun 2001