The Caboteria / Tech Web / DocBookTips (19 Mar 2004, TobyCabot)
(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:

-- TobyCabot - 28 Jun 2001

Edit | Attach | Print version | History: r7 < r6 < r5 < r4 < r3 | Backlinks | Raw View | Raw edit | More topic actions
Copyright © 2008-2017 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding The Caboteria? Send feedback