FAQ

Abstract

Answers to common questions

Q:.

I have a SGML DocBook document. How do I use docbook2X?

A:.

One way is to pass --sgml to db2x_xsltproc.

However, db2x_xsltproc does not actually use a real SGML parser: it does not support some features of SGML. So the safest way still to use SGML is to convert (using sx) the source to XML. Type: sx -xlower -xid sgml-document >xml-document. (On Debian systems replace sx with sgml2xml.)

There is one problem with this kind of conversion; the SGML ISO entities do not work. (sx will complain “SDATA not supported”.) You can work around this, but the procedure is somewhat cumbersome: run sx without the -xid option, and add a DocBook DTD declaration to the beginning of the output file. Such a declaration might look like this:

<?xml version="1.0" ?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
        "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

… rest of document …

(Replace “article” with whatever element name that your document starts with. You may also have to use a different DTD then the above — check with the original SGML source, and use the DocBook XML DTD that corresponds with the DocBook SGML DTD used there.)

Q:.

docbook2X bombs with this document!

A:.

It is probably a bug in docbook2X. (Assuming that the input document is valid DocBook in the first place.) Please file a bug report. In it, please include the document which causes docbook2X to fail, or a pointer to it, or a test case that reproduces the problem.

I don't want to hear about bugs in obsolete tools (i.e. tools that are not in the current release of docbook2X.) I'm sorry, but maintaining all that is a lot of work that I don't have time for.

Q:.

Where have the SGML-based docbook2X tools gone?

A:.

They are in a separate package now, docbook2man-sgmlspl.

Q:.

I don't like how docbook2X renders this markup.

A:.

The XSLT stylesheets are customizable, so assuming you have knowledge of XSLT, you should be able to change the rendering easily.

If your customizations can be generally useful, I would like to hear about it.