Linux Today: Linux News On Internet Time.

MLUG: Doing Damage with DocBook

Oct 06, 2001, 18:16 (4 Talkback[s])
(Other stories by Paul Tatham)

[ Thanks to Alan Truesdale for this link. ]

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

Complete Story

Related Stories: