All, I am what I guess you'd call a "newbie" - Elizabeth got me on this list during ZendCon and though I've been following it I still have no idea how the doc editing process works. I'm exactly who you want this kind of tool for - a new contributor who is eager to contribute but unsure about how to do so.
I've always been a fan of finding easy ways to do hard things. And I think that this kind of system would be great for contributors, new and old alike. My .02. Brandon On Wed, Oct 1, 2008 at 3:06 PM, Hannes Magnusson <[EMAIL PROTECTED] > wrote: > 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 >
