Tony, Ok, fair 'nough. First off, I market no such products. Almost every DocBook tool is OpenSource (OpenJade for example).
The reason why the docs are still not well organized is because I took what was already in the readme file, and ported the first few sections over to the DocBook format. Ok, so why is it the way, well, you'd be hard pressed to argue with almost the entire OpenSource community, of which the format is used extensively. The entire Linux Documentation Project is based on DocBook. As for maintainability (which I believe is one of the core requirements) is that the documentation can be broken up into mutilple XML files. In fact, a theoreticaly infinite number (but one per "chapter" works well). If you are familiar w/ XML/XSL, each "chapter" file is assigned a DTD entity (e.g. &ch01;), and then it's included into an agregate file, which is what is feed into the parser. Look, we need two things here: 1. Well written and 2. Maintainable docs. Lemme just say that I won't loose sleep if Davide decides to go elsewhere. It's just that I work with XML/XSL everyday (our presentation tier is based on it), so I know what works, nothing more, nothing less. Oh, and as for my name, I just followed the structure layed out in the DTD, and where it called for editor, I put the appropriate tags, and since I haven't ventured into designing my own stylesheet yet, that's just how it's done. A good example of a multi-file DocBook project is at http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/docbook/defguide/en/. This is the O'reilly book on DocBook (Ok, last example, I promise). -dave --- [EMAIL PROTECTED] wrote: > As it turns out, I couldn't care less what tool you > use to make the doc. If > it is poorly organized, and contains the same > information - then it's not > going to be a good tool for someone trying to > understand xmail server. > > I thought perhaps the installation guide should be > put together to please > the users, and not the programmers. Davide (and > others) already said they > don't want to learn a new publishing program to > create and maintain this > doc. > > David Bitton, I take it you market the docbook tool? > Why not tell us why > you feel that it's the way to go instead of > republishing the same examples > over and over again? Those examples only > demonstrated that the resulting > document would be unpleasant to look at, and as > poorly organized as the > exisitng document. I must admit, I thought it was a > real nice touch the way > you added "Edited By David Bitton" to the example > doc - and in such nice, > big type too! > > So - why docbook? No more samples - just some > answers. Tell us why thats > the "only way" to go. ok? > > ----- Original Message ----- > From: "David Bitton" <[EMAIL PROTECTED]> > To: "Davide Libenzi" <[EMAIL PROTECTED]> > Cc: <[EMAIL PROTECTED]> > Sent: Wednesday, October 03, 2001 7:32 PM > Subject: Re: DOC Project format > > > > What is being missed here is the issue is not > output > > format, but input content management. Ok, so you > want > > RTF, ok... > > > > http://www.codenoevil.com/Xmail/xmail.rtf > > > > all that took was changing two items in the single > > command line command it took to create that. > > > > Ladies and Gentlemen, DocBook is the way for > > management, we can see that. As for output, the > > format is the limit. Oh yeah, I did up a HTML > frames > > version too: > > > > http://www.codenoevil.com/Xmail/frames.htm > > > > but do pardon the broken image links for now. I > > didn't feel like editing the .js file to add > images/ > > to each image filename ('course when we roll this > out, > > that'll be a no-brainer). > > > > Davide, let's get the CVS setup and let me plop > some > > file in and let's get going. > > > > -dave > > > > > > --- Davide Libenzi <[EMAIL PROTECTED]> > wrote: > > > On Wed, 3 Oct 2001 [EMAIL PROTECTED] wrote: > > > > > > > The present documentation is a terrible > struggle > > > to use for these reasons, > > > > as well as grammer, spelling, and other > general > > > english language concerns. > > > > > > You should have seen it two years ago :) > > > > > > Everyone agree on RTF ? > > > > > > > > > > > > > > > - Davide > > > > > > > > > > > > ===== > > ---- > > David B. Bitton > > [EMAIL PROTECTED] > > > > We will overcome. > > http://www.libertyunites.org > > > > __________________________________________________ > > Do You Yahoo!? > > NEW from Yahoo! GeoCities - quick and easy web > site hosting, just > $8.95/month. > > http://geocities.yahoo.com/ps/info1 > > > ===== ---- David B. Bitton [EMAIL PROTECTED] We will overcome. http://www.libertyunites.org __________________________________________________ Do You Yahoo!? NEW from Yahoo! GeoCities - quick and easy web site hosting, just $8.95/month. http://geocities.yahoo.com/ps/info1
