Re: PEAR documentation and PhpDocumentor

On Wednesday, September 10, 2003 9:19, Lukas Smith wrote: >> From: Greg Beaver [mailto:greg@chiaraquartet.net] >> Sent: Wednesday, September 10, 2003 6:12 AM >> I'm very confused right now - is there a way that I can more clearly >> state that you can generate the exact DocBook needed for the >> pear.php.net manual using phpDocumentor? >> >> I keep running into more and more features of phpDocumentor that I've >> advertised repeatedly which nobody seems to have any idea exists :). >> >> This is frustrating, because that is in essence a documentation > problem >> on my part. So, if any of you have any suggestions, I'd like to get >> that fixed right away. > Forgive Tomas. He was away for some time. > Anyways the bulk of the people certainly know this feature of > phpDocumentor. No. I did know that it could generate API Docs in many formats. But that's not enought for decent documentation. If you read the phpdocumentor manual: "How to write phpDocumentor-style tutorials/extended documentation Tutorials may be written as any legal DocBook top-level tag (<book>, <chapter>, <article>, <refentry>), but it is highly recommended for any project that may become a part of PEAR to write with the <refentry> tag as the top-level, as this will automatically translate into peardoc2-ready tutorials." So I assume it is not a tool for creating tutorials or introduction sections. I don't know if you ever installed the docbook infrastructure, it's quiet long and highweigth, under Windows even more, or the long time it takes for building an human readeable output. IMHO DocBook is a tool for editors not for writers. Maybe we could invent some system for writing introductions or tutorials, plus phpdocumentor for the API, would solve the problem (and write that How To Write Doc - Idiots Guide). If those tool are able to output HTML for the writer to check that all is good, and DocBook for sending to XXXX (where people should send its contributions for the manual?). What I would love to see is something like: // set the doc dir (already supported) $ pear -c doc_dir /home/www/peardocs -s // download and install the manual in html $ pear install pear-manual // install XML_Parser plus its documentation $ pear install --gen-doc XML_Parser Then going with my browser to /home/www/peardocs I'd get the pear manual nicely linked and every time I install a new package its doc gets added to the manual. The tutorials/introductions and the API Doc. Of course each package documentation should be avaible from the package home (other big miss right now). I see phpdocumentor here as the angle piece of this idea. -- Tomas V.V.Cox mailto:cox@idecnet.com