Re: Online doc generator

<jcastagnetto@yahoo.com> wrote : >> 3. Easy to learn the markup to lower barriers to entry (docs are less >> sexy than code, let's make it easy to get into them ;-) > > Huh? What is so difficult about XML? I still do not fully understand what is > the problem. Agree that I've been using DocBook for quite some time (when I > used to be more active on the PHP Doc team), but if a crazy scientist like me > can use it ... :-) > > If you need documentation, there is plenty of docs on how to write manual > entries in the PEAR manual and in the PHP manual too > (http://php.net/dochowto). > The differences between PEAR DOC and PHP DOC are small, so I doubt that the a > prospective author will have problems if she uses the PHP or PEAR Manual docs > as a templates to start documenting. > > The crux of the matter is to get people involved doing documentation. I know I > am guilty of not documenting my own packages and only offering their full API > (using PHPDocumentor). But I not always have the free time I'd like (in > particular with my new job). 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. 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. So your statement is all wrong. If you expect documentors to have openjade, the right version of docbook, the O'Reilly docbook book and so on, then you can wait a long time before anything gets written. 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. Docbook is inefficient for PEAR. PEAR has suffered a lot from lack of documentation. Maybe it is time to decide something. >> 4. Easy to translate the document source to multiple output formats, >> targets, and languages. > > See cvs.php.net, count how many translations are there for the PHP manual > (phpdoc* dirs). There is already a set of supporting tools to help with all > the > things you mention above. All translations use DocBook w/o a problem AFAICT. What is good for PHP is not always good for PEAR. PEAR's should be able to evolve more and faster than PHP. It is easier to modify a PHP class than a PHP extension, so it should be easier to modify the doc to reflect this. >> 5. Fast turnaround between edits and displayed results. > > How *fast*. If you have a machine to build the PEAR manual running daily, > yesterday's edits will be there tomorrow. We are not yet at the size of the > PHP > Documentation (1500+ pages IIRC) No, AFAIK it takes a week (what a joke). And it would be silly to think we won't reach 1500 pages one day, especially if PEAR gets more open and people actually write documentation (which, I admit, is not the case today). And if the system is so efficient, why do you have to rebuild the whole doc to reflect just one typo fix. We already have CVS, so why not query it to get the last revision and just merge with the previous one. Actually, Subversion would be better for this job, if only we had a Subversion extension in PHP. All it could take is Subversion + reST + PHPDocumentor + reST->PEAR. Bertrand Mansion Mamasam