[H-GEN] DocBook Howto software

[Greg Black]

On 2005-11-27, Harry Phillips wrote:

> Does anyone at HUMBUG write any Howto's?
>
> I want to write one using the DocBook format but I can't seem to find a
> decent package that is simple to use.

Hardly surprising, since nothing that really works with DocBook
is simple to use.  In fact, unless it is your misfortune to
already have a significant investment in DocBook, the smart
approach would be to avoid it completely.

For more on that, see the DocBook.org Wiki at

    http://wiki.docbook.org/

In particular, see the sections

    http://wiki.docbook.org/topic/WhatIsWrongWithDocBook
    http://wiki.docbook.org/topic/DocBookFuture

And, from the above, see the comment attributed to Normal Walsh
(who is responsible for much of the misery that is DocBook):

   "There comes a point in the life cycle of any system when
    adding one more patch is the wrong solution to every
    problem. Eventually, it's time to rethink, refactor, and
    rewrite. For DocBook, I think that time has come."

> OpenOffice.org can save in DocBook
> format but it does not seem to do it that well.

OpenOffice doesn't do much well, so that's to be expected.  In
fact, as I recently showed to my own satisfaction, DocBook is
one of the things OO does worst.

> What do you use to create Howto's?

TeX, still the only capable documentation software around.

I keep saying that I'll write something new that will do well
what DocBook does so badly, but my need has not yet been great
enough to push this project near the top of the pile.

Cheers, Greg