FAQ
Prev |  | Next

## FAQ

### Why generate Docbook?

The primary reason to use Docbook as an output format is to take advantage of the Docbook XSL stylesheets. These are a well-designed, well-documented set of XSL stylesheets that provide a variety of publishing features that would be difficult to recreate from scratch for HTML:

- Automatic Table-of-Contents generation

- Automatic part, chapter, and section numbering.

- Creation of single-page, multi-page, PDF, and WinHelp files from the same source document.

- Navigation headers, footers, and metadata for multi-page HTML documents.

- Link resolution and link target text insertion across multiple pages and numbered targets.

- Figure, example, and table numbering, and tables of these.

- Index and glossary tools.

### Why write in XHTML?

Given that Docbook is so great, why not write in it?

Where there are not legacy concerns, Docbook is probably a better choice for structured or technical documentation.

Where the only legacy concern is the documents themselves, and not the tools and skill sets of documentation contributors, you should consider using an (X)HMTL convertor to perform a one-time conversion of your documentation source into Docbook, and then switching development to the result files. You can use this stylesheet to perform this conversion, or evaluate other tools, many of which are probably appropriate for this purpose.

Often there are other legacy concerns: the availability of cheap (including free) and usable HTML editors and editing modes; and the fact that it's easier to teach people XHTML than Docbook. If either of this is an issue in your organization, you may want to maintain documentation sources in XHTML instead of Docbook

For example, at Laszlo, most developers contribute directly to the documentation. Requiring that developers learn Docbook, or that they wait on the doc team to get content into the docs, would discourage this.

### Why not use an existing convertor?

This isn't the first (X)HTML to Docbook convertor. Why not use one of the exisitng ones?

Each HTML to Docbook convertors that I could find had at least some of the following limitations, some of which stemmed from their intended use as one-time-only convertors for legacy documents:

- Many only operated on a subset of HTML, and relied upon hand editing of the output to clean up mistakes. This made them impossible to use as part of a processing pipeline, where the source is maintained in XHTML.

- There was no way to customize the output, except by (1) hand editing, or (2) writing a post-processing stylesheet, which didn't have access to the information in the XHTML source document.

- Many of them were difficult or impossible to customize and extend. They were closed-source, or written in Java or Perl (which I find to be a difficult languages to use for customizing this kind of thing) and embedded in a larger system.

- They didn't take full advantage of the Docbook tag set and content model to represent document structure. For instance, they didn't generate nested `section` elements to represent `h1` `h2` sequences, or `table` to represent tables with `summary` attributes.

### I got this error. What does it mean?

Q. `Fatal Error! The element type "br" must be terminated by the matching end-tag "</br>".`

  A. Your document is HTML, not XHTML. You need to fix it, or run it through Tidy first.

Q. My output document is empty except for the `<?xml version="1.0" encoding="UTF-8"?>` line.

  A. The document is missing a namespace declaration. See the example for an example.

Q. Some of the headers and document sections are repeated multiple times.

  A. The document has out-of-sequence headers, such as `h1` followed by `h3` (instead of `h2`). This won't work.

Q. `Fatal Error! The prefix "db" for element "db:footnote" is not bound.`

  A. You haven't declared the `db` namespace prefix. See the example for an example.

Prev | Up | Next
Customization | Home | Implementation Notes