From mboxrd@z Thu Jan 1 00:00:00 1970 From: "David C. Mason" To: esr@thyrsus.com Cc: docbook-tools-discuss@sourceware.cygnus.com Subject: Re: I'm trying to set up docbook-tools... Date: Thu, 06 Jul 2000 15:23:00 -0000 Message-ID: References: <200007041511.LAA15779@snark.thyrsus.com> <00070410352500.07357@ehome.inhouse> <873dlnjklb.fsf@nwalsh.com> <20000706131959.A25726@thyrsus.com> <20000706150802.A26225@thyrsus.com> <20000706180129.C26696@thyrsus.com> X-SW-Source: 2000-q3/msg00034.html Message-ID: <20000706152300.lRAZeskERU_zRYTB1HJ2BIbjqFt_szTX-yTRHc2aaXs@z> "Eric S. Raymond" 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