FAQ

Abstract

Answers to common questions

1.

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

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.)

2.

docbook2X bombs with this document!

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.

3.

Where have the SGML-based docbook2X tools gone?

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

4.

I don't like how docbook2X renders this markup.

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.