"This is not a tutorial on how to use DocBook; there
are plenty of excellent ones available... Rather, it is an outline
of things not to do from the "don't make the mistakes I made
department"; a kind of "do as I say, not as I did" piece. Those who
are thinking about writing documentation, especially for open
source projects, may find it useful to learn the many ways to screw
things up, just as I did. That way they will know what pitfalls to
avoid. But first, a quick description of DocBook.
DocBook, currently maintained by OASIS , is a markup language
described by a document type definition for SGML or XML. A couple
of years ago, if someone had told me that my eyes would have glazed
over and I would have asked for a glass of water. Let's see if we
can make it easier. DocBook uses a set of tags to describe the
structure and content of a document, somewhat reminiscent of HTML.
For example, a paragraph in DocBook might look like this:
...In fact, HTML is really another document type definition.
While you may be concerned with format, or how your web page will
look when displayed in a browser with HTML, with DocBook you are
concerned with describing your document semantically. Format is
only applied when the document is processed and converted into a
form suitable for publication. DocBook also has a great many more
tags (the proper term is named elements) available than HTML."