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

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

> > I'm trying to set up docbook-tools, and finding it a hideously
> > frustrating experience.  Why does all the SGML software and
> > documentation in the world read as though it was carefully designed 
> > to prevent any actual document production from getting done?

This is one of those cases where certain documentation projects have
taken up the call more so than the tools side. For example, both the
GNOME and KDE doc groups have manuals to help people get involved with
writing documentation for their projects. Both tell the writer where
to get everything they need for Docbook and how to use it - but both
also describe it in terms that are particular to their style of
writing.

I like this approach as it narrows the focus to projects and those who
wish to write for those projects. Outside of that the best resources I
have seen are Mark's tutorial and Deb Richardson's HOWTO at OSWG. The
main problem with it is that describing SGML is not as trivial as you
might think. Describing DocBook is easier, but it still comes as very
foreign to those who come from either the word processor world, or the
format driven mark-up world. The best way to learn is by trying, not
by reading IMHO. Can the documentation be better? Sure it can, and we
shall try.

Still, I find it somewhat humorous at the trouble many hackers (who
would never dream of documenting their code) have when they can read
the source :-)


Cheers,

Dave

-- 

          David Mason
        Red Hat AD Labs

        dcm@redhat.com
  http://people.redhat.com/dcm