On Wed, Oct 1, 2008 at 20:03, Stanislav Malyshev <[EMAIL PROTECTED]> wrote: > > On Wed, Oct 1, 2008 at 19:17, Elizabeth M Smith <[EMAIL PROTECTED]> wrote: >> >> tools). Writing in XML is not a natural thing. An online interface >> where people can edit docs would seriously boost people helping out. >> Why do you think there are so many user notes in the PHP manual ;) > > I think a web-based tool that would allow to generate standard docbook pages > (at least most primitive ones) and allow to edit certain sections while > supporting some basic stuff like paragraphs, links, styles (italic, bold) > etc. would be a HUGE help. I can write docbook and have experience with it > and I still find it annoying and hard to remember all the details, I can > only imagine how intimidating it appears to a newbie.
You were extremely unlucky when you wrote the intl docs, sorry for that! :) Now we do however have skeletons for 99% cases, and even a 5minutes tutorial on howto document exceptions[1]. NOTE: Most of the 5minutes are spent explaining how to build the docs. Sure, an online editing tool would be great but I don't think that is a realistic expectation for the time being. I'd rather want PHP5.3 documented before its release then someone spending all their time on weird dirty mixed application that will probably not be ready until PHP6. >> Why do you think there are so many user notes in the PHP manual ;) Speaking of which, we do also need volunteers to review them. If you login to php.net (via bugsweb or http://master.php.net/manage/users.php) you'll see three boxes above(to the right) of all user notes: 1) Edit (rarely used, mostly just to add <?php ?> tags for syntax highlighting if people missed them 2) Reject the note (questions and stuff like that) 3) Delete (wtf notes, bad code/advise, huge code...) _EVERYONE_ with a php.net account can do that and it would be greatly appreciated if people would remove the horror notes when they encounter them. It would even be more appreciated if extension maintainers regularly review the notes attached to their extensions (currently Derick is prettymuch the online who does that). >> However...you will have to wade through the bad docs too. And I have no >> solution for dealing with the "three million tools" issues. I don't understand this argument. All you need for building and view the documentations are 4things: CVS client, PHP, text editor and a browser. All of which you have installed already if you have any interest in PHP at all. To build and view the docs follow these 6steps for the first time, after you follow it once you only have to repeat 3 of the steps 1) cvs -d:pserver:[EMAIL PROTECTED]/repository co phpdoc 1b) cd phpdoc 2) php configure.php 3) pear channel-discover doc.php.net && pear install doc.php.net/phd-beta 4) phd -d .manual.xml -t chunkedhtml 5) firefox html/index.html 6) notepad en/reference/spl/spl/book.xml Now repeat step 2, 4, and 5 after each change you make with you text editor. If you can install PHP on your operating system then you can build the docs and contribute. -Hannes [1] http://doc.php.net/php/dochowto/article.thequicky.exceptions.php
