Re: Online doc generator

<mike@php.net> wrote : > Bertrand Mansion wrote: > >> That's for sure, it looks like people using docbook think they are clever >> guys. Actually, docbook is not only XML as you tend to think it is. It is >> also difficult to install because not very compatible, it takes a lot of >> disk space, it doesn't install in standard places and the version used by >> PEARDOC is custom and incomplete, so it is difficult to find. I spent 2 days >> trying to get this to work, I won't waste more time on it. > > Well Bertrand, that sounds like a lame excuse to me. AFAIR installing > [open]jade, sgml-tools and docbook-dsssl on debian took me about 30 > seconds - not that I'd have done anything more special than apt-get install. Cool, if docbook works fine on Debian, well, I just have to buy a new computer and throw my Powerbook away... Never ! :) >> Furthermore, if you don't have the super cool converters used by peardoc and >> openjade or whatever, you will have to wait up to one week to see the >> results of the changes you have made to the doc in CVS, and maybe realized >> you made a mistake. Correct the typo, then wait another week before it is >> published. You have to be kidding. > > There are quite some places where you can view peardoc builds on the > fly or generated regularily, despite the fact that you can make > html > yourself when you've finished the docs, so I guess you are kidding :) I don't know about these unofficial "places" you are talking about. If we have to rely on unofficial sites to do the job we could do ourselves, it just shows our inefficiency. And as I said before, I don't have access to 'make html', and I am not ready to install 100Mb of software and mess my env just to do that. And looking at the doc, I guess I am not the only one. >> The fact that almost no documentation is being written at the moment is just >> an evidence so stop lying to yourself and open your eyes. > > It's just a fact for us being lazy developers´, IMHO :) IMO, we wouldn't be so lazy if we had to correct tools to write the doc. Once you have written the code, you want people to use it, then you write documentation. I even know people who start to write the doc before the code is ready ! If you know that writing the doc is going to take you forever, you bypass this step. This reminds me that credits for the documentation on the first page go to : Daniel Convissor David Costa Thomas V.V. Cox Martin Jansen Alan Knowles Alexander Merz Jon Parise Stephan Schmidt Mika Tuupola Michael Wallner Still I wrote Config docs and Alexey and I both wrote QuickForm docs. Plus the different QF renderer developers wrote docs for their renderers. So it seems this list of authors is not dynamic. The credits for the documentation might be better in the package documentation directly. This would probably help writers find a vocation. For the moment, I think Alexey Borzov, Thomas Schultz, Jason Rust and Bertrand Mansion should be added to this list of authors. We are not writing the 10 commandments. Unlike Moses, we need versioning and ease of use. I am going to stop there but I will come back on the subject in July or August if things haven't changed :) Bertrand Mansion Mamasam