6 FAQ

Q:

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

A:

Use the --sgml option to db2x_xsltproc.

(Formerly, we described a quite intricate hack here to convert to SGML to XML while preserving the ISO entities. That hack is actually what --sgml does.)

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 get some iconv error when converting documents.

A:

It's because there is some Unicode character in your document that docbook2X fails to convert to ASCII or a markup escape (in roff or Texinfo). The error message is intentional because it alerts you to a possible loss of information in your document, although admittedly it could be less cryptic, but I unfortunately can't control what iconv says.

You can look at the partial man or Texinfo output — the offending Unicode character should be near the point that the output is interrupted. Since you probably wanted that Unicode character to be there, the way you want to fix this error is to add a translation for that Unicode character to the utf8trans character map. Then use the --utf8trans-map option to the Perl docbook2X tools to use your custom character map.

Alternatively, if you want to close your eyes to the utterly broken Unicode handling in groff and Texinfo, just use the --encoding=utf-8 option. Note that the UTF-8 output is unlikely to display correctly everywhere.

Q:

Texinfo output looks ugly.

A:

You have to keep in mind that Info is extremely limited in its formatting. Try setting the various parameters to the stylesheet (see xslt/texi/param.xsl).

Also, if you look at native Info pages, you will see there is a certain structure, that your DocBook document may not adhere to. There is really no fix for this. It is possible, though, to give rendering hints to the Texinfo stylesheet in your DocBook source, like this this manual does. Unfortunately these are not yet documented in a prominent place.

Q:

How do I use SAXON (or Xalan-Java) with docbook2X?

A:

Bob Stayton's DocBook XSL: The Complete Guide has a nice section on setting up the XSLT processors. It talks about Norman Walsh's DocBook XSL stylesheets, but for docbook2X you only need to change the stylesheet argument (any file with the extension .xsl).

If you use the Perl wrapper scripts provided with docbook2X, you only need to “install” the XSLT processors (i.e. for Java, copying the *.jar files to /usr/local/share/java), and you don't need to do anything else.

Q:

XML catalogs don't work with Xalan-Java. (Or: Stop connecting to the Internet when running docbook2X!)

A:

I have no idea why — XML catalogs with Xalan-Java don't work for me either, no matter how hard I try. Just go use SAXON or libxslt instead (which do work for me at least).

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. See doc/ss-texinfo.xsl of docbook2X's own documentation for a non-trivial example.

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

If you don't want to muck with XSLT, you can still tell me what sort of features you want. Maybe other users want them too.

Q:

Does docbook2X support other XML document types or output formats?

A:

No. But if you want to create code for a new XML document type or output format, the existing infrastructure of docbook2X may be able to help you.

For example, if you want to convert a document in the W3C spec DTD to Texinfo, you can write a XSLT stylesheet that outputs a document conformant to the Texi-XML, and run that through db2x_texixml to get your Texinfo pages. Writing the said XSLT stylesheet should not be any more difficult than if you were to write a stylesheet for HTML output, in fact probably even easier.

If you want, on the other hand, to get troff output but using a different macro set, you will have to rewrite both the stylesheets and the post-processor (performing the function of db2x_manxml but with a different macro set). In this case some of the code in db2x_manxml may be reused, and you can certainly reuse utf8trans and the provided roff character maps.