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

["Edward C. Bailey" <ed@redhat.com>]

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

esr> David C. Mason <dcm@redhat.com>:
>> Then I still don't understand the problems you are having... or at
>> least, I still haven't seen a detail of what you would like to see.

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

I wonder if SGML documentation's current focus on the theoretical versus
the practical is an evolutionary backwater from the days when people using
the technology had to explain why they were "doing things the 'hard' way
with SGML" when most people doing documentation were simply using whatever
tools they happened to have available.  Even if this was the case at one
point in time, I think we all agree that most people "get it" when it comes
to markup languages (if for no other reason than all the hype XML has
brought to our part of the world).  So it's time to move on, and leave the
Cult of the Sacred Tag mentality behind us now... :-)

...
esr> Is it just me?  Am I crazy to think there's something wrong with a
esr> 600-page tome on document production tools that *never once tells you
esr> how to format a document?*

To be honest, and at least in the case of _DocBook: The Definitive Guide_,
I think it's just you.  The book is a reference describing a particular
markup language.  That markup language is processed by a wide variety of
software (both open source and non-) on a wide variety of platforms (again,
both open source and non-).  To have this particular reference guide get
into how the markup language is processed by one particular application on
a subset of the possible platforms would be something similar to HP
including a chapter called "Using Your New Printer to Print Romance Novels"
in every LaserJet owner's manual. :-)

That's not to say that there *shouldn't* be a book that does just what you
describe.  I strongly agree with you that this kind of information should
be in a book somewhere.  I just don't think _DocBook: TDG_ is that book.

esr> The unbelievable part is that it's *all* like that.  It's not just the
esr> individual authors of these particular documents that are high priests
esr> of the Cult of Obscurity -- every piece of documentation I've ever
esr> seen from the DocBook/SGML community is pretty much off in theoretical
esr> cloud-cuckoo land.  I can learn more than I ever wanted to know about
esr> DSSL and FOSI and fifty other acronyms, but I can't find any clue
esr> about what to do when jadetex generates bad Postscript that makes gs
esr> choke.

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

I feel compelled to preface my comments by saying that my goal is neither
to cut anyone down, nor to build myself up.  But I have a bit of background
here that leads me to the following observations:

    o If you were to change a few of the terms in ESR's comments, you'd
      have almost exactly the same kinds of feedback we at Red Hat get from
      users regarding the state of Linux documentation today.  So those of
      us that do documentation for one or more open source software
      projects should keep in mind that we ain't done yet -- not by a long
      shot.  This complaint is true for DocBook documentation, and it's
      true for many (most? all?) open source software projects.

    o Since ESR has worked with me, he knows I'm not the sharpest knife in
      the kitchen (and hopefully feels that I'm at least not the dullest,
      either :-).  Yet he's confounded trying to format DocBook documents,
      while I've been able to convert over 1500 pages of LaTeX-based
      documentation into DocBook, and to create the tools necessary to
      support a production environment to produce DocBook-based content
      here at Red Hat.  What's the difference?  Time.  It was my full-time
      job to make the move to DocBook, while ESR is probably lucky if he
      can devote an hour here and there to the task.  The important point
      here is that we need to get away from the mentality that
      introductory/tutorial texts are for clueless newbies, that hard-core
      reference material is the only truly important documentation.  The
      introductory stuff makes the technology accessible to people that
      would otherwise not have access.  And as I'm sure ESR can vouch,
      being treated like a clueless newbie, on the outside looking in,
      sucks.

esr> Don't get an exaggerrated idea of my creds, either.  I didn't write
esr> SGML-tools, nor was I ever its official maintainer.  I did one really
esr> serious burst of work on it around 0.99-1.0 -- basically so I could
esr> pull Red Hat's nuts out of the fire after Bob Young asked me nicely to
esr> fix the godawful mess their old TeX-centric production process had
esr> degenerated into.

Point of clarification -- ESR helped us replace a contractor (with a
largely manual and TeX-centric production process) that seemed to be unable
to deliver the goods when promised.  That said, the end result still was
the extraction of said gonads from the conflagration -- and in a most
elegant fashion... :-)

                                Ed
-- 
Ed Bailey        Red Hat, Inc.          http://www.redhat.com/