Re: I'm trying to set up docbook-tools...

["David C. Mason" <dcm@redhat.com>]

"Eric S. Raymond" <esr@thyrsus.com> writes:


> I'd like to see documentation that spends less time genuflecting
> before the wonderfulness of semantic markup and stylesheets, and more
> time telling me how I can install and configure working tools and make
> HTML and Postscript from actual documents.

Hmmm I just don't see either of the online documents (Mark's or Deb's)
"genuflecting before the wonderfulness of semantic markup.." I do see
them telling you how to use the tools to "produce actual, viewable
HTML or Postscript from an actual document".

You are correct that there is not very good documentation for the
installation and that is partly due to the fact that depending on the
flavor of Linux or UNIX you are using, it is different. However, that
will change with the new DB Tools being created which includes a nice
proposal to the LSB to make sure it is the same across the board. Once
it is done I will be happy to write an installation guide for it.

You are catching DocBook at a time when it is finally being recognized
and used throughout many projects in Linux. The tools are not 100%
satisfactory but they are being worked on as we speak. When tools are
in flux, documentation is either non-existent or also in flux. That is
the nature of the beast. We release early and release often, usually
at the expense of good documentation and translation.

If you want really good docs *now* perhaps try a commercial Windows
product that uses DocBook. Otherwise wait, ask questions here or in
other forums, or pitch in with the effort. The new tools will be used
in a very different way, but with more functionality... I personally
would like to start documenting those even though they are not
available yet.


> Let's start with replacing that cop-out in the so-called "Practical
> Introduction".  

Please stop referring to people's work with words that are meant only
to insult. I'm sure plenty of people could refer to your essays with
venom, they perhaps choose not to as they know your heart is in the
right place for writing them in the first place.

> What I want to see is a practical guide that is truly a practical guide --
> something like what I wrote for SGML-tools, but covering DocBook.

A technical author tends to want other's writing to be exactly as they
write - its one reason why people have a hard time writing a book
together. There isn't much to be done about that except write it
yourself. I personally think that the Practical Guide is a great start
- it is still in progress mind you, but it tells you the *exact*
things you mentioned (besides the installation which I dealt with
above)... I am staring at it... it tells you how to use the scripts,
how to create a document, etc.

Also keep in mind that DocBook Tools is not the only set of tools
available for using DocBook. There are *many* tools available for the
XML side of it... and I guarantee you you would come in with both guns
blazing if you tried those tools... not one word of
documentation. Why? They released early at the expense of good
documentation/translation.


> -- basically so I could pull Red Hat's nuts out of the fire after
> Bob Young asked me nicely to fix the godawful mess their old
> TeX-centric production process had degenerated into.  

What a gentleman like approach to telling me you worked on it.


Dave
-- 


David Mason
Red Hat Advanced Development Labs
dcm@redhat.com (919)547-0012 x248